Merge branch 'main' of https://github.com/nuwa-protocol/x402-exec

Author: Mine77

CLAUDE.md

@@ -105,10 +105,10 @@ pnpm -C web/frontend check  # Web frontend uses Biome
 cd contracts
 ./deploy-contract.sh [NETWORK] [OPTIONS]
 
-# Examples:
-./deploy-contract.sh base-sepolia --all --verify    # Deploy all contracts
-./deploy-contract.sh base --settlement --verify     # SettlementRouter only
-./deploy-contract.sh xlayer --hooks --verify        # Built-in hooks
+# Examples (using CAIP-2 format):
+./deploy-contract.sh eip155:84532 --all --verify    # Deploy all contracts (Base Sepolia)
+./deploy-contract.sh eip155:8453 --settlement --verify     # SettlementRouter only (Base Mainnet)
+./deploy-contract.sh eip155:196 --hooks --verify        # Built-in hooks (X-Layer Mainnet)
 ```
 
 ## Key Architecture Concepts
@@ -162,7 +162,15 @@ Hooks receive **net value** (after facilitator fee) and implement arbitrary busi
 
 ### Dual-Stack Protocol Support
 
-The codebase supports both x402 v1 (human-readable network names like `base-sepolia`) and v2 (CAIP-2 identifiers like `eip155:84532`). Detection is automatic based on request format. Enable v2 with `FACILITATOR_ENABLE_V2=true`.
+The codebase supports both x402 v1 (human-readable network names like `base-sepolia`) and v2 (CAIP-2 identifiers like `eip155:84532`). Detection is automatic based on request format. CAIP-2 format is recommended for all new implementations.
+
+**CAIP-2 format examples:**
+- Base Sepolia: `eip155:84532` (chain ID 84532)
+- Base Mainnet: `eip155:8453` (chain ID 8453)
+- X-Layer Testnet: `eip155:1952` (chain ID 1952)
+- X-Layer Mainnet: `eip155:196` (chain ID 196)
+
+Enable v2 with `FACILITATOR_ENABLE_V2=true`.
 
 ## Important Development Rules
 

README.md

@@ -154,9 +154,9 @@ cd contracts
 ./deploy-contract.sh [NETWORK] [OPTIONS]  # Configure .env first
 
 # Examples:
-./deploy-contract.sh base-sepolia --all --verify    # Deploy everything on testnet
-./deploy-contract.sh base --settlement --verify     # Deploy SettlementRouter on mainnet
-./deploy-contract.sh xlayer --hooks --verify        # Deploy built-in hooks
+./deploy-contract.sh eip155:84532 --all --verify    # Deploy everything on testnet (Base Sepolia)
+./deploy-contract.sh eip155:8453 --settlement --verify     # Deploy SettlementRouter on mainnet (Base)
+./deploy-contract.sh eip155:196 --hooks --verify        # Deploy built-in hooks (X-Layer)
 ```
 
 ## 💡 Usage Examples

README_CN.md

@@ -105,28 +105,30 @@ x402-exec/
 
 ### 第三方开发者集成
 
-如果你想在自己的项目中使用 x402-exec，我们提供了一个增强版的 x402 包。详细说明请查看 [第三方集成指南](./docs/third-party-integration.md)。
+如果你想在自己的项目中使用 x402-exec，请使用官方 x402 v2 包。详细说明请查看 [第三方集成指南](./docs/third-party-integration.md)。
 
 **快速安装：**
 
 ```bash
-# 使用 npm alias（推荐）
-npm install x402@npm:@x402x/x402@0.6.6-patch.7
+# 使用官方 x402 v2 包
+npm install @x402/core @x402/evm @x402x/extensions
 
 # 或使用 pnpm
-pnpm add x402@npm:@x402x/x402@0.6.6-patch.7
+pnpm add @x402/core @x402/evm @x402x/extensions
 ```
 
 在 `package.json` 中：
 ```json
 {
   "dependencies": {
-    "x402": "npm:@x402x/x402@0.6.6-patch.7"
+    "@x402/core": "latest",
+    "@x402/evm": "latest",
+    "@x402x/extensions": "latest"
   }
 }
 ```
 
-> 💡 **为什么使用修改版？** 我们对 x402 添加了 `paymentRequirements` 字段支持（[PR #578](https://github.com/coinbase/x402/pull/578)），但该改进被官方推迟到 v2。`@x402x/x402` 让你现在就能使用这些功能，且完全向后兼容。
+> ⚠️ **注意**：x402 v1 已废弃。请使用官方 x402 v2 包配合 `@x402x/extensions` 进行集成。
 
 ### 开发者快速开始
 
@@ -156,10 +158,10 @@ forge test
 cd contracts
 ./deploy-contract.sh [网络] [选项]  # 先配置 .env 文件
 
-# 示例：
-./deploy-contract.sh base-sepolia --all --verify    # 在测试网部署所有内容
-./deploy-contract.sh base --settlement --verify     # 在主网部署 SettlementRouter
-./deploy-contract.sh xlayer --hooks --verify        # 部署内置 hooks
+# 示例（使用 CAIP-2 网络标识符）：
+./deploy-contract.sh eip155:84532 --all --verify    # 在测试网部署所有内容 (Base Sepolia)
+./deploy-contract.sh eip155:8453 --settlement --verify     # 在主网部署 SettlementRouter (Base)
+./deploy-contract.sh eip155:196 --hooks --verify        # 部署内置 hooks (X-Layer)
 ```
 
 ## 💡 使用示例

contracts/DEPLOYMENT.md

@@ -6,12 +6,14 @@ This guide explains how to deploy x402-exec contracts to different networks, wit
 
 ## 🌐 Supported Networks
 
-| Network | Chain ID | RPC Default | Block Explorer |
-|---------|----------|-------------|----------------|
-| Base Sepolia | 84532 | https://sepolia.base.org | https://sepolia.basescan.org |
-| Base Mainnet | 8453 | https://mainnet.base.org | https://basescan.org |
-| X-Layer Testnet | 1952 | https://testrpc.xlayer.tech | https://www.oklink.com/xlayer-test |
-| X-Layer Mainnet | 196 | https://rpc.xlayer.tech | https://www.oklink.com/xlayer |
+| Network | CAIP-2 Identifier | Chain ID | RPC Default | Block Explorer |
+|---------|------------------|----------|-------------|----------------|
+| Base Sepolia | `eip155:84532` | 84532 | https://sepolia.base.org | https://sepolia.basescan.org |
+| Base Mainnet | `eip155:8453` | 8453 | https://mainnet.base.org | https://basescan.org |
+| X-Layer Testnet | `eip155:1952` | 1952 | https://testrpc.xlayer.tech | https://www.oklink.com/xlayer-test |
+| X-Layer Mainnet | `eip155:196` | 196 | https://rpc.xlayer.tech | https://www.oklink.com/xlayer |
+
+**Note:** CAIP-2 identifiers use the format `eip155:<chainId>` and are the recommended format for network identification in x402 v2.
 
 ## 🚀 Quick Start: Deploy to X-Layer Testnet
 
@@ -65,9 +67,11 @@ Deploy both SettlementRouter and all showcase scenarios:
 
 ```bash
 cd contracts
-./deploy-contract.sh xlayer-testnet --all
+./deploy-contract.sh eip155:1952 --all
 ```
 
+**Note:** `eip155:1952` is the CAIP-2 identifier for X-Layer Testnet (chain ID 1952).
+
 This will:
 1. ✅ Deploy `SettlementRouter` (built-in TransferHook available)
 2. ✅ Deploy `NFTMintHook` + `RandomNFT`
@@ -87,6 +91,7 @@ X_LAYER_TESTNET_SETTLEMENT_ROUTER_ADDRESS=0x...
 **Showcase server `.env`** (`examples/showcase/server/.env`):
 ```bash
 # Copy from env.example first: cp env.example .env
+# Environment variables use CAIP-2 format for network identification
 X_LAYER_TESTNET_SETTLEMENT_ROUTER_ADDRESS=0x...
 X_LAYER_TESTNET_REVENUE_SPLIT_HOOK_ADDRESS=0x...
 X_LAYER_TESTNET_NFT_MINT_HOOK_ADDRESS=0x...
@@ -111,7 +116,7 @@ If you have `OKLINK_API_KEY` set and used `--verify` flag:
 ### Deploy Only SettlementRouter
 
 ```bash
-./deploy-contract.sh xlayer-testnet --settlement
+./deploy-contract.sh eip155:1952 --settlement
 ```
 
 After deployment, save the address:
@@ -127,14 +132,14 @@ Built-in Hooks are protocol-level Hooks deployed once per network for universal
 Requires `[NETWORK]_SETTLEMENT_ROUTER_ADDRESS` to be set first:
 
 ```bash
-# Deploy all built-in hooks to X-Layer Testnet
-./deploy-builtin-hooks.sh xlayer-testnet --all
+# Deploy all built-in hooks to X-Layer Testnet (CAIP-2: eip155:1952)
+./deploy-builtin-hooks.sh eip155:1952 --all
 
 # Deploy specific hooks
-./deploy-builtin-hooks.sh base-sepolia --transfer  # TransferHook only
+./deploy-builtin-hooks.sh eip155:84532 --transfer  # TransferHook only (Base Sepolia)
 
 # Deploy with verification
-./deploy-builtin-hooks.sh xlayer-testnet --all --verify
+./deploy-builtin-hooks.sh eip155:1952 --all --verify
 ```
 
 **Current Built-in Hooks:**
@@ -148,22 +153,22 @@ Requires `SETTLEMENT_ROUTER_ADDRESS` to be set first:
 
 ```bash
 # Make sure X_LAYER_TESTNET_SETTLEMENT_ROUTER_ADDRESS is set in .env
-./deploy-contract.sh xlayer-testnet --showcase
+./deploy-contract.sh eip155:1952 --showcase
 ```
 
 ### Deploy with Verification
 
 ```bash
 # Requires OKLINK_API_KEY in .env
-./deploy-contract.sh xlayer-testnet --all --verify
+./deploy-contract.sh eip155:1952 --all --verify
 ```
 
 ### Non-Interactive Deployment
 
 Skip confirmation prompts:
 
 ```bash
-./deploy-contract.sh xlayer-testnet --all --yes
+./deploy-contract.sh eip155:1952 --all --yes
 ```
 
 ## 🔧 Legacy Deployment Scripts
@@ -184,17 +189,17 @@ Skip confirmation prompts:
 
 ### Migration Guide
 
-**Before (Base Sepolia):**
+**Before (Base Sepolia - legacy):**
 ```bash
 export RPC_URL=https://sepolia.base.org
 ./deploy.sh
 ./deploy-showcase.sh --all
 ```
 
-**After (Multi-Network):**
+**After (Multi-Network with CAIP-2):**
 ```bash
-# Just specify the network!
-./deploy-contract.sh base-sepolia --all
+# Just specify the network using CAIP-2 format!
+./deploy-contract.sh eip155:84532 --all  # Base Sepolia
 ```
 
 ## 🌐 Deploy to Other Networks
@@ -206,8 +211,8 @@ export RPC_URL=https://sepolia.base.org
 BASE_RPC_URL=https://mainnet.base.org
 BASESCAN_API_KEY=your_api_key
 
-# Deploy
-./deploy-contract.sh base --all --verify
+# Deploy (using CAIP-2 format: eip155:8453)
+./deploy-contract.sh eip155:8453 --all --verify
 ```
 
 ### X-Layer Mainnet
@@ -217,8 +222,8 @@ BASESCAN_API_KEY=your_api_key
 X_LAYER_RPC_URL=https://rpc.xlayer.tech
 OKLINK_API_KEY=your_api_key
 
-# Deploy
-./deploy-contract.sh xlayer --all --verify
+# Deploy (using CAIP-2 format: eip155:196)
+./deploy-contract.sh eip155:196 --all --verify
 ```
 
 ## 🛠️ Troubleshooting
@@ -263,7 +268,7 @@ Cannot deploy showcase: SETTLEMENT_ROUTER_ADDRESS not set
 ```
 
 **Solution:** Either:
-1. Deploy SettlementRouter first: `./deploy-contract.sh xlayer-testnet --settlement`
+1. Deploy SettlementRouter first: `./deploy-contract.sh eip155:1952 --settlement`
 2. Or use `--all` to deploy everything at once
 
 ## 📝 Deployment Checklist
@@ -352,8 +357,8 @@ Always verify contracts on mainnet deployments:
 ### How to Redeploy
 
 ```bash
-# Redeploy everything
-./deploy-contract.sh xlayer-testnet --all
+# Redeploy everything (using CAIP-2 format)
+./deploy-contract.sh eip155:1952 --all
 
 ```
 

contracts/docs/builtin_hooks.md

@@ -70,7 +70,7 @@ function execute(
 ```json
 {
   "scheme": "exact",
-  "network": "base-sepolia",
+  "network": "eip155:84532",
   "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
   "maxAmountRequired": "1010000",
   "payTo": "0xSettlementRouter...",
@@ -113,12 +113,12 @@ The additional ~8k gas provides:
 
 #### Deployment Addresses
 
-| Network | Address | Status |
-|---------|---------|--------|
-| Base Sepolia (Testnet) | [`0x6b486aF5A08D27153d0374BE56A1cB1676c460a8`](https://sepolia.basescan.org/address/0x6b486aF5A08D27153d0374BE56A1cB1676c460a8) | ✅ Active |
-| X-Layer Testnet | [`0x3D07D4E03a2aDa2EC49D6937ab1B40a83F3946AB`](https://www.oklink.com/xlayer-test/address/0x3D07D4E03a2aDa2EC49D6937ab1B40a83F3946AB) | ✅ Active |
-| Base Mainnet | TBD | 🚧 Pending Audit |
-| Ethereum Mainnet | TBD | 🚧 Pending Audit |
+| Network | CAIP-2 Identifier | Address | Status |
+|---------|------------------|---------|--------|
+| Base Sepolia (Testnet) | `eip155:84532` | [`0x6b486aF5A08D27153d0374BE56A1cB1676c460a8`](https://sepolia.basescan.org/address/0x6b486aF5A08D27153d0374BE56A1cB1676c460a8) | ✅ Active |
+| X-Layer Testnet | `eip155:1952` | [`0x3D07D4E03a2aDa2EC49D6937ab1B40a83F3946AB`](https://www.oklink.com/xlayer-test/address/0x3D07D4E03a2aDa2EC49D6937ab1B40a83F3946AB) | ✅ Active |
+| Base Mainnet | `eip155:8453` | TBD | 🚧 Pending Audit |
+| Ethereum Mainnet | `eip155:1` | TBD | 🚧 Pending Audit |
 
 ## Integration Guide
 

contracts/docs/facilitator_guide.md

@@ -506,31 +506,46 @@ function handleSettlement(request):
 ### Environment Variables
 
 ```bash
-# Standard Facilitator configuration
-RPC_URL_BASE_SEPOLIA=https://sepolia.base.org
-RPC_URL_BASE=https://mainnet.base.org
+# Standard Facilitator configuration (using CAIP-2 format for network identifiers)
+# CAIP-2 format: eip155:<chainId>
+RPC_URL_EIP155_84532=https://sepolia.base.org  # Base Sepolia (chain ID 84532)
+RPC_URL_EIP155_8453=https://mainnet.base.org    # Base Mainnet (chain ID 8453)
 PRIVATE_KEY=0x...
 
-# SettlementRouter addresses (per network)
-SETTLEMENT_ROUTER_BASE_SEPOLIA=0x...
-SETTLEMENT_ROUTER_BASE=0x...
-SETTLEMENT_ROUTER_ETHEREUM=0x...
+# SettlementRouter addresses (per network, using CAIP-2 format)
+SETTLEMENT_ROUTER_EIP155_84532=0x...  # Base Sepolia
+SETTLEMENT_ROUTER_EIP155_8453=0x...   # Base Mainnet
+SETTLEMENT_ROUTER_EIP155_1=0x...      # Ethereum Mainnet (chain ID 1)
 ```
 
 ### Network Configuration
 
 ```json
 {
   "networks": {
-    "base": {
+    "eip155:8453": {
       "rpcUrl": "https://mainnet.base.org",
       "settlementRouter": "0x...",
-      "chainId": 8453
+      "chainId": 8453,
+      "name": "Base Mainnet"
     },
-    "base-sepolia": {
-      "rpcUrl": "https://sepolia.base.org", 
+    "eip155:84532": {
+      "rpcUrl": "https://sepolia.base.org",
       "settlementRouter": "0x...",
-      "chainId": 84532
+      "chainId": 84532,
+      "name": "Base Sepolia"
+    },
+    "eip155:196": {
+      "rpcUrl": "https://rpc.xlayer.tech",
+      "settlementRouter": "0x...",
+      "chainId": 196,
+      "name": "X-Layer Mainnet"
+    },
+    "eip155:1952": {
+      "rpcUrl": "https://testrpc.xlayer.tech",
+      "settlementRouter": "0x...",
+      "chainId": 1952,
+      "name": "X-Layer Testnet"
     }
   }
 }

docs/development.md

@@ -235,10 +235,10 @@ pnpm run build
 cd contracts
 ./deploy-contract.sh [NETWORK] [OPTIONS]
 
-# Examples:
-./deploy-contract.sh xlayer-testnet --all         # Deploy everything
-./deploy-contract.sh base-sepolia --settlement    # Deploy SettlementRouter only
-./deploy-contract.sh xlayer --hooks --verify      # Deploy hooks with verification
+# Examples (using CAIP-2 format):
+./deploy-contract.sh eip155:1952 --all         # Deploy everything (X-Layer Testnet)
+./deploy-contract.sh eip155:84532 --settlement  # Deploy SettlementRouter only (Base Sepolia)
+./deploy-contract.sh eip155:196 --hooks --verify    # Deploy hooks with verification (X-Layer)
 ```
 
 ### Cloud Deployment

examples/showcase/README.md

@@ -91,11 +91,12 @@ cp .env.example .env
 
 ```bash
 cd ../../contracts
-./deploy-contract.sh xlayer-testnet --all
+./deploy-contract.sh eip155:1952 --all
 
-# Or deploy to other networks:
-# ./deploy-contract.sh base-sepolia --all --verify
-# ./deploy-contract.sh xlayer --settlement
+# Or deploy to other networks (using CAIP-2 format):
+# ./deploy-contract.sh eip155:84532 --all --verify  # Base Sepolia
+# ./deploy-contract.sh eip155:196 --settlement       # X-Layer Mainnet
+# ./deploy-contract.sh eip155:8453 --settlement       # Base Mainnet
 ```
 
 After deployment, copy the output contract addresses and update `server/.env`:
@@ -360,12 +361,12 @@ These contracts need to be deployed for NFT Mint and Reward Points scenarios:
 For mainnet deployment, use the following commands and update the `client/.env` file with the deployed addresses:
 
 ```bash
-# Deploy to Base Mainnet
+# Deploy to Base Mainnet (CAIP-2: eip155:8453)
 cd contracts
-./deploy-contract.sh base --showcase --verify
+./deploy-contract.sh eip155:8453 --showcase --verify
 
-# Deploy to X Layer Mainnet
-./deploy-contract.sh xlayer --showcase --verify
+# Deploy to X Layer Mainnet (CAIP-2: eip155:196)
+./deploy-contract.sh eip155:196 --showcase --verify
 ```
 
 After deployment, update your `examples/showcase/client/.env`: