feat: integrate The Graph support into EAS client

[robbeverhelst]

• Added dependency on @settlemint/sdk-thegraph.
• Updated EASClient to initialize The Graph client if configured.
• Enhanced getSchemas and getAttestations methods to require The Graph configuration for bulk queries.
• Updated tests to reflect new error messages related to The Graph configuration.
• Introduced EASTheGraphOptions type for better type safety in client options.

Summary by Sourcery

Integrate The Graph client into EASClient to support bulk listing of schemas and attestations via GraphQL, add related configuration, example, and subgraph scaffolding.

New Features:

• Enable optional The Graph integration in EASClient via new theGraph config.
• Implement bulk listing of schemas and attestations using The Graph GraphQL client.
• Add an example script demonstrating The Graph workflow for schemas and attestations.
• Scaffold a subgraph definition with mapping, manifest, schema, and ABIs for indexing EAS events.

Enhancements:

• Introduce EASTheGraphOptions type for better type safety of The Graph configuration.
• Update error messages in getSchemas and getAttestations to reflect The Graph requirement.

Build:

• Add @settlemint/sdk-thegraph dependency.

Tests:

• Update tests to assert new error messages when The Graph is not configured.

[gemini-code-assist]

Summary of Changes

Hello @robbeverhelst, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

I've implemented a significant feature by integrating The Graph support directly into the EAS client. This enhancement allows the client to perform bulk queries for schemas and attestations, which were previously limited or unavailable through direct contract interactions. The change introduces a new dependency, updates core client methods to leverage The Graph for data retrieval, and includes all necessary subgraph definition files to enable comprehensive indexing of EAS-related blockchain data. This greatly expands the client's ability to efficiently access and process large sets of on-chain information.

Highlights

• The Graph Integration: I've integrated The Graph support into the EAS client, allowing it to connect to and query subgraphs. This enables more powerful and flexible data retrieval capabilities for schemas and attestations.
• Bulk Query Capabilities: The getSchemas and getAttestations methods have been significantly enhanced. They now leverage The Graph for bulk queries, providing a way to list multiple schemas and attestations efficiently, including filtering options for attestations.
• New Example Workflow: I've added a new example, the-graph-workflow.ts, to demonstrate how to configure the EAS SDK with The Graph and perform bulk reads for schemas and attestations, mirroring the style of other examples.
• Improved Type Safety and Validation: To ensure robustness, I've introduced the EASTheGraphOptions type and updated the validation schemas. This provides better type safety and ensures that The Graph client is configured correctly.
• Comprehensive Subgraph Definition: I've included all the necessary files (ABIs, GraphQL schema, mapping logic, and subgraph manifest) to define and map the EAS and SchemaRegistry contracts to a The Graph subgraph, which is crucial for indexing the on-chain data.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments or fill out our survey to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request successfully integrates The Graph support into the EAS client, enabling bulk querying for schemas and attestations. The changes include adding the necessary dependency, updating the client initialization, and implementing the new data-fetching logic. The addition of a new example workflow, subgraph definitions, and validation schemas is also well-executed.

My review focuses on a few areas for improvement. I've identified a bug where pagination options are not being applied in getSchemas, a few instances of unsafe type casting that undermine the benefits of gql.tada, and some confusing data mapping logic in getAttestations. Addressing these points will improve the robustness and maintainability of the new functionality.

[gemini-code-assist]

The getSchemas method accepts an _options parameter (which includes limit and offset for pagination), but these options are not passed to the GraphQL request. The request is always sent without variables, so it will use the default first: 100 and skip: 0 defined in the query, ignoring any pagination options provided by the user. This makes the pagination feature non-functional.

  public async getSchemas(options?: GetSchemasOptions): Promise<SchemaData[]> {
    if (!this.theGraph) {
      throw new Error(
        "Schema listing requires The Graph configuration. Provide 'theGraph' options when creating EAS client.",
      );
    }

    // Basic listing without filters. Pagination can be added via @fetchAll directive.
    const query = this.theGraph.graphql(`
      query ListSchemas($first: Int = 100, $skip: Int = 0) {
        schemas(first: $first, skip: $skip) @fetchAll {
          id
          resolver
          revocable
          schema
        }
      }
    `);

    const variables = {
      first: options?.limit ?? 100,
      skip: options?.offset ?? 0,
    };

    const result = (await this.theGraph.client.request(query, variables)) as ResultOf<typeof query>;
    const list = (result as any).schemas as Array<{
      id: string;
      resolver: string;
      revocable: boolean;
      schema: string | null;
    }>;

    return list.map((s) => ({
      uid: s.id as Hex,
      resolver: s.resolver as Address,
      revocable: Boolean(s.revocable),
      schema: s.schema ?? "",
    }));
  }

[gemini-code-assist]

Using any when creating the The Graph client (createTheGraphClient<any>) disables the type-safety features of gql.tada. This leads to any types for query results downstream, forcing the use of unsafe type casts like (result as any).schemas to access the data.

While this might be a pragmatic choice to avoid making the EASClient generic over the subgraph schema, it's a significant trade-off that reduces maintainability and increases the risk of runtime errors if the GraphQL schema changes. It would be beneficial to explore ways to provide stronger types here.

[gemini-code-assist]

The mapping logic for attestations includes defensive code that seems to contradict the GraphQL query and the subgraph schema. For instance:

• (a.id ?? (a as any).uid): The schema defines id, so the fallback to uid is confusing and suggests uncertainty about the API response.
• (typeof a.schema === "string" ? a.schema : a.schema.id): The query specifically requests schema { id }, so a.schema should always be an object, not a string.

This defensive coding makes the logic harder to follow and maintain. It should be simplified to align with the expected response shape defined by the GraphQL query.

    return list.map((a) => ({
      uid: a.id as Hex,
      schema: (a.schema as { id: string }).id as Hex,
      attester: a.attester as Address,
      recipient: a.recipient as Address,
      time: a.time ? BigInt(a.time) : BigInt(0),
      expirationTime: a.expirationTime ? BigInt(a.expirationTime) : BigInt(0),
      revocable: Boolean(a.revocable),
      refUID: (a.refUID ?? ("0x" + "0".repeat(64))) as Hex,
      data: (a.data ?? "0x") as Hex,
      value: BigInt(0),
    }));