chanstate: introduce Store interface (PR 1 of channel-state decomposition) by ziggie1984 · Pull Request #10777 · lightningnetwork/lnd

ziggie1984 · 2026-04-28T18:13:16Z

Summary

First PR in the channel-state decomposition series. Introduces the
chanstate.Store interface as the seam between the channel-state subsystem
and its consumers, mirroring the pattern in invoices/, payments/db/, and
graph/db/. No consumer migrates, no data moves, no behavior changes.

Store is composed of two embedded sub-interfaces — ChannelStore for core
channel-state operations and InitialForwardingPolicyStore for the
per-channel forwarding policy chosen at channel-open time — so future
decomposition PRs can extend the contract without inflating a single
monolithic interface.

Four commits:

channeldb: drop unused kvdb.RTx parameter from FetchChannelByID —
prerequisite so the interface stays free of kvdb types. All four call
sites already pass nil.
chanstate: introduce Store interface — new package with Store and its
ChannelStore sub-interface, a package logger, and the compile-time
assertion var _ Store = (*channeldb.ChannelStateDB)(nil) that guards
against signature drift. GetParentDB (test-only) and LinkNodeDB
(separate domain) are intentionally excluded.
chanstate: add InitialForwardingPolicyStore sub-interface — adds the
second sub-interface for the initial-forwarding-policy methods, embedded
into Store.
docs: release note for chanstate Store interface — seeds the v0.22
"Native SQL migration of the channel state and switch data" series so
follow-up PRs (consumer swap, KV/SQL stores, revocation log, forwarding
package, etc.) hang off the same heading.

Test plan

go build ./... clean
Compile-time assertion catches any interface ↔ concrete drift
make unit pkg=channeldb and make lint pass

gemini-code-assist · 2026-04-28T18:13:33Z

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 initiates the decomposition of the channel-state management logic into a dedicated subsystem. By introducing the ChannelStore interface and implementing a deferred cleanup mechanism for bulk historical data, the changes prepare the codebase for future SQL-backed storage implementations while maintaining current performance and consistency guarantees.

Highlights

ChannelStore Interface: Introduced a new chanstate/ChannelStore interface to decouple the channel-state subsystem from the concrete channeldb.ChannelStateDB implementation, facilitating future SQL-backed storage.
Deferred Cleanup Mechanism: Implemented a two-phase channel closure process for SQL-backed backends, where bulk historical data deletion is deferred to startup to keep the synchronous close path performant.
API Cleanup: Removed the unused kvdb.RTx parameter from FetchChannelByID across all call sites to ensure the interface remains clean and free of database-specific types.

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

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.

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 introduces a deferred cleanup mechanism for closed channels on KV-over-SQL backends (SQLite and Postgres) to prevent long write-lock stalls during synchronous channel closure. The implementation splits the closure into two phases: Phase 1 atomically marks the channel as closed and removes it from open views, while Phase 2 defers the deletion of bulky historical data (revocation logs and forwarding packages) to the next startup. The PR also introduces a ChannelStore interface to abstract the persistence layer. Feedback focuses on improving the robustness of the cleanup queue by handling malformed records and ensuring that individual purge failures do not block the entire node startup process, as well as minor code simplifications.

gemini-code-assist · 2026-04-28T18:19:09Z

+		return cleanupBkt.ForEach(func(k, v []byte) error {
+			var op wire.OutPoint
+			if err := graphdb.ReadOutpoint(
+				bytes.NewReader(k), &op,
+			); err != nil {
+				log.Warnf("Skipping pending closed-channel "+
+					"cleanup with malformed "+
+					"chan_key=%x: %v", k, err)
+
+				return nil
+			}
+
+			rec, err := decodePendingCleanupRecord(v)
+			if err != nil {
+				log.Warnf("Skipping pending closed-channel "+
+					"cleanup for %v: unable to decode "+
+					"record: %v", op, err)
+
+				return nil
+			}
+
+			entries = append(entries, PendingCleanup{
+				ChanPoint: op,
+				Record:    rec,
+			})
+
+			return nil
+		})


Malformed cleanup records are skipped and logged but remain in the pendingChanCleanupBucket. This results in persistent log noise on every startup. Consider collecting the keys of malformed records and deleting them in a separate transaction to keep the cleanup queue healthy.

github-actions · 2026-05-04T22:07:41Z

🔴 PR Severity: CRITICAL

Auto-classified | 4 files | 195 lines changed

🔴 Critical (2 files)

channeldb/db.go - Channel state persistence (channeldb/*)
server.go - Core server coordination

🟡 Medium (2 files)

chanstate/interface.go - New unclassified package (chanstate/*)
chanstate/log.go - New unclassified package (chanstate/*)

Analysis

This PR is classified CRITICAL due to changes in two independently critical areas:

channeldb/db.go — The channeldb package manages channel state persistence and database operations. Any modification here can affect how channel state is read, written, or migrated, making it a high-risk area requiring expert review.
server.go — The core server coordination file is explicitly listed as a critical path. Changes here can affect the overall node lifecycle and component wiring.

The new chanstate package (156 lines added) introduces a new interface/abstraction for channel state. While it doesn't directly map to an existing critical package and is classified MEDIUM on its own, it is being integrated via channeldb/db.go and server.go, both of which are critical touchpoints. Reviewers should pay close attention to how this new abstraction interacts with the existing channel state machinery.

No severity bump triggers were met (4 non-test files, 195 lines changed).

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

ziggie1984 · 2026-05-04T22:37:58Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces the ChannelStore interface within a new chanstate package, serving as a persistence contract to decouple the channel-state subsystem from the concrete channeldb implementation. As part of this refactoring, the FetchChannelByID method signature was simplified by removing the optional database transaction parameter, with corresponding updates made across tests and the main server logic. Regarding the review feedback, a style guide violation was identified in chanstate/log.go where the init function requires a comment explaining its purpose.

Add a sibling bullet under the existing "Native SQL migration of the channel state and switch data" heading, covering the consumer-side swap that pairs with the interface introduced in lightningnetwork#10777.

Roasbeef

Straight forward diff. Main comment is that I think we can avoid the mega channel store interface in favor of more domain specific interfaces.

yyforyongyu

Nice small PR - think we just need to split the mega interface.

All four call sites pass nil for tx today (server.go, two in channeldb/db_test.go, funding/manager_test.go). The internal channelScanner(nil, selector) call inside FetchChannelByID is preserved verbatim, so runtime behavior is unchanged. This is a prerequisite for the upcoming chanstate.ChannelStore interface: keeping the parameter would leak kvdb into a domain interface.

Add a new chanstate package containing the Store interface plus a package logger. The interface mirrors the public surface of *channeldb.ChannelStateDB so the compile-time assertion var _ ChannelStore = (*channeldb.ChannelStateDB)(nil) No consumer migrates in this commit.

Roasbeef

LGTM 🔫

yyforyongyu

LGTM 🚢

ziggie1984 self-assigned this Apr 28, 2026

gemini-code-assist Bot reviewed Apr 28, 2026

View reviewed changes

saubyk added this to lnd v0.22 Apr 28, 2026

github-project-automation Bot moved this to Backlog in lnd v0.22 Apr 28, 2026

saubyk added this to the v0.22.0 milestone Apr 28, 2026

saubyk moved this from Backlog to In progress in lnd v0.22 Apr 28, 2026

ziggie1984 force-pushed the chanstate-sql-migration-pr1-interface branch from 577cb0e to a91f13f Compare May 4, 2026 22:06

github-actions Bot added the severity-critical Requires expert review - security/consensus critical label May 4, 2026

ziggie1984 changed the base branch from master to elle-base-branch-channelstate-native-sql May 4, 2026 22:20

ziggie1984 force-pushed the chanstate-sql-migration-pr1-interface branch from a91f13f to 9c66646 Compare May 4, 2026 22:36

ziggie1984 added sql refactoring labels May 4, 2026

ziggie1984 requested review from bitromortac and yyforyongyu May 4, 2026 22:38

gemini-code-assist Bot reviewed May 4, 2026

View reviewed changes

Comment thread chanstate/log.go

ziggie1984 force-pushed the chanstate-sql-migration-pr1-interface branch from 9c66646 to 299e8a8 Compare May 5, 2026 14:59

github-actions Bot added severity-critical Requires expert review - security/consensus critical and removed severity-critical Requires expert review - security/consensus critical labels May 5, 2026

ziggie1984 changed the title ~~chanstate: introduce ChannelStore interface (PR 1 of channel-state decomposition)~~ chanstate: introduce Store interface (PR 1 of channel-state decomposition) May 5, 2026

ziggie1984 mentioned this pull request May 5, 2026

chanstate: migrate consumers to Store interface (PR 2 of channel-state decomposition) #10790

Merged

4 tasks

ziggie1984 mentioned this pull request May 5, 2026

[epic]: Channel State + Forwarding Log SQL Migration #10680

Open

ziggie1984 changed the base branch from elle-base-branch-channelstate-native-sql to master May 6, 2026 16:12

saubyk moved this from In progress to In review in lnd v0.22 May 7, 2026

Roasbeef reviewed May 8, 2026

View reviewed changes

Comment thread chanstate/interface.go Outdated

yyforyongyu reviewed May 11, 2026

View reviewed changes

Comment thread chanstate/interface.go Outdated

Comment thread chanstate/log.go

Comment thread docs/release-notes/release-notes-0.22.0.md Outdated

ziggie1984 force-pushed the chanstate-sql-migration-pr1-interface branch from 299e8a8 to d8b5c09 Compare May 11, 2026 20:58

ziggie1984 added the no-changelog label May 11, 2026

ziggie1984 force-pushed the chanstate-sql-migration-pr1-interface branch 2 times, most recently from 7f21a8b to a92b08f Compare May 11, 2026 21:08

ziggie1984 requested review from Roasbeef and yyforyongyu and removed request for bitromortac May 11, 2026 21:22

ziggie1984 force-pushed the chanstate-sql-migration-pr1-interface branch 2 times, most recently from 3dc4865 to 6b8249e Compare May 11, 2026 21:35

ziggie1984 force-pushed the chanstate-sql-migration-pr1-interface branch from 6b8249e to 96e0fd7 Compare May 11, 2026 21:54

github-actions Bot added severity-critical Requires expert review - security/consensus critical and removed severity-critical Requires expert review - security/consensus critical labels May 11, 2026

Roasbeef approved these changes May 12, 2026

View reviewed changes

yyforyongyu approved these changes May 12, 2026

View reviewed changes

yyforyongyu merged commit 3adf45d into lightningnetwork:master May 12, 2026
41 of 46 checks passed

github-project-automation Bot moved this from In review to Done in lnd v0.22 May 12, 2026

Conversation

ziggie1984 commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

gemini-code-assist Bot commented Apr 28, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 4, 2026

🔴 PR Severity: CRITICAL

Analysis

Uh oh!

ziggie1984 commented May 4, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Roasbeef left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yyforyongyu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Roasbeef left a comment

Choose a reason for hiding this comment

Uh oh!

yyforyongyu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ziggie1984 commented Apr 28, 2026 •

edited

Loading