Skip to main content
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/Read binary, 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:
  1. Ledger: Append-only block segment files;
  2. QMDB (canonical state): Three flat KV databases (state_db, tx_index, tx_receipts) with Blake3 Merkle commitments;
  3. 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):
    1. 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.
    2. 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.
    3. The node rejects the block if its computed roots differ from the header roots.
    4. The node caches the write batch and applies it atomically to QMDB on finalization.
    5. The node derives auxiliary indexes from the ledger and QMDB. This work can run asynchronously.
  • Read Path (how they cooperate during queries):
    • For a transaction hash, the node queries tx_index for its location, reads the raw transaction from the ledger, and reads its receipt from tx_receipts.
    • For an address and slot, the node reads state_db directly and can return a QMDB Merkle proof.
    • For an event topic, the node queries auxiliary indexes for candidates and verifies them against receipts.
  • Consistency invariants:
    1. state_db.root_at(N) == Ledger.block[N].state_root;
    2. tx_root computed via BMT over block transactions matches header;
    3. receipt_root computed via BMT over block receipts matches header;
    4. 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):
Cowboy addresses are 20 bytes (Ethereum-style). Hash-keyed prefixes place a 32-byte keccak in the first 32 bytes of the address+slot region; the total key is always 86 bytes.

4.2 State prefixes

Normative: the table below is the StatePrefix allocation. The storage layout uses 0x01–0x22 and 0x24–0x26 (37 distinct prefixes); there is no 0x00, and 0x23 remains unallocated. The earlier CIP-27 draft’s CodeMeta = 0x1E assignment is superseded: 0x1E belongs to TimerIndexPage. 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, and TimerIndexPage(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 = 0x25 uses the exact 86-byte key 0x25 ‖ address[20] ‖ 0x00[65]. The value reuses StateValue::SystemBytes, wire tag 0x0A, with a one-byte payload 0x01; its complete commonware-codec bytes are 0A 01 01 (tag, canonical unsigned-varint vector length 1, payload). Test vector: encoding StateValue::SystemBytes([0x01]) yields exactly [0x0a, 0x01, 0x01], and decoding those bytes yields the same value. This uses commonware Vec<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 single VecDeque<Message> blob. Overflow spills to the dead-letter ring (0x1C / 0x1D).
  • All values, including transactions, use the commonware Write/Read binary codec.
  • Decode bounds enforced: DeferredTxList max 16,384 entries; ActorEventList max 1,000 entries.

5. QMDB state commitments

5.1 State root

QMDB computes a Merkle root over all key-value pairs in state_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) over keccak256 hashes of all transactions in the block:

5.3 Receipt root

The node computes the BMT over each receipt’s commonware-codec encoding (Encode):
Empty receipts hash to 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 proof
  • GET /proof/actor/{address} — actor metadata proof
  • GET /proof/storage/{address}/{key} — actor storage slot proof
  • GET /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)
Independent Verifier: The 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

  1. Fetch block: Read block header and body from Ledger.
  2. Pre-check: Validate signatures, nonces, gas limits.
  3. Speculative execution: Execute all transactions in batch mode:
    • The node calls begin_batch(), executes the transactions and calls commit_batch().
    • Produces state_pending, tx_index_pending, tx_receipts_pending write sets
    • Processes timers, deferred TXs (with per-actor limits and expiration)
  4. Compute roots: Calculate state_root, tx_root, receipt_root from the write set.
  5. Root verification: Roots must match block header; reject if mismatch.
  6. Cache: Store write batch for later finalization.
  7. On finalization: Apply cached batch to QMDB databases.

6.2 Atomic commit

The node commits the QMDB databases sequentially, starting with state_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/StateValue interface;
  • 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_db as ActorEventList)

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 from H.
  • 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_db as authoritative state;
  • Proof integrity: Merkle proofs verified against state_root in 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/multi batches 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 = 8
  • MAX_DEFERRED_TX_LIST_SIZE = 16,384
  • MAX_ACTOR_EVENTS = 1,000
  • MAX_TIMERS_PER_ACTOR = 1,024
  • MAX_PENDING_DEFERRED_PER_ACTOR = 64
  • DEFERRED_TX_MAX_AGE_BLOCKS = 1,000
  • SNAPSHOT_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 below RESERVED_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:
where:
  • 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 default rent_rate_atto = 2_739_726_027_397 atto/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_debt lives on the Actor record (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 are rent_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> and pre_evict_storage_hash: Option<[32]u8>; it carries no quota or bond field.
Settlement. Settlement runs before every handler the actor executes and in the bounded per-block rent sweep. It computes 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:
  1. adds the elapsed rent to the debt: owed = rent_debt + rent_per_rent_epoch × epochs_due (atto, u128);
  2. pays whole wei from the actor’s balance: paid_wei = min(balance_wei, floor(owed / 10^9)), debits exactly paid_wei, and sets rent_debt = owed − paid_wei × 10^9. The sub-wei remainder carries in rent_debt, and nothing else is subtracted;
  3. sets last_settled_epoch = current_epoch.
Paid rent is burned. No penalty accrues on unpaid rent; the catch-up premium applies only at restoration (§12.3). Eviction threshold. An actor becomes evictable at settlement when its unpaid debt is at least one wei and exceeds 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 with rent_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, and dormant_since_epoch records 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, clears dormant_since_epoch, pre_evict_storage_hash and rent_debt, and sets last_settled_epoch to the current epoch.
The 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 deployed RentConfig 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 / year at 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.
Re-evaluation triggers for re-pegging: (a) availability of a battle-tested CBY/USD oracle module (precondition for any USD-pegged consensus parameter), or (b) sustained USD-rent drift outside the band beyond what Tier-0 cadence can manage.

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

Verification: reconstruct the Merkle path from loc through digests to ops_root, then verify ops_root matches the state_root from the block header.