> For the complete documentation index, see [llms.txt](https://docs.bitplanet.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitplanet.ai/developer-guides/quick-start.md).

# Quick Start

## Prerequisites

**Required Software**

```bash
# 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**

```bash
# 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.

```bash
# 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)**

```bash
# 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

```bash
# Compile Brahma contracts
make contracts-compile

# Using Foundry
cd foundry
forge build
forge test
```

### E2E Testing Scripts

```bash
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:

```bash
# 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:

```bash
# 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

```bash
# 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:

```json
{
  "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:

```bash
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](/developer-guides/module-api.md) for detailed API reference
* Explore [Smart Contract Integration](/developer-guides/smart-contract.md) for contract development
* Study [Module Interaction](/developer-guides/module-interaction.md) to understand the architecture
* Read [Security Considerations](/developer-guides/security-considerations.md) before deploying to production