Skip to main content

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.
TL;DR: Cowboy combines a Python-based Actor VM (PVM), two-meter gas, native timers, verifiable off-chain compute (LLM/HTTP/MCP runners), and encrypted distributed storage (CBFS) into a cohesive protocol for agentic applications.

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)
Architecture:
The CIP-6 SDK (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
Flow:
Properties:
  • 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:
Independent Fee Markets:
  • Each resource has its own basefee
  • Basefees adjust independently (dual EIP-1559)
  • Prevents cross-subsidization
See: Fee Model

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 Overview

5. Off-Chain Compute (CIP-2)

Purpose: Verifiable execution of AI models, API calls, heavy computation Architecture:
Selection: A job’s runners are picked by a random draw (a VRF) from the active runners, weighted by stake and reputation. So no central scheduler decides who gets the work, and anyone can verify who was picked (CIP-2). Continuation flow:
Builders write an ordinary 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:
Key properties:
  • Client-side encryption — storage nodes never see plaintext
  • Reed-Solomon erasure coding — K data + M parity shards, recover from any K
  • 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.
See: CIP-4 State Storage · CIP-9 Runner Storage

Transaction Lifecycle

State Organization

State Root: Merkle tree root of entire state State Transition: σ' = 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:
  1. Validator: takes part in consensus, and proposes and validates blocks.
  2. Full node: stores the full state and serves queries.
  3. Light client: keeps only block headers and verifies proofs.
  4. Runner: does off-chain work, watching for events and submitting results. It isn’t part of consensus.

Storage Layer

Components:
  1. State Storage:
    • Merkleized key-value store
    • Key: account/actor address + storage key
    • Value: serialized data
    • Root hash in block header
  2. Block Storage:
    • Sequential blocks
    • Headers + transactions
    • Indexed by height and hash
  3. Transaction Log:
    • All transactions (historical)
    • Receipts with events
    • Queryable by hash, block, address
  4. 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)
Defenses:
  1. Consensus Security:
    • BFT tolerance (2/3+ honest required)
  2. VM Security:
    • Sandboxed execution (no I/O)
    • Resource limits (cycles, cells, memory)
    • Deterministic execution (no non-determinism)
  3. Gas Economics:
    • Two meters prevent abuse
    • Basefee burn (anti-spam)
    • Priority market (fair access)
  4. 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)

Further Reading