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:

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

• 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:

// 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

• 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

• Maintains accurate historical records

Range Queries

Prefix-Based Iteration

Enables efficient queries without full store scans:

All contributors for AI at height:

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

First N AIs:

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 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