Joining the IDChain Network

Building on Ubuntu

$ sudo snap install go --classic
$ sudo apt-get install -y build-essential
$ git clone https://github.com/BrightID/IDChain.git
$ cd IDChain
$ make all
$ echo "export PATH=$PATH:$PWD/build/bin" >> ~/.profile
$ source ~/.profile

The above routine tested with go1.14.2 installed by snap. If you have older version of go (you can check by go version), first remove that using sudo rm /usr/bin/go and then use snap as described to install latest version of go.

Running a Node

❕The machine running geth should have at least 4GB of RAM and a swap file equal to the size of the RAM.

❕Syncing for the first time may require 8GB RAM.

$ cd ~
$ mkdir node
$ cd node
# Initializing the node by genesis file
$ wget https://idchain.one/files/idchain-genesis.json
$ geth --datadir . init idchain-genesis.json
# Setting static peers
$ wget https://idchain.one/files/static-nodes.json
# Running the node
$ geth --datadir . --networkid 74

The node folder will play as datadir for geth and can be anywhere, but it should not be inside IDChain that we created and built geth in previous step.

Adding a Validator

Proposing New Validator to Network

To join the network as validator, half of the current validators should use clique api to propose the new validator to the network.

$ cd ~/node
$ geth attach geth.ipc
Welcome to the Geth JavaScript console!

> clique.propose("0x...", true)

After the proposal approved, the new validator address should be appeared in the sealersActivity in response of clique.status().

> clique.status()
{
  inturnPercent: 66.6666,
  numBlocks: 64,
  sealerActivity: {
    VALIDATOR1_ADDRESS: 32,
    VALIDATOR2_ADDRESS: 32,
    NEW_VALIDATOR1_ADDRESS: 0
  }
}

Joining the Network as Validator

To join the network as validator, the new validator should import the private key of the address proposed to network in previous step into geth and run the node in mining mode.

$ cd ~
$ mkdir node
$ cd node
# Initializing the node by genesis file
$ wget https://idchain.one/files/idchain-genesis.json
$ geth --datadir . init idchain-genesis.json
# Setting static peers
$ wget https://idchain.one/files/static-nodes.json
# importing the address proposed as validator to network
$ echo "YOUR PRIVATE KEY" > key.priv
$ geth account import --datadir . key.priv
The new account will be encrypted with a passphrase.
Please enter a passphrase now.
Passphrase:
Repeat Passphrase:
Address: {...}
$ rm key.priv
# Creating password file to unlock account using that
$ echo "YOUR PASSPHRASE" > password.txt
$ geth --datadir . --syncmode full --port 30329 --networkid 74 --miner.gasprice 10000000000 --unlock "YOUR ADDRESS" --password password.txt --mine --rpc --rpcapi 'eth,miner,clique,debug' --allow-insecure-unlock

Running Deadlock Resolver

Clique algorithm has a known deadlock issue where all the validators are waiting for each other and chain stop creating new blocks. This issue can be resolved using a simple script that monitor the node and if chain stopped, use debug.setHead to return the node state to n/2+1 blocks ago where n is the number of validators. The only disadvantage of using such approach to resolve the deadlock is that it increases the number of blocks required to wait for finality from n/2+1 to n/2+2. Validators should follow these instructions to run deadlock resolver script as a service beside their idchain node.

Adding the New Validator Address to Static Peers List

It's a good practice to add enode address for all validators to static-nodes.json file hosted on https://idchain.one/files/static-nodes.json to enable decentralized access to all peers for everyone that want to join the network. The new validator can find its node id by:

$ cd ~/node
$ bootnode -nodekey ./geth/nodekey -writeaddress

• The format for enode address that should be added to static-nodes.json is enode://NODE_ID@ip:port.
• The standard port for IDChain nodes will be 30329.
• The new validator should configure the firewall on its server to open port 30329 to enable others to connect its node.