Lightning Python reference implementation — design questions before PR

[Bortlesboat]

Building on the Lightning scheme spec in #1311, I've been working on a Python reference implementation and wanted to get feedback on a few design decisions before opening a PR.

Chain identification

Using the existing Bitcoin CAIP-2 identifier (bip122:000000000019d6689c085ae165831e93) with extra.paymentMethod = "lightning" to distinguish from on-chain. Seemed cleaner than introducing a new CAIP namespace — thoughts?

Naming

The existing x402 pattern uses "signer" terminology but that doesn't really map to Lightning where there's no transaction signing in the traditional sense. I went with LightningPayer / LightningReceiver instead. Open to other suggestions.

Facilitator settle() and replay protection

Since Lightning payments are atomic (preimage proves payment), settle() just returns the payment_hash as the txn identifier. For replay protection, BOLT11 invoices are inherently unique via payment_hash, and verification checks against actual node payment records — so no extra nonce mechanism needed.

Dependencies

Only hard dependency is bolt11 for invoice encoding/decoding. No LND/CLN/Eclair-specific deps in core. Node adapters would live separately.

Amount handling

BOLT11 uses millisatoshis on the wire so that's what I'm using internally, with explicit msat_to_sat() / sat_to_msat() conversion helpers since mixing those up is a common footgun.

Proposed structure would be under mechanisms/bip122/exact/ with types, payer, receiver, facilitator, and utils modules.

Happy to start a PR once the approach looks right.

[Bortlesboat]

I think the split between settlement evidence and authorization evidence is real. I just don't think the Lightning mechanism itself is the right place to solve it.

For this PR I'm planning to keep settle() narrow and return payment_hash as the settlement identifier. That keeps the mechanism focused on the Lightning-native proof surface and replay story.

The extra fields you're describing (authorized_by, correlation to the triggering request, operator-facing audit context) feel like generic x402 workflow metadata, not Lightning settlement semantics. If we want that surfaced in Python, I'd rather do it as a generic receipt / extension / hook story across mechanisms, not as Lightning-specific fields in the core API.

So my plan is to keep the Lightning PR scoped to mechanism behavior, and treat richer receipt/audit metadata as follow-up work.