Determinism & Sandboxing - Cowboy Protocol

Introduction

Cowboy’s Actor VM executes Python code in a deterministic and sandboxed environment. This document explains the technical challenges and solutions for running a high-level, dynamic language like Python on a blockchain.

Core Challenge: Python is inherently non-deterministic and has unlimited system access. We must constrain it without breaking its expressiveness.

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.

Why Determinism Matters

The Consensus Requirement

Same input and environment MUST lead to the same state transition and outputs on all nodes; any divergence implies consensus failure. What happens if non-deterministic:

❌ Nodes cannot agree on state root
❌ Chain halts or forks
❌ Network is unusable

Sources of Non-Determinism

Key sources include: system time, OS randomness, filesystem and network I/O, hardware floating-point variance, and reliance on container iteration order. These must be either prohibited or made deterministic per protocol rules.

Cowboy’s Determinism Solutions

1. No System Dependencies

Problem: System calls produce different results on different machines. Solution: Complete isolation from host system.

Prohibited Operations
Allowed Alternatives

# ❌ All of these are FORBIDDEN:

import os
hostname = os.gethostname()  # ImportError

import socket
s = socket.socket()  # ImportError

import time
now = time.time()  # ImportError

import random
x = random.random()  # ImportError

open("/etc/passwd")  # ImportError (no file access)

import requests
requests.get("...")  # ImportError

2. Software Floating-Point

Problem: Hardware FPUs produce slightly different results across CPU architectures. Solution: Deterministic software implementation of IEEE 754.

# All floating-point operations use software implementation
x = 3.14159 * 2.71828  # Same result on ALL hardware

# Breakdown:
# 1. Fetch operands (3.14159, 2.71828)
# 2. Software multiply using IEEE 754 algorithm
# 3. Round result deterministically
# 4. Return exact same bit pattern on all nodes

Trade-off:

✅ Deterministic across all platforms
❌ ~2-5× slower than native FPU
✅ Acceptable for blockchain consensus

3. Deterministic Memory Management

Problem: Garbage collection timing is non-deterministic in standard Python. Solution: Reference counting with immediate, deterministic cleanup.

Standard Python GC
Cowboy Deterministic GC

# ❌ Non-deterministic GC

def process():
    data = [0] * 1000000
    result = compute(data)
    return result
    # When does GC run?
    # - Maybe immediately
    # - Maybe after 100 more allocations
    # - Maybe after next GC cycle
    # → Non-deterministic timing!

Key properties:

✅ Immediate: Objects destroyed when refcount reaches 0
✅ Deterministic: Same operations → same cleanup timing
✅ Metered: Destruction costs charged in Cycles
❌ No cycle detection: Circular references forbidden

4. No JIT Compilation

Problem: JIT compilers make non-deterministic optimization decisions. Solution: Pure interpretation mode only.

# Traditional Python (CPython with JIT):
# 1. Interpret bytecode
# 2. Hot loop detected
# 3. JIT compile to machine code
# 4. Execute native code
# → When does JIT kick in? Non-deterministic!
# → What optimizations apply? Platform-dependent!

# Cowboy Python (Pure Interpreter):
# 1. Interpret bytecode
# 2. Continue interpreting
# 3. Always interpret
# → Same bytecode → same execution path
# → Same cost, always ✅

Trade-off:

✅ Deterministic execution
✅ Predictable gas costs
❌ Slower than JIT (10-100×)
✅ Acceptable for blockchain (security > speed)

5. Dictionary Ordering and Serialization

Problem: Relying on dictionary iteration order can introduce non-determinism. Solution: Do not rely on in-memory iteration order when it affects results. When order matters, sort keys explicitly. Per CIP‑3, dictionary keys MUST be sorted lexicographically during serialization to ensure determinism.

# When order matters, sort explicitly
for key in sorted(d.keys()):
    process(key)

Implementation:

Serialization: keys sorted lexicographically (CIP-3 requirement)
In execution paths where order impacts results, explicitly sort

6. Prohibited Async Concurrency

Problem: async/await scheduling can be non-deterministic. Solution: Strict deterministic scheduling (FIFO queue).

# ❌ Forbidden: Non-deterministic concurrency
async def task1():
    await asyncio.gather(subtask_a(), subtask_b())
    # Execution order undefined!

# ✅ Allowed: Deterministic async
async def task2():
    result_a = await subtask_a()  # Executes first
    result_b = await subtask_b()  # Executes second
    # Order always same ✅

Rules:

Single-threaded execution only
FIFO queue for awaiting coroutines
No asyncio.gather() or similar
Deterministic scheduling guaranteed

7. String Encoding Determinism

Problem: Encoding edge cases handled differently across platforms. Solution: UTF-8 only, strict mode.

# ✅ Allowed: UTF-8 with strict error handling
text = "Hello world"
encoded = text.encode('utf-8', errors='strict')
# Same bytes on all platforms

# ❌ Forbidden: Other encodings
text.encode('latin-1')  # ValueError
text.encode('utf-8', errors='ignore')  # ValueError (non-strict)

# ❌ Forbidden: Invalid UTF-8
invalid = b'\xff\xfe'
try:
    invalid.decode('utf-8', errors='strict')
except UnicodeDecodeError:
    pass  # Must raise exception, cannot silently replace

8. Integer Precision Limits

Problem: Arbitrary precision enables DoS attacks. Solution: 4096-bit limit with overflow checks.

# ✅ Allowed: Numbers up to 4096 bits
x = 2 ** 4096  # OK: Exactly at limit

# ❌ Forbidden: Exceeding limit
y = 2 ** 4097  # OverflowError

# ❌ Forbidden: Intermediate overflow
a = 2 ** 4000
b = 2 ** 4000
c = a * b  # OverflowError (result would be 8000 bits)

Benefits:

✅ Prevents big-int DoS attacks
✅ Proportional costs for large integers
✅ Still larger than practical needs (4096 bits >> 256 bits for crypto)

Sandboxing Mechanisms

Module Whitelist

Enforcement: Import hook intercepts all imports.

# Protocol whitelist (example subset per CIP-3)
ALLOWED_MODULES = {
    # Data structures
    "collections", "itertools",
    
    # Math (deterministic implementation)
    "math",
    
    # Hashing/crypto
    "hashlib",
    
    # Serialization
    "json",
    
    # Protocol APIs
    "cowboy.messaging", "cowboy.storage", "cowboy.timers", "cowboy.crypto"
}

def import_hook(module_name):
    if module_name in ALLOWED_MODULES:
        return load_module(module_name)
    else:
        raise ImportError(f"Module '{module_name}' not whitelisted")

Costs:

First import: 100 cycles + module init
Cached import: 5 cycles
Failed import: 50 cycles (penalty)

System Isolation

Actors cannot perform file, network, or process operations. Access to host OS is prohibited; only protocol-provided, deterministic and metered host APIs are available.

Resource Limits

Enforcement overview:

Cycles: instruction-level metering; execution halts on limit (CIP‑3).
Cells: metered at I/O boundaries (calldata, storage, blobs, return data) per CIP‑3.
Memory/stack: hard limits enforced; overflow triggers deterministic errors.

Host Function APIs

Enforcement: Only whitelisted host functions callable.

# Conceptual host APIs (non-normative)
# Examples: storage_get/set, send, schedule_timer, verify_ecdsa, hash_keccak256, submit_offchain_task

# ✅ Only approved, metered, deterministic host functions are callable

# ❌ Cannot call arbitrary native functions
# ❌ Cannot load C extensions
# ❌ Cannot access CPython internals

Testing Determinism

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

Sandboxing Verification

Security Audit Checklist

System Isolation

Module Restrictions

Resource Limits

Determinism Guarantees

Performance Considerations

Determinism and security take precedence over raw speed. The VM uses software floating‑point, prohibits JIT, and enforces deterministic memory management per CIP‑3.

Best Practices

Embrace Determinism

Design with determinism in mind from the start:

# ✅ Good: Deterministic by design
def process_batch(self, items):
    # Sort for consistent ordering
    sorted_items = sorted(items, key=lambda x: x.id)
    
    for item in sorted_items:
        self.process_item(item)

Use Protocol APIs

Leverage protocol-provided functionality:

# For randomness (conceptual):
rand = vrf_random()

# For time:
current_time = self.block.timestamp

# For external data (conceptual; CIP-2 Dispatcher):
submit_offchain_task(...)

Test Extensively

Verify determinism in tests:

def test_my_actor(self):
    # Execute same input multiple times
    results = [self.execute(input) for _ in range(10)]
    
    # All must be identical
    assert all(r == results[0] for r in results)

Next Steps

Actor VM Overview

High-level VM architecture

Resource Limits

Detailed limit specifications

CIP-3 Metering

Complete metering specification

Best Practices

Writing efficient actors

​Introduction

​Why Determinism Matters

​The Consensus Requirement

​Sources of Non-Determinism

​Cowboy’s Determinism Solutions

​1. No System Dependencies

​2. Software Floating-Point

​3. Deterministic Memory Management

​4. No JIT Compilation

​5. Dictionary Ordering and Serialization

​6. Prohibited Async Concurrency

​7. String Encoding Determinism

​8. Integer Precision Limits

​Sandboxing Mechanisms

​Module Whitelist

​System Isolation

​Resource Limits

​Host Function APIs

​Testing Determinism

​Sandboxing Verification

​Security Audit Checklist

​Performance Considerations

​Best Practices

​Next Steps

Actor VM Overview

Resource Limits

CIP-3 Metering

Best Practices

​Further Reading

Introduction

Why Determinism Matters

The Consensus Requirement

Sources of Non-Determinism

Cowboy’s Determinism Solutions

1. No System Dependencies

2. Software Floating-Point

3. Deterministic Memory Management

4. No JIT Compilation

5. Dictionary Ordering and Serialization

6. Prohibited Async Concurrency

7. String Encoding Determinism

8. Integer Precision Limits

Sandboxing Mechanisms

Module Whitelist

System Isolation

Resource Limits

Host Function APIs

Testing Determinism

Sandboxing Verification

Security Audit Checklist

Performance Considerations

Best Practices

Next Steps

Further Reading