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

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-12T04:17:56Z

+    chan = l1.get_channel_scid(l2)
+
+    l1.pay(l2, 200000000)
+    wait_for(lambda: only_one(l2.rpc.listpeerchannels()['channels'])['htlcs'] == [])


This is unnecessary, since close will wait for it.

rustyrussell · 2026-05-12T04:18:51Z

+    l2.daemon.wait_for_log('Simple close: broadcasting')
+    l1.daemon.wait_for_log('sendrawtx exit 0')
+    l2.daemon.wait_for_log('sendrawtx exit 0')
+


There's a general preference only to test for log messages when there's no other choice (in this case, 'Simple close starting' is probably necessary).

rustyrussell · 2026-05-12T04:19:16Z

+    wait_for(lambda: bitcoind.rpc.getmempoolinfo()['size'] == 1)
+
+    # Mine one block: the winner confirms, the loser is evicted.
+    bitcoind.generate_block(1)


generate_block(1, wait_for_mempool=1) does this inline.

rustyrussell · 2026-05-12T08:02:30Z

+msgdata,simpleclosed_init,min_feerate_perkw,u32,
+msgdata,simpleclosed_init,max_feerate_perkw,u32,


Shouldn't this just be "feerate"? You don't use max, and you use min as the feerate...

rustyrussell · 2026-05-12T08:07:44Z

+ * broadcast by the subdaemon, so we only need to (a) watch for the funding
+ * output being spent (so we can move to FUNDING_SPEND_SEEN when it confirms)
+ * and (b) resolve any pending close command. */
+void drop_to_chain_simple_close(struct lightningd *ld, struct channel *channel)


This misses out on a great deal of drop_to_chain :(

I don't think you can do it this way.

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.

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

+	broadcast_tx(channel, ld->topology, channel, tx, NULL, false, 0,
+		     NULL, NULL, NULL);
+


Here too...

rustyrussell · 2026-05-12T08:15:33Z

+	min_feerate = feerate_min(ld, NULL);
+	max_feerate = unilateral_feerate(ld->topology, false);
+	if (!max_feerate)
+		max_feerate = get_feerate(channel->fee_states,
+					  channel->opener, LOCAL);


We only need one, and we should figure out what it is. We allow json_close to specify a range: perhaps we should use the minimum of those if avail?

/* FIXME: API forces user to specify a range, so we use minimum */ if (channel->closing_feerate_range) feerate = channel->closing_feerate_range[0];

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

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;

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

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 wasn't ready in time for RC1 26.06 so MP moved it off the milestone but can we squeeze it to RC2 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 added 7 commits May 12, 2026 17:42

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

8103245

…lity

nGoline force-pushed the simple-close branch from 78780e6 to 8103245 Compare May 12, 2026 21:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

closingd: implement option_simple_close (BOLT2)#9104

closingd: implement option_simple_close (BOLT2)#9104
nGoline wants to merge 7 commits into
ElementsProject:masterfrom
nGoline:simple-close

nGoline commented May 1, 2026

Uh oh!

rustyrussell left a comment

Uh oh!

Uh oh!

Uh oh!

rustyrussell May 12, 2026

Uh oh!

rustyrussell May 12, 2026

Uh oh!

rustyrussell May 12, 2026

Uh oh!

rustyrussell May 12, 2026

Uh oh!

rustyrussell May 12, 2026

Uh oh!

rustyrussell May 12, 2026

Uh oh!

rustyrussell May 12, 2026

Uh oh!

rustyrussell May 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		msgdata,simpleclosed_init,min_feerate_perkw,u32,
		msgdata,simpleclosed_init,max_feerate_perkw,u32,

		broadcast_tx(channel, ld->topology, channel, tx, NULL, false, 0,
		NULL, NULL, NULL);

Conversation

nGoline commented May 1, 2026

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants