closingd: implement option_simple_close (BOLT2) by nGoline · Pull Request #9104 · ElementsProject/lightning

nGoline · 2026-05-01T14:51:26Z

Implements the option_simple_close mutual close protocol from BOLT2 (feature bit 60/61), replacing the legacy iterative closing_signed fee negotiation for peers that support it.

Background

The existing mutual close protocol requires both sides to agree on a single fee via closing_signed messages. If their fee sources diverge (e.g. during a fee spike) they can loop indefinitely and stall.

The new protocol is simpler: each peer independently proposes their own closing transaction via closing_complete, the other side signs it and replies with closing_sig, and both broadcast their respective versions. Two valid-but-conflicting transactions enter the mempool, whichever confirms first wins. The closer (the one who sent closing_complete)
bears the fee.

What this adds

common/features: OPT_SIMPLE_CLOSE (bit 60/61), registered in feature_styles[] for dev-force-features support. Not in default_features() yet: opt-in only.
common/close_tx: create_simple_close_tx() builds the BOLT3 simple closing transaction: sequence 0xFFFFFFFD (RBF), locktime from closing_complete, closer pays fee, dust outputs omitted, zero-value OP_RETURN when both outputs are dust.
channeld: stubs that call peer_failed_warn() if closing_complete or closing_sig arrive inside channeld (they should only ever reach simpleclosed).
closingd/simpleclosed: new subdaemon lightning_simpleclosed that implements the full BOLT2 exchange loop, including TLV variant selection, signature verification, and both-sides broadcast.
lightningd:
- simple_close_control.c starts the daemon and handles its wire messages; channel_control.c routes to it when OPT_SIMPLE_CLOSE is negotiated;
- peer_control.c adds drop_to_chain_simple_close() which sets up the on-chain watch and resolves the close RPC without re-broadcasting the commitment tx (which would otherwise RBF-replace the mutual close txs).

Testing

Four integration tests in tests/test_closing.py using--dev-force-features=+60:

test_simple_close_basic: happy path, state transitions, on-chain settlement
test_simple_close_closer_pays_fee: fee deducted from closer's output only
test_simple_close_dust_output_omitted: dust output omitted
test_simple_close_no_feature_fallback: without bit 60, legacy closingd is used
test_simple_close_restart: re-transmit our simple_close transaction after restart
test_simple_close_closee_path: the closee (peer) transaction is stored

Enabling

lightningd --dev-force-features=+60

To enable by default in a future release, add OPTIONAL_FEATURE(OPT_SIMPLE_CLOSE) to default_features() in
lightningd/lightningd.c.

Checklist

Changelog updated (Changelog-Experimental: in commit 979a285)
Tests added
Documentation reviewed: no new RPC commands; BOLT quotes included in source per check-source-bolt
Related issues: closes Implement option_simple_close (BOLT 2 Simple Closing Negotiation) #9099
lightning-downgrade: not applicable: no database migrations or schema changes

rustyrussell

As you'll see, I've gone through this with a fine-toothed comb and picked all the nits I could find!

It's generally excellent, with a few things requiring cleanup (and obviously, some folding of those fix commits). Great work!

rustyrussell · 2026-05-12T08:10:22Z

+	/* Broadcast it (rebroadcast on restarts as needed). */
+	broadcast_tx(channel, ld->topology, channel, tx, NULL, false, 0,
+		     NULL, NULL, NULL);


No. You need to check that it is a valid transaction: by policy we don't trust our subdaemons (much! We should also check it actually goes where we expect it, and pays us, but you'll note that check is missing already in closing_control!). You then need to set it as as our channel's last tx using:

channel_set_last_tx(channel, tx, &sig); wallet_channel_save(ld->wallet, channel);

Otherwise it won't restore coming back. The closing logic will then handle broadcast, normally.

I've based this implementation heavily on legacy close... Thanks for the heads-up!

I was able to add a few checks, let me know if it's necessary for now, we can always get back to this when adding checks to closing_control.

exactly 1 input spending channel->funding, every output goes to shutdown_scriptpubkey[LOCAL] or [REMOTE] (also skipping the validation for Elements' outputs)

peer's signature is valid for this exact tx over the funding wscript

nGoline · 2026-05-14T14:19:28Z

@rustyrussell I reviewed all your comments and fixed the code. Waiting for your review.

sangbida · 2026-06-22T05:14:35Z

+
+    # The channel must resolve as a MUTUAL close — not as a unilateral close,
+    # which would happen if l1 had rebroadcast the commitment tx instead.
+    l1.daemon.wait_for_log('Resolved FUNDING_TRANSACTION/FUNDING_OUTPUT by MUTUAL_CLOSE')


This test could also check if the correct mutual close tx got selected based on their fee. You could do this by asserting on channel->last_tx

channel->last_tx here is always our own closer tx, not a fee-based pick. Both handle_simpleclosed_got_sig(closer tx) and handle_simpleclosed_closee_broadcast(closee tx) call channel_set_last_tx, and closing_sig always arrives after the peer's closing_complete, so the closer tx is the one stored last.
The fee comparison lives in the delay heuristic (it decides broadcast timing, not which tx is stored), and test_simple_close_delay_broadcast already covers that path via its log assertion. So there's no fee-based last_tx selection to assert on in this test.

sangbida · 2026-06-22T06:52:42Z

+            "added": "v26.08",
+            "deprecated": null
+        },


I think the release will be 26.09?

That's correct, fixed!

sangbida · 2026-06-22T07:57:24Z

+			if (got_peer_complete) {
+				status_debug("Got another closing_complete "
+					"(peer bumping fee): re-signing");
+			}


It might be good to have a test for this case?

This branch only runs when a peer sends a second closing_complete to bump the fee. CLN's simpleclosed sends closing_complete exactly once and never RBF-bumps, so two CLN nodes can't reach it. It's kept for interop with peers that do bump. A test would need a mock peer that re-sends closing_complete, so I'll defer coverage until CLN itself gains closing fee-bumping.

sangbida · 2026-06-22T08:03:26Z

+		txs[0] = channel->last_tx;
+		resolve_close_command(ld, channel, true, txs);
+		notleak(new_reltimer(ld->timers, channel,
+			time_from_sec(3600),


nit: magic number, could use a comment or be a constant

Four tests for the `option_simple_close` protocol (BOLT ElementsProject#2, bit 60). `test_simple_close_no_feature_fallback` exercises the existing legacy `closingd` path and passes now; the other three are marked xfail until the implementation lands: - test_simple_close_basic: happy path; both nodes exchange closing_complete/closing_sig, each broadcasts two conflicting txs, the winner confirms, both nodes detect their output CONFIRMED - test_simple_close_closer_pays_fee: closer bears the fee, closee receives their exact pre-close balance - test_simple_close_dust_output_omitted: closee output below dust is omitted from the closing tx (closer_output_only variant) - test_simple_close_no_feature_fallback: without bit 60, nodes fall back to legacy closingd - test_simple_close_restart: re-transmit our simple_close transaction after restart - test_simple_close_closee_path: the closee (peer) transaction is stored

features.h: Reserves bits 60/61 for `option_simple_close` per BOLT2. features.c: Add `OPT_SIMPLE_CLOSE` to `feature_styles[]` and declare the correct `feature_name`. tests/test_closing.py: Update options on `test_simple_close_...` to include `{experimental-simple-close: None}`. lightningd/options.c: Register noarg option for simple close. doc/schemas/listconfigs.json: add `experimental-simple-close` to config targeting v26.08. doc/lightningd-config.5.md: Specify `experimental-simple-close` option. contrib/pyln-testing/pyln/testing/utils.py: Allow setting `EXPERIMENTAL_SIMPLE_CLOSE` on tests. Generated files after modifying sources.

…ose` Adds the BOLT3 simple closing transaction builder: - sequence 0xFFFFFFFD (RBF-signalling) - locktime from closing_complete - closer pays fee (their output is reduced) - dust outputs are omitted and a zero-value OP_RETURN is used when both outputs would be dust.

When `option_simple_close` is negotiated the master launches `simpleclosed` after `channeld` exits, so `closing_complete` and `closing_sig` should never arrive inside `channeld`. Add stubs that call peer_failed_warn() with an informative message rather than hitting the default unknown-message path.

New subdaemon implementing the BOLT2 simple close protocol, replacing `lightning_closingd` when `option_simple_close` is negotiated: - Each peer independently sends `closing_complete` with their fee proposal; - The other side signs it and sends `closing_sig`; - Both sides broadcast two conflicting closing transactions and whichever confirms first wins. Key protocol details: - Closer pays the fee and closee receives their exact channel balance; - TLV variants selected per BOLT2: `closer_output_only`, `closer_and_closee_outputs`, `closee_output_only`; - Sequence 0xFFFFFFFD enables RBF via re-sending `closing_complete`; - Script mismatch on `closee_scriptpubkey` warns and fails to reconnect; common/shutdown_scriptpubkey.h/c: removed `static` from `is_valid_op_return` so it can be used in `simpleclosed.c`

Adds the master-side glue for the `simpleclosed` subdaemon and removes the xfail markers from the integration tests: - simple_close_control.c: - starts the daemon with feerate bounds and shutdown scripts; - handles SIMPLECLOSED_GOT_SIG (broadcast closer tx), SIMPLECLOSED_CLOSEE_BROADCAST (broadcast closee tx), and SIMPLECLOSED_COMPLETE (advance state, resolve close RPC) - channel_control.c: route to peer_start_simpleclosed() instead of peer_start_closingd() when OPT_SIMPLE_CLOSE is negotiated; - peer_control.c: drop_to_chain_simple_close() sets up the funding-spend watch and resolves the close RPC without broadcasting the commitment tx, avoids it RBF-replacing the mutual close txs; - resend_closing_transactions() uses the same variant on restart Changelog-Experimental: Protocol: implement `option_simple_close` (BOLT2) for simpler one-shot mutual close fee negotiation. Enable with --dev-force-features=+60.

…lity

… is less AND our fee is less than our peer's amount and fee in case of a reboot the tx will be broadcast as usual. simple_close_control.c: add delay logic to `drop_to_chain` after 1 hour. test_closing.py: add test to verify the heuristic is being applied.

nGoline · 2026-07-01T19:44:51Z

I don't know what's happening. 3 runs gets cancelled at 10%: https://github.com/ElementsProject/lightning/actions/runs/28530856367/job/84619960038?pr=9104

nGoline self-assigned this May 1, 2026

nGoline requested a review from rustyrussell May 1, 2026 18:26

madelinevibes added this to the 26.06 milestone May 4, 2026

nGoline force-pushed the simple-close branch 2 times, most recently from ff9b5a6 to 9f9896b Compare May 4, 2026 12:23

nGoline marked this pull request as ready for review May 5, 2026 17:25

nGoline force-pushed the simple-close branch from a167b2c to 9a055d3 Compare May 5, 2026 17:29

madelinevibes added the 26.06 RC label May 11, 2026

madelinevibes modified the milestones: v26.06, v26.09 May 11, 2026

rustyrussell reviewed May 12, 2026

View reviewed changes

nGoline force-pushed the simple-close branch from 9a055d3 to 78780e6 Compare May 12, 2026 20:32

nGoline requested a review from cdecker as a code owner May 12, 2026 20:32

nGoline force-pushed the simple-close branch 6 times, most recently from a4c8771 to aa8a412 Compare May 14, 2026 14:19

nGoline force-pushed the simple-close branch 2 times, most recently from 4d784c5 to 569b63e Compare May 18, 2026 20:41

nGoline removed the 26.06 RC label May 21, 2026

nGoline requested review from daywalker90 and removed request for cdecker June 18, 2026 18:59

nGoline added the Status::Ready for Review The work has been completed and is now awaiting evaluation or approval. label Jun 18, 2026

nGoline requested review from cdecker and sangbida and removed request for daywalker90 June 19, 2026 10:25

madelinevibes assigned sangbida Jun 22, 2026

sangbida reviewed Jun 22, 2026

View reviewed changes

nGoline force-pushed the simple-close branch from 569b63e to 4aacafd Compare July 1, 2026 13:52

nGoline requested a review from sangbida July 1, 2026 13:52

nGoline added 3 commits July 1, 2026 12:47

nGoline force-pushed the simple-close branch from 4aacafd to d5ba114 Compare July 1, 2026 15:47

nGoline added 4 commits July 1, 2026 13:01

test: add run-close_tx to validate simple-close transaction functiona…

8b60e95

…lity

nGoline force-pushed the simple-close branch from d5ba114 to cb95481 Compare July 1, 2026 16:01

Uh oh!

Conversation

nGoline commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

What this adds

Testing

Enabling

Checklist

Uh oh!

rustyrussell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

nGoline commented May 14, 2026

Uh oh!

Uh oh!

sangbida Jun 22, 2026 • 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!

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!

nGoline commented Jul 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nGoline commented May 1, 2026 •

edited

Loading

sangbida Jun 22, 2026 •

edited

Loading