Documentation

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 $sel:pendingDeposits:NodeInSync.

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

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 $sel:pendingDeposits:NodeInSync 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 $sel:pendingDeposits:NodeInSync 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 'version /= newVersion' to avoid duplicate SnapshotRequestDecided events when multiple parties post the same on-chain tx and each posting produces a separate finalisation observation. * 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 $sel:pendingDeposits:NodeInSync 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 $sel:pendingDeposits:NodeInSync 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.

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.

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

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

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

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.

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, transitions the head into PartialFanout (in DistributingSelection mode) and emits the first PartialFanoutTx.

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.

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.

Emit the next partial fanout on-chain effect.

• When the chunk source target covers the entire remaining set and the head is already in FanoutProgress on chain, emit the final FinalPartialFanoutTx that distributes the rest and burns the head tokens.
• Otherwise emit a non-final PartialFanoutTx drawing from target. The chain layer sizes the actual on-chain chunk dynamically.

Client request to continue a selective partial fanout. Validates the selection against the current StateChanged, records it as the active selection and emits the next step.

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

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

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.

Whether a PostChainTx is one of the fanout-posting transactions (used to scope the optimistic-fanout revert to genuine fanout post failures).

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

distributedOutputs being empty means no partial fanout has landed on chain yet (the head datum is still Closed); otherwise the datum is FanoutProgress and a FinalPartialFanoutTx is possible.

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 $sel:pendingDeposits:NodeInSync, 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).

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.

An Idle head only having a chain state with things seen on chain so far.

Get the chain state in any HeadState.

Whether AckSns are currently being collected for a snapshot. Unlike snapshotInFlight, returns False for RequestedSnapshot — a snapshot sent but not yet echoed is stale once the version bumps and should not block a fresh request with the new version.

Smart constructor for SeenSnapshot that computes and caches $sel:signableBytes:NoSeenSnapshot from $sel:snapshot:NoSeenSnapshot, enforcing the invariant that they stay in sync.

Get the last seen snapshot number given a SeenSnapshot.

Update the chain state in any HeadState.

Whether a snapshot is currently in-flight (requested or being signed).

Analogous to inputs, the pure head logic "core" can have effects emitted to the "shell" layers and we distinguish the same: effects onto the client, the network and the chain.