multi: add upfront-shutdown-address to lnd.conf. #9432

NishantBansal2003 · 2025-01-21T10:43:24Z

Change Description

This PR introduces a new configuration option, upfront-shutdown-address, in the lnd.conf file.
fixes: #7964

Added a new configuration option in lnd.conf to specify an upfront shutdown address.
When set, this ensures that funds from a channel closure are transferred to the specified address.
The behavior applies to both funder and fundee, with the ability to override it during openchannel and/or channel acceptor.

Steps to Test

Integration tests are provided to validate this new functionality.

Pull Request Checklist

Testing

Your PR passes all CI checks.
Tests covering the positive and negative (error paths) are included.
Bug fixes contain tests triggering the bug to prevent regressions.

Code Style and Documentation

The change obeys the Code Documentation and Commenting guidelines, and lines wrap at 80.
Commits follow the Ideal Git Commit Structure.
Any new logging statements use an appropriate subsystem and logging level.
Any new lncli commands have appropriate tags in the comments for the rpc in the proto file.
There is a change description in the release notes, or [skip ci] in the commit message for small changes.

📝 Please see our Contribution Guidelines for further guidance.

coderabbitai · 2025-01-21T10:43:31Z

Important

Review skipped

Auto reviews are limited to specific labels.

🏷️ Labels to auto review (1)

llm-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Generate unit testing code for this file.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai generate unit testing code for this file.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and generate unit testing code.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR. (Beta)
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

NishantBansal2003 · 2025-01-27T06:51:34Z

PTAL @yyforyongyu

NishantBansal2003 · 2025-02-15T03:28:05Z

Hey @yyforyongyu, could you take a look at this PR and share any comments if you have any? Thanks!

Abdulkbk · 2025-08-19T05:31:08Z

@NishantBansal2003 do you mind rebasing and fixing the conflicts?. I want to take a look.

NishantBansal2003 · 2025-08-19T16:46:43Z

@NishantBansal2003 do you mind rebasing and fixing the conflicts?. I want to take a look.

sure, working on it now...

NishantBansal2003 · 2025-08-24T14:19:14Z

I rebased this. I want to add that this was a relatively old PR at the time, and I was a beginner with LND and the Lightning Network as a whole (I still am ;)). Please let me know if there are any loose ends that need to be addressed, and if additional unit tests or itests could be added.

ellemouton

Nice work 🙏

My main comment is around the fact that setting this global option means that we will never be able to open a channel with a peer that does not support upfront shutdown (given the current state of the logic). So we need to decide if this is desired behaviour and if so, we should warn the user of this in the config description.

config.go

funding/manager.go

ellemouton · 2025-09-15T04:56:48Z

itest/list_exclude_test.go

 	"wipe forwarding packages",

 	"coop close with htlcs",
+	"open channel with shutdown address",


why do we need to skip this one for windows?

was getting the cannot coop close channel with active HTLCs error. It looked similar to the exclude above so I thought it was some flaky behavior on windows but let's add NoWait: true to fix this

itest/lnd_open_channel_test.go

ellemouton · 2025-09-15T05:00:48Z

itest/lnd_open_channel_test.go

+	// Create an invoice for Bob and send payment from Alice.
+	preimage := ht.Random32Bytes()
+	invoice := &lnrpc.Invoice{
+		RPreimage: preimage,
+		Value:     paymentAmount,
+	}
+	invoiceResp := bob.RPC.AddInvoice(invoice)


i think you can just use the ht.CreatePayReqs helper

funding/manager.go

ellemouton · 2025-09-15T05:12:37Z

funding/manager.go

+	if len(msg.ShutdownScript) == 0 {
+		msg.ShutdownScript = f.cfg.ShutdownScript


hmm, the problem with doing this is: not all our peers necessarily have advertised support for upfront shutdown. So now with this global script, if our peer doesnt support it, getUpfrontShutdownScript will always fail here:

// Check whether the remote peer supports upfront shutdown scripts. remoteUpfrontShutdown := peer.RemoteFeatures().HasFeature( lnwire.UpfrontShutdownScriptOptional, ) // If the peer does not support upfront shutdown scripts, and one has been // provided, return an error because the feature is not supported. if !remoteUpfrontShutdown && len(script) != 0 { return nil, errUpfrontShutdownScriptNotSupported }

since the script will now never be empty.

So I think we need to decide if this is desired behaviour & if so, the config option should warn the user that setting the option will result in channel-open failures for any peer that doesnt support upfront shutdown

considering the cooperative nature of the close I think it is better to warn that users would not be able to open a channel with peers who does not support upfront shutdown. It is up to the user to decide whether they want this partial protection or prefer to disable this feature. wdyt? we can discuss any better ideas you may have

Also similar behaviour is followed in the case of a channel acceptor -- if a peer has set up the channel acceptor with upfront_shutdown, the channel will not be opened by a peer that does not support this feature bit.

This can also be backed by https://github.com/lightning/bolts/blob/master/02-peer-protocol.md#the-open_channel-message

If you're going with warning the user about this behavior, then you should update the description of the field in config.go and sample-lnd.conf to explicitly state what this means for them.

Abdulkbk

Nice one, took a look and left some comments.

Abdulkbk · 2025-09-24T20:37:11Z

sample-lnd.conf

 ; pong failure.
 ; no-disconnect-on-pong-failure=false

+; An address to enforce payout of our funds to on cooperative close.


In the commit msg you mentioned "...but
can be overridden by the value specified during...", if that is the case, I think "enforce" doesn't fit this IMO. Additionally, you could also mention here that this value can be overridden.

config.go

funding/manager.go

Abdulkbk · 2025-09-24T21:48:19Z

funding/manager.go

+	if len(msg.ShutdownScript) == 0 {
+		msg.ShutdownScript = f.cfg.ShutdownScript


If you're going with warning the user about this behavior, then you should update the description of the field in config.go and sample-lnd.conf to explicitly state what this means for them.

Abdulkbk · 2025-09-24T21:56:47Z

itest/lnd_open_channel_test.go

 }
+
+// testOpenChannelWithShutdownAddr verifies that if the funder or fundee
+// specifies an upfront shutdown address in `lnd.conf`, the funds are correctly


nit: shutdown address in the config, the funds... since user can do lnd --upfront-shutdown-address=<addr>.

ellemouton

Cool, looks good!

Couple of comments but then i think we're g2g

ellemouton · 2025-09-29T15:28:03Z

config.go

+	// Note: If this field is set when opening a channel with a peer that
+	// does not advertise support for the upfront shutdown feature, the
+	// channel open will fail.
+	UpfrontShutdownAddr string `long:"upfront-shutdown-address" description:"Address that our funds will be paid out to on cooperative close applies to all channel opens unless overridden by openchannel options or a channel acceptor. Note: The channel open will fail if this value is set for a peer that does not support the upfront shutdown feature bit."`


nit: The address that funds will be paid out to on a cooperative channel close. This applies to all channels that are opened from the time of this option being set unless overridden for a specific channel opening. NOTE: if this option is set, any channel open will fail if the peer does not explicitly advertise the upfront-shutdown feature bit.

ellemouton · 2025-09-29T15:28:54Z

funding/manager.go

 		return
 	}

+	shutdownScript := acceptorResp.UpfrontShutdown


nit: put this under the comment

ellemouton · 2025-09-29T15:32:04Z

funding/manager.go

+	if len(shutdownScript) == 0 && f.cfg.ShutdownScript.IsSome() {
+		// Extract shutdown script from fn.Option. It is safe to call
+		// UnsafeFromSome because we just checked that it is some.
+		shutdownScript = f.cfg.ShutdownScript.UnsafeFromSome()
+	}


can just:

shutdownScript := acceptorResp.UpfrontShutdown if len(shutdownScript) == 0 { f.cfg.ShutdownScript.WhenSome( func(script lnwire.DeliveryAddress) { shutdownScript = script }, ) }

ellemouton · 2025-09-29T15:32:12Z

funding/manager.go

+	// If the funder did not provide an upfront-shutdown address, fall back
+	// to the configured shutdown script (if any).
+	if len(shutdownScript) == 0 && f.cfg.ShutdownScript.IsSome() {
+		// Extract shutdown script from fn.Option. It is safe to call


ellemouton · 2025-09-29T15:33:13Z

sample-lnd.conf

 ; pong failure.
 ; no-disconnect-on-pong-failure=false

+; An address that our funds will be paid out to on cooperative channel close.


see the suggestion i left in earlier comment

ellemouton

very nice!

yyforyongyu

LGTM 👏

Will merge once #10343 is merged.

lightninglabs-deploy · 2025-11-13T10:50:14Z

@NishantBansal2003, remember to re-request review from reviewers when ready

yyforyongyu · 2025-11-13T11:06:55Z

Missing a rebase, otherwise can be merged!

Introduced a new config value `upfront-shutdown-address` in the `lnd.conf` file. This ensures that channel close funds are transferred to the specified shutdown address. The value applies to both the funder and the fundee but can be overridden by the value specified during `openchannel` or by the `channel acceptor`. NOTE: If this field is set when opening a channel with a peer that does not advertise support for upfront shutdown feature, the channel open will fail. Signed-off-by: Nishant Bansal <nishant.bansal.282003@gmail.com>

Signed-off-by: Nishant Bansal <nishant.bansal.282003@gmail.com>

NishantBansal2003 · 2025-11-13T15:30:20Z

rebased!
unit-race CI is failing, but I think --- FAIL: TestAcceptedHodlNotExpired is flaky

NishantBansal2003 changed the title ~~Add upfront-shutdown-address to lnd.conf~~ multi: add upfront-shutdown-address to lnd.conf. Jan 21, 2025

NishantBansal2003 mentioned this pull request Jan 23, 2025

[feature]: allow configuring upfront shutdown address in lnd.conf #7964

Closed

2 tasks

NishantBansal2003 force-pushed the close-addr-conf branch from 0411618 to e0e5d26 Compare January 29, 2025 06:44

saubyk assigned NishantBansal2003 Feb 3, 2025

saubyk added this to the v0.20.0 milestone Feb 3, 2025

NishantBansal2003 force-pushed the close-addr-conf branch from e0e5d26 to 69f1f79 Compare August 24, 2025 14:17

NishantBansal2003 force-pushed the close-addr-conf branch from 69f1f79 to a4a00e7 Compare August 24, 2025 14:23

saubyk added this to lnd v0.20 Aug 25, 2025

saubyk moved this to In progress in lnd v0.20 Aug 25, 2025

saubyk modified the milestones: v0.20.0, v0.21.0 Sep 5, 2025

saubyk removed this from lnd v0.20 Sep 5, 2025

NishantBansal2003 force-pushed the close-addr-conf branch from a4a00e7 to 1d80f3d Compare September 13, 2025 04:44

ellemouton reviewed Sep 15, 2025

View reviewed changes

Abdulkbk reviewed Sep 24, 2025

View reviewed changes

NishantBansal2003 force-pushed the close-addr-conf branch from 1d80f3d to 0daffc2 Compare September 28, 2025 10:00

NishantBansal2003 requested a review from ellemouton September 28, 2025 15:45

ellemouton reviewed Sep 29, 2025

View reviewed changes

NishantBansal2003 force-pushed the close-addr-conf branch from 0daffc2 to 31722ee Compare September 30, 2025 16:07

NishantBansal2003 requested a review from ellemouton September 30, 2025 16:08

ellemouton approved these changes Oct 1, 2025

View reviewed changes

NishantBansal2003 force-pushed the close-addr-conf branch from 31722ee to cdbc0dc Compare October 19, 2025 19:03

yyforyongyu added this to v0.21 Nov 6, 2025

yyforyongyu reviewed Nov 6, 2025

View reviewed changes

NishantBansal2003 added 3 commits November 13, 2025 19:32

itest: add itest for upfront-shutdown-address config

4c3cff1

Signed-off-by: Nishant Bansal <nishant.bansal.282003@gmail.com>

docs: add release notes

36fb79e

Signed-off-by: Nishant Bansal <nishant.bansal.282003@gmail.com>

NishantBansal2003 force-pushed the close-addr-conf branch from cdbc0dc to 36fb79e Compare November 13, 2025 14:05

saubyk moved this to In review in v0.21 Nov 13, 2025

yyforyongyu merged commit ff20dd2 into lightningnetwork:master Nov 14, 2025
35 of 39 checks passed

github-project-automation bot moved this from In review to Done in v0.21 Nov 14, 2025

		if len(msg.ShutdownScript) == 0 {
		msg.ShutdownScript = f.cfg.ShutdownScript

multi: add upfront-shutdown-address to lnd.conf. #9432

multi: add upfront-shutdown-address to lnd.conf. #9432

Conversation

NishantBansal2003 commented Jan 21, 2025

Change Description

Steps to Test

Pull Request Checklist

Testing

Code Style and Documentation

Uh oh!

coderabbitai bot commented Jan 21, 2025

Review skipped

Chat

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Documentation and Community

Uh oh!

NishantBansal2003 commented Jan 27, 2025

Uh oh!

NishantBansal2003 commented Feb 15, 2025

Uh oh!

Abdulkbk commented Aug 19, 2025

Uh oh!

NishantBansal2003 commented Aug 19, 2025

Uh oh!

NishantBansal2003 commented Aug 24, 2025

Uh oh!

ellemouton left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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!

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!

Abdulkbk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ellemouton 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ellemouton left a comment

Choose a reason for hiding this comment

Uh oh!

yyforyongyu left a comment

Choose a reason for hiding this comment

CodeRabbit Configuration File (`.coderabbit.yaml`)

ellemouton left a comment •

edited

Loading