Learn State Machines
Master Ottochain State Machines
State machines are powerful tools for modeling automated workflows on the blockchain. Learn the core concepts, understand advanced features, and build your own state machines.
🤖Train an AI to Help You Build State MachinesCore Concepts
Click on each concept to learn more about how state machines work
What is a State Machine?
A state machine models a workflow as a series of states and transitions
A state machine is a computational model that represents a system moving through different states based on events. Think of it like a flowchart where: • **States** represent different stages in a process (e.g., "Pending", "Approved", "Rejected") • **Transitions** are the arrows between states, triggered by events • **Events** are actions that cause the machine to move from one state to another For example, an approval workflow might start in "Pending", move to "Under Review" when a reviewer looks at it, then finally to either "Approved" or "Rejected" based on the reviewer's decision.
Example Structure
{
"states": {
"Pending": { "isFinal": false },
"UnderReview": { "isFinal": false },
"Approved": { "isFinal": true },
"Rejected": { "isFinal": true }
},
"initialState": "Pending",
"transitions": [
{ "from": "Pending", "to": "UnderReview", "event": "StartReview" },
{ "from": "UnderReview", "to": "Approved", "event": "Approve" },
{ "from": "UnderReview", "to": "Rejected", "event": "Reject" }
]
}State Data
Each state machine instance can store and track custom data
Guards
Conditions that must be true for a transition to occur
Effects
Actions that modify state data when a transition occurs
Events
Messages that trigger transitions and carry data
Cross-Machine Dependencies
Access and coordinate with other state machines in your workflow
Context & Variables
Understanding what data is available in guards and effects
Oracles
External computation units that can be called by state machines
Advanced Features
Take your state machines to the next level with these powerful capabilities
Self-Transitions
Stay in the same state while accumulating data or incrementing counters
Multiple Guards on Same Event
Branch to different states based on conditions from the same event
Triggers
Send events to other state machines when transitions occur
Spawns
Dynamically create child state machines during transitions
Outputs
Emit structured data for external systems (webhooks, logs, etc.)
Oracle Calls
Invoke oracle methods from effects with results stored in state
Best Practices & Next Steps
✅Best Practices
Keep Guards Deterministic
Same inputs should always produce the same output. Avoid time-dependent or random conditions.
Use Meaningful State Names
Choose clear names like "pending_approval" instead of "state_1".
Mark Final States Correctly
Set isFinal: true for terminal states to prevent further transitions.
Always Include idempotencyKey
Even if null, this field is REQUIRED in ProcessFiberEvent or signature validation will fail.
Start Effects with Current State
Use merge with { "var": "state" } to preserve existing data.
Avoid Circular Dependencies
Be careful with triggers - machine A triggering B, which triggers A again, causes infinite loops.
🎓Recommended Learning Path
Start with Examples
Visit the Approval Workflow Example to see a simple state machine in action.
Try the Playground
Switch to Playground mode and create your first state machine on the live blockchain.
Study Advanced Examples
Check out Fuel Logistics to see cross-machine dependencies and GPS tracking.
Use the Sign Tool
Go to /sign to craft and submit your own custom state machines.
Learn JSON Logic
Visit jsonlogic.com to master guards and effects.
🎯Common Patterns Quick Reference
Simple Approval Flow
draft → submitted → approved/rejected
Use: Basic workflows with binary outcomes
Multi-Stage Pipeline
stage1 → stage2 → stage3 with gates
Use: Sequential processes with validation checkpoints
Coordinated Machines
Contract depends on Supplier + GPS + Quality
Use: Complex workflows requiring multiple dependencies
Data Accumulation
tracking → tracking (self-transition)
Use: Logging, counters, building arrays
Conditional Branching
One event → multiple states based on guards
Use: Quality checks, score-based routing
Event Cascades
Transition triggers events on other machines
Use: Notification workflows, task spawning