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
io.github.portdeveloper由 GitHub 帳號 portdeveloper 發布v0.1.2更新於 Oct 25, 2026
Resolve any EVM contract ABI (even unverified, via decompilation), read, simulate, prepare txs.
解析 EVM 合約 ABI(未驗證合約可透過反編譯),並支援讀取、模擬與準備待簽名的未簽署交易。
Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。
把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式,或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南,先向你展示發布者、端點和登入方式,經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。
閱讀 https://sourceweft.com/mcp/io.github.portdeveloper%2Fgulltoppr/install.md,並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前,先告訴我它的發布者、端點和登入方式,等我確認。不要把 API 金鑰寫進命令或我會提交的檔案;問我金鑰應從哪裡取得。把它新增到你客戶端的 mcpServers 設定中。
{
"mcpServers": {
"gulltoppr": {
"type": "http",
"url": "https://mcp.gulltoppr.dev/mcp"
}
}
}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).
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.
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 engine seeds an open selector→signature registry as a byproduct of resolution:
selector → signature pairs for functions, events (full 32-byte topic0,
collision-free), and errors. Proof grade: verified-source.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.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).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.
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.
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):
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).
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:
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.
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.
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.
HEIMDALL_API_URL / SIGNING_BASE_URL / PORT are set in fly.toml [env].
Machines auto-stop when idle and auto-start on request.
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.
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
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_rpcRuntime metrics
Read process-local resolver/rung/RPC counters for smoke checks and reliability dashboards.
無需輸入參數。
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
Read selector commons counts by proof grade and bytecode-match index size.
無需輸入參數。
Export selector commons
Return the CC0 selector commons as NDJSON. This can be large; prefer lookup_selector for normal agent workflows.
無需輸入參數。
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_limitRead 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 a function call
Encode a function call to calldata (0x…) without sending anything.
argschain必填valueaddress必填rpc_urlfunction必填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_urlfunctionPrepare 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必填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 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已滿足適用檢查項的 90%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
請在儲存庫或註冊中心條目中宣告授權條款。
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)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"}'{ "mcpServers": { "gulltoppr": { "command": "npm", "args": ["run", "--silent", "mcp"], "cwd": "/home/ubuntu/repos/abi-agent", "env": { "ETHERSCAN_API_KEY": "" } } }}{ "mcpServers": { "gulltoppr": { "url": "https://mcp.gulltoppr.dev/mcp" } } }flyctl deploy --remote-only --ha=false# optional: set an Etherscan v2 key to enable ladder rung 1flyctl secrets set ETHERSCAN_API_KEY=... -a gulltopprsrc/ 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