feat: integrate The Graph support into EAS client

sdk/eas/package.json

@@ -53,6 +53,7 @@
   "devDependencies": {},
   "dependencies": {
     "@settlemint/sdk-portal": "workspace:*",
+    "@settlemint/sdk-thegraph": "workspace:*",
     "@settlemint/sdk-utils": "workspace:*",
     "gql.tada": "^1",
     "viem": "^2",

sdk/eas/src/eas.test.ts

@@ -361,15 +361,11 @@ describe("EAS Portal Client", () => {
     expect(timestamp).toBe(BigInt(1640995200));
   });
 
-  test("should throw error on bulk query methods", async () => {
+  test("should throw error on bulk query methods when The Graph not configured", async () => {
     const client = createEASClient(optionsWithAddresses);
 
-    await expect(client.getSchemas()).rejects.toThrow(
-      "Schema listing not implemented yet. Portal's direct contract queries don't support listing all schemas",
-    );
-    await expect(client.getAttestations()).rejects.toThrow(
-      "Attestation listing not implemented yet. Portal's direct contract queries don't support listing all attestations",
-    );
+    await expect(client.getSchemas()).rejects.toThrow("Schema listing requires The Graph configuration");
+    await expect(client.getAttestations()).rejects.toThrow("Attestation listing requires The Graph configuration");
   });
 
   test("should throw error when trying to query without contract addresses", async () => {

sdk/eas/src/eas.ts

@@ -1,4 +1,5 @@
 import { createPortalClient, waitForTransactionReceipt } from "@settlemint/sdk-portal";
+import { createTheGraphClient, type ResultOf } from "@settlemint/sdk-thegraph";
 import { createLogger, requestLogger } from "@settlemint/sdk-utils/logging";
 import { validate } from "@settlemint/sdk-utils/validation";
 import type { Address, Hex } from "viem";
@@ -46,6 +47,7 @@ export class EASClient {
   private readonly portalClient: PortalClient["client"];
   private readonly portalGraphql: PortalClient["graphql"];
   private deployedAddresses?: DeploymentResult;
+  private theGraph?: ReturnType<typeof createTheGraphClient<any>>;
 
   /**
    * Create a new EAS client instance
@@ -74,6 +76,19 @@ export class EASClient {
 
     this.portalClient = portalClient;
     this.portalGraphql = portalGraphql;
+
+    // Initialize The Graph client if configured
+    if (this.options.theGraph) {
+      this.theGraph = createTheGraphClient<any>(
+        {
+          instances: this.options.theGraph.instances,
+          accessToken: this.options.theGraph.accessToken,
+          subgraphName: this.options.theGraph.subgraphName,
+          cache: this.options.theGraph.cache,
+        },
+        undefined,
+      );
+    }
   }
 
   /**
@@ -538,9 +553,38 @@ export class EASClient {
    * Consider using getSchema() for individual schema lookups.
    */
   public async getSchemas(_options?: GetSchemasOptions): Promise<SchemaData[]> {
-    throw new Error(
-      "Schema listing not implemented yet. Portal's direct contract queries don't support listing all schemas. Use getSchema() for individual schema lookups or implement The Graph subgraph integration for bulk queries.",
-    );
+    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 result = (await this.theGraph.client.request(query)) 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 ?? "",
+    }));
   }
 
   /**
@@ -586,10 +630,72 @@ export class EASClient {
    * as Portal's direct contract queries don't support listing all attestations.
    * Consider using getAttestation() for individual attestation lookups.
    */
-  public async getAttestations(_options?: GetAttestationsOptions): Promise<AttestationInfo[]> {
-    throw new Error(
-      "Attestation listing not implemented yet. Portal's direct contract queries don't support listing all attestations. Use getAttestation() for individual attestation lookups or implement The Graph subgraph integration for bulk queries.",
-    );
+  public async getAttestations(options?: GetAttestationsOptions): Promise<AttestationInfo[]> {
+    if (!this.theGraph) {
+      throw new Error(
+        "Attestation listing requires The Graph configuration. Provide 'theGraph' options when creating EAS client.",
+      );
+    }
+
+    const query = this.theGraph.graphql(`
+      query ListAttestations($first: Int = 100, $skip: Int = 0, $schema: Bytes, $attester: Bytes, $recipient: Bytes) {
+        attestations(
+          first: $first
+          skip: $skip
+          where: {
+            ${options?.schema ? "schema: $schema" : ""}
+            ${options?.attester ? "attester: $attester" : ""}
+            ${options?.recipient ? "recipient: $recipient" : ""}
+          }
+        ) @fetchAll {
+          id
+          schema { id }
+          attester
+          recipient
+          time
+          expirationTime
+          revocable
+          refUID
+          data
+          revokedAt
+        }
+      }
+    `);
+
+    const variables: Record<string, unknown> = {
+      first: options?.limit ?? 100,
+      skip: options?.offset ?? 0,
+    };
+    if (options?.schema) variables.schema = options.schema;
+    if (options?.attester) variables.attester = options.attester;
+    if (options?.recipient) variables.recipient = options.recipient;
+
+    const result = (await this.theGraph.client.request(query, variables)) as ResultOf<typeof query>;
+    const list = (result as any).attestations as Array<{
+      id: string;
+      schema: { id: string } | string;
+      attester: string;
+      recipient: string;
+      time: string | number | null;
+      expirationTime: string | number | null;
+      revocable: boolean;
+      refUID: string | null;
+      data: string | null;
+      revokedAt?: string | null;
+    }>;
+
+    return list.map((a) => ({
+      uid: (a.id ?? (a as any).uid) as Hex,
+      schema: (typeof a.schema === "string" ? a.schema : a.schema.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),
+    }));
   }
 
   /**

sdk/eas/src/examples/the-graph-workflow.ts

@@ -0,0 +1,133 @@
+/**
+ * EAS The Graph Listing Example
+ *
+ * This example demonstrates how to configure the EAS SDK with The Graph
+ * and perform bulk reads for schemas and attestations using the same style
+ * as the other examples.
+ */
+
+import { createEASClient } from "../eas.js";
+import { createLogger, requestLogger } from "@settlemint/sdk-utils/logging";
+import { loadEnv } from "@settlemint/sdk-utils/environment";
+import type { Address, Hex } from "viem";
+import { decodeAbiParameters, parseAbiParameters } from "viem";
+
+async function theGraphWorkflow() {
+  const logger = createLogger();
+  const env = await loadEnv(true, false);
+
+  if (!env.SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT) {
+    console.error("❌ Missing SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT");
+    process.exit(1);
+  }
+  if (!env.SETTLEMINT_THEGRAPH_SUBGRAPHS_ENDPOINTS || env.SETTLEMINT_THEGRAPH_SUBGRAPHS_ENDPOINTS.length === 0) {
+    console.error("❌ Missing SETTLEMINT_THEGRAPH_SUBGRAPHS_ENDPOINTS (JSON array of subgraph URLs ending with /<name>)");
+    process.exit(1);
+  }
+
+  console.log("🚀 EAS The Graph Listing Example");
+  console.log("================================\n");
+
+  // Build client with The Graph config
+  const eas = createEASClient(
+    {
+      instance: env.SETTLEMINT_PORTAL_GRAPHQL_ENDPOINT,
+      accessToken: env.SETTLEMINT_ACCESS_TOKEN,
+      theGraph: {
+        instances: env.SETTLEMINT_THEGRAPH_SUBGRAPHS_ENDPOINTS,
+        subgraphName: env.SETTLEMINT_THEGRAPH_DEFAULT_SUBGRAPH ?? "eas",
+        accessToken: env.SETTLEMINT_ACCESS_TOKEN,
+        cache: "force-cache",
+      },
+      debug: true,
+    },
+  );
+
+  // Replace global fetch logging for visibility (no-op in Node unless used)
+  // This pattern mirrors other examples and ensures consistent logging.
+  void requestLogger(logger, "eas-thegraph", fetch);
+
+  // Step 1: List Schemas
+  console.log("📚 Step 1: List Schemas (via The Graph)");
+  try {
+    const schemas = await eas.getSchemas({ limit: 10, offset: 0 });
+    if (schemas.length === 0) {
+      console.log("⚠️  No schemas found in the subgraph\n");
+    } else {
+      console.log(`✅ Found ${schemas.length} schema(s)`);
+      for (const s of schemas) {
+        console.log(`   • ${s.uid} | revocable=${s.revocable} | resolver=${s.resolver}`);
+      }
+      console.log();
+    }
+  } catch (error) {
+    console.log("❌ Failed to list schemas:", error);
+    console.log();
+  }
+
+  // Step 2: List Attestations (optionally filter by schema/attester/recipient)
+  console.log("🧾 Step 2: List Attestations (via The Graph)");
+  try {
+    // Optional filters
+    const schemaUID = process.env.EAS_SCHEMA_UID as Hex | undefined;
+    const attester = process.env.EAS_ATTESTER as Address | undefined;
+    const recipient = (env.SETTLEMINT_DEPLOYER_ADDRESS as Address | undefined) ?? (process.env.EAS_RECIPIENT as Address | undefined);
+
+    const attestations = await eas.getAttestations({
+      limit: 10,
+      offset: 0,
+      schema: schemaUID,
+      attester,
+      recipient,
+    });
+
+    if (attestations.length === 0) {
+      console.log("⚠️  No attestations found with current filters\n");
+    } else {
+      console.log(`✅ Found ${attestations.length} attestation(s)`);
+      for (const a of attestations) {
+        console.log(`   • uid=${a.uid} schema=${a.schema} attester=${a.attester} recipient=${a.recipient}`);
+      }
+      console.log();
+    }
+  } catch (error) {
+    console.log("❌ Failed to list attestations:", error);
+    console.log();
+  }
+
+  // Step 3: (Optional) Decode attestation data for the first attestation of the first schema
+  console.log("🔍 Step 3: Optional Data Decode Example");
+  try {
+    const schemas = await eas.getSchemas({ limit: 1, offset: 0 });
+    if (schemas.length === 0) {
+      console.log("ℹ️  Skipping decode: no schemas available\n");
+      return;
+    }
+
+    const schema = schemas[0];
+    const [example] = await eas.getAttestations({ limit: 1, offset: 0, schema: schema.uid });
+    if (!example || !example.data || example.data === ("0x" as Hex)) {
+      console.log("ℹ️  Skipping decode: no example attestation with data found\n");
+      return;
+    }
+
+    // Convert the EAS schema string (e.g., "uint256 score, address user") to ABI parameter format
+    const abiParams = parseAbiParameters(schema.schema);
+    const decoded = decodeAbiParameters(abiParams, example.data);
+
+    console.log("✅ Decoded example attestation data:");
+    console.log(decoded);
+    console.log();
+  } catch (error) {
+    console.log("⚠️  Decode step failed:", error);
+    console.log();
+  }
+
+  console.log("🎉 The Graph listing example complete\n");
+}
+
+if (typeof require !== "undefined" && require.main === module) {
+  theGraphWorkflow().catch(console.error);
+}
+
+export { theGraphWorkflow };

sdk/eas/src/schema.ts

@@ -43,6 +43,11 @@ export interface SchemaField {
  */
 export type EASClientOptions = z.infer<typeof EASClientOptionsSchema>;
 
+/**
+ * Narrow type for The Graph configuration inside EAS options
+ */
+export type EASTheGraphOptions = NonNullable<EASClientOptions["theGraph"]>;
+
 /**
  * Schema registration request
  */

sdk/eas/src/utils/validation.ts

@@ -1,4 +1,4 @@
-import { ApplicationAccessTokenSchema, UrlSchema } from "@settlemint/sdk-utils/validation";
+import { ApplicationAccessTokenSchema, UrlOrPathSchema, UrlSchema } from "@settlemint/sdk-utils/validation";
 import { type Address, isAddress } from "viem";
 import { z } from "zod";
 
@@ -31,4 +31,21 @@ export const EASClientOptionsSchema = z.object({
    * Whether to enable debug mode
    */
   debug: z.boolean().optional(),
+  /**
+   * Optional The Graph configuration for enabling bulk listing queries
+   */
+  theGraph: z
+    .object({
+      /** TheGraph subgraph endpoints (must include an entry that ends with `/<subgraphName>`). */
+      instances: z.array(UrlOrPathSchema),
+      /** Subgraph name used to select the correct instance from `instances`. */
+      subgraphName: z.string(),
+      /** Optional access token for authenticated Graph endpoints. */
+      accessToken: ApplicationAccessTokenSchema.optional(),
+      /** Optional cache policy passed to GraphQL client. */
+      cache: z
+        .enum(["default", "force-cache", "no-cache", "no-store", "only-if-cached", "reload"])
+        .optional(),
+    })
+    .optional(),
 });

sdk/eas/subgraph/abis/EAS.json

@@ -0,0 +1,6 @@
+{
+  "abi": [
+    {"anonymous":false,"inputs":[{"indexed":true,"internalType":"bytes32","name":"uid","type":"bytes32"},{"indexed":true,"internalType":"bytes32","name":"schema","type":"bytes32"},{"indexed":true,"internalType":"address","name":"attester","type":"address"},{"indexed":false,"internalType":"address","name":"recipient","type":"address"},{"indexed":false,"internalType":"uint64","name":"time","type":"uint64"},{"indexed":false,"internalType":"uint64","name":"expirationTime","type":"uint64"},{"indexed":false,"internalType":"bool","name":"revocable","type":"bool"},{"indexed":false,"internalType":"bytes32","name":"refUID","type":"bytes32"},{"indexed":false,"internalType":"bytes","name":"data","type":"bytes"}],"name":"Attested","type":"event"},
+    {"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"revoker","type":"address"},{"indexed":true,"internalType":"bytes32","name":"schema","type":"bytes32"},{"indexed":true,"internalType":"address","name":"recipient","type":"address"},{"indexed":false,"internalType":"bytes32","name":"uid","type":"bytes32"}],"name":"Revoked","type":"event"}
+  ]
+}

sdk/eas/subgraph/abis/SchemaRegistry.json

@@ -0,0 +1,5 @@
+{
+  "abi": [
+    {"anonymous":false,"inputs":[{"indexed":true,"internalType":"bytes32","name":"uid","type":"bytes32"},{"indexed":true,"internalType":"address","name":"resolver","type":"address"},{"indexed":false,"internalType":"bool","name":"revocable","type":"bool"},{"indexed":false,"internalType":"string","name":"schema","type":"string"}],"name":"Registered","type":"event"}
+  ]
+}

sdk/eas/subgraph/schema.graphql

@@ -0,0 +1,24 @@
+# EAS Subgraph Schema (MVP)
+
+type Schema @entity {
+  id: Bytes! # uid
+  resolver: Bytes!
+  revocable: Boolean!
+  schema: String!
+  createdAt: BigInt!
+  txHash: Bytes!
+}
+
+type Attestation @entity {
+  id: Bytes! # uid
+  schema: Schema!
+  attester: Bytes!
+  recipient: Bytes!
+  time: BigInt!
+  expirationTime: BigInt!
+  revocable: Boolean!
+  refUID: Bytes!
+  data: Bytes!
+  revokedAt: BigInt
+  txHash: Bytes!
+}