284 lines
13 KiB
Markdown
284 lines
13 KiB
Markdown
# WTFX 核心智能合约系统设计与实战开发指南
|
||
|
||
> **项目名称**：WTFX (原 WTFPred / WTF Market)
|
||
> **核心定位**：基于 Bonding Curve（多结果联动幂律 LDA 曲线）的高频预测市场协议，支持内盘快速发射与毕业后无缝转入现货/订单簿。
|
||
> **设计语言**：Solidity `^0.8.29` / `Cancun EVM` / `Arbitrum Nitro`
|
||
|
||
---
|
||
|
||
## 目录
|
||
1. [系统整体架构与核心组件](#1-系统整体架构与核心组件)
|
||
2. [经济模型与核心数学机制](#2-经济模型与核心数学机制)
|
||
3. [分档位治理体系与单市场覆盖](#3-分档位治理体系与单市场覆盖)
|
||
4. [完整生命周期与业务流程](#4-完整生命周期与业务流程)
|
||
5. [目录结构与代码组织](#5-目录结构与代码组织)
|
||
6. [编译、部署与测试指南 (Robinhood Chain & 本地)](#6-编译部署与测试指南)
|
||
7. [关键接口速查与开发示例](#7-关键接口速查与开发示例)
|
||
|
||
---
|
||
|
||
## 1. 系统整体架构与核心组件
|
||
|
||
WTFX 采用模块化解耦与可升级代理架构（Upgradeable Proxy Pattern），核心由三大支柱构成：
|
||
|
||
```
|
||
┌────────────────────────┐
|
||
│ WTFX 用户 / 交易者 │
|
||
└───────────┬────────────┘
|
||
│ (Mint/Redeem/Claim/Transfer)
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ WTFMarketV2.sol │
|
||
│ - ERC-6909 多代币标准（每个结果选项一个 TokenId: 1, 2, 4...） │
|
||
│ - 市场资金池状态机（Trading -> Graduated / Finalised / Refunded）│
|
||
└──────────────┬──────────────────────────────┬───────────────┘
|
||
│ │
|
||
(查询联动曲线边际价与成本) (查询市场元数据、档位与治理配置)
|
||
▼ ▼
|
||
┌─────────────────────────────┐┌──────────────────────────────┐
|
||
│ PowerLDACurveV2.sol ││ WTFControllerV2.sol │
|
||
│ - 幂律 LDA 联合曲线计算库 ││ (Upgradeable Proxy + Facade)│
|
||
│ - calMarginalPrice / Seed ││ - MarketFactory (建盘分发) │
|
||
│ - 多结果自平衡与时间衰减 ││ - Governance (分档位与参数) │
|
||
│ ││ - Registry (命题确权与争议期) │
|
||
└─────────────────────────────┘└──────────────────────────────┘
|
||
```
|
||
|
||
### 核心合约模块职责
|
||
1. **`WTFControllerV2.sol` (中枢控制器)**：
|
||
- 作为协议的主入口与可升级代理实现（Proxy Pattern）；
|
||
- **`MarketFactory`**：负责根据创作者配置部署专属 `WTFMarketV2` 实例，并完成初始流动性（Seed）注入；
|
||
- **`Governance`**：管理创作者手续费分成、中心化收益钱包（Central Wallet）、全局默认毕业阈值与 **分档位（Tiers）/ 单市场覆盖（Overrides）**；
|
||
- **`Registry`**：负责链上命题元数据确权（`questionId`）、选项绑定与裁决争议期管理。
|
||
2. **`WTFMarketV2.sol` (预测市场交易实例)**：
|
||
- 采用 **ERC-6909** 多资产标准，每个预测选项对应一个独立的 `tokenId`（如 `Yes = 1`, `No = 2`）；
|
||
- 独立托管抵押品（WUSD / USDC），执行交易者的买入（`mintCollateralToExactOt`）与卖出（`redeemExactOtToCollateral`）；
|
||
- 实现市场毕业（`graduate`）、全员返还（`refund`）以及最终兑付（`claim`）。
|
||
3. **`PowerLDACurveV2.sol` (联合曲线引擎)**：
|
||
- 基于幂律连续拍卖（Linear Discrete Auction / Power Curve）算法；
|
||
- 实现任意数量选项（2 ~ 255 个）的联动价格发现；
|
||
- 保证资金池抵押品与代币铸造的严格守恒与无摩擦做市。
|
||
|
||
---
|
||
|
||
## 2. 经济模型与核心数学机制
|
||
|
||
### 2.1 创作者 Seed 机制（冷启动注入）
|
||
创作者建盘时需注入一定量的底仓（Seed OT），例如每个选项 1 ~ 10 OT：
|
||
- **零额外费用**：初始 Seed 调用 `curve.calSeedCost`，不收取创作者手续费；
|
||
- **博弈论本质**：Seed 锁在池子中作为底仓，创作者持有全套结果代币。即使盘子无人交易，创作者可通过 `refund()` 或到期 `claim()` **100% 取回大部分本金**。
|
||
|
||
### 2.2 交易手续费流向 (Fee Split)
|
||
每一笔买入/卖出交易扣除的 `feeRate`（创作者建盘时在 0.1% ~ 3.0% 之间自主选择并冻结）：
|
||
- **50% 创作者激励**：直接沉淀为创作者待提取收入；
|
||
- **50% 平台中心化钱包**：流入超级管理员配置的 `centralWallet`。
|
||
|
||
### 2.3 毕业（Graduation）机制
|
||
当买方狂热将资金池推升至阈值时触发毕业：
|
||
- **触发条件**：`totalMarketCap >= thresholdMcap` 或 `maxSupplySingle >= thresholdMaxSupply`；
|
||
- **毕业效果**：
|
||
1. 联合曲线立即永久冻结，停止 Curve 买卖；
|
||
2. 按照各选项最终边际价格归一化计算概率分布，锁定 `redeemValue`；
|
||
3. 资金池流动性与代币可平滑迁移至外部 CLOB 订单簿或 AMM 现货池。
|
||
|
||
---
|
||
|
||
## 3. 分档位治理体系与单市场覆盖
|
||
|
||
系统彻底废弃全局一刀切设计，建立了三级优先级的治理读取模型：
|
||
|
||
$$ ext{生效参数} = \mathbf{单市场独立覆盖 (Override)} \succ \mathbf{所属市场档位 (Tier)} \succ \mathbf{全局兜底配置 (Global Default)}$$
|
||
|
||
### 3.1 预设标准档位参数 (Robinhood / Production Grade)
|
||
|
||
| 档位 | 命名 | 定位与场景 | 毕业 mcap | 单结果供给 | 争议窗口期 |
|
||
| :--- | :--- | :--- | :--- | :--- | :--- |
|
||
| **Tier 1** | **PvP 极速盘** | 链上热点、KOL 互撕、数小时结算 | **$3,000 WUSD** | 50,000 OT | **10 分钟 (600s)** |
|
||
| **Tier 2** | **社区主流盘** | 赛事决赛、周度行情、经济指标 | **$25,000 WUSD** | 300,000 OT | **2 小时 (7200s)** |
|
||
| **Tier 3** | **旗舰宏观盘** | 总统大选、宏观政策、机构大盘 | **$100,000 WUSD**| 1,000,000 OT| **24 小时 (86400s)**|
|
||
| **Tier 0** | **全局默认** | 兜底未分档市场 | $10,000 WUSD | 100,000 OT | 1 小时 (3600s) |
|
||
|
||
### 3.2 治理接口说明
|
||
- `setMarketTier(tierId, mcap, maxSupply, disputeWindow)`：管理员配置指定档位的标准参数；
|
||
- `setMarketTierBinding(market, tierId)`：为特定市场切换绑定的档位；
|
||
- `setMarketConfigOverride(market, mcap, maxSupply, disputeWindow, isCustom)`：为某个重要盘子定制独一无二的阈值（`isCustom=true` 立即生效覆盖，`isCustom=false` 撤销并回退到档位）。
|
||
|
||
---
|
||
|
||
## 4. 完整生命周期与业务流程
|
||
|
||
```
|
||
[创作者建盘] ──> [联合曲线交易阶段] ──> [触发毕业] (自动/Keeper冻结曲线)
|
||
│
|
||
▼ (事件截止)
|
||
[创作者裁决] (resolveOutcome -> finaliseOutcome)
|
||
│
|
||
▼
|
||
[争议窗口期内] (10分钟 ~ 24小时)
|
||
├── 超级管理员改判 (overrideFinalise)
|
||
└── 创作者/管理员全员返还 (refund)
|
||
│
|
||
▼ (争议期结束)
|
||
[赢家兑付] (claim 销毁获胜 OT 领取抵押品)
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 目录结构与代码组织
|
||
|
||
`wtf-contract/` 目录下包含了完整的合约体系与依赖：
|
||
|
||
```
|
||
wtf-contract/
|
||
├── main/ # 核心主合约体系
|
||
│ ├── src/
|
||
│ │ ├── controllerv2/ # 控制器、工厂、存储与治理逻辑
|
||
│ │ │ ├── ControllerStorage.sol # 统一存储槽与数据结构定义
|
||
│ │ │ ├── Governance.sol # 治理分档位与费率逻辑
|
||
│ │ │ ├── MarketFactory.sol # 市场部署与 Seed 注入
|
||
│ │ │ ├── Registry.sol # 命题注册与裁决逻辑
|
||
│ │ │ └── WTFControllerV2.sol # 主入口与代理合约
|
||
│ │ ├── interfaces/ # 外部与内部接口
|
||
│ │ │ ├── IRegistry.sol
|
||
│ │ │ ├── IWTFControllerV2.sol
|
||
│ │ │ ├── IWTFCurve.sol
|
||
│ │ │ └── IWTFMarketV2.sol
|
||
│ │ ├── libraries/ # 核心算法、事件与自定义错误
|
||
│ │ │ ├── Errors.sol # 统一 EVM Custom Errors
|
||
│ │ │ ├── Event.sol # 链上日志定义
|
||
│ │ │ ├── QuestionV2.sol # 命题状态与哈希算法
|
||
│ │ │ └── WTFMath.sol # 高精度定点数数学库
|
||
│ │ ├── WTFERC6909.sol # 极简高效 ERC-6909 多代币实现
|
||
│ │ └── WTFMarketV2.sol # 预测市场交易与资金池状态机
|
||
│ └── lib/ # OpenZeppelin & Solady 标准依赖库
|
||
│
|
||
├── curve/ # 联合曲线与高阶数学计算库
|
||
│ └── src/
|
||
│ └── curves/
|
||
│ ├── math/ # 幂律与 LDA 边际价求解器
|
||
│ │ ├── PowerLDAMath.sol
|
||
│ │ ├── PowerMath.sol
|
||
│ │ └── LDAMath.sol
|
||
│ └── PowerLDACurveV2.sol # 联合曲线合约
|
||
│
|
||
└── mock/ # 测试辅助合约
|
||
├── MockERC20.sol # 支持无限 Mint 领水的 WUSD 抵押品
|
||
└── TestProxy.sol # 极简 Delegatecall 可升级代理
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 编译、部署与测试指南
|
||
|
||
### 6.1 本地与 Robinhood Chain 测试网环境要求
|
||
- **Node.js**: `>= 18.0.0`
|
||
- **Solidity 编译器**: `0.8.29`
|
||
- **EVM Target**: `cancun` (或 `paris` / `shanghai`，若目标链不支持 Cancun EIP-1153，可在 `MarketV2` 中使用标准 ReentrancyGuard)
|
||
|
||
### 6.2 部署到 Robinhood Chain Testnet 快速配置
|
||
|
||
在 Hardhat 配置文件中添加测试网网络：
|
||
```javascript
|
||
module.exports = {
|
||
solidity: {
|
||
version: "0.8.29",
|
||
settings: {
|
||
evmVersion: "cancun",
|
||
optimizer: { enabled: true, runs: 200 }
|
||
}
|
||
},
|
||
networks: {
|
||
robinhoodTestnet: {
|
||
url: "https://rpc.testnet.chain.robinhood.com",
|
||
chainId: 46630,
|
||
accounts: [process.env.PRIVATE_KEY] // 部署者私钥
|
||
}
|
||
}
|
||
};
|
||
```
|
||
|
||
### 6.3 部署核心步骤
|
||
1. **部署抵押品 (WUSD)**：部署 `MockERC20("WTF USD", "WUSD", 18)`；
|
||
2. **部署联合曲线**：部署 `PowerLDACurveV2`；
|
||
3. **部署控制器代理**：
|
||
- 部署 `Registry` 库并链接部署 `WTFControllerV2` 实现；
|
||
- 部署 `TestProxy` 指向实现合约；
|
||
- 调用 `controller.initialize(admin, treasury, defaultFeeRate, delay)`；
|
||
4. **初始化参数与档位**：
|
||
- 授权抵押品与曲线进入白名单；
|
||
- 调用 `setMarketTier` 初始化 Tier 1 ($3k)、Tier 2 ($25k)、Tier 3 ($100k)。
|
||
|
||
---
|
||
|
||
## 7. 关键接口速查与开发示例
|
||
|
||
### 1) 创建预测市场 (`deployMarket`)
|
||
```solidity
|
||
QuestionParams memory qParams = QuestionParams({
|
||
timestampEnd: block.timestamp + 7 days,
|
||
title: "WTFX？Robinhood Chain 主网本季度会上线吗？",
|
||
ancillaryData: "0x",
|
||
imageUri: "https://...",
|
||
outcomeNames: ["会", "不会"],
|
||
outcomeImageUris: ["", ""]
|
||
});
|
||
|
||
MarketParams memory mParams = MarketParams({
|
||
parentTokenId: 0,
|
||
collateral: wusdAddress,
|
||
curve: curveAddress,
|
||
timestampStart: block.timestamp,
|
||
feeRate: 6000000000000000, // 0.6%
|
||
tierId: 1 // Tier 1: PvP 盘
|
||
});
|
||
|
||
// otSeed = 1e18 (每选项 1 个 OT)
|
||
(bytes32 questionId, address market) = controller.deployMarket(
|
||
qParams,
|
||
mParams,
|
||
oracleAddress,
|
||
1 ether
|
||
);
|
||
```
|
||
|
||
### 2) 买入指定结果代币 (`mintCollateralToExactOt`)
|
||
```solidity
|
||
// 在 market 合约中买入 10 个 Yes (tokenId = 1)
|
||
uint256 tokenId = 1; // 2^0
|
||
uint256 otAmount = 10 ether;
|
||
|
||
// 先 approve 给 market 合约抵押品
|
||
wusd.approve(market, type(uint256).max);
|
||
|
||
// 执行买入
|
||
market.mintCollateralToExactOt(
|
||
msg.sender,
|
||
tokenId,
|
||
otAmount,
|
||
""
|
||
);
|
||
```
|
||
|
||
### 3) 创作者裁决与结算 (`resolveOutcome` & `finaliseOutcome`)
|
||
```solidity
|
||
uint256 winningAnswer = 1; // 2^0 表示 Yes 赢
|
||
|
||
// 1. 提交裁决
|
||
controller.resolveOutcome(questionId, winningAnswer);
|
||
|
||
// 2. 定案并开启争议期
|
||
controller.finaliseOutcome(questionId, winningAnswer);
|
||
```
|
||
|
||
### 4) 争议期后领取获胜收益 (`claim`)
|
||
```solidity
|
||
uint256[] memory tokenIds = new uint256[](1);
|
||
tokenIds[0] = 1;
|
||
|
||
uint256[] memory amounts = new uint256[](1);
|
||
amounts[0] = 10 ether; // 销毁 10 个 Yes
|
||
|
||
// 自动根据资金池总金额结算抵押品返回至接收者
|
||
market.claim(msg.sender, tokenIds, amounts);
|
||
```
|