@catalyst-team/poly-sdk 0.1.0

package/docs/e2e/01-trader-tools.md

@@ -0,0 +1,159 @@
+# Trader Tools E2E Test
+
+> 交易者分析工具端到端测试
+
+---
+
+## 工具清单
+
+| 工具 | 功能 | 认证 | 优先级 |
+|------|------|------|--------|
+| `get_leaderboard` | 获取 PnL 排行榜 | 无 | P1 |
+| `get_trader_profile` | 获取交易者资料 | 无 | P1 |
+| `get_trader_positions` | 获取持仓和 PnL | 无 | P0 |
+| `get_trader_trades` | 获取交易历史 | 无 | P1 |
+
+---
+
+## Test Case 1: get_leaderboard
+
+### 1.1 默认参数
+```
+调用: get_leaderboard()
+预期: 返回 10 个交易者，按 PnL 排序
+验证:
+- traders 数组长度 = 10
+- 每个 trader 有 rank, address, pnl, volume
+- rank 从 1 开始递增
+```
+
+### 1.2 自定义 limit
+```
+调用: get_leaderboard(limit=5)
+预期: 返回 5 个交易者
+验证:
+- traders 数组长度 = 5
+```
+
+### 1.3 分页测试
+```
+调用: get_leaderboard(limit=5, offset=5)
+预期: 返回第 6-10 名交易者
+验证:
+- 第一个 trader 的 rank = 6
+- 与 offset=0 的结果不重叠
+```
+
+---
+
+## Test Case 2: get_trader_profile
+
+### 2.1 有效地址
+```
+前置: 从 leaderboard 获取一个地址
+调用: get_trader_profile(address=<top_trader>)
+预期: 返回完整的交易者资料
+验证:
+- trader.address 匹配
+- ranking.rank 存在
+- performance.officialPnl 存在
+- stats.positionCount >= 0
+```
+
+### 2.2 无效地址
+```
+调用: get_trader_profile(address="0x0000000000000000000000000000000000000000")
+预期: 返回空数据或错误
+验证:
+- 错误信息清晰
+```
+
+---
+
+## Test Case 3: get_trader_positions
+
+### 3.1 有持仓的交易者
+```
+前置: 从 leaderboard 获取顶级交易者
+调用: get_trader_positions(address=<top_trader>)
+预期: 返回持仓列表和汇总
+验证:
+- positions 是数组
+- 每个 position 有 market, holding, pnl
+- summary.totalPositions 匹配 positions.length
+- unrealizedPnl 和 realizedPnl 有值
+```
+
+### 3.2 无持仓的地址
+```
+调用: get_trader_positions(address=<new_address>)
+预期: 返回空持仓列表
+验证:
+- positions = []
+- summary.totalPositions = 0
+```
+
+---
+
+## Test Case 4: get_trader_trades
+
+### 4.1 默认参数
+```
+前置: 从 leaderboard 获取活跃交易者
+调用: get_trader_trades(address=<active_trader>)
+预期: 返回最近 20 笔交易
+验证:
+- trades 数组长度 <= 20
+- 每笔交易有 side, outcome, size, price, timestamp
+- 按时间倒序排列
+```
+
+### 4.2 过滤 BUY
+```
+调用: get_trader_trades(address=<trader>, side="BUY")
+预期: 只返回买入交易
+验证:
+- 所有 trade.side = "BUY"
+```
+
+### 4.3 过滤 SELL
+```
+调用: get_trader_trades(address=<trader>, side="SELL")
+预期: 只返回卖出交易
+验证:
+- 所有 trade.side = "SELL"
+```
+
+### 4.4 自定义 limit
+```
+调用: get_trader_trades(address=<trader>, limit=5)
+预期: 返回 5 笔交易
+验证:
+- trades.length <= 5
+```
+
+---
+
+## 执行记录
+
+| Test Case | 状态 | 结果 | 备注 |
+|-----------|------|------|------|
+| 1.1 get_leaderboard 默认 | - | - | - |
+| 1.2 get_leaderboard limit | - | - | - |
+| 1.3 get_leaderboard 分页 | - | - | - |
+| 2.1 get_trader_profile 有效 | - | - | - |
+| 2.2 get_trader_profile 无效 | - | - | - |
+| 3.1 get_trader_positions 有持仓 | - | - | - |
+| 3.2 get_trader_positions 无持仓 | - | - | - |
+| 4.1 get_trader_trades 默认 | - | - | - |
+| 4.2 get_trader_trades BUY | - | - | - |
+| 4.3 get_trader_trades SELL | - | - | - |
+| 4.4 get_trader_trades limit | - | - | - |
+
+---
+
+## 发现的问题
+
+| ID | 问题描述 | 严重性 | 状态 |
+|----|---------|--------|------|
+| - | - | - | - |

package/docs/e2e/02-market-tools.md

@@ -0,0 +1,180 @@
+# Market Tools E2E Test
+
+> 市场查询工具端到端测试
+
+---
+
+## 工具清单
+
+| 工具 | 功能 | 认证 | 优先级 |
+|------|------|------|--------|
+| `search_markets` | 搜索市场 | 无 | P1 |
+| `get_trending_markets` | 趋势市场 | 无 | P3 |
+| `get_market` | 市场详情 | 无 | P0 |
+| `get_market_trades` | 市场成交 | 无 | P1 |
+
+---
+
+## Test Case 1: search_markets
+
+### 1.1 热门关键词搜索
+```
+调用: search_markets(query="Trump")
+预期: 返回与 Trump 相关的市场
+验证:
+- markets 是数组
+- 每个市场的 question 或 slug 包含搜索词
+- 按 volume 排序
+```
+
+### 1.2 技术关键词搜索
+```
+调用: search_markets(query="Bitcoin")
+预期: 返回加密货币相关市场
+验证:
+- 结果与 Bitcoin/BTC 价格预测相关
+```
+
+### 1.3 active 过滤
+```
+调用: search_markets(query="2024", active=false)
+预期: 包含已结束的市场
+验证:
+- 可能返回已关闭的 2024 年市场
+```
+
+### 1.4 limit 参数
+```
+调用: search_markets(query="election", limit=3)
+预期: 最多返回 3 个市场
+验证:
+- markets.length <= 3
+```
+
+---
+
+## Test Case 2: get_trending_markets
+
+### 2.1 按交易量排序
+```
+调用: get_trending_markets(sortBy="volume")
+预期: 返回高交易量市场
+验证:
+- markets 按 volume24h 降序排列
+```
+
+### 2.2 按流动性排序
+```
+调用: get_trending_markets(sortBy="liquidity")
+预期: 返回高流动性市场
+验证:
+- 返回的市场流动性较高
+```
+
+### 2.3 最新市场
+```
+调用: get_trending_markets(sortBy="newest")
+预期: 返回最近创建的市场
+验证:
+- 按创建时间排序
+```
+
+### 2.4 自定义数量
+```
+调用: get_trending_markets(limit=5)
+预期: 返回 5 个市场
+验证:
+- markets.length = 5
+```
+
+---
+
+## Test Case 3: get_market
+
+### 3.1 使用 slug
+```
+调用: get_market(identifier="presidential-election-winner-2024")
+预期: 返回完整市场信息
+验证:
+- market.slug 匹配
+- prices.yes + prices.no ≈ 1.0
+- tokens.yes 和 tokens.no 都有 tokenId
+- status 字段存在
+```
+
+### 3.2 使用 conditionId
+```
+前置: 从 search_markets 获取一个 conditionId
+调用: get_market(identifier=<conditionId>)
+预期: 返回同样的市场信息
+验证:
+- 与使用 slug 返回的数据一致
+```
+
+### 3.3 无效标识符
+```
+调用: get_market(identifier="invalid-slug-12345")
+预期: 返回错误
+验证:
+- 错误信息清晰说明市场不存在
+```
+
+---
+
+## Test Case 4: get_market_trades
+
+### 4.1 热门市场成交
+```
+前置: 获取一个高交易量市场的 conditionId
+调用: get_market_trades(conditionId=<id>)
+预期: 返回最近成交
+验证:
+- trades 是数组
+- 每笔交易有 trader, side, outcome, size, price, timestamp
+- 按时间倒序
+```
+
+### 4.2 自定义数量
+```
+调用: get_market_trades(conditionId=<id>, limit=5)
+预期: 返回 5 笔成交
+验证:
+- trades.length <= 5
+```
+
+### 4.3 冷门市场
+```
+调用: get_market_trades(conditionId=<low_volume_market>)
+预期: 返回较少或空的成交
+验证:
+- 即使没有成交也不报错
+```
+
+---
+
+## 执行记录
+
+| Test Case | 状态 | 结果 | 备注 |
+|-----------|------|------|------|
+| 1.1 search_markets Trump | - | - | - |
+| 1.2 search_markets Bitcoin | - | - | - |
+| 1.3 search_markets active=false | - | - | - |
+| 1.4 search_markets limit | - | - | - |
+| 2.1 trending volume | - | - | - |
+| 2.2 trending liquidity | - | - | - |
+| 2.3 trending newest | - | - | - |
+| 2.4 trending limit | - | - | - |
+| 3.1 get_market slug | - | - | - |
+| 3.2 get_market conditionId | - | - | - |
+| 3.3 get_market invalid | - | - | - |
+| 4.1 market_trades 热门 | - | - | - |
+| 4.2 market_trades limit | - | - | - |
+| 4.3 market_trades 冷门 | - | - | - |
+
+---
+
+## 发现的问题
+
+| ID | 问题描述 | 严重性 | 状态 |
+|----|---------|--------|------|
+| - | - | - | - |

package/docs/e2e/03-order-tools.md

@@ -0,0 +1,166 @@
+# Order Tools E2E Test
+
+> 订单簿分析工具端到端测试
+
+---
+
+## 工具清单
+
+| 工具 | 功能 | 认证 | 优先级 |
+|------|------|------|--------|
+| `get_orderbook` | 获取订单簿深度 | 无 | P0 |
+| `get_best_prices` | 获取最优价格 | 无 | P1 |
+| `estimate_execution` | 估算执行成本 | 无 | P3 |
+
+---
+
+## Test Case 1: get_orderbook
+
+### 1.1 Yes 方向订单簿
+```
+前置: 获取一个活跃市场的 conditionId
+调用: get_orderbook(conditionId=<id>, outcome="Yes")
+预期: 返回 Yes 方向的订单簿
+验证:
+- orderbook.bids 存在且是数组
+- orderbook.asks 存在且是数组
+- 每个价格级有 price, size, total
+- bids 按价格降序，asks 按价格升序
+- summary.bestBid <= summary.bestAsk
+```
+
+### 1.2 No 方向订单簿
+```
+调用: get_orderbook(conditionId=<id>, outcome="No")
+预期: 返回 No 方向的订单簿
+验证:
+- 数据结构与 Yes 方向一致
+- Yes.bestBid + No.bestBid ≈ 1.0 (套利检查)
+```
+
+### 1.3 自定义深度
+```
+调用: get_orderbook(conditionId=<id>, outcome="Yes", depth=5)
+预期: 返回 5 个价格级
+验证:
+- bids.length <= 5
+- asks.length <= 5
+```
+
+### 1.4 深度 = 20
+```
+调用: get_orderbook(conditionId=<id>, outcome="Yes", depth=20)
+预期: 返回更多价格级
+验证:
+- 如果市场流动性足够，返回更多级别
+```
+
+---
+
+## Test Case 2: get_best_prices
+
+### 2.1 双向最优价格
+```
+前置: 获取一个活跃市场的 conditionId
+调用: get_best_prices(conditionId=<id>)
+预期: 返回 Yes 和 No 的最优价格
+验证:
+- yes.bestBid, yes.bestAsk 存在
+- no.bestBid, no.bestAsk 存在
+- yes.spread = yes.bestAsk - yes.bestBid
+- no.spread = no.bestAsk - no.bestBid
+```
+
+### 2.2 价格一致性验证
+```
+前置: 同时调用 get_orderbook(Yes) 和 get_best_prices
+验证:
+- get_best_prices.yes.bestBid = get_orderbook(Yes).summary.bestBid
+- get_best_prices.yes.bestAsk = get_orderbook(Yes).summary.bestAsk
+```
+
+### 2.3 套利空间检查
+```
+验证:
+- yes.bestBid + no.bestAsk 是否 > 1.0 (卖出套利)
+- yes.bestAsk + no.bestBid 是否 < 1.0 (买入套利)
+- 记录发现的套利机会
+```
+
+---
+
+## Test Case 3: estimate_execution
+
+### 3.1 小额买入估算
+```
+前置: 获取一个活跃市场
+调用: estimate_execution(conditionId=<id>, outcome="Yes", side="BUY", amount=100)
+预期: 估算 $100 买入 Yes 的成本
+验证:
+- estimate.avgPrice 存在
+- estimate.sharesReceived 存在
+- estimate.priceImpact 较小 (< 1%)
+```
+
+### 3.2 大额买入估算
+```
+调用: estimate_execution(conditionId=<id>, outcome="Yes", side="BUY", amount=1000)
+预期: 估算 $1000 买入的成本
+验证:
+- priceImpact 比小额大
+- avgPrice 比小额高
+- 可能有 warning 字段
+```
+
+### 3.3 超大额买入
+```
+调用: estimate_execution(conditionId=<id>, outcome="Yes", side="BUY", amount=10000)
+预期: 显示高滑点警告
+验证:
+- priceImpact > 5%
+- warning 字段存在
+```
+
+### 3.4 卖出估算
+```
+调用: estimate_execution(conditionId=<id>, outcome="Yes", side="SELL", amount=500)
+预期: 估算卖出成本
+验证:
+- avgPrice 存在
+- 卖出价格通常低于买入价格
+```
+
+### 3.5 No 方向估算
+```
+调用: estimate_execution(conditionId=<id>, outcome="No", side="BUY", amount=500)
+预期: 估算 No 方向买入
+验证:
+- 数据结构一致
+```
+
+---
+
+## 执行记录
+
+| Test Case | 状态 | 结果 | 备注 |
+|-----------|------|------|------|
+| 1.1 orderbook Yes | - | - | - |
+| 1.2 orderbook No | - | - | - |
+| 1.3 orderbook depth=5 | - | - | - |
+| 1.4 orderbook depth=20 | - | - | - |
+| 2.1 best_prices 双向 | - | - | - |
+| 2.2 best_prices 一致性 | - | - | - |
+| 2.3 套利空间检查 | - | - | - |
+| 3.1 estimate 小额 | - | - | - |
+| 3.2 estimate 大额 | - | - | - |
+| 3.3 estimate 超大额 | - | - | - |
+| 3.4 estimate 卖出 | - | - | - |
+| 3.5 estimate No | - | - | - |
+
+---
+
+## 发现的问题
+
+| ID | 问题描述 | 严重性 | 状态 |
+|----|---------|--------|------|
+| - | - | - | - |

package/docs/e2e/04-wallet-tools.md

@@ -0,0 +1,224 @@
+# Wallet Tools E2E Test
+
+> 钱包管理工具端到端测试
+
+---
+
+## 工具清单
+
+| 工具 | 功能 | 认证 | 优先级 |
+|------|------|------|--------|
+| `get_supported_deposit_assets` | 支持的充值资产 | 无 | P1 |
+| `get_wallet_balances` | 查询任意钱包余额 | 无 | P1 |
+| `get_deposit_addresses` | 获取充值地址 | 私钥 | P1 |
+| `get_token_balances` | 获取自己的余额 | 私钥 | P1 |
+| `check_allowances` | 检查授权状态 | 私钥 | P1 |
+| `approve_trading` | 授权交易合约 | 私钥 | P2 |
+| `swap` | 代币交换 | 私钥 | P2 |
+| `swap_and_deposit` | 交换并充值 | 私钥 | P2 |
+| `deposit_usdc` | 充值 USDC | 私钥 | P2 |
+
+---
+
+## Phase A: 只读工具 (无需认证)
+
+### Test Case 1: get_supported_deposit_assets
+
+#### 1.1 列出所有资产
+```
+调用: get_supported_deposit_assets()
+预期: 返回所有支持的链和资产
+验证:
+- assets 是数组
+- 包含多个链 (Ethereum, Polygon, Arbitrum, Base, Solana, Bitcoin)
+- 每个资产有 chainId, chainName, tokenSymbol, minDeposit
+```
+
+#### 1.2 按链过滤
+```
+调用: get_supported_deposit_assets(chainId=137)
+预期: 只返回 Polygon 链的资产
+验证:
+- 所有资产的 chainId = 137
+```
+
+---
+
+### Test Case 2: get_wallet_balances
+
+#### 2.1 查询主钱包
+```
+调用: get_wallet_balances(address="0x0F5988a267303f46b50912f176450491DF10476f")
+预期: 返回钱包的代币余额
+验证:
+- balances 包含 MATIC, USDC, USDC_E 等
+- nonZeroBalances 只包含有余额的代币
+```
+
+#### 2.2 查询顶级交易者钱包
+```
+前置: 从 leaderboard 获取一个地址
+调用: get_wallet_balances(address=<top_trader>)
+预期: 返回该钱包的余额
+验证:
+- 数据结构一致
+```
+
+#### 2.3 空钱包
+```
+调用: get_wallet_balances(address="0x0000000000000000000000000000000000000001")
+预期: 返回全零余额
+验证:
+- 所有余额 = 0
+- nonZeroBalances = []
+```
+
+---
+
+## Phase B: 需要私钥的工具
+
+> 注意: 如果环境未配置私钥，这些测试将被跳过
+
+### Test Case 3: get_deposit_addresses
+
+#### 3.1 获取充值地址
+```
+调用: get_deposit_addresses()
+预期: 返回所有链的充值地址
+验证:
+- addresses.evm 是有效的以太坊地址
+- addresses.solana 是有效的 Solana 地址 (如果支持)
+- addresses.bitcoin 是有效的 BTC 地址 (如果支持)
+```
+
+---
+
+### Test Case 4: get_token_balances
+
+#### 4.1 获取自己的余额
+```
+调用: get_token_balances()
+预期: 返回配置钱包的余额
+验证:
+- wallet 地址与配置一致
+- balances 包含所有支持的代币
+```
+
+---
+
+### Test Case 5: check_allowances
+
+#### 5.1 检查授权状态
+```
+调用: check_allowances()
+预期: 返回所有合约的授权状态
+验证:
+- erc20Allowances 包含 CTF Exchange, Neg Risk Exchange 等
+- erc1155Approvals 包含 Conditional Tokens
+- tradingReady 表示是否可以交易
+- issues 列出未授权的合约
+```
+
+---
+
+### Test Case 6: approve_trading (危险操作)
+
+> 警告: 此测试会产生链上交易，消耗 Gas
+
+#### 6.1 授权所有合约
+```
+前置条件:
+- 确认钱包有足够的 MATIC 支付 Gas
+- 确认这是测试环境或用户明确同意
+
+调用: approve_trading()
+预期: 授权所有必要的合约
+验证:
+- 所有授权交易成功
+- check_allowances 显示 tradingReady = true
+```
+
+---
+
+### Test Case 7: swap (危险操作)
+
+> 警告: 此测试会产生链上交易
+
+#### 7.1 MATIC -> USDC 小额交换
+```
+前置: 确认钱包有足够 MATIC
+调用: swap(tokenIn="MATIC", tokenOut="USDC", amount="0.1")
+预期: 成功交换
+验证:
+- txHash 存在
+- amountOut > 0
+```
+
+---
+
+### Test Case 8: swap_and_deposit (危险操作)
+
+> 此测试通常跳过，除非明确需要测试
+
+---
+
+### Test Case 9: deposit_usdc (危险操作)
+
+> 此测试通常跳过，除非明确需要测试
+
+---
+
+## 执行记录
+
+### Phase A (只读) - 2025-12-23
+
+| Test Case | 状态 | 结果 | 备注 |
+|-----------|------|------|------|
+| 1.1 supported_assets 全部 | ✅ PASS | 返回 6 链 47 资产 | 包含 Ethereum, Polygon, Base, Arbitrum, Optimism, Solana |
+| 1.2 supported_assets 按链 | ✅ PASS | Polygon: 7 资产 | chainId=137 过滤正常 |
+| 2.1 wallet_balances 主钱包 | ✅ PASS | 返回所有代币余额 | 0x0F5988... 查询成功 |
+| 2.2 wallet_balances 交易者 | ✅ PASS | Top trader 余额正常 | 从 leaderboard 获取地址 |
+| 2.3 wallet_balances 空钱包 | ✅ PASS | 全零余额 | nonZeroBalances = [] |
+
+### Phase B (需要私钥) - 2025-12-23
+
+| Test Case | 状态 | 结果 | 备注 |
+|-----------|------|------|------|
+| 3.1 deposit_addresses | ⚠️ SKIPPED | - | AUTH_REQUIRED (需要私钥) |
+| 4.1 token_balances | ⚠️ SKIPPED | - | AUTH_REQUIRED (需要私钥) |
+| 5.1 check_allowances | ✅ PASS | 7 项缺失授权 | 钱包 0xed1050... |
+| 6.1 approve_trading | ✅ PASS | 7 项授权成功 | 全部 ERC20+ERC1155 |
+| 7.1 swap MATIC→USDC | ✅ PASS | 20 MATIC → 7.5 USDC | QuickSwap V3 |
+| 7.2 swap WMATIC→USDC_E | ❌ FAIL | 无直接池 | 需用 deposit 替代 |
+| 8.x swap_and_deposit | ⚠️ SKIPPED | 用分步替代 | - |
+| 9.x deposit_usdc | ✅ PASS | 7 USDC → 6.99 USDC.e | Bridge 1-5分钟 |
+
+---
+
+## 发现的问题
+
+| ID | 问题描述 | 严重性 | 状态 |
+|----|---------|--------|------|
+| 5 | approve_trading: signer.provider 为 null | High | ✅ FIXED |
+| 6 | swap/get_token_balances: signer.provider 为 null | High | ✅ FIXED |
+
+### 问题修复详情 (2025-12-23)
+
+**Issue #5 & #6 - Provider 未初始化**
+
+- **问题**: SDK 返回的 signer 没有 provider 属性，导致 SwapService 和 AuthorizationService 无法执行链上查询
+- **根因**: `getSignerFromSdk()` 直接返回 signer，未检查是否有 provider 连接
+- **修复**:
+  1. `swap-service.ts`: 添加 provider 回退逻辑
+     ```typescript
+     this.provider = signer.provider || new ethers.providers.JsonRpcProvider('https://polygon-rpc.com');
+     this.signer = signer.provider ? signer : signer.connect(this.provider);
+     ```
+  2. `wallet.ts`: 在 `getSignerFromSdk()` 中确保 signer 连接到 provider
+     ```typescript
+     if (!signer.provider) {
+       const provider = new ethers.providers.JsonRpcProvider(POLYGON_RPC);
+       return signer.connect(provider);
+     }
+     ```
+- **验证**: 需要重启 MCP Server 以加载新代码