web3-tools-mcp 1.3.4 → 1.5.0

package/src/anvil.ts

@@ -0,0 +1,323 @@
+import { spawn, ChildProcess } from 'child_process'
+import { createPublicClient, http } from 'viem'
+import { mainnet } from 'viem/chains'
+
+export interface AnvilInstance {
+  process: ChildProcess
+  port: number
+  rpcUrl: string
+  client: ReturnType<typeof createPublicClient>
+}
+
+export interface AnvilConfig {
+  forkUrl: string
+  forkBlockNumber?: bigint
+  port?: number
+  chainId?: number
+}
+
+// Check if anvil is installed
+export async function isAnvilInstalled(): Promise<boolean> {
+  return new Promise(resolve => {
+    const proc = spawn('anvil', ['--version'], { shell: true })
+    proc.on('close', code => resolve(code === 0))
+    proc.on('error', () => resolve(false))
+  })
+}
+
+// Find an available port
+async function findAvailablePort(startPort: number = 8545): Promise<number> {
+  const net = await import('net')
+  return new Promise((resolve, reject) => {
+    const server = net.createServer()
+    server.listen(startPort, () => {
+      const address = server.address()
+      if (address && typeof address === 'object') {
+        server.close(() => resolve(address.port))
+      } else {
+        server.close(() => reject(new Error('Could not get port')))
+      }
+    })
+    server.on('error', () => {
+      // Port in use, try next one
+      findAvailablePort(startPort + 1).then(resolve).catch(reject)
+    })
+  })
+}
+
+// Start an Anvil instance
+export async function startAnvil(config: AnvilConfig): Promise<AnvilInstance> {
+  const installed = await isAnvilInstalled()
+  if (!installed) {
+    throw new Error(
+      'Anvil is not installed. Please install Foundry: https://book.getfoundry.sh/getting-started/installation'
+    )
+  }
+
+  const port = config.port ?? (await findAvailablePort())
+  const rpcUrl = `http://127.0.0.1:${port}`
+
+  const args = ['--fork-url', config.forkUrl, '--port', port.toString(), '--silent']
+
+  if (config.forkBlockNumber !== undefined) {
+    args.push('--fork-block-number', config.forkBlockNumber.toString())
+  }
+
+  if (config.chainId !== undefined) {
+    args.push('--chain-id', config.chainId.toString())
+  }
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn('anvil', args, {
+      shell: true,
+      stdio: ['ignore', 'pipe', 'pipe']
+    })
+
+    let stderr = ''
+    proc.stderr?.on('data', data => {
+      stderr += data.toString()
+    })
+
+    proc.on('error', err => {
+      reject(new Error(`Failed to start Anvil: ${err.message}`))
+    })
+
+    proc.on('close', code => {
+      if (code !== 0 && code !== null) {
+        reject(new Error(`Anvil exited with code ${code}: ${stderr}`))
+      }
+    })
+
+    // Wait for Anvil to be ready by polling the RPC
+    const maxAttempts = 50 // 5 seconds
+    let attempts = 0
+
+    const checkReady = async () => {
+      attempts++
+      try {
+        const response = await fetch(rpcUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            method: 'eth_blockNumber',
+            params: [],
+            id: 1
+          })
+        })
+        if (response.ok) {
+          // Add small delay to ensure all RPC methods are ready (including debug_*)
+          await new Promise(r => setTimeout(r, 100))
+          const client = createPublicClient({
+            chain: mainnet, // Chain is overridden by fork anyway
+            transport: http(rpcUrl)
+          })
+          resolve({ process: proc, port, rpcUrl, client })
+        } else if (attempts < maxAttempts) {
+          setTimeout(checkReady, 100)
+        } else {
+          proc.kill()
+          reject(new Error('Anvil failed to start within timeout'))
+        }
+      } catch {
+        if (attempts < maxAttempts) {
+          setTimeout(checkReady, 100)
+        } else {
+          proc.kill()
+          reject(new Error('Anvil failed to start within timeout'))
+        }
+      }
+    }
+
+    // Start checking after a small delay
+    setTimeout(checkReady, 200)
+  })
+}
+
+// Stop an Anvil instance
+export function stopAnvil(instance: AnvilInstance): void {
+  if (instance.process && !instance.process.killed) {
+    instance.process.kill('SIGTERM')
+  }
+}
+
+// Helper to run a function with a temporary Anvil instance
+export async function withAnvil<T>(
+  config: AnvilConfig,
+  fn: (instance: AnvilInstance) => Promise<T>
+): Promise<T> {
+  const instance = await startAnvil(config)
+  try {
+    return await fn(instance)
+  } finally {
+    stopAnvil(instance)
+  }
+}
+
+// Archive RPC URLs for chains that need historical state access
+const ARCHIVE_RPCS: Record<string, string> = {
+  arbitrum: 'https://arbitrum-one.arpc.x.superfluid.dev'
+}
+
+// Trace a transaction using Anvil fork
+export async function traceTransactionWithAnvil(
+  forkUrl: string,
+  transactionHash: string,
+  blockNumber: bigint,
+  tracer: 'callTracer' | 'prestateTracer' | 'stateDiffTracer' = 'callTracer',
+  chainName?: string
+): Promise<unknown> {
+  // Use archive RPC if available for better historical state access
+  const archiveUrl = chainName && ARCHIVE_RPCS[chainName] ? ARCHIVE_RPCS[chainName] : forkUrl
+
+  // First, fetch the original transaction from the RPC
+  const fetchClient = createPublicClient({
+    chain: mainnet,
+    transport: http(forkUrl)
+  })
+
+  const tx = await fetchClient.getTransaction({
+    hash: transactionHash as `0x${string}`
+  })
+
+  if (!tx) {
+    throw new Error(`Transaction ${transactionHash} not found`)
+  }
+
+  // Fork at the block BEFORE the transaction to replay it accurately
+  // Note: This requires an archival RPC that has historical state
+  const forkBlock = blockNumber > 0n ? blockNumber - 1n : 0n
+
+  return withAnvil(
+    {
+      forkUrl: archiveUrl,
+      forkBlockNumber: forkBlock
+    },
+    async instance => {
+      // Use debug_traceCall to simulate and trace the transaction
+      // Note: This replays the tx against the post-block state, which may differ slightly
+      // from the original execution if state changed within the block
+      const trace = await instance.client.request({
+        method: 'debug_traceCall' as never,
+        params: [
+          {
+            from: tx.from,
+            to: tx.to,
+            data: tx.input,
+            value: tx.value ? `0x${tx.value.toString(16)}` : '0x0',
+            gas: tx.gas ? `0x${tx.gas.toString(16)}` : undefined
+          },
+          'latest',
+          { tracer }
+        ] as never
+      })
+
+      return trace
+    }
+  )
+}
+
+// Simulate a call with tracing
+export interface SimulateCallParams {
+  to: string
+  data?: string
+  from?: string
+  value?: bigint
+  gas?: bigint
+}
+
+export async function simulateCallWithTrace(
+  forkUrl: string,
+  params: SimulateCallParams,
+  blockNumber?: bigint,
+  tracer: 'callTracer' | 'prestateTracer' = 'callTracer'
+): Promise<{
+  result: string
+  trace: unknown
+  gasUsed: bigint
+  success: boolean
+  revertReason?: string
+}> {
+  return withAnvil(
+    {
+      forkUrl,
+      forkBlockNumber: blockNumber
+    },
+    async instance => {
+      // First, try a regular call to get the result
+      let result = '0x'
+      let success = true
+      let revertReason: string | undefined
+      let gasUsed = 0n
+
+      try {
+        // Use eth_call to get the result
+        result = (await instance.client.request({
+          method: 'eth_call' as never,
+          params: [
+            {
+              to: params.to,
+              data: params.data,
+              from: params.from ?? '0x0000000000000000000000000000000000000000',
+              value: params.value ? `0x${params.value.toString(16)}` : undefined,
+              gas: params.gas ? `0x${params.gas.toString(16)}` : undefined
+            },
+            'latest'
+          ] as never
+        })) as string
+
+        // Estimate gas
+        try {
+          gasUsed = await instance.client.estimateGas({
+            to: params.to as `0x${string}`,
+            data: params.data as `0x${string}` | undefined,
+            account: params.from as `0x${string}` | undefined,
+            value: params.value
+          })
+        } catch {
+          // Ignore gas estimation errors
+        }
+      } catch (error) {
+        success = false
+        const errorMessage = (error as Error).message
+        // Try to extract revert reason
+        const revertMatch = errorMessage.match(/revert(?:ed)?[:\s]*(.+?)(?:\n|$)/i)
+        if (revertMatch) {
+          revertReason = revertMatch[1].trim()
+        } else {
+          revertReason = errorMessage
+        }
+      }
+
+      // Get the trace using debug_traceCall
+      let trace: unknown = null
+      try {
+        trace = await instance.client.request({
+          method: 'debug_traceCall' as never,
+          params: [
+            {
+              to: params.to,
+              data: params.data,
+              from: params.from ?? '0x0000000000000000000000000000000000000000',
+              value: params.value ? `0x${params.value.toString(16)}` : undefined,
+              gas: params.gas ? `0x${params.gas.toString(16)}` : undefined
+            },
+            'latest',
+            { tracer }
+          ] as never
+        })
+      } catch (traceError) {
+        // If tracing fails, include the error
+        trace = { error: (traceError as Error).message }
+      }
+
+      return {
+        result,
+        trace,
+        gasUsed,
+        success,
+        revertReason
+      }
+    }
+  )
+}

package/src/chain-meta.ts

@@ -0,0 +1,102 @@
+/**
+ * On-chain metadata every layer of the preview needs: contract ABIs, token symbols and
+ * human labels for addresses. Kept apart from the preview and the clear-signing registry
+ * so both can use it without importing each other.
+ */
+import { type Abi, type Address, parseAbiItem } from 'viem'
+import { whatsabi } from '@shazow/whatsabi'
+import { getClientManager } from './client.js'
+import type { ChainName } from './types.js'
+
+const ERC20_META_ABI = [
+  parseAbiItem('function decimals() view returns (uint8)'),
+  parseAbiItem('function symbol() view returns (string)')
+]
+
+const abiCache = new Map<string, { abi: Abi; source: 'verified' | 'guessed'; proxy?: string; name?: string }>()
+const labelCache = new Map<string, string | undefined>()
+const metaCache = new Map<string, { symbol?: string; decimals?: number }>()
+
+export async function loadAbi(chain: ChainName, address: string) {
+  const key = `${chain}:${address.toLowerCase()}`
+  const cached = abiCache.get(key)
+  if (cached) return cached
+
+  const clientManager = getClientManager()
+  const client = clientManager.getClient(chain)
+  const etherscanApiKey = clientManager.getConfig().etherscanApiKey
+
+  const loaders: whatsabi.loaders.ABILoader[] = [new whatsabi.loaders.SourcifyABILoader({ chainId: clientManager.getChainId(chain) })]
+  if (etherscanApiKey) {
+    loaders.push(new whatsabi.loaders.EtherscanV2ABILoader({ apiKey: etherscanApiKey, chainId: clientManager.getChainId(chain) }))
+  }
+
+  const result = await whatsabi.autoload(address as Address, {
+    provider: client,
+    abiLoader: new whatsabi.loaders.MultiABILoader(loaders),
+    signatureLookup: new whatsabi.loaders.OpenChainSignatureLookup(),
+    followProxies: true
+  })
+
+  // Bytecode-guessed ABIs carry no argument names; verified ones do.
+  const source = result.abi.some((item) => item.type === 'function' && item.inputs?.some((i) => i.name)) ? 'verified' : 'guessed'
+  const loaded = {
+    abi: result.abi as Abi,
+    source: source as 'verified' | 'guessed',
+    proxy: result.address !== address ? result.address : undefined,
+    name: result.contractResult?.name ?? undefined
+  }
+  abiCache.set(key, loaded)
+  return loaded
+}
+
+export async function tokenMeta(chain: ChainName, token: string) {
+  const key = `${chain}:${token.toLowerCase()}`
+  const cached = metaCache.get(key)
+  if (cached) return cached
+
+  const client = getClientManager().getClient(chain)
+  const [decimals, symbol] = await client.multicall({
+    contracts: [
+      { address: token as Address, abi: ERC20_META_ABI, functionName: 'decimals' },
+      { address: token as Address, abi: ERC20_META_ABI, functionName: 'symbol' }
+    ],
+    ...(chain === 'localhost' && { deployless: true })
+  })
+
+  const meta = {
+    decimals: decimals.status === 'success' ? Number(decimals.result) : undefined,
+    symbol: symbol.status === 'success' ? (symbol.result as string) : undefined
+  }
+  metaCache.set(key, meta)
+  return meta
+}
+
+/**
+ * Human label for an address: token symbol first (more recognisable than the contract
+ * name — "USDC" beats "FiatTokenProxy"), then the verified contract name. EOAs get none,
+ * and the bytecode check keeps us from asking explorers about plain wallets.
+ */
+export async function addressLabel(chain: ChainName, address: string): Promise<string | undefined> {
+  const key = `${chain}:${address.toLowerCase()}`
+  if (labelCache.has(key)) return labelCache.get(key)
+
+  let label: string | undefined
+  try {
+    const code = await getClientManager().getClient(chain).getBytecode({ address: address as Address })
+    if (code && code !== '0x') {
+      label = (await tokenMeta(chain, address).catch(() => ({ symbol: undefined }))).symbol
+      if (!label) label = (await loadAbi(chain, address)).name
+    }
+  } catch {
+    // Unknown address — show it bare rather than failing the preview.
+  }
+
+  labelCache.set(key, label)
+  return label
+}
+
+
+/** uint256 max and anything near it means "infinite" in an approval. */
+export const MAX_UINT256 = (1n << 256n) - 1n
+export const UNLIMITED_THRESHOLD = MAX_UINT256 / 2n

package/src/clear-signing.ts

@@ -0,0 +1,206 @@
+import { createRequire } from 'node:module'
+import { gunzipSync } from 'node:zlib'
+import { formatUnits, getAddress, isAddress } from 'viem'
+import { addressLabel, tokenMeta, UNLIMITED_THRESHOLD } from './chain-meta.js'
+import { getClientManager } from './client.js'
+import type { ChainName } from './types.js'
+
+/**
+ * Clear signing from the Ledger ERC-7730 registry: for a known contract and selector it
+ * says what the transaction *means* ("Swap", "Approve spending") and labels each field the
+ * way the protocol intends, instead of showing raw ABI argument names.
+ *
+ * The index is built from the registry by scripts/build-erc7730-index.mjs.
+ */
+
+interface IndexField {
+  // A handful of registry descriptors omit these, so nothing here is guaranteed.
+  label?: string
+  path?: string
+  format?: string
+  /** tokenAmount: `tokenPath` points at the field holding the token address. */
+  params?: { tokenPath?: string; tokenAddress?: string; [k: string]: unknown }
+}
+
+interface IndexSelector {
+  name: string
+  intent: string
+  /** Full signature, needed to ABI-decode the calldata these paths address. */
+  signature?: string
+  fields: IndexField[]
+}
+
+interface IndexEntry {
+  protocol: string
+  chainIds: number[]
+  selectors: Record<string, IndexSelector>
+}
+
+export interface ClearSigningField {
+  label: string
+  format: string
+  value: string
+  address?: string
+  name?: string
+}
+
+export interface ClearSigningInfo {
+  protocol: string
+  intent: string
+  functionName: string
+  fields: ClearSigningField[]
+}
+
+// Prettier names for registry directory slugs; unknown ones read fine as-is.
+const PROTOCOL_LABELS: Record<string, string> = {
+  lifi: 'LI.FI',
+  '1inch': '1inch',
+  uniswap: 'Uniswap',
+  paraswap: 'ParaSwap',
+  cowswap: 'CoW Swap',
+  '0x': '0x Protocol',
+  aave: 'Aave',
+  morpho: 'Morpho',
+  safe: 'Safe',
+  lido: 'Lido',
+  eigenlayer: 'EigenLayer',
+  ens: 'ENS'
+}
+
+const require = createRequire(import.meta.url)
+let index: Record<string, IndexEntry> | undefined
+
+/** Loaded on first use: ~1.5MB of JSON, shipped gzipped at ~60KB. */
+function registry(): Record<string, IndexEntry> {
+  if (!index) {
+    try {
+      const path = require.resolve('./erc7730-index.json.gz')
+      index = JSON.parse(gunzipSync(require('node:fs').readFileSync(path)).toString())
+    } catch {
+      index = {}
+    }
+  }
+  return index as Record<string, IndexEntry>
+}
+
+export function protocolLabel(slug: string): string {
+  return PROTOCOL_LABELS[slug] ?? slug
+}
+
+/** Resolve a registry path ("params.amountIn", "#.to", "[0].value") against decoded args. */
+function getByPath(root: unknown, path: string): unknown {
+  let current: unknown = root
+  for (const part of path.replace(/^[#@]\./, '').split('.')) {
+    if (current == null) return undefined
+    const arrayIndex = part.match(/^\[(\d*)\]$/)
+    if (arrayIndex) {
+      current = Array.isArray(current) ? current[arrayIndex[1] === '' ? 0 : Number(arrayIndex[1])] : undefined
+    } else {
+      current = (current as Record<string, unknown>)[part]
+    }
+  }
+  return current
+}
+
+interface TxContext {
+  to: string
+  value?: string
+  from?: string
+}
+
+function resolvePath(root: unknown, tx: TxContext, path: string): unknown {
+  if (path.startsWith('@.')) {
+    if (path.slice(2) === 'to') return tx.to
+    if (path.slice(2) === 'value') return tx.value
+    if (path.slice(2) === 'from') return tx.from
+    return undefined
+  }
+  return getByPath(root, path)
+}
+
+async function formatField(chain: ChainName, field: IndexField, root: unknown, tx: TxContext): Promise<ClearSigningField> {
+  // A missing format with a token reference still means an amount.
+  const format = field.format ?? (field.params?.tokenPath || field.params?.tokenAddress ? 'tokenAmount' : 'raw')
+  const label = field.label ?? field.path ?? format
+  const raw = field.path ? resolvePath(root, tx, field.path) : undefined
+  const out: ClearSigningField = { label, format, value: '' }
+
+  // Unresolved: show the descriptor's path rather than an empty row.
+  if (raw == null) {
+    out.value = field.path ?? ''
+    return out
+  }
+
+  switch (format) {
+    case 'tokenAmount':
+    case 'amount': {
+      const amount = typeof raw === 'bigint' ? raw : BigInt(raw as string | number)
+      const token =
+        field.params?.tokenAddress ?? (field.params?.tokenPath ? resolvePath(root, tx, field.params.tokenPath) : undefined)
+
+      const meta =
+        typeof token === 'string' && isAddress(token)
+          ? await tokenMeta(chain, token).catch(() => ({ symbol: undefined, decimals: undefined }))
+          : { symbol: undefined, decimals: undefined }
+
+      const symbol = meta.symbol ? ` ${meta.symbol}` : ''
+      out.value = amount > UNLIMITED_THRESHOLD ? `Unlimited${symbol}` : `${formatUnits(amount, meta.decimals ?? 18)}${symbol}`
+      return out
+    }
+
+    case 'addressName':
+    case 'address':
+    case 'tokenName': {
+      if (!isAddress(raw as string)) {
+        out.value = String(raw)
+        return out
+      }
+      const address = getAddress(raw as string)
+      const name = registry()[address.toLowerCase()]?.protocol
+      out.address = address
+      out.name = name ? protocolLabel(name) : await addressLabel(chain, address).catch(() => undefined)
+      out.value = out.name ?? address
+      return out
+    }
+
+    default:
+      out.value = typeof raw === 'bigint' ? raw.toString() : String(raw)
+      return out
+  }
+}
+
+/** Registry entry for a contract, if it is listed for this chain. */
+export function lookupContract(chain: ChainName, address: string): IndexEntry | undefined {
+  const entry = registry()[address.toLowerCase()]
+  if (!entry) return undefined
+  const chainId = getClientManager().getChainId(chain)
+  return entry.chainIds.includes(chainId) ? entry : undefined
+}
+
+/**
+ * Clear-signing info for a transaction, or null when the contract/selector is unlisted.
+ * `decodedArgs` is supplied by the caller, which has already decoded the calldata against
+ * the contract's real ABI — the registry's own signature is only a fallback for naming.
+ */
+export async function resolveClearSigning(
+  chain: ChainName,
+  tx: TxContext & { data?: string },
+  decodedArgs: Record<string, unknown>
+): Promise<ClearSigningInfo | null> {
+  if (!tx.data || tx.data.length < 10) return null
+
+  const entry = lookupContract(chain, tx.to)
+  const format = entry?.selectors[tx.data.slice(0, 10).toLowerCase()]
+  if (!entry || !format) return null
+
+  // Fields with neither a path nor a label carry nothing a signer could read.
+  const usable = format.fields.filter((field) => field.path || field.label)
+  const fields = await Promise.all(usable.map((field) => formatField(chain, field, decodedArgs, tx)))
+
+  return {
+    protocol: protocolLabel(entry.protocol),
+    intent: format.intent,
+    functionName: format.name,
+    fields
+  }
+}

package/src/client.ts

@@ -238,6 +238,10 @@ export class ClientManager {
     return client as ReturnType<typeof createPublicClient>
   }
 
+  getConfig(): Config {
+    return this.config
+  }
+
   getEtherscanDomain(chainName: ChainName): string {
     const domains: Record<ChainName, string> = {
       mainnet: 'etherscan.io',
@@ -256,6 +260,16 @@ export class ClientManager {
     }
     return domains[chainName] || 'etherscan.io'
   }
+
+  getRpcUrl(chainName: ChainName): string {
+    const chains = CHAINS(this.config)
+    return chains[chainName].rpc
+  }
+
+  getChainId(chainName: ChainName): number {
+    const chains = CHAINS(this.config)
+    return chains[chainName].chain.id
+  }
 }
 
 // Export a global client manager instance