Skip to content

peer+chancloser: buffer RBF close bumps in FSM and tear down on CloseFin - #11575

Open
Roasbeef wants to merge 6 commits into
lightningnetwork:masterfrom
Roasbeef:rbf-coop-close-lifecycle
Open

Roasbeef wants to merge 6 commits into
lightningnetwork:masterfrom
Roasbeef:rbf-coop-close-lifecycle

Conversation

@Roasbeef

@Roasbeef Roasbeef commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Change Description

In this PR, we resolve #11571 and #11488 by moving RBF cooperative close bump serialization and buffering directly into the RbfChanCloser state machine and unifying CloseFin channel+link teardown under a single per-closer lifecycle observer.

Previously, startRbfChanCloser inspected CurrentState() out of band and branched on it: bumps arriving in ShutdownPending or ChannelFlushing fell through to a warning log and were silently dropped, while bumps in ClosingNegotiation blocked the peer's channelManager goroutine inside waitUntilRbfCoastClear using the peer's lifetime context rather than the caller's, stalling other peer operations (and hanging forever in LocalCloseStart, CloseErr, or LocalOfferSent without a peer reply).

We eliminate waitUntilRbfCoastClear and the CurrentState() switch entirely. Instead, startRbfChanCloser sends a single non-blocking LocalCloseReq event into the state machine, which every state handles deterministically:

  • In ShutdownPending and ChannelFlushing, an incoming bump is buffered in PendingBump and applied as soon as ChannelFlushed fires (transitioning into CloseErr if an explicit bump exceeds local balance, while preserving LocalCloseStart when an unpayable initial close waits for the remote party).
  • In LocalOfferSent, a bump is buffered in PendingOffer and emitted as an internal SendOfferEvent right after LocalSigReceived completes the active round and updates RemoteCloseeNonce for taproot channels.
  • In LocalCloseStart, ClosePending, and CloseErr, LocalCloseReq triggers a new offer right away.

If an RPC caller cancels before a buffered bump starts, observeRbfCloseUpdatesWithSeq emits a sequence-tagged CancelPendingOffer so only that unstarted request is retracted. When maybeNotifyTxBroadcast reports a CloseErr, the observer exits right away instead of lingering until context cancellation. On fatal FSM errors, chanErrorReporter.ReportError retires the failed closer from activeChanCloses and aborts waiting callers in activeCloseReqs with the FSM error before re-initializing, and startRbfChanCloser checks closer pointer identity and liveness (isSameLiveRbfCloser) so a caller cannot bind to a stopped or replaced closer.

For #11488, we add Done() on protofsm.StateMachine and generalize chanFlushEventSentinel into rbfCloserLifecycleSentinel, registered before the state machine starts in initRbfChanCloser. Once CloseFin is reached (whether locally initiated, remote initiated, or restored), the sentinel retires the closer from activeChanCloses, delivers success to any waiting RPC callers, and calls WipeChannel to remove the channel from activeChannels and stop its link in the switch.

Steps to Test

go test -race -count=1 ./protofsm/... ./lnwallet/chancloser/... ./peer/...
make itest icase="rbf coop close"
make itest-only icase="coop close rbf with reorg"

Fixes #11571
Fixes #11488

In this commit, we add a Done() method to StateMachine that returns its internal quit channel. Downstream observers and lifecycle sentinels can now select on Done() so they exit promptly when the state machine stops instead of waiting on a peer disconnect.
In this commit, we add LocalCloseReq and CancelPendingOffer events to the RBF cooperative close state machine so local close and fee bump requests are valid in every state without out-of-band state polling.

Requests arriving in ShutdownPending or ChannelFlushing are buffered as PendingBump and applied as soon as ChannelFlushed fires, ensuring explicit fee bumps that exceed local balance transition into CloseErr rather than silently skipping. Requests arriving while LocalOfferSent awaits the remote party's signature are buffered as PendingOffer and emitted immediately after LocalSigReceived completes the round and refreshes any taproot closee nonce. If a caller cancels before a buffered bump starts, CancelPendingOffer retracts only the matching sequence.
In this commit, we remove waitUntilRbfCoastClear and the CurrentState switch from startRbfChanCloser, sending LocalCloseReq directly into the RBF state machine so the peer's channelManager goroutine never blocks on a remote-controlled close state or ignores caller cancellation (fixing lightningnetwork#11571).

We also generalize chanFlushEventSentinel into rbfCloserLifecycleSentinel, registered before the state machine starts, so every RBF closer tears down its router endpoint, RBF actor, activeChannels entry, and switch link once CloseFin is reached for both local and remote-initiated closes (fixing lightningnetwork#11488).
In this commit, we have maybeNotifyTxBroadcast return whether it reported a CloseErr so observeRbfCloseUpdatesWithSeq exits immediately instead of lingering until RPC cancel and emitting a late CancelPendingOffer. We also extract shared helpers for pending close buffering and LocalCloseStart transitions.
@github-actions github-actions Bot added the ci-hold CI is held; remove this label to run CI label Nov 13, 2026
In this commit, we update chanErrorReporter.ReportError to retire the failed closer from activeChanCloses and abort any callers in activeCloseReqs with the FSM error before re-initializing a replacement closer, preventing waiting RPC callers from hanging when observeRbfCloseUpdatesWithSeq exits on Done(). We also check closer pointer identity and liveness in startRbfChanCloser's post-add recheck so a caller cannot bind to a stopped or replaced closer.
In this commit, we add the release note fragment for PR lightningnetwork#11575 covering the RBF cooperative close bump buffering and CloseFin teardown fixes.

@litbot-9000 litbot-9000 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/gateway review

Approve. This is a substantial FSM/concurrency change and it holds up under close reading. The two core problems are genuinely gone, by construction rather than by patch-over:

  • No more channelManager stall: waitUntilRbfCoastClear and the out-of-band CurrentState() switch are deleted outright. LocalCloseReq is now a first-class event valid in every state, so a bump in ShutdownPending/ChannelFlushing buffers as a Seq-tagged PendingBump (applied on ChannelFlushed, preferred over the ideal fee rate), a bump in LocalOfferSent buffers as PendingOffer (emitted as an internal SendOfferEvent right after LocalSigReceived completes the round), and LocalCloseStart/ClosePending/CloseErr act immediately.
  • Unified CloseFin teardown: the lifecycle sentinel retires the closer from activeChanCloses, delivers success, then WipeChannels — in that order, so a concurrent caller can't register after takeAll and strand. The new protofsm.StateMachine.Done() plus p.cg.Done() give the sentinel clean exits, and the flush hook is registered with the peer-lifetime context (consistent with the hook lifetime semantics from #11483).

Edges I checked specifically: taproot RemoteCloseeNonce is updated from the completing round's ClosingSig before a buffered offer is emitted, so the next offer uses the fresh nonce; CancelPendingOffer retracts only a Seq-matching unstarted bump; ReportError captures the chanPoint and aborts waiting callers with the FSM error before re-initializing, and isSameLiveRbfCloser prevents binding to a stopped/replaced closer.

Verified by execution: go test -race -count=1 ./protofsm/... ./lnwallet/chancloser/... ./peer/... — all green with the race detector. The nine new tests map to the PR's claims (buffering across states, restored-shutdown bump, channelManager staying free, caller-cancel retraction, CloseFin teardown, CloseErr no-leak, ReportError answering callers, identity guard). Mutation check: disabling the PendingBump buffering fails TestRbfLocalCloseReqBuffering, so the coverage bites. gofmt/vet clean; the long lines are all nolint:ll-approved. Release note present.

Not verified: itests (no Docker here) — the two make itest cases in the PR's test plan are CI-covered.

Note: the failing "CI result" check is the ci-hold label on this PR, not the code.

— claudell ⚡ (OpenClaw dev agent; approval posts as litbot-9000 and does not count toward branch protection)

@Amirhosein Amirhosein left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Walked through the FSM transitions and peer lifecycle changes and ran go test -race -count=1 ./protofsm/... ./lnwallet/chancloser/... ./peer/... locally. The in-FSM buffering and CloseFin sentinel cleanup look really clean.

A few small questions on peer/brontide.go in case these edge cases matter:

  • startRbfChanCloser (peer/brontide.go:5069-5091): I see coopCloseStates := rbfCloser.RegisterStateEvents() (L5050) is registered before SendEvent so fast transitions aren't missed, which makes sense. If req.Ctx is already cancelled when startRbfChanCloser runs, could spawning observeRbfCloseUpdatesWithSeq (L5072) before rbfCloser.SendEvent(sendCtx, &chancloser.LocalCloseReq{..., Seq: bumpSeq}) (L5087) let the observer hit <-closeReq.Done() and send CancelPendingOffer{Seq: bumpSeq} before SendEvent runs? Since StateMachine.SendEvent selects between s.events <- event (buffered size 1) and <-ctx.Done(), it looks like SendEvent could still enqueue LocalCloseReq after CancelPendingOffer was already processed as a no-op.
  • chanErrorReporter.ReportError (peer/brontide.go:4606-4646): Pulling activeChanCloses.LoadAndDelete(c.chanID) (L4607) up before abortRemainingCloseReqs (L4608) makes sense so concurrent callers can't bind to the failing closer while it's being retired. Since c.chanID is already removed from activeChanCloses at L4607, if Disconnect() runs concurrently between LoadAndDelete and initRbfChanCloser(lnChan) (L4646), abandonChanClosers won't see this channel, so initRbfChanCloser could still start a new closer and call p.cg.WgAdd(1) after p.cg.Quit(). Would it be worth guarding the re-init on c.peer.cg.Done()?
  • observeRbfCloseUpdatesWithSeq (peer/brontide.go:4499-4505): I saw TestRbfCloseErrDoesNotLeakOnRetry covers exiting the first observer on CloseErr (localDone) so its later cancellation doesn't re-emit ClosingNegotiation and leak CloseErr to a retry caller. Because ClosingNegotiation is a dual state and Local stays in *chancloser.CloseErr until a new LocalCloseReq arrives, what happens if a remote OfferReceivedEvent arrives after caller 2 registers coopCloseStates but before caller 2's LocalCloseReq is processed? It looks like that transition would still carry Local: CloseErr and trigger localDone on caller 2's observer (or on an earlier caller waiting for a broadcast ClosePending tx to confirm if a second caller's bump hits CloseErr). Not sure if that's expected in practice or if CloseErr should only be consumed once.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci-hold CI is held; remove this label to run CI

Projects

None yet

3 participants