> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.lat/llms.txt
> Use this file to discover all available pages before exploring further.

# What is Cowboy?

> Understanding the fundamentals of the Cowboy Protocol

## Overview

Cowboy is a **Layer 1 blockchain protocol** purpose-built for **autonomous agents** and **verifiable off-chain computation**. Unlike traditional smart contract platforms, Cowboy provides native support for time-based execution, Python programming, and a fair dual-resource pricing model.

<Note>
  **Key Insight**: Cowboy treats time as a first-class citizen in the protocol, enabling truly autonomous agents that can schedule their own execution without relying on external infrastructure.
</Note>

## The Problem Space

Modern blockchain platforms face three fundamental challenges:

### 1. No Native Time Awareness

Smart contracts cannot schedule their own future execution. This forces developers to rely on:

* **External bots** (centralized, unreliable)
* **Keeper networks** (expensive, complex)
* **User-triggered transactions** (poor UX)

### 2. Unfair Resource Pricing

Single gas metrics cannot distinguish between:

* **Computation** (CPU cycles)
* **Storage** (state growth)
* **Data transfer** (bandwidth)

This leads to:

* Heavy computations subsidized by storage users
* Storage bloat subsidized by compute users
* Unpredictable costs for developers

### 3. Limited Computation

On-chain VMs are intentionally constrained:

* No AI/ML model inference
* No complex data processing
* No external API calls
* No access to off-chain data

**But moving computation off-chain introduces trust issues.**

## Cowboy's Solution

### 1. Protocol-Level Timers

Cowboy introduces **native timers** as a core protocol primitive.

**Key features:**

* **Tiered Calendar Queue**: O(1) enqueue/dequeue for near-term timers
* **Dynamic Gas Bidding (GBA)**: Actors bid for priority using protocol-supplied context
* **Autonomous Execution**: No external keeper infrastructure required

### 2. Dual-Metered Gas Model

Cowboy independently meters and prices two dimensions:

<CardGroup cols={2}>
  <Card title="Cycles (Computation)" icon="microchip">
    **What it measures**: CPU work - bytecode instructions, function calls, operations

    **Use case**: Python code execution, cryptography, data processing

    **Metering**: Instruction-level tracking in the VM
  </Card>

  <Card title="Cells (Data/Storage)" icon="database">
    **What it measures**: Bytes - transaction payloads, storage writes, return data

    **Use case**: State storage, large inputs/outputs, blob commitments

    **Metering**: Event-based tracking at I/O boundaries
  </Card>
</CardGroup>

**Benefits:**

* Fair pricing: Pay for what you use
* Predictable costs: Independent fee markets
* DoS protection: Separate limits prevent abuse

### 3. Verifiable Off-Chain Compute

Cowboy enables actors to **outsource computation** to a decentralized runner network while maintaining verifiability.

**Key properties:**

* **VRF-based selection**: Deterministic, verifiable runner assignment
* **Asynchronous execution**: Deferred callback model (per CIP-2)
* **Configurable verification**: Proof requirements are specified by the developer within the framework defined in CIP-2
* **Market-driven pricing**: Runners compete on price and reliability

## Core Architecture

### Actor Model

Cowboy uses an **actor-based** execution model:

```
+----------------------+
|       Messages       |
+----------------------+
          |
          v
+------------------------------------------------------------+
|    Actor                                                   |
|  - Persistent State (storage)                              |
|  - Message Handlers (Python code)                          |
|  - Mailbox (incoming messages)                             |
|  - Timer Queue (scheduled execution)                       |
|  - Balance (CBY tokens)                                    |
+------------------------------------------------------------+
          |
          v
+----------------------+
|      Responses       |
+----------------------+
```

**Characteristics:**

* **Isolated state**: Each actor has its own storage
* **Message-driven**: Communicate via asynchronous messages
* **Single-threaded**: One message processed at a time (deterministic)
* **Autonomous**: Can schedule its own future execution

### Python VM

Actors are written in **Python** and execute in a deterministic VM (no JIT, software FPU)

**VM guarantees:**

* ✅ **Determinism**: Same input → same output, always
* ✅ **Sandboxing**: No file I/O, network, or system calls
* ✅ **Resource metering**: Every operation has a cost
* ✅ **Memory limits**: Bounded per call (deterministic, configurable)

### Fee Markets

Two **independent EIP-1559 style markets**:

```
Cycles Market:
  basefee_cycle adjusts based on compute usage
  
Cells Market:
  basefee_cell adjusts based on data/storage usage
  
Total Fee = (cycles_used × basefee_cycle) + (cells_used × basefee_cell)
            + tips
```

**Basefee is burned**, creating deflationary pressure.

## Key Differentiators

| Feature               | Traditional Chains               | Cowboy                        |
| --------------------- | -------------------------------- | ----------------------------- |
| **Timers**            | External keepers required        | Native protocol support       |
| **Language**          | Domain-specific (Solidity, Move) | Python                        |
| **Gas Model**         | Single metric                    | Dual-metered (Cycles + Cells) |
| **Off-chain Compute** | Trust oracles                    | Verifiable runner network     |
| **Autonomy**          | Reactive only                    | Fully autonomous              |
| **Resource Pricing**  | Unified, often unfair            | Independent, fair markets     |

## Design Principles

<AccordionGroup>
  <Accordion title="1. Determinism First" icon="fingerprint">
    Every operation must produce identical results across all nodes. This guides every VM design decision.
  </Accordion>

  <Accordion title="2. Fair Resource Pricing" icon="scale-balanced">
    Different resources (compute, storage, data) should be priced independently based on their actual costs.
  </Accordion>

  <Accordion title="3. Autonomous by Default" icon="robot">
    Actors should be able to schedule their own execution without external dependencies.
  </Accordion>

  <Accordion title="4. Verifiable Off-Chain" icon="shield-check">
    Heavy computation can happen off-chain, but results must be verifiable on-chain.
  </Accordion>

  <Accordion title="5. Developer-Friendly" icon="code">
    Use familiar languages (Python) and patterns. Don't force developers to learn niche languages.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Key Innovations" icon="lightbulb" href="/overview/key-innovations">
    Dive deeper into Cowboy's technical innovations
  </Card>

  <Card title="Quick Start" icon="rocket" href="/getting-started/quickstart">
    Build your first Cowboy actor
  </Card>

  <Card title="Architecture" icon="sitemap" href="/overview/architecture">
    Understand the system architecture
  </Card>

  <Card title="Examples" icon="code" href="/getting-started/quickstart">
    Study working examples via Quickstart
  </Card>
</CardGroup>

## Further Reading

* [Architecture Overview](/overview/architecture)
* [Design Principles](/overview/design-principles)
* [Actor VM Overview](/architecture/actor-vm/overview)
* [Fee Model Overview](/architecture/fees/overview)