> 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/advanced-topics/blockchain-architecture/bit-sdk.md).

# BitSDK Integration

Bitplanet is built on BitSDK, our customized implementation of the Cosmos SDK modular blockchain framework. BitSDK extends Cosmos SDK v0.53.3 with Bitplanet-specific enhancements while maintaining full compatibility with the Cosmos ecosystem.

## What is BitSDK?

BitSDK is Bitplanet's enhanced version of Cosmos SDK, providing:

* All standard Cosmos SDK v0.53.3 functionality
* Custom modules for AI attribution (x/brahma)
* Enhanced EVM integration through BitEVM (based on Cosmos EVM v1.0.0-rc2)
* Optimizations for AI-focused token economics

This page explains how Bitplanet leverages BitSDK's infrastructure and capabilities.

## How Bitplanet Leverages BitSDK

Bitplanet uses BitSDK as its foundation, inheriting core blockchain functionality while adding custom modules for AI attribution.

### Core Framework

**Application Structure:**

* Bitplanet is a BitSDK application (`EVMD` type)
* Uses standard module architecture
* Extends BaseApp for transaction processing
* Integrates custom modules (x/brahma, x/precompile) alongside standard modules

**Module System:**

{% @mermaid/diagram content="graph TB
BA\[Bitplanet Application]

```
BA --> SCM[Standard BitSDK Modules]
BA --> CM[Custom Modules]

SCM --> AUTH[auth]
SCM --> BANK[bank]
SCM --> STAKING[staking]
SCM --> GOV[gov]
SCM --> ETC[etc.]

CM --> BRAHMA[x/brahma - AI attribution & rewards]
CM --> PRECOMPILE[x/precompile - EVM-Cosmos bridge]
CM --> VM[x/vm - EVM execution]" %}
```

### State Management

Bitplanet uses BitSDK's KVStore for all state persistence. For detailed storage architecture and data structures, see [State Management](/advanced-topics/blockchain-architecture/state-management.md).

**IAVL Tree Storage:**

* Immutable state snapshots at each block height
* Merkle proofs for light client verification
* Deterministic state commitment in block headers

**Module Stores:**

* **State Root** (App Hash)
  * auth (accounts)
  * bank (balances)
  * staking (validators)
  * brahma (AI tensors, core grants)
  * ... (other modules)

Each module has isolated storage space, preventing cross-module conflicts.

### Transaction Processing

BitSDK handles the complete transaction lifecycle:

**Transaction Flow:**

```
1. User submits transaction
2. Mempool receives and validates
3. Validator proposes block with transactions
4. AnteHandler runs pre-execution checks
5. Message routed to module handler
6. Module executes business logic
7. State changes committed
```

**Bitplanet leverages:**

* **AnteHandler chain**: Signature verification, fee deduction, gas metering
* **Message routing**: Automatic routing to correct module based on message type
* **Gas system**: Prevents infinite loops and DOS attacks
* **Fee market**: Transaction prioritization and validator compensation

### Consensus

Bitplanet uses CometBFT (Tendermint) consensus provided by BitSDK:

**What BitSDK Provides:**

* Byzantine Fault Tolerant consensus (tolerates 1/3 malicious validators)
* Instant finality (no chain reorganizations)
* Validator set management
* Block production and propagation

**Bitplanet's Configuration:**

* Block time: \~6 seconds (deterministic)
* Validator selection: Top validators by stake
* Slashing for misbehavior (downtime, double-signing)

### Governance

Bitplanet leverages BitSDK's on-chain governance:

**Governance Capabilities:**

* Parameter updates for any module
* Software upgrade coordination
* Custom proposal types (e.g., CoreGrantApplication)

**How Bitplanet Uses It:**

```
x/brahma parameters → Updated via governance proposals
x/precompile addresses → Controlled by governance
Consensus parameters → Adjustable through voting
```

All 12 x/brahma parameters are governance-controlled, enabling community-driven protocol evolution.

### Module Keepers

Bitplanet's custom modules use standard BitSDK keepers:

**x/brahma Integration:**

* **AccountKeeper** - Query and manage accounts
* **BankKeeper** - Transfer tokens, check balances
* **MintKeeper** - Query inflation parameters
* **EVMKeeper** - Interact with EVM state

This enables x/brahma to:

* Mint/burn tokens (via BankKeeper)
* Query inflation data (via MintKeeper)
* Call EVM contracts (via EVMKeeper)
* All using standard BitSDK interfaces

### gRPC/REST APIs

BitSDK provides automatic API generation:

**What Bitplanet Gets:**

* gRPC server (port 9090)
* REST gateway via gRPC-Gateway (port 1317)
* Automatic endpoint generation from protobuf definitions
* Query and transaction submission interfaces

**Example:**

```protobuf
// Define query in proto file
rpc QueryAI(QueryAIRequest) returns (QueryAIResponse);

// Automatically available at:
// gRPC: localhost:9090/brahma.QueryAI
// REST: localhost:1317/bitplanet/brahma/v1/ai/{id}
```

### CLI Generation

BitSDK's AutoCLI automatically generates command-line interfaces:

**Auto-Generated Commands:**

```bash
evmd query brahma ai <id>           # Auto-generated from QueryAI
evmd tx brahma request-for-core ... # Auto-generated from MsgRequestForCore
```

No manual CLI code needed - derived from protobuf definitions.

### IBC Support

Bitplanet inherits Inter-Blockchain Communication protocol:

**What This Enables:**

* Cross-chain token transfers
* IBC channel creation and management
* Light client verification
* Packet relay infrastructure

**Custom Enhancement:** The x/transfer module is extended to support ERC-20 token transfers over IBC, combining Cosmos and EVM ecosystems.

## Benefits of BitSDK Foundation

### Proven Infrastructure

**Battle-Tested:**

* Years of production use across 50+ chains
* Validator ecosystem and tooling
* Well-understood security model

**Standard Tooling:**

* Compatible with Cosmos ecosystem tools
* Familiar interfaces for Cosmos developers
* Existing infrastructure (explorers, wallets)

### Modular Architecture

**Clean Separation:**

* Standard modules handle common functionality
* Custom modules add Bitplanet-specific features
* No need to reimplement core blockchain logic

**Easy Integration:**

```go
// Adding x/brahma to BitSDK app
app.BrahmaKeeper = brahmakeeper.NewKeeper(
    appCodec,
    keys[brahmatypes.StoreKey],
    app.AccountKeeper,
    app.BankKeeper,
    app.MintKeeper,
)
```

### Development Efficiency

**What Bitplanet Doesn't Need to Build:**

* Consensus mechanism
* P2P networking
* State storage and commitment
* Transaction mempool
* Account system
* Fee handling
* API servers
* CLI framework

**Focus on Core Innovation:**

* AI attribution logic (x/brahma) - see [**AI Tensor Matrix**](/advanced-topics/token-economics-technical/ai-tensor-matrix.md)
* EVM integration (x/vm)
* Reward distribution algorithms - see [**Inflation Mechanism**](/advanced-topics/token-economics-technical/inflation-mechanism.md)
* Custom precompiles (x/precompile)

### Upgradability

**BitSDK Enables:**

* Coordinated on-chain upgrades
* Height-based upgrade plans
* Migration scripts for state changes
* No hard forks required

**Example Upgrade Flow:**

```
1. Governance proposes upgrade at height H
2. Validators vote and approve
3. At height H-1, nodes halt
4. Validators upgrade binary
5. Network resumes with new features
```

## Bitplanet-Specific Customizations

While leveraging BitSDK built on Cosmos SDK foundation, Bitplanet adds:

### Custom Modules

**x/brahma:**

* AI tensor tracking
* Core grant management
* Reward distribution (via BeginBlock hook)

**x/precompile:**

* EVM-Cosmos bridge contracts
* Precompile address registry

**x/vm (BitEVM):**

* Full EVM execution environment
* Ethereum transaction compatibility

### Extended Modules

**x/transfer (IBC):**

* Overrides standard ICS-20 implementation
* Supports ERC-20 token transfers over IBC

**x/erc20:**

* Bidirectional Cosmos coin ↔ ERC-20 conversion
* Seamless ecosystem bridging

### Hooks Integration

**BeginBlock Hook:**

```go
func (app *EVMD) BeginBlocker(ctx sdk.Context) {
    // Standard BitSDK processing
    ...

    // x/brahma inflation distribution
    app.BrahmaKeeper.DistributeRewards(ctx)
}
```

The x/brahma module hooks into BitSDK's block lifecycle to distribute rewards automatically.

## Integration Architecture

{% @mermaid/diagram content="graph TB
subgraph BA\[Bitplanet Application]
direction TB
CM\[Custom Modules]
B\[x/brahma - AI attribution]
P\[x/precompile - bridges]
V\[x/vm - EVM]
CM --> B
CM --> P
CM --> V
end

```
subgraph CS[BitSDK Framework]
    direction TB
    MS[Module System]
    SM[State Management - KVStore/IAVL]
    TP[Transaction Processing]
    API[gRPC/REST APIs]
    CLI[CLI Framework]
    GOV[Governance]
end

subgraph CBF[CometBFT Consensus]
    direction TB
    BP[Block Production]
    VV[Validator Voting]
    PN[P2P Networking]
end

BA --> CS
CS --> CBF" %}
```

**Key Insight:** Bitplanet builds on top of BitSDK rather than forking it, enabling seamless upgrades and ecosystem compatibility.