GoldRush MCP Server

Instructions

Implementation Reference

• src/services/BaseService.ts:264-346 (handler)

  Registration and handler implementation for the 'log_events_by_topic' tool, which uses the Covalent GoldRush client to fetch log events by topic hash.

  server.tool(
      "log_events_by_topic",
      "Commonly used to get all event logs of the same topic hash across all contracts within a particular chain. " +
          "Useful for cross-sectional analysis of event logs that are emitted on-chain." +
          "Requires chainName (blockchain network) and topicHash (the event signature hash). " +
          "Optional parameters include block range (startingBlock, endingBlock), secondaryTopics for " +
          "filtering by additional parameters, and pagination settings (pageSize default 10, pageNumber default 0). " +
          "Returns decoded event logs matching the specified topic hash, ideal for tracking specific " +
          "event types across multiple contracts on a blockchain.",
      {
          chainName: z
              .enum(Object.values(ChainName) as [string, ...string[]])
              .describe(
                  "The blockchain network to query (e.g., 'eth-mainnet', 'matic-mainnet', 'bsc-mainnet')."
              ),
          topicHash: z
              .string()
              .describe(
                  "The event signature hash (topic[0]) to search for. This is the keccak256 hash of the event signature."
              ),
          startingBlock: z
              .union([z.string(), z.number()])
              .optional()
              .describe(
                  "Starting block number to begin search from. Use with endingBlock to define a range."
              ),
          endingBlock: z
              .union([z.string(), z.number()])
              .optional()
              .describe(
                  "Ending block number to search until. Use with startingBlock to define a range."
              ),
          secondaryTopics: z
              .string()
              .optional()
              .describe(
                  "Additional topic filters (topic[1], topic[2], topic[3]) to narrow down the search."
              ),
          pageSize: z
              .number()
              .optional()
              .default(10)
              .describe(
                  "Number of log events to return per page. Default is 10, maximum is 100."
              ),
          pageNumber: z
              .number()
              .optional()
              .default(0)
              .describe(
                  "Page number for pagination, starting from 0. Default is 0."
              ),
      },
      async (params) => {
          try {
              const response =
                  await goldRushClient.BaseService.getLogEventsByTopicHashByPage(
                      params.chainName as Chain,
                      params.topicHash,
                      {
                          startingBlock: params.startingBlock,
                          endingBlock: params.endingBlock,
                          secondaryTopics: params.secondaryTopics,
                          pageSize: params.pageSize,
                          pageNumber: params.pageNumber,
                      }
                  );
              return {
                  content: [
                      {
                          type: "text",
                          text: stringifyWithBigInt(response.data),
                      },
                  ],
              };
          } catch (err) {
              return {
                  content: [{ type: "text", text: `Error: ${err}` }],
                  isError: true,
              };
          }
      }
  );