RSK Command Line Interface

This a command line tool to interact with RSK and Ethereum nodes. You can:

• query blocks, transactions, transaction receipts
• send transactions like transfer, contract deploys, contract invocation
• query contract state
• estimate gas for transaction
• query accounts state

A local configuration file rskcli.json is created to be used in the sequence of command invocation.

Install

Using npm:

npm install rskclitools -g

This command install the tool globally, adding them to the execution path. The tool is invoked with the name rskcli.

Configuration File

There is a file in the current directory, rskcli.json that contains information generated by the execution of commands.

Usually it contains:

• Host information: the blockchain node to connect to
• Account information: named accounts, addresses, private key if it is known
• Instance information: named smart contract instances, addresses
• Pending transactions information: transactions without a receipt yet
• Non-default options for gas, gas price, and value

Example:

TBD

Notice that when you create a new account or setup one providing the private key, the private key information is stored in this file. Then, it is recommended NOT TO BE included in any source repository.

Add this line to your .gitignore.

rskcli*.json

The * is needed to avoid the commitment of configuration copies, used by the putconf and getconf commands.

Commands

All the commands starts with rskcli.

Command Options

Many of the following commands (not all of them) accept options:

• '-d', '--dec'
• '-g', '--gas' ''
• '-gp', '--gasPrice' ''
• '-l', '--log'
• '-q', '--quick'
• '-v', '--value' ''

There are described when it is pertinent to mention them.

Query Info

It returns the status of a blockchain node:

rskcli info <host>

Example, using RSK mainnet:

> rskcli info https://public-node.rsk.co:443

host https://public-node.rsk.co:443
block number 3164289
chain id 0x1e
network version 30
client version RskJ/2.2.0/Linux/Java1.8/PAPYRUS-dev
date/time 2021-03-07T13:48:14.425Z

(notice that an explicit port should be specified when using https)

If no host is specified, it uses the host from the last sethost command.

You can use alias names instead of explicit entrypoint:

• ganache, truffle, hardhat are equivalent to http://localhost:8545
• local, regtest are equivalent to http://localhost:4444
• testnet is equivalent to https://public-node.testnet.rsk.co:443
• mainnet is equivalent to https://public-node.rsk.co:443

Set Host

Set the node JSON RPC entrypoint to use in the commands:

rskcli sethost <host>

Examples:

rskcli sethost http://localhost:8545
rskcli sethost http://localhost:4444
rskcli sethost https://public-node.testnet.rsk.co:443
rskcli sethost https://public-node.rsk.co:443

They are the usual connections for ganache/truffle/hardhat nodes, RSK regtest, RSK testnet and RSK mainnet. You also can use an Infura or Ethereum node.

The info is saved into the local rskcli.json file, to be used in the subsequent commands.

This command should be execute BEFORE other commands (except rskcli info that takes the host information from the command line)

You can use alias names instead of explicit entrypoint:

• ganache, truffle, hardhat are equivalent to http://localhost:8545
• local, regtest are equivalent to http://localhost:4444
• testnet is equivalent to https://public-node.testnet.rsk.co:443
• mainnet is equivalent to https://public-node.rsk.co:443

List Host Accounts

Some nodes have a list of activated account, ie ganache and RSK regtest. You can list their addresses with:

rskcli haccounts

Example:

> rskcli haccounts

0x224a143ed6b080493f7c09f51b8c17b058d0427c
0xba6c074888635320dafe913405a52177bbabc39b
0x845caad64d3f438b232417e32e79848e81a3b42f
0xe56cafd3876e995d45912bff38e2a3f3f155768a
0x7592628e13afbe1977afd67c2c389d517d3a0f42
0x72911753d68829063d5cebdffc310c7fcf993cb7
0x101cbd4149d7f2bde5a34b6f125297ff38a7dcf1
0x1ee2b46391b95a92fc141406be2eef4b45e2cfad
0xee552d41682d2a94a4559e5671cb26e3dcca703b
0xb46ac24c04ab99c24bafff440ce069bbb98117b7

Set Account

To set an account with name:

rskcli setaccount <name> <ordinal>
rskcli setaccount <name> <address>
rskcli setaccount <name> <privatekey>

Example, this command set root account using the first host account (number 0):

rskcli setaccount root 0

Then you can use the name of the account instead of his address. You can use it as the sender account (signer) in transfer, deploy, invoke and call commands, because usually the host accounts can sign transactions inside the node.

If you already knows the address of an account and you want to manage it under a name:

rskcli setaccount alice 0x0142d73c968ad62dcd477bdc2f74aa0608195231

You cannot use this account as the sender in an operation because the tool does not know the private key.

If you controls an account knowing its private key:

rskcli setaccount alice 0x...privatekey...

Now, you can use the symbolic name alice to sign transactions, if the account has enough funds.

New Account

Create a new account with symbolic name:

rskcli newaccount <name>

Examples:

rskcli newaccount root
rskcli newaccount alice
rskcli newaccount bob
rskcli newaccount charlie

A valid random private key is generated, and then, their associated public key and address are derived.

Once the account is generated, you can use the name instead of the address in any of this tool commands.

Also, having the private key, the tool commands transfer, deploy and invoke can be used to generate transactions signed locally, without intervention from the running node.

Take into account that that information is saved in the local rskcli.json file, so it is recommended not share this file, ie, not include it into a public repository.

In case the current folder is in a public repository add the following line to .gitignore file:

rskcli*.json

This line avoid the save of rskcli.json file and other ones that can be generated with rskcli putconf command.

Get Account Balance

To retrieve the balance of an account, execute:

rskcli balance <account>

The account could be specified as an hexadecimal address or as an account name.

Also, you can specify a block number:

rskcli balance <account> <blocknumber>

In this case, the balance returned is the balance at that block world status. If the block is not specified, the world state of the current best blockchain is used.

Examples:

rskcli balance 0x01000006
rskcli balance alice
rskcli balance bob 1000000

The first example refers to RSK bridge precompiled contract.

The balance is shown in weis. You can use the option -d, --decimals to express the balance in ether/rbtc:

rskcli balance 0x01000006 -d
rskcli balance alice --decimals

Get Account Transaction Count

It's pretty similar to balance command. To retrieve the number of transactions sent by an account, execute:

rskcli nonce <account>

The account could be specified as an hexadecimal address or as an account name.

Examples:

rskcli nonce 0xbd0a5547f1ae8d0de041c0ccacafc7ba28dc2f87
rskcli nonce alice

Get Account Code

An account could be an smart contract. To retrieve the code associated execute:

rskcli code <account>

The code is an array of bytes and it is expressed as an hexadecimal string.

The account could be specified as an hexadecimal address or as an account name.

Examples:

rskcli code 0x1ac16d9523832f9a5f4b6d7758353ed49f2f842d
rskcli code counter

Set Instance

To set an smart contract instance with name:

rskcli setinstance <name> <address>

Example, this command set token account to point to a given address:

rskcli setinstance token 0x0142d73c968ad62dcd477bdc2f74aa0608195231

Then you can use the name of the instance instead of his address. You can use it as the receiver account in transfer, call and invoke commands.

Transfer

To transfer value from an account to another, execute:

rskcli transfer <sender> <receiever> <value>

Example:

rskcli transfer alice charlie 10000000

The value is expressed in weis. The sender and receiver can be specified by name or by explicit address.

The sender should be an account:

• Exposed in the node you are using (like in ganache or RSK regtest)
• An account with a known private key, ie, created with newaccount command or with setaccount given a private key.

The gas limit used for a transfer is 21000 units, but you can specify the gas limit to use with the option -g, --gas, examples:

rskcli transfer alice pool 20000000 -g 100000
rskcli transfer charlie faucet 60000000000 --gas 80000

Usually the gas used in a transfer transactions is 21000 but if your receiver account is an smart contract, it could have code to be executed on transfer, so you need to pay the code execution providing more gas units.

The gas price is set using the value informed by the network. If you want to set the gas price explicitly, use the -gp, --gasPrice option:

rskcli transfer alice charlie 20000000 -gp 70000000
rskcli transfer charlie bob 60000000000 --gasPrice 100000000

When the transfer transaction is sent to the node, the transaction hash is shown in the console. Then, the command waits for the mining of the transaction, querying for the transaction receipt that describes its execution result. If you want to skip that time, use the -q, --quick flag:

rskcli transfer alice bob 10000000 -q
rskcli transfer charlie bob 100000000000 --quick

The transfer is sent but it is up to you to check its inclusion into the blockchain.

Deploy a Contract

To deploy a compiled contract:

rskcli deploy <sender> <instancename> <contractname> [<path>]
rskcli deploy <sender> <instancename> <contractname> <argtypes> <arguments> [<path>]

Example:

rskcli deploy alice counter Counter
rskcli deploy bob token Token string,string TOK,Token
rskcli deploy bob token Token string,string TOK,Token ../../MyProject

The sender should be an account:

• Exposed in the node you are using (like in ganache or RSK regtest)
• An account with a known private key, ie, created with newaccount command or with setaccount given a private key.

The instance name is the name to use to refer the new instance.

The contract name should correspond to a compiled contract. If no path is specified, the compiled contract information is retrieved from ./build/contracts/<contractname>.json, that is the usual folder where Truffle saves the compiled contract information. In this case, you have a ./contracts local folder, and Truffle configured to compile using truffle compile.

If your compiled contracts are in another folder, you can specify the path. Then, the contract information will be retrieved from <path>/build/contracts/<contractname>.json.

The gas limit used for a deploy is 5_000_000 units, but you can specified the gas limit with the option -g, --gas, examples:

rskcli deploy alice counter Counter -g 100000
rskcli deploy bob token BasicToken string,string TOK,Token --gas 100000

The gas price is set using the value informed by the network. If you want to set the gas price explicitly, use the -gp, --gasPrice option:

rskcli deploy alice counter Counter -gp 100000
rskcli deploy bob token BasicToken string,string TOK,Token --gasPrice 100000

In the second example, the constructor arguments types are specified with string,string (comma separated) and their values are given with TOK,Token (again, separated by commas).

When the deploy transaction is sent to the node, the transaction hash is shown in the console. Then, the command waits for the mining of the transaction, querying for the transaction receipt that describes its execution result.

If you want to skip that time, use the -q, --quick flag:

rskcli deploy alice counter Counter -q
rskcli deploy charlie token Token string,string TOK,Token --quick

The deploy transaction is sent but it is up to you to check its inclusion into the blockchain. Take into account that if you uses this option, the instance address will be not saved (to be improved in future versions).

You can specify a value to be transferred to the new instance using the option -v, --value, examples:

rskcli deploy alice counter Counter -v 10000000
rskcli deploy charlie token Token string,string TOK,Token --value 100000000

In this use case, the contract constructor should allow the reception of value (in Solidity, the constructor should be a payable one)

Invoke a Contract

To invoke a deployed smart contract instance:

rskcli invoke <sender> <instancename> <functionsignature> [<arguments>]
rskcli invoke <sender> <instanceaddress> <functionsignature> [<arguments>]

Example:

rskcli invoke alice counter increment()
rskcli invoke alice token transfer(address,uint256) bob,1000000

In the latter example the token amount to transfer is expressed as uint256. The value is not expressed in token integer units: the token usually has a 18 decimal implicit positions. So to transfer a full token unit in a token with 6 decimals, you must use 1000000, and if the token have been defined with 18 decimals, you must use 1000000000000000000.

The sender should be an account:

• Exposed in the node you are using (like in ganache or RSK regtest)
• An account with a known private key, ie, created with newaccount command or with setaccount given a private key.

If they are more than one argument, their values are separated by commas.

The gas limit used for an invoke operation is 5_000_000 units, but you can specify the gas limit with the option -g, --gas, examples:

rskcli invoke alice counter increment() -g 100000
rskcli invoke bob token transfer(address,uint256) charlie,1000000 --gas 100000

The gas price is set using the value informed by the network. If you want to set the gas price explicitly, use the -gp, --gasPrice option:

rskcli invoke alice counter increment() -gp 100000
rskcli invoke bob token transfer(address,uint256) charlie,1000000 --gasPrice 100000

When the invoke transaction is sent to the node, the transaction hash is shown in the console. Then, the command waits for the mining of the transaction, querying for the transaction receipt that describes its execution result.

If you want to skip that time, use the -q, --quick flag:

rskcli invoke alice counter increment() -q
rskcli invoke alice counter add(uint256) 42 --quick

The invoke transaction is sent but it is up to you to check its inclusion into the blockchain. You must check manually the existence of a corresponding receipt using receipt command.

You can specify a value to be transferred to the invoked instance using the option -v, --value, examples:

rskcli invoke alice counter increment() -v 10000000
rskcli invoke bob token transfer(address,uint256) --value 100000000

In this use case, the invoked function should allow the reception of value (in Solidity, the function should be a payable one).

Call a Contract

Estimate Gas for Transaction

Accounts

Retrieves information about the known accounts with name.

rskcli accounts

For each named account, this info is retrieved: name, balance, no. of transactions sent (the nonce), and gas availability (account balance divided by current gas price in network).

The balance is expressed in weis. If you add the -d, --decimals, the balance is shown in ether/RBTC.

Instances

Retrieves information about the known smart contracts instances with name.

rskcli instances

For each named instance, this info is retrieved: name, balance, no. of transactions sent (the nonce), name of the original contract (if it is known).

The balance is expressed in weis. If you add the -d, --decimals, the balance is shown in ether/RBTC.

Retrieve Block

Retrieve block by number or hash

rskcli block <knumber>
rskcli block <hash>

You can also use the words latest and earliest to retrieve the latest and firt block, respectively.

Examples:

rskcli block latest
rskcli block 123456
rskcli block 0x6719dfc1d42a76dfc5a5257ff7188e00aa1e8bf82b9d71b46462074244a09a3e

The JSON with the block information is returned. Also, you can specify a property:

rskcli block latest gasUsed
rskcli block 123456 number

Retrieve Transaction

Retrieve Transaction Receipt

Save Configuration

The current configuration is stored in local rskcli.json file. You can make a copy with the command:

rskcli putconf <name>

Example:

rskcli putconf testnet1

The above command makes a copy of rskcli.json to rskcli-testnet1.json.

See Configuration File for more information about these files and security recommendations.

Restore Configuration

You can restore a configuration saved with the Save Configuration command executing:

rskcli getconf <name>

Example:

rskcli getconf testnet1

The above command copy the content of local rskcli-testnet1.json file to rskcli.json file.

See Configuration File for more information about these files and security recommendations.

Versions

• 0.0.1 First commands: haccounts, sethost, setaccount, newaccount, transfer, deploy, invoke, call, estimate, code, info, block, transaction, receipts, nonce
• 0.0.1 (Republish with fixed package name): put and get configuration, estimate deploy, info command, accounts command, instances command, setinstance command
• 0.0.2: balance command using optional block argument; save latest transaction in transfer command; transaction command retrieving the lastest transaction; property values in block, transaction and receipt; deploy command saves latest transaction; using [email protected]; call command with output types but no argument; verbose options in some commands; execute command remove verb from arguments; improved newaccount and accounts commands; invoke command saves latest transaction
• 0.0.3: using [email protected] with [email protected] with better bytes encoding/decoding

References

• GetBlock

To Do

• pending command
• wait command
• Commands description
• Tutorial- Save and restore configuration
• .gitignore notice or update
• help command
• setnetwork command
• no of time waiting receipts as option
• peers command
• estimate transfer
• setgas, setgasprice commands
• JSON format in outpus as flag
• silence flag
• host flag

References

• A guide to creating a NodeJS command-line package

License

MIT