grimoire-uniswap

Grimoire Uniswap 技能

使用此技能检查 Uniswap 元数据，并为 spells 生成代币／池快照。

推荐调用方式：

• grimoire venue uniswap ...
• npx -y @grimoirelabs/cli venue uniswap ...（无需安装）
• bun run packages/cli/src/index.ts venue uniswap ...（在仓库本地运行）
• grimoire-uniswap ...（来自 @grimoirelabs/venues 的独立二进制文件）

建议预检：

• grimoire venue doctor --adapter uniswap --chain 1 --rpc-url <rpc> --json

命令

• grimoire venue uniswap info — 适配器元数据
• grimoire venue uniswap routers [--chain <id>] — 各链上的路由器地址
• grimoire venue uniswap tokens [--chain <id>] [--symbol <sym>] [--address <addr>] [--source <url>] — 查询代币列表
• grimoire venue uniswap tokens-snapshot [--chain <id>] [--symbol <sym>] [--address <addr>] [--source <url>] — 为代币生成 spell 的 params: 块（仅限 Agent）
• grimoire venue uniswap pools --token0 <address|symbol> --token1 <address|symbol> [--chain <id>] [--fee <bps>] [--limit <n>] [--source <url>] [--endpoint <url>] [--graph-key <key>] [--subgraph-id <id>] [--rpc-url <url>] [--factory <address>] — 查找代币对对应的池
• grimoire venue uniswap pools-snapshot --token0 <address|symbol> --token1 <address|symbol> [--chain <id>] [--fee <bps>] [--limit <n>] [--source <url>] [--endpoint <url>] [--graph-key <key>] [--subgraph-id <id>] [--rpc-url <url>] [--factory <address>] — 为池生成 spell 的 params: 块（仅限 Agent）

池数据源

可以从 The Graph（子图）或直接从链上工厂合约获取池数据：

• 子图（设置 GRAPH_API_KEY 时为默认方式）：查询 The Graph 去中心化网络。内置子图 ID 适用于 Ethereum、Optimism、Polygon、Base 和 Arbitrum。
• RPC（回退方式）：如果没有可用的图配置，pools 会通过链上工厂查询池（提供 --rpc-url／RPC_URL 时使用该地址，否则在可用情况下使用链的默认 RPC）。
• 强制使用 RPC 模式：提供 --rpc-url，并省略 --graph-key。

环境变量

变量	描述
GRAPH_API_KEY	用于子图查询的 The Graph API 密钥（请前往 https://thegraph.com/studio/apikeys/ 获取）
RPC_URL	用于链上池查询的备用 RPC URL

示例

grimoire venue uniswap info --format table
grimoire venue uniswap routers
grimoire venue uniswap routers --chain 1
grimoire venue uniswap tokens --chain 1 --symbol USDC --format spell
grimoire venue uniswap pools --chain 1 --token0 USDC --token1 WETH --fee 3000 --format spell
grimoire venue uniswap pools --chain 8453 --token0 USDC --token1 WETH --fee 500 --rpc-url $RPC_URL --format table
grimoire venue uniswap pools --chain 8453 --token0 USDC --token1 WETH --fee 500 --graph-key $GRAPH_API_KEY --subgraph-id <id>
grimoire venue uniswap tokens-snapshot --chain 1 --symbol USDC
grimoire venue uniswap pools-snapshot --chain 1 --token0 USDC --token1 WETH --rpc-url $RPC_URL

使用 tokens-snapshot 或 pools-snapshot 输出用于 spell 输入的 params: 块。这些命令仅限 Agent 使用（交互模式下会抑制输出）。

指标范围（Spell 对比）

Uniswap V3 和 V4 提供 quote_out，用于协议对比：

v3_out = metric("quote_out", uni_v3, USDC, "asset_out=WETH,amount=1000000,fee_tier=3000")
v4_out = metric("quote_out", uni_v4, USDC, "asset_out=WETH,amount=1000000,fee_tier=3000,tick_spacing=60")

选择器字段：

• 必填：asset_out
• 可选：amount（默认为 1 个输入资产单位）、fee_tier
• V4 可选：tick_spacing

Spell 约束

在以 Uniswap 为目标的 .spell 文件中编写兑换操作时，使用 with 子句设置约束：

uniswap_v3.swap(USDC, WETH, params.amount) with (
  fee_tier=3000,
  max_slippage=50,
  min_output=900000000000000,
  deadline=300,
)

必须指定 fee_tier。 如果未指定 fee_tier，适配器会报错。它是操作参数（而非约束），并从 with() 子句中提取。

常见费率等级：500（0.05%）、3000（0.3%）、10000（1%）。

参数	类型	描述
fee_tier	整数（bps）	必填。 Uniswap 池费率等级（例如 500、3000、10000）

约束	类型	描述
max_slippage	整数（bps）	最大滑点，以基点为单位（例如 50 = 0.5%）
min_output	整数（wei）	最低输出数量下限
max_input	整数（wei）	最大输入数量上限
deadline	整数（秒）	从现在起算的交易截止时间
require_quote	布尔值	如果链上报价获取失败则报错
require_simulation	布尔值	如果模拟不可用则报错
max_gas	整数（wei）	Gas 估算上限

兑换时务必同时设置 max_slippage 和 min_output，以防意外损失。

支持的适配器

适配器	路由器	授权流程
@uniswap_v3	SwapRouter02	标准 ERC20 授权
@uniswap_v4	Universal Router	Permit2

说明

• CLI 目前提供 V3 元数据。V4 适配器可通过 createUniswapV4Adapter() 以编程方式使用。
• 查询元数据（tokens、pools）时，即使你的 spell venue 是 uniswap_v4，也请使用 grimoire venue uniswap ...。
• 输出为 JSON 或表格；tokens 和 pools 也支持 --format spell。
• 自动化和可复现快照场景下，建议使用 --format json。
• 仅提供元数据（不提供链上报价端点）。