x402-Conflux Adapter

x402 Payment Protocol adapter for Conflux Network with Tree-Graph consensus support.

项目概述

本项目实现了 x402 支付协议与 Conflux 区块链的适配，支持 Tree-Graph 共识机制的交易验证。

核心功能

• x402 协议支持: HTTP 402 Payment Required 响应处理
• Tree-Graph 验证: 基于 Conflux 独特的 Tree-Graph 共识进行交易确认验证
• 链上数据读取: 封装 js-conflux-sdk 提供简洁的链上数据访问接口
• REST API: 完整的 API 服务端点

技术架构

┌─────────────────────────────────────────────────────────────┐
│                      Client Layer                           │
│                    (AI Agent / API)                         │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                   x402 Payment Layer                        │
│              (Payment Verifier / 402 Header)                │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                Conflux Adapter Layer                        │
│     (Tree-Graph Verifier / Chain Reader / Tx Validator)     │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                  Conflux Testnet                            │
│                  (RPC / Smart Contract)                     │
└─────────────────────────────────────────────────────────────┘

快速开始

安装依赖

npm install

运行开发服务器

npm run dev

构建项目

npm run build

运行测试

npm test

启动生产服务器

npm start

API 端点

端点	方法	描述
/	GET	服务信息
/health	GET	健康检查
/chain/status	GET	Conflux 链状态
/verify	POST	完整支付验证
/verify/:txHash	GET	快速交易验证
/tree-graph/:txHash	GET	Tree-Graph 确认路径
/tx/:txHash	GET	交易详情
/protected	GET	x402 受保护资源示例

使用示例

1. 查询链状态

curl http://localhost:3000/chain/status

响应:

{
  "success": true,
  "data": {
    "chainId": 1,
    "networkId": 1,
    "epochNumber": 12345678,
    "latestConfirmedEpoch": 12345670,
    "network": "conflux-testnet"
  }
}

2. 验证交易

curl http://localhost:3000/verify/0x1234...abcd

响应:

{
  "success": true,
  "verification": {
    "valid": true,
    "confirmed": true,
    "epochConfirmations": 10,
    "message": "Transaction confirmed by Tree-Graph consensus"
  }
}

3. 获取 Tree-Graph 路径

curl http://localhost:3000/tree-graph/0x1234...abcd

响应:

{
  "success": true,
  "data": {
    "txHash": "0x1234...abcd",
    "verification": {
      "confirmed": true,
      "confirmations": 10,
      "txEpoch": 12345660,
      "currentEpoch": 12345670
    },
    "treeGraphPath": [
      { "epochNumber": 12345660, "blockHash": "0xabc...", "isPivot": true },
      { "epochNumber": 12345661, "blockHash": "0xdef...", "isPivot": true }
    ]
  }
}

4. 访问受保护资源

首次请求（无支付凭证）:

curl http://localhost:3000/protected

响应 (HTTP 402):

{
  "error": "Payment Required",
  "x402": {
    "version": "1.0",
    "network": "conflux-testnet",
    "recipient": "cfxtest:aak2rra2njvd77ezwjvx04kkds9fzagfe6d5r8e957",
    "price": "0.01",
    "currency": "CFX"
  }
}

携带支付凭证请求:

curl -H "X-Payment-Proof: {\"txHash\":\"0x...\",\"amount\":\"10000000000000000\"}" \
     http://localhost:3000/protected

Tree-Graph 共识说明

Conflux 使用独特的 Tree-Graph 共识机制：

1. Epoch 结构: 每个 epoch 包含一个 pivot block 和若干 sibling blocks
2. 确认模型: 交易确认基于 epoch 确认数，而非区块确认数
3. 验证逻辑:
   • 获取交易所在的 epoch 号
   • 获取当前 latest_confirmed epoch
   • 计算确认数 = 当前 epoch - 交易 epoch
   • 确认数 >= 所需确认数时，交易被认为最终确认

// Tree-Graph 验证核心逻辑
const latestConfirmed = await conflux.getEpochNumber('latest_confirmed');
const txEpoch = receipt.epochNumber;
const confirmations = latestConfirmed - txEpoch;
const isConfirmed = confirmations >= REQUIRED_CONFIRMATIONS;

环境变量

变量名	默认值	描述
PORT	3000	服务端口
CONFLUX_RPC_URL	https://test.confluxrpc.com	Conflux RPC 端点
RECIPIENT_ADDRESS	(内置测试地址)	收款地址
REQUIRED_CONFIRMATIONS	5	所需 epoch 确认数

项目结构

├── src/
│   ├── x402/
│   │   ├── types.ts          # x402 类型定义
│   │   ├── payment.ts        # 支付验证逻辑
│   │   └── middleware.ts     # Express 中间件
│   ├── conflux/
│   │   ├── client.ts         # Conflux 客户端封装
│   │   ├── tree-graph.ts     # Tree-Graph 验证适配
│   │   └── transaction.ts    # 交易读取工具
│   ├── api/
│   │   └── server.ts         # Express API 服务
│   └── index.ts              # 入口文件
├── test/
│   ├── x402.test.ts          # x402 单元测试
│   ├── conflux.test.ts       # Conflux 集成测试
│   └── integration.test.ts   # 端到端测试
├── package.json
├── tsconfig.json
└── vitest.config.ts

依赖

• js-conflux-sdk: Conflux JavaScript SDK
• express: Web 服务框架
• typescript: TypeScript 支持
• vitest: 测试框架

License

MIT