npm package: @pendulum-chain/api-solang
Description: Interface to interact with smart contracts compiled via Solang
Author: Pendulum
Latest version: 0.7.4

# Polkadot API for Smart Contracts compiled via Solang

This library allows to deploy and call into smart contracts that have been compiled from Solidity to wasm via Solang.

It has three main functions:

- deploy (instantiate) a smart contract
- execute a message call by submitting an extrinsic
- make a message call via RPC (dry-run)

These functions are meant to be used very flexibly and they have the following special features:

1. The first two functions allow to either specify a keypair or a general signer in order to sign the extrinsics. The keypair is generally useful for command line tools whereas the signer is more useful in a browser context, where it can give access to a wallets or browser extensions.

2. In certain applications it can be necessary to extend the extrinsics created in the first two functions, e.g., to wrap them into a sudo call. For that reason these functions allow to specify an optional argument `modifyExtrinsic` that allows the caller to arbitrarily change or extend the created extrinsic.

3. Contracts usually emit events and these events can be emitted by contracts (recursively) called by the original contract. In order to properly decode the binary data contained in the event, one needs to lookup the abi of the respective contract emitting the event. For that reason the first two functions take an optional argument `lookupAbi` that allows the caller to provide the abi for any deployed contract (identified through the contract address).

4. All functions can correctly decode the return value of message calls, i.e., whether a message call reverted (including the revert message) or whether it panicked and why it panicked.

The differences between the message call by extrinsic and the message call by RPC methods are:

- the dry-run does not cost any fees
- the dry-run does not require signatures or secret keys
- the dry-run is executed immediately, and does not need to wait for a block
- the dry-run returns an output value
- changes to the chain or contract storage during the dry-run will be discarded after the call

## Deploy a smart contract

The function `deployContract` has the following arguments:

- `api`: the polkadot-js `ApiPromise` object

  This is the `ApiPromise` object that polkadot-js creates when connecting to an RPC node of a chain.

- `abi`: The abi (metadata) of the smart contract

  This needs to be an object of type `Abi`. It can be constructed from the metadata JSON file (that is generated by Solang) as follows:

  ```
  const metadata = JSON.parse(metadataString);
  new Abi(metadata, api.registry.getChainProperties());
  ```

- `signer`: Specifies the signer of the extrinsic submitted to the chain.

  This can either be a keypair or any generic signer. If it is a keypair, then it needs to have the format

  ```
  {
    type: "keypair";
    keypair: KeyringPair;
  }
  ```

  If it is a generic signer, then it needs to have the format

  ```
  {
    type: "signer";
    address: string; // the address of the signer
    signer: Signer;
  }
  ```

- `constructorArguments`: the array with the arguments to the constructor
- `constructorName`: an optional argument to specify the constructor

  This is `new` by default. Contracts that are compiled via Solidity usually only have the `new` constructor.

- `limits`: the resource limits

  These limits specify the resources that are allowed to be used for the execution. They need to be specified as the type

  ```
  {
    gas: {
      refTime: string | number;
      proofSize: string | number;
    };
    storageDeposit?: string | number;
  }
  ```

  The `gas.refTime` and `gas.proofSize` entries specify limits of the gas usage. The optional argument `storageDeposit` specifies a limit for the storage deposit.

- `modifyExtrinsic`: allows to extend the generated extrinsic.

  This is an optional function that allows the caller to extend, modify or wrap the extrinsic created by `deployContract` before it is submitted to the chain.

- `lookupAbi`: provide abi for deployed contracts

  This is an optional argument that allows to provide the abi of any deployed contract (specified by the address of the contract). This allows `deployContract` to properly decode events emitted during contract execuction.

The return value of this function is an object that contains the field `type`. This fields indicate the execution status and is either one of the values:

- `"success"`: in this case the deployment was successful and the return object also contains the entries `events` (which is the collection of (decoded) contract events that were emitted during contract execution), the `deploymentAddress` and the `transactionFee` that the signer had to pay
- `"error"`: in this case there was a general error when submitting the extrinsic and the return object contains the entry `error` (a string with an error description)
- `"reverted"`: in this case the contract reverted and the return object contains the revert message in the entry `description`
- `"panic"`: in this case the contract panicked and the return object contains the entries `errorCode` (a numerical error code) and `explanation` (an explanation of the error code)

## Execute a Message Call

The function `executeMessage` has the following arguments:

- `api`: the polkadot-js `ApiPromise` object

  This is the `ApiPromise` object that polkadot-js creates when connecting to an RPC node of a chain.

- `abi`: The abi (metadata) of the smart contract

  This needs to be an object of type `Abi`. It can be constructed from the metadata JSON file (that is generated by Solang) as follows:

  ```
  const metadata = JSON.parse(metadataString);
  new Abi(metadata, api.registry.getChainProperties());
  ```

- `contractDeploymentAddress`: the address of the contract

  This needs to be the address of a deployed contracts that has the abi specified by `abi`

- `callerAddress`: the address of the caller of the contract

- `messageName`: the name of the message

- `messageArguments`: the array with the arguments to the message

- `limits`: the resource limits

  These limits specify the resources that are allowed to be used for the execution. They need to be specified as the type

  ```
  {
    gas: {
      refTime: string | number;
      proofSize: string | number;
    };
    storageDeposit?: string | number;
  }
  ```

  The `gas.refTime` and `gas.proofSize` entries specify limits of the gas usage. The optional argument `storageDeposit` specifies a limit for the storage deposit.

- `getSigner`: Specifies the signer of the extrinsic submitted to the chain.

  This callback will be invoked when an extrinsic is submitted to the chain. The address associated with the signer should be the same as `callerAddress`.
  This can either be a keypair or any generic signer. If it is a keypair, then it needs to have the format

  ```
  {
    type: "keypair";
    keypair: KeyringPair;
  }
  ```

  If it is a generic signer, then it needs to have the format

  ```
  {
    type: "signer";
    address: string; // the address of the signer
    signer: Signer;
  }
  ```

- `modifyExtrinsic`: allows to extend the generated extrinsic.

  This is an optional function that allows the caller to extend, modify or wrap the extrinsic created by `executeMessage` before it is submitted to the chain.

- `lookupAbi`: provide abi for deployed contracts

  This is an optional argument that allows to provide the abi of any deployed contract (specified by the address of the contract). This allows `executeMessage` to properly decode events emitted during contract execuction.

The return value of this function is an object that contains two entries `execution` and `result`. The `execution` entry contains the field `type`, which can be either one of

- `onlyQuery`: in this case only the rpc method has been executed because an error occurred before submitting an extrinsic
- `extrinsic`: an extrinsic has been submitted to execute the message call – in this case the `execution` object also contains the entries `contractEvents` (which is the collection of (decoded) contract events that were emitted during contract execution) and the `transactionFee` that the signer had to pay

The `result` object contains the entry `gasMetrics` with the sub entries `gasRequired` and `gasConsumed` (both are a `Weight`). Furthermore, it has the field `type` which is either one of the following values:

- `"success"`: in this case the deployment was message call was successful and it contains a return value in the entry `value`
- `"error"`: in this case there was a general error when submitting the extrinsic and the return object contains the entry `error` (a string with an error description)
- `"reverted"`: in this case the contract reverted and the return object contains the revert message in the entry `description`
- `"panic"`: in this case the contract panicked and the return object contains the entries `errorCode` (a numerical error code) and `explanation` (an explanation of the error code)

## Dry Run a Message Call (Read Message)

The function `readMessage` has the following arguments:

- `api`: the polkadot-js `ApiPromise` object

  This is the `ApiPromise` object that polkadot-js creates when connecting to an RPC node of a chain.

- `abi`: The abi (metadata) of the smart contract

  This needs to be an object of type `Abi`. It can be constructed from the metadata JSON file (that is generated by Solang) as follows:

  ```
  const metadata = JSON.parse(metadataString);
  new Abi(metadata, api.registry.getChainProperties());
  ```

- `contractDeploymentAddress`: the address of the contract

  This needs to be the address of a deployed contracts that has the abi specified by `abi`

- `callerAddress`: the address of the caller of the contract

- `messageName`: the name of the message

- `messageArguments`: the array with the arguments to the message

- `limits`: the resource limits

  These limits specify the resources that are allowed to be used for the execution. They need to be specified as the type

  ```
  {
    gas: {
      refTime: string | number;
      proofSize: string | number;
    };
    storageDeposit?: string | number;
  }
  ```

  The `gas.refTime` and `gas.proofSize` entries specify limits of the gas usage. The optional argument `storageDeposit` specifies a limit for the storage deposit.

The return value of this function contains the entry `gasMetrics` with the sub entries `gasRequired` and `gasConsumed` (both are a `Weight`). Furthermore, it has the field `type` which is either one of the following values:

- `"success"`: in this case the deployment was message call was successful and it contains a return value in the entry `value`
- `"error"`: in this case there was a general error when submitting the extrinsic and the return object contains the entry `error` (a string with an error description)
- `"reverted"`: in this case the contract reverted and the return object contains the revert message in the entry `description`
- `"panic"`: in this case the contract panicked and the return object contains the entries `errorCode` (a numerical error code) and `explanation` (an explanation of the error code)

## Submit an Extrinsic

Additionally this module also exposes a function `signAndSubmitExtrinsic` that allows to submit an arbitrary extrinsic and that processes the chain events in order to determine the execution status of the extrinsic.

It has two arguments:

- `extrinsic`: the extrinsic itself
- `signer`: as for the other two functions this specifies the signer of the extrinsic submitted to the chain.

This function only returns after the extrinsic has been executed on-chain. The return value of this function is an object with the following entries:

- `transactionFee`: the transaction fee that the signer had to pay for the execution
- `events`: the array of all Substrate events generated during execution
- `status`: this is an object whose `type` entry is either `"success"` or `"error"`. In the latter case this object also contains the entry `error`, which is a string of the error message