google-agentic-commerce · lingzhong · Sep 24, 2025 · Sep 18, 2025 · Sep 18, 2025 · Sep 18, 2025
@@ -0,0 +1,151 @@
+# Exact Payment Scheme for Lightning Network
+
+This document specifies the `exact` payment scheme for the x402 protocol on Bitcoin's Lightning Network.
+
+This scheme facilitates instant, low-fee Bitcoin payments using native Lightning Network capabilities with BOLT11 invoices and preimage verification.
+
+## Scheme Name
+
+`exact`
+
+## Key Features
+
+- **Proven Standard**: Uses broadly adopted BOLT11 spec to maximize compatibility
+- **Instant Settlement**: Sub-second payment confirmation
+- **Micropayment Friendly**: Sub-cent transactions with minimal fees
+- **High Reliability**: Exceptional payment success rates with robust error handling
+- **Security Hardened**: Protects against preimage reuse and routing attacks
+
+## Protocol Flow Overview
+
+The protocol flow for `exact` on Lightning Network follows the standard [x402 pattern](https://github.com/coinbase/x402?tab=readme-ov-file#v1-protocol-sequencing):
+
+1. **Client** makes an HTTP request to a **Resource Server**
+2. **Resource Server** calls Lightning Facilitator to generate payment requirements with BOLT11 invoice
+3. **Resource Server** responds with a `402 Payment Required` status containing the `paymentRequirements`
+4. **Client** creates signed authorization to pay the specific BOLT11 invoice
+5. **Client** sends payment submission with `PaymentPayload` containing the signed authorization
+6. **Resource Server** calls Lightning Facilitator to verify the client's authorization signature
+7. **Resource Server** calls Lightning Facilitator to settle payment (facilitator pays Lightning invoice)
+8. **Resource Server** grants the **Client** access to the resource
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+   participant Client
+   participant ResourceServer
+   participant LightningFacilitator
+   participant LightningNetwork
+
+   Client->>ResourceServer: Request service
+   ResourceServer->>LightningFacilitator: Generate payment requirements
+   LightningFacilitator-->>ResourceServer: PaymentRequirements with BOLT11 invoice
+   ResourceServer-->>Client: 402 Payment Required
+
+   Client->>Client: Create signed authorization for BOLT11 invoice
+   Client->>ResourceServer: Submit PaymentPayload with authorization
+   ResourceServer->>LightningFacilitator: Verify authorization
+   LightningFacilitator-->>ResourceServer: VerifyResponse (valid/invalid)
+   ResourceServer->>LightningFacilitator: Settle payment
+   LightningFacilitator->>LightningNetwork: Pay BOLT11 invoice
+   LightningNetwork-->>LightningFacilitator: Payment complete (preimage)
+   LightningFacilitator-->>ResourceServer: SettleResponse (success/failure)
+   ResourceServer-->>Client: Service delivered
+```
+
+## `PaymentRequirements` for `exact`
+
+```json
+{
+  "scheme": "exact",
+  "network": "lightning",
+  "maxAmountRequired": "5000000",
+  "asset": "BTC",
+  "payTo": "03a1b2c3d4e5f6789...",
+  "resource": "https://api.example.com/ai-service",
+  "description": "Batch AI inference request",
+  "mimeType": "application/json",
+  "maxTimeoutSeconds": 60,
+  "extra": {
+    "invoice": "lnbc50u1..."
+  }
+}
+```
+
+### Field Descriptions
+
+* `maxAmountRequired`: Payment amount in millisatoshis (msat)
+* `asset`: The currency to be paid ("BTC")
+* `payTo`: Lightning node public key
+* `extra.invoice`: BOLT11 Lightning invoice generated by the facilitator
+
+
+## `PaymentPayload` Structure
+
+The client submits payment authorization using the standard x402 `PaymentPayload` format:
+
+```json
+{
+  "x402Version": 1,
+  "scheme": "exact",
+  "network": "lightning",
+  "payload": {
+    "invoice": "lnbc50u1...",
+    "signature": "0x123abc...",
+    "from": "0x456def..."
+  }
+}
+```
+
+The `payload` field contains the client's signed authorization to pay the specific BOLT11 invoice, not the preimage (which the facilitator obtains when executing the payment).
+
+## Lightning Facilitator Responsibilities
+
+The Lightning Facilitator handles all Lightning-specific operations:
+
+### Invoice Generation
+- Generate BOLT11 invoices with correct amount and expiry
+- Store invoice metadata (payment_hash, amount, expiry) for later verification
+- Return `PaymentRequirements` with invoice in `extra.invoice` field
+
+### Payment Verification
+- Receive `PaymentPayload` with client authorization from server
+- Validate client's signature on the authorization
+- Confirm authorization matches a generated BOLT11 invoice
+- Check client has authority to authorize this payment
+- Verify invoice hasn't expired or been used
+- Return `VerifyResponse` with validation result
+
+### Payment Settlement
+- Use verified authorization to pay the BOLT11 invoice on Lightning Network
+- Obtain preimage as proof of successful Lightning payment
+- Record settlement in facilitator's database with preimage proof
+- Return `SettleResponse` with transaction details
+- Clean up used authorizations and expired invoices
+
+## Security Considerations
+
+**Lightning Facilitator Security**:
+- MUST store invoice metadata securely with payment_hash indexing
+- MUST validate client signatures on payment authorizations
+- MUST verify authorization corresponds to a legitimate generated invoice
+- MUST prevent authorization reuse through nonce tracking
+- MUST validate invoice amounts match original payment requirements
+- MUST handle invoice expiry and authorization timeouts properly
+- MUST secure Lightning Network credentials for payment execution
+
+**Resource Server Security**:
+- MUST delegate all Lightning verification and settlement to the facilitator
+- MUST NOT implement Lightning-specific logic directly
+- MUST follow standard x402 verify/settle pattern
+- MUST NOT store or handle Lightning Network credentials
+
+---
+
+## References
+
+- [BOLT 11: Invoice Protocol for Lightning Payments](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
+- [Lightning Network Security Guidelines](https://lightning.engineering/security/)
+- [x402 Core Protocol Specification](https://github.com/coinbase/x402)
+- [Lightning Network Developer Resources](https://lightning.engineering/)