Head closed with sub-min-ADA (dust) outputs can never be fanned out — stuck in Closed with H39

[v0d1ch]

Context & versions

• hydra-node on master .
• Head configured with L2 --ledger-protocol-parameters where utxoCostPerByte = 0 (the zero-fee setup suggested by the tutorial). The L2 ledger consequently accepts outputs below L1 min-ADA, e.g. token-only or tiny-lovelace outputs.
• L1 with standard protocol parameters (coinsPerUTxOByte = 4310).

Steps to reproduce

1. Open a head with utxoCostPerByte = 0 in the L2 ledger parameters.
2. Submit an L2 NewTx creating an output below L1 min-ADA (e.g. 100 000 lovelace) — the snapshot confirms fine.
3. Close the head, wait for the contestation deadline, then Fanout.

Actual behavior

Every fanout attempt fails locally with ScriptFailedInWallet and head validator error H39 FanoutUTxOHashMismatch — the transaction is never submitted. The head stays in Closed indefinitely and funds are locked: a sub-min-ADA output can never exist on L1, so not even partial fanout can finalize the head, and the head tokens plus ada overhead remain locked as well.

ScriptFailedInWallet, redeemerPtr = ConwaySpending (AsIx 0)
CekError: The machine terminated because of an error ... ["H39","PT5"]

The root cause has two layers:

1. An output below L1 min-ADA cannot be an output of any valid L1 transaction, so a head closed in this state is unfannable by construction.
2. It surfaces as a confusing H39 instead of an honest OutputTooSmallUTxO because of the internal wallet: coverFee_ applies ensureMinCoinTxOut to all transaction outputs before running script estimation (Hydra.Chain.Direct.Wallet.coverFee_), silently bumping the dust output to min-ADA (100 000 → ~849 070 for a simple payment address). The bumped output no longer matches the accumulator commitment that the parties signed in the snapshot and that is stored in the closed datum, so the fanout membership check fails on every retry.

Expected behavior

• The node prevents accidentally closing a head whose UTxO cannot be fanned out on L1: SafeClose refuses to close (the API schema already advertises a pre-close safety check, but it currently only covers non-ADA assets), and plain Close at least emits a warning listing the offending outputs. The checks must run against L1 protocol parameters: per-output min-ADA, closing value covered by the head output, per-output size.
• The internal wallet does not silently mutate outputs of hash-committed protocol transactions — failing loudly would surface the real error (OutputTooSmallUTxO) instead of a misleading script failure.

[v0d1ch]

Proposed solution

Guard the close path so a head cannot be (accidentally) closed when its snapshot UTxO is not distributable on L1. SafeClose hard-blocks, Close proceeds with a warning. All checks run in the chain layer against fresh L1 protocol parameters (getPParams on the internal wallet), where the head output on L1 is also known.

Behavior

• ClientInput SafeClose → close is not posted if any check fails; head stays Open; clients receive PostTxOnChainFailed with a new structured error listing offending outputs.
• ClientInput Close → close is posted as today, but a new PostTxOnChainWarning server output is broadcast first with the same payload.
• Checks on the UTxO the close would commit to fanning out (version-dependent set: utxo ± utxoToCommit/utxoToDecommit):
  a. Min-ADA: each output's lovelace ≥ calculateMinimumUTxO with L1 pparams (catches dust created under L2 utxoCostPerByte = 0).
  b. Value conservation: closing value must be covered by the head output value on L1, modulo the lovelace-only headAdaOverhead (catches tokens minted/burned on L2 — mirror of on-chain H4).
  c. Size sanity: each output fits an L1 tx (maxValSize / maxTxSize bound).

Changes

Types (hydra-node/src/Hydra/Chain.hs)

• data CloseGuard = EnforceFanoutable | WarnOnly; new field closeGuard on CloseTx.
• data FanoutIssue = OutputBelowMinAda {txIn, providedValue, minimumValue} | OutputTooLarge {txIn, serializedSize, maximumSize} | ValueNotCoveredByHead {missingValue} | TokensNotDistributable {leftoverValue}.
• PostTxError gains CloseUTxONotFannableOnL1 {fanoutIssues :: [FanoutIssue]}.
• ChainEvent gains PostTxWarning {postChainTx, postTxWarning}; ClientMessage gains PostTxOnChainWarning mirroring PostTxOnChainFailed.
• Remove the checkNonADAAssets field from the Chain handle (superseded, see below).

Fanout set (hydra-tx/src/Hydra/Tx/Close.hs)

• Extract the version-dependent utxoInHead table from closeTx into an exported utxoInHeadAtClose :: IncrementalAction -> SnapshotVersion -> ConfirmedSnapshot Tx -> UTxO, reused by closeTx and the new check (keeps guard and on-chain commitment in sync).

Check + wiring (hydra-node/src/Hydra/Chain/Direct/Handlers.hs)

• checkCloseFannableOnL1 :: PParams LedgerEra -> PolicyId -> Value -> UTxO -> [FanoutIssue] next to rejectLowDeposits (same calculateMinimumUTxO pattern, but collecting all offenders).
• mkChain gains the ChainCallback parameter (already in scope at both call sites; Blockfrost reuses mkChain, so parity is free). New explicit CloseTx case in postTx (like the existing InitTx case, since getPParams needs IO): run checks → EnforceFanoutable ⇒ throwIO (CloseUTxONotFannableOnL1 …); WarnOnly ⇒ callback PostTxWarning{…} and continue. Head output located via headIdToPolicyId + utxoOfThisHead (as in close); if absent, skip (fails later as today).

HeadLogic / API

• onOpenClientClose takes the guard: Close → WarnOnly, SafeClose → EnforceFanoutable; new input case maps ChainInput PostTxWarning → ClientEffect PostTxOnChainWarning (no state change).
• Remove the current SafeClose intercept in WSServer.receiveInputs (single-connection, check-time/post-time race) together with checkNonADAAssetsUTxO — the non-ADA concern is subsumed by the value-conservation check.
• api.yaml: closeGuard on CloseTx, new CloseUTxONotFannableOnL1 + FanoutIssue schemas, new PostTxOnChainWarning message, and rewritten SafeClose/Close descriptions (replaces the "no non-ADA assets" contract).

Tests

• HandlersSpec: pure cases for checkCloseFannableOnL1 (dust / clean / L2-minted asset / leftover token / overhead tolerated / oversized) and postTx behavior with a mocked wallet (Enforce throws + no submit; Warn emits callback + submits).
• HeadLogicSpec: Close/SafeClose routing; PostTxWarning → PostTxOnChainWarning.
• e2e (hydra-cluster): open head with the devnet L2 params (utxoCostPerByte: 0), NewTx paying 100 000 lovelace, expect SafeClose rejection, then Close warning + HeadIsClosed (devnet L1 has effective coinsPerUTxOByte = 4310, so this reproduces).
• No golden regeneration needed (PostChainTx/PostTxError/ClientMessage have no golden files; schema prop-tests cover api.yaml).

Out of scope / follow-ups

• Wallet fix: coverFee_ silently bumping sub-min outputs via ensureMinCoinTxOut (which turns this situation into a misleading H39 at fanout time) — should fail loudly or leave protocol tx outputs untouched; needs an audit of paths relying on the bump.
• Same dust problem exists for decommit (decrement outputs are only validated against the L2 ledger).
• Recovering an already-closed head in this state is not addressed here.