Source Layout

Introduction

This page is for contributors working in the full Cowboy source workspace. App developers following the Quickstart do not need these directories; they only need the cowboy CLI installed and a normal project directory. The full workspace contains the core blockchain, Python VM, off-chain runner network, distributed storage, and developer tooling. Depending on how you obtained the source, these components may be checked out as sibling repositories rather than as directories inside this documentation repo.

Top-Level Structure

cowboy/
├── node/                 # L1 blockchain (Rust, 18+ crates)
├── pvm/                  # Python VM (Rust, based on RustPython)
├── runner/               # Off-chain compute network (Rust)
├── cbfs/                 # Distributed encrypted storage (Rust)
├── explorer/             # Block explorer frontend (HTML/JS)
├── lasso/                # Interactive terminal console (Node.js/Ink)
└── cowboy/               # Protocol documentation and examples

Core Components

node — L1 Blockchain

Path: node/ A Rust workspace containing ~18 crates that make up the validator, CLI, indexer, and chain logic.

Consensus & Execution
CLI & Client
Indexing & Inspection
Protocol Features

validator/ — Simplex BFT consensus node (~1s block time, ~2s finality)
chain/ — Block production, execution engine, RPC API
execution/ — Transaction execution pipeline
storage/ — Account, actor, and receipt persistence (QMDB-backed)

cli/ — The cowboy command-line binary
cowboy/ — CLI helper libraries
client/ — Rust SDK for embedding a Cowboy client
wallet/ — secp256k1 keypair management

indexer/ — Stateless activity indexer daemon
inspector/ — Chain state inspection tool
rpc/ — JSON-RPC server

token/ — CIP-20 fungible token registry
ras/ — Role-based access system
proof-verifier/ — Merkle proof verification
types/ — Shared transaction and block types

pvm — Python Virtual Machine

Path: pvm/ A deterministic Python 3 interpreter in Rust (forked from RustPython), with blockchain-specific extensions. Key features:

Checkpoint/resume — Serialize and restore full program state mid-execution
Fuel metering — Deterministic cycle-level execution limits
Rust ↔ Python interop — Bidirectional function calls via pvm_host
Soft float — Software floating-point for bit-identical results across hardware

Notable subdirectories:

pvm/src/ — The Rust interpreter core
pvm/Lib/ — Python standard library (curated, deterministic subset)
pvm/Lib/cowboy_sdk/ — The Cowboy Python SDK (CIP-6): @actor, runner.continuation, CowboyModel, capture, codec, etc.

runner — Off-Chain Compute

Path: runner/ Decentralized network for verifiable off-chain computation (CIP-2). Runners execute jobs that actors request and submit signed results back on-chain. Executor types: LLM (OpenAI/Anthropic), HTTP, MCP (Model Context Protocol). Verification models: N-of-M consensus, TEE attestation, ZK proofs (v2).

cbfs — Distributed Storage

Path: cbfs/ Encrypted distributed filesystem with Reed-Solomon erasure coding, AES-256-GCM client-side encryption, QUIC transport, and a FUSE mount binary. Key crates:

Crate	Purpose
`cbfs-types`	Shared types: VolumeId, ShardId, NodeId
`cbfs-crypto`	AES-256-GCM, BLAKE3, DEK wrapping
`cbfs-erasure`	Reed-Solomon (K data + M parity, SIMD)
`cbfs-manifest`	Client-side volume index with Merkle integrity
`cbfs-auth`	Delegated identity, token minting, cache helpers
`cbfs-store`	Sled-backed blob storage for storage nodes
`cbfs-transport`	QUIC client/server with bincode RPC
`cbfs-sdk`	High-level Volume API: `put`, `get`, `commit`
`cbfs-node`	Storage node daemon
`cbfs-fuse`	FUSE filesystem binary

actors — Example Python Actors

Path: actors/ Reference actors you can deploy out of the box.

actors/hello/main.py — Minimal counter actor
actors/feed-subscriber/main.py — Subscribe to Watchtower (CIP-7) streams

Additional worked examples live under examples/ in the docs/source workspace:

examples/core/05-tokens-and-balances/ — CIP-20 token workflows
examples/gallery/advanced-messaging-ring/ — Multi-actor ring topology demo
examples/core/08-minimal-runner-continuation/ — Runner continuation pattern
examples/core/07-timers-and-automation/ — Timer scheduling pattern

lasso — Interactive Console

Path: lasso/ React/Ink-based terminal UI that wraps the cowboy CLI with session persistence, command history, and a live status bar. Useful for interactive debugging.

explorer — Block Explorer

Path: explorer/ Static HTML/JS + TailwindCSS block explorer — dashboard, blocks, transactions, actors, runner status. Serve with any static HTTP server.

docker — Local Dev Environment

Path: docker/ Docker Compose stacks for running a local validator + runner network in a contributor/source checkout. The public Quickstart uses the hosted devnet and does not require Docker.

aws-infrastructure — Production Deployment

Path: aws-infrastructure/ Terraform modules for AWS: VPC, EC2 validators/runners (ASG with spot), S3 artifacts, IAM, GitHub Actions CI/CD.

Finding Your Way Around

The Python VM interpreter

Path: pvm/src/The Rust-based Python bytecode interpreter with fuel metering.

The Cowboy Python SDK (CIP-6)

Path: pvm/Lib/cowboy_sdk/The @actor decorator, continuation FSM compiler, storage/runtime APIs, and CBOR codec.

Gas metering logic

Path: node/execution/ and pvm/src/ (fuel hooks)Cycles metering in the VM; Cells metering at I/O boundaries.

Off-chain runner

Path: runner/src/ and runner/crates/Executors for LLM, HTTP, MCP. See runner/README.md for the on-chain system actor addresses.

CBFS filesystem

Path: cbfs/fuse/, cbfs/store/, cbfs/sdk/FUSE mount binary, node daemon, and volume SDK.

The CLI binary

Path: node/cli/Built as cargo build --release --bin cowboy from the node/ workspace.

Example actors

Paths: actors/ and examples/Ready-to-deploy reference actors and worked end-to-end demos.

Protocol specs (CIPs)

Path: cowboy/docs/cips/Formal CIP (Cowboy Improvement Proposal) documents.

Contributing Areas

Core Protocol

Language: RustAreas: consensus, execution, storage, networkingPaths: node/, pvm/

Off-Chain Runner

Language: RustAreas: executors (LLM/HTTP/MCP), verification, registryPath: runner/

CBFS Storage

Language: RustAreas: erasure coding, auth, FUSE, transportPath: cbfs/

Python SDK

Language: PythonAreas: @actor decorator, continuation FSM, codecPath: pvm/Lib/cowboy_sdk/

Tooling

Language: MixedAreas: CLI, Lasso console, explorer UIPaths: node/cli/, lasso/, explorer/

Documentation

Language: Markdown (MDX)Areas: guides, architecture, CIPsPath: cowboy/docs/

Start Here

Build

How Cowboy Works

Reference

Introduction

Top-Level Structure

Core Components

node — L1 Blockchain

pvm — Python Virtual Machine

runner — Off-Chain Compute

cbfs — Distributed Storage

actors — Example Python Actors

lasso — Interactive Console

explorer — Block Explorer

docker — Local Dev Environment

aws-infrastructure — Production Deployment

Finding Your Way Around

Contributing Areas

Core Protocol

Off-Chain Runner

CBFS Storage

Python SDK

Tooling

Documentation

​Introduction

​Top-Level Structure

​Core Components

​node — L1 Blockchain

​pvm — Python Virtual Machine

​runner — Off-Chain Compute

​cbfs — Distributed Storage

​actors — Example Python Actors

​lasso — Interactive Console

​explorer — Block Explorer

​docker — Local Dev Environment

​aws-infrastructure — Production Deployment

​Finding Your Way Around

​Contributing Areas

Core Protocol

Off-Chain Runner

CBFS Storage

Python SDK

Tooling

Documentation

Introduction

Top-Level Structure

Core Components

node — L1 Blockchain

pvm — Python Virtual Machine

runner — Off-Chain Compute

cbfs — Distributed Storage

actors — Example Python Actors

lasso — Interactive Console

explorer — Block Explorer

docker — Local Dev Environment

aws-infrastructure — Production Deployment

Finding Your Way Around

Contributing Areas