预测市场 + SDK — 设计

日期：2026-03-10 状态：已批准 作者：BabyDriver Team

---

1. 背景与决策

1.1 目标

构建 Polymarket 风格的预测市场系统，集成 BabyDriver 原生 OracleHub 实现价格类市场自动结算，并提供 isomorphic TypeScript SDK 供 DApp 和 Bot 开发者使用。

1.2 关键决策

决策项	选择	理由
条件代币标准	ERC-1155 Conditional Tokens（Gnosis CTF）	行业标准，Polymarket 使用，生态兼容
交易模式	链上 CLOB 订单簿	L2 gas 低，资金效率高于 AMM
结算模式	混合：OracleHub 自动 + admin 手动	价格类自动化，事件类灵活
SDK 风格	isomorphic（browser + Node.js）	一个包覆盖前端 + Bot
SDK 底层库	viem	轻量、tree-shakeable、类型安全
架构	Polymarket 克隆（方案 A）	refs/ 有完整参考，行业验证

---

2. 合约架构

2.1 目录结构

contracts/src/prediction/
├── ConditionalTokens.sol        — ERC-1155 条件代币
├── CTFExchange.sol              — 链上 CLOB 订单簿
├── OracleResolver.sol           — 混合结算器
└── interfaces/
    ├── IConditionalTokens.sol
    ├── ICTFExchange.sol
    └── IOracleResolver.sol

2.2 合约职责

合约	职责	参考
ConditionalTokens	ERC-1155 position tokens，split/merge/redeem	refs/conditional-tokens-contracts
CTFExchange	限价单撮合，EIP-712 签名验证，maker/taker 费率	refs/ctf-exchange
OracleResolver	混合结算 + 市场创建工厂	refs/uma-ctf-adapter 简化版

2.3 数据流

创建市场 → OracleResolver.createPriceMarket / createManualMarket
                ↓
         ConditionalTokens.prepareCondition(oracle, questionId, outcomeSlotCount)
                ↓
交易 → User 用 collateral splitPosition 成 YES/NO position tokens
                ↓
       CTFExchange 上挂限价单交易 position tokens
                ↓
结算 → OracleResolver.resolvePrice() — 读 OracleHub 自动结算
       OracleResolver.resolveManual() — admin 手动结算
                ↓
       ConditionalTokens.reportPayouts(questionId, payouts)
                ↓
赎回 → User.redeemPositions() → 按 payout 比例拿回 collateral

Collateral 默认 WETH（BabyDriver L2 上的 wrapped ETH）。

---

3. ConditionalTokens 合约

简化版 Gnosis CTF，去掉嵌套条件（parentCollectionId），只支持单层市场。

3.1 核心数据

// conditionId = keccak256(abi.encodePacked(oracle, questionId, outcomeSlotCount))
mapping(bytes32 => uint[]) public payoutNumerators;
mapping(bytes32 => uint) public payoutDenominator;

// positionId = uint(keccak256(abi.encodePacked(collateralToken, conditionId, indexSet)))
// 作为 ERC-1155 tokenId

3.2 核心函数

函数	说明
prepareCondition(oracle, questionId, outcomeSlotCount)	注册条件（由 OracleResolver 调用）
reportPayouts(questionId, payouts[])	Oracle 报告结果（仅 oracle 地址可调用）
splitPosition(collateral, conditionId, partition[], amount)	锁定 collateral，铸造 outcome position tokens
mergePositions(collateral, conditionId, partition[], amount)	销毁 position tokens，解锁 collateral
redeemPositions(collateral, conditionId, indexSets[])	结算后按 payout 比例赎回 collateral
getOutcomeSlotCount(conditionId)	查询 outcome 数量

3.3 简化点（vs Gnosis 原版）

• 去掉 parentCollectionId（不支持嵌套条件）

• 去掉 P-256 椭圆曲线计算（collectionId 改为简单 keccak256）

• positionId = uint(keccak256(collateral, conditionId, indexSet)) 直接计算

---

4. CTFExchange 订单簿

链上 CLOB，EIP-712 签名订单，任何人可以提交匹配。

4.1 Order 结构

struct Order {
    uint256 salt;           // 随机数（防重复）
    address maker;          // 挂单者
    address signer;         // 签名者（可以是 maker 的委托）
    uint256 tokenId;        // position token ERC-1155 ID
    uint256 makerAmount;    // maker 出的数量
    uint256 takerAmount;    // maker 要的数量
    uint256 expiration;     // 过期时间
    uint256 nonce;          // 取消用的 nonce
    uint256 feeRateBps;     // 费率（basis points）
    Side side;              // BUY or SELL
}

enum Side { BUY, SELL }
enum MatchType { COMPLEMENTARY, MINT, MERGE }

4.2 核心函数

函数	说明
fillOrder(order, fillAmount, signature)	填充单个订单
matchOrders(takerOrder, makerOrders[], fillAmounts[], sigs)	批量撮合
cancelOrder(order)	maker 取消订单
incrementNonce()	批量取消（nonce 以下全部失效）

4.3 交易模式

类型	说明	场景
COMPLEMENTARY	BUY YES vs BUY NO，互为对手方	最常见
MINT	两个 BUY 订单 → split collateral 铸造	新建流动性
MERGE	两个 SELL 订单 → merge positions 回 collateral	回收流动性

4.4 费率

• 默认 maker 0 bps, taker 2 bps (0.02%)

• admin 可调

• 费用从交易 proceeds 中扣除

4.5 简化点（vs Polymarket 原版）

• 去掉 POLY_PROXY / POLY_GNOSIS_SAFE 签名类型，只支持 EOA + EIP-1271

• 去掉 taker 字段的定向订单（所有订单公开可填充）

• 去掉 operator 代理模式

---

5. OracleResolver 混合结算器

5.1 结算模式

enum ResolutionType { PRICE_THRESHOLD, MANUAL }

struct Market {
    bytes32 conditionId;
    bytes32 questionId;
    ResolutionType resolutionType;
    address creator;
    bool resolved;
    // 价格类专用
    string priceSymbol;        // OracleHub symbol, e.g. "ETH/USD"
    uint256 priceThreshold;    // 阈值, e.g. 3000 * 1e18
    uint256 resolutionTime;    // 结算时间点
    // 手动类专用
    address resolver;          // 有权 resolve 的地址
}

5.2 核心函数

函数	说明
createPriceMarket(question, symbol, threshold, time, collateral, outcomeCount)	创建价格类市场
createManualMarket(question, resolver, collateral, outcomeCount)	创建事件类市场
resolvePrice(marketId)	任何人调用，自动读 OracleHub 结算
resolveManual(marketId, payouts[])	仅 resolver 可调用
getMarket(marketId)	查询市场信息

5.3 OracleHub 集成

• 构造函数接收 oracleHub 地址（0x8016）和 conditionalTokens 地址

• resolvePrice 内部调用 OracleHub.getLatestPrice(symbol) 获取价格

• 价格有效性检查：staleness < 1h，否则 revert

• 价格类自动结算：price > threshold ? payouts=[1,0] : payouts=[0,1]

---

6. TypeScript SDK

6.1 包结构

sdk/
├── package.json           — @babydriver/sdk, isomorphic
├── tsconfig.json
├── src/
│   ├── index.ts           — 主入口 + re-exports
│   ├── client.ts          — BabyDriverClient (provider 管理)
│   ├── contracts/
│   │   ├── conditional-tokens.ts  — ConditionalTokens 合约交互
│   │   ├── exchange.ts            — CTFExchange 订单操作
│   │   ├── resolver.ts            — OracleResolver 市场创建/结算
│   │   └── oracle-hub.ts          — OracleHub 价格查询
│   ├── market/
│   │   ├── types.ts       — Market, Order, Position 类型定义
│   │   └── helpers.ts     — conditionId/positionId 计算, EIP-712 签名
│   ├── did/
│   │   └── did-client.ts  — DID 注册/查询/凭证 (封装 0x8017-0x8019)
│   └── abis/              — 合约 ABI JSON (编译时生成)
└── test/
    └── *.test.ts

6.2 核心 API

// 初始化
const client = new BabyDriverClient({ rpcUrl, signer? });

// 预测市场
const market = await client.markets.createPriceMarket({
  question: "ETH > $3000 by June?",
  symbol: "ETH/USD",
  threshold: 3000n * 10n**18n,
  resolutionTime: 1751328000,
  collateral: WETH_ADDRESS,
});

// 交易
await client.exchange.createOrder({
  marketId, side: "BUY", outcomeIndex: 0,
  amount: parseEther("10"), price: 0.65,
});
const orders = await client.exchange.getOrderbook(marketId);
await client.exchange.fillOrder(order, fillAmount);

// 结算 + 赎回
await client.markets.resolve(marketId);
await client.positions.redeem(marketId);

// Oracle 价格
const price = await client.oracle.getLatestPrice("ETH/USD");

// DID
await client.did.createDID(verificationMethods);
await client.did.issueCredential(subject, type, data);

6.3 技术栈

• viem — 轻量、tree-shakeable、isomorphic

• TypeScript strict mode

• vitest 测试

• tsup 打包（ESM + CJS 双输出）

6.4 不做

• React hooks（用户自己封装）

• GraphQL 索引（后续加）

• WebSocket 实时订单推送（后续加）

---

7. 测试策略

7.1 Solidity 合约测试

合约	测试文件	预计测试数
ConditionalTokens	ConditionalTokens.t.sol	~20（prepare, split, merge, redeem, payout）
CTFExchange	CTFExchange.t.sol	~25（fill, match, cancel, nonce, fees, EIP-712）
OracleResolver	OracleResolver.t.sol	~15（create, resolvePrice, resolveManual, OracleHub mock）
E2E	PredictionMarketE2E.t.sol	~5（完整生命周期）

7.2 SDK 测试

模块	测试文件	预计测试数
helpers	helpers.test.ts	~10（ID 计算、签名）
contracts	contracts.test.ts	~15（合约交互 mock）
client	client.test.ts	~5（初始化、provider）

---

8. 实现范围

做

任务	描述	预计行数
ConditionalTokens	简化版 Gnosis CTF ERC-1155	~400
CTFExchange	链上 CLOB + EIP-712	~500
OracleResolver	混合结算 + 市场工厂	~300
接口	3 个 interface 文件	~150
Foundry 测试	4 个测试文件	~800
SDK 核心	client + contracts + market + did	~600
SDK 测试	vitest	~200

不做

功能	原因
AMM / FPMM	选择了 CLOB，AMM 留后续
嵌套条件市场	复杂度高，MVP 不需要
链下 orderbook server	MVP 阶段链上 CLOB 够用
React hooks	SDK 只提供底层，用户自己封装 UI
GraphQL indexer	后续加
多 collateral	MVP 仅 WETH
Operator 代理模式	简化，直接 EOA 交易

---

9. 与现有系统的关系

系统	集成方式
OracleHub (0x8016)	OracleResolver 读取价格做自动结算
DIDRegistry (0x8017)	SDK 封装 DID 操作
CredentialRegistry (0x8018)	SDK 封装凭证操作
IdentityVerifier (0x8019)	可选：限制只有 KYC 用户可交易
FastWithdrawalPoolV2	独立，不直接集成