Validator Guide for Devnet

The Agoric Devnet should not be used for production store of value. Mainnet is covered in other Validator Guide sections.

Join Discord Chat for Technical Discussion

For technical discussion, join the Agoric Discord server, especially #devnet and #validators.

Network Status

You can browse the current Devnet at an Agoric block explorer:

devnet.explorer.agoric.net.

Participants in the incentivized testnet should see the Validator Guide for Incentivized Testnet.

From devnet.agoric.net, you can find the current chain.json.

launch	`agd` version	`<GIT-BRANCH>`	Git commit hash	Chain ID
>>CURRENT<<	`v0.32.0`	`agoricdev-15`	fa272e	pismoA-rc2
2022-10-05	`v0.32.0`	`agoricdev-15`	fa272e	pismoA-rc2
2022-09-20	`v0.31.0`	`agoricdev-14`	bc883b	agoricdev-14
2022-05-27	`v0.30.0`	`agoricdev-13`	fca3db8	agoricdev-13
2022-05-07	`v0.29.0`	`agoricdev-11`	e9ed050	agoricdev-11
2022-04-18	`v0.29.0`	`agoricdev-10`	75965ee	agoricdev-10
2022-02-25	`v0.28.0`	`agoricdev-8`	8eef3e3	agoricdev-8
2021-12-26	`v0.27.2`	`agoricdev-7`	2b0ce50	agoricdev-7
2021-12-03	`v0.27.1`	`agoricdev-6`	6bf2266	agoricdev-6
2021-10-14	`v0.27.0`	`agoricdev-5.1`	f650334	agoricdev-5
2021-09-22	`v0.26.19`	`agoricdev-4`	9f3978d	agoricdev-4
2021-07-28	`v0.26.10`	`agoricdev-3`	65cec90	agoricdev-3
2021-04-22	`v0.25.4`	`agoricdev-2`	cd015a9	agoricdev-2
2021-03-17	`@agoric/[email protected]`	`@agoric/[email protected]`	5ad5f48	agoricdev-1
2021-02-17	`@agoric/[email protected]`	`@agoric/[email protected]`	3169872	agorictest-6
2020-12-11	`@agoric/[email protected]`	`@agoric/[email protected]`	940a9eb	agorictest-4
2020-10-14	`@agoric/[email protected]`	`@agoric/[email protected]`	f7e1505	testnet-3
2020-09-21T18:00:00Z	`@agoric/[email protected]`	`@agoric/[email protected]`	f5ee0a0	testnet-2.8.0
2020-09-02T18:00:00Z	`@agoric/[email protected]`	`@agoric/[email protected]`	b4955e7	testnet-2.7.2

Installing an Agoric Validator

NOTE: First see the latest software release notes. Any breaking changes for this release will be described there.

Also, note that the timeout_commit parameter has been changed back to 5s. The value in some Devnets was 2s, which was too low for globally-dispersed validators.

Prerequisites

You should select an all-purpose server with at least 4 GB of RAM, good connectivity, and a solid-state drive with at sufficient disk space. Storage requirements are discussed further in the section below. In addition, you’ll need to open port 26656 to connect to the Agoric peer-to-peer network. As the usage of the blockchain grows, the server requirements may increase as well, so you should have a plan for updating your server as well.

Storage

The monthly storage requirements for a node are as follows. These are estimated values based on experience but should serve as a good guide:

With the current block cadence of 5 seconds/block:
- a full Devnet node (with the default pruning=syncable) grows at the rate of ~6GB/month (approximately 200MB/day)
- an archiving Devnet node (with pruning=nothing) grows at the rate of ~12GB/month (approximately 400MB/day),

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.17+. 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.18.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.18.x 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:

agd version --long

name: agoriccosmos
server_name: agd
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 agd is running.

Configuring Your Node

Check the Network Parameters

To check the current devnet network parameters:

# First, get the network config for the current network.
curl https://devnet.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 agoricdev-N.
echo $chainName

NOTE: If the $chainName is out of date (i.e. it is for the previous Devnet), then it means you need to wait until the new Devnet has been bootstrapped before you can continue. Please refer to Network Status for when the Devnet 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 Devnet 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/.agoric`.
agd init --chain-id $chainName <your_moniker>

Once you have an initialized validator, do:

# Download the genesis file
curl https://devnet.rpc.agoric.net/genesis | jq .result.genesis > $HOME/.agoric/config/genesis.json 
# Reset the state of your validator.
agd 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/.agoric/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/.agoric/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/agd.service
[Unit]
Description=Agoric Cosmos daemon
After=network-online.target

[Service]
# OPTIONAL: turn on JS debugging information.
#SLOGFILE=.agoric/data/chain.slog
User=$USER
# OPTIONAL: turn on Cosmos nondeterminism debugging information
#ExecStart=$HOME/go/bin/agd start --log_level=info --trace-store=.agoric/data/kvstore.trace
ExecStart=$HOME/go/bin/agd 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/agd.service

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

agd start --log_level=warn

To start syncing:

# Start the node
sudo systemctl enable agd
sudo systemctl daemon-reload
sudo systemctl start agd

To check on the status of syncing:

agd status | jq .SyncInfo

`agd status` Errors

If agd 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/.agoric/config/config.toml

If agd status fails with:

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

then you should run sudo journalctl -u agd 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

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
agd keys add <your-key-name>
# To see a list of wallets on your node
agd 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, use the Devnet Faucet with your generated Agoric address (the address: agoric1... address, not the pubkey: agoricpub1... public key):

Check your balance

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

Verify that you have at least 1 BLD (1000000ubld).

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=`agd status | 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.
agd tendermint show-validator

This will display something like {"@type":"/cosmos.crypto.... 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:

agd tx staking create-validator -h

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

# Set the chainName value again
chainName=`curl https://devnet.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
agd tx staking create-validator \
  --amount=50000000ubld \
  --broadcast-mode=block \
  --pubkey='{"@type":"/cosmos.crypto...' \
  --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:

agd status | jq .ValidatorInfo

Delegating to a Validator

To delegate your tokens you should use Operator Address:

# Replace <operator-address> with agoricvaloper1 address of a Validator you want to delegate BLD tokens
# Replace <amount> with the amount you prefer to delegate
# You could also replace $chainName with CURRENT git branch e.g agoricdev-7
agd tx staking delegate <operator-address> <amount>ubld --chain-id=$chainName --gas=auto --from=<your-key-name>
# Enter your keyring passphrase confirm transaction

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).

Frequently Asked Questions

Where can I get support?

For technical questions and troubleshooting: join the #validators channel on the Agoric Discord server.

When is mainnet? When are tokens going on sale?

See Agoric FAQs.

What does Power Change: 49 -> 0 mean?

Your validator was jailed.

How do I unjail my validator?

First, ensure your validator is caught up.

Run:

# Set the chainName value again
chainName=`curl https://devnet.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
agd tx slashing unjail \
  --broadcast-mode=block \
  --from=<your-key-name> \
  --chain-id=$chainName \
  --gas=auto \
  --gas-adjustment=1.4

How do I move my validator to another machine?

To preserve your validator's identity, you must copy the $HOME/.agoric directory to the new machine. Be sure that your agd is not running on the old machine. If it is, you will be slashed for double-signing.

Finally, just start agd on the new machine. If your validator has been jailed due to downtime, you may have to unjail it.

How do I upgrade my validator to a new network?

For now, every new devnet starts over with a fresh set of validators. You will not be penalized for joining the devnet later than genesis. Thus, after the new devnet starts, you can stop your existing validator, then follow the Guide above. Please work through it carefully, as instructions may have changed.

How do I recover a key?

You will need your 24-word mnemonic, then run:

Most keys

You should try the following:

agd keys add <your-new-key-name> --recover

If agd keys list doesn't show your correct address, and you have been a validator since before testnet-3, go on to the next step.

Otherwise, you're done!

Generated before `testnet-3`

Only use this method if you are certain you need to recover a key you generated before testnet-3.

agd keys add <your-new-key-name> --recover --coin-type=118

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.

Incentivized Testnet: apply at validate.agoric.com

Joining the current Devnet is not a prerequisite for the Incentivized Testnet.

For a walkthrough:

Agoric Community Call #6 streamed March 10, 2021
- See also Agoric Events

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.

This wiki is for developing agoric-sdk. For help using Agoric SDK, see https://docs.agoric.com/ and https://agoric-sdk.pages.dev/