Cosmos Wrapper Paths

Cosmos Wrapper Paths enable wrapping between BitBadges tokens and native Cosmos SDK coin asset types, making tokens IBC-compatible. These paths automatically mint and burn tokens when transferring to/from specific wrapper addresses. These transfers to/from are handled within the tokens module, so you can set up customizable logic for how these transfers are handled.

Important: Since wrapper addresses are uncontrollable (no private keys), approval design requires careful consideration. You must override the wrapper address's user-level approvals where necessary using collection approvals to ensure wrapping/unwrapping functions properly.

Auto-Generating Wrapper Addresses

You can programmatically generate wrapper addresses using the bitbadgesjs-sdk npm package. Note that the address is generated based on the denom set. It is just the custom denom, not the full badges:collectionId:denom format.

import { generateAliasAddressForDenom } from 'bitbadgesjs-sdk';

const denom = 'utoken1';
const wrapperAddress = generateAliasAddressForDenom(denom);
console.log('Wrapper Address:', wrapperAddress);

Transferability Requirements

Even though wrapper addresses are special addresses, they are still subject to the same transferability requirements as any other address. This means that you can user-gate, rate-limit, or anything else you can do with an address and its transferability.

This allows you to build complex wrapping / unwrapping logic. For example:

$2500 per day withdrawal limit
Must KYC on way out
Or any other logic you can think of

Behind the scenes, think of this address as an external contract that updates its approvals dynamically. So, wraps/unwraps are technically treated as initiated by the user but approved by the address itself.

Proto Definition

message CosmosCoinWrapperPathAddObject {
  string denom = 1;
  repeated Balance balances = 2;
  string symbol = 3;
  repeated DenomUnit denomUnits = 4;
  bool allowOverrideWithAnyValidToken = 5;
}

message DenomUnit {
  string decimals = 1 [(gogoproto.customtype) = "Uint", (gogoproto.nullable) = false];
  string symbol = 2;
  bool isDefaultDisplay = 3;
}

Configuration Fields

Denom

Base denomination - The fundamental unit name for the wrapped coin. For the full Cosmos denomination, it will be "badges:collectionId:denom"
{id} placeholder support - You can use {id} in the denom to dynamically replace it with the actual token ID during transfers if allowOverrideWithAnyValidToken is true

Symbol

Display symbol - Human-readable symbol for the wrapped asset

Balances

Custom conversion rates - Defines which tokens and ownership times participate in wrapping and how many tokens are wrapped for each native coin unit

Denomination Units

Multiple denomination units allow for different display formats:

Decimals

Precision level - Number of decimal places for this unit
Conversion factor - How this unit relates to the base denomination

Symbol

Unit symbol - Symbol for this specific denomination unit
Different from base - Can differ from the main symbol
Context-specific - Used in appropriate contexts (micro, milli, etc.)

Default Display

Primary unit - Which unit is shown by default in interfaces
Only one default - Only one unit can be marked as default display. If none are marked as default, the base level with 0 decimals is shown by default.
User experience - Determines what users see first

Allow Override With Any Valid Token

Dynamic token ID handling - When true, allows the wrapper to accept any SINGLE valid token ID from the collection's validTokenIds range
Override conversion balances - Temporarily overrides the balances field's token ID ranges with the actual token ID being transferred
Validation required - The transferred token ID must be within the collection's valid token ID range
Use case - Useful when you want a single wrapper path to handle multiple token IDs dynamically

Example with {id} Placeholder

{
    "denom": "utoken{id}",
    "symbol": "TOKEN:{id}",
    "balances": [
        {
            "amount": "1",
            "tokenIds": [{ "start": "1", "end": "1" }],
            "ownershipTimes": [{ "start": "1", "end": "18446744073709551615" }]
        }
    ],
    "denomUnits": [
        {
            "decimals": "6",
            "symbol": "TOKEN",
            "isDefaultDisplay": true
        }
    ],
    "allowOverrideWithAnyValidToken": true
}

When transferring token ID 5, the final denomination becomes utoken5.

Allow Override With Any Valid Token

This feature provides flexibility in handling different token IDs within a single wrapper path.

How It Works

Validation Check - Verifies the transferred token ID is within the collection's validTokenIds range
Dynamic Override - Temporarily replaces the wrapper's token ID ranges with the actual token ID being transferred
Conversion - Uses the overridden token ID for the conversion calculation

Example with Override Enabled

{
    "denom": "utoken",
    "symbol": "TOKEN",
    "balances": [
        {
            "amount": "1",
            "tokenIds": [{ "start": "1", "end": "1" }], // These technically don't matter since we can override the token IDs during conversion
            "ownershipTimes": [{ "start": "1", "end": "18446744073709551615" }]
        }
    ],
    "denomUnits": [
        {
            "decimals": "6",
            "symbol": "TOKEN",
            "isDefaultDisplay": true
        }
    ],
    "allowOverrideWithAnyValidToken": true
}

This wrapper can now handle any token ID from 1-100 (assuming the collection's validTokenIds includes that range), dynamically overriding the token ID during conversion.

Usage Examples

Basic Wrapper Path

{
    "denom": "utoken1",
    "symbol": "TOKEN1",
    "balances": [
        {
            "amount": "1",
            "tokenIds": [{ "start": "1", "end": "1" }],
            "ownershipTimes": [{ "start": "1", "end": "18446744073709551615" }]
        }
    ],
    "denomUnits": [
        {
            "decimals": "6",
            "symbol": "TOKEN1",
            "isDefaultDisplay": true
        }
    ],
    "allowOverrideWithAnyValidToken": false
}

Multi-Unit Display System

{
    "denom": "utoken",
    "symbol": "TOKEN",
    "balances": [
        {
            "amount": "1",
            "tokenIds": [{ "start": "1", "end": "100" }],
            "ownershipTimes": [{ "start": "1", "end": "18446744073709551615" }]
        }
    ],
    "denomUnits": [
        {
            "decimals": "3",
            "symbol": "mtoken",
            "isDefaultDisplay": false
        },
        {
            "decimals": "6",
            "symbol": "TOKEN",
            "isDefaultDisplay": true
        }
    ],
    "allowOverrideWithAnyValidToken": false
}

This creates a system where:

utoken is the base unit (smallest denomination)
mtoken = 1,000 utoken (milli-token)
TOKEN = 1,000,000 utoken (full token, default display)

Use Cases

IBC Transfers

Cross-chain transfers - Send wrapped tokens to other Cosmos chains
DeFi integration - Use wrapped tokens in Cosmos DeFi protocols
Liquidity provision - Add wrapped tokens to AMM pools

Multi-Chain Ecosystems

Ecosystem bridges - Connect BitBadges to broader Cosmos ecosystem
Shared liquidity - Participate in cross-chain liquidity pools
Governance tokens - Use wrapped tokens in governance across chains

Trading and Exchange

DEX compatibility - Trade on Cosmos-native decentralized exchanges
Price discovery - Enable market-driven price discovery
Arbitrage opportunities - Cross-chain arbitrage possibilities

Featured Use Case: List on Osmosis

With BitBadges' existing relayer infrastructure and IBC-compatible wrapped denominations, listing wrapped tokens on Osmosis is streamlined:

IBC Relayer Ready - BitBadges already has relayer infrastructure set up for seamless cross-chain transfers
Native IBC Compatibility - Wrapped tokens become native SDK coins that work seamlessly with IBC protocols
Automatic Liquidity - Create liquidity pools on Osmosis DEX with wrapped token assets
Streamlined Process - The technical infrastructure eliminates common barriers to cross-chain trading
Enhanced Discoverability - Tokens gain exposure to the broader Cosmos DeFi ecosystem

Conversion Process

Token to Coin (Wrapping)

User transfers tokens to the wrapper address
System processes the denom (replaces {id} if present, validates override if enabled)
System burns the tokens from user's balance
System mints equivalent native coins
Coins are credited to the user's account

Coin to Token (Unwrapping)

User transfers coins to the wrapper address
System processes the denom (replaces {id} if present, validates override if enabled)
System burns the native coins
System mints equivalent tokens
Tokens are credited to the user's balance

Cosmos Wrapper Paths provide seamless interoperability between BitBadges and the broader Cosmos ecosystem while maintaining the unique properties of both token and coin systems.

PreviousCollection Invariants NextCustom Data

Last updated 3 days ago