Cowboy: Design Decisions Overview

Note: This document explains the “why” behind Cowboy’s architecture. For complete technical specifications, see the Technical Whitepaper, the Storage Whitepaper, the Secrets Whitepaper, and the CBQS Whitepaper. This Markdown file is authoritative; the committed PDF is a point-in-time rendering of it.

​

Abstract

​

Introduction

​

The Problem: A Chasm Between Intelligence and Agency

​

The Solution: Cowboy

​

Key Innovations in Cowboy

• Deterministic Python Actors: A sandboxed Python VM with mailbox messaging, reentrancy (depth‑capped), and first-class support for the world’s most popular programming language.
• Native Timers & Scheduler: Protocol-native scheduling combines per-fire fee payment, a timer-lane EIP-1559 basefee, priority tips, and bounded per-actor fairness without requiring an external keeper network.
• Protocol-Mediated Off-Chain Compute: A Runner market for LLM inference, HTTP fetches, MCP tool calls, custom compute, and one-shot container jobs, with explicit trust profiles rather than one universal verification claim.
• A Sovereign Substrate of Near-Chain Services: CBFS, CBSS, and CBQS keep bulk and private payloads off replicated state while using scoped capabilities, registries, commitments, and settlement at the boundaries where they are required.
• Application and Commerce Rails: Session payments, routing, event subscriptions, container policy, and the Trading Post make software addressable, hireable, and payable through protocol-defined interfaces.
• Dual-Metered Gas: Independent pricing and EIP-1559-style fee markets for compute (Cycles) and data/storage (Cells) to ensure fair and predictable costs.

​

Two Ways to Build

​

Consensus Applications

​

Sovereign Applications

​

Why Python?

​

The Actor Model

​

Why Actors?

1. Natural Asynchrony: Actors communicate via asynchronous messages, matching the real-world behavior of autonomous systems that interact with external services, wait for responses, and operate on independent schedules.
2. Encapsulation: Each actor has actor-scoped state that can only be modified through its handlers. This isolates mutation between actors, but it is not a privacy claim: validators replicate and execute consensus state.
3. Composability: Complex systems emerge from simple actors sending messages to each other. This modularity makes it easier to reason about, test, and audit autonomous systems.
4. Autonomy: Actors can schedule their own execution via timers, enabling true autonomy without external keeper networks.

​

Single-Block Atomicity

​

Awaiting Off-Chain Work

from cowboy_sdk import actor, runner, capture, codec, runtime

@actor
class RunnerLLMActor:

    @runner.continuation
    async def ask_llm(self, payload):
        obj = codec.decode(payload) if payload else {}
        prompt = str(obj.get("prompt", ""))
        request_id = self.storage.get("request_count", 0)
        self.storage["request_count"] = request_id + 1
        self.storage[f"llm:{request_id}:status"] = "pending"

        ctx = capture()              # context that must cross the block boundary
        ctx.request_id = request_id

        result = await runner.llm(   # suspends; resumes in a later block
            prompt,
            system_prompt=SYSTEM_PROMPT,
            max_tokens=256,
        )

        request_id = ctx.request_id  # restored from captured context
        self.storage[f"llm:{request_id}:response"] = _extract_llm_response(result)
        self.storage[f"llm:{request_id}:status"] = "done"
        runtime.emit_event("llm.response", {"request_id": request_id})

• No hidden control flow. The await desugars to explicit message passing — a job message out, a result message back in, each its own on-chain transaction. Nothing is a closure held in memory; execution can be traced block by block.
• Explicit context capture. Only what is written to capture() (or storage) crosses the boundary. There is no accidental closure over stale local variables — what survives the gap is a deliberate, visible choice.
• Re-validation is the developer’s job. The continuation runs against current state. Code that acted on pre-await reads (a price, a balance) must re-read and re-check them — the model makes the staleness possible to see, and the pattern makes checking it natural.

​

Native Timers and Scheduling

​

Why Protocol-Level Timers?

1. Centralization Risk: Keepers are typically operated by a small number of entities, creating single points of failure.
2. Cost Inefficiency: Each keeper network requires separate infrastructure, payment mechanisms, and trust assumptions.
3. Coordination Overhead: Actors must integrate with external services, manage subscriptions, and handle keeper failures.
4. MEV (Maximal Extractable Value) Exposure: Keepers can observe scheduled transactions and potentially front-run them.

​

Scalable Design: Height-Indexed Storage

​

Economic Rationality: The Per-Fire Fee Payer Model

​

Fairness and Liveness

​

DoS Prevention Philosophy

• Per-Actor Timer Limits: Each actor is limited to a maximum of 1,024 active timers at any time.
• Non-Refundable Scheduling Cost: Every scheduled timer pays a flat 200-cycle cost, so failed or cancelled spam is not free.
• Same-Block Prohibition and Fanout Cap: A timer cannot fire in the block that creates it, and each transaction may enqueue at most 1,024 messages or timers.
• Governance-Activated Timer Basefee: The target EIP-1559 hybrid adjusts a timer-lane basefee with utilisation after Tier-3 activation.
• Per-Block Execution Budget: Each block reserves a dedicated portion of its compute budget for timer execution, ensuring timer storms cannot completely crowd out regular transactions.

​

Protocol-Mediated Off-Chain Compute

​

Job Lifecycle

1. Post: An actor submits a job with an escrowed max price, explicit resource bounds (tokens, wall time, memory), and a chosen trust profile.
2. Assign: The protocol samples Runners via stake-weighted VRF from the eligible set — staked, healthy, and whose advertised capabilities satisfy the job’s entitlements. The request is bound in the submission block, and every assignment draws from the threshold seed three absolute views later. This adds a minimum three-view dispatch delay, including for single-Runner jobs, and prevents request contents from being chosen after learning that request’s seed. It does not prevent paid multi-request sampling or proposer inclusion strategies. Quorum profiles require nine eligible Runners at launch and fail admission rather than silently weakening the threshold.
3. Commit / Reveal: Committee members commit to output hashes before revealing their outputs. This prevents a member from changing its reveal after observing another valid reveal; it does not prevent collusion or pre-commit sharing.
4. Challenge, where supported: For profiles with objective failure rules, a bonded challenge window can penalize proven violations. The none and economic_bond profiles do not provide per-result objective slashing.
5. Payout: 89% of the job payment goes to the runner(s), 10% is burned, and 1% funds the Treasury. Unused escrow returns to the actor.

​

Trust Profiles

​

Bring Your Own Compute

• No mandatory platform compute provider. Selection is protocol-mediated rather than hard-wired to one inference vendor. The selected Runner still receives the job inputs it is authorized to process unless a stronger isolation profile applies.
• Markets find the hardware. Idle GPUs, specialized accelerators, region-specific capacity, and consumer hardware all clear at their own prices through rate cards, instead of being flattened into one provider’s SKU list.
• Capability matching replaces gatekeeping. The entitlements system matches jobs to runners on declared facts — supported models, TEE hardware, geographic region, network egress — so specialization is expressed in the protocol, not negotiated in a sales channel.
• Run your own supply. An application with strict requirements can run its own Runners. Its compute joins the same market, serves its jobs, and remains subject to the same authorization and settlement rules. This is the marketplace used at N=1, not a separate deployment mode.

​

Bring Your Own Models

• Monetize without publishing. A model owner can serve a proprietary model from its own Runners, publish a rate card, and earn per-inference revenue without distributing the weights. The chain records selection, commitments, evidence, and settlement according to the chosen trust profile; it does not inspect or prove the model artifact itself.
• Private weights as private data. Weights can live in a private CBFS volume, with the decryption key released through CBSS only to an authorized Runner for a dispatched job. That authorized Runner is able to process the plaintext. Excluding its host operator requires an additional isolation mechanism such as an accepted TEE profile; CBFS plus CBSS alone does not make that claim.
• Why this matters: open-weight models commoditize; frontier and fine-tuned models are where economic value concentrates. A platform that can only serve public models cedes that entire economy to centralized APIs. Cowboy’s design lets model owners participate in a permissionless market while keeping the asset that makes them valuable.

​

The Sovereign Substrate

Consensus records the resource lifecycle, authority, commitments, and settlement each near-chain capability requires. Relays, proxies, and brokers carry storage objects, release shares, and queue records outside consensus; Runners are the adjacent compute plane.

​

CBFS: Storage

1. Separate state from storage. State is consensus-critical key/value data billed per cell and subject to rent. Storage is bulk data — agent memory, embeddings, artifacts, web assets — referenced on-chain only by compact manifest-root commitments. Ethereum fuses these; the fusion is why “put it on-chain” is a joke and “put it on S3” is a surrender.
2. Off-chain data plane. Reads and writes are client-to-relay RPCs authenticated by capability tokens; the chain is touched only at lifecycle boundaries (create, anchor, bill, repair, evict). An agent reading its memory thousands of times a day pays for storage, not for consensus.
3. Private by default, public by choice. Private volumes are encrypted client-side: relays store and serve ciphertext, and the protocol never asks storage operators to be trusted with private content — so the storage network can be permissionless without being a privacy hazard. Public volumes are deliberately plaintext and world-readable without a CapToken — that is what lets the gateway serve web assets and public datasets straight from relays. A volume’s visibility is chosen at creation and immutable thereafter.
4. Capability tokens over transactions. Scoped, signed CapTokens (volume, path prefix, mode, quota, expiry) grant access — chain-issued for runner mounts at job dispatch, client-signed via a delegation keypair for owner access. Cold wallet authority and hot data-path authority are deliberately separated.
5. Auditable durability. Reed-Solomon shards across independent relays and on-chain Proof-of-Retrievability challenges produce evidence about storage service. Failed proofs trigger protocol-defined penalties and slashing.

​

CBSS: Secrets

1. Conditional plaintext release is the missing primitive. Chains make everything public; private rollups make everything available to whoever decrypts the rollup; off-chain vaults release plaintext against a bearer token with no link to on-chain reality. Agents need a third thing: release this secret only to whoever the chain says is doing this job — so Cowboy built it as infrastructure.
2. Thresholds, not hardware. Decryption requires t-of-n proxy cooperation; the trust root is threshold non-collusion plus the protocol’s registration, audit, and accountability records. TEEs are an additional execution profile, not the foundation of secret release.
3. Chain-derived authorization. Proxies validate each release request against current chain state: the actor’s manifest declares the secret, the job is real, the requesting runner is the one dispatched. Authorization is computed from the authority record, not from possession of a credential.
4. Actors hold references and policy, not plaintext. An actor can operate authenticated integrations while its public code and state contain a secret reference and release policy rather than the credential. An authorized Runner crosses into the plaintext boundary when it combines the release shares; applications that need stronger host isolation must request it separately.

​

CBQS: Coordination

1. Mailboxes are not a message bus. Actor mailboxes carry public, consensus-relevant state transitions at consensus speed and gas cost. Multi-agent applications also need high-frequency, durable transport between runner-hosted workloads — a coordinator fronting a chat surface, workers fanning out tasks. Before CBQS, every serious multi-agent build re-implemented persistence, retry, fan-out, cursors, and crash recovery on its own. Repeated reinvention of the same infrastructure is a signal the platform is missing a primitive.
2. Chain lifecycle, broker records. A stream is created, owned, and billed through chain state, while its configuration is broker state; message flow is broker RPC rather than a chain write per record. The broker is authoritative for accepted records, leases, cursors, and consumer progress. Provider assignment is immutable: replacing a broker is a migration to a new stream across which the application carries its own durable copy, not a re-homing of the existing one.
3. Opaque payloads, explicit metadata. The broker stores bytes it cannot interpret and never receives a key, but CBQS does not itself encrypt: confidentiality is exactly as strong as the application’s own key management. Stream records, connection metadata, and traffic patterns remain visible at their respective layers. Self-hosting can reduce exposure to a third-party broker; it does not erase metadata already committed elsewhere.

​

Why the Iceberg Shape

• Scoped authority — each subsystem says exactly which lifecycle, policy, commitment, and settlement facts belong in consensus and which operational facts remain authoritative at a provider.
• Configured privacy — private CBFS volumes protect content from their storage providers, and a CBQS payload is opaque to the broker only to the extent the application encrypted it first; public volumes and operational metadata are deliberately outside that claim; authorized Runners can see the plaintext they process.
• Provider choice with explicit procedures — Runner, Relay, proxy, and broker supply are open to protocol-registered providers; each subsystem defines the evidence and state transfer required to replace a provider.
• Economic accountability — rate cards, escrow, receipts, commitments, challenges, and rent connect off-chain work to on-chain payment without pretending every result is reproduced by validators.

​

Sovereignty as an Exit Property

1. Export: Can the owner retrieve the complete data and metadata needed to continue elsewhere?
2. Replace: Can authority move to another provider without the incumbent’s cooperation?
3. Recover: What survives if the provider disappears, corrupts state, or refuses service?
4. Revoke: How quickly do old capabilities, replicas, and release rights become unusable?
5. Verify: Which provider claims can the owner or protocol independently check?

​

Dual-Metered Gas

• Cycles measure compute: Python operations and host calls (e.g., send, set‑timer, blob‑commit) each have a fixed cost. Cycles resemble Erlang reductions: a budget of discrete steps that bounds how long a handler runs.
• Cells measure bytes: calldata, return data, blobs, and storage all consume cells.

​

Why Separate Meters?

1. Fair Pricing: A transaction that processes large amounts of data but does little computation pays for data, not computation. Conversely, a compute-intensive transaction pays for cycles, not data.
2. Predictable Costs: Developers can reason about costs independently: “This operation will cost X cycles and Y cells” rather than trying to understand how a single gas scalar maps to both dimensions.
3. Better Resource Management: The protocol can adjust pricing for compute and storage independently based on network conditions. If storage is scarce but compute is abundant, cell basefees rise while cycle basefees fall.
4. Independent Basefees: Each meter has its own EIP-1559-style basefee update and burn rule.

​

Consensus Philosophy

​

Why Simplex?

1. Compact consensus core: Simplex uses same-view notarize, application-certify, finalize, and nullify phases. This keeps the consensus logic that must be implemented and audited small.
2. VRF-based leader election: A leader is elected for each absolute consensus view. The same validator can lead consecutive views, so election does not remove single-proposer discretion or public-mempool MEV.
3. Fast-finality target: Cowboy targets roughly two seconds across proposal, notarization, application certification, and finalization phases within the proposal’s view. This is a target to validate under realistic geographic latency, not a substitute for measured network evidence.

​

MEV Resistance Through Design

• VRF-Based Transaction Ordering: Candidate batches are finalized before their ordering seed is revealed, then ordered deterministically within each lane. This reduces discretionary placement inside the committed batch; it adds pipeline latency and does not prevent pre-commitment censorship, paid multi-transaction sampling, or private order flow.
• Dedicated Lanes: Block space is partitioned into reserved lanes for system operations, timers, and runner results. This isolates congestion between lanes; it does not prevent an attacker from competing with a victim inside the same lane.
• Public Mempool: Cowboy does not require an encrypted mempool. That choice accepts single-block inclusion, private-order-flow, and JIT MEV risks and should be revisited against observed workloads rather than justified by fast finality alone.

​

Economic Model

​

Fee Burns

​

Validator Rewards

• Block Inflation: Validators receive rewards from a declining gross-inflation schedule on a fixed genesis supply of 1,000,000,000 CBY: 8%/6% in the bootstrap years, 4%/3% on the glidepath, and a 2% floor at steady state. Gross inflation is offset by protocol burns, so net inflation depends on network usage.
• Tips: Proposers receive transaction tips.
• Conservative Slashing: Most specified offenses cause temporary jailing; stake is destroyed only for faults assigned a slashing penalty.

​

Runner Marketplace

• Runners set their own rates via on-chain rate cards
• Jobs are matched to runners based on price, capabilities, and entitlements
• Economic bonds and reputation affect eligibility and consequences for delivery failures and defined faults; they do not prove result correctness
• Each job settlement pays 89% to runners, burns 10%, and sends 1% to the Treasury. These are protocol-configured settlement destinations, not a claim about token value.

​

State Rent

​

USD-Denominated Billing

​

Application and Commerce Rails

​

Entitlements: Least-Privilege by Default

• Actors declare requirements: What permissions they need (HTTP domains, TEE access, storage quotas)
• Runners advertise capabilities: What they can provide (supported models, geographic regions, TEE hardware)
• Scheduler enforces matching: Jobs only run on runners where requires ⊆ provides
• Syscalls are gated: Operations fail if the actor lacks the corresponding entitlement

​

Why Cowboy Chooses a Purpose-Built Layer 1

• Consensus-native scheduling. Validators execute due timers and system work as part of the state transition, with dedicated budgets that do not depend on a separate sequencer policy.
• One authority and settlement domain. Actors, Runner assignments, near-chain resource lifecycles, fees, and governance share one chain-defined state machine instead of crossing a rollup-to-L1 boundary.
• Independent economics and upgrades. Cowboy can tune block cadence, lanes, fee markets, validator incentives, and execution semantics without inheriting a rollup framework’s upgrade or proving constraints.
• No proving requirement for launch. A validity rollup would require a proof system for the PVM and Cowboy’s enshrined services; an optimistic rollup would require a complete fault-proof and data-availability design. Those are viable architectures, but they are different projects with different security assumptions.

• Independent security budget: Cowboy must bootstrap and retain sufficient distributed stake rather than inherit Ethereum settlement security.
• Bridge and liquidity risk: Assets are not natively composable with Ethereum, and third-party bridges introduce additional trust and failure modes.
• Operational burden: The network owns consensus clients, validator operations, upgrades, incident response, and long-range recovery.

​

Ethereum Interoperability

​

Intent-Based Settlement

• Sealed-bid solver auctions: Solver competition can run as a sealed auction using CBSS time-lock encryption — bids are encrypted to a future block height and revealed permissionlessly after it passes. This eliminates last-look and bid-sniping, a fairness property open solver markets do not provide.
• Pluggable corridor backends: Cross-chain legs go through a uniform settlement interface with governance-selected backends per corridor — the native bridge, ERC-7683/Open Intents adapters for EVM corridors, or NEAR Intents for BTC and non-EVM reach. No standard is treated as a liquidity source: external liquidity always comes from solvers fronting capital over a rail they trust, and the settlement core depends on none of them.

​

Security Philosophy

• Constrained Application Code: Python syntax can improve review accessibility, while the custom PVM, deterministic standard library, deploy gate, and syscall boundary remain consensus-critical attack surfaces requiring independent audits and differential testing.
• Explicit Semantics: The message-passing model makes execution flow explicit and traceable.
• Economic Accountability: Staking, jailing, slashing, and fees attach defined consequences to delivery failures and provable protocol faults; they do not establish result correctness or prevent collusion.
• Least Privilege: The Entitlements system enforces least-privilege access by default.
• Curious-Provider Threat Model: Provider data paths assume a relay, proxy, broker, or Runner host may inspect what it holds. Private CBFS volumes, encrypted CBQS streams, and threshold release reduce specific exposures, but they do not create one universal confidentiality guarantee: public volumes and operational metadata are visible, and an authorized Runner can see the plaintext it processes unless a stronger isolation profile applies.

​

Prior Art and Differentiation

• Actor-oriented chains: TON models accounts as actors that process messages and emit outbound messages; the Internet Computer provides canister timers and asynchronous inter-canister execution. Cowboy differs in its Python PVM, dedicated timer lane, and protocol-mediated Runner and near-chain service boundaries.
• Object and ownership models: Sui makes object identity and ownership first-class and uses those facts for execution and agreement. Cowboy instead centers durable actor identity and capability-scoped service relationships.
• Off-chain computation and automation: Chainlink Functions, Automation, and decentralized oracle networks demonstrate external computation and scheduled triggering. Cowboy enshrines job assignment, settlement, and multiple trust profiles in its own state machine.
• Storage markets: Filecoin’s Proof-of-Replication and Proof-of-Spacetime are foundational prior art for economically accountable storage. CBFS uses a different relay, erasure-coding, capability, and manifest model with accountable Proof-of-Retrievability challenges and slashing.
• MEV research: Flashbots and Ethereum’s proposer-builder separation work show that fast finality and leader election do not resolve block-construction incentives. Cowboy’s VRF ordering is one bounded mitigation, not a complete MEV design.
• State lifecycle: Ethereum’s statelessness and state-expiry research frames the same resurrection and historical-data availability problems Cowboy must solve for evicted actors.

​

Applications

• Consensus applications — trading agents, DeFi automation, oracle committees, and on-chain games — center deterministic actors, native timers, and protocol-mediated Runner calls, with consequential decisions committed in consensus.
• Sovereign applications — durable workspaces, personal AI, multi-agent businesses, and private-model services — are chain-anchored and Runner-centric: identity and authority live in actors, executable logic uses Runner jobs or persistent workloads, and data, credentials, and coordination use the sovereign substrate.