Introduction
Cowboy runs on its own blockchain, designed from the ground up for autonomous agents and verifiable off-chain computation. This document provides a high-level overview of the system architecture.System Architecture

Core Components
1. Actor VM (Python Runtime)
Purpose: Execute actor (smart contract) code deterministically Key Features:- Python bytecode interpreter (no JIT)
- Deterministic execution (no system calls, software FPU)
- Two-meter gas (Cycles for compute, Cells for data)
- Sandboxed environment (no I/O, no network)
cowboy_sdk) sits on top of pvm_host, providing an Actor base class, CBOR auto-serialization, and a continuation FSM for async runner calls.
See: Actor VM Overview · SDK Overview
2. Consensus Layer (Simplex BFT)
Purpose: Achieve agreement on block ordering and finality Key Features:- Byzantine Fault Tolerant (BFT)
- Deterministic finality (no reorgs)
- Leader-based block proposal
- Quorum certificates (QC) for votes
- Safety: No forks (deterministic finality)
- Liveness: Progress guaranteed with 2/3+ honest validators
3. Two-Meter Gas System
Purpose: Fair resource pricing for compute and data Architecture:- Each resource has its own basefee
- Basefees adjust independently (dual EIP-1559)
- Prevents cross-subsidization
4. Timer Scheduler (CIP-5)
Purpose: Native timer scheduling with bounded FIFO execution. Timers run at the end of each block, after transactions, oldest due first, within a fixed per-block budget. A timer whose actor can’t pay is removed instead of run (CIP-5). See: Scheduler Overview5. Off-Chain Compute (CIP-2)
Purpose: Verifiable execution of AI models, API calls, heavy computation Architecture:async def handler with await runner.llm(...) or await runner.http(...). The CLI compiler generates its continuation and resume entrypoints. The code before the await submits the job; the code after it runs later when the result arrives.
See: Off-Chain Compute
6. Encrypted Distributed Storage (CBFS)
Purpose: Store data too large for on-chain persistence — models, datasets, media, logs — with end-to-end encryption and redundancy. For private volumes, this encryption boundary includes the CBSS committee: a threshold of t out of n members can release committee-wrapped keys by design. Harness boxes that hold grantee keys are also inside the trust boundary. Architecture:- Client-side encryption — storage nodes never see plaintext
- Reed-Solomon erasure coding —
Kdata +Mparity shards, recover from anyK - Delegated auth — owner signs short-lived capability tokens; no chain write on every data-plane call
- Self-healing — background repair detects dead nodes and re-shards
- FUSE mount — volumes appear as normal filesystems to actors and runners
The Actor VM still forbids ordinary file I/O during deterministic execution. CBFS access is mediated by protocol/runtime APIs and delegated capability tokens; runner-side jobs may use mounted volumes, while actor state remains the consensus key-value store.
Transaction Lifecycle
State Organization
σ' = STF(σ, B) where B is block
Network Layer
Nodes share transactions, blocks and votes over a peer-to-peer gossip network. What a node does depends on its type:- Validator: takes part in consensus, and proposes and validates blocks.
- Full node: stores the full state and serves queries.
- Light client: keeps only block headers and verifies proofs.
- Runner: does off-chain work, watching for events and submitting results. It isn’t part of consensus.
Storage Layer
Components:-
State Storage:
- Merkleized key-value store
- Key: account/actor address + storage key
- Value: serialized data
- Root hash in block header
-
Block Storage:
- Sequential blocks
- Headers + transactions
- Indexed by height and hash
-
Transaction Log:
- All transactions (historical)
- Receipts with events
- Queryable by hash, block, address
-
Archive Node (optional):
- Full historical state
- Every block’s complete state
- For queries like “balance at block X”
Security Model
Threat Model:- Byzantine validators (up to 1/3)
- Malicious actors (smart contracts)
- DoS attacks (computational, storage)
- Network attacks (eclipse, Sybil)
-
Consensus Security:
- BFT tolerance (2/3+ honest required)
-
VM Security:
- Sandboxed execution (no I/O)
- Resource limits (cycles, cells, memory)
- Deterministic execution (no non-determinism)
-
Gas Economics:
- Two meters prevent abuse
- Basefee burn (anti-spam)
- Priority market (fair access)
-
Off-Chain Security:
- VRF-based selection (no coordinator)
- Configurable verification requirements (per CIP-2)
- Economic incentives (per application design)
Next Steps
Actor VM Deep Dive
How the PVM achieves deterministic Python execution
Fee Model
Two-meter gas and EIP-1559 basefees
Scheduler
Native timer system (CIP-5)
Off-Chain Compute
Verifiable runner network (CIP-2)
State Storage
QMDB state store + Merkle proofs (CIP-4)
SDK Overview
The
cowboy_sdk Python library (CIP-6)