Add Payjoin Receiver Support (BIP 77)

[Camillarhi]

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 partially fixes #177 and fixes #1019

[ldk-reviews-bot]

👋 I see @tnull was un-assigned.
If you'd like another reviewer assignment, please click here.

[DanGould]

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]

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]

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

[Camillarhi]

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]

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

[ldk-reviews-bot]

🔔 18th Reminder

Hey @tnull @DanGould @zealsham! 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]

🔔 18th Reminder

Hey @tnull @DanGould @zealsham! 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]

🔔 20th Reminder

Hey @tnull @DanGould @zealsham! 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]

🔔 19th Reminder

Hey @tnull @DanGould @zealsham! 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]

🔔 19th Reminder

Hey @tnull @DanGould @zealsham! 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]

As mentioned elsewhere, we'll defer this to the 0.9 milestone. For now removed the review requests to silence the 5-fold notifications every day. Still ofc. intend to get back to this soon though.

[Camillarhi]

@spacebear21 notified me out of band that version 1.0 has been released. This PR has been updated and now builds on the released 1.0.0. The 1.0 API moved a fair bit from the version the PR was originally based on, and I have handled all the changes it introduced. I also tested end-to-end on regtest against a Polar bitcoind, with payjoin-cli as the sender.

@bc1cindy @spacebear21 @DanGould @zealsham, ready for another look since some changes have been made since the last review due to the version bump.

[xstoicunicornx]

I did a cursory review using Opus and Sol and found a couple larger design considerations that probably should be reworked before doing a low level review. There were also some straightforward implementation issues that I think are secondary to the design considerations. For now I think we should focus on resolving the design considerations before proceeding with cleaning up the implementation issues.

With that being said, please let me know if there is anything here is inaccurate.

Design considerations

Payjoin is not feature gated

I guess whether Payjoin should be feature gated is something that would require input from LDK team, however I would imagine that it probably should be.

Even if the LDK team determines that Payjoin should not be feature gated, the current implementation breaks other currently supported features like uniffi-default. When you run:

cargo check --no-default-features --features uniffi-default

it fails with errors.

Bitcoin core is mandatory dependency (which is not explicitly enforced at build time)

Currently Payjoin requires the Bitcoin core backend during the LDK node construction and throws an error if not found. This basically makes Bitcoin core a silent dependency of Payjoin that is only found at run time instead of build time when the Payjoin configuration exists. This feels like a bad anti-pattern.

The main part of this concern is that nodes that rely on Esplora or Electrum backends cannot use Payjoin. Additionally, this also makes Payjoin unusable by the uniffi bindings (as mentioned in previous section).

My suggestion

The best suggestion I can think of is to enable the bitccoinconcensus feature within bitcoin library and do a best effort check for Esplora and Electrum:

1. Fetch every previous output.
2. Check that those outputs appear unspent.
3. Run Transaction::verify.
4. Check input and output totals and fee rate.
5. Check lock-time constraints.
6. Apply locally implemented standardness limits.

What do you think of this approach? I think the 2 main requirements that implementing Payjoin in LDK node should have (other than not breaking anything) are:

1. Can run with all backends
2. Can be exported in uniffi bindings

As for whether Payjoin should be feature gated I think I lean towards not feature gating it, or at least making it a default feature, however I would defer to LDK maintainers on that.

Implementation details

Anchor reserve not protected from being used in Payjoin tx

Anchor reserve UTXO can potentially be selected as an input to the Payjoin tx. contribute_inputs reads get_spendable_amount_sats(cur_anchor_reserve_sats) and bails only if it's zero, then hands try_preserving_privacy the output of list_unspent_confirmed_utxos, which is every confirmed UTXO with no exclusions. Nothing stops the selected input from being the UTXO backing the anchor reserve.

Lack of UTXO locking

Contributed UTXOs are never locked or reserved. A concurrent send_to_address, a channel open, or a second payjoin session can select the same UTXO. Selection and reservation should be one wallet operation. The selected outpoint should be persisted in the session, excluded from other spends, and released when the session becomes terminal.

Mid-session errors strand the fallback for ~24h

Non-transient Err out of process_receiver_session is caught in the JoinSet drain and only logged. Session stays Active, replays and fails every 15s, fallback never broadcasts, sender waits out directory expiry. A temporary UTXO shortage becomes a day-long hang.

Relay requests have no timeout and allow very large responses

post_request() uses a bare bitreq request:

bitreq::post(req.url)
    .with_header(...)
    .with_body(...)
    .send_async()

See src/payment/payjoin/manager.rs:282-291.

bitreq has no timeout by default and permits bodies up to 1 GiB by default. A stalled or hostile relay can hold a session task forever. Because resume_payjoin_sessions() waits for the whole JoinSet, one stuck session also prevents later 15-second resume rounds.

These requests need a timeout, a small protocol-specific body limit, and explicit status validation.

The scheduler does unbounded work every 15 seconds

Every cycle:

• Scans all active sessions.
• Replays every complete event log.
• Spawns one task per session.
• Polls monitoring sessions every two seconds.
• Potentially issues concurrent Bitcoin Core RPC requests.

There is no session limit, concurrency limit, per-session backoff, or next-attempt timestamp. Applications can create unused URIs for 24 hours, making this an easy local resource exhaustion path.

A per-session worker or persisted next-action schedule with bounded concurrency would fit better.

The public API hides the session lifecycle

receive() returns only a URI:

pub async fn receive(...) -> Result<String, Error>

There is no public session ID, status query, cancellation method, or user-facing event. Background failures are only logged. The application cannot reliably correlate a URI with the resulting payment or distinguish an active session from a failed one.

Returning a session handle containing the URI and ID would leave room for status() and cancel().

Disabling Payjoin strands existing sessions

The manager is constructed only when config.payjoin_config is present. If a node issued Payjoin URIs and restarts without that config, its active persisted sessions are ignored. They will not be polled, expired, or closed with fallback.

Existing active sessions should at least cause a warning or build error when Payjoin is disabled.