Skip to content

python: add Lightning reference implementation under bip122/exact#1873

Open
Bortlesboat wants to merge 3 commits intocoinbase:mainfrom
Bortlesboat:codex/lightning-python
Open

python: add Lightning reference implementation under bip122/exact#1873
Bortlesboat wants to merge 3 commits intocoinbase:mainfrom
Bortlesboat:codex/lightning-python

Conversation

@Bortlesboat
Copy link
Copy Markdown
Contributor

Description

Adds a Python Lightning reference implementation under python/x402/mechanisms/bip122/exact/.

This keeps the PR scoped to mechanism behavior:

  • uses the existing Bitcoin CAIP-2 network identifiers and extra.paymentMethod = "lightning"
  • adds LightningPayer / LightningReceiver adapter protocols for client and receiver integrations
  • generates BOLT11 invoice-backed payment requirements on the server side
  • verifies paid invoices and returns payment_hash from settle() as the settlement identifier
  • treats sats as the default Money input and converts to msats internally, with explicit helper functions for sats <-> msats
  • adds duplicate-settlement protection keyed by payment_hash
  • keeps the core dependency surface narrow by only adding bolt11
  • adds focused unit coverage plus a sync end-to-end roundtrip through x402ClientSync, x402ResourceServerSync, and x402FacilitatorSync

This intentionally does not add operator-facing audit or receipt fields like authorized_by to the Lightning settlement response. That is broader x402 workflow metadata and should be handled separately from the Lightning mechanism API.

Closes #1857.

Tests

  • cd python/x402 && ./.venv/Scripts/python.exe -m ruff format mechanisms/bip122 tests/unit/mechanisms/bip122
  • cd python && ./x402/.venv/Scripts/python.exe -m ruff check x402/mechanisms/bip122 x402/tests/unit/mechanisms/bip122
  • cd python && ./x402/.venv/Scripts/python.exe -m pytest x402/tests/unit/mechanisms/bip122 -q
  • cd python && ./x402/.venv/Scripts/python.exe -m pytest x402/tests/unit/mechanisms -q
  • cd python && ./x402/.venv/Scripts/python.exe -m pytest x402/tests/unit -q
  • cd python && ./x402/.venv/Scripts/python.exe -m pytest x402/tests -q

Checklist

  • I have formatted and linted my code
  • All new and existing tests pass
  • My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits
  • I added a changelog fragment for user-facing changes

@cb-heimdall
Copy link
Copy Markdown

cb-heimdall commented Mar 30, 2026

🟡 Heimdall Review Status

Requirement Status More Info
Reviews 🟡 0/1
Denominator calculation
Show calculation
1 if user is bot 0
1 if user is external 0
2 if repo is sensitive 0
From .codeflow.yml 1
Additional review requirements
Show calculation
Max 0
0
From CODEOWNERS 0
Global minimum 0
Max 1
1
1 if commit is unverified 0
Sum 1

@vercel
Copy link
Copy Markdown

vercel bot commented Mar 30, 2026

@Bortlesboat is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

@github-actions github-actions bot added sdk Changes to core v2 packages python docs labels Mar 30, 2026
@github-actions github-actions bot added the ci label Mar 30, 2026
@Bortlesboat Bortlesboat marked this pull request as ready for review March 30, 2026 15:22
@Bortlesboat Bortlesboat changed the title [codex] python: add Lightning reference implementation under bip122/exact python: add Lightning reference implementation under bip122/exact Mar 30, 2026
Verify bip122/exact mechanism is wire-compatible with Alby's
live Lightning facilitator at x402.albylabs.com. Tests confirm
schema parsing, CAIP-2 network match, and x402Version alignment.
@Bortlesboat
Copy link
Copy Markdown
Contributor Author

Added compatibility tests against Alby's live Lightning facilitator (x402.albylabs.com/supported). All 7 tests pass — confirms our bip122/exact mechanism is wire-compatible:

  • SupportedResponse schema parses correctly
  • Network matches: bip122:000000000019d6689c085ae165831e93 (mainnet)
  • Scheme: exact, version: 2
  • Signers map includes bip122:*

39 total tests passing (32 unit + 7 facilitator compat).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci docs python sdk Changes to core v2 packages

Development

Successfully merging this pull request may close these issues.

Lightning Python reference implementation — design questions before PR

2 participants