> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.lat/llms.txt
> Use this file to discover all available pages before exploring further.

# Minimal Actor

> Example of creating a minimal Actor

# 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.

```python theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Actor VM Overview" icon="microchip" href="/architecture/actor-vm/overview">
    Learn the execution model and guarantees
  </Card>

  <Card title="Resource Limits" icon="gauge" href="/architecture/actor-vm/resource-limits">
    Understand limits and metering
  </Card>
</CardGroup>

## Further Reading

* [Actor VM Overview](/architecture/actor-vm/overview)
* [Determinism & Sandbox](/architecture/actor-vm/determinism-and-sandbox)
* [Resource Limits](/architecture/actor-vm/resource-limits)