Skip to content

README_CN.md

Latest commit

 

History

History
279 lines (202 loc) · 11.5 KB

README_CN.md

File metadata and controls

279 lines (202 loc) · 11.5 KB
Raw

x402-exec

License Solidity Foundry

English | 简体中文

x402x (x402-exec 的简称) 是一个为 x402 协议 设计的可编程结算框架，在原子交易中结合支付验证、基于 Hook 的业务逻辑和 Facilitator 激励。

✨ 特性

x402x 的独特之处

可编程结算与真正的原子性 - 不仅仅是支付路由，而是一个完整的结算执行框架，在单个原子交易中组合支付验证、业务逻辑执行和 Facilitator 激励。

🎯 核心能力

🔌 通过 Hook 实现无限扩展性

  • 多方支付的收入分账
  • 原子化的 NFT 铸造支付
  • 积分奖励分发
  • 任何你能想象到的自定义业务逻辑

💰 原生 Facilitator 费用支持

  • 内置 Facilitator 费用机制，实现真正的无需许可 Facilitator
  • 解决 x402 协议中的关键缺失功能
  • 随时可提取累积费用
  • 通过事件透明追踪费用

⚡ 最小化集成开销

  • PaymentRequirements 中仅需 3 个额外字段
  • 单次交易完成所有操作 - 无需 Multicall3 复杂性
  • 客户端改动极小（仅需调整 nonce 计算）
  • 向后兼容现有 x402 基础设施

🔄 原生幂等性与可观测性

  • 通过 EIP-3009 nonce 内置重放保护
  • 完整的事件日志用于对账和监控
  • 基于上下文的结算追踪

💡 内置示例

✅ 收入分账 - 自动多方支付分配
✅ NFT 商务 - 原子化铸造支付与收入分账
✅ 会员计划 - 实时积分奖励分发

🔐 安全设计

多层保护

  • 密码学承诺验证防止参数篡改
  • 不持币原则 - Router 余额始终为零
  • 基于 OpenZeppelin 的重入保护
  • CEI（检查-效果-交互）模式强制执行
  • 35+ 测试用例覆盖边界情况

🏗️ 架构

Client (EIP-3009 Signature)
         ↓
    Facilitator
         ↓
   SettlementRouter ──→ Hook ──→ Recipients
         │                      (分账/发货)
         └→ Events (可观测性)

Core Components

  1. SettlementRouter：核心结算合约

    • 消费 EIP-3009 授权
    • 调用 Hook 执行业务逻辑
    • 确保原子性和幂等性

  2. TransferHook（内置）：默认转账 Hook

    • 简单转账与 Facilitator 费用支持
    • 替代直接 ERC-3009 转账
    • 最小 Gas 开销（~8k gas）
    • 通用部署（每个网络一个实例）

  3. ISettlementHook：Hook 接口

    • 所有业务逻辑通过 Hook 实现
    • 完全可扩展，支持任意场景

📦 项目结构

x402-exec/
├── contracts/              # Solidity 智能合约
│   ├── src/
│   │   ├── SettlementRouter.sol    # 核心结算合约
│   │   └── interfaces/             # 合约接口
│   ├── examples/                   # Hook 示例
│   ├── script/                     # 部署脚本
│   ├── test/                       # 合约测试
│   └── docs/                       # 合约文档
├── examples/
│   ├── facilitator/                # 支持 SettlementRouter 的 Facilitator
│   └── showcase/                   # 全栈演示应用
└── docs/                           # 项目文档

🚀 快速开始

第三方开发者集成

如果你想在自己的项目中使用 x402-exec，请使用官方 x402 v2 包。详细说明请查看 第三方集成指南。

快速安装：

# 使用官方 x402 v2 包
npm install @x402/core @x402/evm @x402x/extensions

# 或使用 pnpm
pnpm add @x402/core @x402/evm @x402x/extensions

在 package.json 中：

{
  "dependencies": {
    "@x402/core": "latest",
    "@x402/evm": "latest",
    "@x402x/extensions": "latest"
  }
}

⚠️ 注意：x402 v1 已废弃。请使用官方 x402 v2 包配合 @x402x/extensions 进行集成。

开发者快速开始

前置要求

# 安装 Foundry
curl -L https://foundry.paradigm.xyz | bash
foundryup

# 克隆项目
git clone https://github.com/nuwa-protocol/x402-exec.git
cd x402-exec

构建和测试

cd contracts
forge build
forge test

部署合约

cd contracts
./deploy-contract.sh [网络] [选项]  # 先配置 .env 文件

# 示例（使用 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)

💡 使用示例

Facilitator 集成

该 Facilitator 自动支持两种模式：

  • 标准 x402 支付：直接 ERC-3009 转账
  • SettlementRouter 支付：扩展结算与 Hook 执行

查看 Facilitator README 获取完整设置指南和运行说明，或查看 Facilitator 开发指南 了解如何扩展你自己的 Facilitator。

在线演示

查看全栈演示应用：

  • 位置：examples/showcase/
  • 场景：收入分账、NFT 铸造、积分奖励
  • 技术栈：React + TypeScript + Viem

Hook 示例

内置 Hooks

协议级 Hooks，每个网络部署一次，供所有项目使用：

  • TransferHook：简单转账与 Facilitator 费用支持 (文档)
    • 直接替代 ERC-3009 转账
    • 最小 Gas 开销
    • 无需 hookData

示例 Hooks

教学模板和参考实现，位于 contracts/examples/：

  • TransferHook：简单转账和收入分成（内置，无需单独合约）
  • NFTMintHook：原子化 NFT 铸造与支付 (源码)
  • RewardHook：会员积分分发 (源码)

SettlementRouter 合约

网络 SettlementRouter 状态
Base Sepolia (测试网) 0x817e4f0ee2fbdaac426f1178e149f7dc98873ecb ✅ 活跃
X-Layer 测试网 0xba9980fb08771e2fd10c17450f52d39bcb9ed576 ✅ 活跃
SKALE Base Sepolia 0x1Ae0E196dC18355aF3a19985faf67354213F833D ✅ 活跃
BSC 测试网 0x1Ae0E196dC18355aF3a19985faf67354213F833D ✅ 活跃
Base 主网 0x73fc659Cd5494E69852bE8D9D23FE05Aab14b29B 🎉 已上线
X-Layer 主网 0x73fc659Cd5494E69852bE8D9D23FE05Aab14b29B 🎉 已上线
BSC 主网 0x1Ae0E196dC18355aF3a19985faf67354213F833D 🎉 已上线
Ethereum 主网 - 🚧 计划中

TransferHook（内置）

网络 TransferHook 状态
Base Sepolia (测试网) 0x4DE234059C6CcC94B8fE1eb1BD24804794083569 ✅ 活跃
X-Layer 测试网 0xD4b98dd614c1Ea472fC4547a5d2B93f3D3637BEE ✅ 活跃
SKALE Base Sepolia 0x2f05fe5674aE756E25C26855258B4877E9e021Fd ✅ 活跃
BSC 测试网 0x2f05fe5674aE756E25C26855258B4877E9e021Fd ✅ 活跃
Base 主网 0x081258287F692D61575387ee2a4075f34dd7Aef7 🎉 已上线
X-Layer 主网 0x081258287F692D61575387ee2a4075f34dd7Aef7 🎉 已上线
BSC 主网 0x2f05fe5674aE756E25C26855258B4877E9e021Fd 🎉 已上线
Ethereum 主网 - 🚧 计划中

在线示例

用于测试和参考的示例部署：

💡 注意：这些是示例部署。生产环境请部署你自己的 Facilitator 并根据需求进行配置。

📖 文档

开发者文档

🗺️ 路线图

  • SettlementRouter 核心合约
  • Hook 接口和示例
  • TransferHook 内置实现
  • 文档和指南
  • 完整测试覆盖
  • Gas 优化
  • 安全审计
  • 主网部署

🤝 贡献

欢迎贡献！请查看 贡献指南。

对于 AI 代理：在进行任何代码更改之前，必须阅读 开发工作流规则，其中定义了强制性的 Git 工作流实践。

📄 许可证

Apache-2.0 License - 详见 LICENSE

🔗 相关链接