Archway v6.x Developer Upgrade Guide

[emperorjm]

This guide aims to equip developers with essential updates and modifications for a transition to Archway v6.x. The focus is on addressing key changes impacting smart contract and frontend application development, ensuring a smooth upgrade process.

A number of updates have been made to the protocol, the most notable being the shift to Cosmos SDK version 0.47.7 from v0.45.16. This transition also allowed us to upgrade wasmd (from v0.33 to v0.45), wasmvm (from v1.3.1 to v1.5.2) and ibc-go (from v4.3.1 to v7.3.0).

Smart Contract Development

Archway v6.x uses CosmWasm v1.5.2 and therefore if you want to take advantage of the new features in this version of CosmWasm you will need to update your cosmwasm-* dependencies in Cargo.toml:

[dependencies]

cosmwasm-std = "1.5.2"

cosmwasm-storage = "1.5.2"

...

[dev-dependencies]

cosmwasm-schema = "1.5.2"

cosmwasm-vm = "1.5.2"

...

If you wish to use a feature that is available only in CosmWasm 1.5+ chains, you can do the following:

cosmwasm-std = { version = "1.5.2", features = ["stargate", "cosmwasm_1_4"] }

Please note that cosmwasm_1_2 implies cosmwasm_1_1, and cosmwasm_1_3 implies cosmwasm_1_2, and so on. Therefore, there is no need to set multiple versions.

Governance

The way to create gov props for Sudo operations has changed. It now follows x/gov v1 (https://github.com/cosmos/cosmos-sdk/blob/v0.47.7/proto/cosmos/gov/v1/gov.proto) types. The legacy gov props for x/wasmd have been removed from the codebase.

New and Updated Features
You can view the full changelog from v1.4.0 to v1.5.2 here: https://github.com/CosmWasm/cosmwasm/blob/v1.5.2/CHANGELOG.md, to see the list of all additions. The following are some notable additions:

• Enables the DistributionQuery::{DelegationRewards, DelegationTotalRewards, DelegatorValidators} queries.
• Instance::set_debug_handler/unset_debug_handler were added to allow for customizing the handling of debug messages emitted by the contract.

The following are some notable changes:

• When enabling print_debug the debug logs are now printed to STDERR instead of STDOUT by default.
• Within cosmwasm-std there is an addition of to_json_{vec,binary,string} and from_json. to_{vec,binary} has been deprecated in favor of to_json_{vec,binary} and from_{slice,binary} in favor of from_json.

Frontend Development

This section guides developers through significant API modifications in Archway v6.x, ensuring your frontend applications stay operational in the new environment.

APIs

It should be noted that all modules no longer support the REST APIs previously known as LCD. Most of the legacy REST endpoints have been replaced by REST endpoints generated from gRPC Query services using grpc-gateway. The following page (https://docs.cosmos.network/v0.45/migrations/rest.html#migrating-to-new-rest-endpoints) includes a section titled “Migrating to New REST Endpoints” which presents a table listing the new REST endpoints alongside their respective legacy counterparts.

There are number of changes but here are some notable changes:

• REMOVED All of the governance endpoints starting with /cosmos/gov/v1beta1/…
• NEW Governance endpoints now start with /cosmos/gov/v1/…
• NEW /cosmos/bank/v1beta1/balances/archway1n…..address/by_denom?denom=
• REMOVED /cosmos/bank/v1beta1/supply/
• NEW /cosmos/bank/v1beta1/supply/by_denom?denom=

Instead of migrating to the new Rest endpoints we recommend that you migrate to gRPC instead https://docs.cosmos.network/v0.45/migrations/rest.html#migrating-to-grpc.

Archway Developer CLI

For the v6.x upgrade, devs should use the following version of the Devloper CLI: 2.1.0-rc.1. You can install this verison by using the following command:

npm i -g @archwayhq/cli@pre

Arch3.js

For the v6.x upgrade, devs should use the following version of arch3.js: 0.6.0. You can install this version by using the following command:

npm install --save @archwayhq/[email protected]

Breaking changes

There's a breaking change in CosmJs 3.1.x affecting the searchTx feature, which has been dramatically overhauled. Note that CosmJs is a dependency of Arch3.js. If your dapps stops working, this could be a possible issue.

Swagger

The URL for the Swagger UI will change from https://api.titus.archway.io/swagger to https://api.titus.archway.io/. The Swagger spec file path will change from https://api.titus.archway.io/swagger/swagger.yaml to https://api.titus.archway.io/static/swagger.min.json.

Explore New Modules

In the latest Archway v6.x update, developers have access to exciting new core modules that expand the capabilities on the platform.

• x/nft - NFT Base Module: This module lays the foundation for working with NFTs, providing essential infrastructure for developers to create, manage, and interact with NFTs within their applications.
• x/group - Group Module for DAOs, Multisig, and Policies: The x/group module is a versatile addition that facilitates the creation of DAOs, multi-signature wallets, and policy management. Its compatibility with x/authz enhances its utility, enabling a more integrated approach to managing permissions and actions within these entities.

You are able to use Stargate msgs in your contracts to utilize these modules.

Other Notable Changes

Refined Rewards Withdrawal

The process of withdrawing gas and inflationary rewards on Archway was cumbersome and expensive.

A new attribute named withdraw_to_wallet has been introduced in the ContractMetadata. When this attribute is activated (set to true), instead of generating a RewardRecord for the contract upon accruing gas or inflationary rewards, the rewards will be directly dispatched to the ContractMetadata.withdraw_address.

• If withdraw_to_wallet is set to false, the RewardRecord will be generated, necessitating manual withdrawal.
• If withdraw_to_wallet is set to true, the RewardRecord will not be generated, and rewards will be directly sent to the ContractMetadata.withdraw_address.

Params

The params module has been deprecated since Cosmos SDK v0.46. Cosmos SDK modules now store their parameters directly in their respective modules, and this is now the case for Archway custom modules as well. If you were pulling any data from the params module, you will need to redirect to the respective module's parameters.

Governance

Minimum Proposal Deposit At Time of Submission

The gov module has been updated to support a minimum proposal deposit at submission time. It is determined by a new parameter called MinInitialDepositRatio. When multiplied by the existing MinDeposit parameter, it produces the necessary proportion of coins needed at the proposal submission time. The motivation for this change is to prevent proposal spamming.

Currently, this feature is disabled but it can be enabled post upgrade if needed.

New Proposal.Proposer field

The Proposal proto has been updated with a proposer field.

Breaking Changes

• Significant enhancements have been made to the gov module. The former API is now under v1beta1, and the updated version is designated as v1. To submit a proposal, it is now required to use a proposal.json file with the submit-proposal command. While the older method, submit-legacy-proposal, remains usable, it is not recommended. Further details are available in the gov module client documentation (https://docs.cosmos.network/v0.46/modules/gov/07_client.html).
• For some new messages (for example, /cosmos.distribution.v1beta1.MsgCommunityPoolSpend) it seems it’s required to pass the authority address. The authority address is usually the governance module address. From the cli you can get it via archwayd --node https://rpc.titus.archway.io:443 q auth module-account gov or via rest https://{rest_url}/cosmos/auth/v1beta1/module_accounts/gov.

Staking

The staking module added a new message type to cancel unbonding delegations. Users that have unbonded by accident or wish to cancel a undelegation can now specify the amount and valdiator they would like to cancel the unbond from.

Keyring Migrations

The keyring holds the private/public keypairs used to interact with your node. The keyring has been refactored as of Cosmos SDK v0.46. This refactoring will require migrating your current Keyring to the newly improved solution. The migration should happen when utilizing archwayd. The migration is not backwards compatible and so you will need to create a backup before installing v6.x of archwayd if you would want to go back to a previous version.

NOTE: Please make sure you backup your private keys before attempting this upgrade.

[drewstaylor]

Note that if you're upgrading your archwayd daemon your keyring will be migrated to a new format. This change is not backwards compatible and if you need to use both keyrings (e.g. right now v6 is live on Constantine, but not on Mainnet) you will need to create a backup copy before installing v6.x archwayd so you can switch back and forth between versions

[emperorjm]

Thanks a lot for highlighting this @drewstaylor. I've added a section in the original post on this.