channeldb: split channel coordination from kv stores#10950
Draft
ziggie1984 wants to merge 125 commits into
Draft
channeldb: split channel coordination from kv stores#10950ziggie1984 wants to merge 125 commits into
ziggie1984 wants to merge 125 commits into
Conversation
Move the small value types referenced by chanstate.Store out of channeldb. This includes ChannelConfig, ChannelStatus, ChannelCloseSummary, ChannelShell, ChanCount, and FinalHtlcInfo. Leave aliases in channeldb so existing callers keep compiling while the backend still lives there. Parameterize the Store facets over the channel type and instantiate current callers with *channeldb.OpenChannel. This removes the chanstate -> channeldb import edge without moving OpenChannel yet, keeping the first step reviewable and backend-neutral.
Move ChannelType and its flag helpers into chanstate while leaving compatibility aliases in channeldb. This is a backend-neutral value type and does not require moving any KV serialization logic. Keep the full type documentation with the moved chanstate definition. The channeldb aliases preserve the existing public surface while later commits continue moving OpenChannel state out of the KV package.
Move the OpenChannel error definitions into chanstate and leave channeldb aliases for existing callers. These errors describe channel state behavior rather than a concrete KV bucket layout. Keeping the aliases preserves the public channeldb API while later commits move more OpenChannel state and receiver logic toward chanstate.
Move the ShutdownInfo state type, constructor, and closer helper into chanstate. The type describes channel shutdown state and is not tied to the concrete KV backend. Keep the TLV encode and decode helpers in channeldb for now, since those functions describe the current persisted format. The channeldb constructor remains as a compatibility wrapper.
Add a lifecycle facet to the chanstate Store contract for refresh, confirmation, open-state, and SCID mutations. Implement the facet on ChannelStateDB using the existing KV persistence code. Update the matching OpenChannel receivers to call through the store methods instead of reaching into the ChannelStateDB backend directly. Also convert fullSync into a channeldb helper so that KV-specific code is no longer an OpenChannel receiver.
Add a status facet to the chanstate Store contract for status bit updates and data-loss commit point handling. Implement the facet on ChannelStateDB using the existing persistence code. Update the matching OpenChannel receivers to call through the store methods. The broadcast path still uses a private channeldb helper until its closing-transaction facet is introduced in a later commit.
Add shutdown and close-transaction facets to the chanstate Store contract. These cover persisted shutdown info plus stored unilateral and cooperative closing transactions. Implement the facets on ChannelStateDB with the existing KV code and update OpenChannel receivers to call through the store methods. The backend-specific key selection remains private to channeldb.
Add pending-channel setup to the chanstate lifecycle store facet. This covers the path that writes a new pending channel and records the funding broadcast height. Move the OpenChannel receiver to call through ChannelStateDB and pass the backend explicitly into the channeldb sync helper. This keeps the link-node persistence detail in channeldb while removing another direct backend reference from OpenChannel.
Move ChannelCommitment and HTLC into chanstate so upcoming store facets can name commitment state without importing channeldb. Leave the KV serialization helpers in channeldb and keep aliases for existing call sites. This preserves the current disk format and keeps backend-specific persistence code out of chanstate for now.
Move LogUpdate into chanstate so commitment store interfaces can refer to pending update state without importing channeldb. Keep the log-update serialization helpers in channeldb. Those helpers remain part of the existing KV disk format and can move with the KV backend implementation later.
Add a commitment-focused store facet for updating local channel commitment state. This lets OpenChannel call through the chanstate store contract instead of reaching directly into the KV backend. Keep the existing KV transaction body on ChannelStateDB for now. The receiver still owns locking and in-memory state updates while the store method owns persistence.
Move CommitDiff and its forwarding reference types into chanstate. This lets the next commitment store facet name pending remote commitment state without importing channeldb. Keep forwarding package persistence and commit-diff serialization in channeldb for now. The aliases preserve existing call sites while the KV backend code remains in place.
Add the remote commitment-chain append method to the chanstate commitment store facet. Move the existing KV transaction body onto ChannelStateDB and have the OpenChannel receiver call through the store. This removes another direct backend dependency from OpenChannel while keeping KV persistence code in channeldb.
Add read-side commitment lookup methods to the chanstate commitment store facet. Move the existing OpenChannel KV view transaction bodies onto ChannelStateDB. Leave the OpenChannel receivers as store-call wrappers. This removes three more direct backend references from the receiver code without changing the persisted data format.
Add the next-revocation persistence method to the chanstate commitment store facet. Move the existing OpenChannel KV update body onto ChannelStateDB. The OpenChannel receiver keeps the external locking behavior and delegates persistence through the store interface.
Move FwdState, PkgFilter, and FwdPkg into chanstate with their existing comments and helper methods. Leave channeldb aliases for the moved value types and constructors so current callers keep compiling. The KV forwarding package persistence code stays in channeldb.
Add the commitment-tail advancement method to the chanstate commitment store facet. Move the existing AdvanceCommitChainTail KV transaction body onto ChannelStateDB. The OpenChannel receiver now keeps locking and restored channel checks before delegating persistence through the store.
Add a forwarding-package store facet to chanstate.Store. Move the existing OpenChannel forwarding-package KV transaction bodies onto ChannelStateDB. The OpenChannel receivers keep their locking behavior and delegate package loading, acking, filtering, and removal through the store.
Add commitment-height, latest-commitment, and remote revocation store lookups to the chanstate commitment store facet. Move the existing OpenChannel KV view transaction bodies onto ChannelStateDB. This leaves the receivers as store-call wrappers while keeping the persisted format and read behavior unchanged.
Move the remaining OpenChannel revocation-log KV reads onto ChannelStateDB. This keeps FindPreviousState and the unit-test tail-height helper as OpenChannel wrappers. It removes direct backend access from the receiver methods while leaving RevocationLog in channeldb for now.
Move the revocation-log value types and TLV serialization helpers into chanstate. Leave channeldb aliases and wrapper functions for the existing KV persistence code and tests. Bucket keys, errors, and transaction helpers stay in channeldb, so this commit only moves backend-neutral state data.
Add FindPreviousState to the chanstate commitment store facet now that RevocationLog is a chanstate value type. This extends the store contract without changing runtime behavior. The existing ChannelStateDB method already satisfies the new method.
Keep the revocation-log tail-height helper on ChannelStateDB instead of the OpenChannel receiver. The helper is only used by channeldb tests, so it should not become part of the backend-independent chanstate store contract. The tests now call the concrete helper directly.
Change OpenChannel.Db to the composed chanstate Store interface while keeping the existing field name. Tests that need raw channeldb access now assert the concrete test backend explicitly instead of reaching through OpenChannel.Db. This keeps backend setup out of the store contract.
Convert the KV-only OpenChannel helpers for TLV aux data and borked-state lookup into package-level channeldb helpers. This keeps serialization and bucket inspection code tied to the KV backend while leaving the OpenChannel receiver set closer to the future chanstate type.
Add transitional OpenChannel accessors for the channel status and confirmed SCID fields used by KV store code. These helpers keep the fields private while allowing channeldb backend code to continue hydrating and serializing channel state after OpenChannel moves to chanstate.
Remove the KV forwarding packager from OpenChannel and derive a ChannelPackager inside the channeldb store methods that need one. This keeps the backend-specific kvdb transaction helper in channeldb, so the OpenChannel type no longer carries that dependency toward chanstate.
Move the backend-neutral ChannelSnapshot value type into chanstate and leave channeldb with a compatibility alias. This keeps the future OpenChannel Snapshot receiver close to its return type without changing existing channeldb callers.
Move the backend-neutral taproot shachain and verification nonce helpers into chanstate with the thaw-height threshold they support. Leave channeldb aliases for existing callers while OpenChannel and its receiver methods are moved across the package boundary.
Add a transitional non-locking status predicate for channeldb store code and use it from KV serialization helpers. This avoids calling an unexported OpenChannel helper from channeldb after the type moves into chanstate.
Move the pending open-channel write into the chanstate KV store implementation while keeping link-node creation in channeldb. Preserve the existing transaction boundary used by pending channels and restores.
Fold the channel key and thaw-height helpers into the store files that own them, instead of keeping separate kv files that do not represent their own stores. The open-channel keys and thaw-height helpers now live with kv_open_channel, closed-channel bucket ownership lives with kv_close_summary, and commitment/update keys live with kv_commitment.
Move the KV-backed ChannelSetupStore implementation onto the chanstate KVStore. This includes both channel-opening state and initial forwarding policy persistence, which together make up the setup store facet. Keep the channeldb ChannelStateDB methods as compatibility wrappers so callers can continue using the old package while the concrete KV store implementation moves by facet.
Move the KV-backed FinalHTLCStore implementation onto KVStore. The ChannelStateDB methods keep compatibility wrappers while final HTLC lookup and on-chain outcome writes now live with the final HTLC KV store code. Carry the store-final-resolution option into KVStore so the on-chain outcome path keeps the existing opt-in behavior.
Move the KV-backed OpenChannelFwdPkgStore implementation onto KVStore. ChannelStateDB keeps the existing wrapper methods, but now delegates through the channelstate KV store instead of passing its backend into package-level helpers. This keeps forwarding package persistence grouped with the existing kv_forwarding_package code while removing another direct backend use from the channeldb compatibility layer.
Move the KV-backed OpenChannelShutdownStore methods onto KVStore. ChannelStateDB keeps the existing compatibility methods, but shutdown state now flows through the channelstate KV store rather than backend helper functions. The bucket-level shutdown codec helper stays in kv_shutdown because it is still the local serialization primitive used by the store method.
Move the KV-backed OpenChannelCloseTxStore implementation onto KVStore. ChannelStateDB keeps compatibility wrappers for marking and fetching broadcast close transactions while the KV logic now lives in kv_close_tx. Keep the generic close transaction fetch helper private to KVStore and expose only the domain methods required by the channelstate interface.
Move the KV-backed OpenChannelStatusStore implementation onto KVStore. ChannelStateDB keeps compatibility wrappers while status updates, data-loss commit point lookup, and borked marking now flow through the channelstate KV store. Keep the status write helper private to KVStore so related KV store facets can share the same status mutation path without passing raw backends around.
Move the backend-local open channel lifecycle mutations onto KVStore. ChannelStateDB keeps compatibility wrappers for refreshing channel state and marking confirmation, open, real scid, and scid-alias negotiation state. Leave SyncPendingChannel in channeldb for now because that path still creates link-node records, and LinkNodeDB ownership remains in channeldb for this refactor.
Move the KV-backed open channel commitment store methods onto KVStore. ChannelStateDB keeps compatibility wrappers for commitment updates, pending commit diffs, revocation queries, and previous-state lookups. Carry the no-rev-log-amount-data option into KVStore alongside the existing final HTLC option so revocation log and final-resolution writes preserve their previous configuration behavior.
Move the KV-backed revocation log tail helper onto KVStore. This removes the last direct backend call from the channeldb open channel compatibility methods while keeping the test-facing helper in place.
Move closed-channel summary reads and CloseChannel onto KVStore. ChannelStateDB keeps compatibility wrappers, while the KV code for close summary lookup and close archiving now lives with kv_close_summary. Carry the tombstone-close option into KVStore so the existing close strategy selection remains unchanged. Leave MarkChanFullyClosed and AbandonChannel in channeldb because they still coordinate link-node pruning and cross-store behavior.
Move historical channel bucket lookup and FetchHistoricalChannel onto KVStore. The channeldb wrapper still attaches itself to channel.Db so existing callers continue to receive a compatibility store reference. Move ErrNoHistoricalBucket into chanstate and keep the channeldb error as an alias, matching the other channel-state errors that have moved.
Move the KV-backed open channel read and scan methods onto KVStore. ChannelStateDB keeps compatibility wrappers that attach themselves to returned OpenChannel values so existing receiver methods still use the channeldb store. Leave restore and sync paths in channeldb because they still coordinate link-node creation and repair while LinkNodeDB ownership remains outside chanstate.
Move the KV-backed AbandonChannel implementation onto KVStore. ChannelStateDB keeps a compatibility wrapper while callers still import channeldb for the channel-state store. Keep the link-node-coupled close and repair methods in channeldb so the follow-up LinkNode store can define that boundary explicitly.
Move the remaining channel-state tests and helpers into the chanstate package so the store owns the KV-specific behavior directly. This also narrows the channel-state store interface by removing cross-domain link-node lifecycle methods. Those workflows will be owned by a separate channel coordinator in the next commits.
Move link-node persistence into its own package while keeping channeldb aliases and wrappers for existing callers. This creates an explicit linknode.Store boundary that can be wired independently from channel-state persistence in later commits.
Add the channel coordination contract and a KV-backed implementation for workflows that span channel-state and link-node storage. The channeldb.DB type now constructs and exposes the coordinator while remaining the legacy KV composition and migration root. ChannelStateDB keeps compatibility wrappers that delegate to the coordinator.
Pass channel-state persistence and lifecycle coordination into the wallet separately instead of routing both through ChannelStateDB. Update the funding manager config and tests with the same split because the funding flow constructs wallets and uses the same channel-state surface.
Use channel-state store interfaces for ordinary channel reads and closed-channel queries in the arbitrators. Route lifecycle operations that also maintain link-node state through channelcoord.ChannelLifecycle instead of the ChannelStateDB facade.
Accept only the open and closed channel store methods needed to hydrate channel notification payloads. This keeps the notifier on channel-state persistence without depending on the full store surface.
Rename the peer channel persistence dependency to ChannelStateStore and describe the exact channel-state surfaces it needs. Test fixtures now write channels through the coordinator while channel records keep only the channel-state store.
Update htlcswitch test channels to persist through channelcoord while keeping channel records bound to chanstate.Store. The tests retain access to the owning channeldb.DB separately for switch construction and restart scenarios.
Keep channeldb.DB as the server's legacy KV and migration root, but store the channel-state, coordinator, and link-node dependencies separately on server. Route RPC, restore, autopilot, and subserver setup through those explicit fields so consumers no longer reach through ChannelStateDB for mixed responsibilities.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR builds on #10812 and separates the remaining cross-domain channel
storage responsibilities.
The main changes are:
linknodepackage,channelcoordfor operations that must update channel state andlink-node metadata together,
channeldb.DBas the KV composition and migration root,ChannelStateDBwhere they only needchannel-state storage or lifecycle coordination.
This keeps the current KV migration path intact while making the
channel-state, link-node, and coordination boundaries explicit for future SQL
backends.
The PR is intentionally not adding SQL implementations yet. It only prepares
the storage boundaries so SQL can later provide separate channel-state,
link-node, and coordinator implementations without removing the KV migration
root.
Commit story
chanstate: finish kv store extractionlinknode: move store from channeldbchannelcoord: add kv coordinatorlnwallet: split channel lifecycle depscontractcourt: split channel lifecycle depschannelnotifier: narrow channel store deppeer: narrow channel state dependencyhtlcswitch: use split channel stores in testsserver: wire explicit channel storesValidation
go test ./channelcoord ./chanstate ./channeldb ./linknode ./lnwallet ./lnwallet/test ./funding ./contractcourt ./channelnotifier ./peer ./htlcswitch . -run '^$'make lint