web3-tools-mcp 3.0.0 → 3.1.0

package/src/tools/read/contract-info.ts

@@ -2,7 +2,7 @@ import { isAddress } from 'viem'
 import { z } from 'zod'
 import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
 import type { ChainName } from '../../types.js'
-import { createTool, formatResponse } from '../../utils.js'
+import { createTool, formatResponse, TtlCache } from '../../utils.js'
 
 // Type for raw Etherscan contract info
 interface EtherscanContractInfo {
@@ -21,66 +21,83 @@ interface EtherscanContractInfo {
   SwarmSource: string
 }
 
-// Cache for contract source code and ABIs
 interface CachedContract {
-  rawInfo: EtherscanContractInfo // Cache the raw Etherscan response
+  rawInfo: EtherscanContractInfo
   sourceFiles: Record<string, string>
-  abi?: any[]
   metadata: {
     contractName: string
     compilerVersion: string
     isProxy: boolean
     implementationAddress?: string
   }
-  timestamp: number
 }
 
-const contractCache = new Map<string, CachedContract>()
-// No TTL - contracts are immutable, cache never expires
+// Source is immutable, but a proxy's implementation is not; an hour notices an upgrade.
+const contractCache = new TtlCache<CachedContract>(100, 60 * 60 * 1000)
 
 // Helper to generate cache key
 function getCacheKey(chainId: number, address: string): string {
   return `${chainId}:${address.toLowerCase()}`
 }
 
-// Shared helper to fetch contract info from Etherscan (with caching)
-async function fetchContractInfo(chainId: number, address: string, etherscanApiKey: string): Promise<EtherscanContractInfo> {
-  // Check cache first
-  const cacheKey = getCacheKey(chainId, address)
-  const cached = contractCache.get(cacheKey)
+/** Etherscan's `result` for a query, or why there is none: it answers status "0" with the reason there. */
+export async function etherscan<T>(chainId: number, params: string, etherscanApiKey: string): Promise<T> {
+  const response = await fetch(`https://api.etherscan.io/v2/api?chainid=${chainId}&${params}&apikey=${etherscanApiKey}`, {
+    signal: AbortSignal.timeout(15_000)
+  })
+  if (!response.ok) throw new Error(`Etherscan API error: HTTP ${response.status}`)
 
-  if (cached?.rawInfo) {
-    return cached.rawInfo
+  const data = (await response.json()) as { status: string; message?: string; result: unknown }
+  if (data.status !== '1') {
+    throw new Error(`Etherscan API error: ${typeof data.result === 'string' ? data.result : data.message || 'request failed'}`)
   }
+  return data.result as T
+}
 
-  // Fetch from Etherscan API
-  const sourceUrl = `https://api.etherscan.io/v2/api?chainid=${chainId}&module=contract&action=getsourcecode&address=${address}&apikey=${etherscanApiKey}`
-
-  const sourceResponse = await fetch(sourceUrl)
-  const sourceData = (await sourceResponse.json()) as {
-    status: string
-    message?: string
-    result: Array<EtherscanContractInfo>
+/** Etherscan's SourceCode is one file, a `{{…}}`-wrapped standard JSON input, or a plain map of files. */
+function parseSourceFiles(info: EtherscanContractInfo): Record<string, string> {
+  const single = { [`${info.ContractName}.sol`]: info.SourceCode }
+  if (!info.SourceCode.startsWith('{')) return single
+
+  try {
+    const parsed = JSON.parse(info.SourceCode.startsWith('{{') ? info.SourceCode.slice(1, -1) : info.SourceCode)
+    const files = (parsed.sources ?? parsed) as Record<string, string | { content?: string }>
+    return Object.fromEntries(
+      Object.entries(files).map(([path, data]) => [path, typeof data === 'string' ? data : data.content || ''])
+    )
+  } catch {
+    return single
   }
+}
 
-  if (sourceData.status !== '1' || !sourceData.result || sourceData.result.length === 0) {
-    throw new Error(`Etherscan API error: ${sourceData.message || 'No contract source found'}`)
-  }
+function fileStats(sourceFiles: Record<string, string>) {
+  return Object.entries(sourceFiles).map(([path, content]) => ({ path, lines: content.split('\n').length, size: content.length }))
+}
 
-  const contractInfo = sourceData.result[0]
+// Shared helper to fetch contract info from Etherscan (with caching)
+async function fetchContractInfo(chainId: number, address: string, etherscanApiKey: string): Promise<EtherscanContractInfo> {
+  const cacheKey = getCacheKey(chainId, address)
+  const cached = contractCache.get(cacheKey)
+  if (cached) return cached.rawInfo
+
+  const result = await etherscan<EtherscanContractInfo[]>(
+    chainId,
+    `module=contract&action=getsourcecode&address=${address}`,
+    etherscanApiKey
+  )
+  const contractInfo = result[0]
+  if (!contractInfo) throw new Error('Etherscan API error: No contract source found')
 
-  // Cache the raw info immediately
   const isProxy = contractInfo.Proxy === '1'
   contractCache.set(cacheKey, {
     rawInfo: contractInfo,
-    sourceFiles: {},
+    sourceFiles: contractInfo.SourceCode ? parseSourceFiles(contractInfo) : {},
     metadata: {
       contractName: contractInfo.ContractName,
       compilerVersion: contractInfo.CompilerVersion,
       isProxy,
       implementationAddress: isProxy ? contractInfo.Implementation : undefined
-    },
-    timestamp: Date.now()
+    }
   })
 
   return contractInfo
@@ -102,7 +119,7 @@ export default {
     }),
     async (args) => {
       const clientManager = getClientManager()
-      const config = (clientManager as any).config
+      const config = clientManager.getConfig()
 
       if (!config.etherscanApiKey) {
         throw new Error(
@@ -189,23 +206,16 @@ export default {
       // Try to get creation info if requested
       if (includeSet.has('creation')) {
         try {
-          const creationUrl = `https://api.etherscan.io/v2/api?chainid=${chainId}&module=contract&action=getcontractcreation&contractaddresses=${args.address}&apikey=${config.etherscanApiKey}`
-          const creationResponse = await fetch(creationUrl)
-          const creationData = (await creationResponse.json()) as {
-            status: string
-            result?: Array<{ contractCreator: string; txHash: string }>
-          }
-          if (creationData.status === '1' && creationData.result && creationData.result.length > 0) {
-            const result = creationData.result[0]
-            if (result) {
-              abiResult.creationInfo = {
-                creator: result.contractCreator,
-                transactionHash: result.txHash
-              }
-            }
+          const [creation] = await etherscan<Array<{ contractCreator: string; txHash: string }>>(
+            chainId,
+            `module=contract&action=getcontractcreation&contractaddresses=${args.address}`,
+            config.etherscanApiKey
+          )
+          if (creation) {
+            abiResult.creationInfo = { creator: creation.contractCreator, transactionHash: creation.txHash }
           }
-        } catch {
-          // Creation info is optional
+        } catch (error) {
+          abiResult.creationError = (error as Error).message
         }
       }
 
@@ -249,14 +259,6 @@ export default {
         }
       }
 
-      // Update cache with ABI (rawInfo already cached by fetchContractInfo)
-      const cacheKey = getCacheKey(chainId, args.address)
-      const existing = contractCache.get(cacheKey)!
-      contractCache.set(cacheKey, {
-        ...existing,
-        abi
-      })
-
       return formatResponse(abiResult)
     }
   ),
@@ -282,7 +284,7 @@ export default {
     }),
     async (args) => {
       const clientManager = getClientManager()
-      const config = (clientManager as any).config
+      const config = clientManager.getConfig()
 
       if (!config.etherscanApiKey) {
         throw new Error('Etherscan API key is required. Use --etherscan-api-key or set ETHERSCAN_API_KEY environment variable.')
@@ -316,43 +318,8 @@ export default {
         })
       }
 
-      // Parse source code
-      let sourceFiles: Record<string, string> = {}
-      let sourceCodeString = contractInfo.SourceCode
-
-      // Handle multi-file sources (wrapped in {{ }} or [ ])
-      if (sourceCodeString.startsWith('{{') || sourceCodeString.startsWith('[')) {
-        try {
-          // Remove outer braces/brackets if present
-          if (sourceCodeString.startsWith('{{')) {
-            sourceCodeString = sourceCodeString.slice(1, -1)
-          }
-          const parsed = JSON.parse(sourceCodeString)
-
-          if (parsed.sources) {
-            // Standard JSON format
-            sourceFiles = Object.fromEntries(
-              Object.entries(parsed.sources).map(([path, data]: [string, any]) => [path, data.content || ''])
-            )
-          } else if (typeof parsed === 'object') {
-            // Simple object format
-            sourceFiles = parsed
-          }
-        } catch {
-          // If parsing fails, treat as single file
-          sourceFiles = { [`${contractInfo.ContractName}.sol`]: sourceCodeString }
-        }
-      } else {
-        // Single file source
-        sourceFiles = { [`${contractInfo.ContractName}.sol`]: sourceCodeString }
-      }
-
-      // Calculate file stats for summary mode
-      const fileStats = Object.entries(sourceFiles).map(([path, content]) => ({
-        path,
-        lines: (content as string).split('\n').length,
-        size: (content as string).length
-      }))
+      const sourceFiles = parseSourceFiles(contractInfo)
+      const files = fileStats(sourceFiles)
 
       const result: Record<string, unknown> = {
         success: true,
@@ -369,7 +336,7 @@ export default {
         licenseType: contractInfo.LicenseType,
         constructorArguments: contractInfo.ConstructorArguments,
         fileCount: Object.keys(sourceFiles).length,
-        totalLines: fileStats.reduce((sum, stat) => sum + stat.lines, 0),
+        totalLines: files.reduce((sum, stat) => sum + stat.lines, 0),
         etherscanUrl: clientManager.explorerUrl(args.chain as ChainName, `/address/${args.address}#code`)
       }
 
@@ -377,7 +344,7 @@ export default {
       if (args.includeSource === 'full') {
         result.sourceFiles = sourceFiles
       } else if (args.includeSource === 'summary') {
-        result.files = fileStats
+        result.files = files
       }
       // 'none' mode: no source files added
 
@@ -387,37 +354,8 @@ export default {
           const implInfo = await fetchContractInfo(chainId, contractInfo.Implementation, config.etherscanApiKey)
 
           if (implInfo && implInfo.SourceCode !== '') {
-            // Parse implementation source code
-            let implSourceFiles: Record<string, string> = {}
-            let implSourceCodeString = implInfo.SourceCode
-
-            if (implSourceCodeString.startsWith('{{') || implSourceCodeString.startsWith('[')) {
-              try {
-                if (implSourceCodeString.startsWith('{{')) {
-                  implSourceCodeString = implSourceCodeString.slice(1, -1)
-                }
-                const parsed = JSON.parse(implSourceCodeString)
-
-                if (parsed.sources) {
-                  implSourceFiles = Object.fromEntries(
-                    Object.entries(parsed.sources).map(([path, data]: [string, any]) => [path, data.content || ''])
-                  )
-                } else if (typeof parsed === 'object') {
-                  implSourceFiles = parsed
-                }
-              } catch {
-                implSourceFiles = { [`${implInfo.ContractName}.sol`]: implSourceCodeString }
-              }
-            } else {
-              implSourceFiles = { [`${implInfo.ContractName}.sol`]: implSourceCodeString }
-            }
-
-            // Calculate implementation file stats
-            const implFileStats = Object.entries(implSourceFiles).map(([path, content]) => ({
-              path,
-              lines: (content as string).split('\n').length,
-              size: (content as string).length
-            }))
+            const implSourceFiles = parseSourceFiles(implInfo)
+            const implFileStats = fileStats(implSourceFiles)
 
             const implResult: Record<string, unknown> = {
               address: contractInfo.Implementation,
@@ -440,16 +378,6 @@ export default {
             }
 
             result.implementation = implResult
-
-            // Update cache with implementation source (rawInfo already cached by fetchContractInfo)
-            if (contractInfo.Implementation) {
-              const implCacheKey = getCacheKey(chainId, contractInfo.Implementation)
-              const existingImpl = contractCache.get(implCacheKey)!
-              contractCache.set(implCacheKey, {
-                ...existingImpl,
-                sourceFiles: implSourceFiles
-              })
-            }
           }
         } catch (error) {
           // Implementation fetch failed, continue without it
@@ -459,14 +387,6 @@ export default {
         result.implementationAddress = contractInfo.Implementation
       }
 
-      // Update cache with main contract source (rawInfo already cached by fetchContractInfo)
-      const cacheKey = getCacheKey(chainId, args.address)
-      const existing = contractCache.get(cacheKey)!
-      contractCache.set(cacheKey, {
-        ...existing,
-        sourceFiles
-      })
-
       return formatResponse(result)
     }
   ),

package/src/tools/read/contract.ts

@@ -2,7 +2,7 @@ import { type AbiFunction, type Address, isAddress, parseAbiItem } from 'viem'
 import { z } from 'zod'
 import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
 import type { ChainName } from '../../types.js'
-import { convertArgumentsToTypes, createTool, formatResponse } from '../../utils.js'
+import { convertArgumentsToTypes, createTool, formatResponse, MAX_BATCH } from '../../utils.js'
 
 const ContractCallSchema = z.object({
   chain: z.enum(SUPPORTED_CHAINS).describe('Blockchain network (mainnet, base, arbitrum, polygon, optimism, celo, localhost)'),
@@ -27,6 +27,7 @@ export default {
     z.object({
       calls: z
         .array(ContractCallSchema)
+        .max(MAX_BATCH)
         .describe('Array of contract function calls. Automatically batched by chain/block for optimal performance.')
     }),
     async (args) => {

package/src/tools/read/ens.ts

@@ -1,9 +1,9 @@
 import { type Address, isAddress, namehash } from 'viem'
 import { normalize } from 'viem/ens'
 import { z } from 'zod'
-import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
+import { getClientManager } from '../../client.js'
 import type { ChainName } from '../../types.js'
-import { createTool, formatResponse } from '../../utils.js'
+import { createTool, formatResponse, MAX_BATCH } from '../../utils.js'
 
 // Base ENS Contract Addresses
 const BASE_ENS_CONTRACTS = {
@@ -159,32 +159,32 @@ async function getTextRecordBase(name: string, key: string): Promise<string | nu
   }
 }
 
+/** Where a name service is deployed: ENS on mainnet, Linea Names on Linea, Basenames on Base. */
+const ENS_CHAINS = ['mainnet', 'linea', 'base'] as const
+const ensChain = z
+  .enum(ENS_CHAINS)
+  .default('mainnet')
+  .describe('Where the name lives: mainnet for .eth (ENS), linea for Linea Names, base for Basenames. Defaults to mainnet.')
+
 const EnsResolveSchema = z.object({
-  chain: z
-    .enum(SUPPORTED_CHAINS)
-    .default('mainnet')
-    .describe('Blockchain network (defaults to mainnet, as ENS is primarily on Ethereum)'),
-  name: z.string().describe("ENS name to resolve to an address (e.g., 'vitalik.eth', 'example.eth')"),
-  universalResolver: z.boolean().optional().describe('Use universal resolver for cross-chain resolution (defaults to true)')
+  chain: ensChain,
+  name: z.string().describe("ENS name to resolve to an address (e.g., 'vitalik.eth', 'example.eth')")
 })
 
 const EnsReverseResolveSchema = z.object({
-  chain: z.enum(SUPPORTED_CHAINS).default('mainnet').describe('Blockchain network (defaults to mainnet)'),
-  address: z.string().describe('Ethereum address to resolve to an ENS name'),
-  universalResolver: z.boolean().optional().describe('Use universal resolver for cross-chain resolution (defaults to true)')
+  chain: ensChain,
+  address: z.string().describe('Ethereum address to resolve to an ENS name')
 })
 
 const EnsTextRecordSchema = z.object({
-  chain: z.enum(SUPPORTED_CHAINS).default('mainnet').describe('Blockchain network (defaults to mainnet)'),
+  chain: ensChain,
   name: z.string().describe('ENS name to query text records from'),
-  key: z.string().describe("Text record key (e.g., 'avatar', 'description', 'email', 'url', 'com.twitter', 'com.github')"),
-  universalResolver: z.boolean().optional().describe('Use universal resolver for cross-chain resolution (defaults to true)')
+  key: z.string().describe("Text record key (e.g., 'avatar', 'description', 'email', 'url', 'com.twitter', 'com.github')")
 })
 
 const EnsBatchResolveSchema = z.object({
-  chain: z.enum(SUPPORTED_CHAINS).default('mainnet').describe('Blockchain network (defaults to mainnet)'),
-  names: z.array(z.string()).describe('Array of ENS names to resolve to addresses in a single batch'),
-  universalResolver: z.boolean().optional().describe('Use universal resolver for cross-chain resolution (defaults to true)')
+  chain: ensChain,
+  names: z.array(z.string()).max(MAX_BATCH).describe('Array of ENS names to resolve to addresses in a single batch')
 })
 
 export default {
@@ -207,8 +207,7 @@ export default {
         const client = clientManager.getClient(args.chain as ChainName)
 
         address = await client.getEnsAddress({
-          name: normalizedName,
-          universalResolverAddress: args.universalResolver !== false ? undefined : undefined
+          name: normalizedName
         })
       }
 
@@ -253,8 +252,7 @@ export default {
         const client = clientManager.getClient(args.chain as ChainName)
 
         ensName = await client.getEnsName({
-          address: args.address as Address,
-          universalResolverAddress: args.universalResolver !== false ? undefined : undefined
+          address: args.address as Address
         })
       }
 
@@ -297,8 +295,7 @@ export default {
 
         textRecord = await client.getEnsText({
           name: normalizedName,
-          key: args.key,
-          universalResolverAddress: args.universalResolver !== false ? undefined : undefined
+          key: args.key
         })
       }
 
@@ -327,11 +324,10 @@ export default {
 
   get_ens_avatar: createTool(
     'Get ENS Avatar',
-    'Get the avatar URI for an ENS name. Returns the avatar URL if set.',
+    'Get the raw avatar text record for an ENS name: an https/ipfs URL, a data URI, or an NFT reference (eip155:1/erc721:0x…/1). It is not fetched or resolved to an image.',
     z.object({
-      chain: z.enum(SUPPORTED_CHAINS).default('mainnet').describe('Blockchain network (defaults to mainnet)'),
-      name: z.string().describe('ENS name to get avatar from'),
-      universalResolver: z.boolean().optional().describe('Use universal resolver for cross-chain resolution (defaults to true)')
+      chain: ensChain,
+      name: z.string().describe('ENS name to get avatar from')
     }),
     async (args) => {
       // Normalize the ENS name
@@ -347,10 +343,8 @@ export default {
         const clientManager = getClientManager()
         const client = clientManager.getClient(args.chain as ChainName)
 
-        avatar = await client.getEnsAvatar({
-          name: normalizedName,
-          universalResolverAddress: args.universalResolver !== false ? undefined : undefined
-        })
+        // getEnsAvatar would fetch the record's URL (or the NFT's metadata) from this server.
+        avatar = await client.getEnsText({ name: normalizedName, key: 'avatar' })
       }
 
       if (!avatar) {
@@ -394,8 +388,7 @@ export default {
             const client = clientManager.getClient(args.chain as ChainName)
 
             address = await client.getEnsAddress({
-              name: normalizedName,
-              universalResolverAddress: args.universalResolver !== false ? undefined : undefined
+              name: normalizedName
             })
           }
 

package/src/tools/read/gas.ts

@@ -4,6 +4,7 @@ import {
   decodeFunctionResult,
   encodeFunctionData,
   formatEther,
+  formatGwei,
   type Hex,
   isAddress,
   parseAbiItem,
@@ -14,12 +15,10 @@ import { z } from 'zod'
 import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
 import { enrichTransfers } from '../../preview.js'
 import type { ChainName } from '../../types.js'
-import { convertArgumentsToTypes, createTool, formatResponse } from '../../utils.js'
+import { convertArgumentsToTypes, createTool, formatResponse, MAX_BATCH, rpcReason } from '../../utils.js'
 
 /** Alchemy's bundle method takes at most this many transactions. */
 const ALCHEMY_BUNDLE_LIMIT = 3
-/** One tool call is one quota unit, so an unbounded bundle would be a way around the quota. */
-const MAX_BUNDLE = 25
 /** Where eth_simulateV1's traced native transfers say they come from. */
 const NATIVE_TOKEN = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
 
@@ -67,15 +66,6 @@ interface AlchemyOutcome {
   error?: { message: string }
 }
 
-/**
- * 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.
- */
-function rpcReason(error: unknown): string {
-  const { details, shortMessage } = error as { details?: string; shortMessage?: string }
-  return details || shortMessage || 'The RPC request failed'
-}
-
 function bundleCall(
   call: { to: string; functionAbi?: string; args?: z.infer<typeof argsSchema>; data?: string; value?: string; from?: string },
   from: string | undefined,
@@ -223,33 +213,16 @@ export default {
         const abiItem = parseAbiItem(args.functionAbi) as AbiFunction
         const convertedArgs = convertArgumentsToTypes(args.args || [], abiItem.inputs)
 
-        const blockTag = args.blockNumber ? BigInt(args.blockNumber) : undefined
-
-        // Simulate the call
-        const result = await client.call({
+        const tx = {
           to: args.contractAddress as Address,
-          data: encodeFunctionData({
-            abi: [abiItem],
-            functionName: abiItem.name,
-            args: convertedArgs
-          }),
+          data: encodeFunctionData({ abi: [abiItem], functionName: abiItem.name, args: convertedArgs }),
           account: args.from ? (args.from as Address) : undefined,
           value: args.value ? BigInt(args.value) : undefined,
-          blockNumber: blockTag
-        })
+          blockNumber: args.blockNumber ? BigInt(args.blockNumber) : undefined
+        }
 
-        // Also estimate gas
-        const gasEstimate = await client.estimateGas({
-          to: args.contractAddress as Address,
-          data: encodeFunctionData({
-            abi: [abiItem],
-            functionName: abiItem.name,
-            args: convertedArgs
-          }),
-          account: args.from ? (args.from as Address) : undefined,
-          value: args.value ? BigInt(args.value) : undefined,
-          blockNumber: blockTag
-        })
+        const result = await client.call(tx)
+        const gasEstimate = await client.estimateGas(tx)
 
         // Decode the result if the function has outputs
         let decodedResult: unknown = result.data
@@ -272,15 +245,12 @@ export default {
           blockNumber: args.blockNumber || 'latest'
         })
       } catch (error) {
-        // Check if it's a revert error
-        const errorMessage = error instanceof Error ? error.message : String(error)
-
         return formatResponse({
           success: false,
           chain: args.chain,
           contractAddress: args.contractAddress,
-          error: errorMessage,
-          reverted: errorMessage.includes('revert') || errorMessage.includes('execution reverted')
+          error: rpcReason(error),
+          reverted: String(error instanceof Error ? error.message : error).includes('revert')
         })
       }
     }
@@ -311,7 +281,7 @@ export default {
           })
         )
         .min(1)
-        .max(MAX_BUNDLE)
+        .max(MAX_BATCH)
         .describe('Transactions to run, in order'),
       blockNumber: z.string().optional().describe('Block to simulate on top of (defaults to latest)')
     }),
@@ -437,14 +407,7 @@ export default {
         client.estimateFeesPerGas().catch(() => null) // Some chains don't support EIP-1559
       ])
 
-      const formatPrice = (wei: bigint): string => {
-        if (args.formatted) {
-          // Convert to Gwei (1 Gwei = 1e9 wei)
-          const gwei = Number(wei) / 1e9
-          return `${gwei.toFixed(2)} Gwei`
-        }
-        return wei.toString()
-      }
+      const formatPrice = (wei: bigint): string => `${formatGwei(wei)} Gwei`
 
       const response: any = {
         chain: args.chain,
@@ -470,7 +433,7 @@ export default {
         const standardGasLimit = 21000n
         const estimatedCost = feeData.maxFeePerGas * standardGasLimit
         response.eip1559.estimatedCostFor21kGas = args.formatted
-          ? `${(Number(estimatedCost) / 1e18).toFixed(6)} ETH`
+          ? `${formatEther(estimatedCost)} ${client.chain?.nativeCurrency.symbol ?? 'ETH'}`
           : estimatedCost.toString()
       }