web3-tools-mcp 1.3.3 → 1.4.0

package/src/preview.ts

@@ -0,0 +1,320 @@
+import {
+  type Abi,
+  type AbiFunction,
+  type Address,
+  decodeFunctionData,
+  formatEther,
+  formatUnits,
+  parseAbiItem,
+  toFunctionSelector
+} from 'viem'
+import { simulateBlocks } from 'viem/actions'
+import { whatsabi } from '@shazow/whatsabi'
+import { getClientManager } from './client.js'
+import type { ChainName } from './types.js'
+
+export interface PreviewField {
+  name: string
+  type: string
+  value: string
+  warning?: string
+  /** Set when the value is an address, so the UI can link and label it. */
+  address?: string
+  label?: string
+}
+
+export interface AssetChange {
+  token: string
+  symbol?: string
+  decimals?: number
+  from: string
+  to: string
+  amount: string
+  humanAmount?: string
+}
+
+export interface TxPreview {
+  chain: string
+  to: string
+  /** Token symbol or verified contract name for `to`, when we can resolve one. */
+  toLabel?: string
+  /** Block explorer base URL, for linking addresses and tokens. */
+  explorer?: string
+  value?: string
+  valueFormatted?: string
+  decoded?: {
+    functionName: string
+    signature: string
+    fields: PreviewField[]
+    /** 'verified' = ABI from Sourcify/Etherscan, 'guessed' = selector lookup on bytecode */
+    source: 'verified' | 'guessed'
+    proxy?: string
+  }
+  simulation?: {
+    success: boolean
+    gasEstimate?: string
+    error?: string
+    assetChanges: AssetChange[]
+  }
+}
+
+export interface RawTx {
+  to: string
+  data?: string
+  value?: string
+}
+
+const ERC20_META_ABI = [
+  parseAbiItem('function decimals() view returns (uint8)'),
+  parseAbiItem('function symbol() view returns (string)')
+]
+
+const TRANSFER_TOPIC = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
+const MAX_UINT256 = (1n << 256n) - 1n
+const UNLIMITED_THRESHOLD = MAX_UINT256 / 2n
+
+// Selectors whose amount argument is denominated in the token at tx.to.
+const ERC20_AMOUNT_ARGS: Record<string, { arg: string; approval?: boolean }> = {
+  [toFunctionSelector('function approve(address,uint256)')]: { arg: 'amount', approval: true },
+  [toFunctionSelector('function transfer(address,uint256)')]: { arg: 'amount' },
+  [toFunctionSelector('function transferFrom(address,address,uint256)')]: { arg: 'amount' }
+}
+
+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 }>()
+
+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
+}
+
+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.
+ */
+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
+}
+
+function stringify(value: unknown): string {
+  if (typeof value === 'bigint') return value.toString()
+  if (Array.isArray(value)) return `[${value.map(stringify).join(', ')}]`
+  if (value && typeof value === 'object') {
+    return `{${Object.entries(value)
+      .map(([k, v]) => `${k}: ${stringify(v)}`)
+      .join(', ')}}`
+  }
+  return String(value)
+}
+
+/**
+ * Decode calldata into labelled fields (clear signing). Token amounts on the standard
+ * ERC20 selectors are formatted with on-chain decimals and unlimited approvals flagged.
+ */
+async function decodeCalldata(chain: ChainName, tx: RawTx): Promise<TxPreview['decoded']> {
+  if (!tx.data || tx.data === '0x') return undefined
+
+  const { abi, source, proxy } = await loadAbi(chain, tx.to)
+  const { functionName, args } = decodeFunctionData({ abi, data: tx.data as `0x${string}` })
+
+  const abiItem = abi.find((item): item is AbiFunction => item.type === 'function' && item.name === functionName)
+  const inputs = abiItem?.inputs ?? []
+  const erc20 = ERC20_AMOUNT_ARGS[tx.data.slice(0, 10)]
+  const meta = erc20 ? await tokenMeta(chain, tx.to).catch(() => ({ symbol: undefined, decimals: undefined })) : undefined
+
+  const fields: PreviewField[] = (args ?? []).map((value, i) => {
+    const input = inputs[i]
+    const name = input?.name || `arg${i}`
+    const field: PreviewField = { name, type: input?.type ?? 'unknown', value: stringify(value) }
+
+    if (input?.type === 'address' && typeof value === 'string') field.address = value
+
+    // Amount argument is positionally last on all three ERC20 selectors.
+    if (erc20 && i === (args as readonly unknown[]).length - 1 && typeof value === 'bigint') {
+      if (meta?.decimals !== undefined) {
+        field.value = `${formatUnits(value, meta.decimals)}${meta.symbol ? ` ${meta.symbol}` : ''}`
+      }
+      if (erc20.approval && value > UNLIMITED_THRESHOLD) {
+        field.value = `Unlimited${meta?.symbol ? ` ${meta.symbol}` : ''}`
+        field.warning = 'Unlimited spending approval'
+      }
+    }
+    return field
+  })
+
+  // Label every address argument at once rather than serially per field.
+  await Promise.all(
+    fields
+      .filter((field) => field.address)
+      .map(async (field) => {
+        field.label = await addressLabel(chain, field.address as string)
+      })
+  )
+
+  const signature = abiItem
+    ? `${functionName}(${inputs.map((i) => `${i.type}${i.name ? ` ${i.name}` : ''}`).join(', ')})`
+    : functionName
+
+  return { functionName, signature, fields, source, proxy }
+}
+
+function topicToAddress(topic: string): string {
+  return `0x${topic.slice(-40)}`
+}
+
+async function enrichTransfers(chain: ChainName, logs: readonly { address: string; topics: readonly string[]; data: string }[]) {
+  const transfers = logs.filter((log) => log.topics[0]?.toLowerCase() === TRANSFER_TOPIC && log.topics.length >= 3)
+
+  return Promise.all(
+    transfers.map(async (log): Promise<AssetChange> => {
+      const amount = log.data && log.data !== '0x' ? BigInt(log.data).toString() : '0'
+      const meta = await tokenMeta(chain, log.address).catch(() => ({ symbol: undefined, decimals: undefined }))
+      return {
+        token: log.address,
+        symbol: meta.symbol,
+        decimals: meta.decimals,
+        from: topicToAddress(log.topics[1]!),
+        to: topicToAddress(log.topics[2]!),
+        amount,
+        humanAmount: meta.decimals !== undefined ? formatUnits(BigInt(amount), meta.decimals) : undefined
+      }
+    })
+  )
+}
+
+/**
+ * Simulate a transaction without broadcasting.
+ *
+ * Prefers eth_simulateV1 (viem `simulateBlocks`) for the ERC20 transfer logs it returns,
+ * falling back to eth_call + estimateGas on RPCs that don't implement it.
+ */
+async function simulate(chain: ChainName, tx: RawTx, from: Address): Promise<TxPreview['simulation']> {
+  const client = getClientManager().getClient(chain)
+  const call = {
+    account: from,
+    to: tx.to as Address,
+    ...(tx.data && { data: tx.data as `0x${string}` }),
+    ...(tx.value && BigInt(tx.value) > 0n && { value: BigInt(tx.value) })
+  }
+
+  try {
+    const blocks = await simulateBlocks(client, { blocks: [{ calls: [call] }], traceTransfers: true, validation: false })
+    const result = blocks?.[0]?.calls?.[0]
+    if (result) {
+      const error = result.error as { shortMessage?: string; message?: string } | undefined
+      return {
+        success: result.status === 'success',
+        gasEstimate: result.gasUsed?.toString(),
+        error: result.status === 'success' ? undefined : (error?.shortMessage ?? error?.message ?? 'execution reverted'),
+        assetChanges: await enrichTransfers(chain, (result.logs ?? []) as never)
+      }
+    }
+  } catch {
+    // RPC lacks eth_simulateV1 — fall through
+  }
+
+  try {
+    await client.call(call)
+    const gas = await client.estimateGas(call)
+    return { success: true, gasEstimate: gas.toString(), assetChanges: [] }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message.slice(0, 500) : String(error),
+      assetChanges: []
+    }
+  }
+}
+
+/**
+ * Build the human-readable preview shown in the wallet before signing: decoded calldata
+ * plus a simulation of the outcome. Never throws — a preview that cannot be built is
+ * reported as missing rather than blocking the transaction.
+ */
+export async function buildTxPreview(chain: ChainName, tx: RawTx, from?: string): Promise<TxPreview> {
+  const value = tx.value ? BigInt(tx.value).toString() : undefined
+
+  const [decoded, simulation, toLabel] = await Promise.all([
+    decodeCalldata(chain, tx).catch(() => undefined),
+    from ? simulate(chain, tx, from as Address).catch(() => undefined) : Promise.resolve(undefined),
+    addressLabel(chain, tx.to).catch(() => undefined)
+  ])
+
+  return {
+    chain,
+    to: tx.to,
+    toLabel,
+    explorer: `https://${getClientManager().getEtherscanDomain(chain)}`,
+    value,
+    valueFormatted: value && value !== '0' ? formatEther(BigInt(value)) : undefined,
+    decoded,
+    simulation
+  }
+}

package/src/tools/advanced.ts

@@ -2,7 +2,12 @@ import { type Address, decodeAbiParameters, isAddress, parseAbiParameters } from
 import { z } from 'zod'
 import type { ChainName } from '../types.js'
 import { getClientManager, SUPPORTED_CHAINS } from '../client.js'
-import { createTool, formatResponse } from '../utils.js'
+import { createTool, formatResponse, summarizeTrace } from '../utils.js'
+import {
+  isAnvilInstalled,
+  traceTransactionWithAnvil,
+  simulateCallWithTrace
+} from '../anvil.js'
 
 export default {
   get_storage_at: createTool(
@@ -162,7 +167,17 @@ export default {
         .describe(
           'Trace type: "trace" (call tree, recommended), "vmTrace" (VM execution), "stateDiff" (state changes)'
         )
-        .default('trace')
+        .default('trace'),
+      useAnvil: z
+        .boolean()
+        .optional()
+        .describe('Force using Anvil for tracing (requires Foundry installed). Auto-used as fallback when RPC tracing fails.')
+        .default(false),
+      summarize: z
+        .boolean()
+        .optional()
+        .describe('Return a compact summary instead of full trace. Truncates hex data and flattens nested calls.')
+        .default(false)
     }),
     async (args) => {
       const clientManager = getClientManager()
@@ -174,89 +189,243 @@ export default {
         const receipt = await client.getTransactionReceipt({ hash: args.transactionHash as `0x${string}` })
 
         let traceResult: unknown = null
+        let usedAnvil = false
 
-        // Perform the requested trace type
-        switch (args.traceType) {
-          case 'trace':
-            try {
-              // Use debug_traceTransaction for call trace
-              traceResult = await client.request({
-                method: 'debug_traceTransaction',
-                params: [args.transactionHash, { tracer: 'callTracer' }]
-              })
-            } catch (e) {
-              traceResult = { error: (e as Error).message }
-            }
-            break
+        // Map trace type to tracer name
+        const tracerMap: Record<string, 'callTracer' | 'prestateTracer' | 'stateDiffTracer'> = {
+          trace: 'callTracer',
+          vmTrace: 'prestateTracer',
+          stateDiff: 'stateDiffTracer'
+        }
+        const tracer = tracerMap[args.traceType ?? 'trace'] ?? 'callTracer'
 
-          case 'vmTrace':
-            try {
-              traceResult = await client.request({
-                method: 'debug_traceTransaction',
-                params: [args.transactionHash, { tracer: 'prestateTracer' }]
-              })
-            } catch (e) {
-              traceResult = { error: (e as Error).message }
+        // Try RPC tracing first (unless forceAnvil is true)
+        if (!args.useAnvil) {
+          try {
+            traceResult = await client.request({
+              method: 'debug_traceTransaction',
+              params: [args.transactionHash, { tracer }]
+            })
+          } catch (rpcError) {
+            // RPC tracing failed, will try Anvil fallback
+            const errorMessage = (rpcError as Error).message
+            if (
+              errorMessage.includes('not supported') ||
+              errorMessage.includes('not available') ||
+              errorMessage.includes('method not found') ||
+              errorMessage.includes('does not exist')
+            ) {
+              // This is an expected error for public RPCs, try Anvil
+              traceResult = null
+            } else {
+              // Other error, store it but still try Anvil
+              traceResult = { rpcError: errorMessage }
             }
-            break
+          }
+        }
 
-          case 'stateDiff':
+        // Fallback to Anvil if RPC tracing failed or was skipped
+        if (traceResult === null || (traceResult && typeof traceResult === 'object' && 'rpcError' in traceResult) || args.useAnvil) {
+          const anvilAvailable = await isAnvilInstalled()
+          if (anvilAvailable) {
+            usedAnvil = true // Mark as used before attempting (even if it fails)
             try {
-              traceResult = await client.request({
-                method: 'debug_traceTransaction',
-                params: [args.transactionHash, { tracer: 'stateDiffTracer' }]
-              })
-            } catch (e) {
-              traceResult = { error: (e as Error).message }
-            }
-            break
+              const forkUrl = clientManager.getRpcUrl(args.chain as ChainName)
+              const blockNumber = transaction.blockNumber ?? 0n
 
-          default:
+              traceResult = await traceTransactionWithAnvil(
+                forkUrl,
+                args.transactionHash,
+                blockNumber,
+                tracer,
+                args.chain
+              )
+            } catch (anvilError) {
+              // Anvil tracing also failed
+              traceResult = {
+                error: `Anvil tracing failed: ${(anvilError as Error).message}`,
+                rpcError: traceResult && typeof traceResult === 'object' && 'rpcError' in traceResult
+                  ? (traceResult as { rpcError: string }).rpcError
+                  : 'RPC does not support debug_traceTransaction'
+              }
+            }
+          } else if (!traceResult || (typeof traceResult === 'object' && 'rpcError' in traceResult)) {
+            // Anvil not available and RPC failed
             traceResult = {
-              type: 'CALL',
-              from: transaction.from,
-              to: transaction.to,
-              value: transaction.value?.toString() || '0',
-              gas: transaction.gas?.toString() || '0',
-              gasUsed: receipt.gasUsed?.toString() || '0',
-              input: transaction.input,
-              output: '0x',
-              error: receipt.status === 'success' ? null : 'Transaction failed'
+              error: 'Tracing not available. Install Foundry (anvil) for local tracing: https://book.getfoundry.sh/getting-started/installation',
+              rpcError: traceResult && typeof traceResult === 'object' && 'rpcError' in traceResult
+                ? (traceResult as { rpcError: string }).rpcError
+                : 'RPC does not support debug_traceTransaction'
             }
+          }
         }
 
-        const result = {
-          success: true,
-          chain: args.chain,
-          transactionHash: args.transactionHash,
-          traceType: args.traceType,
-          transaction: {
-            blockNumber: transaction.blockNumber?.toString(),
-            from: transaction.from,
-            to: transaction.to,
-            value: transaction.value?.toString() || '0',
-            gas: transaction.gas?.toString() || '0',
-            gasPrice: transaction.gasPrice?.toString() || '0',
-            nonce: transaction.nonce?.toString() || '0',
-            input: transaction.input
-          },
-          receipt: {
-            status: receipt.status,
-            gasUsed: receipt.gasUsed?.toString() || '0',
-            effectiveGasPrice: receipt.effectiveGasPrice?.toString() || '0',
-            logs: receipt.logs.map(log => ({
-              address: log.address,
-              topics: log.topics,
-              data: log.data
-            }))
-          },
-          trace: traceResult
-        }
+        // Apply summarization if requested - focused on finding reverts
+        // Skip summarization only if traceResult is a plain error object (not a call trace with an error field)
+        const isPlainError = traceResult && typeof traceResult === 'object' &&
+          'error' in traceResult && !('type' in traceResult) && !('calls' in traceResult)
+        const traceSummary = args.summarize && traceResult && typeof traceResult === 'object' && !isPlainError
+          ? summarizeTrace(traceResult)
+          : null
+
+        const result = args.summarize && traceSummary
+          ? {
+              chain: args.chain,
+              transactionHash: args.transactionHash,
+              status: receipt.status,
+              gasUsed: receipt.gasUsed?.toString(),
+              ...traceSummary // { hasError, errorPath, summary }
+            }
+          : {
+              success: true,
+              chain: args.chain,
+              transactionHash: args.transactionHash,
+              traceType: args.traceType,
+              usedAnvil,
+              transaction: {
+                blockNumber: transaction.blockNumber?.toString(),
+                from: transaction.from,
+                to: transaction.to,
+                value: transaction.value?.toString() || '0',
+                gas: transaction.gas?.toString() || '0',
+                gasPrice: transaction.gasPrice?.toString() || '0',
+                nonce: transaction.nonce?.toString() || '0',
+                input: transaction.input
+              },
+              receipt: {
+                status: receipt.status,
+                gasUsed: receipt.gasUsed?.toString() || '0',
+                effectiveGasPrice: receipt.effectiveGasPrice?.toString() || '0',
+                logs: receipt.logs.map(log => ({
+                  address: log.address,
+                  topics: log.topics,
+                  data: log.data
+                }))
+              },
+              trace: traceResult
+            }
 
         return formatResponse(result)
       } catch (error) {
         throw new Error(`Transaction trace failed: ${error}`)
       }
     }
+  ),
+
+  debug_call: createTool(
+    'Debug Contract Call',
+    'Simulate a contract call with full trace output. Requires Foundry (anvil) installed. Useful for debugging reverts and understanding call execution.',
+    z.object({
+      chain: z.enum(SUPPORTED_CHAINS).describe('The blockchain network to fork'),
+      to: z.string().describe('Contract address to call'),
+      data: z.string().optional().describe('Calldata (hex encoded). Either provide this or functionAbi + args.'),
+      functionAbi: z
+        .string()
+        .optional()
+        .describe('Function ABI signature (e.g., "function transfer(address to, uint256 amount)"). Use with args parameter.'),
+      args: z
+        .array(z.union([z.string(), z.number(), z.boolean()]))
+        .optional()
+        .describe('Function arguments (when using functionAbi)'),
+      from: z
+        .string()
+        .optional()
+        .describe('Sender address (defaults to zero address)'),
+      value: z.string().optional().describe('ETH value to send (in wei)'),
+      blockNumber: z.string().optional().describe('Block number to fork from (defaults to latest)'),
+      traceType: z
+        .enum(['callTracer', 'prestateTracer'])
+        .optional()
+        .default('callTracer')
+        .describe('Trace type: callTracer (call tree) or prestateTracer (state before execution)'),
+      summarize: z
+        .boolean()
+        .optional()
+        .describe('Return a compact summary instead of full trace. Truncates hex data and flattens nested calls.')
+        .default(false)
+    }),
+    async (args) => {
+      // Check if Anvil is installed
+      const anvilAvailable = await isAnvilInstalled()
+      if (!anvilAvailable) {
+        throw new Error(
+          'Anvil is not installed. Please install Foundry: https://book.getfoundry.sh/getting-started/installation'
+        )
+      }
+
+      const clientManager = getClientManager()
+      const forkUrl = clientManager.getRpcUrl(args.chain as ChainName)
+
+      // Encode calldata if functionAbi is provided
+      let calldata = args.data
+      if (args.functionAbi && !calldata) {
+        try {
+          const { encodeFunctionData, parseAbiItem } = await import('viem')
+          const abiItem = parseAbiItem(args.functionAbi)
+          if (abiItem.type !== 'function') {
+            throw new Error('ABI must be a function signature')
+          }
+          calldata = encodeFunctionData({
+            abi: [abiItem],
+            functionName: abiItem.name,
+            args: (args.args ?? []) as readonly unknown[]
+          })
+        } catch (encodeError) {
+          throw new Error(`Failed to encode function call: ${(encodeError as Error).message}`)
+        }
+      }
+
+      try {
+        const blockNumber = args.blockNumber ? BigInt(args.blockNumber) : undefined
+        const value = args.value ? BigInt(args.value) : undefined
+
+        const traceResult = await simulateCallWithTrace(
+          forkUrl,
+          {
+            to: args.to,
+            data: calldata,
+            from: args.from,
+            value
+          },
+          blockNumber,
+          args.traceType
+        )
+
+        // Apply summarization if requested - focused on finding reverts
+        // Skip summarization only if trace is a plain error object (not a call trace with an error field)
+        const isPlainTraceError = traceResult.trace && typeof traceResult.trace === 'object' &&
+          'error' in traceResult.trace && !('type' in traceResult.trace) && !('calls' in traceResult.trace)
+        const traceSummary = args.summarize && traceResult.trace && typeof traceResult.trace === 'object' && !isPlainTraceError
+          ? summarizeTrace(traceResult.trace)
+          : null
+
+        const result = args.summarize && traceSummary
+          ? {
+              chain: args.chain,
+              to: args.to,
+              success: traceResult.success,
+              gasUsed: traceResult.gasUsed.toString(),
+              revertReason: traceResult.revertReason,
+              ...traceSummary // { hasError, errorPath, summary }
+            }
+          : {
+              success: traceResult.success,
+              chain: args.chain,
+              to: args.to,
+              from: args.from ?? '0x0000000000000000000000000000000000000000',
+              data: calldata,
+              value: value?.toString() ?? '0',
+              blockNumber: blockNumber?.toString() ?? 'latest',
+              result: traceResult.result,
+              gasUsed: traceResult.gasUsed.toString(),
+              revertReason: traceResult.revertReason,
+              trace: traceResult.trace
+            }
+
+        return formatResponse(result)
+      } catch (error) {
+        throw new Error(`Debug call failed: ${(error as Error).message}`)
+      }
+    }
   )
 }

package/src/tools/contract.ts

@@ -94,9 +94,12 @@ export default {
           });
 
           // Execute multicall
+          // Use deployless mode for localhost/anvil since Multicall3 may not be deployed
+          const useDeployless = chain === "localhost";
           const multicallResults = await client.multicall({
             contracts: multicallContracts,
             blockNumber: blockTag === "latest" ? undefined : blockTag,
+            ...(useDeployless && { deployless: true }),
           });
 
           // Process results