Skip to content

Turn the pending payment store into an OnchainPaymentTracker - #1240

Open
tnull wants to merge 10 commits into
lightningdevkit:mainfrom
tnull:2026-11-onchain-payment-tracker
Open

tnull wants to merge 10 commits into
lightningdevkit:mainfrom
tnull:2026-11-onchain-payment-tracker

Conversation

@tnull

@tnull tnull commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Builds on #1232. Closes #950.

Pending-store entries kept a full copy of each on-chain payment record. Every status change wrote both stores, and the two copies could disagree: a stale tx_type misled pending_send_txids, and a failed mirror write left a confirmed payment that never graduated. Splice round figures were also
stored twice and could drift apart.

This PR makes each piece of data live in one place:

  • Entries keep only the record's txid. The payment store is the sole source of status and type, so a confirmation or reorg costs one write instead of two.
  • Facts are read once per wallet event. Each event reads its channel facts once instead of twice.
  • Splice round figures stay stable. A later signing no longer overwrites the figures of rounds already recorded, so the entry agrees with the channel facts.
  • Funding fields are grouped and the store is renamed. Funding-only fields become Option. The store is now OnchainPaymentTracker (src/wallet/payment_tracker.rs), and the on-disk namespace is unchanged.
  • Plumbing is simplified. The sync event handling is shared, the generic update machinery goes, and test helpers and builders move out of production code.

The persisted entry format changes. It was never released, and #1232 already breaks it, so there is no compat read: entries written by current main will fail to load.

@tnull tnull added this to the 0.8 milestone Nov 17, 2026
@tnull
tnull requested a review from jkczyz November 17, 2026 10:42
@ldk-reviews-bot

ldk-reviews-bot commented Nov 17, 2026 •

Copy link
Copy Markdown

👋 Thanks for assigning @jkczyz as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

Comment thread src/wallet/mod.rs Resolved
tnull added 10 commits November 18, 2026 10:15
Wallet tests read and write the pending payment store directly, each
spelling out the store call and the entry or update type it takes.
Changing the shape of pending entries would touch nearly every test.

Route those reads and writes through a few test helpers, so later
changes to the entry type only need to adapt the helpers.

Written with the help of an AI tool.

Co-Authored-By: HAL 9000
The confirmed, unconfirmed and dropped wallet events each repeated the
same steps to resolve a transaction's payment and write its record and
pending entry, so any change to that flow had to be made three times.

Handle all three through one method, parameterized by the status the
event implies. The store calls, their order and error handling stay
as they were.

Written with the help of an AI tool.

Co-Authored-By: HAL 9000
Pending entries implemented the store's generic update interface, with
merge rules covering cases only tests exercised. Wallet sync was its
one production user, so most of those rules guarded nothing real.

Replace it with a single merge of what wallet sync observes about a
payment, keeping the rules sync relies on. Stored entries are read and
written as before.

Written with the help of an AI tool.

Co-Authored-By: HAL 9000
Each pending entry mirrored the full payment record, so every
confirmation or reorg wrote both stores, and the copies could disagree:
a late classification left the mirror's transaction type stale, and a
failed mirror write left a confirmed payment that never graduated.

Entries now keep only the record's current txid, and the payment store
is the sole source of status, confirmation, direction and type. An
entry is written only when its txid, conflicts or channels change; the
channels of an interactive funding are set from its classification.
The chain-tip pass reads each record, skips one it cannot read, and
removes the entry of a settled record. The persisted entry format
changes without a compatibility read, as no release has written it.

Written with the help of an AI tool.

Co-Authored-By: HAL 9000
A wallet event resolved the payment of its transaction through a lenient
read of the transaction's channel facts, and then read the same facts
again, strictly, to record the transaction from its provenance. Absent
facts are not cached, so an ordinary transaction cost two facts reads
per event, and a signing re-read the signed round's facts while
resolving its payment id.

Each event and each signing now reads the transaction's own facts once
and hands that read to both payment resolution and provenance. A failed
read still falls back to the pending entries for resolution and still
fails the event only where a record would be written from the
transaction. Resolution also returns the entry it matched, which the
funding status update takes instead of reading it again.

Written with the help of an AI tool.

Co-Authored-By: HAL 9000
A signing recomputed every round's figures from LDK's current view of
the contributions and overwrote the figures of rounds already in the
entry, while the rounds' facts keep their first answer. The two could
then disagree, and a confirmation applied from the entry reported other
figures than a record created from the facts.

Rounds already in the entry now keep their recorded figures, and the
signed round takes the figures its facts carry, so entry and facts
agree. A later signing still clears earlier rounds' broadcast marks.

Written with the help of an AI tool.

Co-Authored-By: HAL 9000
The channels, candidate rounds and locked rounds of a pending entry
only ever apply to interactive funding, yet sat as three independent
lists beside the fields every entry uses, and each site that cleared
the funding state had to clear all three by hand.

Gather them in an optional FundingRounds that a non-funding entry
leaves unset, so clearing a splice's whole funding state is a single
assignment. The persisted format changes, which is fine as it is
unreleased; sites that clear only part of the state keep doing so.

Written with the help of an AI tool.

Co-Authored-By: HAL 9000
The pending payment store no longer holds payments: its entries only
index the on-chain transactions that may still change a payment
record. Its name, its entry type and its home in the payment module
still suggested a second copy of the payment store.

Rename it to OnchainPaymentTracker with TrackedOnchainPayment entries
and move it next to the wallet code that maintains it, renaming the
accessors to match. The on-disk namespace stays "pending_payments", so
persisted entries are read as before.

Written with the help of an AI tool.

Co-Authored-By: HAL 9000
The test-only builders for funding contributions lived in the payment
tracker module, although they have nothing to do with tracked
payments and only serve the wallet tests.

Move them into a test-only module of the wallet, so the tracker module
holds only the tracker and its own tests.

Written with the help of an AI tool.

Co-Authored-By: HAL 9000
The tracker entry carried getters for fields that are already public
and thin wrappers around creating its funding state, the lock handler
spelled out a bool-to-Option conversion, and a test-only helper lived
among the production methods while another test helper duplicated the
logic wallet sync uses to track a pending payment.

Access the fields directly, inline the wrappers, move the funding
test helper into the test module and let the pending-payment helper
go through the production upsert path, so tests exercise the same
code as the node. Behaviour is unchanged.

Written with the help of an AI tool.

Co-Authored-By: HAL 9000
@tnull
tnull force-pushed the 2026-11-onchain-payment-tracker branch from b7d9091 to 778788b Compare November 18, 2026 09:50
@tnull

tnull commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator Author

Rebased after #1232 landed.

@jkczyz jkczyz left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, otherwise.

Comment thread src/wallet/mod.rs
.cloned()
.unwrap_or_else(|| TrackedOnchainPayment::new(id, txid, Vec::new()));
changed |= entry.merge_observed(txid, conflicting_txids);
changed |= entry.track_funding_channels(channels);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Could we add a test for this? With this line removed, all the lib tests still pass. The same goes for funding.channels = record_channels in drop_abandoned_splice_rounds (line 3545). These two lines replace the old fallback to the record's classification, and lookups by channel find an entry only through this list (tracks_channel). Of the places that copy the record's channels onto the entry, only the classification one has a test (a_late_funding_classification_tracks_the_channels). The old fallback wasn't tested either, so this isn't lost coverage, and it could be a follow-up.

Comment thread src/io/mod.rs
@@ -34,8 +34,8 @@ pub(crate) const PAYMENT_INFO_PERSISTENCE_PRIMARY_NAMESPACE: &str = "payments";
pub(crate) const PAYMENT_INFO_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";

/// The pending payment information will be persisted under this prefix.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: This now documents the tracker's namespace, so maybe "Tracked on-chain payments are persisted under this prefix."

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Consider simplifying/refactoring PendingPaymentStore

4 participants