multi: expose local and remote spendable balance in listchannels

[Euler-B]

Change Description

This PR addresses the request to expose the actual "spendable" balance in the listchannels RPC.
Currently, local_balance and remote_balance only show total funds, not considering:

• Channel reserves (ChanReserve).
• Commitment fees (paid by the initiator).
• The cost of adding new HTLCs.

Fixes: #4951

Steps to Test

1. Automated Tests:

$ go test -v -run "TestChanRemoteAvailableBalance|TestApplyCommitmentFee" github.com/lightningnetwork/lnd/lnwallet

3. Manual: Build with make install and verify local_spendable_msat in lncli listchannels.

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

• The change is not insubstantial. Typo fixes are not accepted to fight bot spam.
• The change obeys the Code Documentation and Commenting guidelines, and lines wrap at 80.
• Commits follow the Ideal Git Commit Structure.
• Any new logging statements use an appropriate subsystem and logging level.
• Any new lncli commands have appropriate tags in the comments for the rpc in the proto file.
• There is a change description in the release notes, or [skip ci] in the commit message for small changes.

📝 Please see our Contribution Guidelines for further guidance.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! 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 improves the listchannels RPC by providing a more precise and actionable view of channel liquidity. By introducing new fields that account for channel reserves, commitment fees, and potential HTLC costs, users can now accurately determine the actual amount of funds available for immediate spending or forwarding, both locally and by the remote peer. This enhancement addresses a long-standing request to move beyond simple total balance reporting, offering a more realistic and useful metric for channel management.

Highlights

• New RPC Fields for Spendable Balance: Introduced local_spendable_msat and remote_spendable_msat fields to the Channel message in the listchannels RPC response. These fields provide a more accurate representation of funds available for sending by factoring in channel reserves and commitment fees.
• Remote Bandwidth Calculation: Implemented a new RemoteBandwidth() method within the ChannelLink interface and its concrete types to expose the remote party's available bandwidth, considering their reserves and commitment fees.
• Refactored Balance Logic: Refactored the internal channel balance calculation logic to be more generic, allowing for accurate determination of spendable balances from both local and remote perspectives, and updated the applyCommitFee function to explicitly handle initiator status.

🧠 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

• htlcswitch/interfaces.go
  • Added RemoteBandwidth() method to the ChannelUpdateHandler interface.
  • Updated the comment for the existing Bandwidth() method to clarify its scope for the local party.
• htlcswitch/link.go
  • Implemented the RemoteBandwidth() method for the channelLink type, which returns the remote party's available balance.
• htlcswitch/mock.go
  • Added a mock implementation for the RemoteBandwidth() method to the mockChannelLink type.
  • Updated the comment for the existing Bandwidth() method.
• lnrpc/lightning.proto
  • Added local_spendable_msat and remote_spendable_msat fields to the Channel message, including detailed descriptions of their calculation.
• lnrpc/lightning.swagger.json
  • Updated the Swagger definition to include the newly added local_spendable_msat and remote_spendable_msat fields in the Channel object.
• lnwallet/channel.go
  • Modified the applyCommitFee function to accept an isInitiator boolean parameter, allowing for more flexible fee application logic.
  • Introduced RemoteAvailableBalance() to calculate the remote party's spendable balance.
  • Refactored the balance calculation logic into a new generic function availableBalanceGeneric to handle both local and remote perspectives, reducing code duplication.
  • Adjusted availableCommitmentBalance to use the new generic balance calculation and correctly apply reserves and fees based on the isRemote and initiator flags.
• lnwallet/channel_test.go
  • Added TestChanRemoteAvailableBalance to thoroughly test the accuracy of the RemoteAvailableBalance calculation.
  • Updated calls to applyCommitFee in existing tests to pass the new isInitiator parameter.
  • Modified TestChanCommitWeightDustHtlcs to pass the isRemote parameter to availableCommitmentBalance.
• rpcserver.go
  • Updated the createRPCOpenChannel function to retrieve and populate the LocalSpendableMsat and RemoteSpendableMsat fields in the Channel RPC response using the new Bandwidth() and RemoteBandwidth() methods from the htlcSwitch link.

Activity

• No specific activity (comments, reviews, or progress updates) was provided in the context.

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. ↩

[gemini-code-assist]

Code Review

This pull request successfully exposes the local and remote spendable balances in the listchannels RPC. The core of the change is a significant but well-executed refactoring in lnwallet/channel.go to create a generic balance calculation logic applicable to both local and remote parties. The new test case, TestChanRemoteAvailableBalance, is thorough and provides good coverage for the new logic. The changes to the RPC layer are consistent with the core modifications. I have a couple of minor suggestions related to code comments to improve documentation clarity and adhere to the style guide.

_{Note: Security Review is unavailable for this PR.}

[Euler-B]

Hi @ziggie1984. I've updated the PR to address the latest feedback and fixed the linting issues. This is my current approach to solve Issue #4951

[github-actions]

🔴 PR Severity: CRITICAL

File classification | 12 files | 429 lines changed (307 lines / 9 files excluding tests & auto-generated)

🔴 Critical (6 files)

• htlcswitch/interfaces.go - htlcswitch/* (HTLC forwarding/payment routing state machine interfaces)
• htlcswitch/link.go - htlcswitch/* (HTLC forwarding link logic)
• htlcswitch/mock.go - htlcswitch/* (package file; does not match mock exclusion patterns mock_*.go/*_mock.go)
• lnwallet/channel.go - lnwallet/* (channel state, commitment transactions)
• peer/test_utils.go - peer/* (encrypted peer connection support code; filename doesn't match *_test.go exclusion pattern)
• rpcserver.go - explicitly listed core server coordination file

🟠 High (3 files)

• lnrpc/lightning.pb.go - lnrpc/* generated gRPC bindings (excluded from line/file counts as auto-generated)
• lnrpc/lightning.proto - lnrpc/* RPC/API definition
• lnrpc/lightning.swagger.json - lnrpc/* swagger API spec

🟢 Low (3 files)

• docs/release-notes/release-notes-0.20.1.md - release notes
• lnwallet/channel_test.go - test-only change
• peer/brontide_test.go - test-only change

Analysis

The highest-severity files touched are in htlcswitch/* (HTLC forwarding state machine), lnwallet/* (channel/commitment transaction logic), peer/* (encrypted peer connection support), and rpcserver.go (core server coordination) — all of which fall under the CRITICAL tier per policy. That alone sets the PR's baseline severity to CRITICAL.

For reference, this PR also touches multiple distinct critical packages (htlcswitch, lnwallet, peer, plus rpcserver.go), which would normally trigger a one-level severity bump — but since CRITICAL is already the highest tier, this has no further effect. File count (9) and line changes (307, excluding tests/generated code) are both well under the size-based bump thresholds (20 files / 500 lines), so those thresholds are not a factor here.

Given the changes to lnwallet/channel.go (commitment transaction / channel state logic) and htlcswitch/link.go (HTLC forwarding), this PR warrants expert review of channel state correctness and payment routing safety.

---

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

[saubyk]

/gateway review

[lightninglabs-gateway]

✅ Review posted: #10624 (review)

6 finding(s); 6 inline, 0 in body.

🔁 Need a re-review after pushing changes? Reply with /gateway re-review.
Maintainers can also /gateway dismiss <id> to silence specific findings, or anyone can /gateway explain <id> for elaboration.

[lightninglabs-gateway]

This PR exposes local/remote spendable balance in listchannels by adding RemoteAvailableBalance()/RemoteBandwidth() and refactoring lnwallet/channel.go's balance computation into a party-generic form. The intent and the reserve/dust/initiator mapping are sound, and the RPC/proto plumbing is consistent.

The refactor, however, silently changes the HTLC view used by the pre-existing AvailableBalance() path — it now folds in un-ACKed remote updates rather than only remote-ACKed ones. Because that value drives Bandwidth() on a high-reach HTLC-forwarding path, this is the primary concern and needs to be confirmed intentional or reverted. A secondary correctness/usability gap is that the new RPC fields silently report 0 for any channel without an active link, with no signal to the consumer.

Findings: 🔴 0 Blocker · 🟠 2 Major · 🟡 4 Minor · 🔵 0 Nit

[lightninglabs-gateway]

🤖 gateway audit metadata for this PR — auto-generated, please don't edit.

[litbot-9000]

@Euler-B, remember to re-request review from reviewers when ready

[litbot-9000]

@Euler-B, remember to re-request review from reviewers when ready

[litbot-9000]

@Euler-B, remember to re-request review from reviewers when ready

[litbot-9000]

@Euler-B, remember to re-request review from reviewers when ready