Skip to content

rpc: add channel updates to SubscribeChannelEvents#10543

Open
bitromortac wants to merge 8 commits intolightningnetwork:masterfrom
bitromortac:2602-channel-update-events
Open

rpc: add channel updates to SubscribeChannelEvents#10543
bitromortac wants to merge 8 commits intolightningnetwork:masterfrom
bitromortac:2602-channel-update-events

Conversation

@bitromortac
Copy link
Collaborator

Change Description

This PR extends the SubscribeChannelEvents RPC to emit the channel state when we receive a CommitSig for the local commitment. This can be useful to track the exact available balances at each point in time. I have considered to update routerrpc.SubscribeHtlcEvents with channel balances, but I think it isn't that clean and channel update events could also be emitted if channel constraints or the channel type changes (dynamic commitments).

There is a little cost to this code as we have to make a copy of the channel state to transport it to the RPC. I decided to make a copy of channeldb.OpenChannel as I wanted to reuse the mashal helper createRPCOpenChannel and the lnrpc.Channel type (which is also used for ListChannels).

We create a deep copy of the channel state as we want to later expose
the data structure to the rpc, which already has helper methods to
marshal this representation to the rpc representation.
@gemini-code-assist
Copy link

Summary of Changes

Hello @bitromortac, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the SubscribeChannelEvents RPC by introducing a mechanism to broadcast real-time updates of a channel's state. This allows external services and users to monitor the precise evolution of channel balances and other critical parameters as new commitments are signed. The changes involve adding robust deep-copying capabilities for channel data structures, integrating these notifications into the core channel processing logic, and updating the RPC definitions to expose this new event type.

Highlights

  • Extended RPC for Channel Updates: The SubscribeChannelEvents RPC has been extended to emit channel state updates, allowing clients to track real-time changes in channel balances and other parameters.
  • Deep Copy Mechanism for Channel State: New copy() methods have been added to ChannelCommitment and OpenChannel structs in channeldb to ensure that a deep copy of the channel state is provided to RPC subscribers, preventing unintended modifications.
  • New Channel Update Event Type: A ChannelUpdateEvent has been introduced in the channelnotifier package, along with a corresponding notification function, to signal when a channel's state has been updated.
  • Integration with Commitment Signing: Channel update notifications are now triggered in htlcswitch after a CommitSig is successfully processed, ensuring that subscribers are informed when a new local commitment is established.
  • RPC and Protocol Buffer Updates: The lightning.proto and lightning.swagger.json files have been updated to include a new ChannelCommitUpdate message and a CHANNEL_UPDATE event type, enabling the new functionality in the RPC interface.
  • Comprehensive Integration Test: A new integration test, testChannelUpdateNotifications, has been added to verify that channel update events are correctly emitted and received by subscribers during channel operations, including payments.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog
  • channeldb/channel.go
    • Added copy() methods for ChannelCommitment and OpenChannel to create deep copies of channel states.
  • channelnotifier/channelnotifier.go
    • Introduced ChannelUpdateEvent struct to represent channel state updates.
    • Added NotifyChannelUpdateEvent function to send channel update notifications.
  • channelnotifier/channelnotifier_test.go
    • Added TestChannelUpdateEvent to verify the proper notification of channel update events.
  • docs/release-notes/release-notes-0.21.0.md
    • Updated release notes to document the new SubscribeChannelEvents functionality for channel updates.
    • Added bitromortac to the list of contributors.
  • htlcswitch/link.go
    • Added NotifyChannelUpdate field to ChannelLinkConfig.
    • Integrated NotifyChannelUpdate call after processing lnwire.CommitSig to emit channel state updates.
  • itest/lnd_open_channel_test.go
    • Added testChannelUpdateNotifications to verify channel update event notifications during channel operations.
  • lnrpc/lightning.proto
    • Defined ChannelCommitUpdate message to encapsulate updated channel information.
    • Added updated_channel field and CHANNEL_UPDATE enum value to ChannelEventUpdate.
  • lnrpc/lightning.swagger.json
    • Updated Swagger definition to include lnrpcChannelCommitUpdate and CHANNEL_UPDATE event type.
  • lntest/harness_assertion.go
    • Added AssertChannelEventType helper function for asserting channel event types in tests.
  • lnwallet/channel.go
    • Added ChannelState() method to LightningChannel to return a deep copy of the underlying OpenChannel state.
  • peer/brontide.go
    • Configured NotifyChannelUpdateEvent in ChannelLinkConfig when adding a new channel link.
  • rpcserver.go
    • Modified SubscribeChannelEvents to handle channelnotifier.ChannelUpdateEvent and send lnrpc.ChannelCommitUpdate to subscribers.
Activity
  • The pull request introduces a new feature to provide real-time channel state updates via RPC.
  • It involves significant changes across multiple core components, including channel database, notification system, HTLC switch, wallet, and RPC definitions.
  • New deep-copying logic has been implemented to ensure data integrity when exposing internal channel states.
  • A dedicated integration test has been added to validate the end-to-end functionality of the new channel update notifications.
  • The release notes have been updated to reflect this new user-facing capability.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

@lightninglabs-deploy
Copy link
Collaborator

🔴 PR Severity: CRITICAL

rpc: add channel updates to SubscribeChannelEvents | 13 files | 3249 additions, 2823 deletions

🔴 Critical (5 files)
  • channeldb/channel.go - Channel state persistence, database operations
  • htlcswitch/link.go - HTLC forwarding state machine modifications
  • lnwallet/channel.go - Core wallet channel operations
  • peer/brontide.go - Encrypted peer connection handling
  • rpcserver.go - Core server RPC coordination
🟠 High (1 file)
  • lnrpc/lightning.proto - RPC API definition changes
  • channelnotifier/channelnotifier.go - Channel event notification system
🟢 Low (5 files)
  • lnrpc/lightning.pb.go - Auto-generated protobuf code
  • lnrpc/lightning.swagger.json - Auto-generated swagger
  • docs/release-notes/release-notes-0.21.0.md - Documentation
  • channelnotifier/channelnotifier_test.go - Test file
  • itest/lnd_open_channel_test.go - Integration test
  • lntest/harness_assertion.go - Test helper

Analysis

This PR is classified as CRITICAL because it modifies multiple core critical components:

  1. Channel State Persistence (channeldb/channel.go): Changes to how channel state is stored and retrieved from the database require careful review to prevent data corruption or loss.

  2. HTLC State Machine (htlcswitch/link.go): Modifications to the HTLC forwarding logic are high-risk as they affect payment routing correctness.

  3. Wallet Channel Operations (lnwallet/channel.go): Core wallet functionality changes need expert review to ensure fund safety.

  4. Multiple Critical Packages: The PR touches 5 distinct critical packages (channeldb, htlcswitch, lnwallet, peer, rpcserver), which increases the complexity and risk surface.

  5. RPC API Changes: The proto file changes indicate new API surface area that needs to be carefully validated for backward compatibility and correctness.

The PR adds channel update events to the subscription system, which involves coordination across the entire stack from database to RPC layer. This requires expert review from engineers familiar with the channel event notification architecture and state management.


To override, add a severity-override-{critical,high,medium,low} label.

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

The pull request introduces a new ChannelUpdateEvent and associated notification mechanism to SubscribeChannelEvents. This allows subscribers to receive real-time updates when a channel's state changes, specifically after a CommitSig is processed. The implementation correctly utilizes deep copy methods (copy() for ChannelCommitment and Copy() for OpenChannel) to ensure that channel state passed through events is immutable, preventing potential race conditions and data inconsistencies. New integration tests (testChannelUpdateNotifications) have been added to verify the functionality of these new events. Overall, the changes are well-implemented and adhere to good practices for managing shared state in concurrent environments.

@bitromortac bitromortac force-pushed the 2602-channel-update-events branch from e5126e8 to cb1ab9a Compare February 3, 2026 19:05
@lightninglabs-deploy
Copy link
Collaborator

🔴 PR Severity: CRITICAL

Automated classification | 15 files | 3,252 lines added, 2,823 deleted

🔴 Critical (5 files)
  • channeldb/channel.go - Channel state persistence (99 additions)
  • lnwallet/channel.go - Wallet operations (7 additions)
  • htlcswitch/link.go - HTLC forwarding state machine (11 additions)
  • peer/brontide.go - Encrypted peer connections (1 addition)
  • rpcserver.go - Core server coordination (18 additions)
🟠 High (3 files)
  • lnrpc/lightning.proto - RPC/API definitions (6 additions)
  • lnrpc/lightning.pb.go - Auto-generated protobuf code (2,911 additions, 2,822 deletions)
  • lnrpc/lightning.swagger.json - Auto-generated API spec (13 additions, 1 deletion)
🟢 Low (7 files)
  • docs/release-notes/release-notes-0.21.0.md - Release notes
  • channelnotifier/channelnotifier.go - Channel event notifications (17 additions)
  • channelnotifier/channelnotifier_test.go - Test file
  • htlcswitch/link_test.go - Test file
  • htlcswitch/test_utils.go - Test utilities
  • itest/lnd_open_channel_test.go - Integration test
  • lntest/harness_assertion.go - Test harness

Analysis

This PR adds channel update notifications to the SubscribeChannelEvents RPC. The CRITICAL severity is assigned because:

  1. Multiple critical subsystems touched: This PR modifies core components across channeldb, lnwallet, htlcswitch, peer/brontide, and rpcserver - all of which are critical to LND's operation.

  2. Channel state persistence changes: Modifications to channeldb/channel.go (99 lines) require careful review as they affect how channel state is stored and retrieved.

  3. HTLC forwarding logic: Changes to htlcswitch/link.go touch the payment routing state machine.

  4. API surface expansion: The proto changes add new RPC functionality that will be exposed to external clients.

While the individual changes appear focused on adding event notification functionality, the breadth of critical systems involved warrants expert review to ensure:

  • Channel state updates are correctly persisted and propagated
  • Event notifications don't introduce race conditions
  • The new RPC behavior is properly synchronized with channel lifecycle events

To override, add a severity-override-{critical,high,medium,low} label.

@bitromortac bitromortac force-pushed the 2602-channel-update-events branch from cb1ab9a to b7c9c42 Compare February 4, 2026 11:02
@lightninglabs-deploy
Copy link
Collaborator

🔴 PR Severity: CRITICAL

rpc: add channel updates to SubscribeChannelEvents | 16 files | 3255 lines added, 2823 deleted

🔴 Critical (5 files)
  • channeldb/channel.go - Channel state persistence modifications (99 lines)
  • htlcswitch/link.go - HTLC forwarding state machine changes (11 lines)
  • lnwallet/channel.go - Wallet operations modifications (7 lines)
  • peer/brontide.go - Peer connection handling (1 line)
  • rpcserver.go - Core server coordination (18 lines)
🟠 High (1 file)
  • channelnotifier/channelnotifier.go - Channel event notification system (17 lines)
🟡 Medium (1 file)
  • lnrpc/lightning.proto - RPC API definition changes (6 lines)
🟢 Low/Test/Generated (9 files)
  • lnrpc/lightning.pb.go - Auto-generated protobuf code (2911 additions, 2822 deletions)
  • lnrpc/lightning.swagger.json - Auto-generated Swagger documentation
  • channelnotifier/channelnotifier_test.go - Test file
  • htlcswitch/link_test.go - Test file
  • htlcswitch/test_utils.go - Test utilities
  • itest/list_on_test.go - Integration test
  • itest/lnd_open_channel_test.go - Integration test (99 lines)
  • lntest/harness_assertion.go - Test harness utilities
  • docs/release-notes/release-notes-0.21.0.md - Release notes

Analysis

This PR is classified as CRITICAL due to modifications across multiple core critical packages:

  1. Channel State Management: Changes to channeldb/channel.go involve channel state persistence, which is fundamental to channel operation safety.

  2. HTLC Switch: Modifications to htlcswitch/link.go affect the HTLC forwarding state machine, which handles payment routing and is critical for funds safety.

  3. Wallet Layer: Changes to lnwallet/channel.go touch wallet-level channel operations.

  4. RPC Server: Updates to rpcserver.go modify core server coordination logic.

  5. Peer Management: Even the single line in peer/brontide.go involves peer connection handling.

The PR extends the SubscribeChannelEvents RPC to emit channel state when receiving CommitSig messages for local commitments. While the feature itself is an enhancement to observability, the implementation touches multiple critical subsystems where bugs could lead to:

  • Incorrect channel state reporting
  • Potential race conditions in state copying
  • Performance impacts on the HTLC switch
  • Memory pressure from channel state copying

Recommendation: This PR requires expert review from engineers familiar with channel state management, the HTLC switch, and the channel notification system. Special attention should be paid to:

  • Thread safety of the channel state copying mechanism
  • Performance impact of copying channel state on every CommitSig
  • Correctness of the emitted channel balance information
  • Integration between the link, wallet, and notification layers

To override, add a severity-override-{critical,high,medium,low} label.

@saubyk saubyk added this to v0.21 Feb 5, 2026
@saubyk saubyk moved this to In progress in v0.21 Feb 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In progress

Development

Successfully merging this pull request may close these issues.

2 participants