log_events_by_address

Instructions

Implementation Reference

• src/services/BaseService.ts:187-262 (handler)

  The MCP tool handler for log_events_by_address. It calls goldRushClient.BaseService.getLogEventsByAddressByPage() with chainName, contractAddress, optional startingBlock/endingBlock, pageSize (default 10), and pageNumber (default 0). Returns the response data serialized with stringifyWithBigInt, or an error message.

  server.tool(
      "log_events_by_address",
      "Commonly used to get all the event logs emitted from a particular contract address. " +
          "Useful for building dashboards that examine on-chain interactions." +
          "Requires chainName (blockchain network) and contractAddress (the address emitting events). " +
          "Optional parameters include block range (startingBlock, endingBlock) and pagination settings " +
          "(pageSize default 10, pageNumber default 0). " +
          "Returns decoded event logs for the specified contract, useful for monitoring specific " +
          "smart contract activity and analyzing on-chain events.",
      {
          chainName: z
              .enum(Object.values(ChainName) as [string, ...string[]])
              .describe(
                  "The blockchain network to query (e.g., 'eth-mainnet', 'matic-mainnet', 'bsc-mainnet')."
              ),
          contractAddress: z
              .string()
              .describe(
                  "The smart contract address to get event logs from. Supports ENS, RNS, Lens Handle, and Unstoppable Domain resolution."
              ),
          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."
              ),
          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.getLogEventsByAddressByPage(
                      params.chainName as Chain,
                      params.contractAddress,
                      {
                          startingBlock: params.startingBlock,
                          endingBlock: params.endingBlock,
                          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,
              };
          }
      }
  );

• src/services/BaseService.ts:196-233 (schema)

  Zod schema for log_events_by_address inputs: chainName (enum of ChainName), contractAddress (string), optional startingBlock/endingBlock (string|number), optional pageSize (number, default 10), optional pageNumber (number, default 0).

  {
      chainName: z
          .enum(Object.values(ChainName) as [string, ...string[]])
          .describe(
              "The blockchain network to query (e.g., 'eth-mainnet', 'matic-mainnet', 'bsc-mainnet')."
          ),
      contractAddress: z
          .string()
          .describe(
              "The smart contract address to get event logs from. Supports ENS, RNS, Lens Handle, and Unstoppable Domain resolution."
          ),
      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."
          ),
      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."
          ),
  },

• src/services/BaseService.ts:187-262 (registration)

  The tool is registered via server.tool() with the name 'log_events_by_address' inside the addBaseServiceTools function, which is called from src/server.ts at line 69.

  server.tool(
      "log_events_by_address",
      "Commonly used to get all the event logs emitted from a particular contract address. " +
          "Useful for building dashboards that examine on-chain interactions." +
          "Requires chainName (blockchain network) and contractAddress (the address emitting events). " +
          "Optional parameters include block range (startingBlock, endingBlock) and pagination settings " +
          "(pageSize default 10, pageNumber default 0). " +
          "Returns decoded event logs for the specified contract, useful for monitoring specific " +
          "smart contract activity and analyzing on-chain events.",
      {
          chainName: z
              .enum(Object.values(ChainName) as [string, ...string[]])
              .describe(
                  "The blockchain network to query (e.g., 'eth-mainnet', 'matic-mainnet', 'bsc-mainnet')."
              ),
          contractAddress: z
              .string()
              .describe(
                  "The smart contract address to get event logs from. Supports ENS, RNS, Lens Handle, and Unstoppable Domain resolution."
              ),
          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."
              ),
          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.getLogEventsByAddressByPage(
                      params.chainName as Chain,
                      params.contractAddress,
                      {
                          startingBlock: params.startingBlock,
                          endingBlock: params.endingBlock,
                          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,
              };
          }
      }
  );

• src/utils/helpers.ts:7-13 (helper)

  Helper function that serializes data to JSON, converting BigInt values to strings to avoid serialization errors. Used to format the response data from log_events_by_address.

  export function stringifyWithBigInt(value: any): string {
      return JSON.stringify(
          value,
          (_, val) => (typeof val === "bigint" ? val.toString() : val),
          2
      );
  }