v30

v30 Latest

🔧 BitBadges Chain Upgrade — v30
📦 [Release v30](https://github.com/BitBadges/bitbadgeschain/releases/tag/v30) • 🆕 [Latest Release](https://github.com/BitBadges/bitbadgeschain/releases/latest)

Upgrade Name: v30
Upgrade Block Height: 9905000
Estimated Time: 4/24/2026, 3:23:35 PM EST

Summary of update: v30 is a state-consistency and cleanup release. The headline change is a one-time migration that re-derives every collection's protocol-owned addresses (mint escrow, coin-backed paths, and coin-wrapper paths) under the current tokenization module name and moves any held bank balances to match — fixing a long-standing drift inherited from the v23 module rename. The release also removes the deprecated maps and anchor modules, consolidates the chain CLI into a single forwarder command, aligns the install instructions with the renamed bitbadges npm package, hardens approval validation for v29 time-check fields, fixes a pool-to-intermediate transfer regression, and pins release binaries for broader Linux compatibility.

🚨 Important Instructions for Node Operators
To successfully upgrade your node to v30 please follow these steps:

Download the New Binary
Download the latest v30 binary from the [release page](https://github.com/BitBadges/bitbadgeschain/releases/tag/v30).

Place Binary in the Correct Path
Move the new binary to:

<your_node_home>/cosmovisor/upgrades/v30/bin/
Ensure Correct Naming
Rename the binary file to:

bitbadgeschaind
This is required for nodes using the default Cosmovisor configuration.

Check Executable Permissions
Ensure the binary is executable:

chmod +x <your_node_home>/cosmovisor/upgrades/v30/bin/bitbadgeschaind
Verify Setup
Run the following to confirm the version and setup:

<your_node_home>/cosmovisor/upgrades/v30/bin/bitbadgeschaind version
Cosmovisor Will Auto-Switch
Cosmovisor will automatically switch to the new binary at the specified block height. If your node does not have the correct setup, it will halt and could be slashed.

📚 For full setup and operational details, see the [Run a Node documentation](https://docs.bitbadges.io/for-developers/bitbadges-blockchain/run-a-node).

📝 Notable Changes in v30

State migration

• Collection address re-derivation: every existing collection has its mintEscrowAddress, cosmosCoinBackedPath.address, and each cosmosCoinWrapperPath.address recomputed under the tokenization module name (previously stored under the legacy badges name from before the v23 rename). All bank balances at the old addresses are moved to the new ones via bankKeeper.SendCoins, the reserved-protocol-address flag is flipped from old to new, and the stored address on the collection is overwritten. Idempotent — collections where old and new derivations match (anything created post-rename) are skipped.

Module removals

• x/maps removed: the deprecated maps module and all of its proto definitions, generated bindings, gRPC clients, CLI commands, and runtime registration are deleted from the chain.
• x/anchor removed: the deprecated anchor module is removed alongside maps with the same scope.
• Stale Pulsar bindings cleaned out alongside the module removals.

Approval validation and transfer fixes

• AltTimeChecks validation tightened: ValidateBasic now rejects out-of-range values for the v29 fields offlineMonths (1–12), offlineDaysOfMonth (1–31), offlineWeeksOfYear (1–53), and timezoneOffsetMinutes (-840–840). Defense-in-depth bounds were also added on the consumer side.
• Pool-to-intermediate swap regression fixed: SwapAndActionHooks and AutoApproveAllIncomingTransfers no longer drop the synthetic all-incoming approval during pool→intermediate transfers when prioritized-only filtering was active. The filter now matches against the prioritized outgoing approval, restoring the intended IBC swap path.

CLI consolidation

• Three separate forwarder commands (sdk, api, builder) are collapsed into a single generic cli command. Any top-level bitbadges-cli subcommand is now reachable as bitbadgeschaind cli <subcommand> [args...] — for example bitbadgeschaind cli sdk review tx.json, bitbadgeschaind cli builder templates vault --backing-coin USDC, bitbadgeschaind cli config set apiKey <key>. New JS-side subcommands no longer require Go changes. The shorter sdk / api / builder aliases shipped in earlier releases are removed; scripts must prefix with cli.
• Help-text and example footers updated chain-wide to reflect the cli prefix.

SDK package rename

• The npm package bitbadgesjs-sdk was renamed to bitbadges. The chain binary's npx delegation, the install.sh one-liner, the release CI workflow, and all CLI help text now reference npm install -g bitbadges and npx -p bitbadges bitbadges-cli.

Release infrastructure

• Linux release binaries are now built on Ubuntu 22.04 instead of ubuntu-latest so they link against an older glibc and run on stable LTS hosts (Ubuntu 22.04, Debian 12, RHEL 9 derivatives). Operators on those distros who hit a glibc mismatch on previous releases will not see it on v30.

Dependency maintenance

• github.com/hashicorp/go-getter 1.7.9 → 1.8.6
• go.opentelemetry.io/otel/sdk 1.40.0 → 1.43.0
• github.com/aws/aws-sdk-go-v2/service/s3 and aws/protocol/eventstream patch bumps

v29

v29 Latest

🔧 BitBadges Chain Upgrade — v29
📦 [Release v29](https://github.com/BitBadges/bitbadgeschain/releases/tag/v29) • 🆕 [Latest Release](https://github.com/BitBadges/bitbadgeschain/releases/latest)

Upgrade Name: v29
Upgrade Block Height: 9768000
Estimated Time: 4/16/2026, 10:30:28 PM

Summary of update: v29 introduces voting challenge enhancements (reset after execution, delay after quorum), expanded time-based restrictions (offlineMonths, offlineDaysOfMonth, offlineWeeksOfYear), UserApprovalSettings for per-approval user preferences, amount scaling with max multiplier caps, self-referencing mustOwnTokens, re-added allowed denoms enforcement for coin transfers, granular approval change events, enriched Msg responses with review items, and CLI/tooling improvements including SDK/API cobra commands and cross-platform release CI.

🚨 Important Instructions for Node Operators
To successfully upgrade your node to v29 please follow these steps:

Download the New Binary
Download the latest v29 binary from the [release page](https://github.com/BitBadges/bitbadgeschain/releases/tag/v29).

Place Binary in the Correct Path
Move the new binary to:

<your_node_home>/cosmovisor/upgrades/v29/bin/
Ensure Correct Naming
Rename the binary file to:

bitbadgeschaind
This is required for nodes using the default Cosmovisor configuration.

Check Executable Permissions
Ensure the binary is executable:

chmod +x <your_node_home>/cosmovisor/upgrades/v29/bin/bitbadgeschaind
Verify Setup
Run the following to confirm the version and setup:

<your_node_home>/cosmovisor/upgrades/v29/bin/bitbadgeschaind version
Cosmovisor Will Auto-Switch
Cosmovisor will automatically switch to the new binary at the specified block height. If your node does not have the correct setup, it will halt and could be slashed.

📚 For full setup and operational details, see the [Run a Node documentation](https://docs.bitbadges.io/for-developers/bitbadges-blockchain/run-a-node).

📝 Notable Changes in v29

• Voting challenge enhancements: resetAfterExecution flag resets votes after execution, delayAfterQuorum adds configurable delay between quorum and execution
• AltTimeChecks expansion: new offlineMonths, offlineDaysOfMonth, offlineWeeksOfYear fields for granular time-based approval restrictions
• UserApprovalSettings: new per-approval settings container with UserRoyalties (migrated from old standalone field), extensible for future features
• Granular approval change events: emitted on every approval modification for better indexer tracking
• Enriched Msg responses: MsgUniversalUpdateCollection responses now include reviewItems for client-side validation
• CLI improvements: sdk and api cobra commands delegating to Node.js bitbadges-cli, documentation links in all --help output
• Cross-platform release CI: automated builds for Linux/macOS/Windows with one-liner installer
• Security: overflow guards on store key allocations, go-jose/v4 bump to 4.1.4

v28

v28 Latest

🔧 BitBadges Chain Upgrade — v28
📦 [Release v28](https://github.com/BitBadges/bitbadgeschain/releases/tag/v28) • 🆕 [Latest Release](https://github.com/BitBadges/bitbadgeschain/releases/latest)

Upgrade Name: v28
Upgrade Block Height: 9591000
Estimated Time: 4/6/2026, 11:45:31 AM EST

Summary of update: v28 adds amount scaling for flexible token pricing, mustOwnTokens self-reference for on-chain goal tracking, allowSpecialWrapping guardrails, and various fixes for event emission and Solidity type parity.

🚨 Important Instructions for Node Operators
To successfully upgrade your node to v28 please follow these steps:

Download the New Binary
Download the latest v28 binary from the [release page](https://github.com/BitBadges/bitbadgeschain/releases/tag/v28).

Place Binary in the Correct Path
Move the new binary to:

<your_node_home>/cosmovisor/upgrades/v28/bin/
Ensure Correct Naming
Rename the binary file to:

bitbadgeschaind
This is required for nodes using the default Cosmovisor configuration.

Check Executable Permissions
Ensure the binary is executable:

chmod +x <your_node_home>/cosmovisor/upgrades/v28/bin/bitbadgeschaind
Verify Setup
Run the following to confirm the version and setup:

<your_node_home>/cosmovisor/upgrades/v28/bin/bitbadgeschaind version
Cosmovisor Will Auto-Switch
Cosmovisor will automatically switch to the new binary at the specified block height. If your node does not have the correct setup, it will halt and could be slashed.

📚 For full setup and operational details, see the [Run a Node documentation](https://docs.bitbadges.io/for-developers/bitbadges-blockchain/run-a-node).

📝 Notable Changes in v28

• Amount Scaling (allowAmountScaling + maxScalingMultiplier) — Allows predetermined balances to scale dynamically based on a user-provided multiplier. Enables flexible pricing models (e.g., crowdfund deposits where users choose their contribution amount). Includes a configurable cap via maxScalingMultiplier to prevent abuse.
• mustOwnTokens Self-Reference (collectionId: 0) — Setting collectionId to 0 in mustOwnTokens criteria now references the current collection itself. Resolved at store time in the MsgUniversalUpdateCollection handler and at runtime in the approval checker. Enables on-chain goal tracking (e.g., crowdfund success/refund gating) without off-chain verifiers.
• allowSpecialWrapping Guardrails — Added parity with allowBackedMinting guardrails. Prevents unauthorized wrapping operations when the collection invariants don't explicitly allow it. Includes mustPrioritize enforcement in test fixtures.
• Scaling Multiplier in PrecalculationOptions — Added scalingMultiplier field to PrecalculationOptions so clients can precalculate balances with a specific scaling factor.
• GetBalanceForToken Query — New query endpoint and CLI command to fetch a specific token's balance for a given address.
• Additional Allowed Denoms — Extended DefaultParams to include additional allowed denominations.
• Event Emission Fixes — Emit msg JSON attribute in CastVote and all dynamic store events for better indexer compatibility. Removed debug logging.
• Solidity Type Parity — Added allowAmountScaling and maxScalingMultiplier fields to Solidity type definitions for EVM compatibility.
• Deterministic Error Messages — Scaling-related addPotentialError calls now use deterministic error messages for consistent error handling.
• Migration — All existing IncrementedBalances are migrated to include allowAmountScaling: false and maxScalingMultiplier: 0 defaults.

v27

v27 Latest

🔧 BitBadges Chain Upgrade — v27
📦 [Release v27](https://github.com/BitBadges/bitbadgeschain/releases/tag/v27) • 🆕 [Latest Release](https://github.com/BitBadges/bitbadgeschain/releases/latest)

Upgrade Name: v27
Upgrade Block Height: 9380000
Estimated Time: 3/24/2026, 6:53:57 PM

Summary of update: v27 strengthens collection invariants enforcement, improves IBC transfer handling in GAMM and custom-hooks modules, and adds validation guardrails for backed-minting approvals.

🚨 Important Instructions for Node Operators
To successfully upgrade your node to v27 please follow these steps:

Download the New Binary
Download the latest v27 binary from the [release page](https://github.com/BitBadges/bitbadgeschain/releases/tag/v27).

Place Binary in the Correct Path
Move the new binary to:

<your_node_home>/cosmovisor/upgrades/v27/bin/
Ensure Correct Naming
Rename the binary file to:

bitbadgeschaind
This is required for nodes using the default Cosmovisor configuration.

Check Executable Permissions
Ensure the binary is executable:

chmod +x <your_node_home>/cosmovisor/upgrades/v27/bin/bitbadgeschaind
Verify Setup
Run the following to confirm the version and setup:

<your_node_home>/cosmovisor/upgrades/v27/bin/bitbadgeschaind version
Cosmovisor Will Auto-Switch
Cosmovisor will automatically switch to the new binary at the specified block height. If your node does not have the correct setup, it will halt and could be slashed.

📚 For full setup and operational details, see the [Run a Node documentation](https://docs.bitbadges.io/for-developers/bitbadges-blockchain/run-a-node).

📝 Notable Changes in v27

• Enforced invariant immutability: Collection invariants (supply caps, transfer protections, pool creation flags) are now strictly enforced as creation-only fields, matching their intended design as permanent guarantees. Once set at collection creation, invariants cannot be changed.
• Improved IBC transfer handling: GAMM and custom-hooks modules now route cross-chain token transfers through the standard IBC transfer keeper, improving compatibility with the broader IBC ecosystem and ensuring proper token accounting across chains.
• Backed-minting approval validation: New validation logic for allowBackedMinting approvals ensures backing paths and conversion configs are consistent at the time of approval creation, catching misconfigurations early.

v26

v26 Latest

🔧 BitBadges Chain Upgrade — v26
📦 [Release v26](https://github.com/BitBadges/bitbadgeschain/releases/tag/v26) • 🆕 [Latest Release](https://github.com/BitBadges/bitbadgeschain/releases/latest)

Upgrade Name: v26
Upgrade Block Height: [INSERT_BLOCK_HEIGHT]
Estimated Time: [INSERT_DATE_TIME]

Summary of update: v26 adds custom-hooks transfer_tokens for IBC mint/transfer, upgrades cosmos-sdk and cosmos/evm, refactors tokenization address handling and transfer keeper usage, and improves tokenization module.

🚨 Important Instructions for Node Operators
To successfully upgrade your node to v26 please follow these steps:

Download the New Binary
Download the latest v26 binary from the [release page](https://github.com/BitBadges/bitbadgeschain/releases/tag/v26).

Place Binary in the Correct Path
Move the new binary to:

<your_node_home>/cosmovisor/upgrades/v26/bin/
Ensure Correct Naming
Rename the binary file to:

bitbadgeschaind
This is required for nodes using the default Cosmovisor configuration.

Check Executable Permissions
Ensure the binary is executable:

chmod +x <your_node_home>/cosmovisor/upgrades/v26/bin/bitbadgeschaind
Verify Setup
Run the following to confirm the version and setup:

<your_node_home>/cosmovisor/upgrades/v26/bin/bitbadgeschaind version
Cosmovisor Will Auto-Switch
Cosmovisor will automatically switch to the new binary at the specified block height. If your node does not have the correct setup, it will halt and could be slashed.

📚 For full setup and operational details, see the [Run a Node documentation](https://docs.bitbadges.io/for-developers/bitbadges-blockchain/run-a-node).

📝 Notable Changes in v26

• Custom-hooks transfer_tokens: Added support for the transfer_tokens action in the custom-hooks module, enabling minting and transferring of BitBadges tokens via IBC. New types and conversion functions handle transfer data with validation for collection IDs and recovery address requirements.
• Dependency and transfer refactor: Updated cosmos-sdk to v0.53.6 and cosmos/evm to v0.6.0. Transfer handling now uses the new ibc-go transfer keeper for improved compatibility with ERC20 conversions and tokenization integration.
• Tokenization address handling: Refactored tokenization module with new EVM↔bech32 address conversion helpers and removed the MigrateCollectionStats function to streamline upgrades. Precompile methods and JSON unmarshaling now use the new conversions for consistent address handling.

v25

v25 Latest

🔧 BitBadges Chain Upgrade — v25
📦 [Release v25](https://github.com/BitBadges/bitbadgeschain/releases/tag/v25) • 🆕 [Latest Release](https://github.com/BitBadges/bitbadgeschain/releases/latest)

Upgrade Name: v25
Upgrade Block Height: 8944000
Estimated Time: 2/28/2026, 10:58:09 AM (1 days 22 hours 0 minutes 2928 seconds)

Summary of update: v25 adds custom read-only EVM queries for approvals and invariants, simplifies tokenization precompile return types for easier integration, and improves collection stats tracking with a dedicated GetCollectionStats query and precompile method.

🚨 Important Instructions for Node Operators
To successfully upgrade your node to v25 please follow these steps:

Download the New Binary
Download the latest v25 binary from the [release page](https://github.com/BitBadges/bitbadgeschain/releases/tag/v25).

Place Binary in the Correct Path
Move the new binary to:

<your_node_home>/cosmovisor/upgrades/v25/bin/
Ensure Correct Naming
Rename the binary file to:

bitbadgeschaind
This is required for nodes using the default Cosmovisor configuration.

Check Executable Permissions
Ensure the binary is executable:

chmod +x <your_node_home>/cosmovisor/upgrades/v25/bin/bitbadgeschaind
Verify Setup
Run the following to confirm the version and setup:

<your_node_home>/cosmovisor/upgrades/v25/bin/bitbadgeschaind version
Cosmovisor Will Auto-Switch
Cosmovisor will automatically switch to the new binary at the specified block height. If your node does not have the correct setup, it will halt and could be slashed.

📚 For full setup and operational details, see the [Run a Node documentation](https://docs.bitbadges.io/for-developers/bitbadges-blockchain/run-a-node).

📝 Notable Changes in v25

• Custom read-only EVM queries (approvals & invariants): Collection approvals and post-transfer invariants can now require one or more read-only EVM contract calls. You specify a contract address, calldata (with placeholders like $sender, $recipient, $collectionId), expected result, and comparison operator. Transfers are allowed only if the contract returns the expected value (e.g. pass/fail checks for balance, holder count, or other on-chain conditions).
• Return type simplifications: Tokenization precompile return types have been simplified for easier EVM/Solidity integration. Conversions and response shapes are standardized so clients can decode responses more predictably.
• Better collection stats tracking: Collection-level stats (e.g. unique holder count) are now tracked and exposed via a dedicated CollectionStats store and the GetCollectionStats gRPC and precompile query. Stats are updated on migrations and transfers for accurate, queryable metrics per collection.
• EVM query challenge validation: New validation and gas limits for EVM query challenges (e.g. max gas per challenge and total across challenges) to keep approval and invariant checks safe and bounded.
• Precompile getCollectionStats: The tokenization precompile now exposes getCollectionStats so Solidity contracts can read collection stats (e.g. holder count) for use in invariants or other logic.
• Fix IBC route not found error: Resolved the IBC route not found error to ensure correct IBC module routing and transfers.

v24

v24 Latest

🔧 BitBadges Chain Upgrade — v24
📦 [Release v24](https://github.com/BitBadges/bitbadgeschain/releases/tag/v24) • 🆕 [Latest Release](https://github.com/BitBadges/bitbadgeschain/releases/latest)

Upgrade Name: v24
Upgrade Block Height: 8890000
Estimated Time: 2/24/2026, 11:19:18 AM EST

Summary of update: This upgrade removes CosmWASM, adds full EVM compatibility with JSON-RPC API and ERC20 support, renames the badges module to tokenization, and introduces Interchain Queries for cross-chain token ownership verification.

🚨 Important Instructions for Node Operators
To successfully upgrade your node to v24 please follow these steps:

Download the New Binary
Download the latest v24 binary from the [release page](https://github.com/BitBadges/bitbadgeschain/releases/tag/v24).

Place Binary in the Correct Path
Move the new binary to:

<your_node_home>/cosmovisor/upgrades/v24/bin/
Ensure Correct Naming
Rename the binary file to:

bitbadgeschaind
This is required for nodes using the default Cosmovisor configuration.

Check Executable Permissions
Ensure the binary is executable:

chmod +x <your_node_home>/cosmovisor/upgrades/v24/bin/bitbadgeschaind
Verify Setup
Run the following to confirm the version and setup:

<your_node_home>/cosmovisor/upgrades/v24/bin/bitbadgeschaind version
Cosmovisor Will Auto-Switch
Cosmovisor will automatically switch to the new binary at the specified block height. If your node does not have the correct setup, it will halt and could be slashed.

📚 For full setup and operational details, see the [Run a Node documentation](https://docs.bitbadges.io/for-developers/bitbadges-blockchain/run-a-node).

⚠️ CosmWASM Removal and EVM Addition

This upgrade includes major architectural changes:

CosmWASM Removal:

• The CosmWASM module has been completely removed from the chain
• WASM stores (wasm-store and wasmx-store) are deleted during the upgrade
• No WASM library installation is required - the libwasmvm library is no longer needed
• If you previously had libwasmvm installed, you can optionally remove it (not required)

EVM Integration:

• Full Ethereum Virtual Machine (EVM) compatibility has been added via the cosmos/evm module
• New stores are added: evm, erc20, feemarket, and precisebank
• The chain now supports:
  • JSON-RPC API - Standard Ethereum JSON-RPC endpoints (port 8545)
  • ERC20 Wrapping - Native Cosmos coins can be wrapped as ERC20 tokens
  • Custom Precompiles - Direct access to tokenization, Gamm, and SendManager modules from Solidity
  • Dual Wallet Support - Same address works for both Cosmos and EVM transactions
  • EVM Chain IDs: Mainnet (50024), Testnet (50025), Local dev (90123)

Precompiles Available:

• Default Cosmos precompiles (0x0800-0x0806): Staking, Distribution, ICS20 (IBC), Vesting, Bank, Governance, Slashing
• Custom BitBadges precompiles:
  • 0x1001 - Tokenization precompile (create collections, transfer tokens, manage approvals)
  • 0x1002 - Gamm precompile (AMM liquidity pool operations)
  • 0x1003 - SendManager precompile (send native Cosmos coins from EVM)

📝 Notable Changes in v24

• CosmWASM removed - WASM and WASMX modules completely removed from the chain
• EVM integration added - Full Ethereum Virtual Machine compatibility via cosmos/evm module
• ERC20 support - Native Cosmos coins can be wrapped as ERC20 tokens
• Custom precompiles - Tokenization, Gamm, and SendManager accessible from Solidity smart contracts
• JSON-RPC API - Standard Ethereum JSON-RPC endpoints for Web3 compatibility
• Badges module renamed to tokenization - Module renamed throughout the codebase (store key badges → tokenization, all data preserved)
• Store migrations - WASM stores deleted, EVM stores (evm, erc20, feemarket, precisebank) added
• EVM Chain ID validation - Chain ID is automatically validated and set during upgrade based on binary build configuration
• Binary builds - Production binaries are built with chain IDs compiled in (mainnet: 50024, testnet: 50025)
• Interchain Queries (ICQ) - Cross-chain token ownership verification via IBC (see below)

🔧 For Developers

Module Rename:

• The badges module has been renamed to tokenization throughout the codebase
• All existing data is preserved - the store key is renamed during migration
• API endpoints, CLI commands, and module paths now use tokenization instead of badges
• This is a cosmetic change - all functionality remains the same

EVM Integration:

• Connect to EVM JSON-RPC at port 8545 (mainnet: https://evm-rpc.bitbadges.io, testnet: https://evm-rpc-testnet.bitbadges.io)
• Use standard Ethereum tooling: MetaMask, ethers.js, web3.js, Hardhat, Foundry
• Precompile addresses are fixed and documented in the EVM Integration Guide
• Chain IDs are set at build time - ensure you're using the correct binary for your network

Breaking Changes:

• CosmWASM contracts are no longer supported - migrate any WASM-based functionality to Solidity
• Module import paths changed from x/badges to x/tokenization (for Go developers)

🌐 Interchain Queries (ICQ)

BitBadges now supports Interchain Queries that allow other Cosmos chains to verify token ownership without transferring tokens. This enables cross-chain gating, proof-of-ownership, and other interoperability use cases.

Two Query Types:

1. OwnershipQuery - Streamlined lookup for a single (tokenId, ownershipTime) → returns exact balance amount
2. FullBalanceQuery - Returns complete UserBalanceStore (balances, approvals, permissions)

Capabilities:

• Query exact balance amount for a specific token ID and ownership time from any IBC-connected chain
• Get full balance store including approvals and permissions
• Bulk queries for up to 100 addresses per packet
• Support for both bech32 and EVM hex address formats

IBC Channel Setup:

• Port: tokenization
• Version: tokenization-1
• Channel Ordering: UNORDERED

Precompile Query Methods (Updated):

• getBalanceAmount - Now takes single tokenId and ownershipTime (not arrays)
• getTotalSupply - Now takes single tokenId and ownershipTime (not arrays)
• getBalance - Returns full UserBalanceStore (unchanged)

Use Cases:

• Cross-chain token gating
• DeFi collateral verification
• Multi-chain identity credentials
• Cross-chain governance voting weights
• Cross-chain approval checking

📚 See Cross-Chain Queries documentation for implementation details.

v23

v23 Latest

🔧 BitBadges Chain Upgrade — v23
📦 [Release v23](https://github.com/BitBadges/bitbadgeschain/releases/tag/v23) • 🆕 [Latest Release](https://github.com/BitBadges/bitbadgeschain/releases/latest)

Upgrade Name: v23
Upgrade Block Height: 8400000
Estimated Time: 1/28/2026, 1:58:28 PM EST

Summary of update: This upgrade removes support for alt-chain signatures, adds allowBackedMinting and allowSpecialWrapping flags that must be toggled on for special handling, and introduces ownershipCheckParty for dynamic stores.

🚨 Important Instructions for Node Operators
To successfully upgrade your node to v23 please follow these steps:

Download the New Binary
Download the latest v23 binary from the [release page](https://github.com/BitBadges/bitbadgeschain/releases/tag/v23).

Place Binary in the Correct Path
Move the new binary to:

<your_node_home>/cosmovisor/upgrades/v23/bin/
Ensure Correct Naming
Rename the binary file to:

bitbadgeschaind
This is required for nodes using the default Cosmovisor configuration.

Check Executable Permissions
Ensure the binary is executable:

chmod +x <your_node_home>/cosmovisor/upgrades/v23/bin/bitbadgeschaind
Verify Setup
Run the following to confirm the version and setup:

<your_node_home>/cosmovisor/upgrades/v23/bin/bitbadgeschaind version
Cosmovisor Will Auto-Switch
Cosmovisor will automatically switch to the new binary at the specified block height. If your node does not have the correct setup, it will halt and could be slashed.

📚 For full setup and operational details, see the [Run a Node documentation](https://docs.bitbadges.io/for-developers/bitbadges-blockchain/run-a-node).

📝 Notable Changes in v23

• Removed any support for alt-chain signatures
• Added allowBackedMinting and allowSpecialWrapping flags that must be toggled on for special handling
• Added ownershipCheckParty for dynamic stores

v22

v22 Latest

🔧 BitBadges Chain Upgrade — v22
📦 [Release v22](https://github.com/BitBadges/bitbadgeschain/releases/tag/v22) • 🆕 [Latest Release](https://github.com/BitBadges/bitbadgeschain/releases/latest)

Upgrade Name: v22
Upgrade Block Height: 8030000
Estimated Time: 1/9/2026, 11:27:42 AM EST

Summary of update: This upgrade introduces significant improvements to the BitBadges chain including a new sendmanager module for enhanced token routing, custom checker system for flexible validation, removal of timeline-based functionality for simplified API, and various other API simplifications. The sendmanager module enables alias denom routing for seamless handling of both standard coins and custom token types. Custom checkers allow developers to add validation logic at approval, transfer, and collection levels. The timeline removal simplifies the API by converting timeline-based fields (e.g., standardsTimeline → standards, managerTimeline → manager) to direct values, making the interface more straightforward. Additionally, several API changes simplify the codebase by removing deprecated fields and reverting to boolean-based dynamic stores.

🚨 Important Instructions for Node Operators
To successfully upgrade your node to v22 please follow these steps:

Download the New Binary
Download the latest v22 binary from the [release page](https://github.com/BitBadges/bitbadgeschain/releases/tag/v22).

Place Binary in the Correct Path
Move the new binary to:

<your_node_home>/cosmovisor/upgrades/v22/bin/
Ensure Correct Naming
Rename the binary file to:

bitbadgeschaind
This is required for nodes using the default Cosmovisor configuration.

Check Executable Permissions
Ensure the binary is executable:

chmod +x <your_node_home>/cosmovisor/upgrades/v22/bin/bitbadgeschaind
Verify Setup
Run the following to confirm the version and setup:

<your_node_home>/cosmovisor/upgrades/v22/bin/bitbadgeschaind version
Cosmovisor Will Auto-Switch
Cosmovisor will automatically switch to the new binary at the specified block height. If your node does not have the correct setup, it will halt and could be slashed.

📚 For full setup and operational details, see the [Run a Node documentation](https://docs.bitbadges.io/for-developers/bitbadges-blockchain/run-a-node).

📝 Notable Changes in v22

• New SendManager Module: Added a new sendmanager module that provides alias denom routing capabilities, allowing seamless handling of both standard Cosmos SDK coins and custom token types (e.g., badgeslp:). The module includes MsgSendWithAliasRouting and QueryBalance endpoints with full CLI support.
• Custom Checker System: Introduced a flexible custom checker system allowing developers to register custom validation logic at three levels: approval criteria checkers (for approval processing), global transfer checkers (for pre-transfer validation), and collection verifiers (for collection-level invariants). All checkers can be registered in app.go for easy integration.
• API Simplifications: Removed the numAttempts field from relevant objects to simplify the API and reduce complexity.
• Address List Changes: CreateAddressList objects no longer require the createdBy field, simplifying address list creation.
• Dynamic Stores Reverted to Booleans: Dynamic stores have been reverted back to using boolean values instead of more complex types, improving performance and simplicity.
• Prioritized Approvals Refinement: Prioritized approvals are now only used for special backing and/or minting scenarios, making the approval system more focused and efficient.
• SendManager Refactoring: Significant refactoring of token sending logic to use the new sendmanager module, improving code organization and maintainability while enabling better support for alias denoms.
• Timeline Functionality Removal: Removed all timeline-based functionality from the BitBadges API to simplify the interface. Timeline fields have been converted to direct values (e.g., standardsTimeline → standards, managerTimeline → manager, collectionMetadataTimeline → collectionMetadata). Permissions have been updated accordingly, with TimedUpdatePermission removed and TimedUpdateWithTokenIdsPermission migrated to TokenIdsActionPermission. Migration logic automatically extracts the current value from timeline fields at the block time and converts them to the simplified format. This change affects both the badges and maps modules, making the API more intuitive and easier to use.
• Hardcoded bb1 Addresses for Ownership Check Party: Added hardcoded bb1 addresses for ownershipCheckParty to improve validation and security.
• Voting Challenges and MsgCastVote: Introduced voting challenges functionality along with MsgCastVote message type to enable voting mechanisms within the chain.
• On-Chain Path/Alias/Denom Unit Metadata: Path, alias, and denom unit metadata are now stored on-chain, providing better accessibility and consistency.
• Path/Alias/Denom Split and Redesign: Implemented a split between alias and cosmos wrapper paths, with a redesign that includes amounts and refactoring for improved clarity and functionality.
• ETH Signature Leaf Handling: Added support for handling ETH signature leaves, enhancing cross-chain compatibility and validation capabilities.
• Precalculation Options Refactoring: Precalculation options have been moved to the precalculateBalancesFromApproval object, improving organization and making the API more intuitive.

v21

v21 Latest

🔧 BitBadges Chain Upgrade — v21
📦 [Release v21](https://github.com/BitBadges/bitbadgeschain/releases/tag/v21) • 🆕 [Latest Release](https://github.com/BitBadges/bitbadgeschain/releases/latest)

Upgrade Name: v21
Upgrade Block Height: 7510000
Estimated Time: 12/14/2025, 10:52:18 AM EST

Summary of update: This upgrade introduces the mustPrioritize flag for approval criteria to control auto-scan functionality, adds support for badgeslp wrapped denominations in coin transfers, and improves validation logic for better code quality and readability.

🚨 Important Instructions for Node Operators
To successfully upgrade your node to v21 please follow these steps:

Download the New Binary
Download the latest v21 binary from the [release page](https://github.com/BitBadges/bitbadgeschain/releases/tag/v21).

Place Binary in the Correct Path
Move the new binary to:

<your_node_home>/cosmovisor/upgrades/v21/bin/
Ensure Correct Naming
Rename the binary file to:

bitbadgeschaind
This is required for nodes using the default Cosmovisor configuration.

Check Executable Permissions
Ensure the binary is executable:

chmod +x <your_node_home>/cosmovisor/upgrades/v21/bin/bitbadgeschaind
Verify Setup
Run the following to confirm the version and setup:

<your_node_home>/cosmovisor/upgrades/v21/bin/bitbadgeschaind version
Cosmovisor Will Auto-Switch
Cosmovisor will automatically switch to the new binary at the specified block height. If your node does not have the correct setup, it will halt and could be slashed.

📚 For full setup and operational details, see the [Run a Node documentation](https://docs.bitbadges.io/for-developers/bitbadges-blockchain/run-a-node).

📝 Notable Changes in v21

• Added mustPrioritize flag to approval criteria (collection, incoming, and outgoing) to control auto-scan functionality - when set to true, approvals must be explicitly prioritized in PrioritizedApprovals to be used
• Added support for badgeslp wrapped denominations in coin transfers - badgeslp: prefixed denoms now use badge module transfer functions for underlying badge transfers (still subject to allowed denoms though)
• Improved validation logic for better code quality and readability with more restrictive checks
• Improved auto scannability functionality to not include amount threhsolds or max num transfer thresholds by default
• Fixed issue with IBC denom expansion in coin transfers