Skip links
rsk logo

Introduction to Smart Contracts Development in RSK


These last years there has been growth in Smart Contracts development, predominantly in the Ethereum blockchain. Ethereum, being a different type of blockchain than Bitcoin, can execute concise lines of code inside its chain, a job that Bitcoin (specifically designed to send transactions easily) can’t do. Here is where RSK intervenes building a sidechain tied up to Bitcoin through a 2-Way Peg system, managed by the Federation Partners, that makes code execution possible. Instead of designing a new programming language for developing Smart Contracts, they used Solidity, the same language that Ethereum uses. This has two benefits: not only programmers won’t have to learn a new skill but also contracts in the Ethereum network could be deployed in RSK without much effort, taking advantage of the vast market capitalization Bitcoin has.

In these articles, I’m going to explain how to create a RSK node, how to configure it properly and finally how to deploy contracts and interact with them.


System Environment

The node software is based on EthereumJ. The RSK developer team offers different ways for different OS to setup a node. For this article, we are going to learn how to setup RSKj 4.2 in Linux, more specifically in Ubuntu LTS 16.04. When I started this walkthrough, the latest Ubuntu LTS was 16.04 and a few days ago, the 18.04 was released. Because of that and other stability issues on the new released OS, I’m going to use the 16.04 version.

Ok, let’s start. I’m going to suppose that you are going to install the node from a fresh install of the OS, so some programs are probably already installed on your PC and you can skip steps. But for those who don’t have them, this would be of help.

Essential Programs

Our firsts tools are git and curl. With them we can obtain libraries and code from many developers and use them in our work. To install them, we have to just write

$ sudo apt-get install git
$ sudo apt-get install curl

We need an instance of Java to get it work because it runs on its VM. The latest Java version was the 10th by the time of writing this guide, but in our case, we are going to use the 8th version of the Oracle branch instead of the OpenJRE. Either of them should work just fine. To do so, we first add the repository to our system and then we install it.

$ sudo add-apt-repository ppa:webupd8team/java
$ sudo apt-get update
$ sudo apt-get install oracle-java8-installer

If we have another version of Java installed, we have to make sure that the default is the one we want:

$ sudo apt-get install oracle-java8-set-default

Then, we check which one is in use as

$ java -version

After that, we need to set the path for Java adding a line in the /etc/environment file as root. The line is


Let’s sum up:
Java? Done.
Git & curl? Double done.
So what’s next? The node, RSKj itself.

Node.js and RSK node

We are going to install the 8th version as

$ curl -sL | sudo -E bash -
$ sudo apt-get install -y nodejs
$ sudo apt-get install -y build-essential

And then the RSK project already packaged rskj and put it up in a PPA as

$ sudo add-apt-repository ppa:rsksmart/rskj
$ sudo apt-get update
$ sudo apt-get install rskj

When it finishes, the installer will ask us in which network we would like to work. Don’t be scared to pick one, you can change it later with some tweaks that we’ll see. Let’s select Testnet for now.

The node is now installed. To use it, you have to handle it as a service as

$ sudo service rsk start
$ sudo service rsk status
$ sudo service rsk stop

These are respectively, to start the node, watch what’s happening (logs and problems in the service) and stop it.

These are a few recommendations born from experience. DO NOT TRY TO:

  • Turn off your PC while it’s running
  • Use conflictive drivers/hardware that could freeze the OS (Ehmm.. Nvidia)
  • Change configuration files while it’s running.

When the database isn’t closed correctly, it ends up corruped and the easy way to sync the node again is to reset it and start over the syncing process from scratch. Try to have a UPS in case of frequent power shortcuts.

The places where the node saves its configuration, logs and databases are:

Configurations files: /etc/rsk/
Databases: /var/lib/rsk/databases/
Logs: /var/logs/rsk/

 Development Environment

There are a few ways to interact with rskj. You can use Node.js, the console from the RSK utils, raw RPC calls, Truffle and any working web3 library. For now, we will be using Truffle because it also allow us to compile and deploy in very few steps.

To install it globally, we use the tool npm from the node.js packages that we’ve installed.

$ sudo npm install -g truffle

Then we create a folder and ask it to unpack the basic developer template. Warning: we need the folder to be completely empty. Otherwise, Truffle will terminate with errors.

$ mkdir ~/Truffle && cd ~/Truffle
$ truffle init

To connect truffle to our node, we need to configure the network in which the node is working. In our case, the default port is 4444 over localhost, so the file should look like:

module.exports = {
  networks: {
    rsk: {
      host: "localhost",
      port: 4444,
      network_id: "*" // Match any network id

Once we have done this, we can connect to the node with

$ truffle console --network rsk

If everything went correctly, you should be able to use the console from Truffle, showing the command line as


Now we should be able to watch the syncing state of our node, the last block number which we have and the number of peers we are connected to. To do so, you have to use the library web3 library in the same way as in Ethereum.

Just a minor warning: the latest web3 inside Truffle is a bit old, 0.20.6, so be warned that some commands have different syntax in the newer versions. Please look for the available commands using the autocomplete feature (TAB key twice) after web3.

For the functions that we have mentioned, the commands in their respective order are

truffle(rsk)> web3.eth.syncing
truffle(rsk)> web3.eth.blockNumber

Network Selection

Up to now, the procedure was independent of which RSK network we were using (Mainnet, Testnet or Regtest). To configure them, we talked about what we need to change its configuration file which is located at /etc/rsk/. There we find three configuration files and a symbolic link to one of them. The symbolic link, node.conf, is the one that the RSK service reads. So if we want to change its network, we stop the node, go to the folder, change the link to the correct configuration file and start over the service like this

$ sudo service rsk stop
$ cd /etc/rsk
$ sudo rm -f node.conf
$ sudo ln -s ABCDEFG.conf node.conf
$ sudo service rsk start

Where ABCDEFG can be “testnet”, “mainnet” or “regtest”. The procedure is the same in all three cases.

If you have installed the node as I explained, you should have most of the parameters already set. If we open one of those files, we see from where does the node obtain peers, the active port (5050 for the Mainnet and 50505 for the Testnet), our node private key, some parameters for the peer’s configuration, the network ID (775 for Mainnet, 779 for the Testnet and 34567 for the Regtest), where the particular database is saved, if we want to start from scratch and reset the database (this is useful when our DB is corrupted. In that case, switch the bool reset to “true” once and then start the node), the port where we can connect from programs like Truffle and lastly, the wallet setting.

Wallet and Account Settings

In the file by default, we have

wallet {
    accounts = []

With this configuration, we can’t deploy contracts nor send transactions, neither create accounts and so on. To enable those we need to add the following line

wallet {
    accounts = []
    enabled = true

Then we can make a new account in Truffle by doing

truffle(rsk)> web3.personal.newAccount(‘somePassword’)
truffle(rsk)> web3.personal.unlockAccount(web3.eth.accounts[0],'somePassword')

Also, if we have already an account in the RSK network, we can simply add it in the config file as

wallet {
    accounts = [
            "privateKey" = "PRIVATEKEY"
            "address" = "0xADDRESS"
    enabled = true

Where “PRIVATEKEY” and “0xADDRESS” are the private key and address of your account with funds in the network to be used.

Having that changed, we can add that address in the truffle.js configuration file so our transactions and deploys are originated from that address by default and also, if you are using the Testnet, set the gas limit to a high number and the gasPrice to zero. These 2 parameters are added because if we don’t set the gas, our transaction could never be mined by the network, and for the second one, the Testnet doesn’t charge us real money to work with, so even with a null price value, miners can add our transactions.

Now our truffle.js for Testnet should look like

module.exports = {
	networks : {
		rsk: {
			gas : 2500000,
			gasPrice : 0,
			from : "0xADDRESS",
			host : "localhost",
			port : 4444,
			network_id : "*" // Match any network id

Having configured all that, and after we wait some time to sync our node in the TestNet or MainNet, between 1 and 3 days, we can start deploying contracts and doing transactions. Congrats!

Extra Utilities

While we wait for that to happen, I want to add that RSK made some tools for our node that are listed in their Github. Among them, there is a console, a local block explorer that works over a web browser and a test module. To use them, clone their repository as

$ mkdir Utils && cd Utils
$ git clone

Then, we enter to the util’s folder, e.g. console, and proceed as

$ cd utilities/console/
$ npm install

After that, we can connect to our node as

$ node console.js -server localhost:4444

In which we can call functions as usual

RSK > web3.eth.blockNumber

I don’t recommend it though because it has an older version of web3 than Truffle (which is already old!).

For the explorer, you have to do the same procedure and add an extra step: change the host:port line in config.json for localhost:4444 after execute npm install. Then, to load the explorer:

$ npm start

Which we can open from the web browser at http://localhost:3000.

The Java Way

There are also other methods to launch it such as executing the .jar package with java and introducing the config file as input as

$ java -Drsk.conf.file=ABCDEFG.conf -cp rskj-core-0.4.1-BAMBOO-all.jar co.rsk.Star

From where, the public and private key, and the node ID, can be obtained from

$ java -cp rskj-core-0.4.1-BAMBOO-all.jar co.rsk.GenNodeKeyId

Nevertheless, with this method, you have to set all the parameters of the template file, which can be confusing for a beginner.

Dedicated Node

Also, if someone uses a computer just for running the node, it could be better to use it as a server and connect to it via ssh. Beforehand, you need to install on that computer the ssh server with

$ sudo apt-get install openssh-server openssh-client

To then connect from another computer with

$ ssh user@host

Getting Funds

To get funds in your account, depends on which network you are working. For the Mainnet, you must exchange your BTC through a 2-Way Peg to get SBTC in the RSK side and be able to pay for the gas and fees of the miner / RSK Labs. To do so, first you need to whitelist your BTC account by going to this form.

Then, once you are whitelisted, you need to call to the Federation Contract’s address (0x0000000000000000000000000000000001000006) and ask for the deposit address. That can be done just as

truffle(rsk)> web3.sha3("getFederationAddress()").slice(0,10); // = 0x6923fa85
truffle(rsk)>{data: "6923fa85", to: "0x0000000000000000000000000000000001000006"});

The result is a long hex number which has 3 parts. The first 32 bytes represent the length field, the second 32 bytes represent the string length and the rest is the address coded in ASCII representation followed by zeros. So, if we convert this last part of the message, we get our BTC (or tBTC) address of the Federation to deposit our funds.

truffle(rsk)> web3.toAscii(‘LAST_PART’)

After sending the transaction, you have to wait for +100 confirmations on that block plus a 5 minute period to see your funds in the RSK network. Your account on the other side is derived from your original BTC account through your private key. To get control of your new account, you can enter to the utils site and obtain the private key of your derived account.

In this case, because I had only the Testnet synced, I’ve done this only on that particular network. Besides, my BTC and tBTC accounts weren’t whitelisted yet, so I can’t tell you how the system works (hopefully soon!). Just one last thing: the address for the Mainnet is different from the one in the Testnet. You have to do the same procedure for your selected network. Be warned!

Although you don’t need funds in your Testnet account (gas is free! :D), it’s recommended to get some just to test if you have a problem with your account, node, or anything else while you debug a contract. Sometimes the system is down and you can’t deploy contracts; in that case, if you don’t know what it’s happening and your hair is falling out, you can test if the network is ok just by sending a transaction to another account of yours and see what happens in the block. If you don’t want to do the 2-Way Peg or wait to be whitelisted, you can just ask test funds from the faucet.

Connecting Metamask to our RSK Node

If you want to use Metamask to send transactions, you have to configure two things: the first one is in node.conf, in which we have to change the cors parameter from cors = “*”  to cors = “*”  and then reboot our node; the second one is to set the local RPC network in Metamask as http://localhost:4444, or as you have configured it in the node.conf file.

After that, you have to import the private key of your account to Metamask and then it should appear the balance of your account. The unit says ETH but it’s really SBTC. Don’t worry.


In this first part of the walkthrough I’ve shown an introduction for creating the developing environment of RSK Smart Contracts. We’ve seen how to

  • build an RSK node in different networks,
  • select a network for syncing,
  • configure Truffle to interact with our node,
  • add an account to make transactions to the network,
  • interact with the 2-Way Peg system and transfer our funds.

In the next chapter, we will be creating and deploying contracts to the network and interacting with them in the Mainnet. You can check it right here.