BitBadges Blockchain

The most feature-rich tokenization standard ever built — exclusively available as a Cosmos SDK module.

Enterprise-grade tokenization with 20+ compliance primitives, protocol-level enforcement, and full EVM compatibility. No smart contracts required. No code required. No per-project audits.

Why BitBadges?

BitBadges provides a no-code, plug-and-play tokenization module designed for RWAs, compliant assets, custom stablecoins, and any use case requiring advanced transferability controls. Unlike existing standards (ERC-20, ERC-3643, ICS20), compliance is checked on every transfer, everywhere — in DEXs, liquidity pools, IBC transfers — automatically and at the protocol level.

Key Capabilities:

• ✅ 20+ Compliance Primitives — Time-gating, KYC requirements, spend limits, freeze/revoke, multi-sig, royalties
• ✅ Four Levels of Control — Chain-level, issuer-level, sender-level, recipient-level rules
• ✅ Full EVM Compatibility — Solidity contracts call module via precompile; works with ERC-3643, DeFi protocols
• ✅ Time-Dependent Balances — Native vesting, auto-expiring subscriptions, time-locked ownership
• ✅ IBC Interoperability — Wrap to ICS20, tap into any IBC liquidity, cross-chain settlement
• ✅ No-Code Deployment — Full features without smart contracts or audits
• ✅ 7000+ Off-Chain Integrations — Gate transfers by Discord, email, KYC providers, custom APIs

For detailed documentation, see docs.bitbadges.io.

---

The Paradigm Shift: Smart Tokens

Traditional tokens are simple balances with permissionless transferability. Smart tokens are different — they have programmable rules, custom transferability, compliance checks, and ownership controls built directly into the token standard itself, enforced on every transfer, everywhere, automatically.

This represents a fundamental shift: instead of fragmented, vulnerable contracts on the app layer, we now have an abstracted tokenization layer that is self-contained, programmable, composable, and reusable across thousands of deployments.

The issuer has full control over the entire lifecycle — transferability, compliance, ownership, revocability, freezability — all configured through composable building blocks, not custom code.

---

Technical Overview

BitBadges blockchain is built on the Cosmos SDK and CometBFT consensus, providing robust infrastructure for enterprise-grade tokenization.

Infrastructure Features:

• ✅ Cosmos EVM Integration — Full Ethereum Virtual Machine (EVM) compatibility via cosmos/evm module
• ✅ ERC20 Support — 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
• ✅ JSON-RPC API — Standard Ethereum JSON-RPC endpoints for Web3 compatibility

Quick Start

Prerequisites

Ubuntu 23.10+:

sudo apt-get install git curl make build-essential gcc
snap install go --classic  # Go 1.21+

Cross-compilation (optional):

# For ARM64
sudo apt-get install gcc-aarch64-linux-gnu

# For macOS (see osxcross project for setup)

Build from Source

# Build for all platforms
make build-all

# Build for specific platform
make build-linux/amd64
make build-darwin/amd64
make build-linux/arm64

Using Ignite CLI

# Install Ignite CLI from https://ignite.com/cli
ignite chain init --skip-proto
ignite chain build --skip-proto
ignite chain serve --skip-proto

Note: The --skip-proto flag is required due to manual corrections in generated query files.

Development

Project Structure

bitbadgeschain/
├── x/                          # Blockchain modules
│   ├── tokenization/           # Core token functionality
│   │   └── precompile/         # Tokenization EVM precompile
│   ├── gamm/                   # AMM liquidity pools
│   │   └── precompile/         # Gamm EVM precompile
│   ├── sendmanager/            # Native coin transfers
│   │   └── precompile/         # SendManager EVM precompile
│   ├── maps/                   # Key-value mappings
│   ├── anchor/                 # Data anchoring
│   └── wasmx/                  # WASM extensions
├── app/                        # Application configuration
│   ├── evm.go                  # EVM module registration
│   └── PRECOMPILE_MANAGEMENT.md # Precompile documentation
├── contracts/                  # Solidity contracts and interfaces
│   ├── docs/                   # EVM integration guides
│   ├── interfaces/             # Precompile interfaces
│   └── libraries/              # Helper libraries
├── proto/                      # Protocol buffer definitions
├── api/                        # Generated Go types
├── ts-client/                  # TypeScript client
├── cmd/                        # CLI commands
└── _docs/                      # Development documentation

Common Commands

Build & Test:

# Build main binary
go build ./cmd/bitbadgeschaind

# Run module tests
go test ./x/tokenization/...
go test ./x/tokenization/keeper/...

# Run specific test
go test ./x/tokenization/keeper/ -run TestMsgCreateDynamicStore

# Integration tests
ignite chain test

Linting & Formatting:

golangci-lint run ./x/tokenization/...
go fmt ./x/tokenization/...

Protocol Buffers:

# Generate Go code from proto files
ignite generate proto-go --yes

# Clean up versioned API folders (required after generation)
rm -rf api/tokenization/v*

# Stage generated files
git add *.pb.go *.pulsar.go

Development Workflows

For detailed development guides, see:

• Adding New Message Types
• Proto Addition Guide
• Module Architecture

Configuration

EVM Configuration

The EVM module is configured in app/evm.go and requires:

• EVM Chain IDs: Set in app/params/constants.go
  • Mainnet: 50024 (BitBadges Mainnet)
  • Testnet: 50025 (BitBadges Testnet)
• Precompile Enablement: Configured in genesis active_static_precompiles array
• JSON-RPC: Optional, can be enabled for Web3 compatibility

For precompile management, see app/PRECOMPILE_MANAGEMENT.md.

Note: These chain IDs are registered in the ethereum-lists/chains registry. See _docs/CHAIN_ID_REGISTRATION.md for details on chain ID registration.

Local Development

Configure your development environment with config.yml:

version: 1
accounts:
    - name: alice
      coins: ['1000000000000000ustake', '1ubadge']
    - name: bob
      coins: ['99999999999999996ubadge', '1000000000000000ustake']

validators:
    - name: alice
      bonded: 1000000000000000ustake

Network Deployment

Production configurations available in:

• config.testnet.yml - Testnet configuration
• Genesis files for mainnet and testnet networks
• Release configurations in release-info/

API & Integration

REST API

The blockchain exposes a REST API for querying collections, balances, and approvals. OpenAPI specification available at docs/static/openapi.yml.

TypeScript Client

Generated TypeScript client available in ts-client/ for easy integration with web applications.

EVM Integration

BitBadges chain includes full EVM compatibility, enabling Ethereum developers to deploy and interact with Solidity smart contracts.

EVM Chain IDs

Mainnet:

• Chain ID: 50024 (BitBadges Mainnet)
• Network Name: BitBadges
• Native Currency: BADGE (ubadge base unit)
• Registry: To be registered in ethereum-lists/chains

Testnet:

• Chain ID: 50025 (BitBadges Testnet)
• Network Name: BitBadges Testnet
• Native Currency: BADGE (ubadge base unit)
• Registry: To be registered in ethereum-lists/chains

Local Development:

• Chain ID: 90123 (defaults to local dev chain ID)
• Configured in app/params/constants.go

JSON-RPC Endpoints

The chain exposes standard Ethereum JSON-RPC endpoints:

• http://localhost:8545 - EVM JSON-RPC (if enabled)
• http://localhost:26657 - Tendermint RPC (also supports some EVM queries)

Precompiles

Precompiles provide direct access to Cosmos modules from Solidity:

Default Cosmos Precompiles (0x0800-0x0806):

• 0x0800 - Staking precompile
• 0x0801 - Distribution precompile
• 0x0802 - ICS20 (IBC) precompile
• 0x0803 - Vesting precompile
• 0x0804 - Bank precompile (read-only queries)
• 0x0805 - Governance precompile
• 0x0806 - Slashing precompile

Custom BitBadges Precompiles (0x1001+):

• 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

See contracts/docs/ for detailed precompile documentation:

• Tokenization Precompile Guide
• Gamm Precompile Guide
• SendManager Precompile Guide
• EVM Send Options

ERC20 Wrapper

Native Cosmos coins can be wrapped as ERC20 tokens for use in standard Ethereum tooling:

• Each native denom has a corresponding ERC20 contract address
• Wrap/unwrap operations via ERC20 keeper
• Supports IBC transfers with ERC20 compatibility

Development Tools

• MetaMask: Connect using Chain ID 50024 (mainnet) or 50025 (testnet)
• Hardhat/Truffle: Use standard Ethereum development tools
• Web3.js/Ethers.js: Full compatibility with standard libraries
• Example dApp: See counter-dapp/ for a complete Next.js + MetaMask example

WASM Bindings

Smart contracts can interact with the tokens module through custom WASM bindings in custom-bindings/.

Releases

Creating Releases

# Tag and push new version
git tag v1.0.0
git push origin v1.0.0

This automatically creates a draft release with configured build targets.

Upgrade Process

Blockchain upgrades are coordinated through governance proposals. See release-info/ for historical upgrade information and app/upgrades/ for upgrade handler implementations.

Testing

Unit Tests

# Run all token module tests
go test ./x/tokenization/...

# Run with coverage
go test -cover ./x/tokenization/...

# Run specific keeper tests
go test ./x/tokenization/keeper/ -run TestMsgCreateCollection

Integration Tests

# Full integration test suite
ignite chain test

# Simulation tests
go test ./x/tokenization/simulation/...

Test Helpers

The module includes comprehensive test helpers in x/tokenization/keeper/integration_*_test.go for setting up test scenarios.

Community

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes following the coding conventions
4. Add tests for new functionality
5. Submit a pull request

Development Guidelines

• Follow existing code patterns and conventions
• Add comprehensive tests for new features
• Update documentation for API changes
• Use the project's linting and formatting tools

Support

• BitBadges Documentation
• BitBadges Website
• Cosmos SDK Documentation
• Ignite CLI Documentation
• Email: trevor@bitbadges.io

Acknowledgments

• Built with Cosmos SDK and Ignite CLI
• Inter-blockchain communication powered by IBC

License

This repository is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License and is registered under US Copyright.