> 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/state-management.md).

# State Management

Bitplanet uses BitSDK's KVStore backed by an IAVL tree for state storage. This page explains the core storage architecture, key encoding schemes, and storage patterns.

## Storage Architecture

### IAVL Tree Foundation

BitSDK stores all state in an IAVL (Immutable AVL) tree:

**Key Properties:**

* **Immutable Snapshots**: Each block height creates a new tree version
* **Merkle Proofs**: State commitment in block headers enables light client verification
* **Balanced Structure**: O(log n) read/write operations via self-balancing AVL+ tree
* **Historical Access**: Archive nodes maintain full history; pruning nodes keep recent N versions

**State Commitment:**

```
Block Header
└─ App Hash (root of all modules)
   ├─ x/brahma Store Hash
   ├─ x/evm Store Hash
   ├─ x/bank Store Hash
   └─ ... (other module stores)
```

### Module Store Organization

Each BitSDK module has an isolated KVStore identified by unique prefixes. The x/brahma module uses:

```go
AITensorsPrefix             = 0x01  // Contribution tensors
CoreGrantApplicationsPrefix = 0x02  // Core grant permissions
AddrsPrefix                 = 0x03  // Address mappings
AIPrefix                    = 0x04  // AI metadata
KeyPrefixClaimableRewards   = 0x05  // Pending rewards
KeyPrefixMarketCaps         = 0x06  // Market cap history
KeyPrefixAIIDOrdered        = 0x20  // AI insertion order
KeyPrefixAIIDOrderedCount   = 0x21  // Total AI count
```

**Benefits:**

* Prevents key collisions between modules
* Enables efficient range scans per prefix
* Logical separation of data types

## Key Encoding Schemes

### Length-Prefixed Encoding (AITensor Keys)

Critical for preventing collisions with variable-length AI IDs:

**Format:**

```
[Length: 2 bytes] + [AI ID: variable] + [Block Height: 8 bytes] + [Address: optional]
```

**Example:**

```
AI "alpha" (5 bytes) at block 1000:
0x0005 616c706861 00000000000003e8

AI "alphabeta" (9 bytes) at block 1000:
0x0009 616c70686162657461 00000000000003e8
```

**Why Length-Prefix:**

* Without prefix: `"ab" + height:3100` could collide with `"abc" + height:100`
* With prefix: `0x0002|ab|3100` vs `0x0003|abc|100` → distinct keys
* Enables deterministic parsing and range queries

### Simple Concatenation (Other Keys)

Most keys use direct prefix + identifier:

```
AI Metadata:         0x04 + AI_ID
Core Grant:          0x02 + requester_address
Claimable Rewards:   0x05 + address
Market Caps:         0x06 + AI_ID
AI Insertion Order:  0x20 + index (8 bytes, big-endian)
```

## Storage Patterns

### Circular Buffer (Market Cap History)

Fixed-size rolling window prevents unbounded growth:

**Implementation:**

```
Max: 1,000 entries per AI
When full: Truncate oldest entries
Storage: Protobuf strings (LegacyDec precision)
```

**Purpose:**

* Smooth market cap volatility (30-block average) - see [**Inflation Mechanism**](/advanced-topics/token-economics-technical/inflation-mechanism.md)
* Prevent consensus failures from non-deterministic state
* Enable historical queries without storage bloat

### AI Insertion Order

Tracks creation sequence of all AIs for deterministic reward distribution:

**Storage Structure:**

```
KeyPrefixAIIDOrdered (0x20):
├─ [0x20 + uint64(0)] → "ai_genesis"      // First AI
├─ [0x20 + uint64(1)] → "ai_alpha"        // Second AI
├─ [0x20 + uint64(2)] → "ai_beta"         // Third AI
└─ ...

KeyPrefixAIIDOrderedCount (0x21):
└─ [0x21] → uint64(1234)                  // Total count
```

**Implementation:**

```go
// Store new AI
index := getAICount()
store.Set(0x20 + bigEndian(index), aiID)
store.Set(0x21, index + 1)

// Iterate first N AIs
for i := 0; i < maxAIsForRewards; i++ {
    aiID := store.Get(0x20 + bigEndian(i))
    processRewards(aiID)
}
```

**Purpose:**

* **Reward Eligibility**: Only first N AIs receive inflation (default: 500) - see [**Inflation Mechanism**](/advanced-topics/token-economics-technical/inflation-mechanism.md)
* **Anti-Spam**: Prevents dilution attacks via mass AI creation
* **Deterministic Iteration**: Same order across all validators
* **Performance**: O(1) lookups, O(N) iteration for rewards

### Tensor Merging (Concurrent RfCs)

Multiple submissions in same block are merged:

**Process:**

1. Load existing tensor at current height
2. For each contributor:
   * If exists: Add contributions element-wise
   * If new: Append row
3. Store merged tensor

**Purpose:**

* Prevents data loss from concurrent submissions
* Accumulates all contributions within a block - see [**AI Tensor Matrix**](/advanced-topics/token-economics-technical/ai-tensor-matrix.md)
* Maintains accurate historical records

## Range Queries

### Prefix-Based Iteration

Enables efficient queries without full store scans:

**All contributors for AI at height:**

```go
prefix := buildAITensorRowKey(aiID, height) // Without address
iterator := store.Iterator(prefixRange(prefix))
for ; iterator.Valid(); iterator.Next() {
    // Process each contributor row
}
```

**First N AIs:**

```go
for i := 0; i < maxAIsForRewards; i++ {
    key := append(AIIDOrderedPrefix, bigEndian(i)...)
    aiID := store.Get(key)
}
```

### Processing Limits

Governance parameters prevent unbounded iteration:

| Parameter                   | Default | Purpose                        |
| --------------------------- | ------- | ------------------------------ |
| `max_ais_for_rewards`       | 500     | Max AIs processed per block    |
| `max_ai_block_heights`      | 1,000   | Max historical blocks per AI   |
| `max_tensor_rows_per_block` | 1,000   | Max contributor rows per block |

These limits ensure operations complete within block time constraints. See [**Inflation Mechanism**](/advanced-topics/token-economics-technical/inflation-mechanism.md) for how these parameters affect reward distribution.

## Storage Optimization

### Lazy Loading

Values loaded only when accessed:

* Iterators don't load all values into memory
* Reduces memory footprint
* Improves query performance

### Deterministic Ordering

Lexicographic key ordering ensures:

* Consistent iteration across validators
* Predictable range query results
* Consensus-safe operations

### Big-Endian Encoding

Block heights and indices use big-endian encoding:

* Enables natural lexicographic ordering
* Efficient range queries by height
* Deterministic across architectures

## Pruning Strategies

**Archive Nodes:**

* Keep all historical IAVL versions
* Enable queries at any block height
* Higher storage requirements (\~1TB+)

**Pruning Nodes:**

* Retain recent N versions only (configurable)
* Reduce storage footprint (\~100GB)
* Sufficient for validation and recent queries

**Default Strategy:**

* Keep last 100,000 blocks + every 10,000th block
* Balances storage efficiency with historical access

## Data Integrity

### Collision Resistance

Length-prefixed keys prevent unintended collisions:

```
Different AI IDs + heights → Always distinct keys
```

### Overflow Protection

Safe arithmetic when calculating storage offsets:

* Validate AI ID length < 65,535 bytes (uint16 max)
* Check array bounds before indexing
* Use big-endian for consistent byte ordering

### Validation at Write Time

State transitions validate before storage:

* Contribution arrays match type count
* Addresses are valid format
* Allocations don't overflow uint64