query-events

Instructions

Implementation Reference

• src/index.ts:91-114 (registration)

  Registration of the 'query-events' MCP tool, including input schema and inline handler function.

  server.tool(
    "query-events",
    "Query events from the Mina blockchain with optional filters",
    {
      address: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{55,60}$/, 'Invalid Ethereum address format'),
      tokenId: z.string().optional().describe("Token ID to filter transactions"),
      status: z.enum(Object.values(BlockStatusFilter) as [BlockStatusFilter, ...BlockStatusFilter[]]).optional().describe("Transaction status to filter"),
      to: z.number().optional().describe("Block height to filter transactions"),
      from: z.number().optional().describe("Block height to filter transactions"),
    },
    async ({ address, tokenId, status, to, from }) => {
      try {
        const result = await minaClient.queryEvents({address, tokenId, status, to, from});
        return {
          content: [{
            type: "text",
            text: JSON.stringify(result, null, 2)
          }]
        };
      } catch (error) {
        throw new Error(`Failed to query events: ${error}`);
      }
    }
  );

• src/index.ts:101-113 (handler)

  Inline handler function for the 'query-events' tool that invokes the GraphQL client and returns formatted JSON response.

  async ({ address, tokenId, status, to, from }) => {
    try {
      const result = await minaClient.queryEvents({address, tokenId, status, to, from});
      return {
        content: [{
          type: "text",
          text: JSON.stringify(result, null, 2)
        }]
      };
    } catch (error) {
      throw new Error(`Failed to query events: ${error}`);
    }
  }

• src/index.ts:94-100 (schema)

  Input schema definition using Zod for validating parameters to the 'query-events' tool.

  {
    address: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{55,60}$/, 'Invalid Ethereum address format'),
    tokenId: z.string().optional().describe("Token ID to filter transactions"),
    status: z.enum(Object.values(BlockStatusFilter) as [BlockStatusFilter, ...BlockStatusFilter[]]).optional().describe("Transaction status to filter"),
    to: z.number().optional().describe("Block height to filter transactions"),
    from: z.number().optional().describe("Block height to filter transactions"),
  },

• src/graphql-client.ts:163-201 (helper)

  Core helper function in MinaGraphQLClient that constructs and executes the GraphQL query for events based on filter options.

  async queryEvents(filterOptions: EventFilterOptions): Promise<{ events: EventOutput[] }> {
    // Convert filter options to GraphQL input format
    const inputParams = Object.entries(filterOptions)
      .filter(([_, value]) => value !== undefined)
      .map(([key, value]) => `${key}: ${typeof value === 'string' ? `"${value}"` : value}`)
      .join(', ');
  
    const query = `
      query {
        events(input: {${inputParams}}) {
          blockInfo {
            height
            stateHash
            parentHash
            ledgerHash
            chainStatus
            timestamp
            globalSlotSinceHardfork
            globalSlotSinceGenesis
            distanceFromMaxBlockHeight
          }
          eventData {
            accountUpdateId
            data
            transactionInfo {
              status
              hash
              memo
              authorizationKind
              sequenceNumber
              zkappAccountUpdateIds
            }
          }
        }
      }
    `;
  
    return this.client.request(query);
  }

• src/graphql-client.ts:15-21 (schema)

  TypeScript interface defining the filter options for querying events, used by the client method.

  export interface EventFilterOptions {
    address: string;
    tokenId?: string;
    status?: BlockStatusFilter;
    to?: number;
    from?: number;
  }