Add Payjoin Receiver Support (BIP 77) 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

👋 Thanks for assigning @bc1cindy 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.

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

spacebear21

This is looking great! I have high-level feedback from the payjoin side, but overall agree with the approach and implementation.

spacebear21 · 2026-03-16T16:54:24Z

src/chain/mod.rs

+					ChainSourceKind::Esplora{..} => {
+						// Esplora does not support a testmempoolaccept equivalent, so we skip
+						// the broadcast suitability check and assume the transaction is broadcastable.
+						log_debug!(self.logger, "Skipping broadcast suitability check: not supported by Esplora backend.");
+						Ok(true)
+					},
+					ChainSourceKind::Electrum{..} => {
+						// Electrum does not support a testmempoolaccept equivalent, so we skip
+						// the broadcast suitability check and assume the transaction is broadcastable.
+						log_debug!(self.logger, "Skipping broadcast suitability check: not supported by Electrum backend.");
+						Ok(true)


The broadcast suitability check is important for non-interactive receivers (e.g. payment processors) to protect against probing attacks, where a malicious sender can repeatedly send proposals to have the non-interactive receiver reveal the UTXOs it owns with the proposals it modifies. The "broadcastable" check ensures the receiver can broadcast the fallback transaction in case the payjoin fails, effectively incurring a cost to the attacker.

Electrum's lack of support for this kind of check is a longstanding issue unfortunately.

I'm not familiar enough with LDK-node usage to know if it's typically used in an interactive way (receiver takes manual action to receive payment) or non-interactive (e.g. bolt12 or similar static payment with no receiver action per payment)?

In interactive conditions, the receiver may use the assume_interactive_receiver transition method to explicitly skip the broadcast check altogether. In non-interactive conditions though, we should find an alternative way to perform this check. Or at least return an error instead of silently skipping the check, so it can be handled by the implementer.

I'm not familiar enough with LDK-node usage to know if it's typically used in an interactive way (receiver takes manual action to receive payment) or non-interactive

it's mostly non-interactive

It is non-interactive. I'll update both Esplora and Electrum to return an error instead so the limitation is explicit. Thanks for the context on the probing attack.

Electrum's lack of support for this kind of check is a longstanding issue unfortunately.

Hmm, did anybody ever raise this explicitly with the Electrum folks? I think I briefly brought this up (though mostly for completeness sake) here when reviewing the recent v1.6: spesmilo/electrum-protocol#6 (comment)

If I had known the history I would have pushed harder on this, but I assume it might make sense to let them know about this and try to get it into the next release at least?

For this PR, I think we had discussed on the initial call that we'd skip the validation for non-bitcoind chain sources, as they are considered semi-trusted already? Any reason why we can't/shouldn't do that?

spacebear21 · 2026-03-16T17:06:15Z

src/payment/payjoin/manager.rs

+		// is assumed to be broadcastable.
+		let proposal = proposal
+			.check_broadcast_suitability(None, |tx| {
+				self.chain_source


So here for example we could call proposal.assume_interactive_receiver() if applicable.

spacebear21 · 2026-03-16T17:13:07Z

src/payment/payjoin/manager.rs

+			Error::PayjoinSessionFailed
+		})?;
+		let proposal = proposal
+			.contribute_inputs(vec![selected_input])
+			.map_err(|e| {
+				log_error!(self.logger, "Failed to contribute inputs to payjoin: {}", e);
+				Error::PayjoinSessionFailed


Are these failure modes handled by broadcasting the fallback transaction? I'm trying to find where these errors are handled but not sure I'm tracing it correctly.

When the session propagates to a Closed state which is handled in handle_closed_session, On Failure or Cancel, the fallback transaction (extracted and stored at the start of check_proposal) is broadcast to ensure the receiver still gets paid.

I also have a question, Should failures at create_poll_request, try_preserving_privacy, contribute_inputs, and create_post_request trigger fallback broadcast immediately, or are these considered retryable until the session expires or propagates a Closed state? Wanted to align on the intended behavior before handling these inline.

Good question, I had to go back and think through each case which means our API should be clearer about this... Anyway these are my thoughts:

create_poll_request and create_post_request are fatal, they only error due to crypto or config errors that won't resolve. In these cases we should trigger fallback immediately.

try_preserving_privacy and contribute_inputs depend on the provided candidate inputs, so they are retryable in the sense that they could succeed with a different input set. Since list_input_pairs() is returning all spendable utxos, the "right" answer here depends on whether you want the user to maybe wait until new inputs become available, or just assume they won't change within the expiration window and broadcast the fallback immediately. I would guess there aren't many on-chain state changes to a typical ldk-node within a 24h window, so the latter choice seems appropriate.

Thanks. I will update the failure handling for these cases accordingly

try_preserving_privacy and contribute_inputs depend on the provided candidate inputs, so they are retryable in the sense that they could succeed with a different input set. Since list_input_pairs() is returning all spendable utxos, the "right" answer here depends on whether you want the user to maybe wait until new inputs become available, or just assume they won't change within the expiration window and broadcast the fallback immediately. I would guess there aren't many on-chain state changes to a typical ldk-node within a 24h window, so the latter choice seems appropriate.

Since these aren't fatal, I'd lean toward letting the session expire naturally rather than broadcasting immediately. The receiver is still covered on expiry.

spacebear21 · 2026-03-16T17:27:39Z

src/config.rs

+	/// The URL of the OHTTP relay to use for sending OHTTP requests to PayJoin receivers.
+	pub ohttp_relay: URL,


We can make this a list of OHTTP relays and randomize the relay per-request. This also improves reliability by enabling retries to other relays in case one is offline for any reason.

I changed ohttp_relay to ohttp_relays: Vec<URL>. Each request now picks a random starting relay and iterates through the rest as fallbacks, so if one relay is offline the next is tried immediately without waiting for a retry cycle.

spacebear21 · 2026-03-16T17:40:48Z

src/payment/payjoin/manager.rs

+			.payjoin_session_store
+			.list_filter(|s| {
+				let is_terminal =
+					s.status == PayjoinStatus::Completed || s.status == PayjoinStatus::Failed;


It may be desirable to keep "Completed" sessions ~forever since it makes it possible to reconstruct past Payjoins for e.g. displaying transaction history.

Completed payjoin sessions are already recorded as Payjoin payments in the PaymentStore with full details on success, so the session itself doesn't need to be kept long-term for history purposes. @tnull, what are your thoughts on this as well.

Makes sense, I see now PaymentDetails already contains all necessary information regarding payment amount and direction that would be ambiguous from the txid alone.

ldk-reviews-bot · 2026-03-18T09:53:03Z

🔔 3rd Reminder

Hey @tnull @zealsham @spacebear21 @bc1cindy! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

bc1cindy

this is really looking good! all fixes applied.

here are some minor points:

bc1cindy · 2026-03-18T00:14:46Z

src/chain/mod.rs

+						// Esplora does not support a testmempoolaccept equivalent
+						log_error!(
+							self.logger,
+							"Broadcast suitability check not supported by Esplora backend."


I think it's important to be explicit about probing attack, like: "Broadcast suitability check not supported by Esplora backend. Probing attack risk not mitigated."

This method could be called from other contexts down the line where probing attacks aren't relevant, so I'd rather keep the message generic and let the caller log any threat-specific context.

bc1cindy · 2026-03-18T00:15:07Z

src/chain/mod.rs

+						// Electrum does not support a testmempoolaccept equivalent.
+						log_error!(
+							self.logger,
+							"Broadcast suitability check not supported by Electrum backend."


I think it's important to be explicit about probing attack, like: "Broadcast suitability check not supported by Electrum backend. Probing attack risk not mitigated."

This method could be called from other contexts down the line where probing attacks aren't relevant, so I'd rather keep the message generic and let the caller log any threat-specific context.

bc1cindy · 2026-03-18T01:26:42Z

src/payment/payjoin/manager.rs

+		let count = payjoin_config.ohttp_relays.len();
+		let start = if count > 0 {
+			let mut bytes = [0u8; 8];
+			getrandom::fill(&mut bytes).unwrap_or(());


If getrandom::fill fails silently via unwrap_or(()) the selection it's going to be deterministically and not random

The randomisation here is just for load balancing. It's not security-critical. Even if getrandom fails, we still try all relays in order, so nothing breaks. The worst case is relay[0] always goes first. Failing hard on this would be overkill.

bc1cindy · 2026-03-18T15:01:14Z

src/payment/payjoin/manager.rs

+				self.payjoin_session_store.insert_or_update(session.clone())?;
+
+				let fallback_tx = session.fallback_tx.as_ref().ok_or_else(|| {
+					log_error!(self.logger, "Payjoin session {} missing txid.", session_id);


I believe it will be more clear using "Payjoin session {} missing fallback transaction", session_id) here

bc1cindy · 2026-03-18T15:02:02Z

src/payment/payjoin/manager.rs

+				self.payjoin_session_store.insert_or_update(session.clone())?;
+
+				let fallback_tx = session.fallback_tx.as_ref().ok_or_else(|| {
+					log_error!(self.logger, "Payjoin session {} missing txid.", session_id);


I believe it will be more clear using "Payjoin session {} missing fallback transaction", session_id) here

bc1cindy · 2026-03-18T16:54:26Z

src/payment/payjoin/manager.rs

+
+		// Note: broadcast suitability can only be fully verified when using the BitcoindRpc
+		// backend. For Esplora and Electrum backends this check is skipped and the transaction
+		// is assumed to be broadcastable.


it might also be good to explain probing attacks risk

Thanks for pointing this out, I will also update the comment here, as the broadcast check will no longer be skipped

bc1cindy · 2026-03-18T19:13:51Z

src/payment/payjoin/persist.rs

+		}
+	}
+
+	fn close(


close() sets Completed status, but its called from close_failed_session() (manager.rs:820), with log message "Closed failed {} session", which is semantically inconsistent. Should this be addressed?

Yes, it should be addressed. Thanks

ldk-reviews-bot · 2026-03-19T17:46:29Z

🔔 1st Reminder

Hey @tnull @zealsham @spacebear21! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-03-19T18:04:31Z

🔔 1st Reminder

Hey @tnull @zealsham @spacebear21! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-03-21T00:01:09Z

🔔 4th Reminder

Hey @tnull @zealsham @spacebear21! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-03-23T00:00:38Z

🔔 2nd Reminder

Hey @tnull @zealsham @spacebear21! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-03-23T00:00:40Z

🔔 2nd Reminder

Hey @tnull @zealsham @spacebear21! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-03-23T00:02:00Z

🔔 5th Reminder

Hey @tnull @zealsham @spacebear21! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

zealsham · 2026-03-23T12:28:02Z

src/config.rs

+#[derive(Debug, Clone)]
+#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
+pub struct PayjoinConfig {
+	/// The URL of the PayJoin directory to use for discovering PayJoin receivers.


Nit: the sender does not discover receivers using the directory.

i think just "The url of the payjoin directory" is fine

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.

ldk-reviews-bot · 2026-03-25T00:01:01Z

🔔 3rd Reminder

Hey @tnull @zealsham @spacebear21 @bc1cindy! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-03-25T00:02:16Z

🔔 6th Reminder

Hey @tnull @zealsham @spacebear21 @bc1cindy! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-03-26T10:50:08Z

🔔 1st Reminder

Hey @tnull @zealsham @spacebear21 @bc1cindy! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-03-26T10:51:11Z

🔔 1st Reminder

Hey @tnull @zealsham @spacebear21 @bc1cindy! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Thanks, and excuse the delay here!

Given this is a huge PR I'm still in the process of going through anything, but here's an initial rounds of comments that stood out on the first pass.

tnull · 2026-03-26T12:37:08Z

Cargo.toml

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

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


Given we're about to finally drop the reqwest/url dependencies from our dependency tree soon, it's a bit unfortunate that payjoin might take some more time to do so. I guess that's however expected.

I do however wonder about the other dependencies, e.g., are there any further efforts to reduce the dependency tree? (cc @spacebear21 @bc1cindy)

tnull · 2026-03-26T12:41:04Z

src/error.rs

+	/// Payjoin session failed.
+	PayjoinSessionFailed,
+	/// The operation is not supported by the current chain source.
+	UnsupportedChainSource,


I don't think we want to expose this as a user-facing runtime error ~ever. Anything we add as a feature should work with any of the chain sources. If we really find that some configuration can't work at all, we should catch that early the the build step and return a BuildError.

tnull · 2026-03-26T12:44:47Z

src/chain/electrum.rs

+					false,
+					"We should have started the chain source before getting transactions"
+				);
+				return Err(Error::TxLookupTimeout);


Why are we returning a Timeout error type here?

tnull · 2026-03-26T12:47:01Z

src/error.rs

 	/// A transaction sync operation timed out.
 	TxSyncTimeout,
+	/// A transaction lookup operation failed.
+	TxLookupFailed,


Hmm, 'tx lookup' is very generic and not very informative. It would be much better to return error types that reflect what payjoin operation failed exactly?

tnull · 2026-03-26T12:48:53Z

src/payment/payjoin/manager.rs

+		let persister = KVStorePayjoinReceiverPersister::new(
+			session_id,
+			Some(amount_sats * 1000),
+			self.payjoin_session_store.clone(),


nit: Please use Arc::clone here and elsewhere.

tnull · 2026-03-26T12:49:57Z

src/payment/payjoin/manager.rs

+		// Create a new persister for this session
+		let persister = KVStorePayjoinReceiverPersister::new(
+			session_id,
+			Some(amount_sats * 1000),


Seems odd this is hardcoded?

tnull · 2026-03-26T13:24:25Z

src/payment/payjoin/payjoin_session.rs

+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SerializedSessionEvent {
+	/// JSON representation of the event
+	pub event_json: String,


Ugh, let's avoid mixing serialization formats please. Rather than using a JSON string, please create a serialization wrapper (similar to what we did for the BDK objects) and have the event serialized as TLV.

Speaking of, does rust-payjoin offer any backwards/forwards compatibility guarantees for the data types we need to persist? (cc @bc1cindy @spacebear21)

tnull · 2026-03-26T13:26:13Z

src/payment/store.rs

+	/// reached [`ANTI_REORG_DELAY`] confirmations on-chain.
+	///
+	/// [`ANTI_REORG_DELAY`]: lightning::chain::channelmonitor::ANTI_REORG_DELAY
+	Payjoin {


I do wonder if we need a new variant here, or if it would make more sense to list it as Onchain with sub-classification Payjoin? (cf. open questions on #791)

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 10 times, most recently 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

spacebear21 reviewed Mar 16, 2026

View reviewed changes

DanGould mentioned this pull request Mar 17, 2026

LDK Node: add Payjoin support ZeusLN/zeus#3852

Open

Camillarhi force-pushed the payjoin-receiver branch from 0411ada to 8ceddbe Compare March 17, 2026 17:44

Camillarhi requested review from bc1cindy, spacebear21 and zealsham March 17, 2026 17:45

bc1cindy mentioned this pull request Mar 18, 2026

Should ohttp-relay selection be done on a per session basis in the cli payjoin/rust-payjoin#1385

Open

Camillarhi changed the title ~~Add Payjoin Receiver Support~~ Add Payjoin Receiver Support (BIP 77) Mar 18, 2026

bc1cindy reviewed Mar 18, 2026

View reviewed changes

spacebear21 mentioned this pull request Mar 18, 2026

Be specific about error handling for methods that don't return state transitions payjoin/rust-payjoin#1422

Open

zealsham reviewed Mar 23, 2026

View reviewed changes

Camillarhi force-pushed the payjoin-receiver branch from 8ceddbe to 37cfb71 Compare March 24, 2026 10:44

Camillarhi force-pushed the payjoin-receiver branch from 37cfb71 to 98a3bc5 Compare March 24, 2026 10:49

Camillarhi requested review from bc1cindy and zealsham March 24, 2026 10:50

arminsabouri mentioned this pull request Mar 25, 2026

Demonstrate failure handling with fallback TX broadcast payjoin/rust-payjoin#1164

Open

6 tasks

tnull reviewed Mar 26, 2026

View reviewed changes

		/// The URL of the OHTTP relay to use for sending OHTTP requests to PayJoin receivers.
		pub ohttp_relay: URL,

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!

spacebear21 left a comment

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!

tnull Mar 26, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ldk-reviews-bot commented Mar 18, 2026

Uh oh!

bc1cindy left a comment

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!

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

Camillarhi commented Jan 8, 2026 •

edited

Loading

ldk-reviews-bot commented Jan 8, 2026 •

edited

Loading

tnull Mar 26, 2026 •

edited

Loading

bc1cindy Mar 18, 2026 •

edited

Loading