lnwallet: surface initial commitment key ring for N=0 force-close aux resolution

[GeorgeTsagk]

Description

This PR adds InitialKeyRing to lnwallet.ResolutionReq and populates it only when local commit height is 0 during force-close resolution. It gives aux resolvers the correct initial commitment key context for immediate post-funding (N=0) force closes, while leaving later commit-height force-close behavior unchanged (InitialKeyRing=nil).

At N=0, the commitment output keys are derived from the initial commitment point (pre-channel_ready rotation), so using only the live key ring can misidentify outputs and break the aux components.

[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 introduces a mechanism to provide auxiliary resolvers with the initial commitment key ring for channels that are force-closed at height 0. By correctly identifying the commitment keys used before the channel_ready rotation, the changes prevent output misidentification and ensure that auxiliary components function correctly during immediate post-funding force-close events.

Highlights

• Resolution Request Update: Added an InitialKeyRing field to the ResolutionReq struct to support auxiliary resolvers during force-close scenarios.
• Key Derivation Logic: Implemented initialCommitmentKeyRingFromState to derive the correct commitment keys for channels at height 0, distinguishing them from post-channel_ready states.
• Force-Close Integration: Updated NewLocalForceCloseSummary to populate the InitialKeyRing when the local commitment height is 0, ensuring aux resolvers have the necessary context.

New Features

🧠 You can now enable Memory (public preview) 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.

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 the 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 counterproductive. 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.

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

[github-actions]

🔴 PR Severity: CRITICAL

Automated classification | 2 files | 61 lines changed

🔴 Critical (2 files)

• lnwallet/aux_resolutions.go - wallet auxiliary resolution logic (lnwallet/*)
• lnwallet/channel.go - core channel state machine and commitment transaction handling (lnwallet/*)

Analysis

Both changed files reside in the lnwallet package, which is classified as CRITICAL because it encompasses wallet operations, channel funding, signing, and commitment transaction logic — among the most security-sensitive code in the Lightning Network Daemon.

• lnwallet/channel.go is the central channel state machine; changes here can affect commitment transaction construction, fee handling, and the correctness of channel updates.
• lnwallet/aux_resolutions.go handles auxiliary (e.g. custom channel) resolution paths, which feed into on-chain fund recovery.

This PR is small in scope (2 files, 61 lines), so no severity bump was triggered. However, the inherent criticality of lnwallet means expert review is required before merging.

---

_{To override, add a severity-override-{critical,high,medium,low} label.}
<!-- pr-severity-bot -->

[gemini-code-assist]

Code Review

This pull request introduces an InitialKeyRing field to the ResolutionReq struct and implements initialCommitmentKeyRingFromState to derive the key ring for the initial commitment state at height 0. This allows downstream resolvers to correctly distinguish between initial and subsequent commitment states. The reviewer suggested minor documentation improvements to adhere to the repository's style guide, specifically regarding function comment formatting and the requirement for function documentation.

[gemini-code-assist]

The function comment should start with the function's name (initialCommitmentKeyRingFromState) to adhere to the repository's style guide.

Suggested change

	// initialCommitmentKeyRing derives the key ring for the initial commitment
	// initialCommitmentKeyRingFromState derives the key ring for the initial commitment

References

1. Function comments must begin with the function name. ^(link)

[gemini-code-assist]

This function is missing a comment, which is required by the repository's style guide. Please add a comment that describes its purpose.

Suggested change

	func (lc *LightningChannel) initialCommitmentKeyRing(
	whoseCommit lntypes.ChannelParty) *CommitmentKeyRing {
	return initialCommitmentKeyRingFromState(lc.channelState, whoseCommit)
	}
	// initialCommitmentKeyRing derives the key ring for the initial commitment
	// state at height 0 for the channel.
	func (lc *LightningChannel) initialCommitmentKeyRing(
	whoseCommit lntypes.ChannelParty) *CommitmentKeyRing {
	return initialCommitmentKeyRingFromState(lc.channelState, whoseCommit)
	}

References

1. Every function must be commented with its purpose and assumptions. ^(link)