Include onchain transactions in events by tnull · Pull Request #448 · lightningdevkit/ldk-node

tnull · 2025-01-27T15:55:47Z

Closes #446.
Based on #432.

In #432 we exposed transactions in store. Here we take a stab at exposing them via events. However, to avoid emitting duplicate events for channel-related transactions, this is in draft until we have lightningdevkit/rust-lightning#3566

tnull · 2025-10-09T07:52:46Z

While the latest BDK 2.2 now shipped event (which would make emitting events easier on our end), we still need lightningdevkit/rust-lightning#3566 to properly classify the transactions in our store. So this remains blocked until the latter ships (likely with LDK 0.3).

ovitrif · 2025-10-29T09:19:24Z

While the latest BDK 2.2 now shipped event (which would make emitting events easier on our end), we still need lightningdevkit/rust-lightning#3566 to properly classify the transactions in our store. So this remains blocked until the latter ships (likely with LDK 0.3).

Is there a way we could get this into ldk-node sooner?
To be honest we (Bitkit team), kind of relied on the expectation that the BDK 2.2 PR #310 Return wallet events when applying updates will be integrated in ldk-node soon enough (ie. this month or November); and we made our roadmapping around this expectation. Now I'm getting feedback that there is no way we can delay our release any further than when it's planned, and the due date is very soon; which leaves us with very few options:

Get help from you to get this into ldk-node very soon (November)
Collaborate with you to have someone from our team help with implementation efforts (for example by fixing lightningdevkit/rust-lightning#3566), but then we will need a commitment that if we fix that, this PR takes priority and it is implemented shortly thereafter)
Do our own implementation for this

The team seems to lean towards favoring option 3, which is not ideal IMHO, but the main argument is that we don't really have the time to go any other route.

The issue that I see from my PoV is that option 2 might even seem faster.

Could 2 be an option?

tnull · 2026-02-18T10:33:19Z

Technically unblocked, but we should first land #791, as the API here will depend on the API choices there.

Let callers obtain the object produced by merge semantics without a second lookup. Preserve the existing boolean API so unrelated call sites and their allocation behavior remain unchanged. Co-Authored-By: HAL 9000

Let wallet sync enqueue on-chain payment events directly. Co-Authored-By: HAL 9000

tnull · 2026-07-10T13:01:07Z

Should be good for review now.

Notify users when otherwise unclassified on-chain payments reach the anti-reorg confirmation depth. Use the wallet's effective stored payment so classified funding, splice, close, and sweep transactions stay quiet. Co-Authored-By: HAL 9000

The in-memory store source is shared by the library test utilities and integration-test helpers. Keep its unit test in the library-only module so each integration binary does not register and rerun it. Co-Authored-By: HAL 9000

jkczyz · 2026-07-13T16:03:59Z

+		let supplied = MergingTestObject { id, data: [25u8; 3], preserved_data: [26u8; 3] };
+		let expected = MergingTestObject { data: supplied.data, ..existing };
+		assert_eq!(Ok((true, expected)), data_store.insert_or_update_and_get(supplied).await);
+
+		let unchanged = MergingTestObject { preserved_data: [27u8; 3], ..expected };
+		assert_eq!(Ok((false, expected)), data_store.insert_or_update_and_get(unchanged).await);


Add an assertion for when an insert occurs.

jkczyz · 2026-07-13T16:20:00Z

-					if payment_status == PaymentStatus::Pending {
-						let pending_payment =
-							self.create_pending_payment_from_tx(payment, Vec::new());
+						if updated && payment_status == PaymentStatus::Succeeded {


If we crash after the payment_store write but before the event queue is persisted, updated will be false on the next sync upon restart and the event will be lost.

Also from Claude:

This updated gate is the only thing preventing re-emission after a restart (the reloaded store merges the re-derived payment as a no-op), and no test covers it: no restart test syncs and asserts next_event() == None. I wrote that test — it passes, so this is coverage-only.

jkczyz · 2026-07-13T16:29:42Z

+						if payment_status == PaymentStatus::Pending {
+							let pending_payment =
+								self.create_pending_payment_from_tx(stored_payment, Vec::new());
+							self.pending_payment_store.insert_or_update(pending_payment).await?;
+						}


Directly from Claude:

Direct graduation leaves a pre-existing pending entry stale. Sequence: a tx confirms below ANTI_REORG_DELAY, so a pending entry is written recording its confirmation block; a shallow reorg then moves the tx into a different block; by the next batch sync the tx is ≥ ANTI_REORG_DELAY deep. That sync's TxConfirmed graduates the payment and emits an event with the new (canonical) block, but the pending entry still holds the old, now-orphaned block — and ChainTipChanged then merges that stale entry back in (updated == true), emitting a duplicate event carrying the orphaned block hash and regressing the stored confirmation to the orphaned block. Demonstrated by a failing integration test using a 1-block reorg; no restart needed. Remove/refresh the pending entry when graduating directly — with that fixed, emission is exactly-once for reorgs shallower than ANTI_REORG_DELAY, which is worth documenting on the event variants.

jkczyz · 2026-07-13T17:00:30Z

+		/// The value, in thousandths of a satoshi, that was sent.
+		amount_msat: u64,


Should we include a field for the fees paid?

jkczyz · 2026-07-13T17:04:50Z

+		amount_msat: u64,
+		/// The hash of the block in which the transaction was confirmed.
+		block_hash: BlockHash,
+		/// The height at which the block was confirmed.


The height of the block in which the transaction was confirmed.

jkczyz · 2026-07-13T21:29:13Z

+	if !allow_0conf {
+		assert_eq!(
+			node_a.expect_onchain_payment_event(OnchainPaymentEvent::Received).await,
+			splice_out_txo.txid,
+		);
+	}


Hmmm... Clause says we aren't using InteractiveFunding for 0-conf splices.

The gate is correct but subtle — worth a comment: with 0conf, LDK re-broadcasts the splice tx as TransactionType::Funding (classified → no event); without, the acceptor only broadcasts InteractiveFunding, which classification skips → event fires. The cross-variant inconsistency in the acceptor's record may be worth flagging upstream.

jkczyz · 2026-07-13T21:33:44Z

 	};

 	generate_blocks_and_wait(&bitcoind.client, &electrsd.client, 6).await;
 	wait_for_tx(&electrsd.client, txid).await;


The CI failure is here according to Claude:

This ordering is what failed CI (build (self-hosted, beta)) once the new assertion below started depending on it: send() only queues the broadcast (drained by a background task), and wait_for_tx after mining also passes for a mempool-only tx — so the tx can miss the first of the 6 blocks, sit below ANTI_REORG_DELAY at the sync, and never produce the event (expect_onchain_payment_event can't recover; single 60s next_event_async, tests/common/mod.rs:426-434). Swap these two lines, as onchain_send_receive does.

jkczyz · 2026-07-13T21:49:19Z

+	assert_eq!(node_a.next_event(), None);
+	assert_eq!(node_b.next_event(), None);


Claude:

After the reorg sync below, also assert no event, then re-mine to ANTI_REORG_DELAY and assert exactly one event fires. Extended that way, it currently fails due to the stale-pending-entry duplicate (src/wallet/mod.rs:289).

jkczyz · 2026-07-13T22:00:32Z


 	// Restart node_a with the same config
 	println!("\nRestarting node A...");
 	let restarted_node_a = setup_node(&chain_source, config_a);


Claude:

Nothing tests that a restarted node doesn't re-emit. I wrote the test — it passes, so coverage-only.

jkczyz · 2026-07-13T22:03:12Z

+            is Event.OnchainPaymentReceived -> {
+                assertEquals(txid1, onchainPaymentReceivedEvent1.txid)
+                assertEquals(100000000uL, onchainPaymentReceivedEvent1.amountMsat)
+            }


How about testing OnchainPaymentSuccessful?

jkczyz · 2026-07-13T22:19:32Z

Tests mentioned in claude feedback can be found in jkczyz@a7c0269

tnull added the blocked on upstream label Jan 27, 2025

tnull marked this pull request as draft January 27, 2025 15:55

tnull mentioned this pull request Jan 27, 2025

Expose onchain transactions in store #432

Merged

tnull mentioned this pull request Sep 26, 2025

Enhance onchain transaction management #628

Merged

rolznz mentioned this pull request Feb 17, 2026

Fire hub event when on-chain payment is received getAlby/hub#2082

Open

tnull added this to the 0.8 milestone Feb 18, 2026

tnull removed the blocked on upstream label Feb 18, 2026

tnull mentioned this pull request Mar 4, 2026

Explore whether PaidBolt12Invoice should be moved to PaymentMetadataStore #816

Open

tnull mentioned this pull request Jul 9, 2026

Fix funding-payment reclassification downgrade and deep-reorg duplication #962

Open

tnull force-pushed the 2025-01-include-onchain-transactions-in-events branch 2 times, most recently from c832289 to 8362d88 Compare July 10, 2026 10:47

tnull added 2 commits July 10, 2026 13:01

Return effective values from store upserts

45b6833

Let callers obtain the object produced by merge semantics without a second lookup. Preserve the existing boolean API so unrelated call sites and their allocation behavior remain unchanged. Co-Authored-By: HAL 9000

Give Wallet access to EventQueue

0a6010e

Let wallet sync enqueue on-chain payment events directly. Co-Authored-By: HAL 9000

tnull force-pushed the 2025-01-include-onchain-transactions-in-events branch 3 times, most recently from b20b0b5 to b2d7c36 Compare July 10, 2026 12:59

tnull marked this pull request as ready for review July 10, 2026 13:00

tnull force-pushed the 2025-01-include-onchain-transactions-in-events branch from b2d7c36 to 35a60c4 Compare July 10, 2026 13:07

tnull requested a review from jkczyz July 10, 2026 13:39

tnull added 2 commits July 10, 2026 15:39

Emit settled on-chain payment events

cb799ae

Notify users when otherwise unclassified on-chain payments reach the anti-reorg confirmation depth. Use the wallet's effective stored payment so classified funding, splice, close, and sweep transactions stay quiet. Co-Authored-By: HAL 9000

Keep store unit test out of integration tests

176ac00

The in-memory store source is shared by the library test utilities and integration-test helpers. Keep its unit test in the library-only module so each integration binary does not register and rerun it. Co-Authored-By: HAL 9000

tnull force-pushed the 2025-01-include-onchain-transactions-in-events branch from 35a60c4 to 176ac00 Compare July 10, 2026 13:40

jkczyz reviewed Jul 13, 2026

View reviewed changes

		/// The value, in thousandths of a satoshi, that was sent.
		amount_msat: u64,

		assert_eq!(node_a.next_event(), None);
		assert_eq!(node_b.next_event(), None);

Uh oh!

Conversation

tnull commented Jan 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tnull commented Oct 9, 2025

Uh oh!

ovitrif commented Oct 29, 2025

Uh oh!

tnull commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tnull commented Jul 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkczyz commented Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tnull commented Jan 27, 2025 •

edited

Loading

tnull commented Feb 18, 2026 •

edited

Loading