Validator Guide for Incentivized Testnet

The Agoric networks are still under active development, and should not be used for production store of value. Please wait until our "Mainnet" (schedule) before doing any transactions outside of research and testing.

Agoric Incentivized Testnet

See the main Agoric Incentivized Testnet site for an overview.

Join Discord Chat for Technical Discussion

For technical discussion, join the Agoric Discord server.

Network/Software Upgrade Instructions in Brief

1. Stop validator node (Ctrl +c or service stop)
2. Copy old config dir for safety (/home/user/.ag-chain-cosmos/config)
3. Do unsafe-reset-all (This will not change your validator id / keys)
4. Build new version of the software
5. Once the genesis file is available Replace old genesis with new one in your config dir
6. Start server and monitor chain startup.

To see status of votes on the current proposed block:

curl http://localhost:26657/consensus_state | jq '.result.round_state.height_vote_set[0].prevotes_bit_array'

The goal is to get >66% for each block to commit.

"BA{138:xxxxx_x_xxxxxx_xxxxxxxx__x___xxxxxx_x_x_x__xxxxx_x_xxx_xxxx_xxxx_x_xx__xx__x_xxxx__x__xxx_x_x_x_x_xxxxx_x_xxx___xxx_xxx_xx_xxx_x_xxx_x_xxx} 4488/6684 = 0.67"

0% is normal after a new block has begun.

"BA{138:__________________________________________________________________________________________________________________________________________} 0/6684 = 0.00"

In between, we are waiting for more validators to join and vote.

Network Status

Once the chain starts you can browse the current I.T.N. at an Agoric block explorer:

• testnet.explorer.agoric.net.

From testnet.agoric.net, you can find the current chain.json and genesis.json. If these links don't work (they give 503 errors), it is likely that the testnet infrastructure is in the process of being upgraded to the next release.

launch	software version	<GIT-BRANCH>	Git commit hash	Chain ID
2021-06-26	v0.26.7	>>agorictest-14<<	a62941a	agorictest-14
2021-06-24	v0.26.5	agorictest-13	02b6507	agorictest-13

Installing an Agoric Validator

Hardware

see Validator Hardware Requirements

Install Node.js

The Agoric platform currently uses Node.js (version 14.15.0 or higher) to evaluate Javascript smart contracts. See Node.js download instructions for details. In this example, we will be installing Node.js on a fresh install of Ubuntu 20.04:

# Download the nodesource PPA for Node.js
curl https://deb.nodesource.com/setup_14.x | sudo bash

# Download the Yarn repository configuration
# See instructions on https://legacy.yarnpkg.com/en/docs/install/
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

# Update Ubuntu
sudo apt update
sudo apt upgrade -y

# Install Node.js, Yarn, and build tools
# Install jq for formatting of JSON data
sudo apt install nodejs=14.* yarn build-essential jq -y

Install Go

Agoric's Cosmos integration is built using Go and requires Go version 1.15+. In this example, we will be installing Go on the above Ubuntu 20.04 with Node.js installed:

# First remove any existing old Go installation
sudo rm -rf /usr/local/go

# Install correct Go version
curl https://dl.google.com/go/go1.15.7.linux-amd64.tar.gz | sudo tar -C/usr/local -zxvf -

# Update environment variables to include go
cat <<'EOF' >>$HOME/.profile
export GOROOT=/usr/local/go
export GOPATH=$HOME/go
export GO111MODULE=on
export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin
EOF
source $HOME/.profile

To verify that Go is installed:

go version
# Should return go version go1.15.7 linux/amd64

Install Agoric SDK

We’ll install the Agoric SDK using git clone. For network timelines and the correct <GIT-BRANCH> to use, please check the Network Status section.

git clone https://github.com/Agoric/agoric-sdk -b <GIT-BRANCH>
cd agoric-sdk

# Install and build Agoric Javascript packages
yarn install
yarn build

# Install and build Agoric Cosmos SDK support
(cd packages/cosmic-swingset && make)

Note that you will need to keep the agoric-sdk directory intact when running the validator, as it contains data files necessary for correct operation.

To verify that Agoric Cosmos support has been built, check especially the version matches the software version described in the Network Status section:

ag-chain-cosmos version --long

name: agoriccosmos
server_name: ag-cosmos-server
version: <SOFTWARE-VERSION>
commit: <GIT-COMMIT>
build_tags: ""
go: go version go1.15.7 linux/amd64

If the software version does not match, then please check your $PATH to ensure the correct ag-chain-cosmos is running.

Configuring Your Node

Check the Network Parameters

To check the current testnet network parameters:

# First, get the network config for the current network.
curl https://testnet.agoric.net/network-config > chain.json
# Set chain name to the correct value
chainName=`jq -r .chainName < chain.json`
# Confirm value: should be something like agorictest-N.
echo $chainName

NOTE: If the $chainName is out of date, then it means you need to wait until the new Testnet has been bootstrapped before you can continue. Please refer to Network Status for when the Testnet corresponding to your software release is scheduled to be live. Repeat the above step to check if it is ready yet.

Apply Network Parameters

When the Agoric Testnet is ready in the previous step, you can initialize your validator and download the corresponding genesis file:

If you've never initialized your validator before, use:

# Replace <your_moniker> with the public name of your node.
# NOTE: The `--home` flag (or `AG_CHAIN_COSMOS_HOME` environment variable) determines where the chain state is stored.
# By default, this is `$HOME/.ag-chain-cosmos`.
ag-chain-cosmos init --chain-id $chainName <your_moniker>

Once you have an initialized validator, do:

# Download the genesis file
curl https://testnet.agoric.net/genesis.json > $HOME/.ag-chain-cosmos/config/genesis.json 
# Reset the state of your validator.
ag-chain-cosmos unsafe-reset-all

Adjust configuration

Next, we want to adjust the validator configuration to add the peers and seeds from the network config:

# Set peers variable to the correct value
peers=$(jq '.peers | join(",")' < chain.json)
# Set seeds variable to the correct value.
seeds=$(jq '.seeds | join(",")' < chain.json)
# Confirm values, each should be something like "[email protected]:26656,..."
echo $peers
echo $seeds
# Fix `Error: failed to parse log level`
sed -i.bak 's/^log_level/# log_level/' $HOME/.ag-chain-cosmos/config/config.toml
# Replace the seeds and persistent_peers values
sed -i.bak -e "s/^seeds *=.*/seeds = $seeds/; s/^persistent_peers *=.*/persistent_peers = $peers/" $HOME/.ag-chain-cosmos/config/config.toml

Syncing Your Node

To sync our node, we will use systemd, which manages the Agoric Cosmos daemon and automatically restarts it in case of failure. To use systemd, we will create a service file:

sudo tee <<EOF >/dev/null /etc/systemd/system/ag-chain-cosmos.service
[Unit]
Description=Agoric Cosmos daemon
After=network-online.target

[Service]
User=$USER
ExecStart=$HOME/go/bin/ag-chain-cosmos start --log_level=warn
Restart=on-failure
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target
EOF

# Check the contents of the file, especially User, Environment and ExecStart lines
cat /etc/systemd/system/ag-chain-cosmos.service

If you decide to run from the console, you can just do the following:

ag-chain-cosmos start --log_level=warn

To start syncing:

# Start the node
sudo systemctl enable ag-chain-cosmos
sudo systemctl daemon-reload
sudo systemctl start ag-chain-cosmos

To check on the status of syncing:

ag-cosmos-helper status 2>&1 | jq .SyncInfo

If this command fails with parse error: ..., then try just:

ag-cosmos-helper status

ag-cosmos-helper status Errors

If ag-cosmos-helper status fails with:

Error: failed to parse log level (main:info,state:info,statesync:info,*:error): Unknown Level String: 'main:info,state:info,statesync:info,*:error', defaulting to NoLevel

then run:

sed -i.bak 's/^log_level/# log_level/' $HOME/.ag-cosmos-helper/config/config.toml

If ag-cosmos-helper status fails with:

ERROR: Status: Post http://localhost:26657: dial tcp [::1]:26657: connect: connection refused

then you should run sudo journalctl -u ag-chain-cosmos and diagnose the failure.

Status output

If the status command succeeds, this will give output like:

{
  "latest_block_hash": "6B87878277C9164006F2E7C544A27C2A4010D0107F436645BFE35BAEBE50CDF2",
  "latest_app_hash": "010EF4A62021F88D097591D6A31906CF9E5FA4359DC523B535E3C411DC6010B1",
  "latest_block_height": "233053",
  "latest_block_time": "2020-01-31T22:12:45.006715122Z",
  "catching_up": true
}

The main thing to watch is that the block height is increasing. Once you are caught up with the chain, catching_up will become false. At that point, you can start using your node to create a validator.

Creating a Validator

**For a chain restart, skip to

If you are upgrading, skip creating a new operator key.

If you don't have an operator key

Are you really sure you don't have an operator key? You should try recovering it from your mnemonic.

First, create a wallet, which will give you a private key / public key pair for your node.

# Replace <your-key-name> with a name for your operator key that you will remember
ag-cosmos-helper keys add <your-key-name>
# To see a list of wallets on your node
ag-cosmos-helper keys list

NOTE: Be sure to write down the mnemonic for your wallet and store it securely. Losing your mnemonic could result in the irrecoverable loss of Agoric tokens. Also, recovering pre-testnet-3 keys from their mnemonic has changed. Please refer to the software release notes.

Tap the Faucet

To request tokens, go to the Agoric Discord server #testnet-faucet channel and send the following chat message with your generated Agoric address (the address: agoric1... address, not the pubkey: agoricpub1... public key):

!faucet delegate agoric1...

When you get the ✅ the uagstake tokens have been sent, and you can view the tokens in your account.

Check your balance

# View the tokens ("coins") currently deposited in your operator account.
# The "uagstake" tokens are millionths of Agoric staking tokens
ag-cosmos-helper query bank balances `ag-cosmos-helper keys show -a <your-key-name>`

Verify that you have at least 1 agstake (1000000uagstake).

Catching up

Your node must have caught up with the rest of the chain before you can create the validator. Here is a shell script loop that will wait for that to happen:

while sleep 5; do
  sync_info=`ag-cosmos-helper status 2>&1 | jq .SyncInfo`
  echo "$sync_info"
  if test `echo "$sync_info" | jq -r .catching_up` == false; then
    echo "Caught up"
    break
  fi
done

The above loop will poll your node every 5 seconds, displaying the sync_info. When you have caught up, it will display a Caught up message and stop the loop.

Get the validator public key

NOTE: The following command will give incorrect values if you don't run it under the same machine and user that is currently running your validator:

# Get the public key from the current node.
ag-chain-cosmos tendermint show-validator

This will display something like agoricvalconspub1.... Paste this key somewhere you can access it in the below step.

Submit the create-validator transaction

You can see the options for creating a validator:

ag-cosmos-helper tx staking create-validator -h

An example of creating a validator with 50 agstake self-delegation and 10% commission. You need the correct --pubkey= flag as described in the previous section, or you will lose your staking tokens:

# Set the chainName value again
chainName=`curl https://testnet.agoric.net/network-config | jq -r .chainName`
# Confirm value: should be something like agoricdev-N
echo $chainName
# Replace <key_name> with the key you created previously
ag-cosmos-helper tx staking create-validator \
  --amount=50000000uagstake \
  --broadcast-mode=block \
  --pubkey=<your-agoricvalconspub1-key> \
  --moniker=<your-node-name> \
  --website=<your-node-website> \
  --details=<your-node-details> \
  --commission-rate="0.10" \
  --commission-max-rate="0.20" \
  --commission-max-change-rate="0.01" \
  --min-self-delegation="1" \
  --from=<your-key-name> \
  --chain-id=$chainName \
  --gas=auto \
  --gas-adjustment=1.4

To check on the status of your validator:

ag-cosmos-helper status 2>&1 | jq .ValidatorInfo

Next steps

After you have completed this guide, your validator should be up and ready to receive delegations. Note that only the top 100 validators by weighted stake (self-delegations + other delegations) are eligible for block rewards. To view the current validator list, check out an Agoric block explorer (in the Network Status section).

Creating a gentx

see Creating a gentx

Frequently Asked Questions

See Validator Guide

Caveats

Note that this is a minimal guide and does not cover more advanced topics like sentry node architecture and double-signing protection. It is strongly recommended that any parties considering validating do additional research.

Developing dApps?

Note that developing dapps for the Agoric chain does not require you to be a validator. If you're primarily looking to develop, please head here instead. If not, read on!

---

Disclaimer: This content is provided for informational purposes only, and should not be relied upon as legal, business, investment, or tax advice. You should consult your own advisors as to those matters. References to any securities or digital assets are for illustrative purposes only and do not constitute an investment recommendation or offer to provide investment advisory services. Furthermore, this content is not directed at nor intended for use by any investors or prospective investors, and may not under any circumstances be relied upon when making investment decisions.

This work, "Agoric Validator Guide", is a derivative of "Validating Kava Mainnet" by Kevin Davis, used under CC BY. "Agoric Validator Guide" is licensed under CC BY by Agoric. It was extensively modified to make relevant to the Agoric Cosmos Chain.