Installation and usage of the platform

Constructing smart contracts with JS Contract SDK¶

This section describes JS Сontract SDK Toolkit – a toolkit for development, testing and deploying smart contracts in Waves Enterprise public blockchain networks. Use the toolkit to fast take off with the Waves Enterprise ecosystem using programming languages such as JavaScript or TypeScript, since smart contracts are deployed in a Docker container.

Smart contracts are often deployed into different environments and networks. For example, you can scaffold local environment based on a sandbox node and deploy contracts to this network for test use-cases.

Deploy your smart contract to different environments using WE Contract Command line interface (CLI).

Requirements¶

Before you start, make sure that the following software is installed:

Docker
Node.js (LTS)

Quickstart¶

Run the following command in command line to scaffold your new project:

Using npm npx

npx create-we-contract YourContractName -t path-to-contract -n package-name

or

npm create we-contract YourContractName -t path-to-contract -n package-name

or using yarn

yarn create we-contract YourContractName -t path-to-contract -n package-name

This creates your first smart-contract that is ready for development and deployment to the Waves Enterprise blockchain. Now you can run the following command to initialize dependencies and start to develop your project:

npm i // or yarn

Configuration¶

The configuration file is used to set up the image name and the contract name to be displayed in the explorer. You can also set the image tag (the name property) which will be used to send the contract to the registry in the configuration file.

Add the contract.config.js file to the root directory of your project to initialize your contract configuration.

If you scaffolded the project with the create-we-contract command as described above in the Quickstart section, the configuration is set by default.

Default configuration¶

An example of default configuration is given below:

module.exports = {
  image: "my-contract",
  name: 'My Contract Name',
  version: '1.0.1',
  networks: {
  /// ...
  }
}

Network configuration¶

In the networks section, provide specific configuration for your network:

module.exports = {
  networks: {
    "sandbox": {
        seed: "#your secret seed phrase" // or get it from env process.env.MY_SECRET_SEED

        // also you can provide
        registry: 'localhost:5000',
        nodeAddress: 'http://localhost:6862',
        params: {
          init: () => ({
            paramName: 'paramValue'
          })
        }
    }
  }
}

seed – if you are going to deploy a contract to the sandbox network, provide the contract initiator seed phrase;
registry – if you used a specific Docker registry, provide the registry name;
nodeAddress – provide specific nodeAddress to deploy to.
params.init – to specify initialization parameters, set a function.

Caution

DO NOT publish your secret phrases in public repositories.

Deploy contract¶

Smart contracts are executed once they are deployed in the blockchain. To deploy a contract run the deploy command in WE Contract CLI:

we-toolkit deploy -n testnet

where testnet is the name of the network specified in the configuration file. For example, to deploy a contract to the sandbox network run the following command:

we-toolkit deploy -n sandbox

Contract SDK Toolkit¶

Core concepts¶

The basics of making a contract class is to specify class annotations per method. The most important annotations are:

Contract – register a class as a contract;
Action – register action handler of the contract;
State – decorate the class property to access the contract state;
Param – decorator that maps transaction parameters to the contract class action parameters.

The SDK provides contract templates to which you can add your business logic:

@Contract
export class ExampleContract {
    @State state: ContractState;

    @Action
    greeting(@Param('name') name: string) {
        this.state.set('Greeting', `Hello, ${name}`);
    }
}

Methods¶

Methods to manage smart contract state¶

ContractState class exposes useful methods to write to contract state. You can find the list of data types currently available in contract state in the node documentation. Contract SDK supports all the data types currently available in the contract state.

Write¶

The easiest way to write the state is to use set method. This method automatically casts data type.

this.state.set('key', 'value')

For explicit type casting use the methods in the examples below:

// for binary
this.state.setBinary('binary', Buffer.from('example', 'base64'));

// for boolean
this.state.setBool('boolean', true);

// for integer
this.state.setInt('integer', 102);

// for string
this.state.setString('string', 'example');

Read¶

Reading the state is currently asynchronous, and reading behavior depends on the contract configuration.

@Contract
export class ExampleContract {
    @State state: ContractState;

    @Action
    async exampleAction(@Param('name') name: string) {
        const stateValue: string = await this.state.get('value', 'default-value');
    }
}

Caution

state.get `` method has no information about the internal state type in runtime. To explicitly cast types use the following methods: ``getBinary, getString, getBoo`l, getNum.

Write Actions¶

The key decorators are Action and Param.

Init Actions¶

To describe create contract action set the onInit action decorator parameter to true.

@Contract
export class ExampleContract {
    @State state: ContractState;

    @Action({onInit: true})
    exampleAction(@Param('name') name: string) {

        this.state.set('state-initial-value', 'initialized')
    }
}

By default action is used as the name of contract method. To set a different action name, assign it to the name parameter of the decorator.

@Contract
export class ExampleContract {
    @State state: ContractState;

    @Action({name: 'specificActionName'})
    exampleAction() {
        // Your code
    }
}

Сontract version update¶

Use the update method to update contract version. The method updates the last deployed contract version. If no contract is deployed, the method performs no updates.

we-cli update -n, --network <char>