General
The default configuration for the necessary hosts in the new network consists of three root nodes and three master nodes. The number of these nodes may vary, but changes can be easily made through the parameters described in the configuration files. Currently, all Cellframe networks operate in a hybrid regime based on two consensus mechanisms: the first one is a Proof of Authority (PoA) based on a DAG, and the second one is our enhanced Proof of Stake (PoS) consensus - ESBOCS. So, at least one root node is necessary for blockchain synchronization and for the functioning of the DAG-POA consensus. And at least one master node is required for starting up the very blockchain and work as a validator.
Preparation
Important
In the next example, we will use 2 root and 3 master nodes for setting up the network. A brand new network must have a name. Let it be foobar. Also, there must be main network token specified, let it be BUZ. But while setting up your own network, you should use your unique names.
Let’s name the first chain zerochain and the second one main in a traditional way.
Sequence of preliminary actions
- Set up 5 VPS hosts, preferably in different locations and with different hosting providers. For convenience, it is customary to give standard names to the hosts, indicating their role in the network:
0-root-foobar,1-root-foobar,0-master-foobar,1-master-foobar,2-master-foobar. Update the packages and install additional software that may be needed, such asmidnight commander,htop,gdb. - It is not mandatory, but desirable for convenience, to assign DNS names following the same principle, for example, 0.root.foobar.cellframe.net.
- Download and install the required version of a cellframe node on each host.
- Stop the node process on all hosts. To update the system variablePATH and be able to run the node binary files from any location, restart the SSH session.
Command for stop the process:
systemctl stop cellframe-node- On each host create pairs of private and public certificates with corresponding names. For convenience, the certificate names should match the host names. It is also preferable to give the private certificate a
pvtsuffix.
In our case public certs would be:
foobar.root.0
foobar.root.1
foobar.master.0
foobar.master.1
foobar.master.2
And the private are:
foobar.root.pvt.0
foobar.root.pvt.1
foobar.master.pvt.0
foobar.master.pvt.1
foobar.master.pvt.2
- Here is an example of the necessary commands to execute on the host with the name
0-root-foobar:
cellframe-node-tool cert create foobar.root.pvt.0 sig_dilcellframe-node-tool cert create_cert_pkey foobar.root.pvt.0 foobar.root.0As a result, there will be created two files foobar.root.pvt.0.dcert (private certificate) and foobar.root.0.dcert (public certificate) in the catalog /opt/cellframe-node/var/lib/ca.
Important
The
.dcertextension is never specified either in the config or in the node commands as well.
- Copy all the public certificates from the all nodes into the catalog
/opt/cellframe-node/share/caon the every node.
Configuration settings
After the cellframe-node installation, you will get a pack of configuration files for the networks in the opt/cellframe-node/share/configs.
You need four configuration files:
cellframe-node.cfgnetwork_name.cfgfrom thenetworkfolder (for example,Backbone.cfg)chain-0.cfgandmain.cfgwhich you can acquire after thecellframe-nodeprocess started in theopt/cellframe-node/etc/network/network_name
You have to use them as templates for your network configuration. But they must be seriously modified.
Get cellframe-node.cfg and one of the network configs.
For example, take Backbone.cfg, rename it using your network name and use it as a scratch.
On the all hosts where your network will be set up, make two copies of configuration files, one is for root nodes, the second one is for master nodes.
Important
Remember, most of the parameters are the same on all hosts, but some of them are different between root and master nodes, and some are different between each other. Below you can find hints of which parameter must be changed individually.
Let’s make some necessary changes in the configuration files:
General config
Cellframe Node General Config is located in /opt/cellframe-node/etc/cellframe-node.cfg.
Config consists of sections and their parameters with the following structure:
[section]
key=value (string/boolean/array/integer)
#commentaries in the configThe seed mode must be activated on the all root and master nodes during network starting:
[general]
# General debug mode
debug-mode=true
# seed mode. WARNING. Used true only when you start the new network
seed-mode=true For convenience, you should specify the IP address of the every master and root node:
[server]
# By default you don't need to open you to the world
enabled=true
news-url_enabled=false
bugreport-url_enabled=false
listen-address=[0.0.0.0:8079]
# External IPv4 address
ext-address=8.9.10.11 In the ext-address field specify a real IP address of the node (the IP address is different on all hosts, this parameter is individual)
Also, you have to enable mempool auto processing on the master nodes.
# Mempool
[mempool]
# Automatically false, for enabling need role master or higher
auto-proc=true Network config
Cellframe Node Network Config is located in the /opt/cellframe-node/etc/network/ catalog with the following name - NetName.cfg (in our case foobar.cfg). Here Cellframe Node Chain Config is also located.
For the next stage, you have to get all 5 node addresses. You can obtain them by starting cellframe-node process and using net get status command.
Command for start the process:
systemctl start cellframe-nodeCommand:
cellframe-node-cli net get status -net Backbone Instead of Backbone you can use any active network, list of active networks can be obtained by using NET LIST command.
Response:
status:
net: Backbone
current_addr: ABCD::0000::0000::0000 (this is the node address)
links:
active: 1
total: 1
sync_status:
sync_datums: 20
total_datums: 20
percent: 100.000
states:
current: NET_STATE_ONLINE
target: NET_STATE_ONLINEThen, make some changes in the [general] section of the network config:
[general]
id=0x000000000000ffff
name=foobar
native-ticker=BUZ
gdb-groups-prefix=foobar
bridged-network-ids = [] id - specify a new network ID which is unlike from other existing (for example, 0x2490100301000000)
name - a new name of the network
native-ticker - a name of the native token for your network
gdb-groups-prefix - prefix name of the GDB tables, use the name of your network
bridged-network-ids - here you can specify ID’s of the networks for bridge connections
# Possible values: light, full, archive, master, root
node-role=root Specify root for the root nodes and master for the master ones.
seed-nodes-hosts=[] Seed nodes are used for starting the network, it’s like an entering point, only root nodes can serve for this purpose (here you must specify your seed nodes IP’s or domain names and port).
Example: [0.root.scorpion.cellframe.net:8079] or [109.202.1.195:8079].
authorized-nodes-addrs=[] Authorized nodes have special permissions in the GDB groups, and some privileges in the network, they can write to nodelist or zerochain mempool, delete any orders and clean mempool (here you must specify privileged nodes). Here specify their node addresses if you want. Example - [FE39::A741::BCD1::1920, FR87::A659::BCD1::2140].
#permanent-nodes-addrs=[]It is optional parameter which is useful when you want some nodes to be connected with your node all the time, also your node connects to them first. Example - [FE39::A741::BCD1::1920, FR87::A659::BCD1::2140].
links-required= 3 Here you must specify required number of links for node operation, it works the next way: if you specified, for example, 2 permanent node links, while the required number of links is 3, so the balancer will provide 1 additional link with another node.
#permanent-nodes-hosts= [ip/domain names:port] Here you can specify hosts of permanent nodes for direct connection, if you want to synchronize firstly with exactly these nodes.
Then, let’s specify the name of the certificate for the root nodes. This parameter is individual, after replacing original configuration files, paste the name of the certificate in every config separately.
On the root node 0:
[dag-poa]
events-sign-cert=foobar.root.pvt.0On the root node 1:
[dag-poa]
events-sign-cert=foobar.root.pvt.1After, do the same thing for the master nodes (also, specify additional parameters for ESBOCS Consensus).
On the master node 0:
[esbocs]
blocks-sign-cert=foobar.master.pvt.0On the master node 1:
[esbocs]
blocks-sign-cert=foobar.master.pvt.1On the master node 2:
[esbocs]
blocks-sign-cert=foobar.master.pvt.2Chain configs
Finally, make changes in the Cellframe Node Chain Config for both zerochain chain-0.cfg and mainchain main.cfg. In the section [files] change the name of the catalog, where chains will be stored:
[files]
storage-dir=../../../var/lib/network/foobar/zerochain/The path must contain folder with your the name of your network:
storage-dir=../../../var/lib/network/your_network_name/zerochain/
Chain-0
This changes are needed to make on the both root and master nodes.
In the [dag-poa] section of the chain-0.cfg file change name in the certificate’s prefix:
[dag-poa]
auth-certs-prefix=foobar.root
auth-certs-number=2
auth-certs-number-verify=1Change auth-certs-prefix value like this network_name.root.
Parameter auth-certs-number shows how many root certs will be in use in the network. In other words, how many certs will have the prefix foobar.root.
Main
Do the same thing in the [esbocs] section of the main.cfg file only for the master nodes. Also, specify addresses of the validators nodes (this role belongs to master nodes), without them a consensus won’t start:
[esbocs]
min-validators-count=2
#poa-mode=true
auth-certs-prefix=foobar.master
validators-addrs=[FFFF::1234::0000::0000,FFFF::1234::0000::0001,FFFF::1234::0000::0002]
new-round-delay=45Parameter min-validators-count shows how many validators are required to pass the consensus.
Change auth-certs-prefix value like this `network_name.master.
Paste all master node addresses who will play a validator role in your network in the validators-addrs parameter.
End of preparation
We have already prepared two sets of configuration files, the one is for the root nodes, and the second is for the master nodes. Then, replace default config files of the corresponding nodes in the /opt/cellframe-node/etc/ catalog with the newly created config files.
Start the nodes:
systemctl start cellframe-nodeUse Node Command - NODE ADD to add node addresses into the node list.
Syntax:
cellframe-node-cli node add -net <name of the network>Example:
cellframe-node-cli node add -net foobar After this, you can start the cellframe-node process on the all hosts, and do some checkages:
- You can make sure that a new foobar network is set up, and the nodes “see” each other by using commands NET LIST, NET GET STATUS and NODE DUMP.
- Make sure that DAG-POA consensus has started on the root nodes by reading log messages.
- Also, you have to check the work of the ESBOCS consensus on the master nodes.
Master nodes (validators) won’t work without commissions specified. You have to use SRV_STAKE ORDER CREATE command for the every master node.
Syntax:
srv_stake order create -net <net_name> -value <value> -cert <priv_cert_name> Example:
cellframe-node-cli srv_stake order create -net foobar -value 0.05e+18 -cert foobar.master.pvt.0After this, restart the nodes:
systemctl stop cellframe-nodeand
systemctl start cellframe-nodeDAG-POA consensus starting
In the current versions of the Cellframe networks, interaction with global blockchain ecosystems such as ETH and BSC is implemented via the bridge. The description of the emission center’s operation and configuration is not included in the scope of this guide, but it is necessary to consider its functionality.
For security requirements, emissions can only be performed after being signed by the same certificates used during token declaration (Node Command - TOKEN DECL). Therefore, we need certificates for the bridge nodes, which can be created on any of the root nodes and then transferred to the respective bridge nodes during the emission center setup.
- Create 3 certificates (the number of certificates may vary depending on emission center requirements, so there is a corresponding command - Node Command - TOKEN UPDATE, which can update tokens, and in particular, sign it with additional certificates).
cellframe-node-tool cert create foobar.bridge.pvt.0 sig_dilcellframe-node-tool cert create foobar.bridge.pvt.1 sig_dilcellframe-node-tool cert create foobar.bridge.pvt.2 sig_dil- Declare the token via the TOKEN DECL command.
Example (parameters are divided by line breaks for convenient):
cellframe-node-cli token_decl
-net foobar
-chain zerochain
-token BUZ
-decimals 18
-signs_total 3
-signs_emission 2
-certs foobar.bridge.pvt.0,foobar.bridge.pvt.1,foobar.bridge.pvt.2
-type CF20
-total_supply 0- In case not all bridge certificates were used to sign token declaration datum, you can use the following command for signing datum by additional bridge certificates.
Example (parameters are divided by line breaks for convenient):
cellframe-node-cli token_decl_sign
-net foobar (name of the net)
-chain main (chain name)
-datum 0xFE3C0D5CEBAB54957121C01C12017164E516D60709B6BE10BC7EE98758BF4429 (hash of the declaration)
-certs foobar.bridge.pvt3 (enter required certificates)After this, hash of the declaration datum will change.
- Let’s process the token declaration datum that is in the mempool of the zerochain using the Node Command - MEMPOOL PROC.
Example (parameters are divided by line breaks for convenient):
cellframe-node-cli mempool proc
-net foobar (name of the net)
-chain zerochain (chain name)
-datum 0x990A5F50723B21BCEDFCB40EF09B9720AEAC2A4C92ADDCA5E778B53F569E186F (use changed hash)- After that, this datum will undergo consensus rounds, and eventually, the first event will be formed, which we must add to the zerochain configuration file as the genesis event. You can see the hash of this event in the logs or after some time following the execution of the declaration command using Node Command - DAG EVENT LIST with
-from eventsparameter. - Stop the cellframe-node process on the root nodes and make changes to the zerochain configuration file in the [dag] section.
[dag]
is-single-line=true
is-celled=false
is-add-directly=false
datum-add-hashes-count=1
is-static-genesis-event=true "uncomment this string if it's commented"
static-genesis-event=
0x990A5F50723B21BCEDFCB40EF09B9720AEAC2A4C92ADDCA5E778B53F569E186F "here you must input previously given hash"- After that, you can start the node process on all hosts. Node synchronization will be almost instantaneous, and you can verify that the first event is presented everywhere using the Node Command - DAG EVENT LIST.
ESBOCS consensus starting
Let’s execute token emission (Node Command - TOKEN EMIT) in the zerochain, and create basic transaction.
- Create the wallet on the node with the bridge certificates:
cellframe-node-cli wallet new -w main_walletcellframe-node-cli wallet info -w main_wallet -net foobar- Make some changes in the master nodes network
cellframe-node.cfgconfiguration file.
[esbocs]
collecting-level=10.0
fee-addr=myaddr collecting-level - when specified sum (in native token) is accumulated, validator’s wallet automatically collects it
fee-addr - the name of the wallet, which will be used for collecting fees
- Execute emission using Node Command - TOKEN EMIT:
Example (parameters are divided by line breaks for convenient):
cellframe-node-cli token_emit
-net foobar
-chain_emission zerochain
-no_base_tx
-token BUZ
-certs foobar.bridge.pvt.0,foobar.bridge.pvt.1,foobar.bridge.pvt.2
-emission_value
10000000000000000000000000000000000000000000000000000000000000
-addr
jrmnGqeeds4Dp67AaNgMRugT7deFuJeJsxwAnWnMGSixDnjQJt93WFja3HmXciJzDWnnKrHXmoT7jJ2q8RJ1ciTpvVgDN9D9Cf8vsrih- Let’s process the emission datum in the zerochain’s mempool using the Node Command - MEMPOOL PROC. Within a several minutes (the time of waiting depends on round duration, specified in the configuration), we should already see the emission event in the chain.
- Hash of the emission appears in the terminal after requesting the TOKEN EMIT command.
- After that, we can perform a basic transaction in the mainchain, specifying the transaction fee, which should be not less than the one specified in the network configuration, and the name of the certificate that will be used to sign the transaction.
Example (parameters are divided by line breaks for convenient):
cellframe-node-cli tx_create
-net foobar
-chain main
-emission_chain zerochain
-from_emission
0xA78BB75079DEC48FF67370DD2E8B47F3D69DDA26B4751C5D705B95E13F8A522A
-token BUZ
-to_addr
jrmnGqeeds4Dp67AaNgMRugT7deFuJeJsxwAnWnMGSixDnjQJt93WFja3HmXciJzDWnnKrHXmoT7jJ2q8RJ1ciTpvVgDN9D9Cf8vsrih
-value 10000000000000000000000000000000000000000000000000000000000000
-fee 0.05e+18
-certs foobar.root.pvt.0- Almost instantly, there will be generated the first block in the mainchain, which can be checked using Node Command - BLOCK LIST. Also, you can see how tokens come to the node wallet using Node Command - WALLET INFO.
Eventually, a new network has started.