feat: Add Lightning Network payment scheme for x402 #23
Conversation
There was a problem hiding this comment.
Summary of Changes
Hello @lingzhong, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request integrates a new exact payment scheme into the x402 protocol, leveraging the Lightning Network to facilitate instant, low-cost Bitcoin payments. The scheme is designed for high reliability and security, addressing common vulnerabilities while maintaining consistency with existing x402 patterns. It provides a clear framework for client-server interaction, payment processing, and robust server-side verification, aiming to enhance the protocol's capabilities for efficient digital commerce.
Highlights
- New Payment Scheme: Introduces an
exactpayment scheme specifically designed for the Lightning Network within the x402 protocol. - Instant & Micropayment Friendly: Enables sub-second settlement and supports micropayments with minimal fees, ideal for agent-to-agent commerce.
- Security Hardening: Implements robust security measures against preimage reuse and hash manipulation attacks, following Lightning Network best practices.
- Detailed Protocol Specification: Outlines the client-driven protocol flow,
PaymentRequirementsstructure,X-PAYMENTandX-PAYMENT-RESPONSEheader payloads, and a comprehensive server verification process.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in pull request comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
This pull request introduces a well-structured specification for the exact payment scheme on the Lightning Network within the x402 protocol. The document effectively covers the protocol flow, data structures, and security considerations. My feedback focuses on correcting inaccuracies in the JSON examples and enhancing the protocol's error handling capabilities to improve clarity and developer experience for implementers.
6c5a739 to
39b999e
Compare
jorellis
left a comment
There was a problem hiding this comment.
Thanks for this PR, Ling! Two things I'm thinking about:
-
File Structure
We might want to do a bit of a refactor where we move the
v0.1/schemes just up a directory, so the schemes don't need to be moved or udpated every time a new version is sent out. Let me know if what you think! -
Architectural Pattern
This flow breaks a little bit from the typical x402 flow. Here the server manages its own invoice database and verifies the preimage, rather than using a facilitator's /verify and /settle endpoints.
I think we will want to continue to follow the flow where the server gets a PaymentPayload and is able to verify it via a facilitator before processing the request and then settling the transaction. @CarsonRoscoe what do you think? We should look into what a Lightning facilitator would look like if we wanted to follow that flow.
Happy to discuss this further. Thanks!
Agree. The schemes and the extension versioning should be managed independently. Raised #30 to address the directory refactor. Will defer scheme version management to the future (likely will following how the x402 main repo handles it)
Agree. If the (Merchant) server verifies and manages the preimage directly, then it's part of the payment implementation, which violates the separation of concerns between the Merchant role and the payment Facilitator role. I'll rework the responsibility details of relevant section to conform with the typical flow/pattern. Would love to learn Carson's thought as well! |
|
Modified the protocol flow and diagram to conform to pattern in https://github.com/coinbase/x402?tab=readme-ov-file#v1-protocol-sequencing while retaining BOLT11 best practices for security. |
Introduce comprehensive Lightning Network payment scheme enabling instant, low-fee Bitcoin payments for agent-to-agent commerce. Key features: - Native BOLT11 invoice support with preimage verification - Sub-second payment settlement for AI services - Security hardened against preimage reuse and hash manipulation attacks - Production-ready server verification process - Consistent with existing Spark and UMA scheme patterns Technical implementation: - Payment correlation via server-maintained invoice database - Comprehensive verification including amount and timing validation - Protection against known Lightning Network vulnerabilities - Simple preimage-based proof of payment
- Remove server-side invoice management and verification logic - Add Lightning facilitator responsibilities for invoice generation and verification - Update protocol flow to follow standard x402 verify/settle pattern - Simplify PaymentPayload to contain only preimage - Maintain all Lightning security requirements within facilitator architecture
- Fix client direct payment: facilitator now pays Lightning Network - Fix PaymentPayload: contains signed authorization, not preimage - Fix verification: validates client signatures, not preimages - Fix settlement: facilitator executes Lightning payment and obtains proof - Update security model for authorization-based architecture - Ensure full compliance with coinbase x402 protocol pattern
06ae345 to
db46896
Compare
Summary
Key Features
Technical Implementation
Test Plan