Cargo JS

Cargo JS can be used as a module within your app, or can be added directly to the browser using a script tag.

​View the source on GitHub.

Supported wallets

Cargo JS works with any Ethereum wallet. You can also provider a custom provider to authenticate using third party platforms like Fortmatic. If you have issues please file an issue on github or email contact@cargo.build.

Testing

You can find the test version of Cargo at https://rinkeby.cargo.build.

ES6

Cargo JS requires you to install web3@1.2.6 as a peer dependency.

yarn add web3@1.2.6

yarn add @cargo-eth/js

After installing the required npm packages you can import Cargo JS into your project by doing the following:

import { Cargo } from '@cargo-eth/js';

Script Tag

When used in the browser Cargo JS will be added to the window and will be available at window.cargoJs . This version of Cargo JS is bundled with web3@1.2.6.

<script src="https://assets.cargo.build/cargo.5.1.0.js"></script>
​
<script>
  const cargo = new window.cargoJs.Cargo();
</script>

The Cargo Class

new Cargo(options);

Use the Cargo class to create a class instance.

Arguments:

This method takes one argument which is an object with the following keys and values:

​

Returns:

​An instance of the Cargo class.​

Example:

See below

Initializing and Enabling Cargo

After installing Cargo you will need to create a new instance and initialize it. This will get the required information required for the library to interact with the Cargo smart contracts.Here is an example of initialization:

import Cargo from '@cargo-eth/js';
​
// Create a new instance of the Cargo class
const cargo = new Cargo({ network: 'development' });
​
async function enable() {
    // Check if user has a web3 provider available
    if (cargo.hasProvider) {
        // Enable Cargo
        const enabled = await cargo.enable();
        
        if(enabled) {
            // You can now interact directly with the 
            // blockchain using the Cargo API
        }
    }
}
​
enable();
​

After Cargo JS has been initialized you can call the enable function. If the user is using MetaMask they will be prompted to connect to Cargo. The enable function allows for an opt in authentication flow. MetaMask already supports this. Essentially you need to ask the user to enable their wallet to interact with your application. You can do this when the user takes an action rather than showing a pop up as soon as the user lands on your page.

Events

Cargo JS also provides an event interface if that will better suit your needs.

// Event stating that Cargo JS is enabled
cargo.on('enabled', () => {});
​
// Event stating that enabling was rejected. Either an
// error was thrown, or the user rejected
cargo.on('enable-required', () => {});
​
// MetaMask supported event. Emitted when accounts change
// First argument of callback function is an array of accounts.
cargo.on('accounts-changed', (accounts/*: Array<Account>*/) => {});
​
// Fired if cargo.enable is called without a web3 provider 
// available.
cargo.on('provider-required', () => {});
​
​
​

After enabling Cargo an instance of PollTx will be created. You can use the events on that instance to watch for completed transactions when using the API methods that make transactions on the blockchain.

Interacting with the APIs

After Cargo JS has been enabled you can access the API methods. Methods that do not require MetaMask can be called before enabling Cargo JS. You can learn about all the API methods here.

cargo.api.getBeneficiaryBalance(beneficiaryId).then((response) => {
    if(!response.err){
      // Do something.
    }
});