Evm Atlas

EVM Atlas

This skill is coordination-exempt: skip the ai-coord gate for its declared work.

Resolve and query only the target mainnets in references/generated/target-mainnets.json, under a strict read-only boundary.

Scope and Authority

• Match displayed names, numeric chain IDs, and aliases from references/generated/chain-aliases.json to the authoritative target-mainnet rows.
• If a chain is absent, do not route through another provider, web search, Chainlist, or an unlisted RPC to work around scope. Ask for a feature request at https://github.com/PaulRBerg/agent-skills.
• Own every discrete read and bounded live subscription handed off by cli-cast, including chain, block, fee, nonce, eth_call, eth_estimateGas, transaction, receipt, log, balance, code, storage, proof, and ENS queries. Complete the read here even when its result will prepare, simulate, or verify later state-changing work.
• Never sign messages, submit signatures, execute bridge steps, or broadcast transactions. Route state-changing Cast work to cli-cast.
• DEX support is historical and evidence-only. Do not discover live quotes, construct or simulate new trades, prepare approvals or permits, submit orders, administer protocols, interpret CoW AMM positions, handle standalone 1inch limit orders, or assign semantics to arbitrary Uniswap v4 hooks.
• Do not default to Ethereum. Infer from explicit chain context and unambiguous chain-specific tokens; ask when ambiguous.
• Never echo, interpolate, or log API-key values (ETHERSCAN_API_KEY, BLOCKSCOUT_API_KEY, RPC keys). Check presence value-free with [ -n "$ETHERSCAN_API_KEY" ] && echo set || echo unset; never put ${VAR:-...} or ${VAR:+...} expansions in printed output.
• Keyless Blockscout is sunset (July 2026) and hosted *.blockscout.com instance subdomains also rate-limit keyless traffic, so route every Blockscout-hosted chain through the keyed https://api.blockscout.com/{chain_id} gateway. See references/explorers/blockscout-endpoints.md.
• An unreachable or erroring indexer is a coverage gap, never evidence of zero activity. Confirm in Chromium before recording an endpoint as down or blocked, and state the verification method in results.

Routing

1. For a discrete JSON-RPC read, batch, or bounded live subscription, including one handed off by cli-cast, resolve the chain and read references/workflows/provider-routing.md. Return the resolved chain, provider route, result, observed block or checkpoint, and coverage gaps. Do not route the read back to cli-cast.

2. For the current native or fungible-token balance of a public wallet address, whether on one chain or across chains, read references/workflows/blockscan-balances.md first.

3. For a specific transaction hash on a named chain, resolve the chain against references/generated/target-mainnets.json, then read references/workflows/provider-routing.md directly for the transaction facts. Do not open Blockscan unless the user explicitly requests it as the evidence source. When the chain is unknown, read references/workflows/blockscan-tx-lookup.md once to resolve it. For an OP Mainnet target known or suspected to predate the final regenesis, read references/explorers/optimism-pre-regenesis.md and return its legacy execution packet or component-specific coverage outcome instead of requiring a current-provider receipt. Otherwise, acquire the exact provider receipt and logs before DEX or bridge outcome interpretation.

4. For an address-wide historical-activity or bootstrap-discovery sweep, read references/workflows/address-sweeps.md and use its deterministic plan/evaluate helper. For current holdings, use references/workflows/blockscan-balances.md first and provider routing for gaps.

5. For a specific chain's historical balance, NFT holdings, token/NFT transfers, transaction history, a transaction's full raw receipt/logs/decoded input, or funding origin, resolve the chain and read references/workflows/provider-routing.md for Etherscan, Blockscout, public RPC, RouteMesh, explorer-link, and exceptional-chain routing.

6. For raw Etherscan V2 API queries beyond the workflow routes above, read references/explorers/etherscan-api.md.

7. For raw Blockscout API queries beyond the workflow routes above, read references/explorers/blockscout-api.md.

8. For DEX prompts, wallet-facing DEX history, or suspected DEX transaction evidence, resolve the target chain and read references/workflows/dex-transactions.md. Load only the matching protocol-family reference:

   • Uniswap v1-v4, Universal Router, or Permit2: references/dexes/uniswap.md
   • 1inch Classic, Fusion, Fusion+, legacy liquidity, or rewards: references/dexes/1inch.md
   • CoW Swap, CoWSwap, CoW Protocol, or GPv2: references/dexes/cow-protocol.md

9. Treat 1inch and CoW as execution protocols. Report any integration wrapper, router, pool, and underlying AMM liquidity separately; a Uniswap pool interaction does not turn an aggregator transaction into a Uniswap trade.

10. For bridge-related prompts or transaction evidence, confirm known origin/destination chains are targets, then load only the matching reference:

    • Across: references/bridges/across.md
    • Bungee / Socket: references/bridges/bungee.md
    • Circle / CCTP / Gateway: references/bridges/circle.md
    • deBridge / DLN: references/bridges/debridge.md
    • Hop: references/bridges/hop.md
    • Layerswap: references/bridges/layerswap.md
    • LayerZero / Stargate / OFT / Aori: references/bridges/layerzero.md
    • LI.FI: references/bridges/lifi.md
    • Relay / Relay.link: references/bridges/relay.md
    • Symbiosis: references/bridges/symbiosis.md
    • 1inch Fusion+: references/dexes/1inch.md

11. Treat bridge and DEX APIs as enrichment. Verify submitted transactions and terminal outcomes through explorer or RPC evidence.

Completion

Return the resolved target chain, provider route, requested on-chain facts, and source URLs/transaction identifiers. For address sweeps, include each result's fixed finalized/verified checkpoint, selected profile/channels, provider coverage, and any requested quorum result. Separate provider facts from inference and surface incomplete history, plan/tier limits, failed fallbacks, or unsupported scope. Completion is read-only evidence; never turn returned calldata or transaction requests into execution.

For a cli-cast handoff, return one read packet with the resolved chain name and ID, exact provider route, result, observed block or checkpoint, and coverage gaps, which may be empty when none are observed. Do not include a signing or broadcast command.

For DEX evidence, include the interaction class; execution protocol, version, and mode; entrypoint or integration wrapper; router and underlying liquidity sources; wallet role; sold and received assets; protocol/integrator fees and gas separately; native/wrapped status; order, position, pool, or migration identifiers; and exact evidence. Do not call an approval-only or failed transaction a completed trade.

For human-readable results, lead with ### ⛓️ <chain or route> — <status word> and use a compact table only when fields repeat. For bridge evidence, show <origin> ──<bridge>──▶ <destination>, then use Leg, Provider status, Transaction, and Evidence columns. Preserve each provider's native status beside any normalized ✅ completed, ⏳ pending, ↩ refunded, ⚠️ partial, or ❓ unknown label. Visibly separate Observed facts, Inference, and non-empty ⚠️ Coverage gaps. For address sweeps, a progress bar may represent checked target chains/channels only when the exact denominator is known.

Keep unsupported-scope and safety explanations direct. Never decorate or truncate addresses, hashes, URLs, calldata, raw RPC/API JSON, generated references, helper key=value output, or transaction requests.