🐴 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 分

    請在儲存庫或註冊中心條目中宣告授權條款。