Skip to content

Async payments: document the LSPS2 JIT-channel flow variant #317

Description

@ConorOkus

Follow-up from the async payments guide

The async payments guide (added in #314, corrected in #316) covers the core offline-receive flow. It does not yet cover the LSPS2 (JIT channel) variant, which differs in a few important ways and deserves its own section.

What's different about the LSPS2 flow

Unlike the base flow, the LSPS2 path requires pre-negotiated parameters to be threaded through the payment itself:

  1. Pre-negotiate LSPS2 parameters. The recipient and its LSP agree on the respective LSPS2 parameters ahead of time (out of band).
  2. Encode params in the payment metadata. Those negotiated parameters have to be encoded into the payment metadata so they can be recovered later in the flow.
  3. Decode and inject intercept SCIDs. At the right point in the flow, the parameters are decoded and the intercept SCID is injected into the payment paths.
  4. Payer pays over the imaginary SCID. The payer ends up routing over that imaginary/intercept SCID.
  5. LSP detects and opens a JIT channel. Forwarding over the intercept SCID signals the LSP that it should open a just-in-time (JIT) channel before forwarding the payment to the recipient.

Why this matters

This is the mechanism that lets an LSP provide inbound liquidity on demand for async/offline recipients, so it's a natural and commonly-requested extension of what the current guide describes.

Suggested scope

  • New section in the async payments guide (or a dedicated guide) covering the LSPS2 JIT variant
  • Document how the LSPS2 parameters are encoded into / decoded from payment metadata
  • Document where intercept SCIDs are injected into the payment paths and the LSP-side handling that triggers JIT channel open
  • Cross-link with the existing lightning-liquidity guidance request (#301) if relevant

Filed as a follow-up to #314 / #316.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions