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.portdeveloperPublished by GitHub account portdeveloperv0.1.2Updated Oct 25, 2026
Resolve any EVM contract ABI (even unverified, via decompilation), read, simulate, prepare txs.
Resolves EVM contract ABIs (including unverified ones via decompilation), then reads, simulates and prepares unsigned transactions for signing.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.portdeveloper%2Fgulltoppr/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"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.Source: README.md at commit 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.
Takes no parameters.
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.
selectorrequiredRegistry stats
Read selector commons counts by proof grade and bytecode-match index size.
Takes no parameters.
Export selector commons
Return the CC0 selector commons as NDJSON. This can be large; prefer lookup_selector for normal agent workflows.
Takes no parameters.
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.
chainrequiredaddressrequiredrpc_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.
argschainrequiredaddressrequiredrpc_urlfunctionrequiredEncode a function call
Encode a function call to calldata (0x…) without sending anything.
argschainrequiredvalueaddressrequiredrpc_urlfunctionrequiredSimulate 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.
toargsdatafromrequiredchainrequiredvalueaddressrpc_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.
argsfromrequiredchainrequiredvalueaddressrequiredrpc_urlfunctionrequiredExplain 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.
chainrequiredrpc_urltx_hashrequiredResolve ENS/Basenames ⇄ address
Resolve an ENS/Basename to an address, or an address to its primary ENS/Basename. Pass chain=base for Basenames.
namerequiredchain90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare a license in the repository or the registry entry.
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