web3-tools-mcp 3.0.0 → 3.1.0

package/src/tools/read/logs.ts

@@ -15,7 +15,7 @@ import {
 import { z } from 'zod'
 import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
 import type { ChainName } from '../../types.js'
-import { convertEventArgsToTypes, createTool, formatResponse } from '../../utils.js'
+import { convertEventArgsToTypes, createTool, formatResponse, rpcReason } from '../../utils.js'
 
 /**
  * A topic is always 32 bytes, so an address, a number or a short hex value has to be
@@ -34,15 +34,71 @@ function toTopic(value: unknown): Hex {
   throw new Error(`Cannot filter on indexed value ${JSON.stringify(value)} — expected an address, number or hex string`)
 }
 
+/** More than this is cut short, with the block to resume from. */
+export const MAX_LOGS = 1000
+
+interface DecodedLog {
+  address: Address
+  blockHash: Hex | null
+  blockNumber: bigint | null
+  data: Hex
+  logIndex: number | null | undefined
+  topics: readonly Hex[]
+  transactionHash: Hex | null
+  transactionIndex: number | null | undefined
+  eventName: string
+  args: unknown
+}
+
+function serializeLog(log: DecodedLog) {
+  return {
+    address: log.address,
+    blockHash: log.blockHash,
+    blockNumber: log.blockNumber?.toString(),
+    data: log.data,
+    logIndex: log.logIndex,
+    topics: log.topics,
+    transactionHash: log.transactionHash,
+    transactionIndex: log.transactionIndex,
+    decoded: { eventName: log.eventName, args: log.args }
+  }
+}
+
+/** Resuming from `nextBlock` may repeat logs of that block already returned. */
+export function capLogs(logs: DecodedLog[]) {
+  if (logs.length <= MAX_LOGS) return { logs: logs.map(serializeLog) }
+  return {
+    logs: logs.slice(0, MAX_LOGS).map(serializeLog),
+    truncated: true,
+    nextBlock: logs[MAX_LOGS]?.blockNumber?.toString()
+  }
+}
+
+/**
+ * The same range eth_getLogs would scan — each end defaults to the latest block — in
+ * Hypersync's terms, where `toBlock` is exclusive.
+ */
+export function hypersyncRange(fromBlock: string | undefined, toBlock: string | undefined, latest: number) {
+  return {
+    fromBlock: fromBlock ? Number(BigInt(fromBlock)) : latest,
+    toBlock: (toBlock ? Number(BigInt(toBlock)) : latest) + 1
+  }
+}
+
+/** One topic, or a list of alternatives for an OR filter. */
+export function toTopics(value: unknown): Hex | Hex[] {
+  return Array.isArray(value) ? value.map(toTopic) : toTopic(value)
+}
+
 async function getLogsWithHypersync(
   chainName: ChainName,
-  eventAbi: string,
+  abiItem: AbiEvent,
   hypersyncApiKey?: string,
   address?: string,
   fromBlock?: string,
   toBlock?: string,
   eventArgs?: Record<string, unknown>
-) {
+): Promise<DecodedLog[]> {
   const hypersyncUrl = getClientManager().getHypersyncUrl(chainName)
   if (!hypersyncUrl) {
     throw new Error(`Hypersync not supported for chain: ${chainName}`)
@@ -53,25 +109,26 @@ async function getLogsWithHypersync(
     bearerToken: hypersyncApiKey
   })
 
-  const abiItem = parseAbiItem(eventAbi) as AbiEvent
-  const eventSignature = toEventSignature(abiItem)
-  const topic0 = keccak256(toBytes(eventSignature))
+  const topic0 = keccak256(toBytes(toEventSignature(abiItem)))
 
   // Build topics array for filtering
-  const topics: (string | string[] | null)[] = [topic0]
+  const topics: (Hex | Hex[] | null)[] = [topic0]
 
   // Add indexed parameter filtering if eventArgs provided
-  if (eventArgs && Object.keys(eventArgs).length > 0) {
+  if (eventArgs) {
     const indexedInputs = abiItem.inputs.filter((input) => input.indexed)
 
     for (let i = 0; i < indexedInputs.length && i < 3; i++) {
       const input = indexedInputs[i]
       const argValue = input?.name ? eventArgs[input.name] : undefined
 
-      topics.push(argValue === undefined ? null : toTopic(argValue))
+      topics.push(argValue === undefined ? null : toTopics(argValue))
     }
   }
 
+  const latest = fromBlock && toBlock ? 0 : await client.getHeight()
+  const range = hypersyncRange(fromBlock, toBlock, latest)
+
   const query = {
     fieldSelection: {
       log: [
@@ -88,8 +145,7 @@ async function getLogsWithHypersync(
         LogField.LogIndex
       ]
     },
-    fromBlock: fromBlock ? Number.parseInt(fromBlock, 10) : 0,
-    toBlock: toBlock ? Number.parseInt(toBlock, 10) : undefined,
+    ...range,
     logs: [
       {
         address: address ? [address] : undefined,
@@ -100,11 +156,17 @@ async function getLogsWithHypersync(
     ]
   }
 
-  const res = await client.get(query)
+  // One response covers only part of a long range; `nextBlock` says where it stopped.
+  const logs: Log[] = []
+  for (let from = range.fromBlock; from < range.toBlock && logs.length <= MAX_LOGS; ) {
+    const res = await client.get({ ...query, fromBlock: from })
+    logs.push(...res.data.logs)
+    if (res.nextBlock <= from) break
+    from = res.nextBlock
+  }
 
-  // Convert hypersync logs to viem-compatible format
-  const decodedLogs = res.data.logs
-    .map((log: Log) => {
+  return logs
+    .map((log: Log): DecodedLog | null => {
       const topics = log.topics.filter((topic): topic is string => Boolean(topic)) as [Hex, ...Hex[]]
       const data = (log.data ?? '0x') as Hex
 
@@ -113,7 +175,7 @@ async function getLogsWithHypersync(
         return {
           address: log.address as Address,
           blockHash: log.blockHash as Hex,
-          blockNumber: log.blockNumber ? BigInt(log.blockNumber) : 0n,
+          blockNumber: log.blockNumber !== undefined ? BigInt(log.blockNumber) : null,
           data,
           logIndex: log.logIndex,
           topics,
@@ -127,165 +189,91 @@ async function getLogsWithHypersync(
         return null
       }
     })
-    .filter((log): log is NonNullable<typeof log> => log !== null)
-
-  return decodedLogs
+    .filter((log): log is DecodedLog => log !== null)
 }
 
 export default {
   get_logs: createTool(
     'Query Contract Events',
-    'Search and decode contract events with filtering. Uses viem with hypersync fallback. Specify address and block ranges for best performance.',
+    `Search and decode contract events with filtering. Uses viem with hypersync fallback. Specify address and block ranges for best performance. Returns at most ${MAX_LOGS} logs; past that, truncated is true and nextBlock says where to resume.`,
     z.object({
       chain: z.enum(SUPPORTED_CHAINS).describe('The blockchain network to use'),
       eventAbi: z
         .string()
         .describe('Event ABI definition (e.g., "event Transfer(address indexed from, address indexed to, uint256 value)")'),
       address: z.string().optional().describe('Contract address (RECOMMENDED for performance)'),
-      fromBlock: z.string().optional().describe('Start block (defaults to latest-1000)'),
-      toBlock: z.string().optional().describe('End block (defaults to latest)'),
+      fromBlock: z.string().optional().describe('Start block (defaults to the latest block)'),
+      toBlock: z.string().optional().describe('End block, inclusive (defaults to the latest block)'),
       eventArgs: z
         .record(z.union([z.string(), z.number(), z.boolean(), z.array(z.union([z.string(), z.number(), z.boolean()]))]))
         .optional()
-        .describe('Filter by indexed parameters: {"from": "0x123...", "to": "0x456..."}')
+        .describe(
+          'Filter by indexed parameters: {"from": "0x123...", "to": "0x456..."}. A list matches any of its values: {"to": ["0x1...", "0x2..."]}'
+        )
     }),
     async (args) => {
       const clientManager = getClientManager()
-      const config = (clientManager as any).config
+      const chain = args.chain as ChainName
+      const abiItem = parseAbiItem(args.eventAbi) as AbiEvent
 
-      // First try with regular viem client
-      try {
-        const client = clientManager.getClient(args.chain as ChainName)
-        const abiItem = parseAbiItem(args.eventAbi) as AbiEvent
-
-        // Determine block range
-        const fromBlockNum = args.fromBlock ? BigInt(args.fromBlock) : undefined
-        const toBlockNum = args.toBlock ? BigInt(args.toBlock) : undefined
-
-        // Prepare getLogs parameters
-        const getLogsParams: {
-          address?: Address
-          event: AbiEvent
-          fromBlock?: bigint
-          toBlock?: bigint
-          args?: Record<string, unknown>
-        } = {
-          event: abiItem,
-          fromBlock: fromBlockNum,
-          toBlock: toBlockNum
-        }
-
-        // Add address filter if provided
-        if (args.address && isAddress(args.address)) {
-          getLogsParams.address = args.address as Address
-        }
-
-        // Add event argument filters if provided
-        if (args.eventArgs && Object.keys(args.eventArgs).length > 0) {
-          // Convert event arguments to proper types based on ABI
-          const convertedEventArgs = convertEventArgsToTypes(args.eventArgs, abiItem.inputs)
-          getLogsParams.args = convertedEventArgs
-        }
-
-        // Use client.getLogs with proper typing
-        const logs = await client.getLogs(getLogsParams)
-
-        // Convert logs to serializable format
-        const serializedLogs = logs.map((log) => {
-          const baseLogData = {
-            address: log.address,
-            blockHash: log.blockHash,
-            blockNumber: log.blockNumber?.toString(),
-            data: log.data,
-            logIndex: log.logIndex,
-            topics: log.topics,
-            transactionHash: log.transactionHash,
-            transactionIndex: log.transactionIndex
-          }
+      if (args.address && !isAddress(args.address)) {
+        throw new Error(`Invalid contract address: ${args.address}`)
+      }
 
-          return {
-            ...baseLogData,
-            decoded: {
-              eventName: log.eventName,
-              args: log.args
-            }
-          }
-        })
+      const eventArgs =
+        args.eventArgs && Object.keys(args.eventArgs).length > 0
+          ? convertEventArgsToTypes(args.eventArgs, abiItem.inputs)
+          : undefined
+      const fromBlockNum = args.fromBlock ? BigInt(args.fromBlock) : undefined
+      const toBlockNum = args.toBlock ? BigInt(args.toBlock) : undefined
 
+      const respond = (logs: DecodedLog[], dataSource: 'viem' | 'hypersync') => {
+        const capped = capLogs(logs)
         return formatResponse({
-          logs: serializedLogs,
+          ...capped,
           eventSignature: toEventSignature(abiItem),
           chain: args.chain,
           fromBlock: fromBlockNum?.toString() || 'latest',
           toBlock: toBlockNum?.toString() || 'latest',
-          count: logs.length,
-          dataSource: 'viem',
+          count: capped.logs.length,
+          dataSource,
           filters: {
             address: args.address || null,
             eventArgs: args.eventArgs || null
           }
         })
-      } catch (viemError) {
-        // If viem fails and we have hypersync support for this chain, try hypersync as fallback
-        if (clientManager.getHypersyncUrl(args.chain as ChainName)) {
-          console.warn(`Viem getLogs failed for ${args.chain}, trying hypersync fallback:`, viemError)
-
-          try {
-            const hypersyncLogs = await getLogsWithHypersync(
-              args.chain as ChainName,
-              args.eventAbi,
-              config.hypersyncApiKey,
-              args.address,
-              args.fromBlock,
-              args.toBlock,
-              args.eventArgs
-            )
-
-            const abiItem = parseAbiItem(args.eventAbi) as AbiEvent
-            const fromBlockNum = args.fromBlock ? BigInt(args.fromBlock) : undefined
-            const toBlockNum = args.toBlock ? BigInt(args.toBlock) : undefined
-
-            // Convert hypersync logs to the same format as viem logs
-            const serializedLogs = hypersyncLogs.map((log) => {
-              const baseLogData = {
-                address: log.address,
-                blockHash: log.blockHash,
-                blockNumber: log.blockNumber?.toString(),
-                data: log.data,
-                logIndex: log.logIndex,
-                topics: log.topics,
-                transactionHash: log.transactionHash,
-                transactionIndex: log.transactionIndex
-              }
+      }
 
-              return {
-                ...baseLogData,
-                decoded: {
-                  eventName: log.eventName,
-                  args: log.args
-                }
-              }
-            })
+      try {
+        const logs = await clientManager.getClient(chain).getLogs({
+          address: args.address as Address | undefined,
+          event: abiItem,
+          args: eventArgs,
+          fromBlock: fromBlockNum,
+          toBlock: toBlockNum
+        })
+        return respond(logs as DecodedLog[], 'viem')
+      } catch (viemError) {
+        if (!clientManager.getHypersyncUrl(chain)) {
+          throw new Error(`Failed to get logs with viem (hypersync not available for ${args.chain}): ${rpcReason(viemError)}`)
+        }
+        console.warn(`Viem getLogs failed for ${args.chain}, trying hypersync fallback: ${rpcReason(viemError)}`)
 
-            return formatResponse({
-              logs: serializedLogs,
-              eventSignature: toEventSignature(abiItem),
-              chain: args.chain,
-              fromBlock: fromBlockNum?.toString() || 'latest',
-              toBlock: toBlockNum?.toString() || 'latest',
-              count: hypersyncLogs.length,
-              dataSource: 'hypersync',
-              filters: {
-                address: args.address || null,
-                eventArgs: args.eventArgs || null
-              }
-            })
-          } catch (hypersyncError) {
-            throw new Error(`Both viem and hypersync failed. Viem error: ${viemError}. Hypersync error: ${hypersyncError}`)
-          }
-        } else {
-          // No hypersync fallback available for this chain
-          throw new Error(`Failed to get logs with viem (hypersync not available for ${args.chain}): ${viemError}`)
+        try {
+          const logs = await getLogsWithHypersync(
+            chain,
+            abiItem,
+            clientManager.getConfig().hypersyncApiKey,
+            args.address,
+            args.fromBlock,
+            args.toBlock,
+            eventArgs
+          )
+          return respond(logs, 'hypersync')
+        } catch (hypersyncError) {
+          throw new Error(
+            `Both viem and hypersync failed. Viem error: ${rpcReason(viemError)}. Hypersync error: ${rpcReason(hypersyncError)}`
+          )
         }
       }
     }

package/src/tools/read/signatures.ts

@@ -1,7 +1,6 @@
 import {
   type AbiEvent,
   type AbiFunction,
-  type AbiParameter,
   encodeFunctionData,
   keccak256,
   parseAbiItem,
@@ -11,7 +10,7 @@ import {
 } from 'viem'
 import { z } from 'zod'
 import type { AbiError } from '../../types.js'
-import { createTool, formatResponse } from '../../utils.js'
+import { convertArgumentsToTypes, createTool, formatResponse } from '../../utils.js'
 
 const FunctionAbiSchema = z.object({
   functionAbi: z.string().describe('Function ABI definition (e.g., "function transfer(address to, uint256 amount)")')
@@ -92,7 +91,8 @@ export default {
     async (args) => {
       const results = args.items.map((item) => {
         const abiItem = parseAbiItem(item.errorAbi) as AbiError
-        const signature = `${abiItem.name}(${abiItem.inputs.map((input: AbiParameter) => input.type).join(',')})`
+        // Formatted as a function, which an error's signature is; viem keeps an "error " prefix otherwise.
+        const signature = toFunctionSignature({ ...abiItem, type: 'function', outputs: [], stateMutability: 'nonpayable' })
         const hash = keccak256(toBytes(signature))
         const selector = hash.slice(0, 10)
 
@@ -125,7 +125,7 @@ export default {
       const data = encodeFunctionData({
         abi: [abiItem],
         functionName: abiItem.name,
-        args: args.args as readonly unknown[]
+        args: convertArgumentsToTypes(args.args, abiItem.inputs)
       })
 
       return formatResponse({

package/src/tools/read/signing.ts

@@ -52,12 +52,18 @@ export default {
         }
 
         if (request.state === 'failed') {
+          // Only an explicit rejection proves nothing was signed. A timeout or a dropped
+          // connection can land after the wallet signed and broadcast.
+          const rejected = request.stage === 'approval' && /rejected|denied/i.test(request.error ?? '')
           return formatResponse({
             success: false,
-            status: 'rejected_or_failed',
+            status: rejected ? 'rejected' : 'outcome_unknown',
             what: request.summary,
             error: request.error,
-            message: 'Nothing was signed. The wallet rejected it, or it expired before anybody approved.'
+            ...(request.txHash && { transactionHash: request.txHash }),
+            message: rejected
+              ? 'The wallet rejected it. Nothing was signed.'
+              : 'It did not complete here, but it may still have been signed or broadcast. Do not retry until the wallet or a block explorer shows it did not go through.'
           })
         }
 

package/src/tools/sign/transactions.ts

@@ -1,12 +1,13 @@
 import { randomBytes } from 'node:crypto'
 import { type AbiFunction, type Address, encodeFunctionData, isAddress, parseAbiItem, parseUnits, toHex } from 'viem'
 import { z } from 'zod'
+import { tokenMeta } from '../../chain-meta.js'
 import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
 import { log } from '../../log.js'
 import { buildTxPreview, type RawTx, type TxPreview } from '../../preview.js'
 import { type SigningProgress, type SigningRequest, signingCall } from '../../signing-requests.js'
 import type { ChainName } from '../../types.js'
-import { createTool, formatResponse } from '../../utils.js'
+import { convertArgumentsToTypes, createTool, formatResponse } from '../../utils.js'
 import { getWalletClient } from '../../wallet-client.js'
 import { getPhoneSigner } from '../../walletconnect.js'
 import { failure } from './errors.js'
@@ -74,6 +75,33 @@ async function requirePhoneSession(identity: string, account?: string) {
   return { phone, session, from }
 }
 
+/** The phone's wallet reaches chains through its own RPC, which cannot see this machine's node. */
+function requireReachable(chain: ChainName, signWith: SignWith) {
+  if (chain === 'localhost' && signWith === 'phone') {
+    throw new Error('A phone wallet cannot sign on localhost: it has no route to this machine\'s node. Use signWith "browser".')
+  }
+}
+
+/**
+ * The token's own decimals. A caller-supplied figure is only a cross-check: trusting a wrong
+ * one moves orders of magnitude more or less than was asked for.
+ */
+async function tokenDecimals(chain: ChainName, token: Address, claimed?: number): Promise<number> {
+  const onChain = (await tokenMeta(chain, token).catch(() => undefined))?.decimals
+  if (onChain === undefined) {
+    if (claimed === undefined) {
+      throw new Error(
+        `Could not read decimals() from ${token} on ${chain}. Check it is an ERC20 token on this chain, or pass "decimals" explicitly.`
+      )
+    }
+    return claimed
+  }
+  if (claimed !== undefined && claimed !== onChain) {
+    throw new Error(`"decimals" was ${claimed}, but ${token} reports ${onChain} on ${chain}. Nothing was sent.`)
+  }
+  return onChain
+}
+
 /** Long enough for a congested chain, short enough that a stuck one is reported rather than hung on. */
 const RECEIPT_TIMEOUT = 180_000
 
@@ -140,6 +168,7 @@ async function requestSignature(
   progress: SigningProgress
 ) {
   log('info', 'Transaction', `${chain} → ${tx.to}, signing with ${signWith}`)
+  requireReachable(chain, signWith)
   if (signWith === 'phone') return signOnPhone(chain, tx, identity, account, progress)
 
   const wallet = getWalletClient(identity)
@@ -212,6 +241,8 @@ function previewSummary(preview: TxPreview) {
   return {
     action: preview.decoded?.intent ?? preview.decoded?.functionName,
     protocol: preview.decoded?.protocol ?? preview.toLabel,
+    // Labels come from the contracts themselves, so the address they belong to goes too.
+    to: preview.to,
     details: preview.decoded?.fields.map((f) => `${f.name}: ${f.value}${f.warning ? ` (${f.warning})` : ''}`),
     simulation: preview.simulation
   }
@@ -273,7 +304,11 @@ export default {
       tokenAddress: z.string().describe('ERC20 token contract address'),
       to: z.string().describe('Recipient address'),
       amount: z.string().describe('Amount in token units (e.g., "100" for 100 USDC)'),
-      decimals: z.number().optional().default(18).describe('Token decimals (default: 18)'),
+      decimals: z
+        .number()
+        .int()
+        .optional()
+        .describe('Token decimals. Read from the token when omitted; when given, must match what the token reports.'),
       signWith: SignWithSchema,
       account: AccountSchema
     }),
@@ -281,10 +316,11 @@ export default {
       try {
         const tokenAddress = requireAddress('token address', args.tokenAddress)
         const to = requireAddress('recipient address', args.to)
+        const decimals = await tokenDecimals(args.chain as ChainName, tokenAddress, args.decimals)
 
         const data = encodeFunctionData({
           abi: [parseAbiItem('function transfer(address to, uint256 amount)')],
-          args: [to, parseUnits(args.amount, args.decimals ?? 18)]
+          args: [to, parseUnits(args.amount, decimals)]
         })
 
         const outcome = await signingCall(
@@ -327,9 +363,19 @@ export default {
       contractAddress: z.string().describe('Contract address'),
       functionAbi: z.string().describe('Function ABI definition (e.g., "function transfer(address to, uint256 amount)")'),
       args: z
-        .array(z.union([z.string(), z.number(), z.boolean()]))
+        .array(
+          z.union([
+            z.string(),
+            // JSON numbers past 2^53 arrive already rounded, so signing one would send a different value.
+            z.number().refine(Number.isSafeInteger, {
+              message:
+                'Numbers must be integers within ±2^53-1. Pass large or exact values as strings, e.g. "1000000000000000000".'
+            }),
+            z.boolean()
+          ])
+        )
         .optional()
-        .describe('Function arguments in order matching the ABI signature'),
+        .describe('Function arguments in order matching the ABI signature. Pass uint/int values as strings.'),
       value: z.string().optional().describe('Optional native value to send with transaction (in ETH units, e.g., "0.1")'),
       signWith: SignWithSchema,
       account: AccountSchema
@@ -342,7 +388,7 @@ export default {
         const data = encodeFunctionData({
           abi: [abiItem],
           functionName: abiItem.name,
-          args: (args.args || []) as readonly unknown[]
+          args: convertArgumentsToTypes(args.args || [], abiItem.inputs)
         })
         const value = args.value ? `0x${parseUnits(args.value, 18).toString(16)}` : '0x0'
 
@@ -389,8 +435,11 @@ export default {
       try {
         const sign = async (progress: SigningProgress) => {
           if (args.signWith === 'phone') {
-            const { phone, from } = await requirePhoneSession(identity, args.account)
-            return phone.request('mainnet', 'personal_sign', [toHex(args.message), from], {
+            const { phone, session, from } = await requirePhoneSession(identity, args.account)
+            // personal_sign is chain-agnostic, but the request still has to name a chain the session holds.
+            const chain = SUPPORTED_CHAINS.find((c) => session.chains.includes(getClientManager().getChainId(c)))
+            if (!chain) throw new Error(`The paired wallet approved no chain this server knows: ${session.chains.join(', ')}.`)
+            return phone.request(chain, 'personal_sign', [toHex(args.message), from], {
               identity,
               account: args.account,
               onWaiting: progress.waiting
@@ -403,7 +452,9 @@ export default {
             id: generateRequestId(),
             type: 'sign_message',
             chain: 'any',
-            data: { message: args.message }
+            // Hex on both signers: a wallet reads a raw "0x…" string as bytes, so the same text
+            // would otherwise sign differently depending on where it was approved.
+            data: { message: toHex(args.message) }
           })
         }
 

package/src/utils.ts

@@ -136,11 +136,13 @@ function findErrorInTrace(trace: unknown): { errorPath: SummarizedCall[]; errorM
 }
 
 /**
- * Coerce a JSON value into what viem expects for an ABI type. Tuples, arrays and anything
+ * Coerce a JSON value into what viem expects for an ABI type. A list is coerced element by
+ * element — an array argument, or an OR filter on an event argument. Tuples and anything
  * else pass through: viem validates them, and guessing here would only mangle them.
  */
 function coerce(value: unknown, type: string): unknown {
   if (value === null || value === undefined) return null
+  if (Array.isArray(value)) return value.map((item) => coerce(item, type))
 
   if (type === 'address' || type === 'string' || type.startsWith('bytes')) {
     return String(value)
@@ -195,6 +197,50 @@ export function convertEventArgsToTypes(
   )
 }
 
+/** One tool call is one quota unit, so an unbounded batch would be a way around the quota. */
+export const MAX_BATCH = 25
+
+/**
+ * Why an RPC call failed, without the request URL — viem puts it in `message`, and with a
+ * provider key configured that URL carries the key.
+ */
+export function rpcReason(error: unknown): string {
+  const { details, shortMessage } = error as { details?: string; shortMessage?: string }
+  return details || shortMessage || (error instanceof Error ? error.message : String(error))
+}
+
+/** Every configured key blanked out of `text`: RPC URLs carry them, and errors quote the URL. */
+export function redactSecrets(text: string, config: Config): string {
+  return [config.alchemyApiKey, config.infuraApiKey, config.etherscanApiKey, config.hypersyncApiKey].reduce<string>(
+    (out, secret) => (secret ? out.replaceAll(secret, '[redacted]') : out),
+    text
+  )
+}
+
+/** A Map whose entries expire after `ttlMs`, dropping the oldest once it holds `maxSize`. */
+export class TtlCache<V> {
+  private entries = new Map<string, { value: V; expires: number }>()
+
+  constructor(
+    private maxSize: number,
+    private ttlMs: number
+  ) {}
+
+  get(key: string): V | undefined {
+    const entry = this.entries.get(key)
+    if (!entry) return undefined
+    if (entry.expires > Date.now()) return entry.value
+    this.entries.delete(key)
+    return undefined
+  }
+
+  set(key: string, value: V): void {
+    this.entries.delete(key)
+    this.entries.set(key, { value, expires: Date.now() + this.ttlMs })
+    if (this.entries.size > this.maxSize) this.entries.delete(this.entries.keys().next().value as string)
+  }
+}
+
 // Format response as tool result
 export function formatResponse(data: unknown): ToolResult {
   const serializable = convertBigIntToString(data)