Add `AuxHtlcValidator`

[GeorgeTsagk]

Description

Updates the lightning channel to query the TrafficShaper bandwidth once more before adding the HTLC to the channel state. During pathfinding, the reported payment bandwidth could be stale, as it may have not accounted for HTLCs that have not yet been added to the channel state (i.e the aux htlc view).

By querying the aux bandwidth once more, right before the HTLC is added to the channel state, we ensure that no race condition can lead to unexpected failures due to insufficient balance.

[gemini-code-assist[bot]]

Summary of Changes

Hello @GeorgeTsagk, I'm Gemini Code Assist[^1]! 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 introduces a robust mechanism to enhance the reliability of HTLC additions within Lightning channels. It addresses a potential race condition where payment bandwidth calculations could become outdated by implementing a new AuxHtlcValidator. This validator performs a final, real-time check against the channel's most current state, leveraging the TrafficShaper to ensure that HTLCs are only processed when adequate balance is confirmed, thereby preventing unexpected failures due to insufficient funds.

Highlights

• New HTLC Validation Mechanism: Introduced an AuxHtlcValidator interface and associated functionality within the lnwallet package. This allows for an additional, custom validation step for HTLCs just before they are added to the channel state.
• Race Condition Mitigation: The primary goal of this change is to prevent race conditions where the reported payment bandwidth might be stale. By performing a final validation check against the most up-to-date channel state, including pending HTLCs, it ensures that HTLCs are only added if sufficient balance is truly available.
• Traffic Shaper Integration: The peer/brontide.go component now integrates with this new validation mechanism. It creates an AuxHtlcValidator that queries the TrafficShaper's PaymentBandwidth method, providing the most current channel state and HTLC details for a precise bandwidth check.
• Configurable Validation: The AuxHtlcValidator is an optional component, configured via ChannelOpts, allowing for flexible integration with external systems like the TrafficShaper without altering core channel logic.

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 :thumbsup: and :thumbsdown: 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.

[^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.

[GeorgeTsagk]

My gut reaction: can we get rid of some of the extra calls that validate this elsewhere (eg: switch method calls into the link to check if an HTLC is ready for transit) if we're adding this additional layer of protection?

We definitely need more than 1 call sites per operation (forward / payment) as we need to first quickly gauge if enough funds exist to go ahead with the operation, then verify things one last time before committing it to the channel.

The aux bandwidth calls though seem to be a bit intertwined. By adding the AuxHtlcValidator we end up calling the PaymentBandwidth a total of 6 times (previous was 4). We definitely need to trim some of those call sites.

Will update PR soon