Skip to main content

Resource Limits

The Actor VM enforces layered, deterministic resource limits to ensure safety, fairness, and consensus across clients. Limits are expressed along two orthogonal dimensions — Cycles (compute) and Cells (data) — and are complemented by strict execution constraints that make Python-on-chain deterministic.
Note: Names and examples in this page are conceptual and illustrative. Final interfaces and usage should follow the SDK and Developer Guide; CIP specifications define normative protocol behavior. Scope
  • What is limited: compute, data, module imports, numeric ranges, async scheduling, and timers.
  • Where it is enforced: at the VM instruction loop, host function boundaries, transaction ingress/egress, and block-level scheduler.

Resource dimensions

Cycles (compute)

  • Unit: an abstract instruction step. Charged before executing each Python bytecode and on selected control-flow/runtime events.
  • Enforced under protocol-defined cycles limits for execution; when exhausted, execution halts with an Out of Cycles error.
  • Partial cost table (consensus-critical; see CIP-3):
Dynamic surcharges (CIP-3): for type/size-dependent operations, a base cost is charged plus a runtime surcharge (e.g., string/list concatenation proportional to length).

Cells (data)

  • Unit: 1 Cell = 1 byte. Charged at I/O boundaries via host functions and at transaction ingress/egress.
  • Enforced as cells_limit per transaction. When exhausted, execution halts with an Out of Cells error.
  • Metering points (CIP-3):
    • Intrinsic calldata: charged before VM execution (payload size).
    • Host functions: data-bearing calls must charge the exact byte count.
      • storage_set(key, value): len(key) + len(value) Cells.
      • put_blob(data): len(data) Cells.
    • Scratch /tmp: immediate charge on file writes by number of bytes.
    • Return data: charged after a successful handler return by byte size.

Deterministic execution constraints (consensus-critical)

These constraints are mandatory to keep all clients in lockstep (CIP-3):
  • No JIT compilation: the VM executes in pure interpretation mode.
  • No arbitrary C extensions: high-performance needs are exposed as deterministic, metered host functions.
  • Module import whitelist only:
    • Import cost: 100 cycles on first import (+ module init cost), 5 cycles on repeated imports within the same transaction.
    • Importing a disallowed module raises ImportError and consumes 50 cycles penalty.
  • Floating-point determinism: all FP ops must use a version-locked software library; native FPU use is forbidden.
  • Big integer cap: integer bit length must not exceed 4096 bits; operations exceeding the cap raise OverflowError. Large-int costs scale with operand bit length.
  • Exception handling is explicitly metered: raising, entering try blocks, and jumping into except/finally each have base costs.
  • Async/await scheduling is single-threaded and deterministic: strict FIFO of ready coroutines; no true concurrency; no nondeterministic gather patterns.
  • Canonical serialization for messages/state: deterministic encoding with lexicographically sorted dict keys; floats serialized by exact IEEE-754 bits.

Timers and block-level budgets

Timers are delivered and executed under the CIP-5 FIFO contract:
  • The scheduler selects a bounded window from the oldest due height and keeps insertion order within that height. Natural fires share LANE_TIMER_CYCLES = 8,800,000, with a 550,000-cycle per-fire cap by default. From TIMER_FIRE_CYCLES_FOLLOW_CONFIG_ACTIVATION_HEIGHT, the cap follows the governed cip5.timer.max_cycles_per_fire, clamped to [550,000, 2,200,000] and bounded by the selected timer lane. Each fire also respects its persisted request (CIP-5 §6.2).
  • Each fire reserves its complete cycle and charged-access request before execution, subject to the native due window and aggregate budget. A non-fitting request carries forward intact. Reserved bid fields do not affect ordering or fees; natural fires pay no proposer priority tip.
  • Scheduling a timer (conceptual API) and cancellation are charged at fixed Cycle costs (see partial table above). Execution of the timer handler itself is subject to the standard cycles/cells limits of the invocation.

Failure modes and enforcement

  • Out of Cycles: the VM halts immediately; no further bytecodes execute.
  • Out of Cells: the VM halts immediately; no further I/O is performed.
  • Disallowed import: ImportError with penalty cycles charged.
  • Big integer overflow: OverflowError when results exceed the 4096-bit cap.
  • Determinism violations (e.g., attempting JIT or native FPU): forbidden by implementation and specification; clients must not diverge.

Developer guidance

  • Budgeting: estimate Cycles by dominant loops and host calls; estimate Cells by payload, storage writes, blob sizes, and return data.
  • Prefer streaming/chunked approaches for large data to stay within Cells limits.
  • Keep module usage inside the whitelist; avoid dynamic imports that may fail and waste cycles.
  • Validate numeric ranges and payload sizes early to avoid expensive partial work before hitting limits.
  • For timer-driven flows, assume best-effort delivery under a fixed per-block budget; timers may defer to subsequent blocks under congestion.

Further Reading