Skip to content

Latest commit

 

History

History
371 lines (270 loc) · 11.5 KB

validator.md

File metadata and controls

371 lines (270 loc) · 11.5 KB

Validator Manual

Note: This manual assumes familiarity with Unix command line and blockchain validator nodes. Prior experience with Cosmos SDK and Ethereum transactions will be helpful.

Table of Contents

If you only want to run a standby unbonded node to sync the blocks and query sidechain information, stop after run validator with systemd.

Prepare machine and install dependencies

  1. Prepare a Linux machine with a minimum of 16GB RAM, at least 2 cores and at least 100GB of disk space. We assume Ubuntu in this manual but most Linux distros should work.

  2. Install go (version 1.14+), gcc, make, git and libleveldb-dev.

  3. Set $GOBIN and add $GOBIN to $PATH. Edit $HOME/.profile and add:

export GOBIN=$HOME/go/bin; export GOPATH=$HOME/go; export PATH=$PATH:$GOBIN

to the end, then:

source $HOME/.profile

Setup binary, config and accounts

  1. From the /home/ubuntu directory, clone the sgn repository, then install the sgnd, sgncli and sgnops binaries:
git clone /~https://github.com/celer-network/sgn
cd sgn
git checkout master # Use master for latest stable version
WITH_CLEVELDB=yes make install-all
cd ..
  1. From the /home/ubuntu directory, clone the sgn-networks repository:
git clone /~https://github.com/celer-network/sgn-networks
cd sgn-networks
git checkout master
cd <chain-id>
  1. Copy the config files and initialize the validator node:
mkdir -p $HOME/.sgncli/config
cp sgn.toml $HOME/.sgncli/config
sgnd init <validator-name> --chain-id <chain-id>
cp genesis.json config.toml $HOME/.sgnd/config
  1. Initialize common Cosmos SDK CLI configs, which will be saved to $HOME/.sgncli/config/config.toml:
sgncli config trust-node true; sgncli config indent true; sgncli config output json

  1. Fill out the moniker field in $HOME/.sgnd/config/config.toml with the name of the validator. Fill out the external_address field with <public-ip:26656>.

  2. Get the validator public key:

sgnd tendermint show-validator

Make a note of the output.

  1. Add an SGN validator account key:
sgncli keys add <key-name> --keyring-backend=file

Repeat to create multiple transactors for the gateway. You can use <validator_name>_operator to name your validator account and <validator_name_transactor0>, <validator_name_transactor1>, etc. to name your transactor accounts. Use the same passphrase as the validator account for all accounts.

To get the list of accounts, run:

sgncli keys list --keyring-backend=file

  1. Prepare an Ethereum gateway URL. You can use services like Infura, Alchemy or run your own node.

  2. Prepare an Ethereum keystore JSON file for the validator, eg.:

geth account new --lightkdf --keystore <path-to-keystore-folder>

Save it as $HOME/.sgncli/eth_ks.json.

  1. For testnet, obtain some Ropsten ETH from places like the MetaMask faucet. Buy Ropsten mock CELR tokens on the Ropsten Uniswap. If there is not enough CELR in the Uniswap pool, join our Discord server and ping us.

For mainnet, currently we have not opened validator spots. Please stay tuned for more information.

  1. Send ETH and CELR to the validator ETH address. Make sure it has enough CELR for self-staking and a few ETH for gas.

  2. Fill in the placeholders in $HOME/.sgncli/config/sgn.toml.

    Field Description
    ETHEREUM_GATEWAY_URL The Ethereum gateway URL obtained from step 8
    KEYSTORE_PATH The path to the keystore file in step 9
    KEYSTORE_PASSPHRASE The passphrase to the keystore
    VALIDATOR_ACCOUNT_ADDRESS The sgn-prefixed address obtained in step 7
    TRANSACTOR_PASSPHRASE The passphrase you typed in step 7
    VALIDATOR_PUBKEY The validator public key obtained in step 6
    TRANSACTOR_ADDRESS If planning to run gateway, fill in one or multiple transactor accounts obtained in step 7. Otherwise, leave it as an empty array

Run validator with systemd

We recommend using systemd to run your validator. Feel free to experiment with other setups on your own.

  1. Prepare the sgnd system service:
sudo mkdir -p /var/log/sgnd
sudo touch /var/log/sgnd/tendermint.log
sudo touch /var/log/sgnd/app.log
sudo touch /etc/systemd/system/sgnd.service

Add the following to /etc/systemd/system/sgnd.service:

[Unit]
Description=SGN daemon
After=network-online.target

[Service]
ExecStart=/home/ubuntu/go/bin/sgnd start \
  --home /home/ubuntu/.sgnd/ \
  --cli-home /home/ubuntu/.sgncli \
  --config /home/ubuntu/.sgncli/config/sgn.toml
StandardOutput=append:/var/log/sgnd/tendermint.log
StandardError=append:/var/log/sgnd/app.log
Restart=always
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target

tendermint.log contains Tendermint logs (i.e. block height, peer info, etc.) while sgnd.log contains SGN-specific logs.

  1. (Optional) For log rotation, create a /etc/logrotate.d/sgn file and add the following:
/var/log/sgnd/*.log {
    compress
    copytruncate
    maxsize 50M
    rotate 5
}
  1. Enable and start the sgnd service:
sudo systemctl enable sgnd.service
sudo systemctl start sgnd.service
  1. Monitor tendermint.log and wait for the node to sync:
tail -f /var/log/sgnd/tendermint.log

You can tell the node is synced when new blocks show up about every 5 seconds.

Claim validator status

  1. Initialize the validator candidate:
sgnops init-candidate --commission-rate <commission-rate> --min-self-stake <min-self-stake> --rate-lock-period <rate-lock-period>

Wait for the transaction to be confirmed. Refer to the CLI doc and design doc for more details. Note that rateLockPeriod + currentBlockNum = rateLockEndTime

  1. Delegate CELR to the candidate:
sgnops delegate --candidate <candidate-eth-address> --amount <delegate-amount>

Wait for the transaction to be confirmed. Refer to the CLI doc and design doc for more details.

  1. Note that it will take some time for the existing SGN validators to sync your new validator from the mainchain. Afterwards, verify your validator status:
sgncli query validator candidate <candidate-eth-address>

You should be able to see that your candidate has a delegatedStake matching your delegated amount denominated in wei.

  1. Verify validator is in the SGN validator set:
sgncli query validator validator <validator-account-address>

<validator-account-address> is the sgn-prefixed address you created. You should see your validator and its identity should equal to your <candidate-eth-address>. Make a note of the consensus_pubkey - the address prefixed with sgnvalconspub.

If your validator doesn't appear in the query, check the candidate status on mainchain through

sgnops get-candidate-info --candidate <candidate-eth-address>

If Status = 0 (unbonded), try claiming the status manually:

sgnops claim-validator

If Status = 1 (bonded), try triggering the sidechain info sync manually:

sgnops sync sync-validator --candidate <candidate-eth-address>

Then wait for a while and retry the query again.

  1. Verify validator is in the Tendermint validator set:
sgncli query tendermint-validator-set

You should see an entry with pub_key matching the consensus_pubkey obtained in step 4.

  1. Go to the SGN mainnet explorer to view your validator.

  2. Update validator public contact info:

sgncli tx validator edit-candidate-description --contact [email address] --website [entity website]

Setup gateway

Optionally, you can start a gateway service alongside the validator to serve HTTP requests.

  1. Prepare the SGN gateway service:
sudo mkdir -p /var/log/sgn-gateway
sudo touch /var/log/sgn-gateway/gateway.log
sudo touch /var/log/sgn-gateway/gateway_error.log
sudo touch /etc/systemd/system/sgn-gateway.service

Add the following to /etc/systemd/system/sgn-gateway.service:

[Unit]
Description=SGN gateway
After=network-online.target

[Service]
ExecStart=/home/ubuntu/go/bin/sgncli gateway \
  --laddr tcp://0.0.0.0:1317 \
  --home /home/ubuntu/.sgncli \
  --config /home/ubuntu/.sgncli/config/sgn.toml
StandardOutput=append:/var/log/sgn-gateway/gateway.log
StandardError=append:/var/log/sgn-gateway/gateway_error.log
Restart=always
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target
  1. (Optional) Add the log folder to /etc/logrotate.d/sgn:
/var/log/sgnd/*.log
/var/log/sgn-gateway/*.log {
...
  1. Enable and start the service:
sudo systemctl enable sgn-gateway.service
sudo systemctl start sgn-gateway.service

Withdraw stakes / Unbond validator

Please refer to the design doc for better understanding of the stake withdrawal process.

  1. Initialize a withdrawal of your self-delegated stake:
sgnops withdraw intend --candidate <candidate-eth-address> --amount <delegate-amount>

If the self-delegated stake after the withdrawal is below your min-self-stake amout, the validator will transit to unbonding status.

  1. After the slash timeout, confirm the withdrawal of your stake:
sgnops withdraw confirm --candidate <candidate-eth-address>

If your validator is in unbonding status, also confirm it to become unbonded.

sgnops confirm-unbonded-candidate --candidate <candidate-eth-address>

Withdraw rewards

Please refer to the design doc for better understanding of the reward withdrawal process.

  1. Initialize withdrawal of rewards at sidechain:
sgncli tx validator withdraw-reward <self-eth-address>
  1. Wait for the validators to co-sign the reward message, and query the reward message at sidechain:
sgncli query validator reward <self-eth-address>
  1. After new reward message is signed with signer stakes greater than quorum stakes, submit the message to mainchain:
sgnops withdraw reward

Other operations

Please refer to the CLI docs of sgnops and sgncli, or try sgnops --help and sgncli --help to learn more about other operations.

Reset local database

In case the local state of your validator is corrupted, you can try resetting the state by running:

sgnd unsafe-reset-all

Normally this shouldn't be necessary. Please contact us on Discord before doing so.