企业官网建设流程全解析

x402 Python EVM 支付机制详解：Exact 方案、EIP-3009 授权与智能钱包结算

【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402

本文基于仓库中的 EVM 机制说明文档 及其对应的 实现源码，系统讲解 x402 支付协议在 Python SDK 中面向 EVM 链的 Exact 支付方案：如何用ExactEvmClientScheme生成 EIP-3009 签名授权、ExactEvmServerScheme如何解析美元定价并构建付款要求、ExactEvmFacilitatorScheme如何在链上校验签名并完成转账结算，以及 ERC-4337/ERC-6492 智能钱包的自动处理机制。读完后你将能够在 Client / Server / Facilitator 三个角色中完整接入 EVM 链稳定币（USDC 等）的 HTTP 402 支付。

一、机制定位：Exact 方案与三方角色

x402 的 Python EVM 机制（x402.mechanisms.evm）实现的是Exact支付方案：买方签署一份精确金额的转账授权，付款金额必须与卖方的PaymentRequirements完全一致（"exact" 即"分毫不差"）。其底层依赖EIP-3009 TransferWithAuthorization标准——支付方用一次签名授权任意方代其在链上执行transferWithAuthorization，从而避免买方每次支付都要发送交易、支付 gas。

机制由三个对称命名的组件构成（源码位于 exact/ 目录）：

三者共用同一个scheme = "exact"标识（定义于 constants.py 中的SCHEME_EXACT）。在 exact/__init__.py 中，ExactEvmScheme默认导出为 Client 方案（"最常用场景"），而 Server 与 Facilitator 则通过别名ExactEvmServerScheme、ExactEvmFacilitatorScheme单独导出，避免混淆。

二、安装

EVM 机制依赖eth_account与web3，作为可选安装项提供：

uv add x402[evm]

从源码看，signers.py 在模块导入时即尝试from eth_account import Account ... from web3 import Web3，若缺失会抛出带明确提示的ImportError（提示安装x402[evm]），因此在没有该扩展的安装中导入签名器会直接失败。

三、Quick Start：三角色接入

3.1 客户端：签署付款授权

from x402 import x402Client from x402.mechanisms.evm.exact import ExactEvmScheme from x402.mechanisms.evm import EthAccountSigner from eth_account import Account account = Account.from_key("0x...") signer = EthAccountSigner(account) client = x402Client() client.register("eip155:*", ExactEvmScheme(signer=signer)) payload = await client.create_payment_payload(payment_required)

要点（结合 client.py 源码）：

• 构造函数签名是ExactEvmScheme(signer)；若直接传入eth_account的LocalAccount，_wrap_if_local_account()会自动包装成EthAccountSigner，所以跳过手工包装也可以。
• create_payment_payload()内部按requirements.extra["assetTransferMethod"]分流：值为"permit2"时走 Permit2 载荷（create_permit2_payload），否则走标准的 EIP-3009 流程。
• EIP-3009 流程会：随机生成 32 字节 nonce（create_nonce）→ 依据requirements.max_timeout_seconds（缺省 3600 秒，对应 constants.py 的DEFAULT_VALIDITY_PERIOD）计算有效时间窗（create_validity_window，另含 600 秒时钟偏差缓冲DEFAULT_VALIDITY_BUFFER）→ 组装ExactEIP3009Authorization→ 通过build_typed_data_for_signing()构造 EIP-712 类型化数据并调用signer.sign_typed_data()完成签名。
• 签名 EIP-712 需要域参数name/version（如 USDC 的"USD Coin"/"2"）。客户端优先从requirements.extra读取；若缺失，则尝试通过get_asset_info()从本地注册资产中补全，再缺失才抛出ValueError("EIP-712 domain parameters (name, version) required in extra")。

3.2 服务端：构建付款要求

from x402 import x402ResourceServer from x402.mechanisms.evm.exact import ExactEvmServerScheme server = x402ResourceServer(facilitator_client) server.register("eip155:*", ExactEvmServerScheme())

server.py 中的ExactEvmServerScheme提供两个关键能力：

1. parse_price(price, network)— 价格解析。price可以是三种形式：
   • 已是AssetAmount字典（含amount键）或AssetAmount对象：原样返回（要求必须带asset地址）；
   • 美元金额字符串/数字（如"$0.01"或1.5）：先经parse_money_to_decimal()归一化，再依次尝试用户注册的自定义解析器链（register_money_parser()支持链式注册、按注册顺序尝试，返回None则继续下一个），最后回落到默认 USDC 转换amount * 10**decimals（Base 上 USDC 为 6 位小数，即$0.01→10000原子单位）。
2. enhance_payment_requirements()— 付款要求增强。自动完成四件事：按NETWORK_CONFIGS填充默认资产地址；把带小数点的金额按代币decimals转换为最小单位；向extra注入 EIP-712 域参数name/version；若资产配置了assetTransferMethod（如"permit2"）则一并写入extra，供客户端分流。若某网络未配置默认稳定币且用户未显式指定资产，会抛出明确错误提示使用register_money_parser或显式AssetAmount。

3.3 Facilitator：校验与结算

from x402 import x402Facilitator from x402.mechanisms.evm.exact import ExactEvmFacilitatorScheme from x402.mechanisms.evm import FacilitatorWeb3Signer facilitator = x402Facilitator() facilitator.register(["eip155:8453", "eip155:84532"], ExactEvmFacilitatorScheme(signer=signer))

注意以当前源码为准：FacilitatorWeb3Signer的构造参数是private_key+rpc_url（见 signers.py L261-L284），即：

signer = FacilitatorWeb3Signer( private_key="0x...", rpc_url="https://sepolia.base.org", )

它在初始化时会为 Base、Polygon 等 PoA 链注入ExtraDataToPOAMiddleware，并缓存chain_id。

Facilitator 方案支持一个可选配置类ExactEvmSchemeConfig（facilitator.py L46-L54）：

3.4 注册辅助函数

register.py 提供三个一站式注册函数，均同时注册 V2（eip155:*或指定网络）与 V1 遗留网络：

from x402.mechanisms.evm.exact import ( register_exact_evm_client, register_exact_evm_server, register_exact_evm_facilitator, ) # 客户端：自动包装 LocalAccount，注册 eip155:* + 全部 V1 网络 register_exact_evm_client(client, signer) # 服务端：仅 V2 register_exact_evm_server(server) # Facilitator：可开启智能钱包部署与 settle 模拟 register_exact_evm_facilitator( facilitator, signer, networks="eip155:84532", deploy_erc4337_with_eip6492=False, simulate_in_settle=False, )

四、Signer 协议与内置实现

x402 通过两个 Protocol 把"钱包能力"与"支付逻辑"解耦（signer.py）：

• ClientEvmSigner：只需address属性 +sign_typed_data(domain, types, primary_type, message)两个成员，即可接入任意钱包 SDK。
• FacilitatorEvmSigner：需要get_addresses()、read_contract()、verify_typed_data()、write_contract()、send_transaction()、wait_for_transaction_receipt()、get_balance()、get_chain_id()、get_code()等能力，覆盖读合约、验签、发交易、等回执全流程。

signers.py 提供了三个开箱即用的实现：

五、EIP-3009 授权结构与 EIP-712 签名

Exact 方案的核心载荷（types.py 的ExactEIP3009Authorization/ExactEIP3009Payload）序列化为如下 JSON：

{ "from": "0x...", # 支付方地址 "to": "0x...", # 收款地址（payTo） "value": "10000000", # 金额，最小单位（USDC 即 $1.00） "validAfter": "1700000000", # 生效时间（Unix 秒） "validBefore": "1700003600", # 过期时间（Unix 秒） "nonce": "0x...", # 32 字节随机 nonce，防重放 }

ExactEIP3009Payload在此基础上附加signature字段（0x前缀的 65 字节 ECDSA，或更长的 ERC-6492 封装签名）。签名时通过 eip712.py 的build_typed_data_for_signing()构造域{name, version, chainId, verifyingContract: 代币合约}与TransferWithAuthorization主类型——域参数直接决定签名哈希，因此服务端注入的name/version必须与链上name()/version()一致，否则验签必然失败。

链上执行时，Facilitator 按代币 ABI 调用transferWithAuthorization（VRS 与 bytes 两种重载均内置于 constants.py 的TRANSFER_WITH_AUTHORIZATION_VRS_ABI/TRANSFER_WITH_AUTHORIZATION_BYTES_ABI），并可用authorizationState查询 nonce 是否已被使用。

六、Facilitator 校验与结算流程

ExactEvmFacilitatorScheme.verify()的完整校验清单（facilitator.py L116-L270）：

1. Scheme 匹配：payload.accepted.scheme必须为exact，否则返回unsupported_scheme；
2. 网络匹配：payload.accepted.network == requirements.network，否则network_mismatch；
3. 链 ID 解析：CAIP-2eip155:<id>→ chain id，解析失败返回invalid_exact_evm_failed_to_get_network_config；
4. EIP-712 域参数：extra必须含name与version，否则missing_eip712_domain；
5. 收款方一致：authorization.to == requirements.pay_to，否则invalid_exact_evm_payload_recipient_mismatch；
6. 金额一致：authorization.value == requirements.amount（Exact 方案的"精确"约束），否则invalid_exact_evm_payload_authorization_value_mismatch；
7. 时间窗：validBefore必须晚于当前时间 + 6 秒缓冲（防过期竞态），validAfter不得晚于当前时间；
8. 签名分类与校验：classify_eip3009_signature()判定签名属于 EOA / 已部署智能钱包（EIP-1271）/ 未部署智能钱包（ERC-6492）三类之一；未部署钱包若无部署信息则报invalid_exact_evm_payload_undeployed_smart_wallet；
9. 交易模拟：simulate_eip3009_transfer()用eth_call预演转账，失败时经diagnose_eip3009_simulation_failure()给出细化原因（如余额不足invalid_exact_evm_insufficient_balance、nonce 已用invalid_exact_evm_nonce_already_used）。

settle()流程：先复用_verify()（是否再模拟取决于simulate_in_settle）→ 若签名携带 ERC-6492 部署信息且钱包尚未部署，则按配置自动调用工厂部署（deploy_erc4337_with_eip6492）→ 执行transferWithAuthorization→wait_for_transaction_receipt()等待确认（超时 120 秒）→ 回执status == 1返回SettleResponse(success=True, transaction=tx_hash, ...)。

Permit2 载荷会分流到verify_permit2()/settle_permit2()（permit2_utils.py），由 Uniswap Permit2 合约配合仓库中的 x402ExactPermit2Proxy 完成结算（代理地址0x402085c248EeA27D92E8b30b2C58ed07f9E20001，与 Permit2 一样经 CREATE2 在各 EVM 链固定部署）。

七、支持的链与默认资产

x402.mechanisms.evm导出NETWORK_CONFIGS（CAIP-2 映射）与V1_NETWORKS（遗留网络名）。当前 constants.py 中内置的 V2 链及默认资产如下：

eip155:*通配符可注册到所有 EVM 链；V1 遗留网络名（base、base-sepolia、polygon、polygon-amoy、avalanche、avalanche-fuji等）由V1_NETWORKS列出，注册辅助函数会自动完成 V1 侧注册。关于链与代币支持的完整背景（CAIP-2 标识规范、EIP-3009 与 Permit2 的选择逻辑），参见 Networks & Token Support；为美元字符串定价补充新链默认资产的方式亦见该文档 新增默认资产 一节。

八、资产支持：EIP-3009 优先，Permit2 兜底

机制支持两类代币转账路径（可对照 network-and-token-support.mdx 的"EVM: Asset Transfer Methods"一节）：

• EIP-3009：适用于实现了transferWithAuthorization()的代币（USDC 等），一次签名即可、无授权步骤，是首选路径；
• Permit2：适用于任意 ERC-20，需一次性 Permit2 授权。仓库提供了两条免 gas 扩展来免除这一步：EIP-2612 permit 扩展（x402.extensions.eip2612_gas_sponsoring）与 ERC-20 approval 扩展（x402.extensions.erc20_approval_gas_sponsoring）。从客户端源码可见，当服务端在PaymentRequired.extensions中声明相应能力、且签名器实现了对应 Protocol（ClientEvmSignerWithReadContract/ClientEvmSignerWithSignTransaction）时，create_payment_payload()会先链上读取现有 allowance，不足时自动补签扩展数据并放入载荷的__extensions字段。

自定义代币接入需要三要素：代币地址、EIP-712name、EIP-712version（即链上name()/version()返回值），服务端可通过显式AssetAmount（含extra.eip712）或在AssetInfo注册中提供。

九、智能钱包支持（ERC-4337 / ERC-6492）

Exact 方案自动处理三种签名来源：

• EOA：标准 ECDSA，直接Account.recover_message恢复比对；
• 已部署智能钱包：EIP-1271isValidSignature校验，成功返回0x1626ba7e（EIP1271_MAGIC_VALUE）；
• 未部署智能钱包：ERC-6492 反事实签名。签名中内嵌工厂地址与部署 calldata（parse_erc6492_signature()解析，见 erc6492.py），verify 阶段按未来地址校验签名，settle 阶段在deploy_erc4337_with_eip6492=True时由 Facilitator 代为执行部署交易。未开启该配置时，遇到未部署钱包会返回invalid_exact_evm_payload_undeployed_smart_wallet错误码。

十、错误码速查

所有失败路径都返回语义化的invalid_reason（定义于 constants.py L318-L362），常见者如：

十一、关键文件索引

小结：Python 的 x402 EVM 机制把 EIP-3009 "一次签名、代付 gas" 的支付模型封装为三角色对称的 Scheme 类——客户端只管签名、服务端只管定价与要求、Facilitator 只管校验与上链，且通过 Signer Protocol 允许你接入任意钱包实现，通过 ERC-6492 自动兼容尚未部署的 ERC-4337 智能账户。若你只需美元计价 + USDC 结算，按第二、三节的注册方式配合NETWORK_CONFIGS中任一内置链即可跑通；若使用自定义代币或链，则需要补充资产信息或注册自定义 money parser。

【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402