Skip to main content

​
Introduction

The Cowboy documentation is comprehensive and covers many topics. This guide helps you find the most relevant content based on your role, experience level, and goals.
Not sure where to start? Follow the path that best matches your situation below.

​
By Role

​
Application Developer

Goal: Build actors (smart contracts) on Cowboy You should focus on:
  1. High-level concepts
  2. SDK usage
  3. Actor patterns
  4. Deployment
Recommended Path:
1

Quick Overview

What is Cowboy? (5 min)
2

Hands-On Start

Quickstart — initialize the CLI and deploy the hello actor on devnet
3

SDK Mastery

SDK Overview — the @actor decorator, self.storage, and runner.continuation FSM (CIP-6)Examples Curriculum — source-checkout examples from first actor through runner-backed agents
4

Best Practices

Best PracticesStyle Guide · Glossary
5

Advanced Topics

Actor VM OverviewFee ModelTransaction Format
Skip (for now):
  • Core protocol implementation details
  • Consensus mechanisms
  • Validator operations

​
Protocol Developer

Goal: Contribute to Cowboy core or build infrastructure You should focus on:
  1. Architecture deep dives
  2. Protocol specifications (CIPs)
  3. Implementation details
  4. Consensus and networking
Recommended Path:
1

Foundation

What is Cowboy? (5 min)Design Principles (15 min)Architecture Overview (20 min)
2

Deep Dive: Actor VM

Actor VM Overview (20 min)Determinism & Sandboxing (30 min)Resource Limits (15 min)
3

Deep Dive: Fee System

Fee Model Overview (20 min)Dual EIP-1559 (30 min)Metering Points (45 min)Worked Example (60 min)
4

Deep Dive: Scheduler

Scheduler Overview
5

Deep Dive: Off-Chain Compute

Off-Chain Overview
6

Codebase

Source Layout (15 min)Contributing Guide (20 min)
Key Documents:

​
AI/ML Engineer

Goal: Build autonomous AI agents on Cowboy You should focus on:
  1. Off-chain compute capabilities
  2. Python actor development
  3. Model inference patterns
  4. Data handling
Recommended Path:
1

Overview

What is Cowboy? (5 min)Focus on “Verifiable Off-Chain Compute” section
2

Quick Start

Quickstart Guide
3

Off-Chain Deep Dive

Off-Chain Compute Overview (30 min)Task Lifecycle (40 min)This is your key feature!
4

SDK for AI

SDK Overview — runner.llm(), runner.http(), runner.mcp() continuation patternsStudy the runner and LLM lessons in the examples curriculum
5

Runner Economics

Understand Runner Economics (see Off-Chain Overview)Learn how pricing works for compute tasks
Key Features for You:
  • ✅ LLM / HTTP / MCP executors (CIP-2)
  • ✅ Verifiable result submission (N-of-M, TEE, or ZK)
  • ✅ Continuation FSM for async callbacks (CIP-6)
  • ✅ CBFS for model weights and dataset storage

​
DeFi Developer

Goal: Build DeFi protocols (DEX, lending, derivatives) You should focus on:
  1. Actor patterns
  2. Gas optimization
  3. Security (reentrancy, etc.)
  4. Transaction atomicity
Recommended Path:
1

Basics

What is Cowboy? (5 min)Quickstart Guide (15 min)
2

SDK & Patterns

SDK Overview · Example Actors
3

Security (Critical!)

Review scheduling and congestion handling (CIP-1), determinism constraints, and best practices.
4

Gas Optimization

Fee Model Overview (20 min)Worked Example (30 min)Understand dual-gas system
5

Advanced Patterns

  • Flash loans (via atomic transactions)
  • Oracle integration (via off-chain compute)
  • Governance (via timers for delayed execution)
DeFi-Specific Considerations:
  • ✅ Native timers for scheduled execution (CIP-1)
  • ✅ Dual-metered pricing for compute vs data (CIP-3)

​
Security Researcher

Goal: Audit actors or find protocol vulnerabilities You should focus on:
  1. Security model
  2. Attack vectors
  3. Gas economics
  4. Consensus safety
Recommended Path:
1

Architecture

Actor VM OverviewDeterminism & Sandboxing
2

Attack Vectors

Study vulnerable patterns and congestion handling in the context of CIP-1 and CIP-3.
3

Resource Limits

Review determinism, metering, and limits (see CIP-3 and Actor VM sections).
4

Gas Economics

Fee Model
5

Consensus Security

Review consensus mechanism and Byzantine fault tolerance assumptions.
6

Off-Chain Security

Off-Chain OverviewConsider runner selection and collusion risks (see CIP-2).
Key Security Documents:

​
Researcher / Academic

Goal: Understand novel mechanisms and write papers You should focus on:
  1. Novel contributions
  2. Formal specifications
  3. Economic models
  4. Performance analysis
Recommended Path:
1

High-Level Vision

What is Cowboy?Design PrinciplesArchitecture Overview
2

Novel Mechanism 1: Dual-Metered Gas

Fee Model OverviewDual EIP-1559Research angle: Independent resource markets
3

Novel Mechanism 2: Autonomous Scheduling

Scheduler OverviewResearch angle: Gas bidding for timers
4

Novel Mechanism 3: Verifiable Off-Chain

Off-Chain OverviewResearch angle: VRF-based task assignment
5

Economics

TokenomicsEconomic Flows
6

Governance

CIP-12: GovernanceVersioning Strategy
Core Specifications:
  • Whitepaper and CIPs (see documentation)
Potential Research Topics:
  • Dual-resource EIP-1559 dynamics
  • VRF-based task assignment fairness
  • Gas bidding agent strategies
  • Off-chain compute verification trade-offs

​
By Experience Level

​
Blockchain Beginner

You’re new to blockchain entirely Start here:
  1. What is Cowboy?
  2. Architecture Overview
  3. Quickstart Guide
  4. FAQ
Then: Skip (for now):
  • Deep architecture docs
  • Protocol specifications
  • Consensus mechanisms

​
Python Developer (No Blockchain)

You know Python but not blockchain Your Advantages:
  • ✅ Python syntax familiarity
  • ✅ Testing frameworks familiarity
New Concepts to Learn:
  1. Blockchain basics: Blocks, transactions, consensus
  2. Determinism: Whitelisted modules, no JIT, strict UTF-8
  3. Fees: Dual-metered Cycles (compute) and Cells (data)
  4. Immutability: Code can’t be changed after deploy
Recommended Path:
  1. What is Cowboy?
  2. Quickstart
  3. Determinism & Sandboxing
  4. Fee Model
Key Insight: Think of actors as Python classes that:
  • Persist state via provided storage APIs
  • Do not access filesystem/network directly
  • Consume metered resources (Cycles/Cells)
  • Are immutable after deployment

​
Advanced / Protocol Level

You want to understand everything deeply Comprehensive Path:
1

Foundation

2

Actor VM

3

Fee System

4

Scheduler

5

Off-Chain

6

Transactions

  • Idempotency
  • Reentrancy
7

Development

​
By Goal

​
”I want to build a DApp quickly”

Fast Track:
  1. Quickstart
  2. SDK Overview
  3. Example Actors

​
”I want to build production-grade contracts”

Quality Track:
  1. Quickstart
  2. Best Practices
  3. Resource Limits
  4. Fee Model
  5. Testing (via cowboy_sdk.mock_host, hosted devnet, and optional local devnet)

​
“I want to run infrastructure (validator/runner)”

Infrastructure Track:
  1. Architecture Overview
  2. Source Layout — the node/, runner/, cbfs/ trees in a full source workspace
  3. Off-Chain Overview
  4. Local validator and deployment tooling from the full source workspace

​
”I want to contribute to Cowboy”

Contributor Track:
  1. Source Layout
  2. Contributing Guide
  3. Writing rules and style guides
  4. Pick an area (core/SDK/docs)
  5. Start contributing

​
Need Help Choosing?

Still not sure where to start? Refer to the Overview section or CIPs for authoritative guidance.