> ## 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.

# FAQ

> Common questions about Cowboy answered

## General Questions

<AccordionGroup>
  <Accordion title="What is Cowboy?" icon="circle-question">
    Cowboy is a Layer 1 blockchain protocol designed for **autonomous agents** and **verifiable off-chain computation**. It features:

    * **Python-based smart contracts** (Actors) instead of Solidity
    * **Dual-metered gas system** (Cycles for compute, Cells for data)
    * **Native timers** for autonomous execution
    * **Verifiable off-chain compute** for AI/ML and external data

    Think of it as "Ethereum but optimized for AI agents and complex computation."
  </Accordion>

  <Accordion title="Why Python instead of Solidity?" icon="python">
    **Advantages of Python**:

    ✅ **Familiar**: 80%+ of AI/ML developers already know Python
    ✅ **Expressive**: Cleaner, more readable code
    ✅ **Ecosystem**: Direct access to data structures, algorithms
    ✅ **AI-Ready**: Natural fit for AI agent logic

    **How we make it work**:

    * Deterministic Python VM (no system calls, no I/O)
    * Software floating-point for consensus
    * Strict module whitelist
    * Comprehensive gas metering

    See [Actor VM & Determinism](/architecture/actor-vm/determinism-and-sandbox) for details.
  </Accordion>

  <Accordion title="What are Actors?" icon="user">
    **Actors** are Cowboy's equivalent of smart contracts. Key differences:

    | Concept      | Ethereum          | Cowboy         |
    | ------------ | ----------------- | -------------- |
    | **Contract** | Solidity contract | Python Actor   |
    | **Function** | External function | Handler method |
    | **State**    | Storage variables | `storage` API  |
    | **Call**     | Transaction       | Message        |
    | **Address**  | 0x...             | 0x...          |

    **Conceptual example** (pseudocode):

    ```python theme={null}
    class MyActor:
        def my_handler(self, param):
            value = storage.get("key")
            storage.set("key", value + param)
            return value
    ```
  </Accordion>

  <Accordion title="Is Cowboy EVM-compatible?" icon="ethereum">
    **No**, Cowboy is not EVM-compatible. Key differences:

    ❌ **Not compatible**:

    * Different VM (Python instead of EVM)
    * Different transaction format
    * Different gas model (Cycles + Cells vs single gas)

    ✅ **Similar**:

    * Similar concepts (accounts, transactions, blocks)

    **Migration Path**: Solidity contracts need to be rewritten in Python, but logic can be ported.
  </Accordion>

  <Accordion title="What's the difference between Cowboy and Ethereum?" icon="scale-balanced">
    | Feature               | Ethereum               | Cowboy                  |
    | --------------------- | ---------------------- | ----------------------- |
    | **Language**          | Solidity               | Python                  |
    | **VM**                | EVM                    | Python VM               |
    | **Gas Model**         | Single gas             | Cycles + Cells          |
    | **Timers**            | No (need Gelato, etc.) | Native                  |
    | **Off-Chain Compute** | Oracles (Chainlink)    | Native (CIP-2)          |
    | **Consensus**         | PoS (Gasper)           | HotStuff BFT            |
    | **Target Use Case**   | General DeFi           | AI Agents + Computation |
  </Accordion>
</AccordionGroup>

## Technical Questions

<AccordionGroup>
  <Accordion title="How does dual-metered gas work?" icon="gauge">
    Cowboy separates resource pricing into **two dimensions**:

    **Cycles (Computation)**:

    * Measures CPU work
    * Every bytecode instruction costs cycles
    * Example: Function call = 10 cycles

    **Cells (Data/Storage)**:

    * Measures data and storage
    * 1 Cell = 1 byte
    * Charged at I/O boundaries

    **Why?**

    * Fair pricing: Don't subsidize compute-heavy apps with storage costs
    * Independent markets: Each resource has its own basefee
    * Predictable: Know exactly what you're paying for

    See [Fee Model](/architecture/fees/overview) for details.
  </Accordion>

  <Accordion title="How are timers different from Gelato/Chainlink Automation?" icon="clock">
    **Cowboy Native Timers** (CIP-1):

    ✅ **Protocol-native**: No external service required
    ✅ **Gas bidding**: Actors bid for execution priority
    ✅ **Guaranteed execution**: Timers eventually execute (not reliant on keepers)
    ✅ **Fair scheduling**: Based on economic priority, not FCFS

    **vs. External Automation**:

    | Feature     | Gelato/Chainlink   | Cowboy              |
    | ----------- | ------------------ | ------------------- |
    | Integration | External contract  | Native API          |
    | Reliability | Depends on keepers | Protocol-guaranteed |
    | Priority    | FCFS or fixed      | Dynamic bidding     |
    | Cost        | Fixed fee + gas    | Just gas (cycles)   |

    See [Timers & Scheduler](/architecture/scheduler/overview).
  </Accordion>

  <Accordion title="How does off-chain compute work?" icon="server">
    **Verifiable Off-Chain Compute** (CIP-2):

    1. **Submit Task**: Actor calls `submit_task()` with task definition
    2. **VRF Selection**: Runners deterministically selected via VRF
    3. **Execution**: Selected runners execute task (AI model, API call, etc.)
    4. **Result Submission**: Runners submit results on-chain
    5. **Callback**: Actor receives results in callback handler
    6. **Payment**: Actor pays winning runner(s)

    See [Off-Chain Compute](/architecture/offchain/overview).
  </Accordion>

  <Accordion title="Is Cowboy deterministic?" icon="fingerprint">
    **Yes, completely deterministic**. All nodes must produce identical results.

    **How we achieve it**:

    * ✅ Software floating-point (no hardware FPU)
    * ✅ No JIT compilation
    * ✅ Deterministic GC (reference counting)
    * ✅ No system calls (time, random, I/O)
    * ✅ Module whitelist

    **What's forbidden**:

    ```python theme={null}
    # ❌ These will fail:
    import os
    import random
    import time
    import requests
    ```

    **Use instead**:

    * ✅ Use protocol-provided randomness/time context APIs (instead of local RNG/system time)
    * ✅ Use protocol storage and off-chain submission interfaces (see related docs)

    See [Determinism & Sandboxing](/architecture/actor-vm/determinism-and-sandbox).
  </Accordion>

  <Accordion title="How is consensus achieved?" icon="handshake">
    Cowboy uses **HotStuff BFT** consensus:

    **Properties**:

    * Byzantine Fault Tolerant (BFT)
    * Deterministic finality (no reorgs)
    * Leader rotation
    * Requires 2/3+ honest validators

    **Phases**:

    1. Leader proposes block
    2. Validators vote (QC = Quorum Certificate)
    3. Block finalized with 2/3+ votes
    4. Next leader elected

    **vs. Nakamoto Consensus** (Bitcoin):

    * ✅ Faster: 2s vs 10min
    * ✅ Finality: Immediate vs probabilistic
    * ❌ More validators needed
  </Accordion>
</AccordionGroup>

## Development Questions

<AccordionGroup>
  <Accordion title="Do I need to know Rust?" icon="rust">
    **No!** You only need Python to build actors.

    **Rust is only needed if you want to**:

    * Contribute to the core protocol
    * Build custom validator nodes
    * Optimize VM performance

    **For actor development**:

    * ✅ Python only
    * ✅ Familiar SDK
    * ✅ Standard Python tooling
  </Accordion>

  <Accordion title="How do I test actors locally?" icon="vial">
    **Testing Options**:

    **1. Unit Tests** (Fastest):

    * Use standard Python test frameworks (e.g., pytest/unittest) to unit-test business logic
    * Use dependency injection/lightweight stubs to replace protocol interactions

    **2. Local Devnet** (Most realistic):

    * Local devnet and dedicated testing tools will be released in a future milestone

    **3. Testnet** (Public):

    * Use the public testnet for end-to-end validation (deploy, invoke, receipt)

    See [Repository Layout](/getting-started/repo-layout).
  </Accordion>

  <Accordion title="How much does it cost to deploy an actor?" icon="dollar-sign">
    **Testnet**: Free! (Get tokens from [faucet](#))

    **Mainnet** (illustrative principles):

    * Costs are metered separately by Cycles and Cells and computed via their respective basefee/tip
    * Influencing factors: bytecode size (Cells), constructor logic complexity (Cycles), current basefees, etc.

    It is recommended to estimate resources and set limits before deployment (see Fee Model overview).
  </Accordion>

  <Accordion title="Can I use external Python packages?" icon="box-open">
    **No, with exceptions**.

    **Forbidden**:
    ❌ `requests` - Network I/O
    ❌ `numpy` - Native C extensions
    ❌ `pandas` - Native dependencies
    ❌ `tensorflow` - Too large, native code

    **Allowed** (whitelist):
    ✅ `collections` - Data structures
    ✅ `itertools` - Iteration utilities
    ✅ `json` - JSON encoding
    ✅ `math` - Math functions (deterministic impl)
    ✅ `hashlib` - Hashing

    **For external data/compute**:

    * Use Off-chain Compute (CIP-2) to execute off-chain and return verifiable results

    See [Determinism & Sandboxing](/architecture/actor-vm/determinism-and-sandbox).
  </Accordion>

  <Accordion title="How do I debug a failed transaction?" icon="bug">
    **Steps** (general guidance):

    1. Check the transaction receipt/error message (block explorer or SDK)
    2. Common causes:
       * Insufficient Cycles limit: increase `gas_limit_cycles` or optimize computation
       * Insufficient Cells limit: increase `gas_limit_cells` or reduce data
       * Input or business validation failure: verify input data and business logic
       * Insufficient permissions: check access control and caller
    3. Unit test locally before on-chain validation
  </Accordion>

  <Accordion title="How do I upgrade an actor?" icon="arrow-up">
    **Actors are immutable by default**; conceptual strategies include:

    * Proxy pattern: delegate calls to a replaceable implementation with strict access control
    * Redeploy: deploy a new version, migrate state, update frontend addresses
    * Migration contract: dedicated migration process (batch validation/rollback strategy)

    Security notes: access control, replay protection, data consistency checks.
  </Accordion>
</AccordionGroup>

## Economics & Token Questions

<AccordionGroup>
  <Accordion title="How are fees calculated?" icon="calculator">
    **Formula**:

    ```
    Total Fee = (Cycles Used × Basefee_Cycle) + 
                (Cells Used × Basefee_Cell) +
                (Cycles Used × Tip_Cycle) +
                (Cells Used × Tip_Cell)
    ```

    **Basefee**: Burned 🔥 (deflationary)
    **Tip**: To block producer (incentive)

    See [Fee Model](/architecture/fees/overview).
  </Accordion>

  <Accordion title="Why do basefees fluctuate?" icon="chart-line">
    **Dual EIP-1559 Mechanism**:

    Basefees adjust dynamically based on demand:

    ```
    If block usage > target (50%):
      → Basefee increases

    If block usage < target (50%):
      → Basefee decreases
    ```

    **Example**:

    ```
    Block N: 80% utilization
    → Basefee +7.5%

    Block N+1: 30% utilization
    → Basefee -5%
    ```

    **Benefits**:

    * Fair pricing (supply/demand)
    * Predictable (can estimate fees)
    * Anti-spam (expensive during congestion)

    See [Dual EIP-1559](/architecture/fees/dual-eip1559).
  </Accordion>
</AccordionGroup>

## Community & Support

<AccordionGroup>
  <Accordion title="Where can I get help?" icon="circle-question">
    **Official Channels**:

    * 💬 [Discord](#) - Real-time support
    * 📖 [Forum](#) - Technical discussions
    * 🐛 [GitHub Issues](https://github.com/cowboyinc/cowboy/issues) - Bug reports
    * 🐦 [Twitter](#) - Updates
  </Accordion>

  <Accordion title="How can I contribute?" icon="code-pull-request">
    **Ways to Contribute**:

    1. **Code**:
       * Core protocol (Rust)
       * SDK improvements (Python)
       * Tooling and CLI
    2. **Documentation**:
       * Write tutorials
       * Fix typos
       * Add examples
    3. **Testing**:
       * Test on testnet
       * Report bugs
       * Suggest improvements
    4. **Community**:
       * Answer questions on Discord
       * Write blog posts
       * Create videos

    See [Contributing Guide](/contributing/how-to-propose).
  </Accordion>
</AccordionGroup>

## Still Have Questions?

<CardGroup cols={3}>
  <Card title="Join Discord" icon="discord" href="#">
    Ask the community in real-time
  </Card>

  <Card title="Forum" icon="comments" href="#">
    Start a technical discussion
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/cowboyinc/cowboy/">
    Browse existing discussions
  </Card>
</CardGroup>