-
Notifications
You must be signed in to change notification settings - Fork 207
Validator Guide for Devnet
Note: See also the Agoric community forum, especially the Validators category and the Network Upgrades category.
The Agoric Devnet should not be used for production store of value.
For technical discussion, join the Agoric Discord server, especially #devnet and #devnet-announce.
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.
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.
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),
- a full Devnet node (with the default
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 -yAgoric'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/.profileTo verify that Go is installed:
go version
# Should return go version go1.18.x linux/amd64We’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.
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 $chainNameNOTE: 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.
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 tendermint unsafe-reset-allNext, 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
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.serviceIf you decide to run from the console, you can just do the following:
agd start --log_level=warnTo start syncing:
# Start the node
sudo systemctl enable agd
sudo systemctl daemon-reload
sudo systemctl start agdTo check on the status of syncing:
agd status | jq .SyncInfoIf 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.tomlIf 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.
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.
If you are upgrading, skip creating a new 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 listNOTE: 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.
To request tokens, use the Devnet Faucet with your generated Agoric address (the address: agoric1... address, not the pubkey: agoricpub1... public key):
# 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).
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
doneThe 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.
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-validatorThis will display something like {"@type":"/cosmos.crypto.... Paste this key somewhere you can access it in the below step.
You can see the options for creating a validator:
agd tx staking create-validator -hAn 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.4To check on the status of your validator:
agd status | jq .ValidatorInfoTo 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 transactionAfter 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).
For technical questions and troubleshooting: join the #validators channel on the Agoric Discord server.
See Agoric FAQs.
Your validator was jailed.
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.4To 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.
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.
You will need your 24-word mnemonic, then run:
You should try the following:
agd keys add <your-new-key-name> --recoverIf 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!
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=118Note 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
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.