web3-tools-mcp 3.0.0 → 3.2.0

package/src/oauth.ts

@@ -3,7 +3,7 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js'
-import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js'
+import { InvalidGrantError, InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js'
 import type { AuthorizationParams, OAuthServerProvider } from '@modelcontextprotocol/sdk/server/auth/provider.js'
 import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'
 import type { OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js'
@@ -30,6 +30,7 @@ interface StoredCode {
   resource?: string
   scopes: string[]
   address?: string
+  credential?: string
   expiresAt: number
 }
 
@@ -37,9 +38,17 @@ interface StoredToken {
   clientId: string
   scopes: string[]
   address?: string
+  credential?: string
   expiresAt: number
 }
 
+/** Codes expire in milliseconds, tokens in seconds — the unit OAuth reports them in. */
+function expired(key: string, value: unknown): boolean {
+  const expiresAt = (value as { expiresAt?: number } | undefined)?.expiresAt
+  if (expiresAt === undefined) return false
+  return (key.startsWith('code:') ? expiresAt : expiresAt * 1000) < Date.now()
+}
+
 /** Redis where configured, a JSON file otherwise — issued tokens must outlive a restart. */
 class Store {
   private redis: KeyValueStorage | undefined
@@ -69,10 +78,12 @@ class Store {
     return this.read()[key] as T | undefined
   }
 
-  async set<T>(key: string, value: T): Promise<void> {
-    if (this.redis) return this.redis.setItem(`oauth:${key}`, value)
+  /** `ttl` in seconds lets Redis drop the entry itself; the file is pruned on every write. */
+  async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+    if (this.redis) return this.redis.setItem(`oauth:${key}`, value, ttl)
     const data = this.read()
     data[key] = value
+    for (const [name, stored] of Object.entries(data)) if (expired(name, stored)) delete data[name]
     writeFileSync(this.file, JSON.stringify(data), { mode: 0o600 })
   }
 
@@ -104,8 +115,12 @@ function constantTimeEquals(a: string, b: string): boolean {
  * the deployment rather than anybody in particular.
  */
 export interface Login {
-  /** The page served at GET /authorize. `hidden` must be placed inside its form. */
-  page(hidden: string, error?: string): string | Promise<string>
+  /**
+   * The page served at GET /authorize. `hidden` must be placed inside its form. `request`
+   * names who is asking and where the code will be sent, so a person can tell a phishing
+   * client from their own; like `error`, its values arrive HTML-escaped.
+   */
+  page(hidden: string, error?: string, request?: { client: string; redirectHost: string }): string | Promise<string>
   /** Reads the posted form. An `error` re-renders the page; an `address` names the person. */
   identify(form: Record<string, string>): Promise<{ address?: string; error?: string }>
   /**
@@ -113,6 +128,11 @@ export interface Login {
    * page, so a credential can never be echoed back into the HTML.
    */
   owns?: string[]
+  /**
+   * A shared secret this login checks against, if it has one. Everything issued is bound to
+   * it, so rotating the secret revokes every code and token handed out under the old one.
+   */
+  credential?: string
 }
 
 const PAGE_STYLE = `
@@ -131,13 +151,15 @@ const PAGE_STYLE = `
 export function tokenLogin(accessToken: string): Login {
   return {
     owns: ['token'],
-    page: (hidden, error) => `<!doctype html>
+    credential: accessToken,
+    page: (hidden, error, request) => `<!doctype html>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Connect to web3-tools-mcp</title>
 <style>${PAGE_STYLE}
 </style>
 <h1>Connect to web3-tools-mcp</h1>
+${request ? `<p><strong>${request.client}</strong> is asking for access, and will be sent back to <strong>${request.redirectHost}</strong>.</p>` : ''}
 <p>Paste this server's access token to authorise the client.</p>
 ${error ? `<p class="error">${error}</p>` : ''}
 <form method="post">
@@ -155,6 +177,8 @@ ${error ? `<p class="error">${error}</p>` : ''}
 
 export class OAuthProvider implements OAuthServerProvider {
   private store = new Store()
+  // A hash, so the secret itself never lands in the store.
+  private credential: string | undefined
 
   /**
    * `staticToken` is accepted verbatim in an Authorization header, for clients that can send
@@ -163,7 +187,9 @@ export class OAuthProvider implements OAuthServerProvider {
   constructor(
     private login: Login,
     private staticToken?: string
-  ) {}
+  ) {
+    this.credential = login.credential && createHash('sha256').update(login.credential).digest('hex').slice(0, 16)
+  }
 
   get clientsStore(): OAuthRegisteredClientsStore {
     const store = this.store
@@ -203,11 +229,21 @@ export class OAuthProvider implements OAuthServerProvider {
       .map(([name, value]) => `<input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`)
       .join('\n  ')
 
+    const redirectTo = new URL(params.redirectUri)
+    const shown = {
+      client: escapeHtml(client.client_name || 'An unnamed client'),
+      redirectHost: escapeHtml(redirectTo.host || redirectTo.href)
+    }
+
+    // A login page that can be framed can be clickjacked into authorising somebody else.
+    res.setHeader('X-Frame-Options', 'DENY')
+    res.setHeader('Content-Security-Policy', "frame-ancestors 'none'")
+
     const render = async (status: number, error?: string) => {
       res
         .status(status)
         .setHeader('content-type', 'text/html; charset=utf-8')
-        .send(await this.login.page(hidden, error ? escapeHtml(error) : undefined))
+        .send(await this.login.page(hidden, error ? escapeHtml(error) : undefined, shown))
     }
 
     if (request.method !== 'POST') return render(200)
@@ -216,32 +252,53 @@ export class OAuthProvider implements OAuthServerProvider {
     if (identified.error) return render(401, identified.error)
 
     const code = randomBytes(24).toString('hex')
-    await this.store.set<StoredCode>(`code:${code}`, {
-      clientId: client.client_id,
-      codeChallenge: params.codeChallenge,
-      redirectUri: params.redirectUri,
-      resource: params.resource?.href,
-      scopes: params.scopes ?? [],
-      address: identified.address,
-      expiresAt: Date.now() + CODE_TTL
-    })
-
-    const redirect = new URL(params.redirectUri)
-    redirect.searchParams.set('code', code)
-    if (params.state) redirect.searchParams.set('state', params.state)
-    res.redirect(redirect.href)
+    await this.store.set<StoredCode>(
+      `code:${code}`,
+      {
+        clientId: client.client_id,
+        codeChallenge: params.codeChallenge,
+        redirectUri: params.redirectUri,
+        resource: params.resource?.href,
+        scopes: params.scopes ?? [],
+        address: identified.address,
+        credential: this.credential,
+        expiresAt: Date.now() + CODE_TTL
+      },
+      CODE_TTL / 1000
+    )
+
+    redirectTo.searchParams.set('code', code)
+    if (params.state) redirectTo.searchParams.set('state', params.state)
+    res.redirect(redirectTo.href)
   }
 
-  async challengeForAuthorizationCode(_client: OAuthClientInformationFull, authorizationCode: string): Promise<string> {
+  // Refusals here must be InvalidGrantError: the SDK answers anything else with a 500,
+  // where a client needs the 400 invalid_grant to know it should start the flow again.
+  private async validCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<StoredCode> {
     const stored = await this.store.get<StoredCode>(`code:${authorizationCode}`)
-    if (!stored || stored.expiresAt < Date.now()) throw new Error('Authorization code is invalid or expired')
-    return stored.codeChallenge
+    if (!stored || stored.expiresAt < Date.now() || stored.credential !== this.credential) {
+      throw new InvalidGrantError('Authorization code is invalid or expired')
+    }
+    if (stored.clientId !== client.client_id) throw new InvalidGrantError('Authorization code was issued to a different client')
+    return stored
   }
 
-  async exchangeAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<OAuthTokens> {
-    const stored = await this.store.get<StoredCode>(`code:${authorizationCode}`)
-    if (!stored || stored.expiresAt < Date.now()) throw new Error('Authorization code is invalid or expired')
-    if (stored.clientId !== client.client_id) throw new Error('Authorization code was issued to a different client')
+  async challengeForAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<string> {
+    return (await this.validCode(client, authorizationCode)).codeChallenge
+  }
+
+  async exchangeAuthorizationCode(
+    client: OAuthClientInformationFull,
+    authorizationCode: string,
+    _codeVerifier?: string,
+    redirectUri?: string
+  ): Promise<OAuthTokens> {
+    const stored = await this.validCode(client, authorizationCode)
+    // Optional at the token endpoint because the SDK lets a single-URI client omit it at
+    // /authorize too; when sent, it must be the one the code was issued for.
+    if (redirectUri !== undefined && redirectUri !== stored.redirectUri) {
+      throw new InvalidGrantError('redirect_uri does not match the authorization request')
+    }
 
     // One use only: a replayed code must not mint a second token.
     await this.store.remove(`code:${authorizationCode}`)
@@ -250,10 +307,11 @@ export class OAuthProvider implements OAuthServerProvider {
 
   async exchangeRefreshToken(client: OAuthClientInformationFull, refreshToken: string, scopes?: string[]): Promise<OAuthTokens> {
     const stored = await this.store.get<StoredToken>(`refresh:${refreshToken}`)
-    if (!stored) throw new Error('Refresh token is invalid')
-    if (stored.clientId !== client.client_id) throw new Error('Refresh token was issued to a different client')
+    if (!stored || stored.credential !== this.credential) throw new InvalidGrantError('Refresh token is invalid')
+    if (stored.clientId !== client.client_id) throw new InvalidGrantError('Refresh token was issued to a different client')
 
     await this.store.remove(`refresh:${refreshToken}`)
+    if (stored.expiresAt * 1000 < Date.now()) throw new InvalidGrantError('Refresh token has expired')
     // The refreshed token stays the same person's: a refresh proves possession, not identity.
     return this.issue(client.client_id, scopes ?? stored.scopes, stored.address)
   }
@@ -262,9 +320,10 @@ export class OAuthProvider implements OAuthServerProvider {
     const accessToken = randomBytes(32).toString('hex')
     const refreshToken = randomBytes(32).toString('hex')
     const expiresAt = Math.floor(Date.now() / 1000) + TOKEN_TTL
+    const stored: StoredToken = { clientId, scopes, address, credential: this.credential, expiresAt }
 
-    await this.store.set<StoredToken>(`token:${accessToken}`, { clientId, scopes, address, expiresAt })
-    await this.store.set<StoredToken>(`refresh:${refreshToken}`, { clientId, scopes, address, expiresAt })
+    await this.store.set(`token:${accessToken}`, stored, TOKEN_TTL)
+    await this.store.set(`refresh:${refreshToken}`, stored, TOKEN_TTL)
 
     return {
       access_token: accessToken,
@@ -285,7 +344,7 @@ export class OAuthProvider implements OAuthServerProvider {
     // Must be InvalidTokenError specifically: the SDK turns anything else into a 500, and
     // a client needs the 401 to know it should authenticate again.
     const stored = await this.store.get<StoredToken>(`token:${token}`)
-    if (!stored) throw new InvalidTokenError('Invalid access token')
+    if (!stored || stored.credential !== this.credential) throw new InvalidTokenError('Invalid access token')
     if (stored.expiresAt * 1000 < Date.now()) {
       await this.store.remove(`token:${token}`)
       throw new InvalidTokenError('Access token has expired')

package/src/preview.ts

@@ -85,15 +85,17 @@ function stringify(value: unknown): string {
  * 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']> {
+async function decodeCalldata(chain: ChainName, tx: RawTx, from?: string): 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)
+  // By selector, not name: an overloaded name would otherwise pick the wrong inputs.
+  const selector = tx.data.slice(0, 10).toLowerCase()
+  const abiItem = abi.find((item): item is AbiFunction => item.type === 'function' && toFunctionSelector(item) === selector)
   const inputs = abiItem?.inputs ?? []
-  const erc20 = ERC20_AMOUNT_ARGS[tx.data.slice(0, 10)]
+  const erc20 = ERC20_AMOUNT_ARGS[selector]
   const meta = erc20 ? await tokenMeta(chain, tx.to).catch(() => ({ symbol: undefined, decimals: undefined })) : undefined
 
   const fields: PreviewField[] = (args ?? []).map((value, i) => {
@@ -137,7 +139,7 @@ async function decodeCalldata(chain: ChainName, tx: RawTx): Promise<TxPreview['d
 
   // A registry descriptor says what the call means and how the protocol wants each field
   // labelled, which beats raw ABI argument names. Fall back to those when it has none.
-  const clearSigning = await resolveClearSigning(chain, tx, named).catch(() => null)
+  const clearSigning = await resolveClearSigning(chain, { ...tx, from }, named).catch(() => null)
   if (clearSigning) {
     return {
       functionName,
@@ -256,7 +258,7 @@ export async function buildTxPreview(chain: ChainName, tx: RawTx, from?: string)
   const [decoded, simulation, toLabel] = await Promise.all([
     // A preview that cannot be built must not block the transaction, but swallowing the
     // reason makes "no details shown" impossible to diagnose.
-    decodeCalldata(chain, tx).catch((error) => {
+    decodeCalldata(chain, tx, from).catch((error) => {
       console.error('[Preview] Could not decode calldata:', error instanceof Error ? error.message : error)
       return undefined
     }),

package/src/tools/index.ts

@@ -1,12 +1,15 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js'
 import type { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js'
+import { getClientManager } from '../client.js'
 import { identityFrom } from '../context.js'
 import type { ToolResult } from '../types.js'
+import { redactSecrets } from '../utils.js'
 import advancedTools from './read/advanced.js'
 import balanceTools from './read/balance.js'
 import contractTools from './read/contract.js'
 import contractInfoTools from './read/contract-info.js'
+import defiTools from './read/defi.js'
 import ensTools from './read/ens.js'
 import gasTools from './read/gas.js'
 import logTools from './read/logs.js'
@@ -34,6 +37,7 @@ const readTools = {
   ...advancedTools,
   ...ensTools,
   ...gasTools,
+  ...defiTools,
   // A signature already asked for and paid for; collecting it is not a second request.
   ...signingRequestTools
 } as const
@@ -85,7 +89,16 @@ export function registerAllTools(server: McpServer, middleware?: ToolMiddleware)
         const identity = identityFrom(extra.authInfo)
         const run = () => tool.handler(args, identity)
         const group = toolGroup(name) as ToolGroup
-        return await (middleware ? middleware({ tool: name, group, identity }, run) : run())
+        // Anything a tool returns or throws may quote an RPC URL, and those carry provider keys.
+        const config = getClientManager().getConfig()
+        try {
+          const result = await (middleware ? middleware({ tool: name, group, identity }, run) : run())
+          return { ...result, content: result.content.map((item) => ({ ...item, text: redactSecrets(item.text, config) })) }
+        } catch (error) {
+          if (!(error instanceof Error)) throw new Error(redactSecrets(String(error), config))
+          error.message = redactSecrets(error.message, config)
+          throw error
+        }
       }
     )
   })

package/src/tools/read/advanced.ts

@@ -1,9 +1,37 @@
-import { type Address, decodeAbiParameters, isAddress, parseAbiParameters } from 'viem'
+import {
+  type AbiFunction,
+  type Address,
+  decodeAbiParameters,
+  encodeFunctionData,
+  isAddress,
+  parseAbiItem,
+  parseAbiParameters
+} from 'viem'
 import { z } from 'zod'
 import { isDebugNodeAvailable, simulateCallWithTrace, traceTransactionWithAnvil } from '../../anvil.js'
 import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
 import type { ChainName } from '../../types.js'
-import { createTool, formatResponse, summarizeTrace } from '../../utils.js'
+import { convertArgumentsToTypes, createTool, formatResponse, rpcReason, summarizeTrace } from '../../utils.js'
+
+/** Past these, a trace would crowd everything else out of the agent's context. */
+const MAX_TRACE_CHARS = 50_000
+const MAX_INPUT_CHARS = 10_000
+const MAX_RECEIPT_LOGS = 100
+
+const SUMMARIZE_DESCRIPTION =
+  'Return a compact summary instead of the full trace: the path to the revert, or the top-level calls, with selectors only and no calldata.'
+
+/** The trace itself if it fits, otherwise its JSON cut short. */
+export function boundTrace(trace: unknown): { trace: unknown; truncated?: true } {
+  const json = JSON.stringify(trace) ?? ''
+  return json.length > MAX_TRACE_CHARS ? { trace: json.slice(0, MAX_TRACE_CHARS), truncated: true } : { trace }
+}
+
+const TRACERS = {
+  trace: { tracer: 'callTracer' },
+  prestate: { tracer: 'prestateTracer' },
+  stateDiff: { tracer: 'prestateTracer', tracerConfig: { diffMode: true } }
+} as const
 
 export default {
   get_storage_at: createTool(
@@ -77,8 +105,8 @@ export default {
               const parsedTypes = parseAbiParameters([args.abiType])
               if (parsedTypes.length > 0) {
                 const decoded = decodeAbiParameters(parsedTypes, storageValue) as readonly unknown[]
-                decodedValue = decoded.length > 0 ? decoded[0] : null
-                formattedValue = decodedValue ? String(decodedValue) : 'No data'
+                decodedValue = decoded[0]
+                formattedValue = decodedValue === undefined ? 'No data' : String(decodedValue)
               } else {
                 decodedValue = null
                 formattedValue = 'Invalid ABI type'
@@ -148,9 +176,11 @@ export default {
       chain: z.enum(SUPPORTED_CHAINS).describe('The blockchain network to use'),
       transactionHash: z.string().describe('Transaction hash to trace (0x prefixed)'),
       traceType: z
-        .enum(['trace', 'vmTrace', 'stateDiff'])
+        .enum(['trace', 'prestate', 'stateDiff'])
         .optional()
-        .describe('Trace type: "trace" (call tree, recommended), "vmTrace" (VM execution), "stateDiff" (state changes)')
+        .describe(
+          'Trace type: "trace" (call tree, recommended), "prestate" (state of every touched account before the tx), "stateDiff" (state before and after, changed fields only)'
+        )
         .default('trace'),
       useAnvil: z
         .boolean()
@@ -159,11 +189,7 @@ export default {
           'Force tracing through the debug node (ANVIL_RPC_URL). Used automatically as a fallback when the RPC cannot trace.'
         )
         .default(false),
-      summarize: z
-        .boolean()
-        .optional()
-        .describe('Return a compact summary instead of full trace. Truncates hex data and flattens nested calls.')
-        .default(false)
+      summarize: z.boolean().optional().describe(SUMMARIZE_DESCRIPTION).default(false)
     }),
     async (args) => {
       const clientManager = getClientManager()
@@ -176,24 +202,18 @@ export default {
       let traceResult: unknown = null
       let usedAnvil = false
 
-      // 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'
+      const tracerOptions = TRACERS[args.traceType ?? 'trace']
 
       // Try RPC tracing first (unless forceAnvil is true)
       if (!args.useAnvil) {
         try {
           traceResult = await client.request({
             method: 'debug_traceTransaction',
-            params: [args.transactionHash, { tracer }]
+            params: [args.transactionHash, tracerOptions]
           })
         } catch (rpcError) {
           // RPC tracing failed, will try Anvil fallback
-          const errorMessage = (rpcError as Error).message
+          const errorMessage = rpcReason(rpcError)
           if (
             errorMessage.includes('not supported') ||
             errorMessage.includes('not available') ||
@@ -222,11 +242,11 @@ export default {
             const forkUrl = clientManager.getRpcUrl(args.chain as ChainName)
             const blockNumber = transaction.blockNumber ?? 0n
 
-            traceResult = await traceTransactionWithAnvil(forkUrl, args.transactionHash, blockNumber, tracer)
+            traceResult = await traceTransactionWithAnvil(forkUrl, args.transactionHash, blockNumber, tracerOptions.tracer)
           } catch (anvilError) {
             // Anvil tracing also failed
             traceResult = {
-              error: `Anvil tracing failed: ${(anvilError as Error).message}`,
+              error: `Anvil tracing failed: ${rpcReason(anvilError)}`,
               rpcError:
                 traceResult && typeof traceResult === 'object' && 'rpcError' in traceResult
                   ? (traceResult as { rpcError: string }).rpcError
@@ -257,11 +277,20 @@ export default {
       const traceSummary =
         args.summarize && traceResult && typeof traceResult === 'object' && !isPlainError ? summarizeTrace(traceResult) : null
 
+      const replayNote =
+        usedAnvil && !isPlainError
+          ? 'Replayed on the debug node against the state at the end of the previous block: transactions before this one in the same block were not applied, so the trace can differ from what happened on chain.' +
+            (args.traceType === 'stateDiff' ? ' This replay shows the prestate only, not a diff.' : '')
+          : undefined
+      const bounded = boundTrace(traceResult)
+      const input = transaction.input ?? '0x'
+
       const result =
         args.summarize && traceSummary
           ? {
               chain: args.chain,
               transactionHash: args.transactionHash,
+              ...(replayNote && { note: replayNote }),
               status: receipt.status,
               gasUsed: receipt.gasUsed?.toString(),
               ...traceSummary // { hasError, errorPath, summary }
@@ -272,6 +301,10 @@ export default {
               transactionHash: args.transactionHash,
               traceType: args.traceType,
               usedAnvil,
+              ...(replayNote && { note: replayNote }),
+              ...((bounded.truncated || input.length > MAX_INPUT_CHARS || receipt.logs.length > MAX_RECEIPT_LOGS) && {
+                truncated: true
+              }),
               transaction: {
                 blockNumber: transaction.blockNumber?.toString(),
                 from: transaction.from,
@@ -280,19 +313,20 @@ export default {
                 gas: transaction.gas?.toString() || '0',
                 gasPrice: transaction.gasPrice?.toString() || '0',
                 nonce: transaction.nonce?.toString() || '0',
-                input: transaction.input
+                input: input.length > MAX_INPUT_CHARS ? `${input.slice(0, MAX_INPUT_CHARS)}…` : input
               },
               receipt: {
                 status: receipt.status,
                 gasUsed: receipt.gasUsed?.toString() || '0',
                 effectiveGasPrice: receipt.effectiveGasPrice?.toString() || '0',
-                logs: receipt.logs.map((log) => ({
+                logCount: receipt.logs.length,
+                logs: receipt.logs.slice(0, MAX_RECEIPT_LOGS).map((log) => ({
                   address: log.address,
                   topics: log.topics,
                   data: log.data
                 }))
               },
-              trace: traceResult
+              trace: bounded.trace
             }
 
       return formatResponse(result)
@@ -322,11 +356,7 @@ export default {
         .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)
+      summarize: z.boolean().optional().describe(SUMMARIZE_DESCRIPTION).default(false)
     }),
     async (args) => {
       // Check if Anvil is installed
@@ -342,15 +372,14 @@ export default {
       let calldata = args.data
       if (args.functionAbi && !calldata) {
         try {
-          const { encodeFunctionData, parseAbiItem } = await import('viem')
-          const abiItem = parseAbiItem(args.functionAbi)
+          const abiItem = parseAbiItem(args.functionAbi) as AbiFunction
           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[]
+            args: convertArgumentsToTypes(args.args ?? [], abiItem.inputs)
           })
         } catch (encodeError) {
           throw new Error(`Failed to encode function call: ${(encodeError as Error).message}`)
@@ -406,7 +435,7 @@ export default {
               result: traceResult.result,
               gasUsed: traceResult.gasUsed.toString(),
               revertReason: traceResult.revertReason,
-              trace: traceResult.trace
+              ...boundTrace(traceResult.trace)
             }
 
       return formatResponse(result)

package/src/tools/read/balance.ts

@@ -1,8 +1,9 @@
 import { type Address, formatEther, formatUnits, isAddress } from 'viem'
 import { z } from 'zod'
+import { tokenMeta } from '../../chain-meta.js'
 import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
 import type { ChainName } from '../../types.js'
-import { createTool, formatResponse } from '../../utils.js'
+import { createTool, formatResponse, MAX_BATCH, rpcReason } from '../../utils.js'
 
 const BalanceQuerySchema = z.object({
   chain: z.enum(SUPPORTED_CHAINS).describe('The blockchain network to use'),
@@ -19,6 +20,7 @@ export default {
     z.object({
       queries: z
         .array(BalanceQuerySchema)
+        .max(MAX_BATCH)
         .describe('Array of balance queries. Omit tokenAddress for native balance, include for ERC20.')
     }),
     async (args) => {
@@ -42,7 +44,7 @@ export default {
         success: boolean
         balance?: unknown
         balanceFormatted?: string
-        decimals?: number
+        decimals?: number | null
         error?: string
       }> = []
 
@@ -86,42 +88,24 @@ export default {
               throw new Error(`Invalid token address format: ${query.tokenAddress}`)
             }
 
-            const balance = await client.readContract({
-              address: query.tokenAddress as Address,
-              abi: [
-                {
-                  name: 'balanceOf',
-                  type: 'function',
-                  stateMutability: 'view',
-                  inputs: [{ name: 'account', type: 'address' }],
-                  outputs: [{ name: '', type: 'uint256' }]
-                }
-              ],
-              functionName: 'balanceOf',
-              args: [query.address as Address],
-              blockNumber: blockTag === 'latest' ? undefined : blockTag
-            })
-
-            // Try to get decimals
-            let decimals = 18
-            try {
-              decimals = (await client.readContract({
+            const [balance, { decimals }] = await Promise.all([
+              client.readContract({
                 address: query.tokenAddress as Address,
                 abi: [
                   {
-                    name: 'decimals',
+                    name: 'balanceOf',
                     type: 'function',
                     stateMutability: 'view',
-                    inputs: [],
-                    outputs: [{ name: '', type: 'uint8' }]
+                    inputs: [{ name: 'account', type: 'address' }],
+                    outputs: [{ name: '', type: 'uint256' }]
                   }
                 ],
-                functionName: 'decimals',
+                functionName: 'balanceOf',
+                args: [query.address as Address],
                 blockNumber: blockTag === 'latest' ? undefined : blockTag
-              })) as number
-            } catch {
-              // Use default decimals if call fails
-            }
+              }),
+              tokenMeta(chain as ChainName, query.tokenAddress).catch(() => ({ decimals: undefined }))
+            ])
 
             return {
               index: originalIndex,
@@ -132,8 +116,9 @@ export default {
               blockNumber: query.blockNumber || 'latest',
               success: true,
               balance,
-              balanceFormatted: formatUnits(balance as bigint, decimals),
-              decimals
+              // Unknown decimals leave only the raw balance: guessing 18 could be off by 10^12.
+              balanceFormatted: decimals === undefined ? undefined : formatUnits(balance, decimals),
+              decimals: decimals ?? null
             }
           })
         )
@@ -153,7 +138,7 @@ export default {
               chain: query.chain,
               blockNumber: query.blockNumber || 'latest',
               success: false,
-              error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+              error: rpcReason(result.reason)
             }
           }
         })