Module fsm 

Transaction Finite State Machine (FSM)

Formal state machine modeling the lifecycle of a TAP transaction from initiation through authorization to settlement. Each state transition is driven by an incoming TAP message and may require an external decision before the node takes action.

States

                         ┌──────────────────────────────────────────┐
                         │         Transaction Lifecycle            │
                         └──────────────────────────────────────────┘

  ┌─────────┐  Transfer/   ┌──────────────┐  UpdatePolicies/  ┌─────────────────┐
  │         │  Payment     │              │  RequestPresent.  │                 │
  │  (none) │─────────────▶│   Received    │─────────────────▶│ PolicyRequired  │
  │         │              │              │                   │                 │
  └─────────┘              └──────┬───────┘                   └────────┬────────┘
                                  │                                    │
                             ┌────┴─────┐                    Presentation
                             │ DECISION │                    received
                             │ Authorize│                         │
                             │ Reject   │◀────────────────────────┘
                             │ Cancel   │
                             └────┬─────┘
                   ┌──────────────┼──────────────┐
                   │              │              │
               Authorize       Reject         Cancel
                   │              │              │
                   ▼              ▼              ▼
           ┌──────────────┐ ┌──────────┐ ┌───────────┐
           │  Authorized  │ │ Rejected │ │ Cancelled │
           │ (per agent)  │ │          │ │           │
           └──────┬───────┘ └──────────┘ └───────────┘
                  │
           all agents authorized?
                  │ yes
                  ▼
           ┌──────────────────┐
           │ ReadyToSettle    │
           │                  │
           └────────┬─────────┘
                    │
               ┌────┴─────┐
               │ DECISION │
               │ Settle   │
               │ Cancel   │
               └────┬─────┘
                    │
                 Settle
                    │
                    ▼
             ┌─────────────┐
             │  Settled    │
             └──────┬──────┘
                    │
                 Revert?
                    │
                    ▼
             ┌─────────────┐
             │  Reverted   │
             └─────────────┘

Decision Points

The FSM identifies two categories of transitions:

• Automatic: The node processes the message and moves to the next state with no external input (e.g., storing a transaction, recording an authorization).

• Decision Required: The transition produces a Decision that an external system must resolve before the node takes further action. For example, when a Transfer arrives the node must decide whether to Authorize, Reject, or request more information via policies.

Per-Agent vs Per-Transaction State

A transaction has a single top-level TransactionState, but also tracks per-agent authorization status via AgentState. The transaction advances to ReadyToSettle only when all agents reach Authorized.

Structs

AutoApproveHandler

Decision handler that automatically approves all decisions.

InvalidTransition

Error returned when an invalid transition is attempted.

LogOnlyHandler

Decision handler that only logs decisions without taking action.

TransactionContext

The in-memory state of a single transaction tracked by the FSM.

TransactionFsm

Pure-logic FSM engine for TAP transactions.

Transition

The outcome of applying an event to the FSM.

Enums

AgentState

Authorization state of an individual agent within a transaction.

Decision

A decision that an external system must make before the FSM can advance.

DecisionMode

Controls how the node handles decision points during transaction processing.

FsmEvent

An event that can trigger a state transition in the FSM.

TransactionState

Top-level state of a TAP transaction.

Traits

DecisionHandler

Trait for handling FSM decision points.