Status: Draft
Type: Standards Track
Category: Core
Cowboy Cloud and Cowboy Chain. This CIP specifies the Cowboy protocol. Cowboy Cloud runs on this protocol today. Cowboy Chain, a public network on the same protocol, is under consideration for a future release. Where the two differ, this CIP says so.
1. Abstract
Background
Cowboy needs persistent blocks, canonical state and rebuildable query indexes.Goal
This CIP specifies how Cowboy persists blocks and state. QMDB, a flat key-value store with Blake3 hashing, holds state. Cowboy uses:- Sequential ledger for persisting consensus blocks;
- QMDB as the canonical state repository, with fixed 86-byte keys and Blake3-based Merkle commitments;
- StateValue codec (commonware
Write/Readbinary, one tag byte per variant) as the encoding format; - Namespaced key space with byte-prefix routing for accounts, storage, timers, mailbox, and system state;
- Rebuildable auxiliary indexes to support queries and browsing;
- Merkle proof layer for light client state verification (C15 State Proofs).
2. Background and motivation
Cowboy uses QMDB for:- Performance: Flat KV with Blake3 hashing provides 10-100x throughput vs. hexary MPT for state reads/writes;
- Simplicity: Fixed 86-byte keys (1-byte prefix + 20-byte address + 65-byte slot/hash/zero-pad) avoid tree rebalancing;
- Proof capability: QMDB native Merkle proofs + Binary Merkle Tree (BMT) for TX/receipt roots provide equivalent light client verification;
- Production-proven: Running on devnet with full E2E proof verification.
3. Overall design
Data is organized into three layers:- Ledger: Append-only block segment files;
- QMDB (canonical state): Three flat KV databases (
state_db,tx_index,tx_receipts) with Blake3 Merkle commitments; - Aux (rebuildable indexes): Auxiliary tables map transaction hashes to locations and block hashes to heights, and index events for reads. They are rebuildable and excluded from the state root.
3.1 Three-layer relationships and data flow
The node executes ledger blocks to produce QMDB state roots. It derives read-optimized auxiliary indexes from the ledger and QMDB. The node can rebuild QMDB and the auxiliary indexes from the ledger.-
Write and Commit Path (when a block is accepted):
- After consensus produces a block, the node appends its header and transactions/messages to the ledger. The header contains
state_root,tx_root,receipt_root. - The node replays the block speculatively to produce a write batch. It updates account/actor/storage/timer/mailbox/deferred-tx keys and computes three Merkle roots.
- The node rejects the block if its computed roots differ from the header roots.
- The node caches the write batch and applies it atomically to QMDB on finalization.
- The node derives auxiliary indexes from the ledger and QMDB. This work can run asynchronously.
- After consensus produces a block, the node appends its header and transactions/messages to the ledger. The header contains
-
Read Path (how they cooperate during queries):
- For a transaction hash, the node queries
tx_indexfor its location, reads the raw transaction from the ledger, and reads its receipt fromtx_receipts. - For an address and slot, the node reads
state_dbdirectly and can return a QMDB Merkle proof. - For an event topic, the node queries auxiliary indexes for candidates and verifies them against receipts.
- For a transaction hash, the node queries
-
Consistency invariants:
state_db.root_at(N) == Ledger.block[N].state_root;tx_rootcomputed via BMT over block transactions matches header;receipt_rootcomputed via BMT over block receipts matches header;- After deleting Aux, can rebuild from Ledger+QMDB within bounded time.
3.2 Rollback and rebuild
- Speculative rollback: After speculative execution, the write batch is cached but not applied. On finalization, the cached batch is applied atomically.
- Fork reorganization: Replay from last finalized height using Ledger as source of truth.
- Aux-only corruption: Rebuild from Ledger + QMDB receipts; does not affect consensus correctness.
- QMDB corruption: Replay Ledger from genesis or trusted snapshot to regenerate state.
4. Key space and namespaces
4.1 State key format
All state keys are 86 bytes (fixed length):4.2 State prefixes
Normative: the table below is theStatePrefixallocation. The storage layout uses0x01–0x22and0x24–0x26(37 distinct prefixes); there is no0x00, and0x23remains unallocated. The earlier CIP-27 draft’sCodeMeta = 0x1Eassignment is superseded:0x1Ebelongs toTimerIndexPage. The proposed CodeMeta carrier requires a separate coordinated allocation before it can ship; this storage amendment does not activate it. State key prefixes and StateValue value tags are separate namespaces.
For
Library (0x14) and ActorLibPin (0x15), slot(65) is key ‖ zero-pad-to-64 ‖ len(u8) for keys of at most 64 bytes, and keccak256(key) ‖ zero-pad-to-64 ‖ 0xFF for longer keys. These rows retain their own prefixes in both modes.
Actor-storage scans walk only the 0x03 verbatim range. Keys longer than 64 bytes are stored under 0x22 and remain reachable by exact-key reads, but their original keys cannot be enumerated. Physical storage copies and eviction walks cover both ranges.
4.3 Value encoding
- StateValue variants in the current release:
Account(Account)0x01,Actor(Actor)0x02,ActorStorageEntry(Vec<u8>)0x03,MailboxMessage(Message)0x04 (v2 form at 0x11),Timer(IndexedTimer)0x05,TimerList(TimerList)0x06,DeferredTx(Transaction)0x07,DeferredTxList(DeferredTxList)0x08,ActorEventList(ActorEventList)0x09,SystemBytes(Vec<u8>)0x0A (carries the head/tail, KV count/bytes and dead-letter tail scalars; these are values under their own key prefixes, not variants),Code(Vec<u8>)0x0B,Library(ActorLibrary)0x0C,ActorLibPin(ActorLibPin)0x0D,EventSub(ActorEventSubscription)0x0E,EventSubIndexValue(EventSubIndex)0x0F,FairnessCounter(FairnessCounter)0x10,TimerIndexMeta(TimerIndexMeta)0x12, andTimerIndexPage(TimerIndexPage)0x13. The old CIP-27 proposal for a CodeMeta value at 0x12 conflicts with TimerIndexMeta and is not an allocation in this release. - Wallet marker:
StatePrefix::WalletMark = 0x25uses the exact 86-byte key0x25 ‖ address[20] ‖ 0x00[65]. The value reusesStateValue::SystemBytes, wire tag0x0A, with a one-byte payload0x01; its complete commonware-codec bytes are0A 01 01(tag, canonical unsigned-varint vector length 1, payload). Test vector: encodingStateValue::SystemBytes([0x01])yields exactly[0x0a, 0x01, 0x01], and decoding those bytes yields the same value. This uses commonwareVec<T>framing; CBQS has its own explicit fixed-width lengths, and transaction bytes use their versioned binary codec. There is no new StateValue variant or wallet-specific value tag. Absence means unclaimed. A present row with another variant or any payload other than exactly[0x01]MUST fail as invalid storage state, never be treated as absence. Accepted signatures write this value idempotently under the same batch/savepoint as nonce acceptance; it remains committed after instruction failure and is never removed by actor lifecycle or account balance changes. An escaping storage failure rolls back acceptance, including marker writes. Reads use the current speculative view, so a preceding claim in the same block prevents deploy/fork. See CIP-40 §12.1 for admission. - Mailbox model: a mailbox is a FIFO ring of individually-keyed messages (
0x04 ‖ addr ‖ be(seq)→MailboxMessage), bounded by the head (0x10) and tail (0x11) pointer keys — not a singleVecDeque<Message>blob. Overflow spills to the dead-letter ring (0x1C/0x1D). - All values, including transactions, use the commonware
Write/Readbinary codec. - Decode bounds enforced:
DeferredTxListmax 16,384 entries;ActorEventListmax 1,000 entries.
5. QMDB state commitments
5.1 State root
QMDB computes a Merkle root over all key-value pairs instate_db using Blake3 hashing. This root is included in every block header as state_root.
5.2 Transaction root
Computed via Binary Merkle Tree (BMT) overkeccak256 hashes of all transactions in the block:
5.3 Receipt root
The node computes the BMT over each receipt’s commonware-codec encoding (Encode):
keccak256("empty_receipts"). TransactionReceipt::rlp_encode() provides a separate Ethereum-compatible serialization. It does not feed receipt_root.
5.4 Proof system
QMDB provides native Merkle inclusion proofs for any state key: RPC Endpoints:GET /proof/account/{address}— account state proofGET /proof/actor/{address}— actor metadata proofGET /proof/storage/{address}/{key}— actor storage slot proofGET /proof/tx/{tx_hash}— transaction inclusion proof (BMT)GET /proof/receipt/{tx_hash}— receipt inclusion proof (BMT)POST /proof/multi— batch state proof (up to 256 keys per request)
cowboy-proof-verifier crate verifies proofs in Rust and WASM using only the proof data and state root.
6. Execution and consistency
6.1 Block lifecycle
- Fetch block: Read block header and body from Ledger.
- Pre-check: Validate signatures, nonces, gas limits.
- Speculative execution: Execute all transactions in batch mode:
- The node calls
begin_batch(), executes the transactions and callscommit_batch(). - Produces
state_pending,tx_index_pending,tx_receipts_pendingwrite sets - Processes timers, deferred TXs (with per-actor limits and expiration)
- The node calls
- Compute roots: Calculate
state_root,tx_root,receipt_rootfrom the write set. - Root verification: Roots must match block header; reject if mismatch.
- Cache: Store write batch for later finalization.
- On finalization: Apply cached batch to QMDB databases.
6.2 Atomic commit
The node commits the QMDB databases sequentially, starting withstate_db, followed by tx_index and tx_receipts. Each commit is atomic. After a crash between commits, the consensus layer replays finalized blocks on restart (see §3.2).
6.3 Determinism requirements
- All execution engines must write via unified
StateKey/StateValueinterface; - No wall clock, no external randomness during execution;
- Identical block + identical state must produce identical roots.
6.4 Errors and block rejection
- Root mismatch: Block rejected.
- Storage errors: Logged with opaque messages to clients; detailed errors server-side only.
- Resource exhaustion: Degrade gracefully (pause Aux derivation), never break QMDB atomicity.
7. Auxiliary indexes (rebuildable)
7.1 Index schemas
tx_index:tx_hash → TransactionLocation { block_hash, tx_index }tx_receipts:tx_hash → TransactionReceipt { ... }- Event indexes: Per-actor event lists (in
state_dbasActorEventList)
7.2 Construction
After block commit, scan transactions and receipts to update auxiliary indexes. Updates can lag behind finalization without affecting consensus.7.3 Rebuild
Full rebuild by replaying Ledger from genesis. Incremental rebuild from last consistent height.8. Snapshots and sync
8.1 Sync modes
- Full node sync: Replay Ledger from genesis or trusted snapshot.
- Fast sync: Download QMDB state at height
H, verify root matches block header, replay fromH. - Light client: Maintain block header chain; verify state via Merkle proofs (
/proof/*endpoints).
8.2 Proof packaging
- Batch proofs (
POST /proof/multi) deduplicate shared proof nodes across multiple keys. - Max 256 keys per batch request.
- Responses include proof version, chunk location, MMR leaves, and operation digests.
9. Performance
9.1 QMDB advantages
- O(1) reads/writes: Flat KV with fixed-size keys avoids tree traversal;
- Efficient hashing: Blake3 is 3-5x faster than Keccak-256;
- Batch operations: Block-level batch commit with deferred merkleization;
- Bounded cache: Speculative cache limited to 8 entries (evicts oldest on overflow).
9.2 Metrics
Key metrics:block_apply_ms, proof_generation_ms, batch_commit_ms, speculative_cache_size.
10. Security
- Canonical source: Only QMDB
state_dbas authoritative state; - Proof integrity: Merkle proofs verified against
state_rootin finalized block header; - DoS mitigation: Decode bounds on all list types; per-actor limits on timers (1,024) and deferred TXs (64); deferred TX expiration (1,000 blocks); a global RPC rate limit (100 req/s) applies to all endpoints, and the proof endpoints (§5) — whose Merkle/QMDB proof generation is comparatively expensive (
/proof/multibatches up to 256 keys) — additionally SHOULD sit behind a per-IP limiter so a single source cannot exhaust the shared budget; - Error opacity: Storage errors return opaque messages to API callers; detailed errors logged server-side only.
11. Parameters
STATE_KEY_LEN = 86(fixed key size)MAX_SPECULATIVE_CACHE_ENTRIES = 8MAX_DEFERRED_TX_LIST_SIZE = 16,384MAX_ACTOR_EVENTS = 1,000MAX_TIMERS_PER_ACTOR = 1,024MAX_PENDING_DEFERRED_PER_ACTOR = 64DEFERRED_TX_MAX_AGE_BLOCKS = 1,000SNAPSHOT_INTERVAL_BLOCKS = 100_000
12. State rent
This section is the normative source for actor-state rent mechanics. Whitepaper §17.5 now references this section. Rationale for the move: rent is a CIP-4 concern (it governs the lifecycle of state in the QMDB store); the WP retains a one-paragraph operational summary plus the governance monitoring cadence.
12.1 Mechanism
Actors belowRESERVED_SYSTEM_ADDRESS_LIMIT (0x100) are exempt from rent and from the aggregate storage-capacity limits (key count and byte limit, §12.4), and are never evicted (Technical Whitepaper §3.2 and §9).
Non-reserved actors pay ongoing rent measured in CBY on the bytes they store:
kv_bytes(actor)= the actor’s stored key-value bytes (its read-your-writes byte counter).RENT_MIN_BILLABLE_BYTES= 1,024 bytes — the billing floor, so an actor that stores nothing still pays rent and is eventually evicted.rent_rate= the deployed defaultrent_rate_atto = 2_739_726_027_397atto/byte/epoch (≈ 0.001 CBY/byte/year at 365 epochs; governance-tunable, Tier-0 per CIP-12 — see §12.5).rent_epoch_length= 1 day at 1-second blocks per WP §6.1 (i.e., 86,400 blocks per epoch).- Consensus carrier:
rent_debtlives on theActorrecord (codec field, exactly as the current encoder has it) — not under a Governance/SystemBytes key; one carrier, the one the code already uses. The Actor v9 record’s rent fields arerent_debt: u128,last_settled_epoch: u64,rate_stamped_atto: u128(the rate in force when debt was last carried; no rule reads it),dormant_since_epoch: Option<u64>andpre_evict_storage_hash: Option<[32]u8>; it carries no quota or bond field.
epochs_due = current_epoch − last_settled_epoch; when that is zero there is nothing to do. Because kv_bytes changes only while the actor executes, and settlement precedes every handler, the current kv_bytes is what every elapsed epoch held. Settlement then:
- adds the elapsed rent to the debt:
owed = rent_debt + rent_per_rent_epoch × epochs_due(atto, u128); - pays whole wei from the actor’s balance:
paid_wei = min(balance_wei, floor(owed / 10^9)), debits exactlypaid_wei, and setsrent_debt = owed − paid_wei × 10^9. The sub-wei remainder carries inrent_debt, and nothing else is subtracted; - sets
last_settled_epoch = current_epoch.
eviction_threshold_epochs epochs of its current rent: rent_debt ≥ 10^9 and rent_debt > eviction_threshold_epochs × rent_per_rent_epoch + (10^9 − 1). The 10^9 − 1 allowance absorbs the sub-wei remainder carried from paid epochs, so eviction lands exactly eviction_threshold_epochs epochs after the first unpaid one. With the default of 30 epochs, an actor whose rent goes unpaid stays live, and is revived simply by funding its balance, for about 30 days. There is no separate grace or warning phase.
12.2 Catch-up
An actor withrent_debt > 0 that is still live pays its debt down through ordinary settlement (§12.1) as soon as its balance is funded and it next settles. Live catch-up carries no premium.
12.3 Eviction and restoration
- Eviction: an evictable actor’s storage and active timers are pruned. Code, address, balance and a commitment to the pruned storage (
pre_evict_storage_hash) are preserved, anddormant_since_epochrecords the eviction epoch. A dormant actor does not settle rent and does not execute. - Restoration: anyone may restore a dormant actor by supplying its complete storage, which must reproduce the recorded commitment, and paying
ceil(rent_debt × (10,000 + rent_catchup_bps) / (10,000 × 10^9))wei — the debt plus the catch-up premium (10% by default), rounded up once. The payment is burned. Restoration rewrites the storage, clearsdormant_since_epoch,pre_evict_storage_hashandrent_debt, and setslast_settled_epochto the current epoch.
RestoreActor snapshot wire bound includes serialization overhead: at most 8,388,608 + 8 × 10,000 + 4 bytes for the maximum actor storage (§12.4), two u32 lengths per entry and the u32 entry count. Its transaction admission limit adds the ordinary 1 MiB envelope allowance. RPC submit/estimate and mempool admission MUST admit this byte shape; gas/access limits and execution validation remain separate requirements. Ordinary transactions retain their 1 MiB limit.
12.4 Storage limits
Each non-reserved actor stores at most 8 MiB of key-value bytes (MAX_ACTOR_KV_BYTES = 8,388,608) and at most 10,000 live keys (MAX_ACTOR_KV_COUNT). The limits are protocol-wide; a write that would exceed either fails. There is no per-actor quota, reservation, or storage bond: rent (§12.1) bills the bytes an actor actually stores, so storage growth is paid for as it happens. A forked child (CIP-27) holds the parent’s copied bytes from birth and pays rent on them from its first rent epoch.
12.5 Parameters
All Tier-0 governance-tunable (CIP-12 §5.1). Storage: these are not independent keys — the deployedRentConfig struct (all four fields below) is stored as one JSON blob under the single SystemState key system:cip4:rent_config at Governance (0x0A ‖ keccak256("system:cip4:rent_config"), under actor 0x09), enacted atomically via UpdateRentConfig; a missing key yields RentConfig::defaults(). Field names below are the RentConfig field names.
12.6 CBY-denominated rent (Decision Register #4 — HOLD)
The architecture review proposed re-pegging rent to USD via a 7-day TWAP oracle. The analysis Decision Register #4 selected HOLD on CBY-denominated for v1 to avoid introducing a consensus-layer oracle dependency. Operational mitigation:- Monitoring cadence. The Cowboy Foundation publishes monthly the implied USD value of
rent_rate × 1 MiB × 365 days. Target band:[$1, $10] / MiB / yearat the prevailing CBY/USD spot. - Tier-0 adjustment trigger. If the implied USD rent drifts outside the target band for two consecutive monthly reviews, a Tier-0 governance proposal MUST be filed to adjust
rent_rate. - No oracle dependency in v1. A future CIP MAY introduce oracle-anchored rent; this CIP does not.
12.7 Relationship to other CIPs
- CIP-7 retention contracts: separate facility (off-chain blob storage with provider negotiation). State rent in §12 above applies to on-chain QMDB state only.
- CIP-9 / CIP-31 CBFS: separate facility (decentralized off-chain storage via Relay Nodes). CBFS storage fees and Relay economics live in CIP-9 §10.4 + CIP-31, not here.
- WP §17.5: operational summary plus the monitoring cadence above; this CIP §12 is the normative spec.
- WP §13 parameter block: the Tier-0 rent parameters above (the four-field
RentConfig) appear in WP §13 as a one-line reference to this section.
Appendix A/B — removed
The former Appendix A (StateValue variant sketch with obsolete embedded code/storage/mailbox Actor shapes) and Appendix B (a 0x00-based prefix table predating the normative layout) contradicted §4.2/§4.3, which are the sole normative tables; they are deleted rather than maintained in parallel.Appendix C: Proof response format
loc through digests to ops_root, then verify ops_root matches the state_root from the block header.