How To Use RSK Starter Box

The first article relating to RSK Truffle Boxes, Using Truffle Boxes on RSK network, introduces the RSK specialized Truffle Boxes.

This is the second article in this series, which is a step-by-step tutorial to guide you on how to install and use the rsk-starter-box.

The rsk-starter-box comes with everything you need to start using smart contracts on the RSK Network. It includes network configs for Mainnet, Testnet and the SimpleStorage contract as an example for deployment.

Requirements

POSIX compliant shell
Curl
Node.js and NPM (Node Package Manager)
Code editor: Visual Studio Code (VSCode) or any other editor of your choice
Truffle

The requirements are explained in detail in this tutorial on:

How To Set Up An RSK Project Using Truffle And Open Zeppelin

Create the project

You can create an empty project template, but for those just getting started, you need only type truffle unbox <box name> to download and prepare your box of choice.

Create a new folder

For example, create the folder rsk-starter.

Navigate to the folder in the terminal.

mkdir rsk-starter
cd rsk-starter

Run the unbox command

The truffle unbox command will install all necessary dependencies in the project.

truffle unbox rsksmart/rsk-starter-box

This is the result using Windows OS:

The smart contract SimpleStorage.sol

Take a look at the smart contract SimpleStorage.sol. You can check it out in the folder named contracts.

pragma solidity >=0.4.0 <0.7.0;
contract SimpleStorage {
    uint storedData;
    function set(uint x) public {
        storedData = x;
    }
    function get() public view returns (uint) {
        return storedData;
    }
}

This smart contract has:

A variable storedData to store a number
A function get() to return the number stored at variable storedData
A function set() to change the number stored at variable storedData

Truffle development console

Truffle has an interactive console that also spawns a development blockchain. This is very useful for compiling, deploying and testing locally.

Run the development console by typing the following command below into the terminal:

truffle develop

This command is successful if you see a list of 10 accounts, a mnemonic and the command prompt is now truffle(develop)>

You are now in the truffle develop console with seeded accounts and their associated private keys listed.

Inside the development console we don’t preface commands with truffle.

Compile a smart contract

In the Truffle console, run this command:

compile

The compile output should be similar to:

Deploy a smart contract

To deploy a smart contract using Truffle, we need a new migrations file for Truffle to locate. This file contains instructions to deploy the smart contract.

The migrations folder has JavaScript files that help you deploy contracts to the network. These files are responsible for staging your deployment tasks, and they’re written under the assumption that your deployment needs will change over time.

A history of previously run migrations is recorded on-chain through a special Migrations contract. (source: truffle: running-migrations)

Take a look in the file 2_deploy_contracts.js located in the migrations folder.

const SimpleStorage = artifacts.require("SimpleStorage");
module.exports = function(deployer) {  
  deployer.deploy(SimpleStorage);
};

Migrate

In the Truffle console, run this command:

migrate

The migrate output should be similar to:

Test a smart contract

Truffle has an automated testing framework to facilitate the testing of contracts. All test files should be located in the test directory. To learn more, go to the Truffle documentation, in the section testing your contracts.

Our box also comes with the file TestSimpleStorage.js for testing the smart contract. You can check it out in the test folder.

In the Truffle console, run this command:

test

The test output should be similar to:

Interact with a smart contract in the development console

Make sure you deploy the smart contract before executing this part.

The next commands will run inside the development console.

truffle develop

Connect with our published contract

const simpleStorage = await SimpleStorage.deployed()

Now simpleStorage variable contains an instance of the previously deployed contract.

Don't worry about the `undefined` return, it is ok.

About SimpleStorage.json

The published contract information is stored by default in the build\contracts folder. You will find a JSON file with the same name of our smart contract.

The section - networks contains the networks in which the smart contract was published, including its address and hash of the transaction.

The ABI - Application Binary Interface is also very important because to connect with one smart contract, we must know the ABI and the address of the smart contract.

Get value

Get the value stored in the contract.

simpleStorage.get().then(bn => bn.toNumber())

We do not have any value stored, because we do not define anything at the moment when we deployed.

Set value

Store some value in the contract.

simpleStorage.set(10)

Have a look at the response.

This is a transaction receipt, generated by the blockchain nodes, in response to the transaction request.

Get value (again)

Verify if the value stored in the smart contract was changed.

simpleStorage.get().then(bn => bn.toNumber())

The value now should be 10!

Using RSK networks

Truffle makes developing on RSK easier because we can configure custom networks for RSK. The networks are already configured in the truffle-config.js file.

Setup an account
Create a wallet
Update Truffle config
Update the gas price
Get R-BTC

Get an address using these instructions.

For the RSK Testnet, get tR-BTC from our faucet.
For the RSK Mainnet, get R-BTC from an exchange.

Create a wallet

The best way to create a wallet is from a mnemonic, using the pattern defined at BIP39.

There are a few ways to do this. One is to create using a web wallet, such as Metamask or Nifty wallet. These wallets generate the mnemonic for you.

Another way is by using this web app: iancoleman.io/bip39

Note: In this tutorial, the method used to store the mnemonic is not recommended to be used for any ‘real’ wallet because it’s not secure enough to generate a private key in a website, however we will use this here for learning purposes, and because we’re using the Testnet, so no real amounts are at stake.

HD wallet provider

To connect to the RSK network, we are going to use a provider that allows us to connect to any network by unlocking an account locally.

We are using @truffle/hdwallet-provider. It was installed with the box.

Please be aware that we are using HDWalletProvider with RSK Networks derivations path:

RSK Mainnet dpath: m/44’/137’/0’/0
RSK Testnet dpath: m/44’/37310’/0’/0

For more information, check RSKIP57.

Update .secret

Paste the wallet mnemonic in the file .secret, located in the folder project, and save it.

Setup the gas price

Gas is the internal pricing for running a transaction or contract. When you send tokens, interact with a contract, send RBTC, or do anything else on the blockchain, you must pay for that computation. That payment is calculated as gas. In RSK, this is paid in R-BTC. The minimumGasPrice is written in the block header by miners and establishes the minimum gas price that a transaction should have in order to be included in that block.

To update the minimumGasPrice in our project run this query using cURL:

Testnet

curl https://public-node.testnet.rsk.co/ -X POST -H "Content-Type: application/json" \
    --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest",false],"id":1}' \
    > .minimum-gas-price-testnet.json

Mainnet

curl https://public-node.rsk.co/ -X POST -H "Content-Type: application/json" \
    --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest",false],"id":1}' \
    > .minimum-gas-price-mainnet.json

This query saved the details of the latest block to file .minimum-gas-price-testnet.json or .minimum-gas-price-mainnet.json, respectively.

In the truffle-config.js file, we are reading the parameter minimumGasPrice in each json file.

For more information about the Gas and minimumGasPrice please visit the gas page.

Using Truffle Console to connect to the RSK network

Run the development console for any RSK network.

Testnet

truffle console --network testnet

Mainnet

truffle console --network mainnet

This action instructs Truffle to connect to an RSK public node and grants it permission to control the accounts created with your mnemonic through the HD wallet provider.

Let’s connect to the Testnet network:

C:\RSK\rsk-starter>truffle console --network testnet
truffle(testnet)>

Test the connection to RSK network

On any of the networks, run these commands in the Truffle console:

Block number

Shows the last block number.

(await web3.eth.getBlockNumber()).toString()

Network ID

To get the network ID, run this command:

(await web3.eth.net.getId()).toString()

List of network IDs:

mainnet: 30
testnet: 31
regtest (local node): 33

Check it out the results in Testnet:

Accounts

To get your accounts, in the Truffle console, enter:

const accounts = await web3.eth.getAccounts()

To list the accounts, in the Truffle console, enter:

accounts

To view each account:

accounts[0]
accounts[1]

In my example, the account[0] is 0xCd70794c2F3C657310eF13b6FF3Ec2d112513B39.

Check balance

To check the balance of account[0], for example, run this command in Truffle console:

(await web3.eth.getBalance(accounts[0])).toString()

The balance is 0 and we need some tR-BTC to pay gas fees, which will be used to publish smart contracts and interact with them. We shall obtain some tR-BTC in the next step.

Get R-BTC

The Smart Bitcoin (R-BTC) is the token used to pay for the execution of transactions in RSK.

Testnet: get tR-BTC from our faucet.

Mainnet: get R-BTC from an exchange.

On RSK Testnet

Enter your wallet address and pass the CAPTCHA.

Wait a few seconds…

You can see the transaction hash: 0xe7a25985f019482d362a3be908f1c0b3dee612fcc78716b6a341d8ad6138ea95

Recheck balance

To check balance again, run this command in the Truffle console:

(await web3.eth.getBalance(accounts[0])).toString()

For my example on RSK Testnet using account 0xCd70794c2F3C657310eF13b6FF3Ec2d112513B39:

Great! Now I have 50000000000000000, which means that I have 0.05 tR-BTC with 18 decimal place of precision.

Exit Truffle console

In the Truffle console, enter this command to exit the terminal:

.exit

Deploy the smart contract on RSK network

Let’s now switch to interacting with a “real” blockchain, which is running on multiple nodes distributed across multiple computers!

In the terminal, run the migrate command for the RSK network of your choice.

Testnet

truffle migrate --network testnet

Mainnet

truffle migrate --network mainnet

We’ll do it on RSK testnet.

Wait a few minutes… Congratulations!

Simple storage is now published on the RSK network.

Make sure you have enough R-BTC to deploy it.

Interact with a smart contract on RSK network

Interact with the

simpleStorage

smart contract using Truffle console connected to an RSK network.

It’s the same as we did for Truffle development console, but now it will be for a real blockchain!

Make sure you deploy the smart contract before executing this part.

The next commands will run inside the Truffle console.

Connect with our published contract

const simpleStorage = await SimpleStorage.deployed()

Now simpleStorage variable contains an instance of the previously deployed contract.

Get value

Get the value stored in the contract.

simpleStorage.get().then(bn => bn.toNumber())

This method does not modify the storage of the contract, so no funds are spent calling it.

We do not have any value stored, because we do not define anything at the moment when we deployed.

Set value

Store some value in the contract.

simpleStorage.set(10)

To modify a contract’s storage we must pay with gas. This gas is discounted from the account balance.

The value now should be 10!

Final considerations

In this tutorial you learned how to use the Truffle box rsk-starter-box, which comes with everything you need to start using Truffle on RSK networks.

Our goal is to join forces and give options to people who believe in smart contracts based on Ethereum, and also believe in the power of Bitcoin, through RSK.

Check out RSK Blockchain for more details about us.

I hope this tutorial has been helpful and I’d appreciate your feedback. Share it if you like it :)

Do you have questions? Ask in RSK chat

Author: Solange Gueiros

Reviewer: Owanate Amachree