Skip to content

closingd: implement option_simple_close (BOLT2)#9104

Draft
nGoline wants to merge 8 commits intoElementsProject:masterfrom
nGoline:simple-close
Draft

closingd: implement option_simple_close (BOLT2)#9104
nGoline wants to merge 8 commits intoElementsProject:masterfrom
nGoline:simple-close

Conversation

@nGoline
Copy link
Copy Markdown
Collaborator

@nGoline nGoline commented May 1, 2026

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

nGoline added 6 commits May 1, 2026 11:24
@nGoline
tests: add option_simple_close integration tests
6b2df2c 
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
@nGoline
common: add OPT_SIMPLE_CLOSE feature bit (60/61)
437740d 
Reserves bits 60/61 for `option_simple_close` per BOLT2.  Registers
the feature in `feature_styles[]` so dev-force-features ±60 works without
aborting, but does not add it to `default_features()`, it stays opt-in
until the protocol is fully ready to advertise unconditionally.
@nGoline
common/close_tx: add create_simple_close_tx() for `option_simple_cl…
0a3f1ae 
…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.
@nGoline
channeld: reject closing_complete and closing_sig with a clear error
3396c02 
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.
@nGoline
closingd: add lightning_simpleclosed for option_simple_close
fd971bb 
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;
@nGoline
lightningd: wire up option_simple_close master-side handling
979a285 
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.
@nGoline nGoline self-assigned this May 1, 2026
@nGoline
check-source: fix BOLT quotes in simpleclosed, close_tx, and features
85736a3 
Correct the BOLT ElementsProject#2/ElementsProject#3 quote blocks added with `option_simple_close` so
that `check-source-bolt` passes:

- closingd/simpleclosed.c: fix quote formatting and exact text to match
  the spec wording for dust output omission and script validation
- common/close_tx.c: update the BOLT ElementsProject#3 closing transaction quote to
  match the current spec bullet-point format
- common/features.h: fix the feature-table BOLT ElementsProject#9 quote for bit 60/61
@nGoline nGoline requested a review from rustyrussell May 1, 2026 18:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rustyrussell rustyrussell Awaiting requested review from rustyrussell

Assignees

@nGoline nGoline

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Implement option_simple_close (BOLT 2 Simple Closing Negotiation)

1 participant

@nGoline