round: wire round-born VTXOs to the batch-canonicality gate (C6)

[ellemouton]

C6 — Wire round-born VTXOs to the batch-canonicality gate

Part of the reorg-safety epic (lightninglabs/darepo#454). Stacked on the C5
availability gate (#796).

What this does

When a round's commitment tx confirms and the client materializes its owned
VTXOs, the round actor registers the batch with the BatchCanonicalityManager
(RegisterBatchRequest carrying the batch txid, consumed inputs = boarding
outpoints + forfeited VTXO outpoints, dependent VTXOs = round-born VTXO
outpoints, the batch confirmation pkScript, and the CSV expiry delta). The C5
gate (dormant until producers register batches) then governs those VTXOs:
a reorg-out or input double-spend excludes them from coin selection until the
batch is canonical again. The consumed-input set also seeds the manager's
reorg-aware spend watches, underpinning forfeited-VTXO restore (F6).

Registration is gated behind an optional RoundClientConfig.BatchCanonicality
ref — None keeps the gate dormant and preserves pre-C6 behavior, so existing
hosts/tests are unaffected.

Unlocks acceptance F2/F3 (round-born VTXO reorg → limbo → usable / input
conflict → unavailable) and sets up F6 (forfeit-into-invalidated-round
restore).

Foundation commit

The first commit (round: gate commitment-tx terminal transition on finality)
is cherry-picked from #558 — it makes the round commitment watch
reorg-aware and gates the terminal transition on finality, which C6 builds on.
It is the interim home; #558 should drop it (or stack on C6) to avoid the
duplicate at merge time.

F1 (pre-commitment input gate): safety already holds; proactive abort deferred

F1's safety ("a round must not complete using a double-spent boarding input")
is already structurally guaranteed: an unconfirmed commitment never reaches
Confirmed and so never materializes VTXOs, and the reorg-aware finality gate
never finalizes a reorged/never-confirming commitment. The remaining value is
proactive abort (fail fast instead of waiting for the registration timeout) —
a liveness optimization. At InputSigSent the client is past the point of no
return, so a forced FSM abort from an async spend event is intricate for
marginal gain; this is deferred as a focused follow-up, consistent with the
codebase's current detection-only reorg posture.

Activation (darepod) — deferred

Like C5, the round gate ships dormant. Constructing/starting the canonicality
manager and threading the store/ref to the vtxo + round actors is the
integration step that ties #795 + #796 + C6/C7/C8 together and needs the daemon
harness to validate.

Tests

Unit tests cover the populated RegisterBatchRequest, the dormant no-op when
unwired, and the skip for an empty batch. End-to-end F2/F3/F6 land as client
systests in the acceptance pass.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a reorg-safety mechanism by gating the round FSM's terminal transition on commitment finality rather than the first provisional confirmation. It adds a cache for provisional confirmation events, wires reorg-aware lifecycle refs to detect reorgs and finality, and registers confirmed batches with a canonicality manager to track consumed inputs and dependent VTXOs. Feedback on these changes highlights a potential memory leak where pendingCommitmentConfs and commitmentTxIndex are not cleaned up when rounds are cancelled or reaped.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Memory / State Leak on Failed or Cancelled Rounds

While pendingCommitmentConfs is correctly cleaned up on successful finalization in handleCommitmentFinalized, there is currently no cleanup of this map (or commitmentTxIndex) when a round is cancelled via handleCancelRound or reaped via reapFailedRounds.

If a round fails or is cancelled after receiving a provisional confirmation but before finalization, the cached confirmation event will remain in pendingCommitmentConfs indefinitely, leading to a memory leak. Additionally, for cancelled rounds, the TxID is never deleted from commitmentTxIndex because handleCancelRound deletes the round from a.rounds immediately, preventing reapFailedRounds from ever seeing and cleaning it up.

Suggested Fix:

1. In reapFailedRounds, delete the entry from pendingCommitmentConfs:

   delete(a.pendingCommitmentConfs, roundFSM.TxID)

2. In handleCancelRound, ensure both commitmentTxIndex and pendingCommitmentConfs are cleaned up:

   delete(a.commitmentTxIndex, targetFSM.TxID)
   delete(a.pendingCommitmentConfs, targetFSM.TxID)

[ellemouton]

Superseded by #896 as part of condensing the reorg-safety client stack (epic lightninglabs/darepo#454) from 12 PRs into 3. The commits are carried over unchanged; see #896. Branch retained as a backup.