🐴 Gulltoppr

🐴 gulltoppr

一次真实会话：一个几秒前还在交易的未验证 MEV 机器人（没有源码，也没有任何地方提供 ABI），通过两次 MCP 工具调用解析出了完整接口。

gulltoppr 的 REST 引擎：解析阶梯 + 动词操作表面，让 AI Agent 能够从 (chain, address) 开始，完成正确、经过模拟且安全的合约交互。这是四种形态（REST → MCP → SDK → Skill）中的“引擎”；完整合约请参阅 ../SPEC.md，策略请参阅 ../IDEATION.md。

TypeScript + viem + Hono。heimdall 反编译阶梯通过 HTTP 委托给 gulltoppr（按设计在进程外运行）。

运行

npm install
npm run dev            # REST engine: tsx watch on http://localhost:8787
npm run mcp            # MCP server: stdio tools for agent clients
npm run mcp:http       # MCP server: Streamable HTTP (remote agents)
npm run typecheck      # tsc --noEmit
npm test               # vitest unit tests (cache, chains, ladder helpers, args, errors)
npm run verify         # root typecheck/test/audit + SDK build/test/audit
npm run docker:build   # build the REST engine deployment image
npm run docker:build:mcp # build the Streamable HTTP MCP deployment image
npm run docker:smoke   # start both deployment images and check health/discovery/registry metadata
npm run test:live      # opt-in live contract smoke tests (RPC/decompiler/network)

运行 npm run test:live 时设置 LIVE_ENGINE_BASE_URL=https://api.gulltoppr.dev，即可对已部署的引擎进行冒烟测试，而不是使用本地进程内服务器。定时运行的实时 GitHub Action 使用本地路径；手动触发时可以设置相同的已部署 URL。

环境变量

变量	默认值	说明
PORT	8787
HEIMDALL_API_URL	http://heimdall-api.flycast	heimdall 反编译服务（解析阶梯第 4 阶）。自 2026-07-27 起仅对 Fly 组织内部开放；在组织外运行时，请将其指向你自己的实例，否则第 4 阶将回退为仅通过 4byte 查询选择器
HEIMDALL_CONCURRENCY	2	每个进程的出站反编译/解码请求上限；0 表示禁用
HEIMDALL_QUEUE_TIMEOUT_MS	5000	gulltoppr 请求等待出站并发名额的最长时间
ENS_RPC_URL	https://ethereum-rpc.publicnode.com	用于 ENS/Basenames Universal Resolver 调用的主网 RPC；生产环境请使用私有 RPC
ETHERSCAN_API_KEY	(empty)	一个多链 v2 密钥；为空时禁用第 1 阶
ETHERSCAN_RATE_LIMIT	4	共享 Etherscan 密钥的每进程固定窗口配额；0 表示禁用
ETHERSCAN_RATE_WINDOW_SEC	1	Etherscan 配额窗口时长
SIGNING_BASE_URL	https://abi.ninja	prepare_tx 交接深层链接的基址
RATE_LIMIT	120	每个 IP 每个窗口的请求数（固定窗口）；0 表示禁用
RATE_LIMIT_WINDOW_SEC	60	速率限制窗口时长
RATE_LIMIT_ALLOW	(empty)	以逗号分隔的 IP 允许列表（免于限制）；私有 6PN IP 始终免于限制
ANTHROPIC_API_KEY	(empty)	启用注册表对反编译结果进行 LLM 提议与验证；为空时禁用
REGISTRY_LLM_MODEL	claude-opus-4-8	用于提议与验证的模型

端点（SPEC §4）

方法	路由
发现	GET / · 根发现文档，包含 REST/MCP 链接、方法、实用工具以及 prepare_tx 安全门
OpenAPI	GET /openapi.json · 面向编码 Agent 和集成的机器可读 REST 契约
Agent 指南	GET /llms.txt · 精简的大模型/编码 Agent 指南；也发布于 https://gulltoppr.dev/llms.txt
resolve_abi	GET /v1/{chain}/{address}/abi?include_abi=&method_q=&method_kind=&method_limit= · 设置 include_abi=false，即可获取精简的清单/来源信息，而不包含原始 ABI
read_contract	POST /v1/{chain}/{address}/read · 请求体 {function, args}
encode_call	POST /v1/{chain}/{address}/encode · 请求体 {function, args, value?}
simulate	POST /v1/{chain}/simulate · 请求体 {from,to,data,value?} 或 {from,address,function,args,value?}；不得混用两种格式
prepare_tx	POST /v1/{chain}/{address}/prepare · 请求体 {function, args, from, value?}
decode_tx	GET /v1/{chain}/tx/{hash}
resolve_name	GET /v1/{chain}/name/{name} · GET /v1/{chain}/name/by-address/{address}
链目录	GET /v1/chains?q=&testnets=&has_default_rpc= · 基于 viem 的别名，包含供 UI 客户端使用的 testnet/has_default_rpc 标志
注册表查询	GET /v1/lookup/{selector} · 4 字节（函数/错误）或 32 字节（事件 topic0），与链无关
注册表统计	GET /v1/registry/stats
注册表导出	GET /v1/registry/export · CC0 NDJSON 选择器公共数据集（X-License: CC0-1.0）
运行时指标	GET /v1/metrics · 进程内的阶梯/RPC 调用次数、延迟、未命中次数和失败率

GET 路由会设置明确的 Cache-Control：已验证的 ABI 响应缓存时间最长， 代理 ABI 响应的有效期较短，交易解码结果不可变，OpenAPI 契约可缓存，而 /health 和 /v1/metrics 等运维端点则使用 no-store。 受速率限制的路由在 429 响应中会提供 RateLimit-Limit、 RateLimit-Remaining、RateLimit-Reset 和 Retry-After。ABI 解析还会返回 X-Source、X-Confidence、X-Cache、X-Elapsed-Ms 和 X-ABI-Included。

注册表（selector commons）

解析过程中，engine 会将开放的 selector→signature 注册表作为副产品进行填充：

• 每次已验证的解析（Etherscan/Sourcify）都会提取函数、事件（完整的 32 字节 topic0，不会发生冲突）和错误的真实 selector → signature 配对。证明等级：verified-source。
• 解析结果还会按骨架哈希索引（剥离 solc 元数据尾部后的运行时字节码），因此字节码完全相同的克隆合约可通过新的 bytecode-match 阶段解析，无需重新执行解析流程。克隆合约的已验证声明等级最高为 partial（此地址的源代码从未经过验证），而 provenance.bytecode_match 会指向提供复用 ABI 的原始链、地址、源代码和置信度。
• 反编译得到的 ABI 中，Unresolved_<selector> 名称会被已证明的注册表条目替换；如果设置了 ANTHROPIC_API_KEY，还会触发一次无需等待结果的 提议并验证流程，请 Claude 提供候选签名，并且仅接受满足 keccak256(sig)[:4] 可还原出对应 selector 的签名：证明等级为 keccak-proven（签名已证明；语义仍为推断结果）。
• 使用前也会在本地将公开的 4byte 回退标签与 selector 匹配，但这些标签仍未经证明，绝不会作为证明写入 commons。

只有 engine 自身的流程可以写入注册表；不接受外部提交（4byte 正是因此遭到冲突污染）。

累积的数据以 CC0 数据集形式发布： evm-abi-commons （可随时通过 GET /v1/registry/export 重新生成；响应为 NDJSON，并包含 X-License: CC0-1.0 和 license Link 标头）。查询和导出条目包含证明等级；对于已知的已验证源代码条目，还会包含源代码的 chain 和 address。SDK 用户可直接调用 lookupSelector、registryStats 和 exportRegistry。

{chain} 可以是 GET /v1/chains 返回的任意别名（由 viem/chains 提供支持），也可以是数字 ID。链条目包含 testnet 和 has_default_rpc，方便 Agent 判断何时需要请求 rpc_url；q 可匹配 ID、名称、别名、原生代币符号和 bnb chain 等多词搜索。传入 ?rpc_url= 可覆盖 RPC（没有默认 RPC 的链必须传入，例如 local/31337；任何 EVM 链在获得内置别名前都可采用这种方式）。

对于 Agent 上下文，除非需要原始 JSON ABI，否则建议在 resolve_abi 中使用 include_abi=false。精简响应会保留 interface、provenance、proxy、token 和 abi_for，并标记 abi_omitted: true。对于大型合约，可添加 method_q、method_kind=read|write|all 和 method_limit，仅返回与用户意图相关的清单方法。

curl localhost:8787/v1/ethereum/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/abi
curl -X POST localhost:8787/v1/ethereum/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/prepare \
  -H 'content-type: application/json' \
  -d '{"function":"approve","args":["0x1111111254EEB25477B68fb85Ed929f73A960582","1000000000000000000"],"from":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}'

prepare_tx.safety.signing_recommended 控制是否移交交易。如果模拟失败，risk_level 为 blocked，deeplink 为空，并且会省略 wallet_request。 建议签名时，wallet_request 是符合 EIP-1193 格式的 eth_sendTransaction 载荷，使用十六进制 JSON-RPC 数量值，供钱包、区块浏览器和应用集成使用。反编译得到的写入操作或仅基于 selector 的写入操作属于 high 风险，必须由用户明确确认 selector 和意图。正向的代币/NFT spender 授权属于 medium 风险，标记为 spending_approval。从转账来源转出的代币/NFT 资产，无论是通过 trace 得出还是根据标准代币/NFT 转账推断，均属于 medium 风险，标记为 asset_outflow。客户端应在移交前同时展示这两项。

面向钱包、区块浏览器、编码 Agent 和 MCP 客户端的集成指南已发布于 docs/integrations.md。

MCP 服务（SPEC §5）

npm run mcp 会启动一个 stdio MCP 服务，提供七个核心动词，以及用于链、选择器公共数据和运行时指标的只读工具。这些工具是已部署 REST 引擎（ENGINE_URL）的轻量适配器，因此 MCP 与引擎共享持久化缓存和 Etherscan 密钥；不会重复解析或处理密钥。工具描述内置了非托管式交接模式（prepare_tx 绝不会签名），对部分、代理、字节码匹配和反编译 ABI 结果，会优先提示其来源信息；在将签名深链或钱包请求交给用户之前，必须检查 prepare_tx.safety.signing_recommended。JSON MCP 工具会公开输出架构和 structuredContent；客户端无需抓取文本，即可根据 provenance、已解码调用、模拟结果、选择器结果、指标和 safety 进行分支处理。

将其接入 MCP 客户端（Claude Desktop / Claude Code mcp 配置）：

{
  "mcpServers": {
    "gulltoppr": {
      "command": "npm",
      "args": ["run", "--silent", "mcp"],
      "cwd": "/home/ubuntu/repos/abi-agent",
      "env": { "ETHERSCAN_API_KEY": "" }
    }
  }
}

核心工具：resolve_abi、read_contract、encode_call、simulate、 prepare_tx、decode_tx、resolve_name。实用工具：list_chains、 lookup_selector、registry_stats、export_registry、runtime_metrics。除 prepare_tx 外，所有工具都标注为只读（无破坏性：返回未签名的交接信息，不会签名任何内容）。

远程（Streamable HTTP）

对于无法运行本地 stdio 服务的 Agent，同一 MCP 也通过 HTTP 托管在 **https://mcp.gulltoppr.dev/mcp**（本地运行 npm run mcp:http；无状态）。将支持 HTTP 的 MCP 客户端指向该 URL：

{ "mcpServers": { "gulltoppr": { "url": "https://mcp.gulltoppr.dev/mcp" } } }

stdio 入口（mcp.ts）和 HTTP 入口（mcp-http.ts）共用工具注册代码（src/mcp-server.ts），并通过 Dockerfile.mcp / fly.mcp.toml 部署。MCP 目录元数据位于 server.json，其中公布了相同的远程 URL、代码仓库、主页和图标。远程 MCP 服务也在 https://mcp.gulltoppr.dev/server.json 和 https://mcp.gulltoppr.dev/.well-known/mcp-server.json 提供相同的元数据。

npm SDK

sdk/ 中提供了针对该 REST 接口的类型化客户端（gulltoppr）： new Gulltoppr({ baseUrl }).resolveAbi(...) / .read(...) / .prepareTx(...)，以及 一个 contract() 辅助函数。这是第三种接入方式（继 REST 和 MCP 之后），也是钱包、区块浏览器和应用集成的基础。请参阅 sdk/README.md。

部署

已部署至 **https://api.gulltoppr.dev**（Fly.io 应用 gulltoppr，区域 cdg，与 gulltoppr 同区域部署，以尽量降低 ladder 第 4 级的延迟）。通过 Dockerfile 容器化（Node 22，使用 tsx 运行；镜像约 82 MB），由 fly.toml 配置。

flyctl deploy --remote-only --ha=false
# optional: set an Etherscan v2 key to enable ladder rung 1
flyctl secrets set ETHERSCAN_API_KEY=... -a gulltoppr

HEIMDALL_API_URL / SIGNING_BASE_URL / PORT 在 fly.toml [env] 中设置。 机器在空闲时自动停止，并在收到请求时自动启动。

Claude Skill

第四种接入方式：Claude Skill（skill/gulltoppr/），用于向 Agent 讲解工作流（解析 → 检查来源信息 → 读取或准备 → 模拟 → 交接）和非托管安全规则。使用 cp -r skill/gulltoppr ~/.claude/skills/gulltoppr 安装。请参阅 skill/README.md。

目录结构

src/
  server.ts        REST routes (Hono), BigInt-safe JSON, error mapping
  index.ts         REST entry / boot
  mcp.ts           MCP server (stdio): core verbs plus read-only utility tools
  config.ts        env + defaults
  metrics.ts       in-process rung/RPC latency and failure counters
  chains.ts        alias/id → {id, viem chain, rpc}  (SPEC §6)
  clients.ts       cached viem PublicClients
  types.ts         the SPEC §2 data types
  errors.ts        typed ApiError → HTTP status  (SPEC §7)
  resolve/
    index.ts       resolve_abi: the ladder orchestrator (the spine)
    etherscan.ts   rung 1  · sourcify.ts rung 2 · proxy.ts rung 3
    heimdall.ts    rung 4 (gulltoppr) · fourbyte.ts rung 5
    interface.ts   capability manifest builder ("the buttons", SPEC §2.4a)
    selectFunction.ts  name/signature → AbiFunction
  verbs/
    read.ts encode.ts simulate.ts prepare.ts decodeTx.ts resolveName.ts
    args.ts        JSON-arg → viem-typed coercion

状态

端到端可用（已通过实时主网验证）：完整 ladder、能力清单、read_contract、encode_call、prepare_tx（包含 eth_call 模拟 + 深链/钱包交接 + 来源信息警告）、decode_tx（通过 gulltoppr，并可选用已解析 ABI 补充 calldata 信息），以及支持链感知的 ENS/Basenames resolve_name，均通过 REST 接口和 MCP 服务公开（已验证 stdio 握手、核心工具/实用工具，以及实时工具调用）。实时冒烟测试还覆盖了代理、未验证的反编译结果、任意 rpc_url 链、Monad、Monad 测试网和 prepare_tx。

尽力而为的注意事项：

• simulate 跟踪信息：state_diff 来自 debug_traceCall （prestateTracer diff 模式）；当 RPC 支持这些 debug API 时，asset_changes/logs 来自 callTracer；公共 RPC 通常会返回空数组。