Developer Guide

This guide covers essential information for developers building applications on BitBadges Chain that interact with both EVM and Cosmos SDK functionality.

Table of Contents

1. Transaction Signing Capabilities

2. Address Conversion

3. Precompile Caller Limitations

4. Key Types and Compatibility

5. Best Practices

Transaction Signing Capabilities

Overview

BitBadges Chain supports two types of transactions, each with specific signing requirements:

Transaction Type	Signing Key Type	Hash Algorithm	Use Case
MsgEthereumTx	ethsecp256k1 (Ethereum-style)	Keccak256	EVM contract calls, precompile calls
Standard Cosmos Messages	secp256k1 (Cosmos-style)	SHA256	Native Cosmos SDK messages (e.g., MsgDelegate, MsgTransferTokens)

Who Can Sign What?

✅ ETH Wallets (ethsecp256k1 keys)

Can sign:

• MsgEthereumTx transactions

  • Direct EVM contract calls

  • Precompile calls from Solidity contracts

  • Any Ethereum-compatible transaction

Cannot sign:

• Standard Cosmos SDK messages (different hash algorithm)

  • MsgDelegate

  • MsgTransferTokens

  • Other native Cosmos messages

Example:

// ✅ This works - ETH wallet can sign MsgEthereumTx
import "./libraries/TokenizationJSONHelpers.sol";

ITokenizationPrecompile precompile = ITokenizationPrecompile(0x0000000000000000000000000000000000001001);

// Build JSON using helper
string memory tokenIdsJson = TokenizationJSONHelpers.uintRangeToJson(1, 1);
string memory ownershipJson = TokenizationJSONHelpers.uintRangeToJson(1, type(uint256).max);
string memory transferJson = TokenizationJSONHelpers.transferTokensJSON(
    collectionId, recipients, amount, tokenIdsJson, ownershipJson
);

precompile.transferTokens(transferJson);

✅ Cosmos Wallets (standard secp256k1 keys)

Can sign:

• Standard Cosmos SDK messages

  • MsgDelegate

  • MsgTransferTokens

  • MsgCreateCollection

  • All native Cosmos SDK messages

Cannot sign:

• MsgEthereumTx transactions (different signature format)

  • Cannot directly call EVM contracts

  • Cannot call precompiles from native Cosmos transactions

Example:

// ✅ This works - Cosmos wallet can sign standard message
msg := &tokenizationtypes.MsgTransferTokens{
    Creator:      cosmosAddress,
    CollectionId: collectionId,
    Transfers:    transfers,
}

❌ Cross-Compatibility

Not supported out of the box:

• ETH wallets cannot sign standard Cosmos messages

• Cosmos wallets cannot sign MsgEthereumTx

Why?

• Different hash algorithms (Keccak256 vs SHA256)

• Different signature formats

• EVM ante handler routes by transaction type

Workaround:

• Use precompiles from Solidity contracts (ETH wallets) to access Cosmos SDK functionality

• Use native Cosmos messages (Cosmos wallets) for direct SDK access

Address Conversion

Overview

BitBadges Chain uses a unified address system where Ethereum addresses (20 bytes) and Cosmos addresses (Bech32 format) represent the same underlying account when using ethsecp256k1 keys.

Conversion Mechanics

EVM Address → Cosmos Address

When an EVM address is used in Cosmos SDK operations, it's automatically converted:

// In precompile code
caller := contract.Caller()  // common.Address (20 bytes, e.g., 0x1234...)
cosmosAddr := sdk.AccAddress(caller.Bytes()).String()  // Bech32 (e.g., bb1abc...)

Key Points:

• Same 20-byte value, different encoding

• EVM: 0x hex prefix (e.g., 0x1234...5678)

• Cosmos: Bech32 with bb prefix (e.g., bb1abc...xyz)

Cosmos Address → EVM Address

The reverse conversion is also possible:

cosmosAddr, _ := sdk.AccAddressFromBech32("bb1abc...xyz")
evmAddr := common.BytesToAddress(cosmosAddr.Bytes())  // 0x1234...5678

Address Format Examples

Format	Example	Use Case
EVM (hex)	0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb	Solidity contracts, EVM transactions
Cosmos (Bech32)	bb1abc123def456...	Cosmos SDK messages, queries

Important Notes

1. Same Account, Different Representations

   • An account with an ethsecp256k1 key has the same 20-byte address in both formats

   • The Bech32 encoding is just a different way to represent the same bytes

2. Automatic Conversion in Precompiles

   • Precompiles automatically convert EVM addresses to Cosmos addresses

   • No manual conversion needed when calling precompile methods

3. Address Validation

   • Cosmos SDK validates addresses using Bech32 format

   • EVM uses hex format

   • Both represent the same underlying account

Precompile Caller Limitations

Understanding msg.sender in Precompiles

When a Solidity contract calls a precompile, the precompile uses contract.Caller() to identify the caller. This has important implications for authorization and security.

How It Works

// In precompile code
func (p Precompile) GetCallerAddress(contract *vm.Contract) (string, error) {
    caller := contract.Caller()  // EVM msg.sender
    return sdk.AccAddress(caller.Bytes()).String(), nil  // Converted to Cosmos address
}

Limitations

1. Direct Contract Calls Only

The caller is always the immediate caller (the contract making the precompile call), not the original transaction signer.

Example:

User (0xAlice) → Contract A → Precompile
                ↑
                contract.Caller() = Contract A's address, NOT 0xAlice

Implication:

• Precompile sees the contract address as the caller

• Original user address is not directly available

• Authorization must be handled at the contract level

2. No Cross-Contract Delegation

If Contract A calls Contract B, which then calls the precompile:

User → Contract A → Contract B → Precompile
                                    ↑
                                    contract.Caller() = Contract B

Implication:

• Precompile only sees Contract B as the caller

• Contract A's identity is not visible to the precompile

3. Authorization Patterns

Because the precompile sees the contract address, not the user address, you need to design authorization carefully:

Pattern 1: Contract-Level Authorization

import "./libraries/TokenizationJSONHelpers.sol";

contract MyContract {
    ITokenizationPrecompile precompile = ITokenizationPrecompile(0x0000000000000000000000000000000000001001);

    mapping(address => bool) public authorized;

    function transferTokens(
        uint256 collectionId,
        address to,
        uint256 amount
    ) external {
        require(authorized[msg.sender], "Not authorized");

        // Build JSON
        address[] memory recipients = new address[](1);
        recipients[0] = to;
        string memory tokenIdsJson = TokenizationJSONHelpers.uintRangeToJson(1, 1);
        string memory ownershipJson = TokenizationJSONHelpers.uintRangeToJson(1, type(uint256).max);
        string memory transferJson = TokenizationJSONHelpers.transferTokensJSON(
            collectionId, recipients, amount, tokenIdsJson, ownershipJson
        );

        // Contract is authorized, so precompile call succeeds
        precompile.transferTokens(transferJson);
    }
}

Pattern 2: Pass User Address Explicitly

// The precompile automatically uses contract.Caller() as the creator
// For transfers, tokens move from the contract's balance
// If you need to transfer from a specific user, use approvals or pass user address in JSON
string memory transferJson = TokenizationJSONHelpers.transferTokensJSON(...);
precompile.transferTokens(transferJson);

Pattern 3: Use Approval System

// User approves contract, contract acts on user's behalf
// Precompile sees contract as caller, but contract has user's approval

Security Considerations

1. Impersonation Prevention

   • Precompile always uses contract.Caller() to prevent spoofing

   • Cannot be manipulated by malicious contracts

2. Authorization Design

   • Design contracts to handle authorization before calling precompile

   • Don't rely on precompile seeing the original user address

3. Multi-Contract Scenarios

   • Be aware that intermediate contracts are invisible to precompile

   • Design authorization to account for this

Key Types and Compatibility

Key Type Comparison

Key Type	Algorithm	Hash Function	Address Format	Can Sign MsgEthereumTx	Can Sign Cosmos Messages
ethsecp256k1	secp256k1	Keccak256	Both (EVM hex + Cosmos Bech32)	✅ Yes	❌ No (different hash)
secp256k1 (Cosmos)	secp256k1	SHA256	Cosmos Bech32 only	❌ No (different format)	✅ Yes

Account Creation

When creating accounts:

For EVM Compatibility:

# Create account with ethsecp256k1 key
bitbadgeschaind keys add my-eth-account --keyring-backend test --algo eth_secp256k1

For Cosmos-Only:

# Create account with standard secp256k1 key (default)
bitbadgeschaind keys add my-cosmos-account --keyring-backend test

Key Registration

The codebase registers both key types:

// ethsecp256k1 keys are registered in the codec
registry.RegisterImplementations((*cryptotypes.PubKey)(nil), &ethsecp256k1.PubKey{})
registry.RegisterImplementations((*cryptotypes.PrivKey)(nil), &ethsecp256k1.PrivKey{})

This allows the ante handler to recognize and verify signatures from both key types.

Best Practices

1. Choose the Right Key Type

• Use ethsecp256k1 if you need:

  • EVM contract interaction

  • Precompile calls from Solidity

  • Compatibility with Ethereum tooling

• Use standard secp256k1 if you need:

  • Only native Cosmos SDK functionality

  • No EVM interaction required

2. Address Handling

• In Solidity contracts: Use EVM addresses (hex format)

• In Cosmos SDK code: Use Bech32 addresses

• Precompiles handle conversion automatically

3. Authorization Patterns

• For contracts calling precompiles:

  • Implement authorization at the contract level

  • Don't rely on precompile seeing original user address

  • Use approval patterns when needed

4. Transaction Types

• Use MsgEthereumTx for:

  • EVM contract calls

  • Precompile calls from Solidity

• Use standard Cosmos messages for:

  • Direct SDK module interaction

  • Better gas efficiency for simple operations

  • Native Cosmos tooling compatibility

5. Testing Considerations

• Test with both key types if your app supports both

• Verify address conversions work correctly

• Test authorization patterns with contract intermediaries

Summary

Aspect	ETH Wallets (ethsecp256k1)	Cosmos Wallets (secp256k1)
Can sign MsgEthereumTx	✅ Yes	❌ No
Can sign Cosmos messages	❌ No	✅ Yes
Address format	Both (hex + Bech32)	Bech32 only
Precompile access	✅ Via Solidity contracts	❌ No direct access
Native SDK access	❌ Via precompiles only	✅ Direct access

Decimal Handling and the Precisebank Module

Overview

BitBadges Chain uses different decimal precisions for Cosmos SDK and EVM compatibility:

• Cosmos SDK (x/bank): Uses 9 decimals with base denom ubadge

• EVM (precisebank module): Uses 18 decimals for Ethereum compatibility

The precisebank module bridges these two systems, automatically handling conversions between Cosmos and EVM decimal representations.

Unit Conversions

Unit	Decimals	Value	Context
BADGE	9 (Cosmos) / 18 (EVM)	1 BADGE	Display unit
ubadge	9	1 * 10^9	Base unit in Cosmos SDK (x/bank)
abadge	0	1 * 10^0	Base unit in EVM (smallest unit)

Conversion Relationships:

• 1 BADGE = 1 * 10^9 ubadge (Cosmos)

• 1 BADGE = 1 * 10^18 abadge (EVM)

• 1 ubadge = 1 * 10^9 abadge

For Developers

Working with EVM Contracts

When writing Solidity contracts or interacting with EVM precompiles:

// ✅ Correct - Use 18 decimal precision in EVM
uint256 oneBadge = 1 * 10**18;  // 1 BADGE in EVM
uint256 halfBadge = 5 * 10**17; // 0.5 BADGE in EVM

// ❌ Wrong - Don't use 9 decimals in EVM
uint256 wrongAmount = 1 * 10**9;  // This is 0.000000001 BADGE in EVM!

Working with Cosmos SDK

When working with native Cosmos SDK messages or queries:

// ✅ Correct - Use 9 decimal precision in Cosmos
const coin = {
    denom: 'ubadge',
    amount: '1000000000', // 1 BADGE in Cosmos (1 * 10^9)
};

// ❌ Wrong - Don't use 18 decimals in Cosmos
const wrongCoin = {
    denom: 'ubadge',
    amount: '1000000000000000000', // This is 1 * 10^9 BADGE in Cosmos!
};

Automatic Conversion

The precisebank module handles conversions automatically:

• EVM → Cosmos: When EVM contracts interact with Cosmos SDK modules, amounts are converted from 18 decimals to 9 decimals

• Cosmos → EVM: When Cosmos SDK operations interact with EVM, amounts are converted from 9 decimals to 18 decimals

Important: Always use the correct decimal precision for the context you're working in. The precisebank module handles the conversion, but you must provide amounts in the correct format for your context.

Common Mistakes

1. Mixing decimal precisions

   // ❌ Wrong - Using Cosmos precision in EVM
   uint256 amount = 1 * 10**9;  // This is 0.000000001 BADGE in EVM!
   
   // ✅ Correct - Use EVM precision
   uint256 amount = 1 * 10**18;  // 1 BADGE in EVM

2. Assuming 1:1 conversion

   // ❌ Wrong - These are NOT equal
   const cosmosAmount = '1000000000'; // 1 BADGE in Cosmos
   const evmAmount = '1000000000'; // 0.000000001 BADGE in EVM!
   
   // ✅ Correct - Use proper conversion
   const cosmosAmount = '1000000000'; // 1 BADGE in Cosmos
   const evmAmount = '1000000000000000000'; // 1 BADGE in EVM

3. Not accounting for context

   • In Solidity contracts: Always use 18 decimals

   • In Cosmos SDK messages: Always use 9 decimals

   • The precisebank module handles the bridge automatically

EVM Query Challenges / Invariants

EVM queries allow you to gate token transfers or set invariants based on read-only queries to EVM smart contracts. This is a powerful feature for integrating with existing DeFi protocols, compliance registries, and cross-chain state verification.

See invariants or approval criterie -> EVM Query Challenges section for more details.

Quick Example

// Gate transfers to users holding 100+ USDC
string memory evmQueryChallenge = string(abi.encodePacked(
    '{"contractAddress":"0xUSDCAddress",',
    '"calldata":"70a08231000000000000000000000000$sender",',  // balanceOf(address)
    '"expectedResult":"0000000000000000000000000000000000000000000000000000000005f5e100",',  // 100 USDC
    '"comparisonOperator":"gte",',
    '"gasLimit":"100000"}'
));

Additional Resources

• EVM Precompiles Overview

• Tokenization Precompile Documentation

• Architecture Details

• Security Best Practices

• Chain Details