🐴 Gulltoppr

🐴 gulltoppr

実際のセッション：数秒前に取引していた未検証の MEV ボット（ソースなし、ABI もどこにもなし）が、2 回の MCP ツール呼び出しで完全なインターフェースに解決されました。

gulltoppr の REST エンジンです。AI エージェントが (chain, address) から、正しく、シミュレーション済みで、安全なコントラクト操作へ進めるようにする解決ラダーと動詞サーフェスを提供します。これは 4 つの形態（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 つ。空の場合、段 1 は無効になります
ETHERSCAN_RATE_LIMIT	4	共有 Etherscan キーのプロセスごとの固定ウィンドウ予算。0 で無効になります
ETHERSCAN_RATE_WINDOW_SEC	1	Etherscan 予算のウィンドウ長
SIGNING_BASE_URL	https://abi.ninja	prepare_tx の引き継ぎ用ディープリンクのベース URL
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）

verb	route
discovery	GET / · REST/MCP リンク、動詞、ユーティリティツール、prepare_tx の安全ゲートを含むルートディスカバリードキュメント
OpenAPI	GET /openapi.json · コーディングエージェントおよびインテグレーション向けの機械可読な REST コントラクト
agent guide	GET /llms.txt · LLM／コーディングエージェント向けの簡潔なガイド。https://gulltoppr.dev/llms.txt でも公開されています
resolve_abi	GET /v1/{chain}/{address}/abi?include_abi=&method_q=&method_kind=&method_limit= · 生の ABI を含めず、簡潔なマニフェスト／来歴情報を取得するには include_abi=false を設定します
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= · UI クライアント向けの、testnet／has_default_rpc フラグ付き viem ベースのエイリアス
レジストリ検索	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 も返されます。

レジストリ（セレクターの共有基盤）

エンジンは解決処理の副産物として、オープンなセレクター→シグネチャレジストリを構築します。

• 検証済みの解決（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] がセレクターと一致するものだけを採用します。証明グレード：keccak-proven（シグネチャは実証済みですが、意味は推定です）。
• 公開されている4byteのフォールバックラベルも、使用前にローカルでセレクターと照合されますが、実証されていないラベルのままであり、証明として共有基盤に登録されることはありません。

レジストリに書き込めるのはエンジン独自のパイプラインだけです。一般からの登録は受け付けません（それが4byteで衝突による汚染が起きた理由です）。

蓄積されたデータはCC0データセットとして公開されています： evm-abi-commons （GET /v1/registry/export からいつでも再生成できます。レスポンスは NDJSON で、X-License: CC0-1.0 とライセンスを示す Link ヘッダーが含まれます）。検索／エクスポートのエントリには証明グレードが含まれます。また、判明している場合、収集された verified-source エントリにはソースの chain と address も含まれます。SDK のユーザーは lookupSelector、registryStats、exportRegistry を直接呼び出せます。

{chain} には、GET /v1/chains が返す任意のエイリアス（viem/chains に基づく）または数値 ID を指定できます。チェーンエントリには testnet と has_default_rpc が含まれるため、エージェントは rpc_url の指定を求めるべきかどうかを判断できます。q は ID、名前、エイリアス、ネイティブトークンのシンボルに一致し、bnb chain のような複数語の検索にも対応します。?rpc_url= を渡すと RPC を上書きできます（デフォルトがないチェーン、たとえば local／31337 では必須です。組み込みのエイリアスが用意される前の EVM チェーンでは、これを使って動作させます）。

エージェントのコンテキストでは、生の 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 は、ウォレット／ブロックエクスプローラー／アプリとの統合向けに、16進数の JSON-RPC 数量を含む EIP-1193 形式の eth_sendTransaction ペイロードです。逆コンパイルされた書き込み、またはセレクターのみの書き込みはリスクが high であり、セレクターと意図をユーザーが明示的に確認する必要があります。正のトークン／NFT 支出者承認は、spending_approval を伴うリスク medium です。トレースから導出されたものでも、標準的なトークン／NFT 転送から推定されたものでも、転送元からのトークン／NFT の流出は、asset_outflow を伴うリスク medium です。クライアントは引き渡し前に両方を表示してください。

ウォレット、ブロックエクスプローラー、コーディングエージェント、MCP クライアント向けの統合レシピは、docs/integrations.md で公開されています。

MCP サーバー（SPEC §5）

npm run mcp を実行すると、7 つのコア動詞と、チェーン、セレクターの共通情報、ランタイムメトリクス用の読み取り専用ユーティリティツールを公開する stdio MCP サーバーが起動します。ツールはデプロイ済みの REST エンジン（ENGINE_URL）を薄くラップするため、MCP はエンジンの永続キャッシュと Etherscan キーを共有し、解決処理やシークレットが重複することはありません。ツールの説明には、カストディを伴わない引き渡しモデル（prepare_tx は署名しません）が明記されています。また、部分的な ABI、プロキシ、バイトコード照合、逆コンパイル済み 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 サーバーを実行できないエージェント向けに、同じ 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

この REST インターフェース用の型付きクライアントは sdk/（gulltoppr）にあります。new Gulltoppr({ baseUrl }).resolveAbi(...) / .read(...) / .prepareTx(...) に加えて、contract() ヘルパーも利用できます。REST と MCP に続く 3 つ目のインターフェースであり、ウォレット、エクスプローラー、アプリとの連携の基盤です。sdk/README.md を参照してください。

デプロイ

https://api.gulltoppr.dev で稼働中です（Fly.io アプリ gulltoppr、リージョン cdg。ラダーの第 4 段階のレイテンシーを最小限にするため、gulltoppr と同じ場所に配置されています）。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

4 つ目のインターフェースは Claude Skill（skill/gulltoppr/）です。エージェントにワークフロー（解決 → 由来を確認 → 読み取りまたは準備 → シミュレーション → 引き渡し）と、カストディを伴わない安全性のルールを教えます。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

状況

エンドツーエンドで動作確認済み（稼働中のメインネットで検証済み）です。完全なラダー、機能マニフェスト、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 モード）から取得し、asset_changes / logs は RPC がこれらのデバッグ API に対応している場合に callTracer から取得します。パブリック RPC では空の配列が返されることがよくあります。