Aux Closer: Move coop-close aux finalization to chain watcher #10289

GeorgeTsagk · 2025-10-13T13:32:22Z

Description

Moves the aux closer finalization hook call site from ReceiveClosingSigned, which relies on our peer staying online and sending us the message, to the chain watcher where we instead wait for the coop close tx to be detected onchain.

This implies that the finalization will be completed after some delay, but this also comes coupled with the guarantee of not having to rely on our peer behaving correctly.

Circular dependency

The aux closer is used in lnwallet/chancloser and now also in contractcourt (by chain watcher). This caused a circular dependency which disallowed us from importing some definitions directly from the former package. The direct solution was to replicate some of the types and use an adapter on the server for our new slim interface. Not an ideal solution, will keep searching for alternatives -- although this is non blocking for the purpose of this PR.

Due to a circular dependency issue, we cannot directly import these definitions from lnwallet/chancloser. So we'll redefine the types we need and define a slim interface around the aux closer, which contains exactly the functionality that we'll want to use here.

We now execute the aux chan closer finalization within the chain watcher. This is better as we don't need to rely on the remote party being online and sending us a message. Instead we do the finalization once the on-chain transaction has been confirmed.

The final step is to provide the aux closer to the corresponding configs from the server. Here we use an adapter pattern which returns an aux chan closer as defined in the contractcourt package.

gemini-code-assist · 2025-10-13T13:32:36Z

Summary of Changes

Hello @GeorgeTsagk, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refactors the cooperative channel closing mechanism to enhance its reliability. It shifts the responsibility of finalizing auxiliary channel closures from relying on a peer's message to monitoring the blockchain for the confirmed cooperative close transaction. This change ensures that finalization is guaranteed, albeit with a slight delay, by removing the dependency on the peer's online status or correct behavior. The implementation also addresses a resulting circular dependency by introducing new types and an adapter.

Highlights

Aux Closer Relocation: The finalization hook call for the aux closer has been moved from ReceiveClosingSigned (which relied on peer messages) to the chain watcher. This means finalization now occurs when the cooperative close transaction is detected on-chain, ensuring robustness even if the peer is offline or misbehaves.
Circular Dependency Resolution: A circular dependency between lnwallet/chancloser and contractcourt was introduced due to the aux closer's new usage. This was resolved by replicating necessary types in contractcourt and implementing an adapter in server.go to bridge the interfaces.
New Interface and Types: New types (CloseOutput, AuxShutdownReq, AuxCloseDesc) and an interface (AuxChanCloser) have been defined within contractcourt to support the new on-chain finalization logic and manage the circular dependency.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request refactors the cooperative close finalization by moving the AuxChanCloser hook from ReceiveClosingSigned to the chainWatcher. This is a good improvement as it makes the finalization process more reliable by depending on on-chain events rather than peer messages.

The implementation of the adapter pattern to resolve the circular dependency is clean. However, I've found a critical issue in the new finalizeCoopClose function where the logic to identify local and remote outputs is incorrect and could lead to problems if there are more than two outputs in the closing transaction. Additionally, some fields in AuxCloseDesc were not being populated. I've provided a detailed comment and a code suggestion to address this.

contractcourt/chain_watcher.go

gijswijs

I did a first pass on this PR and left some comments.

There's also a typo in the second commit: countractcourt+lnwallet should be contractcourt+lnwallet

I have a few general questions as well:

If node restarts after close tx confirms but before finalization, what happens? Do we re-detect the spend on restart?

I'm missing an unit test for finalizeCoopClose., although the original ReceiveClosingSigned func also doesn't have any testing iiiuc. But this might be a good time to increase that coverage.

gijswijs · 2025-10-17T08:57:28Z

contractcourt/chain_watcher.go

 	// polling the database for a channel's commitpoint.
 	maxCommitPointPollTimeout = 10 * time.Minute
 )



Consider refactoring these types into a shared package. e.g: lnwallet/chantypes

This would avoid the duplication and the circular dependency. 🦅 🦅 🪨💨

gijswijs · 2025-10-17T09:20:15Z

contractcourt/chain_watcher.go

+		return fmt.Errorf("get shutdown info: %w", err)
+	}
+
+	// TODO(roasbeef): Extract the internal key if this is a taproot


Why is this a todo specifically for roasbeef and not for @GeorgeTsagk?

This todo was meant for @GeorgeTsagk , but realized now it is not needed at all. Will update comments accordingly

contractcourt/chain_watcher.go

gijswijs · 2025-10-17T10:06:44Z

lnwallet/chancloser/chancloser.go

 		}
 		c.closingTx = closeTx

-		// If there's an aux chan closer, then we'll finalize with it


question: is there value in leaving this code?

This PR introduces more robust handling of the aux closer finalization by moving the hook call site from ReceiveClosingSigned to the chainwatcher. That also introduces a waiting time of ~10 minutes before the finalization is initiated. Couldn't we keep doing both?

In case our peer stays online this would lead to a faster finalization which in turn maybe is a better user experience.

gijswijs · 2025-10-17T10:54:35Z

server.go

 	// state determines which privileges the peer has with our server.
 	state peerAccessStatus
 }



Maybe consider moving to a dedicated file like contractcourt/aux_closer_adapter.go for better organization. server.go is so long already.

GeorgeTsagk · 2025-10-20T10:42:46Z

Replying to @gijswijs's comment:

If node restarts after close tx confirms but before finalization, what happens? Do we re-detect the spend on restart?

I believe that this is the case, since this is code that is called for any channel in LND (with the finalizeCoopClose being optionally called).

I'm missing an unit test for finalizeCoopClose., although the original ReceiveClosingSigned func also doesn't have any testing iiiuc. But this might be a good time to increase that coverage.

Yeah there's not much to test as this is an external hook. We can make a basic-level assertion on a mock implementation of it -- i.e just make sure that it is being called with non-nil parameters.

lightninglabs-deploy · 2025-10-27T11:35:21Z

@Roasbeef: review reminder
@GeorgeTsagk, remember to re-request review from reviewers when ready

Roasbeef · 2025-10-28T01:37:57Z

contractcourt/chain_watcher.go

+}
+
+// AuxCloseDesc is used to describe the channel close that is being performed.
+type AuxCloseDesc struct {


These types are duplicated from lnwallet/chancloser/aux_closer.go. Why do they need to be moved here?

Roasbeef · 2025-10-28T01:38:46Z

contractcourt/chain_watcher.go

+		return fmt.Errorf("get shutdown info: %w", err)
+	}
+
+	// TODO(roasbeef): Extract the internal key if this is a taproot


Roasbeef · 2025-10-28T01:40:33Z

contractcourt/chain_watcher.go

+	var localCloseOutput, remoteCloseOutput fn.Option[CloseOutput]
+
+	// Get the delivery scripts for both parties.
+	var localDeliveryScript lnwire.DeliveryAddress


The comment says both parties, but lonly extracts this script for a single party.

Roasbeef · 2025-10-28T01:41:09Z

contractcourt/chain_watcher.go

+
+	// Get the delivery scripts for both parties.
+	var localDeliveryScript lnwire.DeliveryAddress
+	shutdown.WhenSome(func(s channeldb.ShutdownInfo) {


IIUC this must be set at this point. We can encode this invariant by returning an error if it isn't available.

Roasbeef · 2025-10-28T01:43:02Z

contractcourt/chain_watcher.go

+	// TODO(roasbeef): Extract the internal key if this is a taproot
+	// channel. For now, we leave it as None since we don't persist it
+	// separately from the delivery script.
+	var internalKey fn.Option[btcec.PublicKey]


In the existing call site, this is always properly set.

Roasbeef · 2025-10-28T01:43:19Z

contractcourt/chain_watcher.go

+		RemoteCloseOutput: remoteCloseOutput,
+	}
+
+	// Call FinalizeClose on the aux closer.


Superflous comments here and above.

Roasbeef · 2025-10-28T01:45:12Z

server.go

+}
+
+// FinalizeClose adapts the chancloser types to contractcourt types.
+func (a auxCloserAdapter) FinalizeClose(desc contractcourt.AuxCloseDesc,


Why do we need this adapter at all? Why can't we pass the existing interface as defined in the chanclose package into the chain watcher?

GeorgeTsagk added 3 commits October 13, 2025 15:20

lnd: provide aux closer to chain arbitrator

2b077d5

The final step is to provide the aux closer to the corresponding configs from the server. Here we use an adapter pattern which returns an aux chan closer as defined in the contractcourt package.

GeorgeTsagk requested review from Roasbeef and gijswijs October 13, 2025 13:32

GeorgeTsagk self-assigned this Oct 13, 2025

GeorgeTsagk changed the title ~~Move aux closer~~ Aux Closer: Move coop-close aux finalization to chain watcher Oct 13, 2025

gemini-code-assist bot reviewed Oct 13, 2025

View reviewed changes

contractcourt/chain_watcher.go Show resolved Hide resolved

gijswijs requested changes Oct 17, 2025

View reviewed changes

Roasbeef requested changes Oct 28, 2025

View reviewed changes

Uh oh!

Aux Closer: Move coop-close aux finalization to chain watcher #10289

Are you sure you want to change the base?

Aux Closer: Move coop-close aux finalization to chain watcher #10289

Conversation

GeorgeTsagk commented Oct 13, 2025

Description

Circular dependency

Uh oh!

gemini-code-assist bot commented Oct 13, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

gijswijs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GeorgeTsagk commented Oct 20, 2025

Uh oh!

lightninglabs-deploy commented Oct 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants