Documentation

Which transaction the next fanout step has to be, carrying the sets that transaction needs. Decided once by nextFanoutStep so that callers deciding what else to record and emitFanoutStep deciding what to post cannot disagree, and so that no caller can pair a step with sets it does not go with.

Which on-chain head datum the next fanout step will be posted against: still Closed (no partial fanout has landed yet) or already FanoutProgress. A FinalPartialFanoutTx (which burns the head tokens) is only valid once the datum is DatumFanoutProgress.

Handles inputs and converts them into StateChanged events along with Effects, in case it is processed successfully. Later, the Node will apply the events via aggregateNodeState, resulting in a new NodeState.

Reflect StateChanged events onto the NodeState aggregateNodeState. Events carrying a HeadId that does not match the current state are silently ignored, preventing cross-head state contamination during event replay. Events without a HeadId are always applied.

Maximum number of transaction ids per snapshot. This effectively limits our "block size" and ensures it does not grow arbitrarily with the backlog of pending transactions (localTxs). Only applied when requesting snapshots as a leader; followers accept larger requests, so this can change without a coordinated upgrade.

1000 was chosen from a sweep against 100/250 on sustained-load benchmarks (see hydra-clusterbenchBASELINES.md): per-round costs that scale with the backlog dominate at small caps (4.6-5.7x lower throughput at 100 with a deep backlog), while peak node memory was flat across the sweep.

Client request to init the head. This leads to an init transaction on chain, containing the head parameters.

Transition: IdleState → IdleState

Observe an init transaction and initialize parameters in an OpenState.

Transition: IdleState → OpenState

Client request to ingest a new transaction into the head.

Transition: OpenState → OpenState

Process a transaction request (ReqTx) from a party.

We apply this transaction to the seen utxo (ledger state). If not applicable, we wait and retry later. If it applies, this yields an updated seen ledger state. Then, we check whether we are the leader for the next snapshot and emit a snapshot request ReqSn including this transaction if needed.

Transition: OpenState → OpenState

The incremental action to put in the next ReqSn: a commit or a decommit, never both. A snapshot carrying both cannot be closed, since close and fanout express a single incremental action (setIncrementalActionMaybe).

A commit wins: its deposit expires on-chain, while a decommit only waits. This cannot starve the decommit, because selectNextDeposit refuses to start a *new* commit while a decommit is pending — only one already in flight can win, and that one stops being selected once it settles and leaves pendingDeposits.

Process a snapshot request (ReqSn) from party.

This checks that s is the next snapshot number and that the party is responsible for leading that snapshot. Then, we potentially wait until the previous snapshot is confirmed (no snapshot is in flight), before we apply (or wait until applicable) the requested transactions to the last confirmed snapshot. Only then, we start tracking this new "seen" snapshot, compute a signature of it and send the corresponding AckSn to all parties. Finally, the pending transaction set gets pruned to only contain still applicable transactions.

Transition: OpenState → OpenState

The deposit claimed by a retained finalized increment ($sel:finalizedCommit:CoordinatedHeadState), if any. Such a deposit only resurfaces in pendingDeposits when a rollback erased its increment, and it is settled solely by re-posting that increment (maybeRepostIncrementTx): it must never be proposed for a snapshot again (the deposited funds are already counted in the head) nor recovered (that would corrupt the L2 ledger). See #2741.

Process a snapshot acknowledgement (AckSn) from a party.

We do require that the is from the last seen or next expected snapshot, and potentially wait wait for the corresponding ReqSn before proceeding. If the party hasn't sent us a signature yet, we store it. Once a signature from each party has been collected, we aggregate a multi-signature and verify it is correct. If everything is fine, the snapshot can be considered as the latest confirmed one. Similar to processing a ReqTx, we check whether we are leading the next snapshot and craft a corresponding ReqSn if needed.

Transition: OpenState → OpenState

Client request to recover deposited UTxO.

Transition: OpenState → OpenState Client request to recover a deposit by posting a recover transaction on-chain. Works in any head state (Open, Closed, or Idle after fanout). Deposits from a previous head are never cleared from pendingDeposits on fanout, so recovery remains available after a head closes. A new head only sees its own deposits via depositsForHead, so old deposits are never accidentally ingested into L2. On-chain, the deposit validator only enforces that the deadline has passed and that the recovered outputs match the originals — it does not require the head to still be active.

Client request to decommit UTxO from the head.

Only possible if there is no decommit _in flight_ and if the tx applies cleanly to the local ledger state.

Transition: OpenState → OpenState

Reject a decommit that materializes no output. checkDecrement requires at least one, so such a decommit can never settle on-chain, and recording it would block every later snapshot (which cannot carry a different one).

Belongs after the applicability check at every call site: a transaction that does not apply is reported with the ledger's own, more precise reason.

Process the request ReqDec to decommit something from the Open head.

Transition: OpenState → OpenState

When node receives ReqDec network message it should: - Check there is no decommit in flight: - Alter it's state to record what is to be decommitted - Issue a server output DecommitRequested with the relevant utxo - Issue a ReqSn since all parties need to agree in order for decommit to be taken out of a Head. - Check if we are the leader

The pending deposit that a local $sel:currentDepositTxId:CoordinatedHeadState still refers to, if any: the deposit must be registered in pendingDeposits and not Expired.

Being registered and unexpired is what makes a recorded deposit id something the head may still act on, and nothing else should be treated as a commit in flight. Neither of the two ways a deposit stops being pending clears $sel:currentDepositTxId:CoordinatedHeadState: DepositExpired deliberately keeps the deposit in the map so it can still be recovered, and DepositRecovered only deletes the map entry. So a caller that reads $sel:currentDepositTxId:CoordinatedHeadState on its own can end up waiting on a deposit that is unclaimable, or already gone, and that wait never resolves.

Process the chain (and time) advancing in any head state.

Transition: AnyState → AnyState

This is primarily used to track deposits status changes.

Process the chain (and time) advancing in an open head.

Transition: OpenState → OpenState

This is primarily used to track deposits and either drop them or request snapshots for inclusion.

If this node is the snapshot leader and there are pending local transactions, request the next snapshot with the bumped version after a commit or decommit finalises on-chain.

Guards: * Only fires when StateChanged is ahead of the local CoordinatedHeadState: this avoids duplicate SnapshotRequestDecided events when multiple parties post the same on-chain tx and each posting produces a separate finalisation observation, and it keeps a finalization re-landing after a rollback (its StateChanged is at or behind the local version, which never rolls back) from requesting a snapshot with a stale version. * Skips when AckSns are already being collected (SeenSnapshot): the in-flight snapshot will complete and maybeRequestNextSnapshot will chain the next one with the bumped version. Firing here would use stale $sel:localTxs:CoordinatedHeadState and cause BadInputsUTxO on other parties. * Allows RequestedSnapshot: the in-flight ReqSn carries the old version and will be parked by waitOnSnapshotVersion until TTL drops it, so we re-request immediately with the new version to make progress without waiting for the stale request's retries to exhaust.

The optional StateChanged argument is forwarded into ReqSn: commit finalisation passes Nothing (deposit already included), while decommit finalisation passes the next queued deposit if one is pending.

Observe a increment transaction. If the outputs match the ones of the pending commit UTxO, then we consider the deposit/increment finalized, and remove the increment UTxO from pendingDeposits from the local state.

Finally, if the client observing happens to be the leader, then a new ReqSn is broadcasted.

Transition: OpenState → OpenState

Observe a decrement transaction. If the outputs match the ones of the pending decommit tx, then we consider the decommit finalized, and remove the decommit tx in flight.

Finally, if the client observing happens to be the leader, then a new ReqSn is broadcasted.

Transition: OpenState → OpenState

Validate whether a current deposit in the local state actually exists in the map of pending deposits.

• If currentDeposit is Nothing, returns Nothing.
• If currentDeposit is Just txId and txId is present in pendingDeposits and not Expired, returns the original currentDeposit.
• Otherwise, returns Nothing.

This is typically used to confirm that a local deposit that is to be requested in ReqSn is indeed still pending and has not been processed or removed.

Expired deposits are dropped rather than carried: requesting one makes every receiving party hard-error with RequestedDepositExpired, so a deposit that somehow became unclaimable would stall snapshots for the whole head instead of just being abandoned by its depositor.

On rollback, re-post the IncrementTx if there is a pending deposit whose confirmed snapshot contains a matching utxoToCommit. The rollback may have erased the original on-chain IncrementTx observation.

If the increment was already finalized (CommitFinalized consumed the deposit and CoordinatedHeadState may have advanced past the incrementing snapshot), fall back to the retained $sel:finalizedCommit:CoordinatedHeadState — but only when the rollback reaches strictly before its observation slot; otherwise the increment is still on chain and re-posting would only produce noise. See #2741.

On rollback, re-post the DecrementTx if there is a pending decommit whose confirmed snapshot contains a matching utxoToDecommit. The rollback may have erased the original on-chain DecrementTx observation.

If the decrement was already finalized (DecommitFinalized cleared StateChanged and CoordinatedHeadState may have advanced past the decrementing snapshot), fall back to the retained $sel:finalizedDecommit:CoordinatedHeadState — but only when the rollback reaches strictly before its observation slot. See #2741.

Client request to close the head. This leads to a close transaction on chain using the latest confirmed snaphshot of the OpenState.

Transition: OpenState → OpenState

Observe a close transaction. If the closed snapshot number is smaller than our last confirmed, we post a contest transaction. Also, we do schedule a notification for clients to fanout at the deadline.

Transition: OpenState → ClosedState

Client request to side load confirmed snapshot.

Note this is not covered by the spec as it is not reachable from an organic use of the protocol.

It must not have any effects outside of a neutral modification of the state to: * something it was before (in the case of the initial snapshot). * something it would be using side communication (in the case of a confirmed snapshot).

Besides the above, it is expected to work very much like the confirmed snapshot.

Transition: OpenState → OpenState

Observe a contest transaction. If the contested snapshot number is smaller than our last confirmed snapshot, we post a contest transaction.

Transition: ClosedState → ClosedState

Client request to fanout the whole closed head automatically. Emits a FanoutTx; the chain layer either lands a single full fanout (→ IdleState) or falls back to dynamically-chunked partial fanouts. The first observed partial fanout transitions the head to PartialFanout in AutoDrain mode, which keeps draining the rest automatically until the final (burning) step.

This node becomes the fanout driver: it transitions into PartialFanout in AutoDrain mode so that, as the chain layer chunks the fanout, this node auto-continues to completion. Other parties that merely observe the resulting partial fanout do not auto-drive (see onClosedChainPartialFanoutTx).

Transition: ClosedState → PartialFanoutState (then → IdleState once the final fanout is observed).

The state change that goes with a fanout step, for the callers that own the head state: taking the driver role, or recording the selection being distributed. Decided here once rather than in each handler.

The selection comes from the step rather than the caller, so a step can only ever be recorded against the set it actually distributes.

Post the transaction a decided NextFanoutStep calls for. The chain layer chunks a full fanout, and sizes a partial one, dynamically.

Transactions only: any accompanying state change belongs to the caller that owns the head state, via fanoutStepStateChange. That keeps this safe to call where effects can be applied but state changes cannot, as in the startup re-post in runHydraNode.

Compute the full UTxO set to be fanned out, combining snapshot utxo with utxoToCommit/utxoToDecommit based on version.

Decide the next fanout step. The multiset comparison here is the only one needed: callers pass the result on rather than re-deriving it.

Whether two UTxO sets have the same outputs (by content, as a multiset). The a == b short-circuit avoids the O(n²) multiset comparison in the common case where both arguments are the same tracked set (e.g. the auto-drain sameOutputs remaining remaining check on every observed chunk), which is exactly the large-UTxO heads partial fanout targets.

The fan-out-able UTxO of a confirmed snapshot at the given on-chain version: the snapshot UTxO plus a pending commit (if the increment landed on chain) or a pending decommit (if the decrement has not landed yet).

Given the on-chain version and a snapshot's own version, decide which of a pending commit / decommit is still to be distributed on fanout. When the increment has landed on chain (versions match) the commit was already applied (drop it) while a pending decommit still applies; otherwise the commit still applies and the decommit was already paid out. Centralises the version check shared by mkFullFanoutTx and fanoutUTxOFromSnapshot.

Build the full automatic FanoutTx from a confirmed snapshot at the given on-chain version. Shared by onClosedClientFanout and the rollback re-post in FanoutProgress (repostFanoutStep).

Client request to fan out a user-selected subset of a freshly closed head. Validates the selection is a non-empty sub-multiset (by content) of the fan-out-able UTxO, then transitions the head into PartialFanout and posts whichever step nextFanoutStep decides on: a strict subset records the selection and posts a PartialFanoutTx, while a selection covering the whole head is a full fanout and drains it automatically instead.

Transition: ClosedState → PartialFanoutState

Whether a UTxO has no outputs.

Whether the outputs of sub are a sub-multiset (by content) of sup. This mirrors how partial fanout tracks distributed UTxO by content rather than by TxIn, so a user-provided selection is validated against what is actually still in the head.

Client request to continue a selective partial fanout. Validates the selection against the current StateChanged and emits whichever step nextFanoutStep decides on, which is not always a recorded selection: one covering the whole remainder finalizes the head, or, if nothing has been distributed yet, becomes a full fanout that drains it automatically.

Transition: PartialFanoutState → PartialFanoutState

The on-chain datum implied by how much has been distributed so far: still Closed while nothing has landed, FanoutProgress once some has.

Observe a (full or final) fanout transaction, finalizing the head.

Transition: ClosedState → IdleState

Observe a partial fanout while this node is still Closed — i.e. a partial fanout this node did NOT initiate (another party did). The fanout driver moved to PartialFanout when it issued its Fanout/PartialFanout command, so this handler is only reached by passive observers.

The observer transitions into PartialFanout in AwaitingSelection mode and does not auto-drive the rest: only the driver advances the fanout. This is what makes selective partial fanout work in a multi-party head — observers must not steamroll the remaining UTxO the driver deliberately left.

Transition: ClosedState → PartialFanoutState

Observe a partial fanout while in PartialFanout. Updates the remaining and distributed sets and, depending on the current FanoutMode, either continues draining automatically (or within the active selection) or waits for the next PartialFanout command.

Transition: PartialFanoutState → PartialFanoutState

Observe the final fanout while in PartialFanout, finalizing the head with the accumulated distributed outputs plus this final batch.

Transition: PartialFanoutState → IdleState

Build the PartialFanout (FanoutProgress) head state from a closed head, carrying over the snapshot/parameters and using the given chain state, remaining and distributed UTxO and fanout StateChanged. Shared by the three Closed → FanoutProgress transitions in aggregateNodeState.

Rebuild the ClosedState from a PartialFanoutState when reverting an optimistic Closed → PartialFanout transition (see HeadFanoutReverted). $sel:readyToFanoutSent:ClosedState is restored to True because a fanout is only reachable after the head was announced ReadyToFanout.

The step this node is currently driving. Nothing while a manual fanout waits on the next selection, where nothing is pending.

Whether a posted transaction is the one a given step posts, telling a failure of the step this node is driving from one it has already moved past.

Compares the distributed set, not just the transaction shape, since two selections can both be non-final steps. By content, because naming the same outputs under other inputs is a valid way to ask for the same set.

The mode a recorded selection leaves the driver in. A selection covering the whole remainder with nothing distributed yet is not distributed as a selection at all: nextFanoutStep routes it to a full fanout and the driver auto-drains the rest, so that is the mode it has to be recorded under.

fanoutStepStateChange never pairs the two - such a step is a FullFanoutStep, recorded as HeadFanoutInitiated - so this only normalises a selection recorded before that routing existed and replayed here. Without it the re-posts (repostFanoutStep) would post the full fanout that nextFanoutStep decides on while the mode kept claiming a selection is being distributed, which is what every HeadPartiallyFannedOut then reports.

Re-post the next fanout step after a chain rollback while in FanoutProgress, so the fanout resumes instead of stalling with the rolled-back transaction gone and nothing re-posted. This mirrors the IncrementDecrement re-post on rollback (maybeRepostIncrementTx maybeRepostDecrementTx): it uses the current best-effort bookkeeping and, like those re-posts, assumes the rolled-back transactions re-appear — it does not attempt to reconstruct fanout progress across a divergent rollback (the same limitation the general rollback handling has).

Which step that is comes from currentFanoutStep, the same derivation the revert guard uses to tell this step's failure from a superseded one's.

Detect our view of the chain going out of sync and issue a NodeUnsynced event when this is the case.

Find the oldest non-empty active deposit, if any. Deposits are selected in FIFO order by their StateChanged timestamp. This mirrors the selection logic in withNextActive used by onOpenChainTick.

Select the deposit to include in the next snapshot.

Prefers a deposit already tracked in $sel:currentDepositTxId:CoordinatedHeadState (if still pending). Falls back to the oldest active deposit from pendingDeposits, but only when neither a decommit is pending nor the last confirmed snapshot already included a deposit (to avoid double-posting IncrementTx before CommitFinalized removes the deposit).

The deposits handlers of an open head may act on: scoped to the head and excluding the deposit claimed by the retained finalized increment (see finalizedDepositTxId).

The deposit blocked by a retained finalized increment of an open head, if any.

Deliberately Nothing for any other head state: an increment can only settle into an open head, so once the head closes the retained snapshot can never claim the deposit on-chain anymore. The resurfaced deposit's escape hatch is then to recover it (after its deadline) and exclude the deposited outputs from the fanout via PartialFanout — so Recover must not stay blocked after close.

Update the retained $sel:finalizedCommit:CoordinatedHeadState on (re-)observation of an increment claiming depositTxId:

• the locally confirmed snapshot claims it: retain that snapshot — only it can re-claim the deposit if a rollback erases the increment, and CoordinatedHeadState may advance past it;
• the already retained snapshot claims it: the increment re-landed (e.g. re-posted after a rollback) — re-stamp the observation slot, so a rollback of the re-landed increment still triggers a re-post;
• neither: the observation raced local snapshot confirmation (another party collected the last AckSn and posted first) — retention happens once the snapshot confirms, see the SnapshotConfirmed branch of applyEvent.

See #2741.

Update the retained $sel:finalizedDecommit:CoordinatedHeadState on (re-)observation of a decrement bumping to newVersion; the counterpart of retainFinalizedCommit. A snapshot is tied to the decrement by identity, not by merely carrying a decommit: only the decrement of that very snapshot bumps the version to exactly one past the snapshot's (with a second decommit racing, the locally confirmed snapshot may still be the previous, already settled one).

Extract the HeadId from the current HeadState, if any.

Extract the HeadId from a StateChanged event, if the event carries one. Events that do not carry a HeadId always pass through aggregateNodeState unchanged.

Inputs that are processed by the head logic (the "core"). Corresponding to each of the "shell" layers, we distinguish between inputs from the client, the network and the chain.

Off-chain state of the Coordinated Head protocol.

The main state of the Hydra protocol state machine. It holds both, the overall protocol state, but also the off-chain CoordinatedHeadState.

Each of the sub-types (OpenState, etc.) contain a black-box IdleState corresponding to the ChainEvent that has been observed leading to the state.

Note that rollbacks are currently not fully handled in the head logic and only this internal chain state gets replaced with the "rolled back to" version.

TODO: chainState would actually not be needed in the HeadState anymore as we do not persist the HeadState and not access it in the HeadLogic either.

An Open head with a CoordinatedHeadState tracking off-chain transactions.

Data structure to help in tracking whether we have seen or requested a ReqSn already and if seen, the signatures we collected already.

An Closed head with an current candidate ConfirmedSnapshot, which may be contested before the ClosedState.

How the node decides which UTxOs to distribute in the next fanout step while the head is in FanoutProgress.

A closed head whose UTxO is being distributed across multiple fanout transactions (on-chain FanoutProgress). Holds the partial-fanout bookkeeping that used to live in ClosedState.