Skip to content

ag0 to agd upgrade for mainnet 1 launch

Jump to bottom
Dan Connolly edited this page Oct 27, 2022 · 6 revisions

🛡️ Network Upgrade Recommendations

To prepare for this network upgrade, which is the first time that the Agoric JavaScript VM will be include on-chain, here is everything you need to know in advance:

  • There is no binary release of 'agd', so validators MUST build the code from source in advance of reaching the blockheight specified in the proposal. The compilation of the code takes longer than ag0, and it requires installing the agd binary as well as additional dependencies. Taking this step in advance will help validators start producing blocks more quickly.
  • Agoric recommends orchestrating the running of agD manually, or create a systemd service for agd as described below. While the code was under evaluation on Emerynet, several validators experienced compatability issues with Cosmovisor, and the Agoric team recommends against relying on it for this upgrade. If you've found a comfortable workaround and would like to proceed with Cosmovisor for this upgrade, please consult Polkachu's Unofficial Upgrade Guide for agoric-upgrade-8 to avoid any issues with symlink or file path names.
  • Before you upgrade, Agoric recommends creating a backup of your local.agoric directory. It is always a good idea to backup important data (e.g. state) before initiating major changes in your environment.

If you have any questions, the Agoric team is available in the #peer-support channel in the Mainnet Validator category of the Agoric Discord. (If you don't see the Mainnet category, visit #get-roles to get the Mainnet role.)

Overview: build from source

For this upgrade, agd installation involves building from source. A binary installation package for agd is an outstanding issue: #6455.

  1. Install agd from source
    1. install node, yarn
    2. install go
    3. install agoric-sdk
    4. Configure agd.service
  2. Disable ag0 once it stops
  3. Start agd to complete the upgrade

Install agd

Tested on Ubuntu 22.04

These source installation instructions were tested on an Ubuntu 22.04.1 LTS amd64 host with with sudo and curl available. For a recording, see:

Note: this recording pre-dates rc4; it used rc3. Also, it shows running as root, which is probably not a good idea in production.

Install Node.js and yarn

Install node.js v16. Following Node.js download instructions:

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

# Install the Yarn package manager
curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/yarnkey.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

# Update Ubuntu
sudo apt-get update
sudo apt upgrade -y

# Install Node.js, Yarn, and build tools
# Install jq for formatting of JSON data
# We'll need git below.
sudo apt install nodejs=16.* yarn build-essential git jq -y

# verify installation
node --version | grep 16
yarn --version

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

# Download and verify go
curl -L -o /tmp/go1.18.7.linux-amd64.tar.gz https://go.dev/dl/go1.18.7.linux-amd64.tar.gz
sha256sum --check <<EOF
6c967efc22152ce3124fc35cdf50fc686870120c5fd2107234d05d450a6105d8  /tmp/go1.18.7.linux-amd64.tar.gz
EOF

# install
sudo tar -C /usr/local -xzf /tmp/go1.18.7.linux-amd64.tar.gz

# 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

# Verify that Go is installed:
go version | grep 1.18

Install Agoric SDK

We’ll install the Agoric SDK from source using git clone.

cd # Writeable directory of your choice. $HOME will do.
git clone https://github.com/Agoric/agoric-sdk -b pismoA
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 the build:

agd version --long

The output should start with:

name: agoriccosmos
server_name: ag-cosmos-helper
version: 0.32.2
commit: 2c812d221
build_tags: ',ledger'
go: go version go1.18.1 linux/amd64
...

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

Configure agd.service

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

sudo systemctl enable agd
sudo systemctl daemon-reload

To confirm that the service is configured but not yet started, run systemctl status agd. The result should look like:

○ agd.service - Agoric Cosmos daemon
     Loaded: loaded (/etc/systemd/system/agd.service; enabled; vendor preset: enabled)
     Active: inactive (dead)

To confirm that agd has access to the same key material that ag0 was using:

ag0 tendermint show-validator
agd tendermint show-validator

Disable ag0 once it stops

ag0 should stop on its own at the block height in the software upgrade governance proposal.

Once that happens, disable it:

sudo systemctl disable ag0

Start agd to complete the upgrade

sudo systemctl start agd

Proposing the upgrade

(this part is done: Proposal 16)

Context / Background

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

Clone this wiki locally