docs: add Section 7 — Wallet and Payment Processor Requirements

[refined-element]

Summary

Adds a new top-level Section 7, "Wallet and Payment Processor Requirements," to protocol-specification.md, addressing a compatibility gap when the underlying Lightning settlement bypasses HTLC routing. Renumbers existing Sections 7–11 to 8–12 to accommodate.

Motivation

L402's proof-of-payment chain depends on the client obtaining the payment preimage r after invoice settlement. In typical Lightning Network routing, r propagates back to the client's wallet through the HTLC settlement chain — no normative wallet behavior is required for L402 to work.

However, when both the payee and payer are hosted by the same custodial Lightning service, that service may settle the payment internally — crediting the payee's account and debiting the payer's account without routing the payment over the Lightning Network. In this scenario:

• No HTLC chain forms.
• r is generated at invoice creation by the custodian and sits in their database.
• r is never propagated to the client through Lightning protocol mechanisms.

If the custodian's payer-facing API does not surface r after settlement, the client has no preimage to present in the L402 Authorization header, even though the invoice is fully paid. The proof chain is broken: the merchant has the funds, the buyer can't construct a valid L402 token, and the resource access is denied.

This has been observed in production with at least one major custodial Lightning provider whose own developer documentation explicitly describes the optimization (same-currency-region same-app payments executed as internal account transfers, "instant and incurs no routing or on-chain fees") but does not document preimage availability on the payer side. The optimization is intentional and arguably correct from a custodial UX perspective; the L402 incompatibility is collateral damage of a design decision that makes sense in every other respect.

The spec-evolution path is one of several ways to close this gap (others include BOLT12 with blinded paths, which would force real routing by hiding the destination from the payer's wallet, and a vendor opt-in flag forcing real routing per invoice). These approaches are complements, not alternatives. This PR addresses the spec-evolution path: making preimage availability a wallet/processor requirement so the custodian-side fix becomes unambiguous expected behavior rather than a per-integrator request.

What this PR adds

A new Section 7 "Wallet and Payment Processor Requirements" with three normative bullets:

1. A wallet or payment processor MUST surface the payment preimage r to the client for any settled invoice, regardless of whether settlement occurred via HTLC routing or via internal accounting on a single custodial service.

2. A wallet or payment processor that omits r from the payment-confirmation response for an internally-settled invoice SHOULD be considered non-compliant with this specification for L402 authentication purposes.

3. A wallet or payment processor MUST NOT release the preimage r to the client prior to settlement of the corresponding invoice. In standard Lightning routing this is enforced by the HTLC protocol; in internal-settlement implementations it MUST be enforced by the wallet or payment processor's accounting logic. The L402 server's stateless H == sha256(r) check (Section 6.1) assumes that possession of r by the client implies the invoice has been settled.

The third bullet is included to make explicit the implicit binding between preimage possession and settlement that the protocol's stateless verification relies on. In the standard HTLC path this is enforced cryptographically by Lightning itself; in the internal-settlement path it has to be enforced by the wallet or payment processor's accounting logic. Without this requirement, a wallet could naively interpret bullet 1 as "release the preimage at invoice creation" and break the L402 server's stateless verification model.

The section explicitly notes that these requirements apply protocol-agnostically — to the HTTP flow (Section 6) and the gRPC flow (Section 8) equally — and that they impose no requirement on the underlying Lightning settlement path. Only what the wallet or payment processor surfaces to the client after settlement is constrained.

Why a new top-level section

Wallets and payment processors are a third actor in the L402 protocol, alongside the server (Section 6.1) and the client (Section 6.2). Their obligation is protocol-agnostic. Placing the requirement as a subsection under "HTTP Protocol Flow" (Section 6) would imply HTTP-specific scope, which is incorrect. A new top-level section preserves structural parity and makes the wallet/processor obligation discoverable.

If the structural placement is the wrong call, happy to revise — could go as a subsection 6.3 with a one-line cross-reference from the gRPC section.

What this PR does NOT change

• No change to the L402 challenge format, credential format, or authentication scheme.
• No change to existing server or client obligations.
• No change to the gRPC flow itself — only its section number shifts (7 → 8).
• No requirement on Lightning settlement implementations to alter their routing or settlement behavior. Internal settlement remains a valid optimization; only preimage surfacing and settlement ordering are constrained.

Renumbering

Sections 7 through 11 of the prior version shift to 8 through 12 in this PR:

• Section 7 (gRPC Protocol Flow) → Section 8
• Section 8 (Credential Reuse and Revocation) → Section 9
• Section 9 (Security Considerations) → Section 10
• Section 10 (Backwards Compatibility) → Section 11
• Section 11 (References) → Section 12

Subsection numbering shifts accordingly (e.g., 9.1 → 10.1). All internal cross-references within the document remain accurate — every existing Section N.M reference points to Section 5.x or Section 6.x, both of which are unchanged.

Acknowledgments

Thanks to Hannah at Lightning Labs DevRel for the pointer to this repo as the right place to land this contribution and for the framing pushback that sharpened the proposed addition. The "implementation issue, not a protocol break" framing is hers; this PR closes the spec gap so that the implementation expectation is normatively explicit.

[Copilot]

Pull request overview

Adds a new top-level specification section defining normative wallet/payment-processor behavior required for L402 to work when Lightning settlement occurs via internal custodial accounting (i.e., no HTLC route to propagate the preimage). This closes a compatibility gap where an invoice can be paid but the client cannot obtain the preimage needed to form an L402 credential.

Changes:

• Introduces Section 7: Wallet and Payment Processor Requirements, including MUST/MUST NOT requirements around preimage surfacing and settlement ordering.
• Renumbers the existing sections (gRPC flow and onward) from 7–11 to 8–12.
• Updates the affected heading/subheading numbers to match the new section ordering.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lightninglabs-deploy]

@refined-element, remember to re-request review from reviewers when ready