Introduction
Cowboy was designed from first principles to enable autonomous agents and verifiable computation on a blockchain. Every architectural decision flows from a set of core principles that prioritize usability, security, fairness, and composability.1. Developer Experience First
Principle: Make blockchain development accessible to mainstream developers, especially those building AI agents.Why Python?
Traditional blockchain: Learn chain-specific languages Cowboy: Use Python (widely adopted in AI/ML ecosystems) Impact:- Lower barrier to entry
- Reuse existing Python skills
- Access to Python ecosystem patterns
- Natural fit for AI/ML logic
- Slower execution (vs compiled languages)
- More complex VM implementation
- Determinism constraints (no standard library I/O)
2. Fair Resource Pricing
Principle: Different resources should have different prices. Users shouldn’t subsidize each other’s costs.Two-Meter Gas System
Traditional blockchain: Single “gas” metric for everything Problem: Compute and storage have different costs- CPU cycles: expensive during execution, free after
- Storage: cheap initially, expensive ongoing (stored forever)
- Fair pricing: compute-heavy apps don’t subsidize storage-heavy apps
- Independent markets: each resource has its own supply/demand dynamics
- Predictable costs: developers know exactly what they’re paying for
3. Determinism Above All
Principle: All nodes must produce identical results. Non-determinism breaks consensus.Strict Determinism Requirements
Challenge: Python is inherently non-deterministic- System time varies
- Random varies
- Dictionary ordering can vary
- Floating-point hardware varies
- Guaranteed consensus (no forks from non-determinism)
- Predictable behavior (same input → same output, always)
- Testable (local tests match on-chain behavior exactly)
- Some Python features unavailable
- Slower execution (software FPU, no JIT)
- Developer constraints (must use protocol APIs)
4. Native Autonomy
Principle: Actors should execute autonomously without external infrastructure.Built-In Timer System
Traditional blockchain: Rely on external services (Gelato, Chainlink Automation) Problems:- Additional dependency
- Trust assumptions
- Extra costs
- Integration complexity
- True autonomy: actors self-execute
- No external dependencies
- Deterministic FIFO admission within bounded resource budgets
- Best-effort execution subject to funding, expiry, and carry limits
5. Verifiable Off-Chain Execution
Principle: Heavy computation should happen off-chain, but remain verifiable and decentralized.Native Off-Chain Compute Framework
Challenge: On-chain execution is expensive and limited- AI models are too large
- API calls need network access
- Heavy computation exceeds gas limits
- Oracles (centralized, trust-based)
- State channels (complex, limited use cases)
- Optimistic rollups (still EVM-limited)
- Submit task to the Dispatcher (with mandatory result_schema; CIP-2)
- Deterministically select candidate runners via VRF logic
- Runner executes or skips; submits results and optional proofs on-chain
- When N results are collected, trigger deferred callback; actor consumes and finalizes payment
- VRF-Based Selection: No central coordinator; deterministic, verifiable selection.
- Configurable Verification: Proof requirements are specified by developers within the CIP-2 framework.
- Market-Based Pricing: The protocol does not mandate a price; participants discover prices off-chain.
- Off-chain execution with on-chain verifiability
- Decentralized selection and submission
- Configurable verification requirements (per CIP-2)
6. Economic Incentive Alignment
Principle: Protocol economics should align incentives for all participants.Fee Burn Mechanism (Dual EIP-1559)
Every transaction pays basefee (burned) and optional tips to the block producer across both resources (Cycles and Cells). Pricing dynamics follow CIP-3.7. Security by Default
Principle: Make the secure path the easy path. Make mistakes hard.Secure Defaults
Secure defaults include: sandboxed execution, enforced resource limits, and isolated processing per transaction.8. Composability
Principle: Actors should easily interact with each other to create complex systems.Message-Based Architecture
Actors talk to each other by sending messages to an address, and each message runs a named handler on the receiver. Design Choices:- Asynchronous messaging, plus synchronous calls where a handler needs the answer
- Explicit handler calls (clear interface)
- Address-based routing (simple)
- Actor calls Actor: Direct messaging
- Actor publishes event: Subscription pattern
- Actor delegates to Actor: Proxy pattern
- Actors coordinate: Multi-party protocols
9. Progressive Complexity (Conceptual)
Principle: Simple things should be simple. Complex things should be possible.Layered Abstractions
Progressive complexity spans from simple stateful actors to timer-driven systems and off-chain integrations (CIP-1 / CIP-2). Principle in Action:- Beginners can build useful things immediately
- Experts can leverage full power
- Gradual learning curve
10. Transparency and Openness
Principle: Everything should be observable and auditable. Cowboy’s rules are written down where you can read them: explicit metering in CIP-3, and the rest of the protocol in the other CIPs.Principles in Practice (Illustrative)
Example: Timer Implementation (Conceptual)
The timer system (CIP-5) applies these principles through protocol-native FIFO scheduling, live-basefee payment, and bounded per-block processing.Trade-offs We Made (High-level)
Principle: Be honest about compromises Trade-offs include: using a Python VM for developer familiarity, software floating-point and no JIT for determinism, two gas meters for fair pricing, and BFT-style consensus for fast finality.Next Steps
Architecture Overview
See how principles became architecture
What is Cowboy
The App Store for AI in a few minutes
Quickstart
Experience the principles in action
Contributing
Help shape Cowboy’s future