DevNews: Running a Full Node and Becoming a Validator

In this article, we will be covering the more technical aspects of interacting with Mainchain, including how to run a full node, and become a Validator on the network. The guide applies to TestNet, but will be equally valid for MainNet upon its imminent launch and will be updated to reflect this in due course.

This guide assumes the Full Node will be installed on Linux. We recommend Ubuntu 18.04 LTS or above, or CentOS 7

Note: An article covering installation on Cloud services (AWS, Google Cloud and Azure) will be published in due course.

Prerequisites

Go 1.13+ is required to install the Mainchain binaries

Install goby following the official docs. Once Go is installed, set your $PATH environment variable, for example:

$ mkdir -p $HOME/go/bin
$ echo "export PATH=$PATH:$(go env GOPATH)/bin">>$HOME/.bash_profile
$ source $HOME/.bash_profile

Git is required to clone the Mainchain repository. jq is also useful. On Ubuntu Linux, this can be installed using apt-get:

$ sudo apt-get install git jq

Or on yum on CentOS:

$ sudo yum install git jq

Note: on CentOS, jq is generally available via EPEL.

Installing the Mainchain binaries

Once Go and Git are installed, clone the latest tagged Mainchain release from https://github.com/unification-com/mainchain/releases and run the make install target — note this should not be cloned in your GOPATH

$ mkdir -p $HOME/src/unification-com
$ cd $HOME/src/unification-com
$ git clone -b [latest-release-tag] https://github.com/unification-com/mainchain
$ cd mainchain
$ make install

Where [latest-release-tag] is the latest version tag, e.g. v1.3.2

The [latest-release-tag] can also be obtained by running:

$ curl --silent "https://api.github.com/repos/unification-com/mainchain/releases/latest" | grep -Po '"tag_name": "\K.*?(?=")'

This will install the two Mainchain binaries und and undcli into your $HOME/go/bin directory.

und is the server/node binary, and undcli is the client side binary used to interact with a Mainchain node.

Verify the installation

Once installed, run the following to verify the binaries installed correctly:

$ und version --long
$ undcli version --long

You should see something similar to:

name: UndMainchain
server_name: und
client_name: undcli
version: 1.3.2
commit: a61c54c06b0381ee5ae515922e605faabb29f060
build_tags: netgo ledger
go: go version go1.13.3 linux/amd64

Initialising a Full Node

Once installed, you will need to initialise the config files for your new node:

$ und init [your_node_tag]

[your_node_tag] can be any identifier you like, but is limited to ASCII characters.

Example:

$ und init myAwesomeUNDNode

Once initialised, you can edit your node’s configuration in $HOME/.und_mainchain/config/config.toml

Genesis

The latest TestNet genesis can always be found at https://github.com/unification-com/testnet/latest

To download the latest genesis.json run:

$ curl https://raw.githubusercontent.com/unification-com/testnet/master/latest/genesis.json > $HOME/.und_mainchain/config/genesis.json

Get the current chain ID from genesis. Make a note of the output, it’ll be required in commands later in the guide. Command is all on one line:

$ jq --raw-output '.chain_id' $HOME/.und_mainchain/config/genesis.json

Seed Node Peers

Your node will need to know at least one seed node in order to join the network and begin P2P communication. The latest TestNet seed node information will always be available at https://github.com/unification-com/testnet/blob/master/latest/seed_nodes.md

Open $HOME/.und_mainchain/config/config.toml in a text editor and set the seeds value with a comma separated list of one or more peers from seed_nodes.md

seeds = "SEED1_ID@SEED1_IP_OR_URL:SEED1_PORT, SEED2_ID@SEED2_IP_OR_URL:SEED2_PORT"

Public visibility

If you want your node to be visible to other peers, you can set the external_address value in $HOME/.und_mainchain/config/config.toml:

external_address = "[IP]:[PORT]"

Example:

external_address = "11.22.33.44:26656"

Minimum Gas value

It is good practice to set the minimum-gas-prices value in $HOME/.und_mainchain/config/app.toml , in order to protect your full node from spam transactions. This should be set as a decimal value in nund, and the recommended value is currently 0.025nund to 0.25nund. This means your node will ignore any Txs with a gas price below this value. To do so, open up $HOME/.und_mainchain/config/app.toml in a text editor, and set minimum-gas-prices

minimum-gas-prices = "0.25nund"

Running your Full Node

Now that you have genesis, and some seed nodes, you can run your full node:

$ und start

You should see the node connect to the network and begin downloading the block history.

Note: You may see output similar to the following when you start the node. This is fine, and just caused by the seed node terminating its connection to your node once it has sent data on other peers in the network:

Stopping peer for error                      module=p2p peer="Peer{MConn{3.134.92.80:26656} dcff5de69dcc170b28b6628a1336d420f7eb60c0 out}" err=EOF

Running:

$ undcli status

in a separate terminal window should show that the node is running and connected. Note: you may need to run source $HOME/.bash_profile or source $HOME/.profile in the new terminal window.

By default, any transactions and queries you send using the undcli command will be sent via your local full node.

Becoming a Validator

Now that you have a full node up and running, you may want to become one of our 96 EVs. EVs are responsible for proposing, signing and committing new blocks to the network, and partaking in network Governance. EVs play a vital role in the running of the network.

Wallets and Accounts

The first thing you will need is an account loaded with some UND.

If you don’t have an account yet, you can create one using the following command:

$ undcli keys add [account_name]

Example:

$ undcli keys add my_new_wallet

The result will output your address, public key and mnemonic (keep this safe!). By default, undcli stores keys in your OS’s keyring.

If you have read our accompanying article on How to Stake, Get Rewards and use the UND Web Wallet, you may already have a mnemonic which can be imported into undcli . Note it is better to create a new key for your validator. If you already have a mnemonic and want to import it for use with undcli, you can run the following command to import the account into your undcli wallet:

$ undcli keys add [account_name] --recover

[account_name] can be any alpha-numeric identifier you choose.

Example:

$ undcli keys add my_imported_acc --recover

You will be prompted to choose a password to secure the account, and finally prompted to enter your recovery mnemonic.

You can run the following command to output information, including your wallet address:

$ undcli keys show [account_name]

Example:

$ undcli keys show my_new_wallet

For TestNet, you can obtain Test UND from our TestNet faucet: https://faucet-testnet.unification.io/

Creating a Validator

During your full node initialisation, a Tendermint validator public key was also generated. This public key is required, along with UND for staking in order to create and register your EV on the network. The public key has the prefix undvalconspub, and can be found by running the following command:

$ und tendermint show-validator

IMPORTANT: Before continuing, ensure your full node has fully synced with Mainchain and downloaded all the blocks (this may take a while, so go and make a brew). You can check the current network block height in the TestNet block explorer. For each block your full node syncs, you will see:

I[2020-01-15|11:45:07.782] Executed block module=state height=37285 validTxs=0 invalidTxs=0

When the height is the same as the current network block number, your full node has completed syncing.

To create your EV, you will need to generate, sign and broadcast a transaction to the network which will register your Tendermint validator public key and stake the amount of UND specified (via self-delegation). Run the following command, modifying as required:

undcli tx staking create-validator \
--amount=[stake_in_nund] \
--pubkey=$(und tendermint show-validator) \
--moniker="[your_ev_moniker]" \
--website="[your_website]" \
--identity=[16_digit_keybase.io_id] \
--details="[description]" \
--security-contact="[security_email]" \
--chain-id=[chain_id] \
--commission-rate="0.10" \
--commission-max-rate="0.20" \
--commission-max-change-rate="0.01" \
--min-self-delegation="1" \
--gas="auto" \
--gas-prices="0.25nund" \
--gas-adjustment=1.5 \
--from=[account_name]

Mandatory fields

[stake_in_nund]: the amount in nund you want to delegate to yourself. For example, if you want to stake 1000 UND, enter 1000000000000nund. You can use the built in undcli conversion tool to calculate this: undcli convert 1000 und nund.

IMPORTANT: do not attempt to stake more than you have in your account, and ensure you have enough UND to pay for the transaction fees, and enough left over for future transactions!

[chain_id]: the chain you are creating a validator for. On TestNet, at the time of writing this is UND-Mainchain-TestNet-v3.

[account_name]: the name of the account being used to stake self-delegated UND and sign the transaction — for example, the identifier you entered when running the undcli keys add command earlier to create/import an account.

[your_ev_moniker]: an ASCII moniker which will publicly identify your EV on the network

Optional fields

Ensure you create your validator with as much of the following additional information as you can. It will be publicly visible, and help potential stakers connect with you:

[your_website]: the URL for the site promoting your validation node

[16_digit_keybase.io_id]: Your 16 digit public keybase.io PGP public key ID if you have one

[description]: a brief description of your validator node

[security_email]: Email address for the security contact for your validator node

Commission Rates

Your commission rates can be set using the --commission-rate , --commission-max-change-rate and --commission-max-rate flags.

--commission-rate: The % commission you will earn from delegators’ rewards. Keeping this low can attract more delegators to your node.

--commission-max-rate: The maximum you will ever increase your commission rate to — you cannot raise commission above this value. Again, keeping this low can attract more delegators.

--commission-max-change-rate: The maximum you can change the commission-rate by in any one change request. For example, if your maximum change rate is 0.01, you can only make changes in 0.01 increments, so from 0.10 (10%) to 0.09 (9%).

The values for --commission-max-change-rate and --commission-max-rate flags cannot be changed after the create-validator command has been run.

Finally, the --min-self-delegation flag is the minimum amount of nund you are required to keep self-delegated to your validator, meaning you must always have at least this amount self-delegated to your node.

Example:

undcli tx staking create-validator \
--amount=5000000000nund \
--pubkey=$(und tendermint show-validator) \
--moniker="MyAwesomeEV" \
--website="https://yourvalidatordomain.com" \
--details="Our awesome validator - we're based in Europe" \
--security-contact="someone@yourvalidatordomain.com" \
--chain-id=UND-Mainchain-TestNet-v3 \
--commission-rate="0.10" \
--commission-max-rate="0.20" \
--commission-max-change-rate="0.01" \
--min-self-delegation="1" \
--gas="auto" \
--gas-prices="0.25nund" \
--gas-adjustment=1.5 \
--from=my_new_wallet

Once broadcast, your full node should be able to contribute to the network by proposing, signing and committing new blocks.

Your Validator Operator Address is required for other users to delegate UND to your operator account, and for querying your status. You can find this by running:

$ undcli keys show [account_name] --bech=val

Example:

$ undcli keys show my_new_wallet --bech=val

To see if you have successfully created a validator, run:

$ undcli query staking validator \
$(undcli keys show [account_name] --bech=val -a) \
--chain-id=[chain_id]

Example:

$ undcli query staking validator \
$(undcli keys show my_new_wallet --bech=val -a) \
--chain-id=UND-Mainchain-TestNet-v3

Important

keep your $HOME/.und_mainchain/config/node_key.json and $home/.und_mainchain/config/priv_validator_key.json files safe! These are required for your node to propose and sign blocks. If you ever migrate your node to a different host, you will need these.

Editing your EV Information

You can edit your EV’s public information, and commission rates at any time with undcli:

$ undcli tx staking edit-validator \
--moniker="[your_new_ev_moniker]" \
--website="[your_website]" \
--identity=[16_digit_keybase.io_id] \
--details="[description]" \
--security-contact="[security_email]" \
--chain-id=[chain_id] \
--commission-rate="0.09" \
--gas="auto" \
--gas-prices="0.25nund" \
--gas-adjustment=1.5 \
--from=[account_name]

Example:

$ undcli tx staking edit-validator \
--moniker="I_changed_my_Moniker" \
--website="https://yourvalidatordomain.com" \
--identity=AAAA1111BBBB2222 \
--details="I'm an awesome EV - find out more at my website" \
--security-contact="newcontact@yourvalidatordomain.com" \
--chain-id=UND-Mainchain-TestNet-v3 \
--gas="auto" \
--gas-prices="0.25nund" \
--gas-adjustment=1.5 \
--from=my_new_wallet

Querying your EV information

You can query your EV information by running:

$ undcli query staking validator $(undcli keys show [account_name] --bech=val -a) --chain-id=[chain_id]

Example:

$ undcli query staking validator $(undcli keys show my_new_wallet --bech=val -a) --chain-id=UND-Mainchain-TestNet-v3

Show me the Money!

To view any outstanding rewards accumulated, run:

$ undcli query distribution validator-outstanding-rewards $(undcli keys show [account_name] --bech=val -a) --chain-id=[chain_id]

Example:

$ undcli query distribution validator-outstanding-rewards $(undcli keys show my_new_wallet --bech=val -a) --chain-id=UND-Mainchain-TestNet-v3

To view other addresses that have delegated to you, run:

$ undcli query staking delegations-to $(undcli keys show [account_name] --bech=val -a) --chain-id=[chain_id]

Example:

$ undcli query staking delegations-to $(undcli keys show my_new_wallet --bech=val -a) --chain-id=UND-Mainchain-TestNet-v3

You can withdraw any self-delegation rewards accumulated by sending a withdraw-rewards transaction:

$ undcli tx distribution withdraw-rewards \
$(undcli keys show [account_name] --bech=val -a) \
--from [account_name] \
--commission \
--chain-id=[chain_id] \
--gas="auto" \
--gas-prices="0.25nund" \
--gas-adjustment=1.5

Including the optional --commission flag will also withdraw any validator commission earned from delegations to you, if you have set a commission rate > 0%.

Example:

$ undcli tx distribution withdraw-rewards \
$(undcli keys show my_new_wallet --bech=val -a) \
--from my_new_wallet \
--commission \
--chain-id=UND-Mainchain-TestNet-v3 \
--gas="auto" \
--gas-prices="0.25nund" \
--gas-adjustment=1.5

Downtime and reactivating your node

If your EV node is halted, goes offline, is for some other reason unable to contribute to block production and signing on the network, or double signs blocks, it will be temporarily removed from the active EV pool, placed in an inactive “jailed” mode, and your (and any delegators’) stake will be slashed by a small percentage (this is to encourage high EV uptimes and good behaviour). In order to unjail your node, and once again become an active node, you will need to restart your node using the und start command, wait for the node to catch up to the latest block, and then manually broadcast an unjail transaction to let the network know that your node is back online and ready to produce blocks:

$ undcli tx slashing unjail \
--from=[account_name] \
--chain-id=[chain_id] \
--gas="auto" \
--gas-prices="0.25nund" \
--gas-adjustment=1.5

Example:

$ undcli tx slashing unjail \
--from=my_new_wallet \
--chain-id=UND-Mainchain-TestNet-v3 \
--gas="auto" \
--gas-prices="0.25nund" \
--gas-adjustment=1.5

Finally, use:

$ undcli query distribution --help
$ undcli query staking --help
$ undcli query slashing --help

to display other commands available to you to query your EV data, and

$ und start --help

to view configuration flags available for the und start command.

Web: unification.com
Telegram: https://t.me/unificationfoundation
Twitter: https://twitter.com/UnificationUND
Gitter: https://gitter.im/unification-com

Tech issues can be raised in the Github repo: https://github.com/unification-com/mainchain/issues

As always, feel free to track our overall progress — all of our public repos are available at https://github.com/unification-com

Paul Hodgson, Unification CTO

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store