var img = document.createElement('img'); img.src = "https://terradocs.matomo.cloud//piwik.php?idsite=1&rec=1&url=https://docs.terra.money" + location.pathname; img.style = "border:0"; img.alt = "tracker"; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(img,s);
Skip to main content

Terra Core upgrade notes

Current version - v2.9.3

On January 18th, 2024, a core upgrade proposal was passed through governance. The Terra Core was upgraded to v2.9.3 at blockheight 8782000.

Core v2.6.1

On November 10th, 2023, a core upgrade proposal was passed through governance. On November 15th, 2023, the Terra Core was upgraded to v2.6.1 at blockheight 7722000.

Core v2.5.2

The Terra blockchain was upgraded to Terra Core v2.5.2 on October 18, 2023 at blockheight 7316000. Refer to the governance proposal for more information on the upgrade.

Breaking changes

  • This upgrade will require the use of IBC relayer v2.4.0 or later, or any other relayer compatible with IBC-Go v7
  • Update @terra-money/feather.js to use the latest protobuf additions
  • Update terra-proto-rs to use the latest protobuf additions and extend to implement all message types supported natively by Terra
  • Terra-sdk python: library upgraded to be compatible with Terra Core v2.5. TFL has discontinued the maintenance for this library and has entered it into the public domain under an MIT license

Core Dependency Upgrades

  • Alliance: v0.1.2 => v0.3.2
  • CosmosSDK: v0.46.13-terra.3 => v0.47.5-terra.2
  • CometBFT: v0.34.27-terra.rc.1 => v0.37.2
  • CosmWasm: v0.30.0-sdk469.5 => v0.41.0
  • Wasmvm: v1.1.2 => v1.3.0
  • IBC-Go: v6.1.1 => v7.3.0
  • Packet Forward Middleware: v6.0.2 => v7.0.0
  • IBC hooks: (Terra Core) v2.4 => v7.0.0
  • TokenFactory: v0.30.0-sdk469.5 into Terra Core v2.5 (with smart contract hooks. More info)

Bug Fixes

  • Fixed an issue with update-client terrad IBC-command (Reported by Synergy Nodes)
  • Fixed: Interchain controller params call returns "UnmarshalJSON cannot decode empty bytes: panic” (Reported by Bretheren on Github)
  • Fixed a vulnerability regarding Packet Forward Middleware interacting with IBC hooks (Reported by SCV)
  • Migrated atlantic-2 IBC channels to increase the unbonding period from 2 days to 5 days (Reported by the Astroport team)

Thank you to the community members for reporting these bugs!

Fork Updates

Finally, we updated some forks maintained by TFL and partners to use the officially developed libraries. Using officially supported libraries allows Terra to get upstream updates faster and reduces overall maintenance effort on the Core team.

  • github.com/terra-money/tendermint => github.com/cometbft/cometbft
  • github.com/terra-money/wasmd => github.com/CosmWasm/wasmd
  • github.com/terra-money/core/v2/x/ibc-hooks => github.com/cosmos/ibc-apps/modules/ibc-hooks
  • github.com/strangelove-ventures/packet-forward-middleware => github.com/cosmos/ibc-apps/middleware/packet-forward-middleware/v7

Previous upgrades

v2.3.1

Terra Core v2.3.1 is a major upgrade for the Terra blockchain. The main feature of this upgrade is the addition of the Alliance module, enabling Terra to form economic alliances with other chains. Refer to the specifications below for a full list of changes.

🛠Upgrade guide

Developers should refer to the Core upgrade guide for instructions on updating their applications.

1. Cosmos-sdk v0.46.10 upgrade

Details

Cosmos SDK will be upgraded to v0.46.10, which includes:

Modules

x/params

  • The x/param module has been depreacted in favor of each module housing and providing way to modify their parameters. Each module that has parameters that are changable during runtime have an authority, the authority can be a module or user account. The Cosmos-SDK team recommends migrating modules away from using the param module. An example of how this could look like can be found here.
  • The Param module will be maintained until April 18, 2023. At this point the module will reach end of life and be removed from the Cosmos SDK.

x/gov

The gov module has been greatly improved. The previous API has been moved to v1beta1 while the new implementation is called v1.

In order to submit a proposal with submit-proposal you now need to pass a proposal.json file. You can still use the old way by using submit-legacy-proposal. This is not recommended. More information can be found in the gov module client documentation.

  • deposits are burned only if the vote returned is nowithveto. All other scenarios will refund deposits. Proposals that fail to meet quorum, fail to reach the minimum deposit, or End in a yes or no vote will get their deposits refunded: https://github.com/cosmos/cosmos-sdk/pull/11011

Overview

Update guide:

https://github.com/cosmos/cosmos-sdk/blob/release/v0.46.x/UPGRADING.md

Full changelog: https://github.com/cosmos/cosmos-sdk/blob/release/v0.46.x/CHANGELOG.md

Terrad changes:

  • make chain-id flag not strictly required for tx commands: https://github.com/cosmos/cosmos-sdk/pull/10184
  • #11313 Fixes --gas auto when executing CLI transactions in --generate-only mode
  • (cli) #12095 Fix running a tx with --dry-run returns an error
  • (cli) #11313 Fixes -gas auto when executing CLI transactions in -generate-only mode
  • (cli) #11337 Fixes show-adress cli cmd
  • #10842 Fix error when --generate-only--max-msgs fags set while executing WithdrawAllRewards command.
  • #11558 Fix --dry-run not working when using tx command.
  • #11197 Signing with multisig now works with multisig address which is not in the keyring.
  • #11983 (x/feegrant, x/authz) rename grants query commands to grants-by-granteegrants-by-granter cmds.
  • #9762 The init command uses the chain-id from the client config if --chain-id is not provided
  • (cli) #11065 Ensure the tendermint-validator-set query command respects the -o output flag.
  • #11354 Added missing pagination flag for bank q total query.
  • #10625 Add --fee-payer CLI flag
  • • (cli) #9856 Overwrite --sequence and --account-number flags with default flag values when used with offline=false in sign-batch command.
  • #10379 Add validation to x/upgrade CLI software-upgrade command --plan-info value.
  • #9695 <app> keys migrate CLI command now takes no arguments.
  • #9246 Removed the CLI flag -setup-config-only from the testnet command and added the subcommand init-files.
  • #10625 Rename -fee-account CLI flag to -fee-granter
  • #10684 Rename edit-validator command's -moniker flag to -new-moniker
  • (authz)#11060 Changed the default value of the -expiration tx grant CLI Flag: was now + 1year, update: null (no expire date).
  • (client/keys) #9407 Added keys rename CLI command and Keyring.Rename interface method to rename a key in the keyring.
  • #10311 Adds cli to use tips transactions. It adds an --aux flag to all CLI tx commands to generate the aux signer data (with optional tip), and a new tx aux-to-fee subcommand to let the fee payer gather aux signer data and broadcast the tx

2. Update Wasm

Details

x/wasm has been upgraded to github.com/notional-labs/wasmd v0.30.0-sdk469.4.

Wasm can now use Wasmd. Wasmd is a Cosmos zone implementation with WebAssembly (WASM) smart contracts enabled, based on a fork of the cosmos/gaia repository. The Wasmd binary functions like gaiad, with the addition of the x/wasm module. It provides compatibility with CosmWasm contracts and supports various interface versions.

3. Update ibc and packetforwardingmiddleware from v3 to v6

Details

IBC

v3 to v4:

  • Moved IBC core modules from x/ibc to core package.
  • All client state types now use ClientState interface.
  • Introduced ICS4Wrapper interface for handling LightClientState and LightClientConsensusState methods.
  • CreateClient method in testing package now returns created client's ClientState.

v4 to v5:

  • Introduced UpgradeableClientState interface for client types.
  • ICS07 Tendermint client now supports upgrade via UpgradeClient and UpgradeConsensusState methods.
  • ICS20 Transfer module now supports unordered channels.

v5 to v6:

  • Introduced migration for 27-interchain-accounts, transferring ownership of ICS27 channel capabilities from authentication modules to ICS27 controller submodule.
  • ICS27 controller submodule now includes MsgServer, providing standardized approach to integrating existing forms of authentication.
  • Updated default params in ICS27 host submodule to include AllowAllHostMsgs wildcard.
  • Removed SendTransfer function from ICS20, IBC transfers should now be initiated with MsgTransfer routed to ICS20 MsgServer.
  • Simplified SendPacket API in ICS04, callers no longer need to pass pre-constructed packet.
  • Updated NewKeeper function in ICS29 to remove paramSpace parameter.
  • Made several changes to IBC testing package, including simplified SendPacket API.

4. Add ibc-hooks as a custom module

Details

Further Documentation

Wasm hooks, an IBC middleware, enable ICS-20 token transfers to initiate contract calls, allowing cross-chain contract calls involving token movement. This addition is particularly useful for cross-chain swaps, a powerful primitive. The mechanism uses a memo field on every ICS20 transfer packet starting from IBC v3.4.0. If the memo field has a specific format, a wasm contract call is executed.

The CosmWasm MsgExecuteContract contains sender, contract, msg, and funds fields, with the sender replaced by an account representing the sender, prefixed by the channel and a wasm module prefix. The contract, msg, and funds fields are obtained from the ICS-20 packet metadata.

5. Add the token-factory module

Details

Further Documentation

The x/tokenfactory module enables accounts to create new tokens using the format factory/{creator address}/{subdenom}. This approach allows permissionless token minting since tokens are namespaced by creator addresses, eliminating the need to resolve name collisions. Accounts can create multiple denoms by providing a unique subdenom for each.

Upon creating a denom, the creator is granted "admin" privileges, empowering them to mint tokens to any account, burn tokens from any account, create transfers between two accounts, and change the admin. Future enhancements may expand admin capabilities. The ChangeAdmin functionality enables changing the master admin account or even removing admin privileges entirely. Admins can also share privileges with others using the x/authz module.

6. Enable the ica-controller module

Details

Further Documentation

The Interchain Accounts module is a Cosmos SDK implementation of the ICS-27 protocol, enabling cross-chain account management using IBC. Interchain Accounts differ from regular accounts by being controlled programmatically via IBC packets instead of using a private key.

The system involves a Host Chain, where the Interchain Account is registered, and a Controller Chain, which controls the account on the Host Chain. The Authentication Module on the Controller Chain manages the creation and management of Interchain Accounts. The SDK security model assumes that modules on a chain are trustworthy, and the ICS-27 implementation in ibc-go relies on this assumption for its security considerations, expecting other IBC application modules not to bind to ports within the ICS-27 namespace.

7. 🤝 Add the alliance module

Details

Further Documentation

Alliance is an open-source module based on the Cosmos SDK that fosters economic cooperation among blockchains through interchain staking. It aims to increase innovation, user adoption, and cross-chain collaboration by promoting bilateral economic alliances across Cosmos chains.

The module enables blockchains to trade yield with one another, similar to yield farming for Layer 1 (L1) protocols. Two chains integrate the Alliance module, determining which assets can be staked and assigning a Take Rate and Reward Weight to each asset. Users can then bridge their assets to other chains and stake them to earn Reward Weight.

There are several use cases for Alliance, including:

  1. Diversifying and augmenting staking yield: Chains can enhance their native staking yield using Alliance assets. Users can also diversify and boost their yield by staking on one chain and bridging to another.
  2. Attracting users, liquidity, and developers: By setting the Take Rate to 0%, blockchains can draw new users and liquidity from allied chain participants, leading to a positive feedback loop of increasing usage, liquidity, and dApp development.
  3. Incentivizing application developers: Alliance can provide L1 staking yield to app token stakers, rewarding users of promising apps with fees and inflation from the underlying L1.

Resources