lightninglabs / lightninglabs/wavelength
boarding sweep: revisit finality-gated durable confirm in the reorg redesign
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 47
- Forks
- 14
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 103
Description
Since the reorg-aware txconfirm lifecycle landed, a `TxConfirmed`
delivery is provisional and the boarding-sweep durable bookkeeping (the
`boarding_sweeps` row flipping to `confirmed`, the ledger fee entry, and
the in-memory watch teardown) only commits on `TxFinalized`, which the
chain backends synthesize at `chainsource.DefaultFinalityDepth = 6`
inclusive confirmations.
To be clear about the blast radius: nothing operational gates on that
status. The sweep broadcasts immediately, the swept coins are ordinary
wallet UTXOs spendable under the wallet's own confirmation policy, and
the only consumer of the `confirmed` status is
`isTerminalSuccessSweepStatus` (the guard that stops a spurious late
`TxFailed` from rolling back already-booked accounting). What users see
is purely observability lag: `ListBoardingSweeps` reports `published`
for ~an hour on mainnet before flipping, and the ledger fee entry books
equally late. Downstream test suites also need to know about the
horizon — the lumos itests had to bump their post-broadcast mining from
3 to 6 blocks so the terminal status becomes observable at all
(lightninglabs/lumos#680).
For the upcoming reorg PR series: consider whether the durable
bookkeeping should instead commit on first confirmation and repair on
`TxReorged` (act-then-repair), rather than waiting out the full
reorg-safety horizon (wait-then-act). The general design lean elsewhere
in the daemon is to take the next action as soon as a confirmation
lands and treat reorgs as the exceptional path to recover from; the
sweep bookkeeping is currently the odd one out. If wait-then-act stays,
the finality depth should probably become configurable (regtest/test
rigs want 1-2) and the RPC could surface a distinct `finalizing` state
so the long `published` window doesn't read as a stuck sweep.
Related surfaces already reconciled to the lifecycle in #972: the
unroll subscriber maps `TxFinalized` to an idempotent confirmation
(it used to terminally fail the job) and drops best-effort `TxReorged`;
the wallet's log-only sweep subscriber treats finality as a repeat
confirmation. Whatever shape the redesign picks, those adapters and the
boarding-sweep classifier should move together.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing the boarding-sweep lifecycle around chainsource.DefaultFinalityDepth, ListBoardingSweeps, and isTerminalSuccessSweepStatus. Review the unroll and wallet sweep subscribers reconciled in #972, then compare act-then-repair with wait-then-act and the configurable finality or distinct finalizing-state options. Done means the redesign choice is implemented consistently across the classifier and adapters, with tests covering confirmation, reorg, and finality behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- backend, payments
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100