> 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/architecture-overview.md).

# Architecture Overview

Bitplanet is a blockchain infrastructure designed for AI data attribution and fair value distribution. Built on BitSDK with EVM compatibility, it transforms traditional asset ledgers into attribution and evaluation systems for AI economies.

## System Design Philosophy

### Why Bitplanet Exists

Traditional AI systems lack transparent mechanisms for tracking contributions and fairly compensating creators, platforms, and contributors. Bitplanet solves this by:

* **Tracking AI contributions** through a multi-dimensional tensor matrix
* **Distributing rewards** based on real economic value (market capitalization) rather than subjective benchmarks
* **Ensuring transparency** through blockchain-based attribution records
* **Enabling governance** where token holders control economic parameters

### Dual-Layer Architecture

Bitplanet combines two blockchain paradigms:

[**BitSDK Layer**](/advanced-topics/blockchain-architecture/bit-sdk.md) (Backend)

* State management and data storage
* Custom modules for AI attribution logic
* gRPC/REST APIs for querying data
* Governance and consensus mechanisms

[**EVM Layer**](/advanced-topics/blockchain-architecture/evm-compatibility.md) (Frontend)

* Smart contracts for token operations
* Familiar Web3 interfaces (ethers.js, web3.js)
* ERC-1155 and ERC-20 token standards
* Easy integration for AI App developers

This design provides the **flexibility of BitSDK** for custom logic and the **accessibility of Ethereum** for developers.

## Core Components

### AIs

AIs are registered entities in the Bitplanet system representing AI models, datasets, or AI-powered applications.

**Key Properties**:

* Unique identifier (AI ID)
* Creator address (receives 40% of rewards)
* Associated AI App address (receives 40% of rewards)
* Market capitalization (determines reward weight)
* Current gem supply

**Lifecycle**:

1. Creator submits Core Grant Application via governance
2. Proposal approved → Cores allocated
3. Creator mints Gems from Cores via smart contract
4. AI accumulates rewards based on market cap
5. Rewards claimed by creators, AI apps, and contributors

### Cores

Core tokens are genesis allocations granted through governance proposals. See [**Core Tokens**](/advanced-topics/token-economics-technical/core-tokens.md) for details.

**Purpose**:

* Bootstrap new AIs with initial token supply
* Controlled distribution via governance approval
* One-time allocation per approved application

**Usage Flow**:

* Creator applies via `CoreGrantApplication` message
* Community votes on proposal
* Approved → Cores allocated to creator
* Creator converts Cores to Gems via `GemCoreNFT` contract
* Conversion ratio: 1 Core = 1 Gem

### Gems

Gem tokens represent AI-specific value and are the primary tokens for AI economies. See [**Gem Tokens**](/advanced-topics/token-economics-technical/gem-tokens.md) for details.

**Characteristics**:

* Minted from Cores via smart contract
* Tradeable ERC-1155 tokens (with ERC-20 adapters)
* Each AI has its own Gem type
* Total supply determines market cap

**Token Standards**:

* **ERC-1155**: Native format in `GemCoreNFT` contract
* **ERC-20**: Wrapped format via adapter contracts for DEX compatibility

### Contributors

Contributors are users who participate in AI development and receive rewards. See [**AI Tensor Matrix**](/advanced-topics/token-economics-technical/ai-tensor-matrix.md) for contribution tracking details.

**Contribution Types**:

* **TRAIN**: Training data or model improvements
* **REFER**: Referrals and community growth
* **CREATE**: Content creation or enhancements (Required)
* **PROMPT**: Prompt engineering and testing
* **REVENUE**: Revenue generation contributions
* **MARKET\_CAP**: Market capitalization increase contributions

**Reward Mechanism** - See [**Reward Distribution**](/advanced-topics/token-economics-technical/reward-distribution.md):

* Contributions recorded in AI Tensor Matrix
* 20% of AI rewards distributed to contributors
* Distribution proportional to contribution quantities
* Rewards accumulate and are claimable on-chain

## How It Works

### Bitplanet Workflow Overview

**1. AI Registration & Core Allocation**

```
Creator → CoreGrantApplication → Governance Vote → Cores Allocated
```

**2. Gem Minting**

```
Cores → GemCoreNFT.mintGem() → Gems Created
```

**3. Contribution Tracking**

```
Approved Requester → Request for Core (RfC) → Tensor Matrix Updated
```

**4. Inflation Distribution (Every Block)**

```
New Supply (50% and adjustable via governance) → Market Cap Weighting → AI Rewards
```

Per AI reward split:

* **40%** → AI App (claimable)
* **40%** → Creator (claimable)
* **20%** → Contributors (by tensor matrix)

**5. Reward Claiming**

```
Check Balance → claimRewards() → Tokens Transferred
```

### 1. AI Registration and Core Allocation

The creator submits a proposal requesting Cores for their AI. Token holders vote on the proposal. If approved, Cores are allocated to the creator's address.

### 2. Gem Minting

The creator calls the `mintGem` function on the `GemCoreNFT` smart contract, burning Cores and minting an equivalent amount of Gems.

### 3. Contribution Tracking

Approved requesters submit Request for Core (RfC) messages containing contribution data. The AI Tensor Matrix records contribution quantities for each contributor.

For detailed information about the AI Tensor Matrix and contribution attribution, see [**AI Tensor Matrix**](/advanced-topics/token-economics-technical/ai-tensor-matrix.md).

### 4. Inflation Distribution

Every block, newly minted tokens are distributed proportionally based on AI market capitalization, split between creators, AI App operators, and contributors.

For detailed information about the inflation mechanism and reward distribution, see [**Inflation Mechanism**](/advanced-topics/token-economics-technical/inflation-mechanism.md).

### 5. Reward Claiming

Users can query their accumulated rewards and submit claim transactions to transfer tokens to their account.

For detailed information about reward claiming mechanics, see [**Reward Distribution**](/advanced-topics/token-economics-technical/reward-distribution.md).

## System Architecture

### Layer Interaction

{% @mermaid/diagram content="graph TB
subgraph Users\["Users / AI Apps"]
end

```
subgraph EVM["EVM Layer"]
    GC[GemCoreNFT Contract]
    BF[BeaconFactory]
end

subgraph Cosmos["BitSDK Layer"]
    BR[x/brahma Module]
    PC[x/precompile Module]
end

Users -->|Web3| EVM
Users -->|REST/gRPC| Cosmos
GC <--> BR
BF <--> PC
EVM -.->|Hooks| Cosmos" %}
```

### Cross-Layer Interaction Sequences

**1. Core to Gem Conversion**

{% @mermaid/diagram content="sequenceDiagram
participant User
participant GemCoreNFT as GemCoreNFT Contract

```
User->>GemCoreNFT: mintGem()
GemCoreNFT->>GemCoreNFT: Burn 1 Core
GemCoreNFT->>GemCoreNFT: Mint 1 Gem
GemCoreNFT-->>User: Gem minted (1:1 ratio)" %}
```

**2. Reward Claiming (User → EVM → Cosmos)**

{% @mermaid/diagram content="sequenceDiagram
participant User
participant EVM as EVM Layer<br/>(GemCoreNFT)
participant Cosmos as BitSDK<br/>(x/brahma)

```
User->>Cosmos: Query claimable rewards
Cosmos-->>User: Return balance
User->>EVM: claimRewards()
EVM->>Cosmos: Emit BplCoinClaimed event
Cosmos->>Cosmos: PostTxProcessing hook
Cosmos->>Cosmos: Validate claim & transfer tokens
Cosmos->>Cosmos: Reset claimable balance
EVM-->>User: Transaction receipt" %}
```

**3. Contribution Attribution (Cosmos → EVM → Cosmos)**

{% @mermaid/diagram content="sequenceDiagram
participant AIApp
participant Cosmos as BitSDK<br/>(x/brahma)
participant EVM as EVM Layer<br/>(GemCoreNFT)

```
AIApp->>Cosmos: RequestForCore (contribution tensors)
Cosmos->>Cosmos: Validate Core Grant Application
Cosmos->>Cosmos: Check allocation quota
Cosmos->>Cosmos: Store tensor matrix
Cosmos->>EVM: Call mintCore(contributors, amounts)
EVM->>EVM: Mint core tokens
Cosmos->>Cosmos: Deduct from allocation quota
EVM-->>AIApp: Cores minted to contributors" %}
```

### Data Flow

**State Storage** (BitSDK)

* AI records (creator, AI App, market cap)
* AI Tensor Matrix (contributions by actor × type)
* Core Grant Applications (proposals)
* Claimable reward balances
* Module parameters (governance-controlled)

**Token Operations** (EVM)

* Gem minting from Cores
* Token transfers and approvals
* ERC-1155 ↔ ERC-20 conversions
* UUPS upgradeable contracts for future enhancements
* BeaconProxy pattern for deploying multiple token instances

**Integration Points**

* `BeginBlock` hook: Distributes inflation to AI rewards
* Precompile registry: Connects EVM contracts to Cosmos state
* Event emission: Both layers emit events for indexing

## Key Differentiators

### Market Cap-Based Distribution

Unlike systems using subjective benchmarks or fixed allocations, Bitplanet distributes rewards proportional to **real market value**. AIs with higher market caps receive more inflation rewards, creating natural economic incentives.

**Current:** Market cap = gem supply (ERC1155 totalSupply)

**Future:** Market cap = `rolling_average[ (W1 × gem_supply) + (W2 × gem_market_cap) ]` where W1, W2 are governance-adjustable weights. This weighted formula mitigates price manipulation attacks on thin AMM liquidity.

### Multi-Dimensional Contribution Tracking

The AI Tensor Matrix supports multiple contribution types (TRAIN, REFER, CREATE, PROMPT) with extensibility for future types. This enables nuanced attribution beyond simple transaction counts.

### Governance-Controlled Economics

All economic parameters are controlled via governance proposals:

* Inflation percentages
* Reward split ratios
* Scalability limits
* New contribution types

This ensures the system can adapt to changing needs without hard forks.

### Hybrid Architecture Benefits

**For Developers**:

* Use familiar Web3 tools (MetaMask, Hardhat, ethers.js)
* Access BitSDK power (custom state queries, governance)

**For Users**:

* Standard ERC-20/ERC-1155 wallet compatibility
* Transparent on-chain attribution records

**For Validators**:

* BitSDK validator infrastructure
* Proven consensus and network security