The sails-js-cli
is a command-line tool designed to generate TypeScript client libraries from Sails IDL files. It automates the process of creating fully functional client libraries based on the interfaces defined in the Sails framework, streamlining development and ensuring consistency between client and on-chain programs.
To install the sails-js-cli
package globally, run the following command:
npm install -g sails-js-cli
Or you can use npx
to run the command without installing the package:
npx sails-js-cli command ...args
To generate a TypeScript client library run the following command:
sails-js generate path/to/sails.idl -o path/to/out/dir
In case you want to use the package w/o installing it globally, you can use npx
:
npx sails-js-cli generate path/to/sails.idl -o path/to/out/dir
If you want to generate only lib.ts
file without the whole project structure, you can use the --no-project
flag.
sails-js generate path/to/sails.idl -o path/to/out/dir --no-project
First, connect to the chain using @gear-js/api
.
import { GearApi } from '@gear-js/api';
const api = await GearApi.create();
Import Program
class from the generated file. And create an instance
import { Program } from './lib';
const program = new Program(api);
// provide the id of the program if the program is already uploaded to the chain
const programId = '0x...';
const program = new Program(api, programId);
The Program
class has all the functions available in the IDL file.
There are a few types of methods available in the Program
class.
- Query methods
- Message methods
- Constructor methods
- Event subscription methods
Query methods are used to query the program state.
These methods accept the arguments needed to call the function in the program and return the result. Apart from the arguments, these functions also accept optional parameters: originAddress
is the address of the account that is calling the function (if this parameter isn't provided zero address is used as a default value), value
is a parameter parameter can be used depending on the function to send some amount of tokens to the correct function execution and atBlock
to query program state at a specific block.
const alice = '0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d';
const result = await program.serviceName.queryFnName(arg1, arg2, alice);
console.log(result);
Message methods are used to send messages to the program. These methods accept the arguments needed to send the message and return transaction builder that has a few methods to build and send the transaction.
const transaction = program.serviceName.functionName(arg1, arg2);
// ## Set the account that is sending the message
// The method accepts either the KeyringPair instance
import { Keyring } from '@polkadot/api';
const keyring = new Keyring({ type: 'sr25519' });
const pair = keyring.addFromUri('//Alice');
transaction.withAccount(pair)
// Or the address and signerOptions
// This case is mostly used on the frontend with connected wallet.
import { web3FromSource, web3Accounts } from '@polkadot/extension-dapp';
const allAccounts = await web3Accounts();
const account = allAccounts[0];
const injector = await web3FromSource(account.meta.source);
const signer = web3FromSource();
transaction.withAccount(account.address, { signer: injector.signer });
// ## Set the value of the message
transaction.withValue(BigInt(10 * 1e12)); // 10 VARA
// ## Calculate gas
// Optionally you can provide 2 arguments.
// The first argument `allowOtherPanics` either allows or forbids panics in other programs to be triggered. It's set to `false` by default.
// The second argument `increaseGas` is percentage to increase the gas limit. It's set to `0` by default.
await transtaion.calculateGas();
// The `withGas` method can be used instead of `calculateGas` if you want to set the gas limit manually.
transaction.withGas(100000n);
// ## Send the transaction
// `signAndSend` method returns the if of the sent message, the block hash in which the message is included and `response` function that can be used to get the response from the program.
const { msgId, blockHash, response } = await transaction.signAndSend();
const result = await response();
console.log(result)
Constructor methods are postfixed with CtorFromCode
and CtorFromCodeId
in the Program
class and are used to deploy the program on the chain.
These methods accept either bytes of the wasm or the id of the uploaded code.
They returns the same transaction builder as the message methods.
const code = fs.readFileSync('path/to/program.wasm');
// Or fetch function can be used to fetch the code on the frontend
const transaction = program.newCtorFromCode(code);
// The same methods as in the message methods can be used to build and send the transaction
Event subscription methods are used to subscribe to the specific events emitted by the program.
program.subscribeToSomeEvent((data) => {
console.log(data);
});