The first article relating to RSK Truffle Boxes, Using Truffle Boxes on RSK network, introduces the RSK specialized Truffle Boxes.
We already presented the rsk-starter-box in the second article: How To Use RSK Starter Box, the first box to start using smart contracts on the RSK Network.
Now, this third article in the series is a step-by-step tutorial to guide you on how to use the rsk-plant-box, which comes with everything you need to create a complete dApp - decentralized application on RSK networks. It includes network configurations for Mainnet, Testnet, local node (regtest) and also an user interface to interact with the smart contract.
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:
Create the project
The truffle unbox command sets up a project based on a known template. In this tutorial, we will be using the RSK plant box Truffle box, which comes with everything you need to build a complete dApp on RSK networks, including a frontend.
1. Create a new folder
For example, create the folder rsk-plant.
Navigate to the folder in the terminal.
2. Run the unbox command
The truffle unbox command will install all necessary dependencies in the project.
Take a look at the commands below:
mkdir rsk-plant
cd rsk-plant
truffle unbox rsksmart/rsk-plant-boxThis is the result using Windows OS:
PlantShop.sol
Take a look at the smart contract PlantShop.sol. You can check it out in folder contracts.
This smart contract has:
- A variable buyers to store an array with 16 positions to store addresses
- A function getBuyers to return the list of addresses stored at variable buyers
- A function buy to update an address at variable buyers, in the number of position sent as parameter
Compile a smart contract
In the Truffle console, run this command:
truffle compileThe compile output should be similar to:
Truffle development console
Truffle has an interactive console that also spawns a development blockchain.
In the article How To Use RSK Starter Box, we presented how to use the Truffle develop console for compiling, deploying and testing locally.
Using RSK networks
Truffle makes developing on RSK easier because we can configure custom networks for RSK. This Truffle box is already configured to connect to three RSK networks:
- regtest (local node)
- testnet
- mainnet
These networks are already configured in the truffle-config.js file. Testnet will be used in this tutorial.
RSK testnet
We need to do some tasks:
- Setup an account / create a wallet
- Update .secret
- Connect to an RSK network
- Get tR-BTC
- Setup RSK network gas price
- Deploy in the network of your choice
Create a wallet
The easy way to set up an account is by using a web3 wallet injected in the browser.
I suggest you use Nifty wallet, because Nifty comes configured for RSK networks.
Select the RSK Network in the web wallet.
Take a look at truffle-config.js file, this shows we are using HDWalletProvider with RSK Networks derivations path:
- RSK Testnet dpath: m/44’/37310’/0’/0
- RSK Mainnet dpath: m/44’/137’/0’/0
For more information, check RSKIP57.
Update .secret file
After creating your wallet, copy your mnemonic.
Paste the wallet mnemonic in the file .secret, located in the folder project, and save it.
Connect to an RSK network
Run the development console for any RSK network. Let's connect to the Testnet network:
truffle console --network testnetThis 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.
Test the connection to RSK network
On any of the networks, run this 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 last steps in this image:
You can verify that I got the last block twice, and the block number increased, so we conclude that the connection is ok.
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:
accountsTo view each account:
accounts[0]
accounts[1]
...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.
Get tR-BTC from our faucet for Testnet.
Recheck balance
To check balance again, run this command in the Truffle console:
(await web3.eth.getBalance(accounts[0])).toString()Exit Truffle console
In the Truffle console, enter this command to exit the terminal:
.exit
Setup the gas price
Gas is the internal pricing for running a transaction or contract. When you send tokens, interact with a contract, send R-BTC, 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, in the project folder, run this query in a POSIX terminal using cURL:
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.jsonThis query saved the details of the latest block to file .minimum-gas-price-testnet.json.
In the truffle-config.js, we are reading the parameter minimumGasPrice in each json file.
For more information about the Gas and minimumGasPrice please go to the gas page.
Deploy the smart contract on RSK network
Now let’s switch to interacting with a "real" blockchain, which is running on multiple nodes distributed around the world, across multiple computers!
We will deploy it by running the below commands directly in the terminal, without using the Truffle console, to show an alternative.
To use Testnet or Mainnet, you need to specify this using the parameter -- network. On any of the networks, run this command in a terminal (not in Truffle console).
truffle migrate --network testnetThe migrate process in a real blockchain takes more time, because Truffle creates some transactions which need to be mined on the blockchain.
Wait a few minutes…
Congratulations!
The plant shop is now published on the RSK network.
Make sure you have enough tR-BTC to deploy it.
View the deployed contract in the Testnet explorer
You can copy the contract address and view it in the Testnet explorer.
For example, 0x3A6Dd83F76eCceA654bDc4ea29170B8A34A9e270 is the contract address for my last deploy.
If you would like to have the code source verified, you can do it in the tab Code in the explorer.
The dApp
Included with the plant-shop Truffle Box was the code for the app's front-end. That code exists within the src directory.
The front-end doesn't use a build system (webpack, grunt, etc.) to be as easy as possible to get started. The structure of the app is already there, including the functions to interact with the smart contract on Blockchain This way, you can take this knowledge and apply it to your own front-end development.
Select the network
To interact with the dapp in a browser, the easy way is using a web3 wallet injected in the browser.
Be sure to select the RSK testnet in the web wallet.
The lite-server
We're using the lite-server package to serve our static files. This shipped with the plant-shop Truffle Box, but let's take a look at how it works.
Running the server
Now we're ready to use our dapp!
Outside the Truffle console, in a terminal, run the liteserver development server for front-end hot reloading.
Smart contract changes must be manually recompiled and migrated.
Start the local web server:
npm run devThe dev server will launch and automatically open a new browser tab containing your dapp. It is running at http://localhost:3000
You can realize that some plants show the first characters of an account, which was bought before, using the Truffle console.
Buying plants
In our garden store, don't worry about the prices, the plants are free!
To use the dapp, click the Get button on the plant of your choice.
You'll be automatically prompted to approve the transaction by the web wallet.
Click Submit / Confirm to approve the transaction.
I will buy the coffee plant:
After the transaction is confirmed, you'll see the button next to the chosen plant change to show the first characters of the wallet that got the plant and become disabled, just as we specified, because the plant has now been acquired.
If the button doesn't automatically change to show the account, refreshing the app in the browser should trigger it.
Final considerations
Congratulations👏👏👏!
You built and ran a complete dApp on RSK network!
In this tutorial you learned how to use the Truffle box rsk-plant-box to create a complete dApp on RSK blockchain.
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