Repository Layout

Introduction

The Cowboy project is organized as a monorepo containing the core protocol implementation, SDK, documentation, and tooling. This guide helps you navigate the codebase.

Repository: github.com/cowboyinc/cowboy

Repository Structure

cowboy/
|-- crates/                                  # Rust implementation
|   \-- cowboy-core/
|       |-- src/
|       |   |-- actor_simulator.rs
|       |   |-- consensus.rs
|       |   |-- metering.rs
|       |   |-- lib.rs
|       |   |-- simulator.rs
|       |   |-- state.rs
|       |   |-- types.rs
|       |   |-- runtime/                     # Actor VM runtime
|       |   |-- runner/                      # Off-chain runner
|       |   \-- bin/                         # Executables
|       \-- Cargo.toml
|
|-- sdk/                                     # Language SDKs
|   \-- python/
|       |-- cowboy_sdk.egg-info/
|       |-- cowboy_sdk/
|       |-- examples/
|       |-- tests/
|       |-- README.md
|       |-- README_SDK.md
|       |-- SETUP.md
|       |-- pyproject.toml
|       |-- pytest.ini
|       |-- requirements.txt
|       \-- test_manual.py
|
|-- docs/                                    # Documentation
|   |-- architecture/
|   |-- assets/
|   |-- cips/
|   |-- contributing/
|   |-- developers/
|   |-- economics/
|   |-- getting-started/
|   |-- governance/
|   |-- images/
|   |-- introduction/
|   |-- overview/
|   |-- references/
|   |-- security/
|   |-- style/
|   |-- versioning/
|   |-- testing/
|   |-- LICENSE
|   |-- README.md
|   |-- docs.json            # Mintlify config
|   |-- docs.backup.json
|   |-- favicon.svg
|   |-- index.mdx
|   \-- quickstart.mdx
|
|-- dashboard/                               # Explorer UI
|   \-- index.html
|
|-- Cargo.toml                               # Rust workspace
|-- package.json                             # Node.js config
|-- package-lock.json
|-- README.md                                # Project overview
|-- README_TESTING.md
|-- cursor-extensions.txt
|-- .gitignore
\-- Cowboy Documentation Plan(v0.1) Milestone.md

Core Components

1. Rust Implementation (`crates/cowboy-core/`)

The heart of Cowboy, written in Rust for performance and safety.

Runtime
Consensus
Off-Chain Runner

Path: crates/cowboy-core/src/runtime/Contents:

pvm.rs - Python VM implementation
executor.rs - VM execution driver
context.rs - Execution context and I/O
mod.rs - Module declarations

Path: crates/cowboy-core/src/consensus.rsPurpose: HotStuff BFT consensus implementationKey Components:

Block proposal
Vote aggregation
QC (Quorum Certificate) verification
Safety and liveness guarantees

Path: crates/cowboy-core/src/runner/Purpose: Off-chain computation executor (CIP-2)Files:

http_executor.rs - HTTP-based runner
llm_executor.rs - LLM integrations
job_queue.rs - Job scheduling
openrouter.rs - OpenRouter client
mod.rs

2. Python SDK (`sdk/python/`)

Developer-facing SDK for building actors.

Core SDK
Examples
Tests

Path: sdk/python/cowboy_sdk/

Path: sdk/python/examples/

Path: sdk/python/tests/

3. Documentation (`docs/`)

This documentation site, built with Mintlify.

docs/
|-- architecture/
|-- assets/
|-- cips/
|-- contributing/
|-- developers/
|-- economics/
|-- getting-started/
|-- governance/
|-- images/
|-- introduction/
|-- overview/
|-- references/
|-- security/
|-- style/
|-- versioning/
|-- LICENSE
|-- README.md
|-- docs.json        # Mintlify config
|-- favicon.svg
|-- index.mdx
\-- quickstart.mdx

Key Files

Configuration Files

File	Purpose
`Cargo.toml`	Rust workspace configuration
`package.json`	Node.js dependencies
`docs/docs.json`	Documentation structure

Important READMEs

File	Description
`/README.md`	Project overview and quick start
`/sdk/python/README.md`	SDK installation and usage
`/docs/README.md`	Documentation contribution guide

Contributing Areas

Core Protocol

Language: RustAreas:

VM implementation
Consensus algorithms
Scheduler optimization
Security improvements

Path: crates/cowboy-core/

Python SDK

Language: PythonAreas:

SDK features
Developer tools
Testing utilities
Example actors

Path: sdk/python/

Documentation

Language: Markdown (MDX)Areas:

Technical guides
Tutorials
API reference
Diagrams

Path: docs/

Tooling

Language: VariousAreas:

CLI tools
Explorer UI
Development scripts
CI/CD

Path: Multiple

Finding Your Way Around

Looking for…

VM implementation

Path: crates/cowboy-core/src/runtime/pvm.rsCore Python VM bytecode interpreter.

Gas metering logic

Path: crates/cowboy-core/src/metering.rsCycle and Cell calculation implementation.

Off-chain runner

Path: crates/cowboy-core/src/runner/Off-chain task execution logic (CIP-2).

Actor base class

Path: sdk/python/cowboy_sdk/actor.pyPython Actor base class that developers inherit from.

Example actors

Path: sdk/python/examples/Ready-to-use actor templates.

Protocol specs

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

Introduction

Overview

Whitepaper

Getting Started

Architecture

Security

Economics

Ethereum Interoperability

Developer Guide

Protocol Specifications

Style & Documentation

Contributing

Versioning & Updates

References

Open Design Questions

Introduction

Repository Structure

Core Components

1. Rust Implementation (`crates/cowboy-core/`)

2. Python SDK (`sdk/python/`)

3. Documentation (`docs/`)

Key Files

Configuration Files

Important READMEs

Contributing Areas

Core Protocol

Python SDK

Documentation

Tooling

Finding Your Way Around

Looking for…

​Introduction

​Repository Structure

​Core Components

​1. Rust Implementation (crates/cowboy-core/)

​2. Python SDK (sdk/python/)

​3. Documentation (docs/)

​Key Files

​Configuration Files

​Important READMEs

​Contributing Areas

Core Protocol

Python SDK

Documentation

Tooling

​Finding Your Way Around

​Looking for…

Introduction

Repository Structure

Core Components

1. Rust Implementation (`crates/cowboy-core/`)

2. Python SDK (`sdk/python/`)

3. Documentation (`docs/`)

Key Files

Configuration Files

Important READMEs

Contributing Areas

Finding Your Way Around

Looking for…