calvyn-code 0.14.0

package/optional-skills/blockchain/evm/scripts/evm_client.py

@@ -0,0 +1,1508 @@
+#!/usr/bin/env python3
+"""
+evm_client.py — EVM blockchain CLI tool for the Hermes Agent project.
+Zero external dependencies. Uses stdlib only: urllib, json, argparse, time, os, sys, typing.
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List, Optional, Tuple
+
+# ---------------------------------------------------------------------------
+# Chain registry
+# ---------------------------------------------------------------------------
+
+CHAINS: Dict[str, Dict[str, Any]] = {
+    "ethereum": {
+        "chain_id": 1,
+        "rpc": "https://ethereum-rpc.publicnode.com",
+        "native": "ETH",
+        "coingecko": "ethereum",
+        "explorer": "https://etherscan.io",
+        "decimals": 18,
+    },
+    "bsc": {
+        "chain_id": 56,
+        "rpc": "https://bsc-dataseed1.binance.org",
+        "native": "BNB",
+        "coingecko": "binancecoin",
+        "explorer": "https://bscscan.com",
+        "decimals": 18,
+    },
+    "base": {
+        "chain_id": 8453,
+        "rpc": "https://mainnet.base.org",
+        "native": "ETH",
+        "coingecko": "ethereum",
+        "explorer": "https://basescan.org",
+        "decimals": 18,
+    },
+    "arbitrum": {
+        "chain_id": 42161,
+        "rpc": "https://arb1.arbitrum.io/rpc",
+        "native": "ETH",
+        "coingecko": "ethereum",
+        "explorer": "https://arbiscan.io",
+        "decimals": 18,
+    },
+    "polygon": {
+        "chain_id": 137,
+        "rpc": "https://polygon-rpc.com",
+        "native": "MATIC",
+        "coingecko": "matic-network",
+        "explorer": "https://polygonscan.com",
+        "decimals": 18,
+    },
+    "optimism": {
+        "chain_id": 10,
+        "rpc": "https://mainnet.optimism.io",
+        "native": "ETH",
+        "coingecko": "ethereum",
+        "explorer": "https://optimistic.etherscan.io",
+        "decimals": 18,
+    },
+    "avalanche": {
+        "chain_id": 43114,
+        "rpc": "https://api.avax.network/ext/bc/C/rpc",
+        "native": "AVAX",
+        "coingecko": "avalanche-2",
+        "explorer": "https://snowtrace.io",
+        "decimals": 18,
+    },
+    "zksync": {
+        "chain_id": 324,
+        "rpc": "https://mainnet.era.zksync.io",
+        "native": "ETH",
+        "coingecko": "ethereum",
+        "explorer": "https://explorer.zksync.io",
+        "decimals": 18,
+    },
+}
+
+DEFAULT_CHAIN = "ethereum"
+
+# ---------------------------------------------------------------------------
+# Known ERC-20 token registry  {chain -> {symbol -> address}}
+# ---------------------------------------------------------------------------
+
+KNOWN_TOKENS: Dict[str, Dict[str, str]] = {
+    "ethereum": {
+        "USDT":  "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+        "USDC":  "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+        "DAI":   "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+        "WETH":  "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+        "WBTC":  "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",
+        "LINK":  "0x514910771AF9Ca656af840dff83E8264EcF986CA",
+        "UNI":   "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
+        "AAVE":  "0x7Fc66500c84A76Ad7e9c93437bFc5Ac33E2DDaE9",
+        "MKR":   "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
+        "COMP":  "0xc00e94Cb662C3520282E6f5717214004A7f26888",
+        "SNX":   "0xC011a73ee8576Fb46F5E1c5751cA3B9Fe0af2a6F",
+        "CRV":   "0xD533a949740bb3306d119CC777fa900bA034cd52",
+        "LDO":   "0x5A98FcBEA516Cf06857215779Fd812CA3beF1B32",
+        "RPL":   "0xD33526068D116cE69F19A9ee46F0bd304F21A51f",
+        "MATIC": "0x7D1AfA7B718fb893dB30A3aBc0Cfc608AaCfeBB0",
+        "SHIB":  "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE",
+        "APE":   "0x4d224452801ACEd8B2F0aebE155379bb5D594381",
+        "GRT":   "0xc944E90C64B2c07662A292be6244BDf05Cda44a7",
+        "FXS":   "0x3432B6A60D23Ca0dFCa7761B7ab56459D9C964D0",
+        "FRAX":  "0x853d955aCEf822Db058eb8505911ED77F175b99e",
+        "BAL":   "0xba100000625a3754423978a60c9317c58a424e3D",
+        "SUSHI": "0x6B3595068778DD592e39A122f4f5a5cF09C90fE2",
+        "YFI":   "0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e",
+        "1INCH": "0x111111111117dC0aa78b770fA6A738034120C302",
+        "ENS":   "0xC18360217D8F7Ab5e7c516566761Ea12Ce7F9D72",
+        "IMX":   "0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF",
+        "SAND":  "0x3845badAde8e6dFF049820680d1F14bD3903a5d0",
+        "MANA":  "0x0F5D2fB29fb7d3CFeE444a200298f468908cC942",
+        "AXS":   "0xBB0E17EF65F82Ab018d8EDd776e8DD940327B28b",
+        "CHZ":   "0x3506424F91fD33084466F402d5D97f05F8e3b4AF",
+        "PEPE":  "0x6982508145454Ce325dDbE47a25d4ec3d2311933",
+    },
+    "bsc": {
+        "USDT":  "0x55d398326f99059fF775485246999027B3197955",
+        "USDC":  "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
+        "BUSD":  "0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56",
+        "WBNB":  "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
+        "CAKE":  "0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82",
+        "XVS":   "0xcF6BB5389c92Bdda8a3747Ddb454cB7a64626C63",
+        "ALPACA":"0x8F0528cE5eF7B51152A59745bEfDD91D97091d2F",
+        "BAKE":  "0xE02dF9e3e622DeBdD69fb838bB799E3F168902c5",
+        "BURGER":"0xAe9269f27437f0fcBC232d39Ec814844a51d6b8f",
+        "DOGE":  "0xbA2aE424d960c26247Dd6c32edC70B295c744C43",
+    },
+    "base": {
+        # Stables + wrapped
+        "USDC":   "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        "DAI":    "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
+        "WETH":   "0x4200000000000000000000000000000000000006",
+        # Liquid-staked ETH variants
+        "cbETH":  "0x2Ae3F1Ec7F1F5012CFEab0185bfc7aa3cF0DEc22",
+        "wstETH": "0xc1CBa3fCea344f92D9239c08C0568f6F2F0ee452",
+        "rETH":   "0xB6fe221Fe9EeF5aBa221c348bA20A1Bf5e73624c",
+        "cbBTC":  "0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf",
+        # Base-native DeFi + meme tokens (carried over from the standalone base/ skill)
+        "AERO":   "0x940181a94A35A4569E4529A3CDfB74e38FD98631",
+        "DEGEN":  "0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed",
+        "TOSHI":  "0xAC1Bd2486aAf3B5C0fc3Fd868558b082a531B2B4",
+        "BRETT":  "0x532f27101965dd16442E59d40670FaF5eBB142E4",
+        "WELL":   "0xA88594D404727625A9437C3f886C7643872296AE",
+    },
+    "arbitrum": {
+        "USDC":  "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+        "USDT":  "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
+        "WETH":  "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
+        "ARB":   "0x912CE59144191C1204E64559FE8253a0e49E6548",
+    },
+    "optimism": {
+        "USDC":  "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+        "USDT":  "0x94b008aA00579c1307B0EF2c499aD98a8ce58e58",
+        "WETH":  "0x4200000000000000000000000000000000000006",
+        "OP":    "0x4200000000000000000000000000000000000042",
+    },
+    "polygon": {
+        "USDC":  "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+        "USDT":  "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
+        "WMATIC":"0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270",
+        "WETH":  "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
+        "DAI":   "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063",
+    },
+    "avalanche": {
+        "USDC":  "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
+        "USDT":  "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
+        "WAVAX": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
+    },
+}
+
+# Gas estimates (units) for common operations
+GAS_ESTIMATES = {
+    "transfer":     21_000,
+    "erc20":        65_000,
+    "approve":      46_000,
+    "swap":        180_000,
+    "nft_mint":    150_000,
+    "nft_transfer": 85_000,
+}
+
+# CoinGecko symbol -> id map for common tokens
+COINGECKO_IDS: Dict[str, str] = {
+    "ETH":   "ethereum",
+    "BTC":   "bitcoin",
+    "BNB":   "binancecoin",
+    "MATIC": "matic-network",
+    "AVAX":  "avalanche-2",
+    "USDT":  "tether",
+    "USDC":  "usd-coin",
+    "DAI":   "dai",
+    "WBTC":  "wrapped-bitcoin",
+    "WETH":  "weth",
+    "LINK":  "chainlink",
+    "UNI":   "uniswap",
+    "AAVE":  "aave",
+    "MKR":   "maker",
+    "COMP":  "compound-governance-token",
+    "SNX":   "havven",
+    "CRV":   "curve-dao-token",
+    "LDO":   "lido-dao",
+    "RPL":   "rocket-pool",
+    "SHIB":  "shiba-inu",
+    "APE":   "apecoin",
+    "GRT":   "the-graph",
+    "BAL":   "balancer",
+    "SUSHI": "sushi",
+    "YFI":   "yearn-finance",
+    "1INCH": "1inch",
+    "ENS":   "ethereum-name-service",
+    "IMX":   "immutable-x",
+    "SAND":  "the-sandbox",
+    "MANA":  "decentraland",
+    "AXS":   "axie-infinity",
+    "ARB":   "arbitrum",
+    "OP":    "optimism",
+    "CAKE":  "pancakeswap-token",
+    "PEPE":  "pepe",
+    "CHZ":   "chiliz",
+}
+
+# ---------------------------------------------------------------------------
+# Helper utilities
+# ---------------------------------------------------------------------------
+
+def hex_to_int(h: str) -> int:
+    if not h or h == "0x":
+        return 0
+    return int(h, 16)
+
+
+# ---------------------------------------------------------------------------
+# Input validation
+# ---------------------------------------------------------------------------
+
+def is_valid_address(s: str) -> bool:
+    """Return True if `s` looks like a 20-byte hex Ethereum address.
+
+    Does NOT validate EIP-55 checksum — RPC endpoints accept any-case hex.
+    Just guards against typos / wrong-length input before we burn an RPC call.
+    """
+    if not isinstance(s, str):
+        return False
+    if not s.startswith("0x") and not s.startswith("0X"):
+        return False
+    if len(s) != 42:
+        return False
+    try:
+        int(s, 16)
+    except ValueError:
+        return False
+    return True
+
+
+def is_valid_txhash(s: str) -> bool:
+    """Return True if `s` looks like a 32-byte hex transaction hash."""
+    if not isinstance(s, str):
+        return False
+    if not s.startswith("0x") and not s.startswith("0X"):
+        return False
+    if len(s) != 66:
+        return False
+    try:
+        int(s, 16)
+    except ValueError:
+        return False
+    return True
+
+
+def require_address(s: str, *, field: str = "address") -> str:
+    """Return `s` lowercased if valid, else exit with an error message.
+
+    Centralizing validation here means every subcommand fails fast on bad input
+    instead of bubbling up an opaque RPC error 30 seconds later.
+    """
+    if not is_valid_address(s):
+        sys.stderr.write(
+            f"error: invalid {field} {s!r}: expected 0x-prefixed 40-hex-char address\n"
+        )
+        sys.exit(2)
+    return s.lower()
+
+
+def require_txhash(s: str, *, field: str = "tx hash") -> str:
+    """Return `s` lowercased if valid, else exit with an error message."""
+    if not is_valid_txhash(s):
+        sys.stderr.write(
+            f"error: invalid {field} {s!r}: expected 0x-prefixed 64-hex-char tx hash\n"
+        )
+        sys.exit(2)
+    return s.lower()
+
+
+def wei_to_native(wei: int, decimals: int = 18) -> float:
+    return wei / (10 ** decimals)
+
+
+def gwei_from_wei(wei: int) -> float:
+    return wei / 1e9
+
+def _short_addr(addr: str) -> str:
+    if addr and len(addr) >= 10:
+        return addr[:6] + "..." + addr[-4:]
+    return addr or ""
+
+def print_json(data: Any) -> None:
+    print(json.dumps(data, indent=2, default=str))
+
+# ---------------------------------------------------------------------------
+# HTTP / JSON-RPC layer
+# ---------------------------------------------------------------------------
+
+def _http_post(url: str, payload: Any, retries: int = 5, timeout: int = 20) -> Any:
+    body = json.dumps(payload).encode()
+    headers = {
+        "Content-Type": "application/json",
+        "Accept":       "application/json",
+        "User-Agent":   "Mozilla/5.0 (compatible; evm_client/1.0)",
+    }
+    req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+    delay = 1.0
+    last_err: Exception = RuntimeError("No attempts made")
+    for attempt in range(retries):
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return json.loads(resp.read().decode())
+        except urllib.error.HTTPError as e:
+            if e.code == 429:
+                time.sleep(delay)
+                delay = min(delay * 2, 30)
+                last_err = e
+                continue
+            body_text = ""
+            try:
+                body_text = e.read().decode()
+            except Exception:
+                pass
+            raise RuntimeError(f"HTTP {e.code}: {body_text}") from e
+        except Exception as e:
+            last_err = e
+            if attempt < retries - 1:
+                time.sleep(delay)
+                delay = min(delay * 2, 30)
+    raise RuntimeError(f"Request failed after {retries} retries: {last_err}") from last_err
+
+def _http_get(url: str, retries: int = 5, timeout: int = 20) -> Any:
+    headers = {"Accept": "application/json", "User-Agent": "evm_client/1.0"}
+    req = urllib.request.Request(url, headers=headers, method="GET")
+    delay = 1.0
+    last_err: Exception = RuntimeError("No attempts made")
+    for attempt in range(retries):
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return json.loads(resp.read().decode())
+        except urllib.error.HTTPError as e:
+            if e.code == 429:
+                time.sleep(delay)
+                delay = min(delay * 2, 30)
+                last_err = e
+                continue
+            body_text = ""
+            try:
+                body_text = e.read().decode()
+            except Exception:
+                pass
+            raise RuntimeError(f"HTTP {e.code}: {body_text}") from e
+        except Exception as e:
+            last_err = e
+            if attempt < retries - 1:
+                time.sleep(delay)
+                delay = min(delay * 2, 30)
+    raise RuntimeError(f"Request failed after {retries} retries: {last_err}") from last_err
+
+# ---------------------------------------------------------------------------
+# RPC helpers
+# ---------------------------------------------------------------------------
+
+def get_rpc_url(chain: str) -> str:
+    env = os.environ.get("EVM_RPC_URL", "")
+    if env:
+        return env
+    cfg = CHAINS.get(chain)
+    if not cfg:
+        raise ValueError(f"Unknown chain '{chain}'. Available: {', '.join(CHAINS)}")
+    return cfg["rpc"]
+
+def rpc_call(chain: str, method: str, params: List[Any], req_id: int = 1) -> Any:
+    url = get_rpc_url(chain)
+    payload = {"jsonrpc": "2.0", "id": req_id, "method": method, "params": params}
+    resp = _http_post(url, payload)
+    if "error" in resp:
+        raise RuntimeError(f"RPC error: {resp['error']}")
+    return resp.get("result")
+
+def rpc_batch(chain: str, calls: List[Tuple[str, List[Any]]], batch_limit: int = 10) -> List[Any]:
+    """Send a batch of JSON-RPC calls; returns list of results in same order.
+
+    Auto-chunks at `batch_limit` (default 10) so we stay under per-RPC limits.
+    Base's public RPC caps batches at 10 — exceeding that returns a single error
+    dict instead of a results list, which would mask all our calls.
+    """
+    url = get_rpc_url(chain)
+
+    # Build the full payload, preserving order via JSON-RPC `id`
+    items = [
+        {"jsonrpc": "2.0", "id": i, "method": m, "params": p}
+        for i, (m, p) in enumerate(calls)
+    ]
+
+    out: List[Any] = [None] * len(items)
+    for start in range(0, len(items), batch_limit):
+        chunk = items[start:start + batch_limit]
+        resp = _http_post(url, chunk)
+        if not isinstance(resp, list):
+            # Single error response (e.g. batch-too-large) — leave this chunk as None
+            continue
+        for r in resp:
+            rid = r.get("id")
+            if isinstance(rid, int) and 0 <= rid < len(out):
+                if "error" in r:
+                    out[rid] = None
+                else:
+                    out[rid] = r.get("result")
+    return out
+
+# ---------------------------------------------------------------------------
+# ABI encoding helpers (minimal, for ERC-20 calls)
+# ---------------------------------------------------------------------------
+
+def _encode_address(addr: str) -> str:
+    """Pad address to 32 bytes."""
+    return addr.lower().replace("0x", "").zfill(64)
+
+def _keccak256(data: bytes) -> bytes:
+    """Pure Python Keccak-256 (Ethereum's hash, NOT SHA3-256)."""
+    # Keccak-256 round constants
+    RC = [
+        0x0000000000000001, 0x0000000000008082, 0x800000000000808A, 0x8000000080008000,
+        0x000000000000808B, 0x0000000080000001, 0x8000000080008081, 0x8000000000008009,
+        0x000000000000008A, 0x0000000000000088, 0x0000000080008009, 0x000000008000000A,
+        0x000000008000808B, 0x800000000000008B, 0x8000000000008089, 0x8000000000008003,
+        0x8000000000008002, 0x8000000000000080, 0x000000000000800A, 0x800000008000000A,
+        0x8000000080008081, 0x8000000000008080, 0x0000000080000001, 0x8000000080008008,
+    ]
+    ROT = [
+        [0, 36, 3, 41, 18], [1, 44, 10, 45, 2], [62, 6, 43, 15, 61],
+        [28, 55, 25, 21, 56], [27, 20, 39, 8, 14],
+    ]
+    def rot64(x, n): return ((x << n) | (x >> (64 - n))) & 0xFFFFFFFFFFFFFFFF
+    rate = 136  # 1088 bits for keccak-256
+    # Padding
+    msg = bytearray(data)
+    msg.append(0x01)
+    while len(msg) % rate != 0:
+        msg.append(0x00)
+    msg[-1] |= 0x80
+    # Absorb
+    state = [0] * 25
+    for block_start in range(0, len(msg), rate):
+        block = msg[block_start:block_start + rate]
+        for i in range(rate // 8):
+            state[i] ^= int.from_bytes(block[i*8:(i+1)*8], "little")
+        # Keccak-f[1600]
+        for rnd in range(24):
+            # Theta
+            C = [state[x] ^ state[x+5] ^ state[x+10] ^ state[x+15] ^ state[x+20] for x in range(5)]
+            D = [C[(x-1) % 5] ^ rot64(C[(x+1) % 5], 1) for x in range(5)]
+            state = [state[i] ^ D[i % 5] for i in range(25)]
+            # Rho + Pi
+            B = [0] * 25
+            for x in range(5):
+                for y in range(5):
+                    B[y*5 + ((2*x+3*y) % 5)] = rot64(state[x + 5*y], ROT[x][y])
+            # Chi
+            state = [B[i] ^ ((~B[(i//5)*5 + (i%5+1)%5]) & B[(i//5)*5 + (i%5+2)%5]) for i in range(25)]
+            # Iota
+            state[0] ^= RC[rnd]
+    # Squeeze
+    out = b"".join(state[i].to_bytes(8, "little") for i in range(4))
+    return out
+
+
+def _selector(sig: str) -> str:
+    """Compute 4-byte function selector via keccak-256."""
+    return "0x" + _keccak256(sig.encode()).hex()[:8]
+
+# Precomputed selectors for ERC-20 functions
+ERC20_SELECTORS: Dict[str, str] = {
+    "name()":                  "0x06fdde03",
+    "symbol()":                "0x95d89b41",
+    "decimals()":              "0x313ce567",
+    "totalSupply()":           "0x18160ddd",
+    "balanceOf(address)":      "0x70a08231",
+}
+
+def eth_call_erc20(chain: str, contract: str, fn: str, arg_addr: Optional[str] = None) -> str:
+    selector = ERC20_SELECTORS[fn]
+    data = selector
+    if arg_addr:
+        data += _encode_address(arg_addr)
+    params = [{"to": contract, "data": data}, "latest"]
+    return rpc_call(chain, "eth_call", params) or "0x"
+
+def decode_string(hex_data: str) -> str:
+    """Decode ABI-encoded string from eth_call result."""
+    try:
+        raw = hex_data[2:] if hex_data.startswith("0x") else hex_data
+        if len(raw) < 128:
+            # Try decoding as raw bytes (some tokens return non-ABI strings)
+            b = bytes.fromhex(raw)
+            return b.rstrip(b"\x00").decode("utf-8", errors="replace").strip()
+        # offset (skip 32 bytes), length, data
+        length = int(raw[64:128], 16)
+        chars = raw[128:128 + length * 2]
+        return bytes.fromhex(chars).decode("utf-8", errors="replace").strip()
+    except Exception:
+        return ""
+
+def decode_uint256(hex_data: str) -> int:
+    try:
+        raw = hex_data[2:] if hex_data.startswith("0x") else hex_data
+        if not raw:
+            return 0
+        return int(raw, 16)
+    except Exception:
+        return 0
+
+def decode_uint8(hex_data: str) -> int:
+    return decode_uint256(hex_data)
+
+# ---------------------------------------------------------------------------
+# CoinGecko price fetching
+# ---------------------------------------------------------------------------
+
+COINGECKO_BASE = "https://api.coingecko.com/api/v3"
+
+def cg_price_by_id(cg_id: str) -> Optional[float]:
+    try:
+        url = f"{COINGECKO_BASE}/simple/price?ids={cg_id}&vs_currencies=usd"
+        data = _http_get(url)
+        return data.get(cg_id, {}).get("usd")
+    except Exception:
+        return None
+
+def cg_price_by_ids(cg_ids: List[str]) -> Dict[str, float]:
+    """Fetch multiple prices in one request."""
+    if not cg_ids:
+        return {}
+    try:
+        joined = ",".join(cg_ids)
+        url = f"{COINGECKO_BASE}/simple/price?ids={joined}&vs_currencies=usd"
+        data = _http_get(url)
+        return {k: v.get("usd", 0.0) for k, v in data.items() if "usd" in v}
+    except Exception:
+        return {}
+
+def cg_price_by_contract(chain: str, contract: str) -> Optional[float]:
+    cg_platform_map = {
+        "ethereum": "ethereum",
+        "bsc":      "binance-smart-chain",
+        "base":     "base",
+        "arbitrum": "arbitrum-one",
+        "polygon":  "polygon-pos",
+        "optimism": "optimistic-ethereum",
+        "avalanche":"avalanche",
+        "zksync":   "zksync",
+    }
+    platform = cg_platform_map.get(chain)
+    if not platform:
+        return None
+    try:
+        url = (
+            f"{COINGECKO_BASE}/simple/token_price/{platform}"
+            f"?contract_addresses={contract}&vs_currencies=usd"
+        )
+        data = _http_get(url)
+        addr_lower = contract.lower()
+        for k, v in data.items():
+            if k.lower() == addr_lower:
+                return v.get("usd")
+        return None
+    except Exception:
+        return None
+
+def get_native_price(chain: str) -> Optional[float]:
+    cg_id = CHAINS[chain]["coingecko"]
+    return cg_price_by_id(cg_id)
+
+# ---------------------------------------------------------------------------
+# Command implementations
+# ---------------------------------------------------------------------------
+
+def cmd_stats(args: argparse.Namespace) -> None:
+    chain = args.chain
+    cfg = CHAINS[chain]
+
+    # Batch: blockNumber + gasPrice
+    results = rpc_batch(chain, [
+        ("eth_blockNumber", []),
+        ("eth_gasPrice",    []),
+    ])
+    block_num = hex_to_int(results[0] or "0x0")
+    gas_price_wei = hex_to_int(results[1] or "0x0")
+
+    # TPS estimate: compare latest block timestamp with parent
+    tps: Optional[float] = None
+    try:
+        latest_block = rpc_call(chain, "eth_getBlockByNumber", ["latest", False])
+        if latest_block:
+            parent_hex = latest_block.get("parentHash")
+            parent_block = rpc_call(chain, "eth_getBlockByHash", [parent_hex, False])
+            if parent_block:
+                t1 = hex_to_int(latest_block.get("timestamp", "0x0"))
+                t0 = hex_to_int(parent_block.get("timestamp", "0x0"))
+                tx_count = len(latest_block.get("transactions", []))
+                if t1 > t0:
+                    tps = round(tx_count / (t1 - t0), 2)
+    except Exception:
+        pass
+
+    native_price = get_native_price(chain)
+
+    print_json({
+        "chain":           chain,
+        "block_number":    block_num,
+        "gas_price_gwei":  round(gwei_from_wei(gas_price_wei), 4),
+        "gas_price_wei":   gas_price_wei,
+        "native_token":    cfg["native"],
+        "native_price_usd": native_price,
+        "tps_estimate":    tps,
+        "explorer":        cfg["explorer"],
+    })
+
+
+def cmd_wallet(args: argparse.Namespace) -> None:
+    address = require_address(args.address)
+    chain   = args.chain
+    limit   = args.limit
+    no_prices = args.no_prices
+    cfg     = CHAINS[chain]
+
+    # Native balance
+    balance_hex = rpc_call(chain, "eth_getBalance", [address, "latest"])
+    native_wei  = hex_to_int(balance_hex or "0x0")
+    native_val  = wei_to_native(native_wei, cfg["decimals"])
+
+    native_usd_price: Optional[float] = None
+    native_usd: Optional[float] = None
+    if not no_prices:
+        native_usd_price = get_native_price(chain)
+        if native_usd_price is not None:
+            native_usd = round(native_val * native_usd_price, 4)
+
+    # ERC-20 tokens
+    token_list = list((KNOWN_TOKENS.get(chain) or {}).items())[:limit]
+    tokens_out = []
+    portfolio_usd = native_usd or 0.0
+
+    if token_list:
+        # Batch balanceOf calls
+        balance_calls = [
+            ("eth_call", [{"to": addr, "data": ERC20_SELECTORS["balanceOf(address)"] + _encode_address(address)}, "latest"])
+            for _, addr in token_list
+        ]
+        balances = rpc_batch(chain, balance_calls)
+
+        for idx, (symbol, addr) in enumerate(token_list):
+            raw_bal = decode_uint256(balances[idx] or "0x0")
+            if raw_bal == 0:
+                continue
+
+            # Fetch decimals
+            dec_hex = eth_call_erc20(chain, addr, "decimals()")
+            decimals = decode_uint8(dec_hex) if dec_hex and dec_hex != "0x" else 18
+            bal_human = wei_to_native(raw_bal, decimals)
+
+            token_price: Optional[float] = None
+            token_usd: Optional[float] = None
+            if not no_prices:
+                try:
+                    cg_id = COINGECKO_IDS.get(symbol)
+                    if cg_id:
+                        token_price = cg_price_by_id(cg_id)
+                    if token_price is None:
+                        token_price = cg_price_by_contract(chain, addr)
+                    if token_price is not None:
+                        token_usd = round(bal_human * token_price, 4)
+                        portfolio_usd += token_usd
+                except Exception:
+                    pass
+
+            tokens_out.append({
+                "symbol":       symbol,
+                "contract":     addr,
+                "balance":      round(bal_human, 8),
+                "price_usd":    token_price,
+                "value_usd":    token_usd,
+            })
+
+    print_json({
+        "chain":             chain,
+        "address":           address,
+        "native_token":      cfg["native"],
+        "native_balance":    round(native_val, 8),
+        "native_price_usd":  native_usd_price,
+        "native_value_usd":  native_usd,
+        "erc20_tokens":      tokens_out,
+        "portfolio_total_usd": round(portfolio_usd, 4) if not no_prices else None,
+    })
+
+
+def cmd_tx(args: argparse.Namespace) -> None:
+    tx_hash = require_txhash(args.hash)
+    chain   = args.chain
+    cfg     = CHAINS[chain]
+
+    results = rpc_batch(chain, [
+        ("eth_getTransactionByHash",       [tx_hash]),
+        ("eth_getTransactionReceipt",      [tx_hash]),
+    ])
+    tx      = results[0]
+    receipt = results[1]
+
+    if not tx:
+        print_json({"error": f"Transaction {tx_hash} not found on {chain}"})
+        return
+
+    block_num = hex_to_int(tx.get("blockNumber") or "0x0")
+    timestamp: Optional[int] = None
+    try:
+        blk = rpc_call(chain, "eth_getBlockByNumber", [hex(block_num), False])
+        if blk:
+            timestamp = hex_to_int(blk.get("timestamp", "0x0"))
+    except Exception:
+        pass
+
+    value_wei  = hex_to_int(tx.get("value", "0x0"))
+    value_eth  = wei_to_native(value_wei, cfg["decimals"])
+    gas_price  = hex_to_int(tx.get("gasPrice") or "0x0")
+    gas_limit  = hex_to_int(tx.get("gas", "0x0"))
+    gas_used   = hex_to_int((receipt or {}).get("gasUsed", "0x0")) if receipt else None
+    status     = None
+    if receipt:
+        status = "success" if hex_to_int(receipt.get("status", "0x0")) == 1 else "failed"
+
+    input_data = tx.get("input", "0x")
+    input_preview = input_data[:66] + ("..." if len(input_data) > 66 else "")
+
+    native_price = get_native_price(chain)
+    value_usd = round(value_eth * native_price, 4) if native_price else None
+
+    fee_eth: Optional[float] = None
+    fee_usd: Optional[float] = None
+    if gas_used is not None:
+        fee_eth = wei_to_native(gas_used * gas_price, cfg["decimals"])
+        if native_price:
+            fee_usd = round(fee_eth * native_price, 6)
+
+    print_json({
+        "chain":          chain,
+        "hash":           tx_hash,
+        "block":          block_num,
+        "timestamp":      timestamp,
+        "from":           tx.get("from"),
+        "to":             tx.get("to"),
+        "value":          round(value_eth, 8),
+        "value_usd":      value_usd,
+        "native_token":   cfg["native"],
+        "gas_limit":      gas_limit,
+        "gas_used":       gas_used,
+        "gas_price_gwei": round(gwei_from_wei(gas_price), 4),
+        "fee_native":     round(fee_eth, 8) if fee_eth is not None else None,
+        "fee_usd":        fee_usd,
+        "status":         status,
+        "input_preview":  input_preview,
+        "nonce":          hex_to_int(tx.get("nonce", "0x0")),
+        "explorer_url":   f"{cfg['explorer']}/tx/{tx_hash}",
+    })
+
+
+def cmd_token(args: argparse.Namespace) -> None:
+    contract = require_address(args.contract, field="contract address")
+    chain    = args.chain
+
+    # Batch all ERC-20 metadata calls
+    calls = [
+        ("eth_call", [{"to": contract, "data": ERC20_SELECTORS["name()"]},        "latest"]),
+        ("eth_call", [{"to": contract, "data": ERC20_SELECTORS["symbol()"]},       "latest"]),
+        ("eth_call", [{"to": contract, "data": ERC20_SELECTORS["decimals()"]},     "latest"]),
+        ("eth_call", [{"to": contract, "data": ERC20_SELECTORS["totalSupply()"]},  "latest"]),
+    ]
+    results  = rpc_batch(chain, calls)
+    name     = decode_string(results[0] or "0x")
+    symbol   = decode_string(results[1] or "0x")
+    decimals = decode_uint8(results[2] or "0x0")
+    supply_raw = decode_uint256(results[3] or "0x0")
+    supply   = wei_to_native(supply_raw, decimals)
+
+    price: Optional[float] = None
+    market_cap: Optional[float] = None
+    cg_id = COINGECKO_IDS.get(symbol.upper())
+    if cg_id:
+        price = cg_price_by_id(cg_id)
+    if price is None:
+        price = cg_price_by_contract(chain, contract)
+    if price is not None and supply > 0:
+        market_cap = round(price * supply, 2)
+
+    cfg = CHAINS[chain]
+    print_json({
+        "chain":        chain,
+        "contract":     contract,
+        "name":         name,
+        "symbol":       symbol,
+        "decimals":     decimals,
+        "total_supply": round(supply, 4),
+        "price_usd":    price,
+        "market_cap_usd": market_cap,
+        "explorer_url": f"{cfg['explorer']}/token/{contract}",
+    })
+
+
+def cmd_activity(args: argparse.Namespace) -> None:
+    address = require_address(args.address)
+    chain   = args.chain
+    limit   = args.limit
+    cfg     = CHAINS[chain]
+
+    # Get current block
+    block_hex = rpc_call(chain, "eth_blockNumber", [])
+    latest    = hex_to_int(block_hex or "0x0")
+
+    txs_out: List[Dict[str, Any]] = []
+    scan_range = min(200, latest)
+    blocks_checked = 0
+
+    for bn in range(latest, max(0, latest - scan_range), -1):
+        if len(txs_out) >= limit:
+            break
+        try:
+            blk = rpc_call(chain, "eth_getBlockByNumber", [hex(bn), True])
+        except Exception:
+            continue
+        if not blk:
+            continue
+        blocks_checked += 1
+        timestamp = hex_to_int(blk.get("timestamp", "0x0"))
+        for tx in blk.get("transactions", []):
+            if len(txs_out) >= limit:
+                break
+            frm = (tx.get("from") or "").lower()
+            to  = (tx.get("to")   or "").lower()
+            addr_lower = address.lower()
+            if frm == addr_lower or to == addr_lower:
+                value_wei = hex_to_int(tx.get("value", "0x0"))
+                value_eth = wei_to_native(value_wei, cfg["decimals"])
+                gas_price = hex_to_int(tx.get("gasPrice") or "0x0")
+                txs_out.append({
+                    "hash":           tx.get("hash"),
+                    "block":          bn,
+                    "timestamp":      timestamp,
+                    "from":           tx.get("from"),
+                    "to":             tx.get("to"),
+                    "value":          round(value_eth, 8),
+                    "native_token":   cfg["native"],
+                    "gas_price_gwei": round(gwei_from_wei(gas_price), 4),
+                    "direction":      "out" if frm == addr_lower else "in",
+                })
+
+    print_json({
+        "chain":          chain,
+        "address":        address,
+        "blocks_scanned": blocks_checked,
+        "tx_count":       len(txs_out),
+        "transactions":   txs_out,
+    })
+
+
+def cmd_gas(args: argparse.Namespace) -> None:
+    chain = args.chain
+    cfg   = CHAINS[chain]
+
+    gas_price_hex = rpc_call(chain, "eth_gasPrice", [])
+    gas_wei       = hex_to_int(gas_price_hex or "0x0")
+    gas_gwei      = gwei_from_wei(gas_wei)
+
+    native_price  = get_native_price(chain)
+
+    estimates: Dict[str, Any] = {}
+    for op, gas_units in GAS_ESTIMATES.items():
+        cost_wei   = gas_wei * gas_units
+        cost_native = wei_to_native(cost_wei, cfg["decimals"])
+        cost_usd    = round(cost_native * native_price, 6) if native_price else None
+        estimates[op] = {
+            "gas_units":   gas_units,
+            "cost_native": round(cost_native, 8),
+            "cost_usd":    cost_usd,
+        }
+
+    print_json({
+        "chain":           chain,
+        "native_token":    cfg["native"],
+        "gas_price_gwei":  round(gas_gwei, 4),
+        "gas_price_wei":   gas_wei,
+        "native_price_usd": native_price,
+        "estimates":       estimates,
+    })
+
+
+def cmd_price(args: argparse.Namespace) -> None:
+    token = args.token
+    chain = args.chain
+
+    price: Optional[float] = None
+    source = "unknown"
+
+    # Check if it's a contract address
+    if token.startswith("0x") and len(token) >= 10:
+        price = cg_price_by_contract(chain, token)
+        source = "coingecko_contract"
+        if price is None:
+            print_json({"error": f"Could not find price for contract {token} on {chain}"})
+            return
+    else:
+        symbol = token.upper()
+        cg_id  = COINGECKO_IDS.get(symbol)
+        if cg_id:
+            price  = cg_price_by_id(cg_id)
+            source = f"coingecko:{cg_id}"
+        if price is None:
+            # Try known tokens on given chain
+            contract = (KNOWN_TOKENS.get(chain) or {}).get(symbol)
+            if contract:
+                price  = cg_price_by_contract(chain, contract)
+                source = f"coingecko_contract:{contract}"
+        if price is None:
+            print_json({"error": f"Could not find price for '{token}'. Try a contract address."})
+            return
+
+    print_json({
+        "token":     token,
+        "chain":     chain,
+        "price_usd": price,
+        "source":    source,
+    })
+
+
+def _fetch_chain_stats(chain: str) -> Dict[str, Any]:
+    """Fetch gas price + native price for a single chain (used in compare)."""
+    try:
+        gas_hex = rpc_call(chain, "eth_gasPrice", [])
+        gas_wei = hex_to_int(gas_hex or "0x0")
+        gas_gwei = round(gwei_from_wei(gas_wei), 4)
+    except Exception:
+        gas_gwei = None
+
+    cg_id = CHAINS[chain]["coingecko"]
+    native_price = cg_price_by_id(cg_id)
+
+    transfer_usd: Optional[float] = None
+    if gas_gwei is not None and native_price is not None:
+        gas_wei_val = int(gas_gwei * 1e9)
+        cost_wei    = gas_wei_val * GAS_ESTIMATES["transfer"]
+        cost_native = wei_to_native(cost_wei, CHAINS[chain]["decimals"])
+        transfer_usd = round(cost_native * native_price, 6)
+
+    return {
+        "chain":             chain,
+        "native_token":      CHAINS[chain]["native"],
+        "gas_price_gwei":    gas_gwei,
+        "native_price_usd":  native_price,
+        "transfer_cost_usd": transfer_usd,
+    }
+
+
+def cmd_compare(_args: argparse.Namespace) -> None:
+    """Compare gas prices and native token prices across all chains simultaneously."""
+    import threading
+
+    results: Dict[str, Any] = {}
+    errors:  Dict[str, str] = {}
+    lock = threading.Lock()
+
+    def fetch(chain: str) -> None:
+        try:
+            data = _fetch_chain_stats(chain)
+            with lock:
+                results[chain] = data
+        except Exception as e:
+            with lock:
+                errors[chain] = str(e)
+
+    threads = [threading.Thread(target=fetch, args=(c,), daemon=True) for c in CHAINS]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join(timeout=30)
+
+    sorted_by_gas = sorted(
+        results.values(),
+        key=lambda x: x.get("gas_price_gwei") or float("inf"),
+    )
+
+    print_json({
+        "comparison":       sorted_by_gas,
+        "errors":           errors,
+        "cheapest_gas":     sorted_by_gas[0]["chain"] if sorted_by_gas else None,
+        "most_expensive_gas": sorted_by_gas[-1]["chain"] if sorted_by_gas else None,
+    })
+
+
+def cmd_whale(args: argparse.Namespace) -> None:
+    chain    = args.chain
+    blocks   = args.blocks
+    min_usd  = args.min_usd
+    cfg      = CHAINS[chain]
+
+    native_price = get_native_price(chain)
+    if native_price is None:
+        print_json({"error": "Could not fetch native token price for USD conversion."})
+        return
+
+    block_hex = rpc_call(chain, "eth_blockNumber", [])
+    latest    = hex_to_int(block_hex or "0x0")
+
+    whales: List[Dict[str, Any]] = []
+    blocks_scanned = 0
+
+    for bn in range(latest, max(0, latest - blocks), -1):
+        try:
+            blk = rpc_call(chain, "eth_getBlockByNumber", [hex(bn), True])
+        except Exception:
+            continue
+        if not blk:
+            continue
+        blocks_scanned += 1
+        timestamp = hex_to_int(blk.get("timestamp", "0x0"))
+
+        for tx in blk.get("transactions", []):
+            value_wei = hex_to_int(tx.get("value", "0x0"))
+            if value_wei == 0:
+                continue
+            value_native = wei_to_native(value_wei, cfg["decimals"])
+            value_usd    = value_native * native_price
+            if value_usd >= min_usd:
+                whales.append({
+                    "hash":         tx.get("hash"),
+                    "block":        bn,
+                    "timestamp":    timestamp,
+                    "from":         tx.get("from"),
+                    "from_short":   _short_addr(tx.get("from") or ""),
+                    "to":           tx.get("to"),
+                    "to_short":     _short_addr(tx.get("to") or ""),
+                    "value_native": round(value_native, 6),
+                    "native_token": cfg["native"],
+                    "value_usd":    round(value_usd, 2),
+                })
+
+    whales.sort(key=lambda x: x["value_usd"], reverse=True)
+
+    print_json({
+        "chain":           chain,
+        "blocks_scanned":  blocks_scanned,
+        "latest_block":    latest,
+        "min_usd":         min_usd,
+        "native_price_usd": native_price,
+        "whale_count":     len(whales),
+        "transfers":       whales,
+    })
+
+
+# ---------------------------------------------------------------------------
+# New commands: multichain, allowance, decode, ens, contract
+# ---------------------------------------------------------------------------
+
+def cmd_multichain(args: argparse.Namespace) -> None:
+    """Scan same wallet across all 8 chains simultaneously."""
+    import threading
+
+    address = require_address(args.address)
+    results: Dict[str, Any] = {}
+    lock = threading.Lock()
+
+    def scan_chain(chain: str) -> None:
+        cfg = CHAINS[chain]
+        try:
+            bal_hex = rpc_call(chain, "eth_getBalance", [address, "latest"])
+            native_bal = int(bal_hex, 16) / 1e18 if bal_hex else 0.0
+            native_price = get_native_price(chain)
+            native_usd = round(native_bal * native_price, 2) if native_price else None
+            entry: Dict[str, Any] = {
+                "native_symbol": cfg["native"],
+                "native_balance": round(native_bal, 8),
+                "native_price_usd": native_price,
+                "native_value_usd": native_usd,
+                "tokens": [],
+                "total_usd": native_usd or 0.0,
+            }
+            # Check known tokens for this chain.
+            # KNOWN_TOKENS[chain] maps {symbol: contract_address}, not {addr: (sym, name)}.
+            known = KNOWN_TOKENS.get(chain, {})
+            for symbol, contract in known.items():
+                raw = eth_call_erc20(chain, contract, "balanceOf(address)", address)
+                if not raw or raw == "0x":
+                    continue
+                try:
+                    bal_int = int(raw, 16)
+                except Exception:
+                    continue
+                if bal_int == 0:
+                    continue
+                dec_raw = eth_call_erc20(chain, contract, "decimals()")
+                decimals = decode_uint8(dec_raw) if dec_raw else 18
+                human = bal_int / (10 ** decimals)
+                tok_price = cg_price_by_contract(chain, contract)
+                tok_usd = round(human * tok_price, 2) if tok_price else None
+                entry["tokens"].append({
+                    "symbol": symbol,
+                    "balance": round(human, 6),
+                    "value_usd": tok_usd,
+                })
+                if tok_usd:
+                    entry["total_usd"] = round(entry["total_usd"] + tok_usd, 2)
+            with lock:
+                results[chain] = entry
+        except Exception as exc:
+            with lock:
+                results[chain] = {"error": str(exc)}
+
+    threads = [threading.Thread(target=scan_chain, args=(c,)) for c in CHAINS]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+
+    grand_total = sum(
+        v.get("total_usd", 0) for v in results.values() if isinstance(v, dict)
+    )
+    print_json({
+        "address": address,
+        "chains": results,
+        "grand_total_usd": round(grand_total, 2),
+    })
+
+
+def cmd_allowance(args: argparse.Namespace) -> None:
+    """Check dangerous ERC-20 approvals for a wallet (known spenders)."""
+    address = require_address(args.address)
+    chain = args.chain
+
+    # Well-known spender contracts (DEXes, bridges, etc.)
+    KNOWN_SPENDERS = {
+        "0x000000000022D473030F116dDEE9F6B43aC78BA3": "Permit2 (Uniswap)",
+        "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D": "Uniswap V2 Router",
+        "0xE592427A0AEce92De3Edee1F18E0157C05861564": "Uniswap V3 Router",
+        "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45": "Uniswap Universal Router",
+        "0x1111111254EEB25477B68fb85Ed929f73A960582": "1inch Router V5",
+        "0x6131B5fae19EA4f9D964eAc0408E4408b66337b5": "KyberSwap Router",
+        "0xDef1C0ded9bec7F1a1670819833240f027b25EfF": "0x Exchange Proxy",
+        "0x3fc91a3afd70395cd496c647d5a6cc9d4b2b7fad": "Uniswap Universal Router 2",
+    }
+
+    known = KNOWN_TOKENS.get(chain, {})
+    approvals = []
+
+    # KNOWN_TOKENS[chain] is {symbol: contract_address}, not {addr: (sym, name)}.
+    for symbol, contract in known.items():
+        for spender_addr, spender_name in KNOWN_SPENDERS.items():
+            # allowance(owner, spender) = 0xdd62ed3e
+            owner_pad  = address.lower().replace("0x", "").zfill(64)
+            spender_pad = spender_addr.lower().replace("0x", "").zfill(64)
+            data = "0xdd62ed3e" + owner_pad + spender_pad
+            raw = rpc_call(chain, "eth_call", [{"to": contract, "data": data}, "latest"])
+            if not raw or raw == "0x":
+                continue
+            try:
+                allowance_int = int(raw, 16)
+            except Exception:
+                continue
+            if allowance_int == 0:
+                continue
+
+            dec_raw = eth_call_erc20(chain, contract, "decimals()")
+            decimals = decode_uint8(dec_raw) if dec_raw else 18
+            max_uint = 2**256 - 1
+            is_unlimited = allowance_int >= max_uint // 2
+
+            approvals.append({
+                "token": symbol,
+                "contract": contract,
+                "spender": spender_name,
+                "spender_address": spender_addr,
+                "allowance": "UNLIMITED" if is_unlimited else str(round(allowance_int / 10**decimals, 4)),
+                "risk": "HIGH" if is_unlimited else "LOW",
+            })
+
+    print_json({
+        "chain": chain,
+        "address": address,
+        "approvals_found": len(approvals),
+        "approvals": approvals,
+        "note": "Only checks known DEX/bridge spenders. Use a full allowance checker for complete coverage.",
+    })
+
+
+def cmd_decode(args: argparse.Namespace) -> None:
+    """Decode transaction input data using 4byte.directory."""
+    chain = args.chain
+    tx_hash = require_txhash(args.hash)
+
+    tx = rpc_call(chain, "eth_getTransactionByHash", [tx_hash])
+    if not tx:
+        print_json({"error": "Transaction not found"})
+        return
+
+    input_data: str = tx.get("input", "0x")
+    if not input_data or input_data == "0x":
+        print_json({
+            "chain": chain,
+            "hash": tx_hash,
+            "decoded": None,
+            "note": "No input data (plain ETH transfer)",
+        })
+        return
+
+    selector = input_data[:10]  # 0x + 4 bytes = 10 chars
+
+    # Query 4byte.directory
+    url = f"https://www.4byte.directory/api/v1/signatures/?hex_signature={selector}"
+    data = _http_get(url)
+
+    signatures = []
+    if data and data.get("results"):
+        signatures = [r["text_signature"] for r in data["results"]]
+
+    # Decode known transfer(address,uint256) manually as fallback
+    decoded_args: Optional[Dict] = None
+    if signatures and len(input_data) >= 74:
+        sig = signatures[0]
+        if sig == "transfer(address,uint256)" and len(input_data) == 138:
+            to_addr = "0x" + input_data[34:74]
+            amount_hex = input_data[74:]
+            try:
+                amount = int(amount_hex, 16)
+                decoded_args = {"to": to_addr, "amount_raw": amount}
+            except Exception:
+                pass
+
+    print_json({
+        "chain": chain,
+        "hash": tx_hash,
+        "selector": selector,
+        "input_length_bytes": (len(input_data) - 2) // 2,
+        "from": tx.get("from"),
+        "to": tx.get("to"),
+        "signatures": signatures,
+        "primary_signature": signatures[0] if signatures else None,
+        "decoded_args": decoded_args,
+        "raw_input_preview": input_data[:74] + ("..." if len(input_data) > 74 else ""),
+        "source": "4byte.directory",
+    })
+
+
+def cmd_ens(args: argparse.Namespace) -> None:
+    """Resolve ENS name <-> address via ensideas.com public API (no key needed)."""
+    query = args.name_or_address
+
+    # ensideas.com handles both forward (name->address) and reverse (address->name)
+    try:
+        data = _http_get(f"https://api.ensideas.com/ens/resolve/{query}")
+    except Exception as exc:
+        print_json({"error": str(exc), "note": "ENS API unavailable"})
+        return
+
+    if not data:
+        print_json({"query": query, "address": None, "ens_name": None, "note": "Not found"})
+        return
+
+    print_json({
+        "query":      query,
+        "address":    data.get("address"),
+        "ens_name":   data.get("name"),
+        "avatar":     data.get("avatar"),
+        "display":    data.get("displayName"),
+        "twitter":    data.get("twitter"),
+        "github":     data.get("github"),
+        "source":     "ensideas.com",
+    })
+
+
+def cmd_contract(args: argparse.Namespace) -> None:
+    """Inspect a smart contract: bytecode size, proxy detection, creation info."""
+    chain = args.chain
+    address = require_address(args.address)
+
+    # Get bytecode
+    code_hex = rpc_call(chain, "eth_getCode", [address, "latest"])
+    if not code_hex or code_hex == "0x":
+        print_json({"chain": chain, "address": address, "is_contract": False, "note": "EOA (externally owned account)"})
+        return
+
+    bytecode_bytes = (len(code_hex) - 2) // 2
+
+    # Proxy detection patterns
+    # EIP-1967: implementation slot 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc
+    impl_slot = "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc"
+    impl_raw = rpc_call(chain, "eth_getStorageAt", [address, impl_slot, "latest"])
+    implementation = None
+    is_proxy = False
+    if impl_raw and impl_raw != "0x" and int(impl_raw, 16) != 0:
+        is_proxy = True
+        implementation = "0x" + impl_raw[-40:]
+
+    # EIP-1167 minimal proxy detection (starts with 0x363d3d37)
+    if code_hex[2:10] == "363d3d37" or code_hex[2:18] == "3d602d80600a3d39":
+        is_proxy = True
+
+    # supportsInterface check: ERC-165
+    supports_erc165 = False
+    try:
+        erc165_data = "0x01ffc9a701ffc9a700000000000000000000000000000000000000000000000000000000"
+        erc165_raw = rpc_call(chain, "eth_call", [{"to": address, "data": erc165_data}, "latest"])
+        supports_erc165 = bool(erc165_raw and erc165_raw != "0x" and int(erc165_raw, 16) == 1)
+    except Exception:
+        pass
+
+    # Try to detect ERC-20 (has totalSupply)
+    is_erc20 = False
+    try:
+        ts_raw = eth_call_erc20(chain, address, "totalSupply()")
+        is_erc20 = ts_raw is not None and ts_raw != "0x" and int(ts_raw, 16) > 0
+    except Exception:
+        pass
+
+    # Try to detect ERC-721 (supportsInterface 0x80ac58cd)
+    is_erc721 = False
+    try:
+        erc721_data = "0x01ffc9a780ac58cd00000000000000000000000000000000000000000000000000000000"
+        erc721_raw = rpc_call(chain, "eth_call", [{"to": address, "data": erc721_data}, "latest"])
+        is_erc721 = bool(erc721_raw and erc721_raw != "0x" and int(erc721_raw, 16) == 1)
+    except Exception:
+        pass
+
+    detected_standards = []
+    if is_erc20:
+        detected_standards.append("ERC-20")
+    if is_erc721:
+        detected_standards.append("ERC-721")
+    if supports_erc165:
+        detected_standards.append("ERC-165")
+
+    print_json({
+        "chain": chain,
+        "address": address,
+        "is_contract": True,
+        "bytecode_size_bytes": bytecode_bytes,
+        "is_proxy": is_proxy,
+        "implementation": implementation,
+        "detected_standards": detected_standards,
+        "explorer_url": f"{CHAINS[chain]['explorer']}/address/{address}",
+        "note": "Proxy detected via EIP-1967 storage slot. Standards via EIP-165 + heuristics." if is_proxy else None,
+    })
+
+
+# ---------------------------------------------------------------------------
+# Argument parsing & dispatch
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    chain_choices = list(CHAINS.keys())
+
+    parser = argparse.ArgumentParser(
+        prog="evm_client",
+        description="EVM blockchain CLI — stdlib only, zero dependencies.",
+    )
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+    sub.required = True
+
+    # -- stats --
+    p_stats = sub.add_parser("stats", help="Chain stats: block, gas price, native price, TPS")
+    p_stats.add_argument("--chain", default=DEFAULT_CHAIN, choices=chain_choices)
+
+    # -- wallet --
+    p_wallet = sub.add_parser("wallet", help="Wallet balance + ERC-20 portfolio")
+    p_wallet.add_argument("address", help="Wallet address (0x...)")
+    p_wallet.add_argument("--limit",     type=int, default=20, metavar="N",
+                          help="Max number of known tokens to check (default: 20)")
+    p_wallet.add_argument("--no-prices", action="store_true",
+                          help="Skip USD price lookups (faster)")
+    p_wallet.add_argument("--chain", default=DEFAULT_CHAIN, choices=chain_choices)
+
+    # -- tx --
+    p_tx = sub.add_parser("tx", help="Transaction details")
+    p_tx.add_argument("hash", help="Transaction hash (0x...)")
+    p_tx.add_argument("--chain", default=DEFAULT_CHAIN, choices=chain_choices)
+
+    # -- token --
+    p_token = sub.add_parser("token", help="ERC-20 token metadata + price")
+    p_token.add_argument("contract", help="Token contract address (0x...)")
+    p_token.add_argument("--chain", default=DEFAULT_CHAIN, choices=chain_choices)
+
+    # -- activity --
+    p_act = sub.add_parser("activity", help="Recent transactions for an address")
+    p_act.add_argument("address", help="Wallet address (0x...)")
+    p_act.add_argument("--limit", type=int, default=10, metavar="N",
+                       help="Max transactions to return (default: 10)")
+    p_act.add_argument("--chain", default=DEFAULT_CHAIN, choices=chain_choices)
+
+    # -- gas --
+    p_gas = sub.add_parser("gas", help="Gas prices and cost estimates")
+    p_gas.add_argument("--chain", default=DEFAULT_CHAIN, choices=chain_choices)
+
+    # -- price --
+    p_price = sub.add_parser("price", help="Token price by symbol or contract address")
+    p_price.add_argument("token", help="Symbol (e.g. ETH, USDC) or contract address")
+    p_price.add_argument("--chain", default=DEFAULT_CHAIN, choices=chain_choices)
+
+    # -- compare --
+    sub.add_parser("compare", help="Gas + native prices across ALL chains simultaneously")
+
+    # -- whale --
+    p_whale = sub.add_parser("whale", help="Scan for large value transfers in recent blocks")
+    p_whale.add_argument("--blocks",  type=int, default=20, metavar="N",
+                         help="Number of recent blocks to scan (default: 20)")
+    p_whale.add_argument("--min-usd", type=float, default=10_000.0, metavar="N",
+                         help="Minimum USD value to report (default: 10000)")
+    p_whale.add_argument("--chain", default=DEFAULT_CHAIN, choices=chain_choices)
+
+    # -- multichain --
+    p_multi = sub.add_parser("multichain", help="Scan same wallet across ALL chains simultaneously")
+    p_multi.add_argument("address", help="Wallet address (0x...)")
+
+    # -- allowance --
+    p_allow = sub.add_parser("allowance", help="Check dangerous ERC-20 approvals (known DEX/bridge spenders)")
+    p_allow.add_argument("address", help="Wallet address (0x...)")
+    p_allow.add_argument("--chain", default=DEFAULT_CHAIN, choices=chain_choices)
+
+    # -- decode --
+    p_decode = sub.add_parser("decode", help="Decode transaction input data via 4byte.directory")
+    p_decode.add_argument("hash", help="Transaction hash (0x...)")
+    p_decode.add_argument("--chain", default=DEFAULT_CHAIN, choices=chain_choices)
+
+    # -- ens --
+    p_ens = sub.add_parser("ens", help="Resolve ENS name <-> address (Ethereum only)")
+    p_ens.add_argument("name_or_address", help="ENS name (vitalik.eth) or address (0x...)")
+
+    # -- contract --
+    p_contract = sub.add_parser("contract", help="Inspect a smart contract: proxy, standards, bytecode size")
+    p_contract.add_argument("address", help="Contract address (0x...)")
+    p_contract.add_argument("--chain", default=DEFAULT_CHAIN, choices=chain_choices)
+
+    return parser
+
+
+DISPATCH = {
+    "stats":      cmd_stats,
+    "wallet":     cmd_wallet,
+    "tx":         cmd_tx,
+    "token":      cmd_token,
+    "activity":   cmd_activity,
+    "gas":        cmd_gas,
+    "price":      cmd_price,
+    "compare":    cmd_compare,
+    "whale":      cmd_whale,
+    "multichain": cmd_multichain,
+    "allowance":  cmd_allowance,
+    "decode":     cmd_decode,
+    "ens":        cmd_ens,
+    "contract":   cmd_contract,
+}
+
+
+def main() -> None:
+    parser = build_parser()
+    args   = parser.parse_args()
+
+    # Validate chain exists (argparse choices already handles this, but for ENV override)
+    if hasattr(args, "chain") and args.chain not in CHAINS:
+        print_json({"error": f"Unknown chain '{args.chain}'. Available: {list(CHAINS.keys())}"})
+        sys.exit(1)
+
+    cmd_fn = DISPATCH.get(args.command)
+    if cmd_fn is None:
+        print_json({"error": f"Unknown command '{args.command}'"})
+        sys.exit(1)
+
+    try:
+        cmd_fn(args)
+    except KeyboardInterrupt:
+        print_json({"error": "Interrupted by user"})
+        sys.exit(130)
+    except Exception as e:
+        print_json({"error": str(e)})
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()