## How to configure Cellframe master node - [[Master Node Manual Setup#Part 1. Preliminary stage|Part 1. Preliminary stage]] - [[Master Node Manual Setup#Part 2. Instructions for setting up the master node|Part 2. Instructions for setting up the master node]] - [[Master Node Manual Setup#Part 3. Interacting with the master node|Part 3. Interacting with the master node]] - [[Master Node Manual Setup#Part 4. Additional information|Part 4. Additional information]] ### Part 1. Preliminary stage What is needed to set up a master node?** - A machine that will stay running 24/7 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. - Linux OS or MacOS. 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. - A public IP address. 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. - IPv4 protocol. The option to use an IP address with IPv6 protocol will be implemented in the future. - Your Backbone wallet balance must have: - at least 10000 $CELL ready for staking or - at least 10 mCELL (received for prior stakes in total of at least 10000 $CELL) ### Part 2. Instructions for setting up the master node #### General notes 1. 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. 2. 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: ```bash sudo -i ``` In MacOS, it can be done with similar command: ```bash sudo -s ``` All the commands presented in this instruction imply that the `root` user is being used. #### 1. Download and install the cellframe-node Linux build: [https://pub.cellframe.net/linux/cellframe-node/master/cellframe-node-5.2-506-updtr-amd64.deb](https://pub.cellframe.net/linux/cellframe-node/master/cellframe-node-5.2-506-updtr-amd64.deb) Linux build for devices based on ARM architecture: [https://pub.cellframe.net/linux/cellframe-node/master/cellframe-node-5.2-506-arm64.deb](https://pub.cellframe.net/linux/cellframe-node/master/cellframe-node-5.2-506-arm64.deb) MacOS build: [https://pub.cellframe.net/macos/cellframe-node/master/cellframe-node_5.2.506_amd64.pkg](https://pub.cellframe.net/macos/cellframe-node/master/cellframe-node_5.2.506_amd64.pkg) Command for downloading files using the terminal: ```none wget <link> ``` Command to install: ```none apt install ./<file_name> ``` #### 2. Initial cellframe-node configuration You will be asked a few questions about the cellframe node configuration. Below are the recommended answers. - Auto online - True - Debug mode - False - Accept connections - True - Server address - 0.0.0.0 - Server port - 8079 - Notify server address - 127.0.0.1 - Notify server port - 8080 - Backbone: Enable network - True - Backbone: Node role - master - KelVPN: Enable network - True - KelVPN: Node role - full - Riemann: Enable network - False - SubZero: Enable network - False - Python plugins - False If a mistake was made in initial configuration, it can be changed with the command: ```bash dpkg-reconfigure cellframe-node ``` Configuration files are located at: `/opt/cellframe-node/etc/cellframe-node.cfg` `/opt/cellframe-node/etc/network/Backbone.cfg` #### 3. Checking the permissions to run the cellframe-node execution files 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. - Change directory to `/opt/celframe-node/bin`: ```bash cd /opt/cellframe-node/bin ``` - Use the command to show detailed information about files in the directory: ```bash ls -la ``` - The result of the command execution will be similar to this: ```bash 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: - Grant execution rights to `cellframe-node-tool`: ```bash chmod +x /opt/cellframe-node/bin/cellframe-node-tool ``` After that, the last symbol will change to `x`: ```bash -rwxrwxr-x 1 root root 3522760 Jul 13 10:23 cellframe-node-tool ``` #### 4. Creating the certificate for signing blocks - The certificate can be created with the command: ```bash 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. #### 5. Viewing the certificate hash 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: ```bash cellframe-node-tool cert pkey show <backbone.cert_name> ``` The created certificate is located in the following folder: `/opt/cellframe-node/var/lib/ca` #### 6. Creation or restoration of a wallet Command to create a new wallet: ```bash 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: - begins with `0x` - minimum length of 4 characters - valid characters: 0-9, a-f, A-F. If 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: - take your seed phrase - join all 24 words together in one unit of text without spaces between words - add a password to the end of the text if your wallet is protected - generate a hash from the resulting text using `sha256` - use the generated hash with `-restore` parameter after the `0x` prefix You 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: ```bash cellframe-node-cli wallet new -w <wallet_name> -sign sig_dil -restore <hash> -force ``` Command to restore a wallet with password: ```bash 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: ```bash 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: ```bash cellframe-node-cli wallet info -net Backbone -w <wallet_name> ``` #### 7. Find out the address of the node on the Backbone network Use the following command to check node status in the network and find its address: ```bash 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. #### 8. Making changes to the Backbone network configuration file The configuration file is located at: ```bash /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. ```bash nano /opt/cellframe-node/etc/network/Backbone.cfg ``` In this file, changes should be made in two sections. - Find the `[general]` section and add the following lines: ```bash node_addr_type=static node-addr=XXXX::XXXX::XXXX::XXXX ``` For the node address a value from the previous step should be used. - Find the `[esbocs]` section and make the necessary changes to match the example below: ```bash [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`. #### 9. Making changes to the node configuration file The configuration file is located at: ```bash /opt/cellframe-node/etc/cellframe-node.cfg ``` To edit it, use a `nano` editor: ```bash 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: ```bash [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`. #### 10. Restarting the node In order for the made changes to apply, the node must be restarted. To do this, use the following commands: ```bash service cellframe-node stop service cellframe-node start ``` To check that the node is running, you can use the command: ```bash systemctl status cellframe-node.service ``` The expected result: ```bash ● 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 ``` #### 11. Creating an order for the validator fee 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: ```bash 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` #### 12. Publishing your node to the public list In this step, you are going to add the information about your node to the network. Command to publish your node: ```bash cellframe-node-cli node add -net Backbone ``` Expected result after successful addition: ```bash 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: ```bash cellframe-node-cli node dump -net Backbone #Expected result: In the obtained list of published nodes in the network, your node is present. ``` #### 13. Required balance 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. #### 14. Locking mCELL Creating a transaction that locks mCELL and delegates the certificate you created: ```bash 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. #### 15. Requesting to become a master node 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: - via the administrator in the [Cellframe Support group](https://t.me/cellframetechsupport); - via sending an email to [email protected]; - via this [Feedback form](https://cellframe.net/feedback-form/) on the [Cellframe website](https://cellframe.net/). If using the [Feedback form](https://cellframe.net/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. #### 16. Restarting the node After receiving approval from the Cellframe team, the node needs to be restarted. ```bash service cellframe-node stop service cellframe-node start ``` To check that the node is running, you can use the command: ```bash systemctl status cellframe-node.service ``` The expected result: ```bash ● 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! #### 17. Sending anonymous diagnostic data to the Cellframe team 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. - Go to the `/opt/cellframe-node/etc/` directory: ```bash cd /opt/cellframe-node/etc/ ``` - Create the `diagdata.json` file: ```bash touch diagdata.json ``` - Open it with the `nano` editor: ```bash nano diagdata.json ``` - Add the following: ```bash {"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`. ### Part 3. Interacting with the master node #### 1. How the auto collection of the earnings works `set_collect_fee` parameter is the threshold value for collecting earned $CELL. If it is reached or exceeded, node will automatically create a transaction to collect the earnings. The auto collect status of your masternode can be checked with the following command: ```bash cellframe-node-cli block autocollect status -net Backbone -chain main ``` The result of the command execution will be similar to this: ```bash Autocollect tables content for: === Fees === 0x2671980FC80BD0A4F2D55F5C11795953826BB47EDE081102BBF9A1279B79ACB3 0.05 0xA8B7889FCACF39D302C2D399E8CEC70A44BECC4CA965E9948A5FB588890E9631 0.05 0x662DF0DD3E3997F7753EF4816671631F1D5E22B7E909166F7B206E32B1CDDB53 1.0 Total prepared value: 1.1 CELL === Rewards === 0x312682BCF6F0861D76EB3FEDE20A0615A12E1DFCFABF2FF70770EFD1D344EA41 2.5 0x7C1879582505248736A80B3539066B496A96E336D82F790D5D1C34AE411BD1CC 3.5 0xAF1C2800173FF5BE119BB6C374EFEB0C0D52B721839D4A7EA87286BA8A06E9B4 1.2 Total prepared value: 7.2 CELL ``` It consists of two lists. - The first is a list of blocks that your node signed first. From these blocks, you have the right to collect fees for transactions that are included in them. Please note that it is also possible that the blocks contain transactions that do not imply payment of a fee. For example, such transactions are harvests. - The second one is a list of blocks that your masternode took part in signing. Despite the fact that your signature may not be in the first place, you are also entitled to a reward from such blocks. Its size depends on the time interval between the current and previous block, as well as the location of your key in the list. As soon as `Total prepared value` reaches or exceeds the `set_collect_fee` value, a transaction will be created automatically. **Note:** Please note that **transaction fees** and **block signing rewards** are two different types of rewards. Despite the fact that one parameter is used to determine the threshold for the auto-collection of both of them, the transaction is created only after one of them reaches the specified value and only to collect this type of the reward. #### 2. Manual collection of the transaction fees and block signing rewards **Note**: Manual collection of the fees and/or rewards is not mandatory, since an automatic collection mechanism is implemented. The transaction to collect the earnings will be formed when the required number of signed blocks accumulates to obtain the previously specified `set_collect_fee` value in the `Backbone.cfg` file. If you have the `set_collect_fee` parameter, then you can skip this paragraph. The owners of the master node have 2 sources of income - fees from transactions on the network and rewards for signing blocks. - The command to view the basic reward for signing a block on the network: ```bash cellframe-node-cli block reward show -net Backbone -chain main ``` - The command to view the list of blocks from which it is possible to withdraw the fee: ```bash cellframe-node-cli block list first_signed -net Backbone -chain main -cert <backbone.cert_name> -unspent ``` The available fee for withdrawal from a block depends on how many transactions got into this block and what amount of fee was paid for each of them. - The command to view the list of blocks from which it is possible to withdraw the reward for signing blocks: ```bash cellframe-node-cli block list signed -net Backbone -chain main -cert <backbone.cert_name> -unspent ``` The block signature reward is calculated based on the value shown by the command above. In addition, it takes into account the time when the block signed by your master node was created and the time of the previous block, as well as where your delegated key is located in the list of those who signed it. - The command to collect the fee (the hashes are taken from the command `cellframe-node-cli block list first_signed`): ```bash 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 ``` - The command to collect rewards for signing blocks (the hashes are taken from the command `cellframe-node-cli block list signed`): ```bash cellframe-node-cli block reward 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 the earnings, block hashes must be separated by commas without spaces. When collecting the earnings, a transaction is created, which also pays the validator's fee and the network fee. Therefore, the greater the number of hashes is used, the more profitable the result will be. #### 3. Moving the master node to another machine 1. Transferring the certificate to a new machine that master node is using to sign the blocks with. ```bash # Certificate is located at: /opt/cellframe-node/var/lib/ca ``` 2. Making sure that the restoration hash for your wallet is saved and does not contain any errors. It is also possible to manually move the wallet. ```bash # Wallet file is located at: /opt/cellframe-node/var/lib/wallet ``` Copy 3. 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. **Note**: It is no longer needed to manually update the entry to the network node list. Once the cellframe-node process starts on the new device, IP address will automatically update. To check that the IP address was updated, use the following command: ```bash cellframe-node-cli node dump -net Backbone ``` #### 4. Returning locked mCELL Before creating a transaction to return mCELL, you need to inform the Cellframe team that you plan to return the tokens. As long as the masternode is active on the network, the return of tokens is not possible. To do this, we need to revoke your certificate in advance. After the certificate is revoked, the tokens can be returned by the command: ```bash cellframe-node-cli srv_stake invalidate -net Backbone -tx <transaction hash> -w <wallet name> -fee 0.05e+18 ``` As a result, the m-tokens will be returned to the specified wallet. 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: ```bash 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. ```bash Pkey hash: <hash> Stake value: <value> Tx hash: <hash> Node addr: <address> ``` **Note**: if you do not have the transaction hash recorded, we recommend saving it before informing you of your intention to return the mCell. After your certificate becomes inactive, the node information disappears from the list accessible by the `srv_stake list keys` command. #### 5. Increasing the amount of locked mCELL If you would like to increase the amount of locked mCELL and increase the weight of your master node in the consensus, the previously locked tokens should be returned first. For this, use the steps 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. ### Part 4. Additional information #### 1. Multiple master nodes on one device Cellframe node allows you to get the master role in multiple networks on the same device. To do this, you need: - the node must have the appropriate networks (for example, Backbone and KelVPN); - the wallet balance must have the required number of m-tokens to get the master role in each of these networks; Our recommendations: - create a separate certificate for block signing for each of the networks; - one wallet can be used to collect fees in different networks; Take note that: - the address of your node in different networks will be different; - each network has its own public list of nodes, so you need to add a node to each of them; - in each network, you need to create an order for the master node to work. The process of configuring the masternode in different networks is the same. However, be careful when executing all of the commands and specify the correct names of networks and configuration files when configuring!