web3-tools-mcp 1.0.1 → 1.2.0

package/src/tools/logs.ts

@@ -0,0 +1,291 @@
+import { HypersyncClient, type Log, LogField } from '@envio-dev/hypersync-client'
+import {
+  type AbiEvent,
+  type Address,
+  isAddress,
+  keccak256,
+  parseAbiItem,
+  toBytes,
+  toEventSignature
+} from 'viem'
+import { z } from 'zod'
+import type { ChainName } from '../types.js'
+import { getClientManager, HYPERSYNC_URLS, SUPPORTED_CHAINS } from '../client.js'
+import { convertEventArgsToTypes, createTool, formatResponse } from '../utils.js'
+
+async function getLogsWithHypersync(
+  chainName: ChainName,
+  eventAbi: string,
+  hypersyncApiKey?: string,
+  address?: string,
+  fromBlock?: string,
+  toBlock?: string,
+  eventArgs?: Record<string, unknown>
+) {
+  const hypersyncUrl = HYPERSYNC_URLS[chainName]
+  if (!hypersyncUrl) {
+    throw new Error(`Hypersync not supported for chain: ${chainName}`)
+  }
+
+  const client = HypersyncClient.new({
+    url: hypersyncUrl,
+    bearerToken: hypersyncApiKey
+  })
+
+  const abiItem = parseAbiItem(eventAbi) as AbiEvent
+  const eventSignature = toEventSignature(abiItem)
+  const topic0 = keccak256(toBytes(eventSignature))
+
+  // Build topics array for filtering
+  const topics: (string | string[] | null)[] = [topic0]
+
+  // Add indexed parameter filtering if eventArgs provided
+  if (eventArgs && Object.keys(eventArgs).length > 0) {
+    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
+
+      if (argValue !== undefined) {
+        // Convert the argument to the proper format for topic filtering
+        let topicValue: string
+        if (typeof argValue === 'string' && argValue.startsWith('0x')) {
+          topicValue = argValue
+        } else if (typeof argValue === 'string' && isAddress(argValue)) {
+          topicValue = argValue.toLowerCase().padStart(66, '0x000000000000000000000000')
+        } else {
+          // For other types, we'd need more sophisticated encoding
+          topicValue = String(argValue)
+        }
+        topics.push(topicValue)
+      } else {
+        topics.push(null)
+      }
+    }
+  }
+
+  const query = {
+    fieldSelection: {
+      log: [
+        LogField.Address,
+        LogField.Topic0,
+        LogField.Topic1,
+        LogField.Topic2,
+        LogField.Topic3,
+        LogField.Data,
+        LogField.BlockNumber,
+        LogField.BlockHash,
+        LogField.TransactionHash,
+        LogField.TransactionIndex,
+        LogField.LogIndex
+      ]
+    },
+    fromBlock: fromBlock ? Number.parseInt(fromBlock) : 0,
+    toBlock: toBlock ? Number.parseInt(toBlock) : undefined,
+    logs: [
+      {
+        address: address ? [address] : undefined,
+        topics: topics.filter(t => t !== null).map(t => (Array.isArray(t) ? t : [t]))
+      }
+    ]
+  }
+
+  const res = await client.get(query)
+
+  // Convert hypersync logs to viem-compatible format
+  const decodedLogs = res.data.logs
+    .map((log: Log) => {
+      try {
+        return {
+          address: log.address as Address,
+          blockHash: log.blockHash as `0x${string}`,
+          blockNumber: log.blockNumber ? BigInt(log.blockNumber) : 0n,
+          data: log.data as `0x${string}`,
+          logIndex: log.logIndex,
+          topics: log.topics as `0x${string}`[],
+          transactionHash: log.transactionHash as `0x${string}`,
+          transactionIndex: log.transactionIndex,
+          eventName: abiItem.name,
+          args: {}
+        }
+      } catch (error) {
+        console.warn('Failed to decode log:', error)
+        return null
+      }
+    })
+    .filter((log): log is NonNullable<typeof log> => log !== null)
+
+  return decodedLogs
+}
+
+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.',
+    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)'),
+      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..."}')
+    }),
+    async (args) => {
+      const clientManager = getClientManager()
+      const config = (clientManager as any).config
+
+      // 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
+          }
+
+          return {
+            ...baseLogData,
+            decoded: {
+              eventName: log.eventName,
+              args: log.args
+            }
+          }
+        })
+
+        return formatResponse({
+          logs: serializedLogs,
+          eventSignature: toEventSignature(abiItem),
+          chain: args.chain,
+          fromBlock: fromBlockNum?.toString() || 'latest',
+          toBlock: toBlockNum?.toString() || 'latest',
+          count: logs.length,
+          dataSource: 'viem',
+          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 (HYPERSYNC_URLS[args.chain as ChainName] && args.chain !== 'localhost') {
+          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
+                }
+              }
+            })
+
+            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}`)
+        }
+      }
+    }
+  )
+}

package/src/tools/signatures.ts

@@ -0,0 +1,126 @@
+import {
+  type AbiEvent,
+  type AbiFunction,
+  type AbiParameter,
+  keccak256,
+  parseAbiItem,
+  toBytes,
+  toEventSignature,
+  toFunctionSignature
+} from 'viem'
+import { z } from 'zod'
+import type { AbiError } from '../types.js'
+import { createTool, formatResponse } from '../utils.js'
+
+const FunctionAbiSchema = z.object({
+  functionAbi: z.string().describe('Function ABI definition (e.g., "function transfer(address to, uint256 amount)")')
+})
+
+const EventAbiSchema = z.object({
+  eventAbi: z
+    .string()
+    .describe('Event ABI definition (e.g., "event Transfer(address indexed from, address indexed to, uint256 value)")')
+})
+
+const ErrorAbiSchema = z.object({
+  errorAbi: z
+    .string()
+    .describe('Error ABI definition (e.g., "error InsufficientBalance(uint256 available, uint256 required)")')
+})
+
+export default {
+  get_function_signature: createTool(
+    'Calculate Function Signatures',
+    'Generate 4-byte function selectors from ABI definitions. BATCH OPTIMIZED - use for transaction decoding.',
+    z.object({
+      items: z
+        .array(FunctionAbiSchema)
+        .describe('Array of function ABI definitions. Batch multiple functions for efficiency.')
+    }),
+    async (args) => {
+      try {
+        const results = args.items.map((item) => {
+          const abiItem = parseAbiItem(item.functionAbi) as AbiFunction
+          const signature = toFunctionSignature(abiItem)
+          const hash = keccak256(toBytes(signature))
+          const selector = hash.slice(0, 10)
+
+          return {
+            signature: selector,
+            fullSignature: signature,
+            functionName: abiItem.name,
+            inputs: abiItem.inputs,
+            outputs: abiItem.outputs || [],
+            stateMutability: abiItem.stateMutability,
+            originalAbi: item.functionAbi
+          }
+        })
+
+        return formatResponse(results)
+      } catch (error) {
+        throw new Error(`Failed to parse function ABI: ${error}`)
+      }
+    }
+  ),
+
+  get_event_signature: createTool(
+    'Calculate Event Signatures',
+    'Generate event topic0 hashes from ABI definitions. BATCH OPTIMIZED - use for log filtering setup.',
+    z.object({
+      items: z.array(EventAbiSchema).describe('Array of event ABI definitions. Batch multiple events for optimal performance.')
+    }),
+    async (args) => {
+      try {
+        const results = args.items.map((item) => {
+          const abiItem = parseAbiItem(item.eventAbi) as AbiEvent
+          const signature = toEventSignature(abiItem)
+          const hash = keccak256(toBytes(signature))
+
+          return {
+            signature: hash,
+            topic0: hash,
+            fullSignature: signature,
+            eventName: abiItem.name,
+            inputs: abiItem.inputs,
+            anonymous: abiItem.anonymous || false,
+            originalAbi: item.eventAbi
+          }
+        })
+
+        return formatResponse(results)
+      } catch (error) {
+        throw new Error(`Failed to parse event ABI: ${error}`)
+      }
+    }
+  ),
+
+  get_error_signature: createTool(
+    'Calculate Error Signatures',
+    'Generate 4-byte error selectors from ABI definitions. BATCH OPTIMIZED - use for revert reason decoding.',
+    z.object({
+      items: z.array(ErrorAbiSchema).describe('Array of error ABI definitions. Batch related errors for efficiency.')
+    }),
+    async (args) => {
+      try {
+        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(',')})`
+          const hash = keccak256(toBytes(signature))
+          const selector = hash.slice(0, 10)
+
+          return {
+            signature: selector,
+            fullSignature: signature,
+            errorName: abiItem.name,
+            inputs: abiItem.inputs,
+            originalAbi: item.errorAbi
+          }
+        })
+
+        return formatResponse(results)
+      } catch (error) {
+        throw new Error(`Failed to parse error ABI: ${error}`)
+      }
+    }
+  )
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+import type { AbiParameter } from 'viem'
+
+// Define AbiError type since it's not exported by viem
+export interface AbiError {
+  type: 'error'
+  name: string
+  inputs: readonly AbiParameter[]
+}
+
+// Configuration interface
+export interface Config {
+  etherscanApiKey?: string
+  alchemyApiKey?: string
+  infuraApiKey?: string
+  customRpcUrls?: Record<string, string>
+  hypersyncApiKey?: string
+}
+
+// Chain names
+export type ChainName = 'mainnet' | 'base' | 'arbitrum' | 'polygon' | 'optimism' | 'celo' | 'localhost'
+
+// Tool handler result type
+export interface ToolResult {
+  [x: string]: unknown
+  content: Array<{
+    type: 'text'
+    text: string
+  }>
+}

package/src/utils.ts

@@ -0,0 +1,222 @@
+import type { AbiParameter } from 'viem'
+import type { ToolResult } from './types.js'
+import { z } from 'zod'
+
+// Create tool helper
+export function createTool<T extends z.ZodType>(
+  title: string,
+  description: string,
+  schema: T,
+  handler: (args: z.infer<T>) => Promise<ToolResult>
+) {
+  return {
+    title,
+    description,
+    schema,
+    handler
+  }
+}
+
+// Convert BigInt values to strings for JSON serialization
+export function convertBigIntToString(obj: unknown): unknown {
+  if (typeof obj === 'bigint') {
+    return obj.toString()
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(item => convertBigIntToString(item))
+  }
+  if (obj && typeof obj === 'object') {
+    const converted: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(obj)) {
+      converted[key] = convertBigIntToString(value)
+    }
+    return converted
+  }
+  return obj
+}
+
+// Convert arguments to appropriate types based on ABI
+export function convertArgumentsToTypes(
+  args: (string | number | boolean | null)[],
+  abiInputs: readonly AbiParameter[]
+): unknown[] {
+  return args.map((arg, index) => {
+    if (index >= abiInputs.length) {
+      throw new Error(`Too many arguments provided. Expected ${abiInputs.length}, got ${args.length}`)
+    }
+
+    const param = abiInputs[index]
+    if (!param?.type) {
+      throw new Error(`Missing type information for parameter at index ${index}`)
+    }
+
+    const paramType = param.type
+
+    // Handle null values
+    if (arg === null) {
+      return null
+    }
+
+    // Handle different parameter types
+    if (paramType === 'address') {
+      return String(arg)
+    }
+
+    if (paramType === 'bool') {
+      if (typeof arg === 'boolean') return arg
+      if (typeof arg === 'string') return arg.toLowerCase() === 'true'
+      return Boolean(arg)
+    }
+
+    if (paramType.startsWith('uint') || paramType.startsWith('int')) {
+      if (typeof arg === 'number') return BigInt(arg)
+      if (typeof arg === 'string') return BigInt(arg)
+      throw new Error(`Invalid type for ${paramType}: ${typeof arg}`)
+    }
+
+    if (paramType === 'string') {
+      return String(arg)
+    }
+
+    if (paramType === 'bytes' || paramType.startsWith('bytes')) {
+      return String(arg)
+    }
+
+    // For other types, try to convert appropriately
+    if (typeof arg === 'string' && arg.startsWith('0x')) {
+      return arg // Assume it's already properly formatted
+    }
+    return arg
+  })
+}
+
+// Convert event arguments to appropriate types
+export function convertEventArgsToTypes(
+  eventArgs: Record<string, unknown>,
+  abiInputs: readonly AbiParameter[]
+): Record<string, unknown> {
+  const converted: Record<string, unknown> = {}
+
+  for (const [argName, argValue] of Object.entries(eventArgs)) {
+    // Find the parameter definition for this argument name
+    const param = abiInputs.find(input => input.name === argName)
+
+    if (!param) {
+      throw new Error(`Parameter '${argName}' not found in event ABI`)
+    }
+
+    if (!param.type) {
+      throw new Error(`Missing type information for parameter '${argName}'`)
+    }
+
+    const paramType = param.type
+
+    // Handle null/undefined values
+    if (argValue === null || argValue === undefined) {
+      converted[argName] = null
+      continue
+    }
+
+    // Handle different parameter types
+    if (paramType === 'address') {
+      converted[argName] = String(argValue)
+    } else if (paramType === 'bool') {
+      if (typeof argValue === 'boolean') {
+        converted[argName] = argValue
+      } else if (typeof argValue === 'string') {
+        converted[argName] = argValue.toLowerCase() === 'true'
+      } else {
+        converted[argName] = Boolean(argValue)
+      }
+    } else if (paramType.startsWith('uint') || paramType.startsWith('int')) {
+      if (typeof argValue === 'number') {
+        converted[argName] = BigInt(argValue)
+      } else if (typeof argValue === 'string') {
+        converted[argName] = BigInt(argValue)
+      } else {
+        throw new Error(`Invalid type for ${paramType}: ${typeof argValue}`)
+      }
+    } else if (paramType === 'string') {
+      converted[argName] = String(argValue)
+    } else if (paramType === 'bytes' || paramType.startsWith('bytes')) {
+      converted[argName] = String(argValue)
+    } else {
+      // For other types, handle arrays and try to convert appropriately
+      if (Array.isArray(argValue)) {
+        converted[argName] = argValue
+      } else if (typeof argValue === 'string' && argValue.startsWith('0x')) {
+        converted[argName] = argValue // Assume it's already properly formatted
+      } else {
+        converted[argName] = argValue
+      }
+    }
+  }
+
+  return converted
+}
+
+// Format response as tool result
+export function formatResponse(data: unknown): ToolResult {
+  const serializable = convertBigIntToString(data)
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(serializable, null, 2)
+      }
+    ]
+  }
+}
+
+// Parse command line arguments
+export function parseCommandLineArgs(): {
+  etherscanApiKey?: string
+  alchemyApiKey?: string
+  infuraApiKey?: string
+  customRpcUrls?: Record<string, string>
+  hypersyncApiKey?: string
+  showHelp?: boolean
+} {
+  const config: {
+    etherscanApiKey?: string
+    alchemyApiKey?: string
+    infuraApiKey?: string
+    customRpcUrls?: Record<string, string>
+    hypersyncApiKey?: string
+    showHelp?: boolean
+  } = {}
+
+  function getArgValue(argName: string): string | undefined {
+    const args = process.argv
+    const index = args.findIndex(arg => arg === argName)
+    return index !== -1 && index + 1 < args.length ? args[index + 1] : undefined
+  }
+
+  function hasArg(argName: string): boolean {
+    return process.argv.includes(argName)
+  }
+
+  // Check for help flag
+  if (hasArg('--help') || hasArg('-h')) {
+    config.showHelp = true
+    return config
+  }
+
+  // Parse environment variables and command line arguments
+  config.etherscanApiKey = process.env.ETHERSCAN_API_KEY || getArgValue('--etherscan-api-key')
+  config.alchemyApiKey = process.env.ALCHEMY_API_KEY || getArgValue('--alchemy-api-key')
+  config.infuraApiKey = process.env.INFURA_API_KEY || getArgValue('--infura-api-key')
+  config.hypersyncApiKey = process.env.HYPERSYNC_API_KEY || getArgValue('--hypersync-api-key')
+
+  // Parse custom RPC URLs
+  const customRpcs = getArgValue('--custom-rpc')
+  if (customRpcs) {
+    try {
+      config.customRpcUrls = JSON.parse(customRpcs)
+    } catch {
+      console.error('Invalid JSON for --custom-rpc:', customRpcs)
+    }
+  }
+
+  return config
+}