x402-rails 0.2.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bfc5a5a404b98b156b9c8ad7d833787e5f082eff1b5d5b95e18663a1cb64fc8
-  data.tar.gz: 0bda82b7d122d5b6fbbe6278db1dcd19efda67a6418ee2d8d6a23fb74ecd55fd
+  metadata.gz: 71561f4eae4f693705a405fd47e2b51a493441abd96dfe5a7d415915cdaa1313
+  data.tar.gz: 251fa92d63aaaa4e944040192b55b1db1ed154cb26d62aaac7f86a200bbc5e07
 SHA512:
-  metadata.gz: 88f0a27e97ee07b7ae746d7e0ecef9c8676bd8b40544fadead68f6eae5d57b5e318c73edf03645d97670ce197334b596e086d948e92c711ad7fe488f2a1666df
-  data.tar.gz: c5647b5c8ce65f3bbdd2dde221afbd2a27240d77e12ba2f6e0c1387a1b046e170efbdbf5288898cc5b670ea9ee615d92f579e28d4f78b86558787ad5d90ebe77
+  metadata.gz: 753e8a4957ebbc21189826904e370ef90ae618aca1078c0889351aa6841106bffc237ee1a893eeba745c8d75773c30f25d083d4e033466ef2a0f3d327f4c239e
+  data.tar.gz: 359cdbfd614777f9004a96aa4b2d5b9eff290266247707d9b886cafd1731bd3fa667625e641da16ea9383e5c3d2a3e74d79c0cf068a9be455ad4115a10715b19

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-01-07
+
+### Added
+- **Protocol v2 support** - Full x402 protocol v2 compliance with CAIP-2 network identifiers and updated headers
+- **v2 `PAYMENT-REQUIRED` header** - 402 responses include base64-encoded PaymentRequired in header per v2 HTTP transport spec
+- **v2 PaymentPayload format** - `scheme` and `network` nested inside `accepted` object per v2 spec
+- **v2 PaymentRequired format** - `resource` info at top level, `amount` field (not `maxAmountRequired`), `extensions` object
+- **Multi-chain accept** - `config.accept(chain:, currency:)` allows accepting payments on multiple chains simultaneously
+- **Per-endpoint version override** - `x402_paywall(amount:, version:)` to use v1 or v2 per endpoint
+- **Custom chain registration** - `config.register_chain(name:, chain_id:, standard:)` for custom EVM chains
+- **Custom token registration** - `config.register_token(chain:, symbol:, address:, decimals:, name:)` for custom tokens
+- **CAIP-2 support** - `to_caip2()` and `from_caip2()` for network identifier conversion
+- **Per-chain fee payer** - Configure via `X402_SOLANA_DEVNET_FEE_PAYER`, `X402_SOLANA_FEE_PAYER` env vars
+- **Dynamic HTML paywall** - Detects decimals and asset symbol from chain configuration
+
+### Changed
+- Default protocol version is now v2
+- v2 responses use CAIP-2 network format (e.g., `eip155:84532` instead of `base-sepolia`)
+- v2 402 responses include full PaymentRequired in both header and body for debugging
+- v1 requirements include `resource`, `description`, `mimeType` in each accept; v2 places these at top level
+
+## [0.2.1] - Previous Release
+
+- Initial stable release with v1 protocol support
+- Custom chain and token registration
+- Optimistic and non-optimistic settlement modes

data/README.md

@@ -1,10 +1,14 @@
 # x402-rails
 
+## Now supporting x402 v2!
+
+> **⚠️ Note:** This gem now defaults to x402 protocol **v2**. If you need v1 compatibility, set `config.version = 1` in your initializer. See [Protocol Versions](#protocol-versions) for details on the differences.
+
 ![Coverage](./coverage/coverage.svg)
 
 Accept instant blockchain micropayments in your Rails applications using the [x402 payment protocol](https://www.x402.org/).
 
-Supports Base, avalanche, and other blockchain networks.
+Supports 18 networks including Base, Polygon, Avalanche, Sei, Solana, and more.
 
 ## Features
 
@@ -14,7 +18,7 @@ Supports Base, avalanche, and other blockchain networks.
 - **$0.001 minimum** payment amounts
 - **Optimistic & non-optimistic** settlement modes
 - **Automatic settlement** after successful responses
-- **Browser paywall** and API support
+- **API paywall** with 402 payment-required responses
 - **Rails 7.0+** compatible
 
 ## Example Video
@@ -59,6 +63,7 @@ Use `x402_paywall` in any controller action:
 class ApiController < ApplicationController
   def weather
     x402_paywall(amount: 0.001)  # $0.001 in USD
+    return if performed?
 
     render json: {
       temperature: 72,
@@ -79,6 +84,7 @@ Call `x402_paywall` in any action:
 ```ruby
 def show
   x402_paywall(amount: 0.01)
+  return if performed?
   # Action continues after payment verified
   render json: @data
 end
@@ -101,6 +107,7 @@ class PremiumController < ApplicationController
 
   def require_payment
     x402_paywall(amount: 0.001, chain: "base")
+    return if performed?
   end
 end
 ```
@@ -112,11 +119,13 @@ Different prices for different actions:
 ```ruby
 def basic_data
   x402_paywall(amount: 0.001)
+  return if performed?
   render json: basic_info
 end
 
 def premium_data
   x402_paywall(amount: 0.01)
+  return if performed?
   render json: premium_info
 end
 ```
@@ -136,7 +145,10 @@ X402.configure do |config|
   config.facilitator = ENV.fetch("X402_FACILITATOR_URL", "https://x402.org/facilitator")
 
   # Blockchain network (default: "base-sepolia")
-  # Options: "base-sepolia", "base", "avalanche-fuji", "avalanche"
+  # Built-in: base, base-sepolia, polygon, polygon-amoy, avalanche, avalanche-fuji,
+  #           sei, sei-testnet, iotex, peaq, xlayer, xlayer-testnet,
+  #           skale-base, skale-base-sepolia, kiteai, kiteai-testnet,
+  #           solana, solana-devnet
   config.chain = ENV.fetch("X402_CHAIN", "base-sepolia")
 
   # Payment token (default: "USDC")
@@ -156,51 +168,184 @@ end
 | ---------------- | -------- | -------------------------------- | --------------------------------------------------------------------------------- |
 | `wallet_address` | **Yes**  | -                                | Your Ethereum wallet address where payments will be received                      |
 | `facilitator`    | No       | `"https://x402.org/facilitator"` | Facilitator service URL for payment verification and settlement                   |
-| `chain`          | No       | `"base-sepolia"`                 | Blockchain network to use (`base-sepolia`, `base`, `avalanche-fuji`, `avalanche`) |
+| `chain`          | No       | `"base-sepolia"`                 | Blockchain network (see built-in list above) |
 | `currency`       | No       | `"USDC"`                         | Payment token symbol (currently only USDC supported)                              |
 | `optimistic`     | No       | `true`                           | Settlement mode (see Optimistic vs Non-Optimistic Mode below)                     |
-| `rpc_urls`       | No       | `{}`                             | Custom RPC endpoint URLs per chain (see Custom RPC URLs below)                    |
+| `version`        | No       | `2`                              | Protocol version (1 or 2). See Protocol Versions section                          |
 
-### Custom RPC URLs
+### Custom Chains and Tokens
 
-By default, x402-rails uses public QuickNode RPC endpoints for each supported chain. For production use or higher reliability, you can configure custom RPC URLs from providers like [QuickNode](https://www.quicknode.com/).
+You can register custom EVM chains and tokens beyond the built-in options.
 
-**Configuration Priority** (highest to lowest):
+#### Register a Custom Chain
 
-1. Programmatic configuration via `config.rpc_urls`
-2. Per-chain environment variables
-3. Built-in default RPC URLs
+Add support for any EVM-compatible chain beyond the 18 built-in networks:
 
-#### Method 1: Programmatic Configuration
+```ruby
+X402.configure do |config|
+  config.wallet_address = ENV['X402_WALLET_ADDRESS']
 
-Configure RPC URLs in your initializer:
+  # Register Arbitrum (not built-in)
+  config.register_chain(
+    name: "arbitrum",
+    chain_id: 42161,
+    standard: "eip155"
+  )
+
+  # Register the token for that chain
+  config.register_token(
+    chain: "arbitrum",
+    symbol: "USDC",
+    address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+    decimals: 6,
+    name: "USD Coin",
+    version: "2"
+  )
+
+  config.chain = "arbitrum"
+  config.currency = "USDC"
+end
+```
+
+#### Register a Custom Token on a Built-in Chain
+
+> **⚠️ Note:** The Facilitator used **must support** the specified chain and token to ensure proper functionality.
+
+Accept different tokens on existing chains:
 
 ```ruby
 X402.configure do |config|
   config.wallet_address = ENV['X402_WALLET_ADDRESS']
 
-  # Custom RPC URLs per chain
-  config.rpc_urls["base"] = "https://your-base-rpc.quiknode.pro/your-key"
-  config.rpc_urls["base-sepolia"] = "https://your-sepolia-rpc.quiknode.pro/your-key"
-  config.rpc_urls["avalanche"] = "https://your-avalanche-rpc.quiknode.pro/your-key"
+  # Accept WETH on Base instead of USDC
+  config.register_token(
+    chain: "base",
+    symbol: "WETH",
+    address: "0x4200000000000000000000000000000000000006",
+    decimals: 18,
+    name: "Wrapped Ether",
+    version: "1"
+  )
+
+  config.chain = "base"
+  config.currency = "WETH"
 end
 ```
 
-#### Method 2: Environment Variables
+#### Token Registration Parameters
 
-Set per-chain environment variables:
+| Parameter  | Required | Description                                    |
+| ---------- | -------- | ---------------------------------------------- |
+| `chain`    | Yes      | Chain name (built-in or custom registered)     |
+| `symbol`   | Yes      | Token symbol (e.g., "USDC", "WETH")            |
+| `address`  | Yes      | Token contract address                         |
+| `decimals` | Yes      | Token decimals (e.g., 6 for USDC, 18 for WETH) |
+| `name`     | Yes      | Token name for EIP-712 domain                  |
+| `version`  | No       | EIP-712 version (default: "1")                 |
 
-```bash
-# Per-chain RPC URL overrides
-X402_BASE_RPC_URL=https://your-base-rpc.quiknode.pro/your-key
-X402_BASE_SEPOLIA_RPC_URL=https://your-sepolia-rpc.quiknode.pro/your-key
-X402_AVALANCHE_RPC_URL=https://your-avalanche-rpc.quiknode.pro/your-key
-X402_AVALANCHE_FUJI_RPC_URL=https://your-fuji-rpc.quiknode.pro/your-key
+**Note:** Custom chains and tokens are only supported for EVM (eip155) networks. Solana chains use a different implementation.
+
+### Accept Multiple Payment Options
+
+Allow clients to pay on any of several supported chains by using `config.accept()`:
+
+```ruby
+X402.configure do |config|
+  config.wallet_address = ENV['X402_WALLET_ADDRESS']
+
+  # Register a custom chain not included in the built-in list
+  config.register_chain(name: "arbitrum", chain_id: 42161, standard: "eip155")
+  config.register_token(
+    chain: "arbitrum",
+    symbol: "USDC",
+    address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+    decimals: 6,
+    name: "USD Coin",
+    version: "2"
+  )
+
+  # Accept payments on multiple chains (built-in + custom)
+  config.accept(chain: "base-sepolia", currency: "USDC")
+  config.accept(chain: "polygon-amoy", currency: "USDC")
+  config.accept(chain: "arbitrum", currency: "USDC")
+end
+```
+
+When `config.accept()` is used, the 402 response will include all accepted payment options:
+
+```json
+{
+  "accepts": [
+    { "network": "eip155:84532", "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", ... },
+    { "network": "eip155:80002", "asset": "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582", ... }
+  ]
+}
 ```
 
-#### Method 3: Default RPC URLs
+Clients can then choose which chain to pay on based on their preferences or available funds.
+
+**Per-accept wallet addresses:** You can specify different recipient addresses per chain:
+
+```ruby
+config.accept(chain: "base-sepolia", currency: "USDC", wallet_address: "0xWallet1")
+config.accept(chain: "polygon-amoy", currency: "USDC", wallet_address: "0xWallet2")
+```
+
+**Fallback behavior:** If no `config.accept()` calls are made, the default `config.chain` and `config.currency` are used.
+
+## Protocol Versions
 
-If no custom RPC URL is configured, it will default to the public QuickNode RPC urls.
+x402-rails supports both v1 and v2 of the x402 protocol. **v2 is the default**.
+
+### Key Differences
+
+| Feature         | v1 (Legacy)                   | v2 (Default)                     |
+| --------------- | ----------------------------- | -------------------------------- |
+| Network format  | Simple names (`base-sepolia`) | CAIP-2 (`eip155:84532`)          |
+| Payment header  | `X-PAYMENT`                   | `PAYMENT-SIGNATURE`              |
+| Response header | `X-PAYMENT-RESPONSE`          | `PAYMENT-RESPONSE`               |
+| Requirements    | Body only                     | `PAYMENT-REQUIRED` header + body |
+| Amount field    | `maxAmountRequired`           | `amount`                         |
+
+### v2 (Default)
+
+```ruby
+X402.configure do |config|
+  config.wallet_address = ENV['X402_WALLET_ADDRESS']
+  config.version = 2  # Default, can be omitted
+end
+```
+
+v2 uses CAIP-2 network identifiers (`eip155:84532`) and the `PAYMENT-SIGNATURE` header. Payment requirements are sent in both the `PAYMENT-REQUIRED` header (base64-encoded) and the response body (JSON).
+
+### v1 (Legacy)
+
+```ruby
+X402.configure do |config|
+  config.wallet_address = ENV['X402_WALLET_ADDRESS']
+  config.version = 1
+end
+```
+
+v1 uses simple network names (`base-sepolia`) and the `X-PAYMENT` header. Payment requirements are sent only in the response body.
+
+### Per-Endpoint Version
+
+Override the version for specific endpoints:
+
+```ruby
+def premium_v2
+  x402_paywall(amount: 0.001, version: 2)
+  return if performed?
+  render json: { data: "v2 endpoint" }
+end
+
+def legacy_v1
+  x402_paywall(amount: 0.001, version: 1)
+  return if performed?
+  render json: { data: "v1 endpoint" }
+end
+```
 
 ## Environment Variables
 
@@ -216,13 +361,25 @@ X402_CHAIN=base-sepolia
 X402_CURRENCY=USDC
 X402_OPTIMISTIC=true  # "true" or "false"
 
-# Custom RPC URLs (optional, per-chain overrides)
-X402_BASE_RPC_URL=https://your-base-rpc.quiknode.pro/your-key
-X402_BASE_SEPOLIA_RPC_URL=https://your-base-speoliarpc.quiknode.pro/your-key
-X402_AVALANCHE_RPC_URL=https://your-avalanche.quiknode.pro/your-key
-X402_AVALANCHE_FUJI_RPC_URL=https://your-fuji-rpc.quiknode.pro/your-key
+# Solana fee payer overrides (required when using a non-default facilitator)
+# The default fee payer is for the Coinbase facilitator (x402.org).
+# Each facilitator manages its own fee payer — check your facilitator's /supported endpoint.
+X402_FEE_PAYER=                     # Global override for all Solana chains
+X402_SOLANA_FEE_PAYER=              # Solana mainnet override
+X402_SOLANA_DEVNET_FEE_PAYER=       # Solana devnet override
+
+# Example: PayAI facilitator (https://facilitator.payai.network)
+# X402_FACILITATOR_URL=https://facilitator.payai.network
+# X402_SOLANA_FEE_PAYER=2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4
+# X402_SOLANA_DEVNET_FEE_PAYER=2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4
 ```
 
+Fee payer lookup priority:
+1. `config.fee_payer` (programmatic, global)
+2. Per-chain ENV variable (e.g., `X402_SOLANA_DEVNET_FEE_PAYER`)
+3. `X402_FEE_PAYER` (ENV, global)
+4. Built-in default from chain config
+
 ## Examples
 
 ### Weather API
@@ -231,11 +388,13 @@ X402_AVALANCHE_FUJI_RPC_URL=https://your-fuji-rpc.quiknode.pro/your-key
 class WeatherController < ApplicationController
   def current
     x402_paywall(amount: 0.001)
+    return if performed?
     render json: { temp: 72, condition: "sunny" }
   end
 
   def forecast
     x402_paywall(amount: 0.01)
+    return if performed?
     render json: { forecast: [...] }
   end
 end
@@ -282,6 +441,8 @@ The gem raises these errors:
 - [x402 Protocol Docs](https://docs.cdp.coinbase.com/x402)
 - [GitHub Repository](https://github.com/coinbase/x402)
 - [Facilitator API](https://x402.org/facilitator)
+- [Step-by-Step Rails Integration Guide](https://www.quicknode.com/guides/infrastructure/x402-payment-integration-with-rails)
+
 
 ## License