State Machines & Event-Driven Architecture

Learning Objectives

• Understand the state machine pattern
• Learn event-driven design principles
• Explore Event and Action types in hyperscale-rs
• Understand determinism and why it matters
• See how state machines compose in hyperscale-rs

1. What is a State Machine?

Definition

A state machine is a computational model that consists of:

• States - The possible configurations of the system
• Transitions - Rules for moving from one state to another
• Inputs - Events that trigger transitions
• Outputs - Actions produced by transitions

Simple Example

Light Switch State Machine:
  States: {ON, OFF}
  Transitions:
    - If state is OFF and event is "flip" → state becomes ON
    - If state is ON and event is "flip" → state becomes OFF

Why State Machines?

• Deterministic - Same state + same event = same result
• Testable - Easy to test all state transitions
• Predictable - Behavior is well-defined
• Composable - Can combine multiple state machines

2. The StateMachine Trait

Core Interface

In hyperscale-rs, everything implements the StateMachine trait:

trait StateMachine {
    fn handle(&mut self, event: Event) -> Vec<Action>;
    fn set_time(&mut self, now: Duration);
    fn now(&self) -> Duration;
}

Key Properties

• Synchronous - No async, no .await
• Pure - No I/O, no locks, no side effects
• Deterministic - Same inputs always produce same outputs
• Simple - Just state + event → actions

Exploring the Trait

Open crates/core/src/traits.rs and find the StateMachine trait. Notice:

• It's very simple - just three methods
• The handle method takes an event and returns actions
• Time is managed explicitly (for determinism)

3. Events: What Happens

What are Events?

Events are passive data structures that describe something that happened. They flow into state machines.

Event Types

Open crates/core/src/event.rs to see all event types. Examples:

enum Event {
    // Timers
    ProposalTimer,
    CleanupTimer,

    // Network Messages
    BlockHeaderReceived { header: BlockHeader, .. },
    BlockVoteReceived { vote: BlockVote },

    // Internal Events
    QuorumCertificateFormed { block_hash: Hash, qc: QuorumCertificate },
    BlockCommitted { block_hash: Hash, .. },

    // ... many more
}

Event Sources

• Network - Messages from other validators
• Timers - Scheduled events (e.g., proposal timer)
• Internal - Generated by other state machines
• Client - User-submitted transactions

Event Priority

Events at the same timestamp are processed by priority:

1. Internal (0) - Consequences of prior processing
2. Timer (1) - Scheduled timers
3. Network (2) - External messages
4. Client (3) - User submissions

4. Actions: What to Do

What are Actions?

Actions are commands that describe what the state machine wants to do. They flow out of state machines and are executed by runners.

Action Types

Open crates/core/src/action.rs to see all action types. Examples:

enum Action {
    // Network
    BroadcastToShard { shard: ShardGroupId, message: OutboundMessage },
    BroadcastStateVote { shard: ShardGroupId, vote: StateVoteBlock },

    // Timers
    SetTimer { id: TimerId, duration: Duration },

    // Internal
    EnqueueInternal { event: Event },

    // Storage
    CommitBlock { block: Block, qc: QuorumCertificate },

    // ... many more
}

Action Execution

Actions are executed by runners:

• SimulationRunner - Deterministic simulation
• ProductionRunner - Real networking, storage, async

5. Event-Driven Flow

The Flow

1. Runner receives network message
2. Runner creates Event::BlockHeaderReceived
3. Runner calls state_machine.handle(event)
4. State machine processes event, updates state
5. State machine returns Vec<Action>
6. Runner executes actions (send network, store, etc.)
7. Actions may generate new events
8. Loop continues...

Example: Block Proposal Flow

1. Timer fires → Event::ProposalTimer
2. State machine handles → Checks if this node is proposer
3. If proposer → Builds block, returns Action::BroadcastToShard
4. Runner executes → Sends block header to network
5. Other nodes receive → Create Event::BlockHeaderReceived
6. They vote → Return Action::BroadcastToShard (vote)
7. Votes collected → Event::QuorumCertificateFormed
8. QC processed → Chain state updated (latest_qc), commit rule checked (Module 1.2; bft crate)

6. Determinism: Why It Matters

What is Determinism?

Deterministic means: given the same initial state and same sequence of events, you always get the same final state and same sequence of actions.

Why Determinism Matters

• Testing - Can reproduce bugs exactly
• Debugging - Can replay execution step-by-step
• Simulation - Can test in controlled environment
• Consistency - All nodes produce same results

What Breaks Determinism?

• ❌ Random number generation (without seed)
• ❌ System time (use explicit time parameter)
• ❌ Network timing (simulate with delays)
• ❌ Thread scheduling (single-threaded in state machine)

How Hyperscale-rs Maintains Determinism

• ✅ Explicit time parameter (set_time)
• ✅ No random number generation in state machine
• ✅ Synchronous execution (no async in state machine)
• ✅ Deterministic event ordering (priority system)

7. Composing State Machines

NodeStateMachine

The NodeStateMachine composes multiple sub-state machines:

NodeStateMachine
├── BftState          (consensus)
├── ExecutionState    (transaction execution)
├── MempoolState      (transaction pool)
├── ProvisionCoordinator (cross-shard coordination)
└── LivelockState     (deadlock prevention)

How They Compose

1. NodeStateMachine receives an event
2. Routes event to appropriate sub-state machines
3. Each sub-state machine processes the event
4. Actions from all sub-machines are collected
5. Sub-machines can generate internal events for each other

Exploring Composition

Open crates/node/src/state.rs and find the handle method. Notice how it:

• Routes events to different sub-machines
• Collects actions from all sub-machines
• Coordinates between sub-machines

8. Knowledge Check Quiz

9. Practical Assignment