Skip to content

lightningd: track funding-tx broadcast visibility, gate zero-conf forwarding on it - #9437

Open
Andezion wants to merge 2 commits into
ElementsProject:masterfrom
Andezion:funding-visibility-status
Open

Andezion wants to merge 2 commits into
ElementsProject:masterfrom
Andezion:funding-visibility-status

Conversation

@Andezion

Copy link
Copy Markdown
Collaborator

Inside

Zero-conf channels (option_zeroconf) become usable for HTLC forwarding immediately, with zero verification that the funding transaction was ever broadcast to the network - peer_start_channeld() sends channeld an artificial 0-depth confirmation event, unconditionally, using a zeroed-out fake txid, regardless of whether the real funding tx has ever been observed. There was no persisted state anywhere distinguishing "never broadcast" from "broadcast, unconfirmed" from "confirmed."

This PR adds:

  1. common/funding_tx_status.h: a new persisted DB enum (UNKNOWN / MEMPOOL / CONFIRMED), stored on both channels and channel_funding_inflights (replacing the in-memory-only channel_inflight.tx_broadcast)
  2. Gating in peer_start_channeld(): the artificial zero-conf depth event is only sent once funding_tx_status >= MEMPOOL, using the real funding txid instead of a zeroed-out one
  3. A lightweight poll in chaintopology.c (every 5s) so the non-broadcasting side of a zero-conf channel also detects funding-tx visibility via gettxout (mempool or confirmed), not just the side that called sendrawtransaction
  4. A new FORWARD_FAIL_FUNDING_NOT_BROADCAST forward-failure reason, raised instead of unknown_next_peer when a forward fails specifically because the outgoing zero-conf channel's funding was never observed broadcast
  5. A migration backfilling already-running channels (state past the pre-lockin dance) to CONFIRMED, so this doesn't retroactively block channels already in production use

Important

26.09 FREEZE August 5th: Non-bugfix PRs not ready by this date will wait for 26.12.

RC1 is scheduled on August 17th

The final release is scheduled for September 7th.

Checklist

Before submitting the PR, ensure the following tasks are completed. If an item is not applicable to your PR, please mark it as checked:

  • The changelog has been updated in the relevant commit(s) according to the guidelines.
  • Tests have been added or modified to reflect the changes.
  • Documentation has been reviewed and updated as needed.
  • Related issues have been listed and linked, including any that this PR closes.
  • Important All PRs must consider how to reverse any persistent changes for tools/lightning-downgrade

Changelog-Fixed: lightningd: zero-conf channels no longer accept HTLC forwards before their funding transaction has actually been observed broadcast, failed forwards over such a channel now report funding_not_broadcast instead of a generic reason

@Andezion Andezion self-assigned this Aug 18, 2026
@Andezion
Andezion force-pushed the funding-visibility-status branch 2 times, most recently from bd22f4a to d429bd1 Compare August 21, 2026 15:02
@Andezion
Andezion marked this pull request as ready for review October 26, 2026 15:28
@Andezion
Andezion requested a review from cdecker as a code owner October 26, 2026 15:28
@Andezion Andezion added the Status::Ready for Review The work has been completed and is now awaiting evaluation or approval. label Oct 26, 2026
@Andezion
Andezion force-pushed the funding-visibility-status branch from d429bd1 to 4853a7d Compare October 26, 2026 15:28
@Andezion
Andezion force-pushed the funding-visibility-status branch 2 times, most recently from c147533 to 57350f8 Compare November 3, 2026 13:47

@cdecker cdecker left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very good change 👍

There is one small logical issue that we need to ensure is solved before we can merge it though. As it stands right now, we are delaying the channel_ready signal, but in the case of JIT LSP channels, which I believe this attemtps to stabilize, the LSP waits for the initial payment to complete, but it cannot attempt the forwarding of the payment, until we have exchanged the channel_ready which results in a circular dependency, that'd cause LSP JIT channels to always fail its completion.

It should be ok to exchange the channel_ready, accepting HTLCs, but we can use the signal you are adding here to gate our own use of the channel, so that we do not accidentally lock up on abandoned channels, whcih is the problem we are currently facing.

Comment thread doc/lightningd-config.5.md Outdated
* **zeroconf-require-funding-seen**=*BOOL*

If set to `true`, a zero-conf channel (`minimum_depth` 0) is not used, and we
don't send `channel_ready` for it, until our own bitcoind has seen its funding

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This prevents the B-LPS and all other LSPs2 implementations from completing:
There is a circular dependency here:

  1. LSP opens channel
  2. Waits for channel_ready so it can add the HTLC paying for the channel
  3. Recipient waits for incoming payment before sending channel_ready
  4. The LSP publishes the funding only if and when the HTLC is accepted by the recipient.

Notice how we have a circular dependency here:

4 -> 3 -> 2 -> 4

There is no way to secure these, but we can still guard ourselves from using a channel ourselves until we have its funding. It is even a stronger check than what we currently have in GL (a max_msat_to_us high water mark that tells us if we ever accepted a payment over this channel if it is non-zero).

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, done!

@cdecker

cdecker commented Nov 5, 2026

Copy link
Copy Markdown
Member

I took the liberty of filing issue #9697 as a followup: it adds a stricter guarantee, i.e., that we save lifecycle relevant transactions in the DB, even if we are the fundee. It builds on your changes here, and strengthens the guarantees a bit, and also gives a fundee all they need to in order to enforce their version of reality.

@cdecker cdecker added needs-rebase and removed Status::Ready for Review The work has been completed and is now awaiting evaluation or approval. labels Nov 5, 2026
Andezion and others added 2 commits November 18, 2026 14:34
Changelog-Added: Config:  makes lightningd wait until it has seen a zero-conf channel's funding transaction before using it
@Andezion
Andezion force-pushed the funding-visibility-status branch from 57350f8 to fa38713 Compare November 18, 2026 14:35

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants