Skip to main content

​
Introduction

The Cowboy project is organized as a monorepo containing the core blockchain, Python VM, off-chain runner network, distributed storage, and developer tooling. This guide helps you navigate the codebase.

​
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 (this site)

​
Core Components

​
node — L1 Blockchain

Path: node/ A Rust workspace containing ~18 crates that make up the validator, CLI, indexer, and chain logic.
  • 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)

​
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:
CratePurpose
cbfs-typesShared types: VolumeId, ShardId, NodeId
cbfs-cryptoAES-256-GCM, BLAKE3, DEK wrapping
cbfs-erasureReed-Solomon (K data + M parity, SIMD)
cbfs-manifestClient-side volume index with Merkle integrity
cbfs-authDelegated identity, token minting, cache helpers
cbfs-storeSled-backed blob storage for storage nodes
cbfs-transportQUIC client/server with bincode RPC
cbfs-sdkHigh-level Volume API: put, get, commit
cbfs-nodeStorage node daemon
cbfs-fuseFUSE 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 node/examples/:
  • node/examples/llm_chat/ — End-to-end LLM chat actor using cowboy_sdk
  • node/examples/ring-demo/ — Multi-actor ring topology demo
  • node/examples/token/ — CIP-20 token example
  • node/examples/multi_call/, restart_test/, proof/, …

​
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. See Quickstart.

​
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

Path: pvm/src/The Rust-based Python bytecode interpreter with fuel metering.
Path: pvm/Lib/cowboy_sdk/The @actor decorator, continuation FSM compiler, storage/runtime APIs, and CBOR codec.
Path: node/execution/ and pvm/src/ (fuel hooks)Cycles metering in the VM; Cells metering at I/O boundaries.
Path: runner/src/ and runner/crates/Executors for LLM, HTTP, MCP. See runner/README.md for the on-chain system actor addresses.
Path: cbfs/fuse/, cbfs/store/, cbfs/sdk/FUSE mount binary, node daemon, and volume SDK.
Path: node/cli/Built as cargo build --release --bin cowboy from the node/ workspace.
Paths: actors/ and node/examples/Ready-to-deploy reference actors and worked end-to-end demos.
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/