Skip to main content

​
Minimal Actor

Here’s an example of a minimal Actor…
Note: Examples on this page are conceptual snippets/pseudocode. Final interfaces and usage should follow the SDK and Developer Guide; CIP specifications define normative protocol behavior. 
# Conceptual minimal actor (pseudocode)
class MinimalActor:
    def handle(self, msg):
        return {"status": "ok", "input": msg}

​
Core Concepts

​
State and Initialization

Actors may keep ephemeral in-memory variables during a single invocation, but persistent state MUST use the protocol storage APIs; costs are metered in Cells per CIP-3.

​
Message Handlers

Handlers should be small, deterministic, and idempotent where possible. When state changes are required, use the protocol storage APIs; avoid relying on implicit container iteration order (CIP-3 requires sorted keys during serialization).

​
Persistent Storage

Use the protocol’s deterministic storage APIs to persist key/value data. Storage reads/writes are metered at I/O boundaries in Cells per CIP-3; design data layouts and batching accordingly.

​
Timers (Scheduling)

For periodic or delayed execution, use the protocol-native timer mechanism defined in CIP-1. Timers are scheduled and later executed under a bounded per-block budget; actors specify a Gas Bidding Agent (GBA) to price execution when due.

​
Messaging (Asynchronous)

Actors communicate via asynchronous messages. Compose systems by sending messages to other actors and handling their replies; avoid synchronous assumptions about execution order.

​
Errors and Limits (Cycles/Cells)

Validate input sizes and execution paths to respect resource limits. Computation is metered in Cycles; data movement and storage are metered in Cells (CIP-3). Fail fast on invalid data and unbounded loops.

​
Determinism Checklist

  • No file/network/system calls
  • No local randomness or system time
  • Pure interpretation (no JIT)
  • Use protocol storage/messaging/timers only

​
Minimal Flow (End-to-End)

  1. Read required state via protocol storage APIs.
  2. Perform deterministic processing under Cycles/Cells limits.
  3. Optionally schedule a follow-up via the CIP-1 timer mechanism (with a GBA).
  4. Return results; serialization is deterministic (e.g., dict keys sorted per CIP-3).

​
Best Practices

  • Keep handlers small and deterministic
  • Validate input sizes; fail fast on invalid data
  • Prefer batching writes to reduce Cells
  • Avoid unnecessary string/collection allocations
  • Use timers for periodic tasks instead of loops

​
Next Steps

Actor VM Overview

Learn the execution model and guarantees

Resource Limits

Understand limits and metering

​
Further Reading