🐴 Gulltoppr

io.github.portdeveloper由 GitHub 账号 portdeveloper 发布v0.1.2更新于 Oct 25, 2026

Resolve any EVM contract ABI (even unverified, via decompilation), read, simulate, prepare txs.

已验证Streamable HTTP可网页运行金融开发者工具

概览

AI 生成的概览

解析 EVM 合约 ABI(未验证合约可通过反编译),并支持读取、模拟与准备待签名的未签名交易。

可以做什么
  • 按链与地址解析合约接口,返回来源证明、代理链与代币元数据
  • 读取 view 函数,并把函数调用编码为 calldata,无需钱包
  • 模拟调用,返回成功与否、gas、解码结果及尽力而为的状态差异
  • 准备未签名的写入交易,附模拟结果、安全警告与签名交接信息
  • 解码交易,并在 ENS/Basename 与地址之间互相解析
  • 列出链、查询选择器、查看注册表统计并导出选择器注册表
适用场景
适合在助手需要查看或操作没有 ABI 的 EVM 合约(包括未验证或克隆合约)时使用,也适合希望先模拟、再以非托管方式把交易交给用户签名,而不是盲目签名的场景。
运行要求
可使用 mcp.gulltoppr.dev 的远程 Streamable HTTP 端点,或本地安装 Node.js 后以 stdio 运行。链上访问依赖 RPC 端点,没有默认 RPC 的链需提供 rpc_url。托管端点无需账号或密钥。
安装前请注意
prepare_tx 返回未签名交易以及签名深链和钱包请求,本身不签名也不广播,但最终仍由用户签名。反编译或仅有选择器的写入被标为高风险,授权与资产流出被标为中风险,交接前应查看安全元数据与来源证明。模拟得到的状态差异与日志为尽力而为,公共 RPC 上常为空。

安装

在 SourceWeft 中

  1. 打开 控制台中的 🐴 Gulltoppr,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable,通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体,或 SourceWeft 对话中。智能体会读取该服务器的安装指南,先向你展示发布者、端点和登录方式,经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.portdeveloper%2Fgulltoppr/install.md,并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前,先告诉我它的发布者、端点和登录方式,等我确认。不要把 API 密钥写进命令或我会提交的文件;问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

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

README

🐴 gulltoppr

[An agent resolving a live unverified MEV bot via gulltoppr: decompiled ABI, provenance warning, registry-proven name, live read]

A real session: an unverified MEV bot that traded seconds earlier (no source, no ABI anywhere) resolved to a full interface in two MCP tool calls.

The REST engine for gulltoppr: the resolution ladder + verb surface that lets an AI agent go from (chain, address) to a correct, simulated, safe contract interaction. This is "the engine" of the four faces (REST → MCP → SDK → Skill); see ../SPEC.md for the full contract and ../IDEATION.md for the strategy.

TypeScript + viem + Hono. The heimdall decompile rung is delegated over HTTP to gulltoppr (kept out-of-process by design).

Run

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

Set LIVE_ENGINE_BASE_URL=https://api.gulltoppr.dev with npm run test:live to smoke a deployed engine instead of the local in-process server. The scheduled live GitHub Action runs the local path; manual dispatch can set the same deployed URL.

Env

vardefaultnotes
PORT8787
HEIMDALL_API_URLhttp://heimdall-api.flycastheimdall decompile service (ladder rung 4). Private to the Fly org since 2026-07-27 — point this at your own instance when running outside it, or rung 4 falls back to selector-only via 4byte
HEIMDALL_CONCURRENCY2per-process cap on outbound decompile/decode requests; 0 disables
HEIMDALL_QUEUE_TIMEOUT_MS5000max time a gulltoppr request can wait for an outbound concurrency slot
ENS_RPC_URLhttps://ethereum-rpc.publicnode.commainnet RPC for ENS/Basenames Universal Resolver calls; use a private RPC in production
ETHERSCAN_API_KEY(empty)one multichain v2 key; empty disables rung 1
ETHERSCAN_RATE_LIMIT4per-process fixed-window budget for the shared Etherscan key; 0 disables
ETHERSCAN_RATE_WINDOW_SEC1Etherscan budget window length
SIGNING_BASE_URLhttps://abi.ninjabase for prepare_tx hand-off deeplinks
RATE_LIMIT120per-IP requests per window (fixed window); 0 disables
RATE_LIMIT_WINDOW_SEC60rate-limit window length
RATE_LIMIT_ALLOW(empty)comma-separated IP allowlist (exempt); private 6PN IPs are always exempt
ANTHROPIC_API_KEY(empty)enables the registry's LLM propose-and-verify pass on decompiles; empty disables
REGISTRY_LLM_MODELclaude-opus-4-8model for propose-and-verify

Endpoints (SPEC §4)

verbroute
discoveryGET / · root discovery document with REST/MCP links, verbs, utility tools, and the prepare_tx safety gate
OpenAPIGET /openapi.json · machine-readable REST contract for coding agents and integrations
agent guideGET /llms.txt · compact LLM/coding-agent guide; also published at https://gulltoppr.dev/llms.txt
resolve_abiGET /v1/{chain}/{address}/abi?include_abi=&method_q=&method_kind=&method_limit= · set include_abi=false for compact manifest/provenance without raw ABI
read_contractPOST /v1/{chain}/{address}/read · body {function, args}
encode_callPOST /v1/{chain}/{address}/encode · body {function, args, value?}
simulatePOST /v1/{chain}/simulate · body {from,to,data,value?} or {from,address,function,args,value?}; never mix both forms
prepare_txPOST /v1/{chain}/{address}/prepare · body {function, args, from, value?}
decode_txGET /v1/{chain}/tx/{hash}
resolve_nameGET /v1/{chain}/name/{name} · GET /v1/{chain}/name/by-address/{address}
chain catalogGET /v1/chains?q=&testnets=&has_default_rpc= · viem-backed aliases with testnet/has_default_rpc flags for UI clients
registry lookupGET /v1/lookup/{selector} · 4-byte (function/error) or 32-byte (event topic0), chain-independent
registry statsGET /v1/registry/stats
registry exportGET /v1/registry/export · CC0 NDJSON selector commons (X-License: CC0-1.0)
runtime metricsGET /v1/metrics · in-process rung/RPC attempts, latency, misses, and failure rates

GET routes set explicit Cache-Control: verified ABI responses cache longest, proxy ABI responses are short-lived, transaction decodes are immutable, the OpenAPI contract is cacheable, and operational endpoints such as /health and /v1/metrics are no-store. Rate-limited routes expose RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and Retry-After on 429 responses. ABI resolves also return X-Source, X-Confidence, X-Cache, X-Elapsed-Ms, and X-ABI-Included.

The registry (selector commons)

The engine seeds an open selector→signature registry as a byproduct of resolution:

  • Every verified resolution (Etherscan/Sourcify) harvests ground-truth selector → signature pairs for functions, events (full 32-byte topic0, collision-free), and errors. Proof grade: verified-source.
  • Resolutions are also indexed by skeleton hash (runtime bytecode with the solc metadata trailer stripped), so byte-identical clones resolve via a new bytecode-match rung without re-running the ladder. Verified claims are capped to partial for clones (this address's source was never verified), and provenance.bytecode_match points at the original chain/address/source/confidence that supplied the reused ABI.
  • Decompiled ABIs get Unresolved_<selector> names replaced from proven registry entries, and (when ANTHROPIC_API_KEY is set) a fire-and-forget propose-and-verify pass asks Claude for candidate signatures and accepts only those where keccak256(sig)[:4] reproduces the selector: proof grade keccak-proven (signature proven; semantics still inferred).
  • Public 4byte fallback labels are also selector-matched locally before use, but remain unproven labels and never enter the commons as proof.

Only the engine's own pipeline writes to the registry; no open submissions (that's how 4byte got collision-poisoned).

The accumulated data is published as a CC0 dataset: evm-abi-commons (regenerate any time from GET /v1/registry/export; the response is NDJSON and includes X-License: CC0-1.0 plus a license Link header). Lookup/export entries include proof grade and, for harvested verified-source entries when known, the source chain and address. SDK users can call lookupSelector, registryStats, and exportRegistry directly.

{chain} is any alias from GET /v1/chains (backed by viem/chains) or a numeric id. Chain entries include testnet and has_default_rpc so agents can decide when to ask for rpc_url; q matches ids, names, aliases, native symbols, and multi-word searches such as bnb chain. Pass ?rpc_url= to override the RPC (required for chains with no default, e.g. local/31337; this is how any EVM chain works before it has a built-in alias).

For agent contexts, prefer include_abi=false on resolve_abi unless you need the raw JSON ABI. The compact response preserves interface, provenance, proxy, token, and abi_for, and marks abi_omitted: true. For large contracts, add method_q, method_kind=read|write|all, and method_limit to return only the manifest methods relevant to the user's intent.

bash
curl localhost:8787/v1/ethereum/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/abicurl -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 gates the hand-off. If simulation fails, risk_level is blocked, deeplink is empty, and wallet_request is omitted. When signing is recommended, wallet_request is an EIP-1193-shaped eth_sendTransaction payload with hex JSON-RPC quantities for wallet/explorer/app integrations. Decompiled or selector-only writes are high risk and require explicit user confirmation of selector + intent. Positive token/NFT spender approvals are medium risk with spending_approval. Token/NFT outflows from the transfer source, whether trace-derived or inferred from a standard token/NFT transfer, are medium risk with asset_outflow. Clients should show both before hand-off.

Integration recipes for wallets, block explorers, coding agents, and MCP clients are published at docs/integrations.md.

MCP server (SPEC §5)

npm run mcp starts a stdio MCP server exposing the seven core verbs plus read-only utility tools for chains, selector commons, and runtime metrics. The tools are a thin adapter over the deployed REST engine (ENGINE_URL), so the MCP shares the engine's persistent cache and Etherscan key; no duplicated resolution or secrets. Tool descriptions bake in the non-custodial hand-off model (prepare_tx never signs), lead with provenance warnings for partial/proxy/bytecode-match/decompiled ABI results, and require prepare_tx.safety.signing_recommended before a signing deeplink or wallet request is handed to the user. JSON MCP tools expose output schemas and structuredContent; clients can branch on provenance, decoded calls, simulations, selector results, metrics, and safety without scraping text.

Wire it into an MCP client (Claude Desktop / Claude Code mcp config):

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

Core tools: resolve_abi, read_contract, encode_call, simulate, prepare_tx, decode_tx, resolve_name. Utility tools: list_chains, lookup_selector, registry_stats, export_registry, runtime_metrics. All are read-only-annotated except prepare_tx (non-destructive: returns an unsigned hand-off, signs nothing).

Remote (Streamable HTTP)

For agents that can't run a local stdio server, the same MCP is hosted over HTTP at https://mcp.gulltoppr.dev/mcp (npm run mcp:http locally; stateless). Point an HTTP-capable MCP client at that URL:

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

Tool registration is shared (src/mcp-server.ts) between the stdio entry (mcp.ts) and the HTTP entry (mcp-http.ts), deployed via Dockerfile.mcp / fly.mcp.toml. MCP directory metadata lives in server.json and advertises the same remote URL, repository, homepage, and icon. The remote MCP service also serves the same metadata at https://mcp.gulltoppr.dev/server.json and https://mcp.gulltoppr.dev/.well-known/mcp-server.json.

npm SDK

A typed client over this REST surface lives in sdk/ (gulltoppr): new Gulltoppr({ baseUrl }).resolveAbi(...) / .read(...) / .prepareTx(...), plus a contract() helper. It's the third face (after REST and MCP) and the basis for wallet, explorer, and app integrations. See sdk/README.md.

Deploy

Live at https://api.gulltoppr.dev (Fly.io app gulltoppr, region cdg, co-located with gulltoppr to minimize ladder rung-4 latency). Containerized via the Dockerfile (Node 22, run with tsx; ~82 MB image), configured by fly.toml.

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

HEIMDALL_API_URL / SIGNING_BASE_URL / PORT are set in fly.toml [env]. Machines auto-stop when idle and auto-start on request.

Claude Skill

The fourth face: a Claude Skill (skill/gulltoppr/) that teaches an agent the workflow (resolve → check provenance → read or prepare → simulate → hand off) and the non-custodial safety rules. Install with cp -r skill/gulltoppr ~/.claude/skills/gulltoppr. See skill/README.md.

Layout

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

Status

Working end-to-end (verified against live mainnet): the full ladder, the capability manifest, read_contract, encode_call, prepare_tx (with eth_call simulation + deeplink/wallet hand-off + provenance warnings), decode_tx (via gulltoppr plus optional resolved-ABI calldata enrichment), and chain-aware ENS/Basenames resolve_name, all exposed over both the REST surface and the MCP server (stdio handshake + core tools/utilities + a live tool call verified). The live smoke suite also covers proxies, unverified decompiles, arbitrary rpc_url chains, Monad, Monad testnet, and prepare_tx.

Best-effort caveats:

  • simulate traces: state_diff comes from debug_traceCall (prestateTracer diff mode) and asset_changes/logs come from callTracer when the RPC supports those debug APIs; public RPCs often return empty arrays.

来源:README.md,提交 9434ff8

工具

12

list_chains

List supported chains

List viem-backed chain aliases and ids. Use filters to find testnets, default-RPC chains, or a named chain before resolving contracts.

输入参数qtestnetshas_default_rpc

runtime_metrics

Runtime metrics

Read process-local resolver/rung/RPC counters for smoke checks and reliability dashboards.

无需输入参数。

lookup_selector

Lookup selector commons

Lookup gulltoppr-proven signatures for a 4-byte function/error selector or 32-byte event topic0. Prefer these over public 4byte guesses.

输入参数selector必填

registry_stats

Registry stats

Read selector commons counts by proof grade and bytecode-match index size.

无需输入参数。

export_registry

Export selector commons

Return the CC0 selector commons as NDJSON. This can be large; prefer lookup_selector for normal agent workflows.

无需输入参数。

resolve_abi

Resolve contract ABI

Resolve a contract's interface from chain + address via a fallback ladder (Etherscan → Sourcify → proxy → heimdall decompile → 4byte). Returns a compact capability manifest (read vs write functions, the 'buttons'), proxy chain, token metadata, and PROVENANCE. ALWAYS read `provenance`: a `decompiled` ABI has synthetic function names — treat it with care and confirm intent before writing. Partial, proxy, and bytecode-match results lead with a WARNING before the JSON. The compact manifest/provenance is also returned as structuredContent. Use method_q/method_kind/method_limit for large ABIs. Raw ABI is omitted from MCP output to save tokens; use REST/SDK resolve_abi with include_abi=true if needed.

输入参数chain必填address必填rpc_urlmethod_qmethod_kindmethod_limit

read_contract

Read a contract (view/pure)

Call a view/pure function and get the decoded result. No wallet, no cost. Rejects state-mutating functions.

输入参数argschain必填address必填rpc_urlfunction必填

encode_call

Encode a function call

Encode a function call to calldata (0x…) without sending anything.

输入参数argschain必填valueaddress必填rpc_urlfunction必填

simulate

Simulate a transaction

Simulate a call and return success, gas, decoded return, and best-effort state diff / asset changes / logs. Provide a high-level call (address + function + args) or raw (to + data), never both.

输入参数toargsdatafrom必填chain必填valueaddressrpc_urlfunction

prepare_tx

Prepare an unsigned transaction (hand-off)

Prepare a contract WRITE for the user to sign. Returns an UNSIGNED transaction, its simulation, a human-readable summary, safety metadata, warnings, a configured signing deeplink, and an EIP-1193 wallet request when signing is recommended. IMPORTANT: this tool NEVER signs or broadcasts. Present the summary + simulation + warnings to the user. Only hand them the `deeplink` or `wallet_request` when `safety.signing_recommended` is true. If `safety.risk_level` is high or blocked, make that explicit; blocked means do not send.

输入参数argsfrom必填chain必填valueaddress必填rpc_urlfunction必填

decode_tx

Explain a transaction

Decode what a transaction did: delegated heimdall decode plus `decoded_call` from the resolved target ABI when available. Prefer `decoded_call` for typed function/arg names, and read its provenance.

输入参数chain必填rpc_urltx_hash必填

resolve_name

Resolve ENS/Basenames ⇄ address

Resolve an ENS/Basename to an address, or an address to its primary ENS/Basename. Pass chain=base for Basenames.

输入参数name必填chain

版本历史

1
  1. v0.1.2最新Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分
  • 已声明认证方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

    请在仓库或注册中心条目中声明许可证。