PolyWeather/docs/payments/PAYMENT_UPGRADE_V2_ZH.md

PolyWeather 支付合约升级方案（V2）

最后更新：2026-03-20

1. 目标

本次 V2 方案对应三个明确目标：

1. 把 owner 迁到多签地址
2. 升级到 SafeERC20 + Pausable + ReentrancyGuard
3. 把“链上 plan 绑定”和“EIP-712 授权支付”都纳入设计，而不是只在链下校验

合约草案：

• PolyWeatherCheckoutV2.sol

构造参数编码脚本：

• encode_checkout_v2_constructor.py

2. V2 新增能力

多签 owner

V2 constructor 不再默认 msg.sender 作为唯一 owner，而是显式传入：

• initialOwner
• initialTreasury
• initialSigner

这意味着：

• 部署后可直接把多签地址设为 owner
• 不需要先单签部署再补 transfer

SafeERC20

V2 内置最小 SafeERC20 封装：

• safeTransferFrom
• safeTransfer

相比直接依赖 IERC20.transferFrom -> bool：

• 对非标准 ERC20 的兼容性更稳
• 出错边界更明确

Pausable

V2 增加：

• pause()
• unpause()

支付入口：

• payPlan(...)
• payAuthorized(...)

都受 whenNotPaused 保护。

一旦发现：

• treasury 配置错误
• token allowlist 配置错误
• 签名器异常
• 链上风控问题

可以直接暂停支付入口。

ReentrancyGuard

V2 增加 nonReentrant，保护：

• payPlan
• payAuthorized
• rescueToken

虽然当前订单去重已经能挡住典型重复支付路径，但 ReentrancyGuard 仍然是更稳的防线。

链上套餐绑定

V2 新增：

• setPlan(planId, token, amount, active)
• planConfig[planId][token]

正式支付入口 payPlan 会：

1. 校验 token 已 allowed
2. 校验 planId + token 的 plan 已 active
3. 从链上读取 amount
4. 按链上配置收款

这意味着：

• planId / amount / token 绑定不再完全依赖链下

EIP-712 授权支付

V2 同时保留第二条入口：

• payAuthorized(...)

它适合：

• 临时折扣
• 特殊活动价
• 不想每次都上链改 setPlan

校验字段包括：

• orderId
• payer
• planId
• token
• amount
• nonce
• deadline

签名人地址由：

• signer

统一控制。

3. 两条支付路径怎么选

路线 A：链上套餐绑定优先

优点：

• 最直观
• 合约级约束最强
• 更容易审计

缺点：

• 套餐改价需要 owner 交易

适合：

• 月付/季付/年付这类稳定商品

路线 B：EIP-712 授权优先

优点：

• 活动价灵活
• 不必每次改链上 plan

缺点：

• 需要管理 signer 密钥
• 风险从 owner 单点，部分转移到 signer 运维

适合：

• 促销
• 临时折扣
• 白名单价格

当前建议

生产建议不是二选一，而是：

1. 稳定套餐 走 payPlan
2. 特殊场景 走 payAuthorized

这样：

• 主流程更稳
• 特殊价仍保留灵活性

4. 推荐迁移步骤

1. 先部署 V2 到测试环境
2. owner 直接用多签地址
3. 配置 treasury
4. 配置 allowedToken
5. 配置 planId/token/amount
6. 仅在需要活动价时再配置 signer
7. 用事件重放脚本和运行态接口验证
8. 再切生产前端/后端配置到新 receiver_contract

5. 构造参数编码

示例：

python scripts/encode_checkout_v2_constructor.py \
  --owner 0xYourMultiSig \
  --treasury 0xYourTreasury \
  --signer 0xYourBackendSigner

6. 当前判断

V2 已经把这三件事做成了明确方案：

1. 多签 owner
2. SafeERC20 + Pausable + ReentrancyGuard
3. 链上 plan 绑定 + EIP-712 授权

它现在是升级草案，不是现网已部署合约。

如果要真正上线，下一步就是：

1. 做一次测试网或本地链验证
2. 更新 PolygonScan 验证文档
3. 修改后端 receiver_contract 配置