web3-tools-mcp 2.0.2 → 3.1.0

package/src/tools/read/logs.ts

@@ -0,0 +1,281 @@
+import { HypersyncClient, type Log, LogField } from '@envio-dev/hypersync-client'
+import {
+  type AbiEvent,
+  type Address,
+  decodeEventLog,
+  type Hex,
+  isAddress,
+  keccak256,
+  numberToHex,
+  padHex,
+  parseAbiItem,
+  toBytes,
+  toEventSignature
+} from 'viem'
+import { z } from 'zod'
+import { getClientManager, SUPPORTED_CHAINS } from '../../client.js'
+import type { ChainName } from '../../types.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
+ * left-padded to fit. Passing one through unpadded is rejected outright by Hypersync.
+ */
+function toTopic(value: unknown): Hex {
+  if (typeof value === 'number' || typeof value === 'bigint') {
+    return padHex(numberToHex(value), { size: 32 })
+  }
+  if (typeof value === 'boolean') {
+    return padHex(value ? '0x01' : '0x00', { size: 32 })
+  }
+  if (typeof value === 'string' && (isAddress(value) || value.startsWith('0x'))) {
+    return padHex(value.toLowerCase() as Hex, { size: 32 })
+  }
+  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,
+  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}`)
+  }
+
+  const client = HypersyncClient.new({
+    url: hypersyncUrl,
+    bearerToken: hypersyncApiKey
+  })
+
+  const topic0 = keccak256(toBytes(toEventSignature(abiItem)))
+
+  // Build topics array for filtering
+  const topics: (Hex | Hex[] | null)[] = [topic0]
+
+  // Add indexed parameter filtering if eventArgs provided
+  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 : toTopics(argValue))
+    }
+  }
+
+  const latest = fromBlock && toBlock ? 0 : await client.getHeight()
+  const range = hypersyncRange(fromBlock, toBlock, latest)
+
+  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
+      ]
+    },
+    ...range,
+    logs: [
+      {
+        address: address ? [address] : undefined,
+        // An unfiltered position is an empty list, not a dropped entry: removing it would
+        // slide every later filter up a slot and match on the wrong parameter.
+        topics: topics.map((t) => (t === null ? [] : Array.isArray(t) ? t : [t]))
+      }
+    ]
+  }
+
+  // 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
+  }
+
+  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
+
+      try {
+        const { args } = decodeEventLog({ abi: [abiItem], data, topics })
+        return {
+          address: log.address as Address,
+          blockHash: log.blockHash as Hex,
+          blockNumber: log.blockNumber !== undefined ? BigInt(log.blockNumber) : null,
+          data,
+          logIndex: log.logIndex,
+          topics,
+          transactionHash: log.transactionHash as Hex,
+          transactionIndex: log.transactionIndex,
+          eventName: abiItem.name,
+          args: args ?? {}
+        }
+      } catch (error) {
+        console.warn('Failed to decode log:', error)
+        return null
+      }
+    })
+    .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. 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 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..."}. A list matches any of its values: {"to": ["0x1...", "0x2..."]}'
+        )
+    }),
+    async (args) => {
+      const clientManager = getClientManager()
+      const chain = args.chain as ChainName
+      const abiItem = parseAbiItem(args.eventAbi) as AbiEvent
+
+      if (args.address && !isAddress(args.address)) {
+        throw new Error(`Invalid contract address: ${args.address}`)
+      }
+
+      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({
+          ...capped,
+          eventSignature: toEventSignature(abiItem),
+          chain: args.chain,
+          fromBlock: fromBlockNum?.toString() || 'latest',
+          toBlock: toBlockNum?.toString() || 'latest',
+          count: capped.logs.length,
+          dataSource,
+          filters: {
+            address: args.address || null,
+            eventArgs: args.eventArgs || null
+          }
+        })
+      }
+
+      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)}`)
+
+        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/{signatures.ts → read/signatures.ts}

@@ -1,7 +1,6 @@
 import {
   type AbiEvent,
   type AbiFunction,
-  type AbiParameter,
   encodeFunctionData,
   keccak256,
   parseAbiItem,
@@ -10,8 +9,8 @@ import {
   toFunctionSignature
 } from 'viem'
 import { z } from 'zod'
-import type { AbiError } from '../types.js'
-import { createTool, formatResponse } from '../utils.js'
+import type { AbiError } from '../../types.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

@@ -0,0 +1,92 @@
+import { z } from 'zod'
+import { collectSigningRequest } from '../../signing-requests.js'
+import { createTool, formatResponse } from '../../utils.js'
+import { failure } from '../sign/errors.js'
+
+/**
+ * Collecting a signature that was not given within the tool call that asked for it.
+ *
+ * A read rather than a signing tool on purpose: the signature was requested — and charged
+ * for — once already, and a host metering signing should not bill an agent again for asking
+ * whether the human has got round to it yet.
+ */
+export default {
+  check_signing_request: createTool(
+    'Check Signing Request',
+    'Collect the result of a signing request that was still waiting for approval. Waits a while for the user to approve, then reports back. Call this instead of asking for the signature again — repeating the original tool would put a second request in front of the wallet.',
+    z.object({
+      requestId: z.string().describe('The requestId returned when the signing tool said it was awaiting approval')
+    }),
+    async (args, identity) => {
+      try {
+        const request = await collectSigningRequest(args.requestId, identity)
+
+        const waitedFor = `${Math.round((Date.now() - request.startedAt) / 1000)}s`
+
+        if (request.state === 'pending') {
+          // Approved already and waiting on the chain is a different thing to report: there
+          // is nothing left for the user to do, and nothing to chase them about.
+          if (request.stage === 'mining') {
+            return formatResponse({
+              success: true,
+              status: 'mining',
+              requestId: request.id,
+              what: request.summary,
+              transactionHash: request.txHash,
+              waitingFor: waitedFor,
+              nextStep: 'Approved and broadcast. Call this again with the same requestId to get the mined result.',
+              message: 'Signed and sent. Waiting for it to be mined.'
+            })
+          }
+
+          return formatResponse({
+            success: true,
+            status: 'awaiting_approval',
+            requestId: request.id,
+            what: request.summary,
+            waitingFor: waitedFor,
+            nextStep:
+              'Still not approved. Ask the user to check their wallet and approve or reject it, then call this again with the same requestId.',
+            message: 'Nothing has been signed yet.'
+          })
+        }
+
+        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 ? 'rejected' : 'outcome_unknown',
+            what: request.summary,
+            error: request.error,
+            ...(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.'
+          })
+        }
+
+        // A transaction carries how it ended on the chain; a message signature is just the
+        // signature, with nothing to mine.
+        const settled = request.result as { receipt?: { status: string; blockNumber?: string; gasUsed?: string } } | undefined
+        const reverted = settled?.receipt?.status === 'reverted'
+
+        return formatResponse({
+          success: !reverted,
+          status: settled?.receipt?.status ?? 'signed',
+          what: request.summary,
+          signedWith: request.signer,
+          result: request.result,
+          message: reverted
+            ? 'Mined, but it reverted. The gas was spent and nothing else changed.'
+            : settled?.receipt?.status === 'broadcast'
+              ? 'Approved and broadcast, but not mined yet.'
+              : 'Approved and done.'
+        })
+      } catch (error) {
+        return failure(error, 'Could not check that signing request')
+      }
+    }
+  )
+}

package/src/tools/sign/errors.ts

@@ -0,0 +1,28 @@
+import { log } from '../../log.js'
+import { formatResponse } from '../../utils.js'
+
+/**
+ * WalletConnect rejects with a plain `{ code, message }` rather than an Error, which
+ * String() renders as "[object Object]" — the reason a wallet gave for refusing is the
+ * whole point of the message, so dig it out.
+ */
+export function describeError(error: unknown): string {
+  if (error instanceof Error) return error.message
+  if (error && typeof error === 'object') {
+    const { message, code, reason } = error as { message?: string; code?: number; reason?: string }
+    const text = message ?? reason
+    if (text) return code === undefined ? text : `${text} (code ${code})`
+    return JSON.stringify(error)
+  }
+  return String(error)
+}
+
+/** A refused or failed signing attempt, reported to the caller and to the log alike. */
+export function failure(error: unknown, message: string) {
+  log('warning', 'Transaction', `${message} — ${describeError(error)}`)
+  return formatResponse({
+    success: false,
+    error: describeError(error),
+    message
+  })
+}