Add Payjoin Receiver Support by Camillarhi · Pull Request #746 · lightningdevkit/ldk-node

Camillarhi · 2026-01-08T19:24:00Z

This PR adds support for receiving payjoin payments in LDK Node. This is currently a work in progress and implements the receiver side of the payjoin protocol.

Add session store for persisting payjoin receiver events across restarts
Implement KVStorePayjoinReceiverPersister to handle session persistence
Add Payjoin as a PaymentKind to the payment store
Add event polling mechanism for active payjoin sessions
Wire up payjoin payment request and receive flows

Note on persistence: The payjoin library currently only supports synchronous persistence, but they're working on adding async support(payjoin/rust-payjoin#1235). This PR sets up the persistence structure (KVStorePayjoinReceiverPersister), which will be updated to use async operations once the upstream PR is merged.

This PR will partially address #177

ldk-reviews-bot · 2026-01-08T19:24:03Z

I've assigned @tnull 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.

DanGould · 2026-01-23T03:51:53Z

We've merged the async persistence PR you mentioned. You might want to build your draft PR on the merged commit from there on until we cut you a release.

Camillarhi · 2026-01-23T12:48:54Z

We've merged the async persistence PR you mentioned. You might want to build your draft PR on the merged commit from there on until we cut you a release.

Thanks for letting me know. I'll build on the merged commit.

DanGould · 2026-02-10T07:14:04Z

Are you stuck? Did something in our library break CI @Camillarhi

Camillarhi · 2026-02-10T07:33:02Z

Are you stuck? Did something in our library break CI @Camillarhi

Not stuck at all. I was just closing out some other PRs. Still working on this one, I'll let you know when it's ready.

Implements the receiver side of the BIP 77 Payjoin v2 protocol, allowing LDK Node users to receive payjoin payments via a payjoin directory and OHTTP relay. - Adds a `PayjoinPayment` handler exposing a `receive()` method that returns a BIP 21 URI the sender can use to initiate the payjoin flow. The full receiver state machine is implemented covering all `ReceiveSession` states: polling the directory, validating the sender's proposal, contributing inputs, finalizing the PSBT, and monitoring the mempool. - Session state is persisted via `KVStorePayjoinReceiverPersister` and survives node restarts through event log replay. Sender inputs are tracked by `OutPoint` across polling attempts to prevent replay attacks. The sender's fallback transaction is broadcast on cancellation or failure to ensure the receiver still gets paid. - Adds `PaymentKind::Payjoin` to the payment store, `PayjoinConfig` for configuring the payjoin directory and OHTTP relay via `Builder::set_payjoin_config`, and background tasks for session resumption every 15 seconds and cleanup of terminal sessions after 24 hours.

Camillarhi · 2026-03-12T09:50:36Z

Marking this as ready for review.

The core receiver flow is implemented, including session persistence, PSBT handling, input contribution, mempool monitoring for payjoin transactions, and node restart recovery.

Two things still pending that I'll follow up with:

Integration tests
Processing/updating confirmation state for payjoin transactions in the payment and pending payment stores

Happy to get early feedback on the overall approach in the meantime.

@tnull @DanGould

bc1cindy

hi there!

congrats and thanks for your work!

I talked to @spacebear21 and we agreed that I would review this PR, so I took a first look and here are some points:

needs to run cargo fmt --all

bc1cindy · 2026-03-12T14:13:31Z

bindings/ldk_node.udl

 	"InvalidLnurl",
+	"PayjoinNotConfigured",
+	"PayjoinSessionCreationFailed",
+	"PayjoinSessionFailed"


PayjoinSessionFailed is used for infrastructure failures (coin selection, InputPair construction) and network errors (poll/post requests). The upstream lib distinguishes these via SelectionError, InputContributionError, and ReceiverError , would it be worth preserving that granularity so callers have more info and know how to act?

bc1cindy · 2026-03-12T15:58:39Z

src/chain/bitcoind.rs

+
+	pub(crate) async fn can_broadcast_transaction(&self, tx: &Transaction) -> Result<bool, Error> {
+		let timeout_fut = tokio::time::timeout(
+			Duration::from_secs(DEFAULT_TX_BROADCAST_TIMEOUT_SECS),


since testmempoolaccept is local validation only, shouldn't this use DEFAULT_TX_LOOKUP_TIMEOUT_SECS?

bc1cindy · 2026-03-12T17:26:01Z

src/chain/electrum.rs

+					Err(e) => {
+						// Check if it's a "not found" error
+						let error_str = e.to_string();
+						if error_str.contains("No such mempool or blockchain transaction")


matching errors by string seems fragile, as the message varies by server implementation.
e.g. tested: ssl://electrum.blockstream.info:60002: Protocol(String("missing transaction")) , which doesn't match either string here and Ok(None) would never be returned. the caller sees a sync failure instead

bc1cindy · 2026-03-12T17:51:35Z

src/chain/electrum.rs

+			self.runtime.spawn_blocking(move || electrum_client.transaction_get(&txid_copy));
+		let timeout_fut = tokio::time::timeout(
+			Duration::from_secs(
+				self.sync_config.timeouts_config.lightning_wallet_sync_timeout_secs,


this is a single onchain tx lookup, should this use tx_broadcast_timeout_secs (10s) instead of lightning_wallet_sync_timeout_secs (30s)? or would a dedicated tx_lookup_timeout_secs field make more sense?

bc1cindy · 2026-03-12T21:14:41Z

src/payment/payjoin/manager.rs

+		&self, proposal: Receiver<Monitor>, persister: &KVStorePayjoinReceiverPersister,
+	) -> Result<(), Error> {
+		// On a session resumption, the receiver will resume again in this state.
+		let poll_interval = tokio::time::Duration::from_millis(200);


this seems aggressive for a daemon (payjoin-cli uses 200ms because its a one-shot CLI with manual retry) but for ldk node maybe 1-5 seconds would be more appropriate?

bc1cindy · 2026-03-12T22:03:04Z

src/payment/payjoin/manager.rs

+			})
+			.save_async(persister)
+			.await
+			.map_err(|_| Error::PersistenceFailed)?;


finalize_proposal returns MaybeTransientTransition to distinguish transient from fatal errors, but .map_err(|_| Error::PersistenceFailed) collapses both into the same error. Transient failures won't be retried and will surface as PersistenceFailed, which is misleading

bc1cindy · 2026-03-12T23:00:52Z

src/payment/store.rs

 		(4, secret, option),
-	}
+	},
+	(11, Payjoin)=>{


all other PaymentKind variants use even TLV tags (0, 2, 4, 6, 8, 10), was 11 intentional, or should this be 12?

bc1cindy · 2026-03-13T01:15:10Z

src/builder.rs

+			Arc::clone(&kv_store),
+			Arc::clone(&logger),
+		)),
+		Err(e) => {


payjoin_session_store_res doesn't handle ErrorKind::NotFound, which will occur on any node that has never used payjoin. fix suggestion in read_payjoin_sessions

bc1cindy · 2026-03-13T02:21:41Z

Cargo.toml

 #bitcoin-payment-instructions = { version = "0.6" }
 bitcoin-payment-instructions = { git = "https://github.com/jkczyz/bitcoin-payment-instructions", rev = "869fd348c3ca0c78f439d2f31181f4d798c6b20e" }

+payjoin = { git = "https://github.com/payjoin/rust-payjoin.git", package = "payjoin", default-features = false, features = ["v2", "io"] }


should this pin a rev?

bc1cindy · 2026-03-13T03:29:28Z

src/io/utils.rs

+		PAYJOIN_SESSION_STORE_PRIMARY_NAMESPACE,
+		PAYJOIN_SESSION_STORE_SECONDARY_NAMESPACE,
+	)
+	.await?;


list() returns NotFound when the namespace has never been written, maybe consider something like this handling it?

rust.or_else(|e| if e.kind() == lightning::io::ErrorKind::NotFound { Ok(vec![]) } else { Err(e) })?;

Camillarhi force-pushed the payjoin-receiver branch from 1db2b08 to 49017bd Compare January 8, 2026 19:27

DanGould mentioned this pull request Jan 9, 2026

1.0 Integrations tracking issue payjoin/rust-payjoin#1156

Open

30 tasks

Camillarhi force-pushed the payjoin-receiver branch 5 times, most recently from 8f6ba65 to 6499918 Compare January 30, 2026 10:36

Camillarhi force-pushed the payjoin-receiver branch 2 times, most recently from 12a41ad to eb97832 Compare February 18, 2026 23:21

Camillarhi force-pushed the payjoin-receiver branch 3 times, most recently from 120b089 to 8cc2a31 Compare February 23, 2026 15:03

Camillarhi force-pushed the payjoin-receiver branch 9 times, most recently from 1e1efcd to 5fe1a5c Compare March 10, 2026 12:06

Camillarhi force-pushed the payjoin-receiver branch from 5fe1a5c to 0411ada Compare March 12, 2026 09:45

Camillarhi marked this pull request as ready for review March 12, 2026 09:50

ldk-reviews-bot requested a review from tnull March 12, 2026 09:51

bc1cindy reviewed Mar 13, 2026

View reviewed changes

Conversation

Camillarhi commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ldk-reviews-bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DanGould commented Jan 23, 2026

Uh oh!

Camillarhi commented Jan 23, 2026

Uh oh!

DanGould commented Feb 10, 2026

Uh oh!

Camillarhi commented Feb 10, 2026

Uh oh!

Camillarhi commented Mar 12, 2026

Uh oh!

bc1cindy left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Camillarhi commented Jan 8, 2026 •

edited

Loading

ldk-reviews-bot commented Jan 8, 2026 •

edited

Loading

bc1cindy left a comment •

edited

Loading