[nisargpatel7042lva]

part of #116

Second of the three NWC sub-PRs (B2 of B1-B3). Stacked on #117; diff base 408a37f. I'll rebase onto main once the parent merges.

Adds LnBolt11NwcPaymentProcessor for PMI bitcoin-lightning-bolt11, behind the same off-by-default nwc feature. It plugs into the PaymentProcessor trait Phase A froze: no trait, middleware or registration entry point changes.

create_payment_required mints a BOLT11 invoice with make_invoice in msats with an expiry, caches the invoice to payment_hash mapping, and advertises the configured TTL rather than the wallet's own expires_at, which providers return in non-standard forms. verify_payment then waits for settlement, either by polling lookup_invoice on the ts backoff schedule or by waiting on a payment_received notification.

The main thing to review: bounds and cancellation, because this is where money moves

Three separate bounds, each doing a different job, and it is worth checking I put them in the right places:

1. create_payment_required has only the client's response_timeout. It runs in the middleware's unbounded, cancellation-blind initiation phase, so nothing else can stop a hung wallet from wedging it. a_hung_wallet_fails_creation_inside_the_response_timeout pins that.
2. verify_payment selects on params.cancel at every wait — before each poll, around the wallet call itself, around the sleep, and around the notification wait. A poller that only checked the token between polls would sit inside a hung lookup_invoice well past the payment TTL, still holding a wallet connection. a_cancelled_verify_errors_and_stops_polling asserts the wallet stops being called after cancellation, not just that the call returns.
3. A cancelled verify always returns Err. Ok(VerifyOutcome::default()) would be read by the middleware as "paid" and would forward an unpaid invocation. Every cancellation path in the file goes through one cancelled() helper so there is a single place to audit.

The in-flight dedup is a Shared future keyed by pay_req, so duplicate delivery of one request cannot multiply wallet and relay load (dedupes_concurrent_verifies_for_the_same_invoice asserts three concurrent verifies make exactly one wallet call). PaymentError is not Clone, so the shared output is Arc<Result<..>> and joiners re-wrap the error by message. The slot is released once the future settles, so a later retry of the same invoice re-runs rather than replaying a stale terminal answer.

One wart inherited from ts and left as-is: callers deduplicated onto one verification share the first caller's cancellation token, so if that one is cancelled the joiners see an Err too. That is a liveness wart, not a safety one — the invoice stays payable, the dedup entry keeps its TTL, and the middleware reads a non-settlement. Worth a look if you would rather it behaved differently.

Settlement classification

The predicate is deliberately generous in one direction and strict in the other:

• Settled on state == "settled" or a positive settled_at. Wallets populate one or the other; requiring both would strand real payments. settles_on_settled_at_without_a_state covers the second path.
• Terminal on expired or failed.
• Pending on NOT_FOUND, because a lagging wallet that has not yet seen its own invoice has not refused it. Every other wallet error code is fatal. not_found_is_pending_and_other_codes_are_fatal checks both halves.

The receipt prefers payment_hash, a stable identifier that is not the preimage, and falls back to ts's settled:<request_event_id>[:<settled_at>] for wallets that omit it on lookup.

Notification mode

Auto-detected once from the wallet's info event through a OnceCell, with an explicit Some(true) / Some(false) short-circuiting the probe entirely. A probe failure means polling, never a hard error.

The subscription installs exactly once, via a second OnceCell. RelayPoolTrait has no unsubscribe, so two verifications racing here would each install a sink and the extra one would live for the process lifetime. concurrent_verifies_subscribe_for_notifications_exactly_once drives that race.

Deliberate divergences from ts

1. No payment_hash cached means fall back to polling, where ts throws NWC notification verification requires payment_hash. A payable invoice should not fail verification because the wallet declined to return a hash on make_invoice. notification_mode_without_a_cached_hash_polls_instead_of_erroring pins the new behavior.
2. Jitter comes from the clock, not a RNG. This crate has no direct rand dependency and I did not want to add one for de-stampeding, which needs spread, not unpredictability. If you would rather have a real RNG, say so and I will add the dependency.
3. Amounts are validated before any wallet call (sats_to_msats rejects non-positive and uses checked_mul), where ts does a bare multiply. rejects_non_positive_and_overflowing_amounts_before_calling_the_wallet also asserts the wallet call count stays at zero.

Log hygiene

An invoice is a bearer payment request, so no_tracing_call_carries_the_invoice parses whole tracing:: macro invocations out of the implementation and asserts none of them binds pay_req, invoice, preimage or secret as a field. It scans whole invocations rather than single lines because a tracing::debug! spans several and its fields are never on the first one, and it is boundary-aware so that has_preimage = ...is_some() — a boolean, which is exactly what we do want logged — is not mistaken for preimage = ....

I got that test wrong three times before it was right, each time with correct code and a broken check. Flagging it because the final version is doing something slightly clever and deserves a read.

Verification

cargo fmt --check clean, cargo clippy --all-features --all-targets clean, 1107 tests pass under --all-features with 0 failures, --no-default-features and default builds green, MSRV 1.88 compiles. 23 tests in this module, covering every case listed for B2 in #116.

One gap remains open. Issue #116 asks for mutation testing of the money paths (the cancellation arms, the settlement predicate, the NOT_FOUND branch, the dedup claim). Those arms all have direct tests, but I have not run a mutation tool over them. Happy to do that before merge if you want it as a gate rather than a follow-up.

Not in this PR

B3: the client-side handler, the e2e suite over one MockRelayPool group, the #[ignore]d real-wallet test, the Cargo.toml test entries, and the docs. docs/payments.md still describes Phase B as deferred and still lists LNbits as planned; both are B3's to correct.