2569718930@qq.com
198 lines
3.7 KiB
Markdown
198 lines
3.7 KiB
Markdown
# PolyWeather 支付合约升级方案（V2）
|
||
|
||
最后更新：`2026-03-20`
|
||
|
||
## 1. 目标
|
||
|
||
本次 V2 方案对应三个明确目标：
|
||
|
||
1. 把 `owner` 迁到多签地址
|
||
2. 升级到 `SafeERC20 + Pausable + ReentrancyGuard`
|
||
3. 把“链上 plan 绑定”和“EIP-712 授权支付”都纳入设计，而不是只在链下校验
|
||
|
||
合约草案：
|
||
- [PolyWeatherCheckoutV2.sol](/E:/web/PolyWeather/contracts/PolyWeatherCheckoutV2.sol)
|
||
|
||
构造参数编码脚本：
|
||
- [encode_checkout_v2_constructor.py](/E:/web/PolyWeather/scripts/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. 构造参数编码
|
||
|
||
示例：
|
||
|
||
```bash
|
||
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` 配置
|