Cosmos Wrapper Paths
Cosmos Wrapper Paths enable 1:1 wrapping between BitBadges badges and native Cosmos SDK coin asset types, making badges IBC-compatible. These paths automatically mint and burn badges when transferring to/from specific wrapper addresses. These transfers to/from are handled within the badges module, so you can set up customizable logic for how these transfers are handled.
Key Concepts
Automatic Conversion
1:1 wrapping - One native coin unit is wrapped and unwrapped for the set conversion rate
Automatic minting/burning - Transfers to/from wrapper addresses trigger automatic conversion
IBC compatibility - Wrapped assets become native SDK coins that work with IBC
Bidirectional - Can wrap badges to coins and unwrap coins back to badges based on the conversion rate
Generated Wrapper Address
Non-controllable - Generated addresses have no known private keys
Collection-specific - Each wrapper path has its own unique address dependent on the denom
Automatic processing - Transfers to this address trigger wrapping/unwrapping
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:
import { generateAliasAddressForDenom } from 'bitbadgesjs-sdk';
const denom = 'utoken1';
const wrapperAddress = generateAliasAddressForDenom(denom);
console.log('Wrapper Address:', wrapperAddress);Proto Definition
message CosmosCoinWrapperPathAddObject {
string denom = 1;
repeated Balance balances = 2;
string symbol = 3;
repeated DenomUnit denomUnits = 4;
}
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"
Symbol
Display symbol - Human-readable symbol for the wrapped asset
Balances
Custom conversion rates - Defines which badges and ownership times participate in wrapping and how many badges 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
Usage Examples
Basic Wrapper Path
{
"denom": "utoken1",
"symbol": "TOKEN1",
"balances": [
{
"amount": "1",
"badgeIds": [{ "start": "1", "end": "1" }],
"ownershipTimes": [{ "start": "1", "end": "18446744073709551615" }]
}
],
"denomUnits": [
{
"decimals": "6",
"symbol": "TOKEN1",
"isDefaultDisplay": true
}
]
}Multi-Unit Display System
{
"denom": "utoken",
"symbol": "TOKEN",
"balances": [
{
"amount": "1",
"badgeIds": [{ "start": "1", "end": "100" }],
"ownershipTimes": [{ "start": "1", "end": "18446744073709551615" }]
}
],
"denomUnits": [
{
"decimals": "3",
"symbol": "mtoken",
"isDefaultDisplay": false
},
{
"decimals": "6",
"symbol": "TOKEN",
"isDefaultDisplay": true
}
]
}This creates a system where:
utokenis the base unit (smallest denomination)mtoken= 1,000utoken(milli-token)TOKEN= 1,000,000utoken(full token, default display)
Use Cases
IBC Transfers
Cross-chain transfers - Send wrapped badges to other Cosmos chains
DeFi integration - Use wrapped badges in Cosmos DeFi protocols
Liquidity provision - Add wrapped badges 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 badges 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 badges on Osmosis is streamlined:
IBC Relayer Ready - BitBadges already has relayer infrastructure set up for seamless cross-chain transfers
Native IBC Compatibility - Wrapped badges become native SDK coins that work seamlessly with IBC protocols
Automatic Liquidity - Create liquidity pools on Osmosis DEX with wrapped badge assets
Streamlined Process - The technical infrastructure eliminates common barriers to cross-chain trading
Enhanced Discoverability - Badges gain exposure to the broader Cosmos DeFi ecosystem
Conversion Process
Badge to Coin (Wrapping)
User transfers badges to the wrapper address
System burns the badges from user's balance
System mints equivalent native coins
Coins are credited to the user's account
Coin to Badge (Unwrapping)
User transfers coins to the wrapper address
System burns the native coins
System mints equivalent badges
Badges 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 badge and coin systems.
Last updated