Skip to main content

​
Introduction

The Actor VM is Cowboy’s deterministic Python execution environment. It enables developers to write smart contracts in Python while maintaining the strict determinism and security requirements of a blockchain protocol.
Key Insight: Cowboy achieves determinism not by creating a new language, but by carefully constraining Python to a deterministic subset and providing a metered, sandboxed execution environment.
Note: Examples in this page are conceptual snippets/pseudocode. Final interfaces and usage should follow the SDK and Developer Guide. CIP specifications define normative protocol behavior.

​
Actor Model Fundamentals

​
What is an Actor?

An Actor is an independent entity with: 
+------------------------------------------------------------+
|                      Actor Instance                        |
+------------------------------------------------------------+
|  - State:    Persistent storage                            |
|  - Code:     Python class                                  |
|  - Mailbox:  Message queue                                 |
|  - Timers:   Scheduled execution                           |
|  - Balance:  CBY tokens                                    |
|  - Address:  Unique identifier                             |
+------------------------------------------------------------+

​
Core Properties

Each actor has its own storage. No shared memory between actors. Persistent state MUST use protocol storage APIs; in-memory variables are ephemeral per invocation.
Communication happens via asynchronous messages; avoid synchronous assumptions about order.
One message processed at a time. No concurrency within an actor.
Can schedule its own future execution via timers (see CIP-1).

​
Python VM Architecture

​
Execution Flow

+--------------------------------------------------------------------+
|  1. Transaction Submission                                         |
|    - User submits transaction with payload                         |
|    - Payload: target actor + handler + arguments                   |
+--------------------------------------------------------------------+
                               |
                               v
+--------------------------------------------------------------------+
|  2. Pre-Execution Metering                                         |
|    - Charge intrinsic calldata (payload size -> Cells)             |
|    - Load actor state from storage                                 |
|    - Initialize VM with resource limits                            |
+--------------------------------------------------------------------+
                               |
                               v
+--------------------------------------------------------------------+
|  3. Bytecode Execution                                             |
|    - Interpret Python bytecode                                     |
|    - Meter every instruction (-> Cycles)                           |
|    - Track memory allocation (-> Cells)                            |
|    - Enforce resource limits                                       |
+--------------------------------------------------------------------+
                               |
                               v
+--------------------------------------------------------------------+
|  4. State Commitment                                               |
|    - Serialize modified state                                      |
|    - Meter storage writes (-> Cells)                               |
|    - Update Merkle state tree                                      |
+--------------------------------------------------------------------+
                               |
                               v
+--------------------------------------------------------------------+
|  5. Fee Settlement                                                 |
|    - Calculate total cost (Cycles + Cells)                         |
|    - Burn basefee portion                                          |
|    - Pay tip to block producer                                     |
+--------------------------------------------------------------------+

​
VM Components

Pure bytecode interpretation (no JIT)Key properties:
  • Deterministic: Same bytecode → same execution
  • Metered: Every instruction charged
  • Sandboxed: No escape to host system

​
Determinism Guarantees

Cowboy’s VM enforces determinism: given the same input, all nodes produce identical output.

​
Determinism Requirements

1

No System Dependencies

No access to:
  • System time
  • Local randomness
  • File system
  • Network
  • Environment variables
Rationale: These produce different values across machines or times.
2

Deterministic Arithmetic

All floating-point operations use a software implementation of IEEE 754.
3

Deterministic Memory Management

Reference counting with immediate cleanup; destruction costs are metered in Cycles per CIP‑3.
4

No JIT Compilation

Pure interpretation only; JIT is prohibited.
5

Dictionary Ordering and Serialization

Do not rely on in-memory iteration order when results depend on ordering. When order matters, sort keys explicitly. During serialization, dictionary keys MUST be sorted lexicographically (CIP‑3) to ensure determinism.

​
Testing Determinism

A determinism test suite verifies that identical inputs produce identical outputs and state transitions across environments, covering instruction metering, serialization (sorted keys), exception handling costs, and software floating‑point behavior.

​
Resource Limits

Per-call resource limits and protocol constraints prevent DoS attacks:
  • Cycles: Instruction-level metering with protocol-defined hard limits (CIP‑3)
  • Cells: Data/IO metering with protocol-defined hard limits (CIP‑3)
  • Memory: Per-transaction/per-call heap memory hard limit per CIP‑3
  • Integer Size: 4096-bit maximum; exceeding raises OverflowError (CIP‑3)
  • Stack/Recursion: Protocol-defined limits to prevent unbounded depth
  • Storage Size: Per-actor quotas with rent/pruning policies per protocol

​
Protocol Host Functions (Categories)

Actors interact with the protocol via deterministic, metered host functions (non-exhaustive categories):
  • Storage: Persistent key/value operations; blob commits for large content-addressed data
  • Messaging: Asynchronous message send/receive
  • Timers: Schedule/cancel per CIP‑1; execution prioritized via GBA under per-block timer budget
  • Cryptography: Hashing and signature verification; VRF access via protocol APIs

​
Best Practices

Batch writes where possible to reduce Cells; design data layout to minimize serialization overhead.
Validate input sizes early; avoid unbounded loops; fail fast on invalid data.
Sort keys or items when order affects results; rely on CIP‑3 serialization guarantees.

​
Next Steps

Determinism & Sandbox

Deep dive into how determinism is achieved

Resource Limits

Detailed specification of all resource limits

Minimal Actor Example

Build your first actor step-by-step

Fee Model

Understand Cycles and Cells metering

​
Further Reading