Quick Start

Prerequisites

Required Software

# Go 1.23.8+
go version

# Python 3.10+ with virtual environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Solidity compiler
# Brahma contracts use 0.8.22+, but 0.8.24 is compatible with all
solc-select install 0.8.24
solc-select use 0.8.24

# Foundry (for Solidity testing and deployment)
curl -L https://foundry.paradigm.xyz | bash
foundryup

Build & Test

Building the Blockchain

# Clone the Bitplanetrepository
git clone https://github.com/BitPlanet/Bitplanet-CosmosEVM.git
cd Bitplanet-CosmosEVM

# Build blockchain binary
make install

# Run unit tests
make test

# Run tests with coverage
make test-unit-cover

# Run race detection tests
make test-race

# Lint code (includes all linters)
make lint

# Check for deprecated BitSDK APIs
make lint-deprecated-apis

Local Testnet Setup

Important: Credential Initialization

Testnet setup requires explicit credential initialization for security.

# Step 1: Initialize credentials (choose one)
make init-env-deterministic  # Recommended: Same credentials every time
# OR
make init-env               # Random credentials (unique per initialization)

# Step 2: Start the testnet
make sh-testnet             # Manual single-node testnet

# Step 3: Run complete E2E tests (optional)
make testnet-complete       # Full workflow with contract deployment

Docker Setup (Alternative)

# Docker automatically handles credential initialization
docker-compose up -d chain

Credential Management

• .env file stores all account credentials

• File permissions automatically set to 600

• Deterministic mode generates same test addresses

• Production requires manual credential configuration

• Run make validate-env to verify configuration

Network Endpoints

Ethereum JSON-RPC:  http://localhost:8545
Cosmos RPC:         http://localhost:26657
REST API:           http://localhost:1317
gRPC:               localhost:9090
WebSocket:          ws://localhost:8546

Contract Development

Compiling Contracts

# Compile Brahma contracts
make contracts-compile

# Using Foundry
cd foundry
forge build
forge test

E2E Testing Scripts

cd tests_brahma/brahma_scripts

# Full E2E workflow
./precompileE2E.sh

# Individual operations
./request-for-core.sh           # Request for core
./query-ai-rewards.sh           # Query AI rewards
./update-contract-addresses.sh  # Update addresses from chain
./update_brahma_params.sh       # Update module parameters

Query Examples

AutoCLI Command Generation

Important: Manual query commands are disabled in x/brahma/module.go:112-117. The CLI uses AutoCLI to auto-generate commands from gRPC service definitions.

AutoCLI Naming Convention:

1. RPC method names are converted to kebab-case

2. Full method name is preserved (Query prefix is NOT dropped by AutoCLI)

3. Commands are generated directly from proto service definitions

4. Example: QueryCoreGrantApplication → query-core-grant-application

Command Generation Examples:

Proto RPC Method	Generated CLI Command	Notes
AITensorByBlockHeight	aitensor-by-block-height	No "Query" prefix to drop
ContributionByWalletAddress	contribution-by-wallet-address	No "Query" prefix to drop
QueryCoreGrantApplication	query-core-grant-application	Full method name preserved
GetAllBlockHeightsByAIID	get-all-block-heights-by-aiid	No "Query" prefix to drop
QueryCore	query-core	Full method name preserved
QueryAITokens	query-aitokens	Full method name preserved
Params	params	Standard params query
QueryClaimableRewards	query-claimable-rewards	Full method name preserved
QueryClaimStatistics	query-claim-statistics	Full method name preserved

CLI Queries

The CLI uses AutoCLI to generate commands from gRPC service definitions:

# Query module parameters
evmd query brahma params --node http://localhost:26657

# Get AI tensor data by block height
evmd query brahma aitensor-by-block-height "my-ai-id" 12345 --node http://localhost:26657

# Get contribution by wallet address
evmd query brahma contribution-by-wallet-address "my-ai-id" 12345 "0x..." --node http://localhost:26657

# Get all block heights for an AI
evmd query brahma get-all-block-heights-by-aiid "my-ai-id" --node http://localhost:26657

# Check core grant application
evmd query brahma query-core-grant-application "ethm1..." --node http://localhost:26657

# Query core token addresses (ERC20 and ERC1155)
evmd query brahma query-core --node http://localhost:26657

# Query AI token addresses (requires base64-encoded AI ID)
evmd query brahma query-aitokens "ZG9uYWxkLWFp" --node http://localhost:26657

# Query claimable rewards for an address
evmd query brahma query-claimable-rewards "ethm1..." --node http://localhost:26657

# Query claim statistics (aggregated data)
evmd query brahma query-claim-statistics --node http://localhost:26657

REST API (Alternative to CLI)

REST endpoints follow the exact paths defined in proto files:

# Query via REST (all endpoints from proto/cosmos/evm/brahma/v1/query.proto)
curl http://localhost:1317/cosmos/evm/brahma/v1/params
curl http://localhost:1317/cosmos/evm/brahma/v1/aitensor/my-ai-id/12345
curl http://localhost:1317/cosmos/evm/brahma/v1/CoreGrantApplication/ethm1...
curl http://localhost:1317/cosmos/evm/brahma/v1/claimable-rewards/ethm1...
curl http://localhost:1317/cosmos/evm/brahma/v1/claim-statistics

Discovering Available Commands

# List all brahma query commands (AutoCLI-generated)
evmd query brahma --help

# Get command-specific help with parameter details
evmd query brahma query-core-grant-application --help

# Example: Check help for AITensor query
evmd query brahma aitensor-by-block-height --help

Note: The command names shown above are based on standard AutoCLI behavior in BitSDK (built on Cosmos SDK v0.53.3), where RPC method names are converted to kebab-case without dropping prefixes. If you find the actual commands differ, use evmd query brahma --help to see the exact generated command names for your version.

Transaction Examples

The Brahma module exposes one direct CLI transaction: Request for Core (rfc). This is used by platforms to submit AI tensor contributions on behalf of users with approved Core grant allocations.

How it works:

1. Platform creates a JSON file with transaction details (requester address, AI tensors, contributions)

2. Platform submits the transaction using evmd tx brahma rfc command

3. The module validates the allocation, calculates cores to mint, and updates balances

4. Users claim their minted cores through the platform's interface (which calls the smart contract's claimCore() function)

Request for Core

Create a request.json file:

{
  "Requester": "bitplanet140fehngcrxvhdt84x729p3f0qmkmea8nt9d6hl",
  "AITensors": [
    {
      "AI": "ZG9uYWxkLWFp",
      "Tensor": [
        {
          "Address": "0x95222290DD7278Aa3Ddd389Cc1E1d165CC4BAfe5",
          "Contributions": [20, 20, 1, 4]
        }
      ]
    }
  ]
}

Important JSON field requirements:

• Field names use PascalCase: Requester, AITensors, Address, Contributions

• AI field must be base64-encoded bytes (e.g., "ZG9uYWxkLWFp" = "donald-ai")

• To encode: echo -n "donald-ai" | base64 → ZG9uYWxkLWFp

• Address can be hex string (0x-prefixed Ethereum address)

• Contributions is an array of uint64 values

Submit transaction:

evmd tx brahma rfc request.json \
    --from user \
    --chain-id 9001 \
    --node http://localhost:26657

Note: Core grant applications and removals are governance proposals, not direct CLI transactions.

Next Steps

• Review Module API for detailed API reference

• Explore Smart Contract Integration for contract development

• Study Module Interaction to understand the architecture

• Read Security Considerations before deploying to production