Skip to content

Conversation

NishantBansal2003
Copy link
Contributor

@NishantBansal2003 NishantBansal2003 commented Apr 4, 2025

Change Description

Fixes: #9452
This PR enhances the PendingChannelsResponse_PendingChannel structure to include the ConfirmationsUntilActive field. This new field provides users with the exact number of confirmations required for a pending channel's transition to an active state.

Changes:

  • Database Update:
    The channel's shortchannelID is now persisted in the database once its funding transaction receives 1 confirmation. This ensures we have a reference point to track progress toward the required confirmation depth.

  • API Enhancement:
    Introduced the ConfirmationsUntilActive field in the PendingChannelsResponse_PendingChannel response. This field indicates the remaining confirmations needed for the channel to become active.​

    • If the funding transaction is unconfirmed, ConfirmationsUntilActive defaults to the total required confirmations (NumConfsRequired).

Steps to Test

  • itest: itest have been added to validate this new functionality.

  • Manual Verification: To manually test:​

    • Establish a channel between two peers without confirming the funding transaction.​

    • Execute lncli pendingchannels to observe the confirmations_until_active field, which should display the remaining confirmations needed for the pending channel to transition to an active state.

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

📝 Please see our Contribution Guidelines for further guidance.

Copy link
Contributor

coderabbitai bot commented Apr 4, 2025

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.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ 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.
    • Explain this complex logic.
    • 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 explain this code block.
    • @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 explain its main purpose.
    • @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.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

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.
  • @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
  • @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 NishantBansal2003 changed the title Conf count Expose confirmation count for pending 'channel open' transactions Apr 4, 2025
@saubyk saubyk added this to the v0.20.0 milestone Apr 4, 2025
@saubyk saubyk added this to lnd v0.20 Apr 4, 2025
@saubyk saubyk moved this to In progress in lnd v0.20 Apr 4, 2025
@saubyk saubyk removed this from lnd v0.20 Apr 4, 2025
@saubyk saubyk self-requested a review April 4, 2025 18:36
Copy link
Contributor

@MPins MPins left a comment

Choose a reason for hiding this comment

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

Good job 👍

Copy link
Collaborator

@saubyk saubyk left a comment

Choose a reason for hiding this comment

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

providing some initial comments. will test further.

Copy link
Contributor

@MPins MPins left a comment

Choose a reason for hiding this comment

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

I took a deeper look at manager_test and have a few questions.

Comment on lines 1499 to 1609
// We send two notifications:
// 1. The first adds the SCID to the database, allowing calculation of
// the number of confirmations before the channel is fully opened.
// 2. The second marks the channel as open.
alice.mockNotifier.oneConfChannel <- &chainntnfs.TxConfirmation{
Tx: fundingTx,
}
bob.mockNotifier.oneConfChannel <- &chainntnfs.TxConfirmation{
Tx: fundingTx,
}
Copy link
Contributor

Choose a reason for hiding this comment

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

It works, but this doesn't reflect the actual open channel process, right? Have you considered sending the channel confirmation after the transaction confirmation?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Sorry, I didn't quite understand what you meant. My understanding is that if we wait until the transaction is confirmed (after 3 or 6 blocks, etc.), then by the time we mark the channel as confirmed, it will already be open. Also, since we need the details of the SCID, we have to mark the channel as confirmed (after 1 block) even before the transaction is fully confirmed. Am I thinking in the right direction, or is there anything I should read first to better align my thoughts with your points?

Copy link
Contributor

Choose a reason for hiding this comment

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

I meaning that you are sending the confirmation tx event twice to Alice and Bob funding managers. I'm not sure if this is happening during the normal workflow when a channel is opening.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I meaning that you are sending the confirmation tx event twice to Alice and Bob funding managers. I'm not sure if this is happening during the normal workflow when a channel is opening.

Ok, so what I understand is that in a normal, real-world workflow, whenever a confirmation tx notification is registered, the notification is sent to all the goroutines that registered for it as soon as the block is mined. However, since this is a unit test, I need to explicitly send the confirmation tx event twice.

Have you considered sending the channel confirmation after the transaction confirmation?

Since we need the details of the SCID, we have to mark the channel as confirmed (after one block) even before the transaction is fully confirmed.
Also, if I send the goroutine for channel confirmation after the transaction confirmation, I still need to send the confirmation tx event twice because of the select statement:

  1. If one or more of the communications can proceed, a single one that can proceed is chosen via a uniform pseudo-random selection.

See: https://go.dev/ref/spec#Select_statements

To avoid flaky tests, I send the confirmation tx event twice.
I hope this is the correct way of handling the process. Please suggest any better method you have in mind.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Agree this testHarness could be better mocked, however both nodes need to receive the confirmation to finally set the channel to active.

Tho this changes with my proposal so I am not going to review this for now.

Copy link
Collaborator

@saubyk saubyk left a comment

Choose a reason for hiding this comment

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

Tested three scenarios:

  1. Regular channel, default confirmations required for active is 3. confirmations_until_active value in pendingchannels response tracks, until the channel is active. Test pass.
  2. Wumbo channel, default confirmations required for active is 6. confirmations_until_active value in pendingchannels response tracks, until the channel is active. Test pass.
  3. Updated the node config with bitcoin.defaultchanconfs=4. confirmations_until_active value in pendingchannels response doesn't track. It still starts off with a value of 3 (should start with 4) and channels gets active after 3 confirmations. Test fail.

Don't think that the issue with last scenario has been introduced with this change. But it would be good to investigate further why the setting in config is not having any bearing on the default behavior.

@NishantBansal2003
Copy link
Contributor Author

3. Updated the node config with bitcoin.defaultchanconfs=4. confirmations_until_active value in pendingchannels response doesn't track. It still starts off with a value of 3 (should start with 4) and channels gets active after 3 confirmations. Test fail.

I checked this locally and it works for me. I have also added an itest for this case. Not entirely sure, but it seems like you might have missed what bitcoin.defaultchanconfs means is "We'll require any incoming channel requests to wait for this many confirmations before we consider the channel active."

So:

  • Alice -> Bob (the confirmations_until_active starts off with a value of Bob's defaultchanconfs)
  • Bob -> Alice (the confirmations_until_active starts off with a value of Alice's defaultchanconfs)

@saubyk
Copy link
Collaborator

saubyk commented Apr 14, 2025

  1. Updated the node config with bitcoin.defaultchanconfs=4. confirmations_until_active value in pendingchannels response doesn't track. It still starts off with a value of 3 (should start with 4) and channels gets active after 3 confirmations. Test fail.

I checked this locally and it works for me. I have also added an itest for this case. Not entirely sure, but it seems like you might have missed what bitcoin.defaultchanconfs means is "We'll require any incoming channel requests to wait for this many confirmations before we consider the channel active."

So:

  • Alice -> Bob (the confirmations_until_active starts off with a value of Bob's defaultchanconfs)
  • Bob -> Alice (the confirmations_until_active starts off with a value of Alice's defaultchanconfs)

Good clarification. Tested again by updating the peer's setting and was able to get the correct values for confirmations_until_active.

Copy link
Collaborator

@saubyk saubyk left a comment

Choose a reason for hiding this comment

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

Great work. tAck.
Code review needs approval from two other devs.

cc: @kaloudis would you like to test this pr and provide some feedback?

Copy link
Collaborator

@ziggie1984 ziggie1984 left a comment

Choose a reason for hiding this comment

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

Thanks for picking this issue up 👍.

Nice work so far, the direction is the right one, left some comments for you.

// database once the channel opening transaction receives one
// confirmation. This enables us to calculate the number of
// confirmations before the pending channel becomes active.
if !ch.IsZeroConf() {
Copy link
Collaborator

Choose a reason for hiding this comment

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

This is not necessary, for can use the function waitForFundingConfirmation to update the short channel id.


// ConfirmationsUntilActive field should decrease as each block is
// mined until the required number of confirmations is reached. Let's
// mine a few empty blocks and verify the value of
Copy link
Collaborator

Choose a reason for hiding this comment

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

we should mine normal blocks here, because there is no tx in the mempool anyways ?

// mined until the required number of confirmations is reached. Let's
// mine a few empty blocks and verify the value of
// ConfirmationsUntilActive at each step.
for i := int32(1); i < numConfs; i++ {
Copy link
Collaborator

Choose a reason for hiding this comment

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

I think for these cases a reverse loop fits better:

// we could also decrease the numConfs immediately when confirming the tx above which is maybe even better.

for i := numConfs-1; i > 0; i-- {
		expectedConfirmationsLeft := i

//
// "Active" here means both channel peers have the channel marked OPEN
// and can immediately start using it. For public channels, this does
// not imply a channel_announcement has been gossiped—it only becomes
Copy link
Collaborator

Choose a reason for hiding this comment

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

Nit: gossiped-it => gossiped. It ...

@@ -877,6 +877,114 @@ func testFundingExpiryBlocksOnPending(ht *lntest.HarnessTest) {
ht.MineBlocksAndAssertNumTxes(1, 1)
}

// testConfirmationsUntilActiveOnPending verifies that as a channel status
Copy link
Collaborator

Choose a reason for hiding this comment

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

Nit: testConfirmationsUntilActiveOnPending => testPendingChannelConfirmationUntilActive verifies the value for the rpc filed ConfirmationUntilActive decreases as expected as soon as blocks are confirmed.

)

// Mine the first block containing the funding transaction, This
// confirms the funding transaction but does not change the channel
Copy link
Collaborator

Choose a reason for hiding this comment

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

Nit: confirms the funding transaction but the channel should still remain pending ...

require.NoError(t, err, "unable to mark channel's confirmation height")

// Ensure the channel remains pending after confirmation.
require.True(t, pendingChannels[0].IsPending, "channel should remain "+
Copy link
Collaborator

Choose a reason for hiding this comment

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

Q: Not sure if this case here makes sense, because the confirmation height is not related to the pending status directly.

)

// Confirm the channel remains pending after refresh.
require.True(t, channelState.IsPending, "channel should remain "+
Copy link
Collaborator

Choose a reason for hiding this comment

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

See comment above.

Copy link
Collaborator

@ziggie1984 ziggie1984 left a comment

Choose a reason for hiding this comment

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

Thank you for finalizing this PR, had some final nits.

@ziggie1984
Copy link
Collaborator

/gemini review

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

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

Code Review

This pull request introduces a mechanism to track the confirmation count for pending channels, exposing this information via the PendingChannels RPC. This is achieved by persisting the confirmation height of the funding transaction and modifying the chain notifier to provide more detailed transaction updates. The changes are well-tested, including new unit and integration tests that cover the new functionality and edge cases like reorgs. My review includes a suggestion to refactor a duplicated code block for better maintainability and a fix for a minor bug in a new test case.

@NishantBansal2003
Copy link
Contributor Author

didn't test a reorg

should I add an itest for this? I'm not sure if there's a way to do it in itest, but I can check/implement if possible.

@ziggie1984
Copy link
Collaborator

should I add an itest for this?

I don't think it is super important for this feature, however if you are interested you can look at testOpenChannelAfterReorg how to design a reorg test.

@NishantBansal2003
Copy link
Contributor Author

I don't think it is super important for this feature, however if you are interested you can look at testOpenChannelAfterReorg how to design a reorg test.

while working on this, I found a critical bug (in this PR) that occurs during a reorg -- the NegativeConf notification is only sent if the Confirmed notification has already been sent. So, if a reorg happens before the channel becomes active, NegativeConf won't be sent. As a result, even after one confirmation we won't be able to reset ConfirmationHeight. Later, when the funding tx is confirmed again, ConfirmationHeight will not be updated because of the if completeChan.ConfirmationHeight == 0 check, so we'll end up with incorrect data.

@ziggie1984
Copy link
Collaborator

while working on this, I found a critical bug (in this PR) that occurs during a reorg -- the NegativeConf notification is only sent if the Confirmed notification has already been sent. So, if a reorg happens before the channel becomes active, NegativeConf won't be sent. As a result, even after one confirmation we won't be able to reset ConfirmationHeight. Later, when the funding tx is confirmed again, ConfirmationHeight will not be updated because of the if completeChan.ConfirmationHeight == 0 check, so we'll end up with incorrect data.

Perfect, also a reminder to always test ! So let's fix the problem can you push the itest.

@ziggie1984
Copy link
Collaborator

I think we just need to make a litter change here:

// dispatchConfReorg dispatches a reorg notification to the client if the
// confirmation notification was already delivered.
//
// NOTE: This must be called with the TxNotifier's lock held.
func (n *TxNotifier) dispatchConfReorg(ntfn *ConfNtfn,
	heightDisconnected uint32) error {

	// If the request's confirmation notification has yet to be dispatched,
	// we'll need to clear its entry within the ntfnsByConfirmHeight index
	// to prevent from notifying the client once the notifier reaches the
	// confirmation height.
	if !ntfn.dispatched {
		confHeight := heightDisconnected + ntfn.NumConfirmations - 1
		ntfnSet, exists := n.ntfnsByConfirmHeight[confHeight]

		// We also signal the reorg to the notifier in case the
		// subscriber is also interested in the reorgs before the
		// transaction received it required confirmation.
		//
		// Because as soon as a new block is connected which has the
		// transaction included again we preemptively read the buffered
		// channel.
		select {
		case ntfn.Event.NegativeConf <- int32(n.reorgDepth):
		case <-n.quit:
			return ErrTxNotifierExiting
		}

		if exists {
			delete(ntfnSet, ntfn)
		}
		return nil
	}

	// Otherwise, the entry within the ntfnsByConfirmHeight has already been
	// deleted, so we'll attempt to drain the confirmation notification to
	// ensure sends to the Confirmed channel are always non-blocking.
	select {
	case <-ntfn.Event.Confirmed:
	case <-n.quit:
		return ErrTxNotifierExiting
	default:
	}

	ntfn.dispatched = false

	// Send a negative confirmation notification to the client indicating
	// how many blocks have been disconnected successively.
	select {
	case ntfn.Event.NegativeConf <- int32(n.reorgDepth):
	case <-n.quit:
		return ErrTxNotifierExiting
	}

	return nil
}

@saubyk saubyk added this to lnd v0.20 Sep 9, 2025
@saubyk saubyk removed this from lnd v0.20 Sep 9, 2025
@ziggie1984
Copy link
Collaborator

@NishantBansal2003 please be aware that we prioritized this for LND20, are you able to fix the underlying issue in the next days ? Otherwise we move it into LND 21

@NishantBansal2003
Copy link
Contributor Author

Oops, apologies, everything is done locally, only my testing remains. I will test and push by the end of today (IST timezone)

Copy link
Collaborator

@ziggie1984 ziggie1984 left a comment

Choose a reason for hiding this comment

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

Pending CI, otherwise excellent work, LGTM 🎉

Copy link
Collaborator

@bitromortac bitromortac left a comment

Choose a reason for hiding this comment

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

re-ACK, thank you for adding the reorg itest 🙏

Comment on lines 1100 to 1101
// Cleanup by mining the remaining blocks to reach the required number
// of confirmations, then closing the channel.
Copy link
Collaborator

Choose a reason for hiding this comment

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

nit: comment doesn't reflect the behavior

Comment on lines +2019 to +2036
// Because as soon as a new block is connected which has the
// transaction included again we preemptively read the buffered
// channel.
select {
case ntfn.Event.NegativeConf <- int32(n.reorgDepth):
Copy link
Collaborator

Choose a reason for hiding this comment

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

So this doesn't block because we will only send on the channel once on reorg of the funding tx's block and it will be emptied by ConnectTip -> handleConfDetailsAtTip

In this commit, we send the reorg notification even when the
transaction has not yet reached the required confirmations, in
case the caller is interested in knowing about it.

Signed-off-by: Nishant Bansal <[email protected]>
Enhance the ConfirmationEvent's Updates channel by including the
BlockHeight alongside NumConfsLeft.

Signed-off-by: Nishant Bansal <[email protected]>
Add the MarkConfirmationHeight method to the OpenChannel struct
to record the block height at which the funding transaction was
first confirmed. Also, introduce the ConfirmationHeight field
to persist this information in the database.

Signed-off-by: Nishant Bansal <[email protected]>
This change ensures that a channel's ConfirmationHeight is recorded in the
database once its funding transaction receives its initial confirmation.
By doing so, we establish a reliable reference point to monitor the
channel's progress toward the required confirmation depth.

Signed-off-by: Nishant Bansal <[email protected]>
Introduce ConfirmationsUntilActive and ConfirmationHeight in
PendingChannelsResponse_PendingChannel. ConfirmationsUntilActive indicates
the remaining confirmations needed for the channel to become active. If the
funding transaction is unconfirmed, ConfirmationsUntilActive defaults to the
total required confirmations (NumConfsRequired). ConfirmationHeight records
the block height at which the funding transaction was first confirmed; if
unconfirmed, it will be 0.

Signed-off-by: Nishant Bansal <[email protected]>
Signed-off-by: Nishant Bansal <[email protected]>
@yyforyongyu yyforyongyu merged commit 5082566 into lightningnetwork:master Sep 11, 2025
34 of 39 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[feature]: Expose negotiated confirmation count for pending 'channel open' transactions
7 participants