Agoric Upgrade 22

antman · September 15, 2025, 7:54pm

Hello Agoric Validators & BLD Community,

Agoric OpCo engineers have released the agoric-upgrade-22-rc1 software upgrade for the agoric-3 chain. Upgrade 22 has two noteworthy changes: migrating the cosmos-sdk to v0.50.14 and continuing the termination of old Vats.

We have prepared the following:

https://github.com/Agoric/agoric-sdk/releases/tag/agoric-upgrade-22-rc1

Breaking Changes for Validators

The following changes may require updates to validator scripts, automation, or operational procedures:

CLI Flag and Response Changes

Status Response Keys
agd status response keys are now snake_case instead of CamelCase.
- Example: SyncInfo → sync_info.
Pagination Flag
–limit is renamed to --page-limit across all paginated queries.
Chain ID Flag
agd query … commands no longer accept the --chain-id flag. Validators must remove this argument from scripts.

Validator Creation

Staking Transaction
agd tx staking create-validator now only accepts a validator_json_file.
Inline parameters are no longer supported.

Governance Queries

Proposal List Query
- agd query gov proposals:
  - Flag --status is now --proposal-status.
  - In v0.47, this command returned a non-zero exit code when no proposals existed.
  - In v0.50, it exits successfully (0) with an empty response.
Single Proposal Query
- agd query gov proposal responses are now nested under a .proposal key.

Tx Queries:

Query a transaction
- The --events option for agd query txs no longer exists
- Now it’s called --query and uses the same DSL as Tendermint.
  Before: agd query tx --events 'foo=123&bar=456\
  After: agd query tx --query ‘foo=123 AND bar=456

Gov Proposal Submissions:

Gov Param Change:
- agd tx gov submit-proposal param-change proposal.json
  - in 0.50, submit-proposal param-change won’t work with gov and staking subspace
  - It has to be MsgUpdateParam instead

Before: agd tx gov submit-proposal param-change legacy-proposal.json


{

“title”: “Reduce MaxValidators to 30”,

“description”: “Reduce MaxValidators to 30”,

“changes”: \[

{

“subspace”: “staking”,

“key”: “max_validators”,

“value”: 30

}

\],

“deposit”: “10000000ubld”

}

After: agd tx gov submit-proposal proposal.json

{

“messages”: \[

{

“@type”: “/cosmos.staking.v1beta1.MsgUpdateParams”,

“authority”: “AGORIC_GOVERNANCE_AUTHORITY_ADDRESS”,

“params”: {

“unbonding_time”: “1814400s”,

“max_validators”: 30,

“max_entries”: 7,

“historical_entries”: 10000,

“bond_denom”: “ubld”,

“min_commission_rate”: “0.000000000000000000”

}

}

\],

“title”: “Reduce MaxValidators to 30”,

“summary”: “Update staking params to reduce active validator set from 100 to 30.”,

“metadata”: “”,

“deposit”: “10000000ubld”

Prerequisites:

IMPORTANT

Note that Agoric SDK no longer supports Node 18. Please make sure you’re on one of the supported versions as outlined in the README.

Agoric SDK now requires Golang version 1.22.12 or greater. To check your Golang version, examine the output produced by running go version in your build environment.

Install supported versions of Go, Node.js, and a compiler such as gcc or clang as documented in the README.

Make sure that the environment running the agd service has the same Node.js version as the environment used for building. In particular, if using nvm to manage Node.js version, the service environment should enable nvm and use the same version.

Milestone Testing

By running long-lived testnets and using that environment to evaluate software before promoting it to mainnet, validators play a vital role in maintaining a healthy, robust network for the Agoric community. Qualifying or certifying any new software release as production ready requires significant testing, and Agoric OpCo recommends that validators perform the following milestone tests to ensure functionality on Emerynet before launching an on-chain governance proposal on the agoric-3 mainnet.

Note: Ensure that you’re up to date on golang and node versions for this release, and that you’ve upgraded to the latest version of Cosmovisor that supports the upgrade handler. See below for information on Node.js version management.

Milestone tests include:

Performing the upgrade on a test node
Restarting a validator node
Testing state sync
- Create a state sync snapshot
- Spinning up a node using state sync
Submitting a test proposal (e.g., a chain parameter change)

Creating an Emerynet upgrade proposal:

Please note that the naming conventions have changed and Emerynet and mainnet now use the same upgrade name. Confirm the commit hash and upgrade name BEFORE submitting a proposal.

# Edit as needed

FROM_WALLET=yourwallet

UPGRADE_HEIGHT="1234-get-blockheight-from-estimator"

# Verify values

UPGRADE_TO="agoric-upgrade-22"

CHAIN_ID="agoric-emerynet-9"

COMMIT_ID=$(git rev-parse HEAD)

ZIP_URL="https://github.com/Agoric/agoric-sdk/archive/${COMMIT_ID}.zip"

CHECKSUM=sha256:$(curl -L "$ZIP_URL" -o- | shasum -a 256 | cut -d' ' -f1)

UPGRADE_INFO="{\"binaries\":{\"any\":\"$ZIP_URL//agoric-sdk-$COMMIT_ID?checksum=$CHECKSUM\"},\"source\":\"$ZIP_URL?checksum=$CHECKSUM\"}"

agd tx gov submit-proposal software-upgrade $UPGRADE_TO --upgrade-info="$UPGRADE_INFO" --upgrade-height="$UPGRADE_HEIGHT" --title="Upgrade to $UPGRADE_TO" --description="This proposal if voted will upgrade the chain to $UPGRADE_TO" --from=$FROM_WALLET --chain-id=$CHAIN_ID

When the testnet milestones are complete and validators have fully qualified the release on Emerynet, the testnet coordinator should inform Agoric Systems to promote the release from rc to final and update tags accordingly, then create and submit a similar on-chain proposal to upgrade the agoric-3 chain to agoric-upgrade-22.

Creating a Mainnet upgrade proposal:

Confirm the commit hash and upgrade name BEFORE submitting a proposal.

# Edit as needed

FROM_WALLET=yourwallet

UPGRADE_HEIGHT="1234-get-blockheight-from-estimator"

# Verify values

UPGRADE_TO="agoric-upgrade-22"

CHAIN_ID="agoric-3"

COMMIT_ID=$(git rev-parse HEAD)

ZIP_URL="https://github.com/Agoric/agoric-sdk/archive/${COMMIT_ID}.zip"

CHECKSUM=sha256:$(curl -L "$ZIP_URL" -o- | shasum -a 256 | cut -d' ' -f1)

UPGRADE_INFO="{\"binaries\":{\"any\":\"$ZIP_URL//agoric-sdk-$COMMIT_ID?checksum=$CHECKSUM\"},\"source\":\"$ZIP_URL?checksum=$CHECKSUM\"}"

agd tx gov submit-proposal software-upgrade $UPGRADE_TO --upgrade-info="$UPGRADE_INFO" --upgrade-height="$UPGRADE_HEIGHT" --title="Upgrade to $UPGRADE_TO" --description="This proposal if voted will upgrade the chain to $UPGRADE_TO" --from=$FROM_WALLET --chain-id=$CHAIN_ID

Note for managing Node.js versions

We recommend avoiding using nvm or similar tools to manage the Node.js version, and instead rely on a package installed globally through the system package manager. Tools like nvm only affect the current shell session, and unless care is taken to configure the agd service environment to also use nvm with the same Node.js version, there is a risk that the Node.js version used when building may be different than the one when running the service, resulting in errors when trying to start the service. We are looking at ways to simplify this dependency management requirement specific to the Agoric chain.

Note for anyone generating state-sync snapshots or restoring from state-sync

State-sync snapshots now only include minimal data to restore a node, and the new configuration settings will help further reduce requirements of non-archival nodes. However, there may still be continued performance issues related to state-sync. In particular, we’ve observed that on some deployments, the snapshot taking and restoring process can take multiple hours, require about 20GB of temporary free disk space, and 16GB of memory.

Note: the agd snapshots export command has been fixed, and can now be used to generate a snapshot export of the latest application state (while the node is not running). Combined with other snapshots commands and the agd tendermint bootstrap-state command, this can be used to restore a node (state-sync pruning) without having to connect the node to the p2p network.

mathieu · October 14, 2025, 6:57pm