Setup and Configuration

This guide covers everything you need to set up your development environment for building dApps on BitBadges Chain with EVM compatibility.

Chain Configuration

Chain ID

The BitBadges Chain EVM uses a custom Chain ID for EVM compatibility:

Local Development: 90123
Testnet: 50025 (claimed in ethereum-lists/chains registry)
Mainnet: 50024 (claimed in ethereum-lists/chains registry)

The Chain ID is configured in app/params/constants.go:

// EVMChainIDMainnet is the EVM chain ID for BitBadges mainnet
// Chain ID: 50024 (claimed in ethereum-lists/chains registry)
// This should match the chain_id in genesis under app_state.evm.params.chain_config.chain_id
EVMChainIDMainnet = "50024"

// EVMChainIDTestnet is the EVM chain ID for BitBadges testnet
// Chain ID: 50025 (claimed in ethereum-lists/chains registry)
// This should match the chain_id in genesis under app_state.evm.params.chain_config.chain_id
EVMChainIDTestnet = "50025"

EVMChainID = "90123" // Default for local development/testing

Important: The Chain ID in your genesis file (app_state.evm.params.chain_config.chain_id) must match this value.

RPC Endpoints

BitBadges Chain provides two RPC interfaces:

Tendermint RPC (Port 26657)
- Used for Cosmos SDK queries and transactions
- Endpoint: http://localhost:26657
- Supports standard Cosmos SDK operations
EVM JSON-RPC (Port 8545)
- Used for Ethereum-compatible operations
- Endpoint: http://localhost:8545
- Supports standard Ethereum JSON-RPC methods
- Required for MetaMask, ethers.js, web3.js, etc.

Starting the Chain with EVM

To start the chain with EVM support, use the --json-rpc.enable flag:

# From the bitbadgeschain repository root
bitbadgeschaind start --json-rpc.enable --json-rpc.address 0.0.0.0:8545

Or use the provided startup script:

# From the bitbadgeschain repository root
./start-chain.sh start

The startup script automatically enables EVM JSON-RPC on port 8545.

Note: The EVM module is always enabled in the chain binary. You only need to enable the JSON-RPC server to interact with it via Ethereum-compatible tools (MetaMask, ethers.js, etc.).

MetaMask Configuration

To connect MetaMask to your local BitBadges chain:

Open MetaMask
Go to Settings > Networks > Add Network
Add the following network configuration:

For Local Development:

Network Name: BitBadges Local
RPC URL: http://localhost:8545 (EVM JSON-RPC)
Chain ID: 90123
Currency Symbol: BADGE
Block Explorer: (Optional, leave blank for local)

For Testnet:

Network Name: BitBadges Testnet
RPC URL: https://evm-rpc-testnet.bitbadges.io
Chain ID: 50025
Currency Symbol: BADGE
Block Explorer: (Testnet block explorer URL)

For Mainnet:

Network Name: BitBadges Mainnet
RPC URL: https://evm-rpc.bitbadges.io
Chain ID: 50024
Currency Symbol: BADGE
Block Explorer: https://explorer.bitbadges.io

Note: Use port 8545 (EVM JSON-RPC), not 26657 (Tendermint RPC).

Getting Test Tokens

After starting your local chain, fund your MetaMask account:

# Get your MetaMask address (0x... format)
# Then fund it using the chain's genesis or by transferring from a validator

# Option 1: Transfer from a validator account
bitbadgeschaind tx bank send \
  $(bitbadgeschaind keys show alice -a --keyring-backend test) \
  <your-metamask-address> \
  1000000000ubadge \
  --chain-id bitbadges \
  --keyring-backend test \
  --yes

# Option 2: Use the chain's genesis accounts if configured

Simple dApp Setup

Project Structure

A typical dApp project structure:

my-dapp/
├── contracts/              # Solidity contracts
│   ├── MyContract.sol
│   └── interfaces/
│       └── ITokenizationPrecompile.sol
├── scripts/               # Deployment scripts
│   └── deploy.ts
├── app/                   # Frontend (Next.js, React, etc.)
│   └── page.tsx
└── package.json

Basic Contract Template

Here's a minimal contract that uses the tokenization precompile:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "./interfaces/ITokenizationPrecompile.sol";
import "./types/TokenizationTypes.sol";

contract MyTokenContract {
    // Precompile address
    ITokenizationPrecompile constant precompile = 
        ITokenizationPrecompile(0x0000000000000000000000000000000000001001);
    
    uint256 public collectionId;
    
    constructor(uint256 _collectionId) {
        collectionId = _collectionId;
    }
    
    function transfer(
        address to,
        uint256 amount,
        uint256 tokenId
    ) external returns (bool) {
        address[] memory recipients = new address[](1);
        recipients[0] = to;
        
        TokenizationTypes.UintRange[] memory tokenIds = new TokenizationTypes.UintRange[](1);
        tokenIds[0] = TokenizationTypes.UintRange({
            start: tokenId,
            end: tokenId
        });
        
        TokenizationTypes.UintRange[] memory ownershipTimes = new TokenizationTypes.UintRange[](1);
        ownershipTimes[0] = TokenizationTypes.UintRange({
            start: 1,
            end: type(uint256).max
        });
        
        return precompile.transferTokens(
            collectionId,
            recipients,
            amount,
            tokenIds,
            ownershipTimes
        );
    }
    
    function getBalance(address user) external view returns (uint256) {
        TokenizationTypes.UintRange[] memory tokenIds = new TokenizationTypes.UintRange[](1);
        tokenIds[0] = TokenizationTypes.UintRange({
            start: 1,
            end: type(uint256).max
        });
        
        TokenizationTypes.UintRange[] memory ownershipTimes = new TokenizationTypes.UintRange[](1);
        ownershipTimes[0] = TokenizationTypes.UintRange({
            start: 1,
            end: type(uint256).max
        });
        
        return precompile.getBalanceAmount(collectionId, user, tokenIds, ownershipTimes);
    }
}

Deployment Script (TypeScript/ethers.js)

import { ethers } from "ethers";
import * as fs from "fs";

async function deploy() {
  // Connect to EVM JSON-RPC
  const provider = new ethers.JsonRpcProvider("http://localhost:8545");
  
  // Get deployer wallet
  const privateKey = process.env.PRIVATE_KEY || "";
  if (!privateKey) {
    throw new Error("PRIVATE_KEY environment variable required");
  }
  
  const wallet = new ethers.Wallet(privateKey, provider);
  console.log("Deployer address:", wallet.address);
  
  // Check balance
  const balance = await provider.getBalance(wallet.address);
  console.log("Balance:", ethers.formatEther(balance), "BADGE");
  
  // Deploy contract
  const contractFactory = new ethers.ContractFactory(
    CONTRACT_ABI,
    CONTRACT_BYTECODE,
    wallet
  );
  
  const contract = await contractFactory.deploy(collectionId);
  await contract.waitForDeployment();
  
  const address = await contract.getAddress();
  console.log("Contract deployed at:", address);
  
  // Save deployment info
  fs.writeFileSync(
    "deployed.json",
    JSON.stringify({ address, abi: CONTRACT_ABI }, null, 2)
  );
}

deploy().catch(console.error);

Frontend Integration (React/ethers.js)

import { ethers } from "ethers";
import { useState, useEffect } from "react";

export function useContract() {
  const [contract, setContract] = useState<ethers.Contract | null>(null);
  const [provider, setProvider] = useState<ethers.BrowserProvider | null>(null);
  
  useEffect(() => {
    if (typeof window.ethereum !== "undefined") {
      const provider = new ethers.BrowserProvider(window.ethereum);
      setProvider(provider);
      
      // Load deployed contract
      const contractAddress = "0x..."; // Your deployed contract address
      const contract = new ethers.Contract(
        contractAddress,
        CONTRACT_ABI,
        await provider.getSigner()
      );
      setContract(contract);
    }
  }, []);
  
  const transfer = async (to: string, amount: bigint, tokenId: bigint) => {
    if (!contract) throw new Error("Contract not loaded");
    const tx = await contract.transfer(to, amount, tokenId);
    await tx.wait();
  };
  
  return { contract, provider, transfer };
}

Contract Snippets

Helper Library

The repository includes a comprehensive helper library at contracts/libraries/TokenizationHelpers.sol that provides utility functions for:

Creating UintRange structs (single values, sequences, full ranges)
Creating Balance, CollectionMetadata, TokenMetadata structs
Creating empty permission structures
Validating ranges and balances
Common patterns for ownership times and token IDs

Import and use the helper library:

import "./libraries/TokenizationHelpers.sol";

contract MyContract {
    function example() external {
        // Create a single token ID range
        TokenizationTypes.UintRange memory tokenId = 
            TokenizationHelpers.createSingleTokenIdRange(123);
        
        // Create a full ownership time range (1 to max uint256)
        TokenizationTypes.UintRange memory fullTime = 
            TokenizationHelpers.createFullOwnershipTimeRange();
        
        // Create a token ID sequence (range from start to end)
        TokenizationTypes.UintRange memory sequence = 
            TokenizationHelpers.createTokenIdSequence(1, 100);
        
        // Create a UintRange array from arrays
        uint256[] memory starts = new uint256[](2);
        uint256[] memory ends = new uint256[](2);
        starts[0] = 1; ends[0] = 10;
        starts[1] = 20; ends[1] = 30;
        TokenizationTypes.UintRange[] memory ranges = 
            TokenizationHelpers.createUintRangeArray(starts, ends);
    }
}

See the TokenizationHelpers.sol file for all available helper functions.

Common Patterns

Pattern 1: Simple Token Transfer

ITokenizationPrecompile constant precompile = 
    ITokenizationPrecompile(0x0000000000000000000000000000000000001001);

function simpleTransfer(
    uint256 collectionId,
    address to,
    uint256 amount,
    uint256 tokenId
) external returns (bool) {
    address[] memory recipients = new address[](1);
    recipients[0] = to;
    
    TokenizationTypes.UintRange[] memory tokenIds = new TokenizationTypes.UintRange[](1);
    tokenIds[0] = TokenizationHelpers.createSingleTokenIdRange(tokenId);
    
    TokenizationTypes.UintRange[] memory ownershipTimes = new TokenizationTypes.UintRange[](1);
    ownershipTimes[0] = TokenizationHelpers.createFullOwnershipTimeRange();
    
    return precompile.transferTokens(
        collectionId,
        recipients,
        amount,
        tokenIds,
        ownershipTimes
    );
}

Pattern 2: Batch Transfer

ITokenizationPrecompile constant precompile = 
    ITokenizationPrecompile(0x0000000000000000000000000000000000001001);

function batchTransfer(
    uint256 collectionId,
    address[] calldata recipients,
    uint256[] calldata amounts,
    uint256 tokenId
) external returns (bool) {
    require(recipients.length == amounts.length, "Arrays length mismatch");
    
    // Transfer to each recipient
    for (uint256 i = 0; i < recipients.length; i++) {
        address[] memory singleRecipient = new address[](1);
        singleRecipient[0] = recipients[i];
        
        TokenizationTypes.UintRange[] memory tokenIds = new TokenizationTypes.UintRange[](1);
        tokenIds[0] = TokenizationHelpers.createSingleTokenIdRange(tokenId);
        
        TokenizationTypes.UintRange[] memory ownershipTimes = new TokenizationTypes.UintRange[](1);
        ownershipTimes[0] = TokenizationHelpers.createFullOwnershipTimeRange();
        
        precompile.transferTokens(
            collectionId,
            singleRecipient,
            amounts[i],
            tokenIds,
            ownershipTimes
        );
    }
    
    return true;
}

Pattern 3: Time-Limited Transfer

ITokenizationPrecompile constant precompile = 
    ITokenizationPrecompile(0x0000000000000000000000000000000000001001);

function transferWithExpiration(
    uint256 collectionId,
    address to,
    uint256 amount,
    uint256 tokenId,
    uint256 expirationTime
) external returns (bool) {
    address[] memory recipients = new address[](1);
    recipients[0] = to;
    
    TokenizationTypes.UintRange[] memory ownershipTimes = new TokenizationTypes.UintRange[](1);
    ownershipTimes[0] = TokenizationTypes.UintRange({
        start: block.timestamp,
        end: expirationTime
    });
    
    TokenizationTypes.UintRange[] memory tokenIds = new TokenizationTypes.UintRange[](1);
    tokenIds[0] = TokenizationHelpers.createSingleTokenIdRange(tokenId);
    
    return precompile.transferTokens(
        collectionId,
        recipients,
        amount,
        tokenIds,
        ownershipTimes
    );
}

Pattern 4: Using Helper Library

import "./libraries/TokenizationHelpers.sol";

contract HelperExample {
    ITokenizationPrecompile constant precompile = 
        ITokenizationPrecompile(0x0000000000000000000000000000000000001001);
    
    function transferWithHelpers(
        uint256 collectionId,
        address to,
        uint256 amount,
        uint256 tokenId
    ) external returns (bool) {
        address[] memory recipients = new address[](1);
        recipients[0] = to;
        
        // Use helper library for cleaner code
        TokenizationTypes.UintRange[] memory tokenIds = new TokenizationTypes.UintRange[](1);
        tokenIds[0] = TokenizationHelpers.createSingleTokenIdRange(tokenId);
        
        TokenizationTypes.UintRange[] memory ownershipTimes = new TokenizationTypes.UintRange[](1);
        ownershipTimes[0] = TokenizationHelpers.createFullOwnershipTimeRange();
        
        return precompile.transferTokens(
            collectionId,
            recipients,
            amount,
            tokenIds,
            ownershipTimes
        );
    }
}

Pattern 5: Dynamic Store for Compliance

contract ComplianceToken {
    ITokenizationPrecompile constant precompile = 
        ITokenizationPrecompile(0x0000000000000000000000000000000000001001);
    
    uint256 public kycRegistryId;
    uint256 public collectionId;
    
    function initialize(uint256 _collectionId) external {
        collectionId = _collectionId;
        
        // Create KYC registry (default: false = not KYC'd)
        kycRegistryId = precompile.createDynamicStore(
            false,
            "ipfs://...", // URI
            "" // customData
        );
    }
    
    function setKYC(address user, bool isKYCd) external {
        precompile.setDynamicStoreValue(kycRegistryId, user, isKYCd);
    }
    
    function isKYCd(address user) public view returns (bool) {
        string memory getValueJson = TokenizationJSONHelpers.getDynamicStoreValueJSON(
            kycRegistryId,
            user
        );
        DynamicStoreValueResult memory result = precompile.getDynamicStoreValue(getValueJson);
        // Use the field that matches your store's value type (e.g. result.verified for a boolean store)
        return result.verified;
    }
    
    function transfer(address to, uint256 amount, uint256 tokenId) external {
        require(isKYCd(msg.sender), "Sender not KYC'd");
        require(isKYCd(to), "Recipient not KYC'd");
        
        // Proceed with transfer...
    }
}

Complete Examples

Counter dApp

For a complete end-to-end example, see the counter-dapp in the repository. It includes:

Simple Solidity contract (Counter.sol)
Deployment script (TypeScript)
Next.js frontend with MetaMask integration
Complete setup instructions

ERC-3643 Example Contracts

The contracts/examples directory contains production-ready examples:

TwoFactorSecurityToken.sol - Security token with 2FA authentication
RealEstateSecurityToken.sol - Tokenized real estate with KYC/AML
CarbonCreditToken.sol - Carbon credits with vintage tracking
PrivateEquityToken.sol - Private equity fund tokens with lock-ups

Each example demonstrates:

Dynamic Stores for compliance registries
Time-bound ownership for lock-ups and expirations
Complex approval systems
Real-world use cases

See the examples README for detailed explanations of each contract.

Troubleshooting

RPC Connection Issues

Problem: Can't connect to RPC endpoint

Solutions:

Ensure the chain is running: bitbadgeschaind start --json-rpc.enable --json-rpc.address 0.0.0.0:8545
Check if EVM JSON-RPC is enabled in app.toml
Try both ports: http://localhost:8545 (EVM) and http://localhost:26657 (Tendermint)
Verify the chain is fully synced

MetaMask Connection Issues

Problem: MetaMask can't connect to the network

Solutions:

Use the correct Chain ID:
- 90123 for local development
- 50025 for testnet
- 50024 for mainnet
Use EVM JSON-RPC port: http://localhost:8545 (not 26657) for local development
Ensure your local chain is running (for local development)
Check MetaMask console for detailed error messages

Transaction Failures

Problem: Transactions fail with "insufficient funds" or revert

Solutions:

Fund your account with BADGE tokens:

bitbadgeschaind tx bank send <validator> <your-address> 1000000000ubadge --keyring-backend test

Check gas prices (may need to adjust in MetaMask)
Verify approvals are set correctly for token transfers
Check contract logs for specific error messages

Contract Deployment Issues

Problem: Contract deployment fails

Solutions:

Ensure you have sufficient balance for deployment gas
Check that the EVM module is enabled
Verify your Solidity version matches the chain's supported version
Check deployment script logs for specific errors

Next Steps

Review the Developer Guide for essential information
Explore Contract Examples for real-world patterns
Check the Precompile API Reference for all available methods
See the Counter dApp for a complete working example

PreviousEVM Compatibility NextDeveloper Guide

Last updated 22 days ago

hashtagChain Configuration

hashtagChain ID

hashtagRPC Endpoints

hashtagStarting the Chain with EVM

hashtagMetaMask Configuration

hashtagGetting Test Tokens

hashtagSimple dApp Setup

hashtagProject Structure

hashtagBasic Contract Template

hashtagDeployment Script (TypeScript/ethers.js)

hashtagFrontend Integration (React/ethers.js)

hashtagContract Snippets

hashtagHelper Library

hashtagCommon Patterns

hashtagPattern 1: Simple Token Transfer

hashtagPattern 2: Batch Transfer

hashtagPattern 3: Time-Limited Transfer

hashtagPattern 4: Using Helper Library

hashtagPattern 5: Dynamic Store for Compliance

hashtagComplete Examples

hashtagCounter dApp

hashtagERC-3643 Example Contracts

hashtagTroubleshooting

hashtagRPC Connection Issues

hashtagMetaMask Connection Issues

hashtagTransaction Failures

hashtagContract Deployment Issues

hashtagNext Steps

Chain Configuration

Chain ID

RPC Endpoints

Starting the Chain with EVM

MetaMask Configuration

Getting Test Tokens

Simple dApp Setup

Project Structure

Basic Contract Template

Deployment Script (TypeScript/ethers.js)

Frontend Integration (React/ethers.js)

Contract Snippets

Helper Library

Common Patterns

Pattern 1: Simple Token Transfer

Pattern 2: Batch Transfer

Pattern 3: Time-Limited Transfer

Pattern 4: Using Helper Library

Pattern 5: Dynamic Store for Compliance

Complete Examples

Counter dApp

ERC-3643 Example Contracts

Troubleshooting

RPC Connection Issues

MetaMask Connection Issues

Transaction Failures

Contract Deployment Issues

Next Steps