What is needed to set up a master node?
A home PC, a VPS or a Raspberry Pi will be suitable.
A mechanism has been developed to track the participation of master nodes in the consensus, which takes into account inaccessible nodes at the time of voting. Despite this, your node must be online 24/7, otherwise it will not earn validators fees.
At the moment, it is possible to set up a master node on Linux and MacOS. In the future, support for Windows and Android will be added as well.
While it is possible to use a private IP address, this will complicate the maintenance process. In the case of a private one, tracking of IP address changes will be required, as well as timely updates to the public node list. Otherwise, the node will not participate in consensus and will not earn validators fees.
The option to use an IP address with IPv6 protocol will be implemented in the future.
Everything that is written in the guide using < and > symbols is an example. This information can and should be changed according to each step of the process.
Symbols < and > shouldn't be used when executing the commands.
We recommend changing to root user for the setup of the master node. This will simplify the process.
In Linux, user can be switched with command:
sudo -i
In MacOS, it can be done with similar command:
sudo -s
All the commands presented in this instruction imply that the root user is being used.
Linux build: https://pub.cellframe.net/linux/cellframe-node/master/cellframe-node-5.2-330-updtr-amd64.deb
Linux build for devices based on ARM architecture : https://pub.cellframe.net/linux/cellframe-node/master/cellframe-node-5.2-330-arm64.deb
MacOS build: https://pub.cellframe.net/macos/cellframe-node/master/cellframe-node_5.2.330_amd64.pkg
Command for downloading files using the terminal:
wget <link>
Command to install:
apt install ./<file_name>
You will be asked a few questions about the cellframe node configuration. Below are the recommended answers.
If a mistake was made in initial configuration, it can be changed with the command:
dpkg-reconfigure cellframe-node
/opt/cellframe-node/etc/cellframe-node.cfg
/opt/cellframe-node/etc/network/Backbone.cfg
First, you need to go to the /opt/celframe-node/bin folder and check the availability of the permissions to run cellframe-node executable files.
/opt/celframe-node/bin:cd /opt/cellframe-node/bin
ls -la
masternode@ubuntu:/opt/cellframe-node/bin$ ls -la
total 16156
drwxrwxr-x 2 root root 4096 Jul 13 22:20 .
drwxrwxr-x 9 root root 4096 Jul 13 22:20 ..
-rwxrwxr-- 1 root root 8714248 Jul 13 10:21 cellframe-diagtool
-rwxrwxr-- 1 root root 4214888 Jul 13 10:23 cellframe-node
-rwxrwxrwx 1 root root 73056 Jul 13 10:23 cellframe-node-cli
-rwxrwxr-- 1 root root 3522760 Jul 13 10:23 cellframe-node-tool
The line with cellframe-node-tool is the one you should take a look at.
If the first column ends with - and not the x, then the following command should be executed:
cellframe-node-tool:chmod +x /opt/cellframe-node/bin/cellframe-node-tool
After that, the last symbol will change to x:
-rwxrwxr-x 1 root root 3522760 Jul 13 10:23 cellframe-node-tool
cellframe-node-tool cert create <backbone.cert_name> sig_dil
It is recommended to use the CRYSTALS-Dilithium signature.
sig_dil parameter represents this signature type.
This step is also a verification that the certificate was created correctly. In the future, we will need this hash when searching for our signature in blocks.
Command to view the certificate hash:
cellframe-node-tool cert pkey show <backbone.cert_name>
The created certificate is located in the following folder:
/opt/cellframe-node/var/lib/ca
Command to create a new wallet:
cellframe-node-cli wallet new -w <wallet_name> -restore <hash>
"-restore" is an important parameter that allows you to restore a created wallet on another machine in case anything happens with the current one.
<hash> value needs to be entered manually. Recovery hash requirements are:
0xIf your wallet was created in cellframe-node with a hash that does not fit these requirements, then the -restore_legacy parameter should be used with the hash of old format instead of the -restore parameter.
If you would like to restore a wallet in cellframe-node that was created in cellframe dashboard, the following needs to be done:
sha256-restore parameter after the 0x prefixYou can convert a SEED phrase into the required hash using the SHA256 algorithm in the terminal in Linux, macOS, or using one of the web resources that provide such functionality.
Correct format is -restore 0x<hash>
Command to restore a wallet:
cellframe-node-cli wallet new -w <wallet_name> -sign sig_dil -restore <hash> -force
Command to restore a wallet with password:
cellframe-node-cli wallet new -w <wallet_name> -sign sig_dil -restore <hash> -password <password> -force
Please take a note of parameter -force at the end of command line. Its presence is necessary to restore the wallet!
Before interacting with a protected wallet, it needs to be activated with command:
cellframe-node-cli wallet activate -w <wallet_name> -password <password>
After successful creation or restoration of a wallet, its address and balance can be checked with the following command:
cellframe-node-cli wallet info -net Backbone -w <wallet_name>
Use the following command to check node status in the network and find its address:
cellframe-node-cli net -net Backbone get status
# Expected result:
Network "Backbone" has state NET_STATE_ONLINE (target state NET_STATE_ONLINE), active links 3 from 5, cur node address XXXX::XXXX::XXXX::XXXX
We are interested in the last record in the format XXXX::XXXX::XXXX::XXXX.
Save the cur node address as it will be required in the next steps.
The configuration file is located at:
/opt/cellframe-node/etc/network/Backbone.cfg
This file should be opened with a editor to make changes to it. For it, a terminal-based text editor nano will be used.
nano /opt/cellframe-node/etc/network/Backbone.cfg
In this file, changes should be made in two sections.
[general] section and add the following lines:node_addr_type=static
node-addr=XXXX::XXXX::XXXX::XXXX
For the node address a value from the previous step should be used.
[esbocs] section and make the necessary changes to match the example below:[esbocs]
# Here we specify the name of our certificate
blocks-sign-cert=<backbone.cert_name>
#minimum_fee=
# We specify the address of our wallet to collect the fees
fee_addr=<Backbone_wallet_address>
# Add "set_collect_fee" line. Here we specify the amount of $CELL which will be automatically collected after the desired amount is accumulated. This amount is defined by you!
set_collect_fee=5
Do not forget that symbols < and > should not be used!
To save changes to the file, use the keyboard shortcut Ctrl + O.
To exit the editor, use the keyboard shortcut Ctrl + X.
The configuration file is located at:
/opt/cellframe-node/etc/cellframe-node.cfg
To edit it, use a nano editor:
nano /opt/cellframe-node/etc/cellframe-node.cfg
The value of the auto_proc parameter needs to be changed from false to true in the [mempool] section:
[mempool]
# Automatically false, for enabling need role master or higher
auto_proc=true
To save changes to the file, use the keyboard shortcut Ctrl + O.
To exit the editor, use the keyboard shortcut Ctrl + X.
In order for the made changes to apply, the node must be restarted.
To do this, use the following commands:
service cellframe-node stop
service cellframe-node start
To check that the node is running, you can use the command:
systemctl status cellframe-node.service
The expected result:
● cellframe-node.service - Cellframe Node
Loaded: loaded (/etc/systemd/system/cellframe-node.service; enabled; vendor preset: enabled)
Active: active (running) since Thu 2023-07-27 05:14:24 PDT; 4s ago
Main PID: 52072 (cellframe-node)
Tasks: 8 (limit: 4558)
Memory: 568.6M
CGroup: /system.slice/cellframe-node.service
└─52072 /opt/cellframe-node/bin/cellframe-node
An order is published on the network. With it, you specify what your validator's fee will be for conducting transactions on the network.
Command to create an order:
cellframe-node-cli srv_stake order create -net Backbone -value <value> -cert <backbone.cert_name>
In this command, the value is the amount of the validator fee in $CELL. That's how much your master node will be paid for signing the block. The amount of $CELL is written in datoshi. For example, 0.05e+18 = 0.05 $CELL.
It is not worth inflating your price, because when conducting transactions, the network focuses on the average value among all created orders.
The recommended amount is 0.05 $CELL
In this step, you are going to add the information about your node to the network, specifying at the same time your public IP address and the port that your node is using (8079 by default)
Command to publish your node:
cellframe-node-cli node add -net Backbone -ipv4 <public IP address> -port 8079
Expected result after successful addition:
Node addr successfully added to node list
To add a node to the public list, port 8079 must be open on your device. It is necessary for the correct functioning of the masternode.
To check if you have published the node address successfully use the following command:
cellframe-node-cli node dump -net Backbone
#Expected result:
In the obtained list of published nodes in the network, your node is present.
In this step, we would like to emphasize some details about locking mCELL.
Your Backbone wallet balance should contain at least 10 mCELL which you agree to stake in order to delegate your key for signing blocks.
The more mCELL are used, the higher the weight of your master node in the consensus, and the higher the probability that your master node will sign the new block and push it onto the blockchain.
However, please take into account your active stakes and their unlock periods. Since your mCELL will be locked, it may be impossible to unlock some stakes and your invested CELLs won't be generating rewards.
If this is not taken into account, then you will have to revoke the blocked mCELL to update your stakes. In this case, you will lose the role of the master node in the network and you will need to get re-approval for the request to become a master node.
The easiest way to avoid this is to make a new stake for the duration that your master node is going to be running.
Creating a transaction that locks mCELL and delegates the certificate you created:
cellframe-node-cli srv_stake delegate -cert <backbone.cert_name> -net Backbone -w <Backbone_wallet_name> -value 10.0e+18 -node_addr XXXX::XXXX::XXXX::XXXX -fee 0.05e+18
#Expected result:
SAVE TO TAKE ===>>> Stake transaction <transaction hash> has done
In this command, the -value parameter is the number of mCELL you are staking.
10.0e+18 = 10 mCELL Cellframe node uses the datoshi format for managing token values.
Datoshi is a format of recording values that allows accuracy of up to 18 decimals after the comma.
As stated in the previous step, the greater the number of blocked mCELL, the greater the weight of your master node in the consensus, and the higher the probability that your master node will sign the new block and push it onto the blockchain.
The hash from the transaction made in the previous step must be sent to the Cellframe team. There are multiple ways to request approval of your node:
If using the Feedback form, please specify the topic of your request as master node and leave a valid e-mail address for the team to contact you.
After receiving approval from the Cellframe team, the node needs to be restarted.
service cellframe-node stop
service cellframe-node start
To check that the node is running, you can use the command:
systemctl status cellframe-node.service
The expected result:
● cellframe-node.service - Cellframe Node
Loaded: loaded (/etc/systemd/system/cellframe-node.service; enabled; vendor preset: enabled)
Active: active (running) since Thu 2023-07-27 05:14:24 PDT; 4s ago
Main PID: 52072 (cellframe-node)
Tasks: 8 (limit: 4558)
Memory: 568.6M
CGroup: /system.slice/cellframe-node.service
└─52072 /opt/cellframe-node/bin/cellframe-node
Hooray! Your node is now a master node and participating in the network consensus!
Creating this file will allow us to quickly respond to changes in the work of validators.
Also, we will be able to notify you about failures in your master node.
/opt/cellframe-node/etc/ directory:cd /opt/cellframe-node/etc/
diagdata.json file:touch diagdata.json
nano editor:nano diagdata.json
{"name":"XXXX::XXXX::XXXX::XXXX", "category":"validator", "ip_addr": "XXX.XXX.XXX.XXX"}
In the name field specify the address of your node in the Backbone network that was received earlier.
In the ip_addr field specify the public IP address of your device.
To save changes to the file, use the keyboard shortcut Ctrl + O.
To exit the editor, use the keyboard shortcut Ctrl + X.
Note: Manual fee collection is not mandatory because the validators fee is collected automatically. The transaction that collects validators fee will be formed when the required number of signed blocks is accumulated to receive the previously specified value - the set_collect_fee parameter in the Backbone.cfg file.
Command to view the list of blocks from which it is possible to withdraw the fees:
cellframe-node-cli block list -net Backbone -chain main -cert <backbone.cert_name> -unspent
The command to collect the fees (hashes are taken from the command above):
cellframe-node-cli block fee collect -cert <backbone.cert_name> -addr <Backbone_wallet_address> -net Backbone -chain main -hashes <hash,hash,hash,hash> -fee 0.05e+18
Note: when collecting fees, block hashes must be separated by commas without spaces.
Since a transaction is created when collecting the fees, a validator's fee and network fee must also be paid from it. Therefore, the more block hashes are used each time when collecting validator fees, the more profitable the result.
# Certificate is located at:
/opt/cellframe-node/var/lib/ca
# Wallet file is located at:
/opt/cellframe-node/var/lib/wallet
Set the same static node address on the new device as was used on the previous one.
Please refer to Part 2 Step 8 for detailed instructions.
Make changes to the list of nodes available in the network.
cellframe-node-cli node del -net Backbone -addr XXXX::XXXX::XXXX::XXXX
cellframe-node-cli node dump -net Backbone
# Expected result:
In the obtained list of published nodes in the network, your node is not present.
cellframe-node-cli node add -net Backbone -addr XXXX::XXXX::XXXX::XXXX -cell 0x0000000000000000 -ipv4 <ip> -port 8079
cellframe-node-cli srv_stake invalidate -net Backbone -tx <transaction hash> -w <wallet name> -fee 0.05e+18
The -tx parameter uses the hash of the transaction with which you locked the mCELL and delegated the certificate.
If it was not saved, it can be found using the following command:
cellframe-node-cli srv_stake list keys -net Backbone
The result of this command execution is a list of all validators in the network. This is where you will find the necessary transaction hash.
Pkey hash: <hash>
Stake value: <value>
Tx hash: <hash>
Node addr: <address>
As a result, the mCELL will be returned to the wallet, and your node will no longer have a master role in the network.
If you would like to increase the amount of locked mCELL and increase the weight of your master node in the consensus, the previously made transaction should be invalidated first.
For this, use the srv_stake invalidate command from the previous section.
After that, a new transaction which locks the mCELL should be made. For this, use the srv_stake delegate command from Part 2 Section 14 of this guide.
Newly received transaction hash must be sent to Cellframe team to get a validator role in the network for your node.
If at any point during the setting up process you need help or clarification of this guide, please contact the team via the Cellframe Support group on Telegram.
To secure your master node, the following data should be saved:
With this data, your master node can be restored on another machine in case anything happens to the current one.
Yes, wallet file can be deleted. It is not necessary for the functioning of the master node.
The file is located in the /opt/cellframe-node/var/lib/wallet/ folder.
First, go to the folder where the wallet file is located
cd /opt/cellframe-node/var/lib/wallet/
To delete it, use the command:
rm <wallet_name>.dwallet
We recommend going through the instructions one more time to ensure that all the steps were executed correctly.
Special attention should be paid to changes in configuration files as well as published node information.