feat: index the Ethereum Follow Protocol (EFP) and expose it via the Omnigraph API

.changeset/efp-omnigraph.md

@@ -0,0 +1,6 @@
+---
+"ensapi": minor
+"enssdk": minor
+---
+
+Expose EFP (Ethereum Follow Protocol) data through the Omnigraph API under a single `efp` root field. The `EfpQuery` namespace provides `list` / `lists`, `listRecords` (with each record's owning `list`), `accountMetadata` / `accountMetadatas`, and `primaryList` (an account's validated primary list, applying the EFP two-step user-role check), with cursor-paginated connections and where-filters (owner/user/manager, recordData, address). EFP is also reachable from the ENS graph: `Account.efp` exposes an account's validated `primaryList` and the `lists` it is the `user` of, and `EfpListRecord.account` links a record to the `Account` it points at. Requires the `efp` plugin to be enabled on the indexer.

.changeset/efp-plugin.md

@@ -0,0 +1,8 @@
+---
+"@ensnode/datasources": minor
+"@ensnode/ensdb-sdk": minor
+"@ensnode/ensnode-sdk": minor
+"ensindexer": minor
+---
+
+Add an EFP (Ethereum Follow Protocol) indexer plugin. Enable it by including `efp` in the `PLUGINS` environment variable (on the `mainnet` ENS namespace, or the `ens-test-env` devnet) to index EFP list NFTs, records, tags, and account metadata into ENSDb's `efp_*` tables.

apps/ensapi/src/omnigraph-api/lib/connection-helpers.ts

@@ -1,4 +1,4 @@
-import { and, asc, desc, gt, lt } from "drizzle-orm";
+import { and, asc, desc, gt, lt, sql } from "drizzle-orm";
 import z from "zod/v4";
 
 import { cursors } from "@/omnigraph-api/lib/cursors";
@@ -42,6 +42,29 @@ export const paginateByInt = (
 export const orderPaginationBy = (column: Column, inverted: boolean) =>
   inverted ? desc(column) : asc(column);
 
+/**
+ * Cursor pagination condition for a numeric value stored in a `text` column (e.g. an EFP `tokenId`,
+ * a sequential uint256 that does not fit a Postgres integer type). Compares with a `::numeric` cast
+ * so ordering is numeric rather than lexicographic (otherwise `"10"` sorts before `"2"`, breaking
+ * ordering and the `before`/`after` cursors once there are more than 9 rows).
+ */
+export const paginateByNumericText = (
+  column: Column,
+  before: string | undefined,
+  after: string | undefined,
+) =>
+  and(
+    before ? sql`${column}::numeric < ${cursors.decode<string>(before)}::numeric` : undefined,
+    after ? sql`${column}::numeric > ${cursors.decode<string>(after)}::numeric` : undefined,
+  );
+
+/**
+ * Order-by clause matching {@link paginateByNumericText}: orders a numeric value held in a `text`
+ * column by its numeric value (ascending, or descending when `inverted`).
+ */
+export const orderByNumericText = (column: Column, inverted: boolean) =>
+  inverted ? desc(sql`${column}::numeric`) : asc(sql`${column}::numeric`);
+
 /**
  * An empty Relay Connection, used when short-circuiting connection resolvers.
  */

apps/ensapi/src/omnigraph-api/schema.ts

@@ -1,11 +1,17 @@
 import { builder } from "@/omnigraph-api/builder";
 
+import "./schema/account-efp";
 import "./schema/account-id";
 import "./schema/reverse-resolve";
 import "./schema/connection";
 import "./schema/domain";
 import "./schema/domain-canonical";
 import "./schema/domain-inputs";
+import "./schema/efp";
+import "./schema/efp-account-metadata";
+import "./schema/efp-inputs";
+import "./schema/efp-list";
+import "./schema/efp-list-record";
 import "./schema/event";
 import "./schema/label";
 import "./schema/name-or-node";

apps/ensapi/src/omnigraph-api/schema/account-efp.ts

@@ -0,0 +1,67 @@
+import { type ResolveCursorConnectionArgs, resolveCursorConnection } from "@pothos/plugin-relay";
+import { and, eq } from "drizzle-orm";
+import type { NormalizedAddress } from "enssdk";
+import type { Hex } from "viem";
+
+import di from "@/di";
+import { builder } from "@/omnigraph-api/builder";
+import { orderByNumericText, paginateByNumericText } from "@/omnigraph-api/lib/connection-helpers";
+import { lazyConnection } from "@/omnigraph-api/lib/lazy-connection";
+import { EfpListRef, TOKEN_ID_PAGINATED_CONNECTION_ARGS } from "@/omnigraph-api/schema/efp-list";
+import { resolveValidatedPrimaryListTokenId } from "@/omnigraph-api/schema/efp-primary-list";
+
+/**
+ * `AccountEfp` is the account-rooted view of Ethereum Follow Protocol data, reached via
+ * `Account.efp`. Its parent is the account's address, and every field is keyed on the EFP `user`
+ * role (the account a list represents). Protocol-rooted queries (a list by token id, "who follows
+ * this address") remain on the root `efp` namespace.
+ */
+export const AccountEfpRef = builder.objectRef<NormalizedAddress>("AccountEfp");
+
+AccountEfpRef.implement({
+  description: "An account's Ethereum Follow Protocol (EFP) presence.",
+  fields: (t) => ({
+    /////////////////////////////
+    // AccountEfp.primaryList
+    /////////////////////////////
+    primaryList: t.field({
+      description:
+        "The account's validated primary EFP list: the list named by its `primary-list` metadata, returned only if that list's `user` role matches the account (the EFP two-step Primary List validation). Null if unset, not indexed, or unvalidated.",
+      type: EfpListRef,
+      nullable: true,
+      resolve: (address) => resolveValidatedPrimaryListTokenId(address),
+    }),
+
+    ////////////////////////
+    // AccountEfp.lists
+    ////////////////////////
+    lists: t.connection({
+      description: "The EFP lists this account is the `user` of (the lists representing it).",
+      type: EfpListRef,
+      resolve: (address, args) => {
+        const { ensDb, ensIndexerSchema } = di.context;
+        const scope = eq(ensIndexerSchema.efpLists.user, address as Hex);
+
+        return lazyConnection({
+          totalCount: () => ensDb.$count(ensIndexerSchema.efpLists, scope),
+          connection: () =>
+            resolveCursorConnection(
+              { ...TOKEN_ID_PAGINATED_CONNECTION_ARGS, args },
+              ({ before, after, limit, inverted }: ResolveCursorConnectionArgs) =>
+                ensDb
+                  .select()
+                  .from(ensIndexerSchema.efpLists)
+                  .where(
+                    and(
+                      scope,
+                      paginateByNumericText(ensIndexerSchema.efpLists.tokenId, before, after),
+                    ),
+                  )
+                  .orderBy(orderByNumericText(ensIndexerSchema.efpLists.tokenId, inverted))
+                  .limit(limit),
+            ),
+        });
+      },
+    }),
+  }),
+});

apps/ensapi/src/omnigraph-api/schema/account.ts

@@ -11,6 +11,7 @@ import { getModelId } from "@/omnigraph-api/lib/get-model-id";
 import { lazyConnection } from "@/omnigraph-api/lib/lazy-connection";
 import { buildAccountPrimaryNamesSelection } from "@/omnigraph-api/lib/resolution/account-primary-names-selection";
 import { resolvePrimaryNameRecords } from "@/omnigraph-api/lib/resolution/resolve-primary-name-records";
+import { AccountEfpRef } from "@/omnigraph-api/schema/account-efp";
 import { AccountIdInput } from "@/omnigraph-api/schema/account-id";
 import {
   ID_PAGINATED_CONNECTION_ARGS,
@@ -146,6 +147,17 @@ AccountRef.implement({
         }),
     }),
 
+    ///////////////
+    // Account.efp
+    ///////////////
+    efp: t.field({
+      description:
+        "This Account's Ethereum Follow Protocol (EFP) presence: its lists and validated primary list.",
+      type: AccountEfpRef,
+      nullable: false,
+      resolve: (parent) => parent.id,
+    }),
+
     ///////////////////////
     // Account.permissions
     ///////////////////////

apps/ensapi/src/omnigraph-api/schema/efp-account-metadata.ts

@@ -0,0 +1,94 @@
+import { inArray } from "drizzle-orm";
+import type { ChainId, NormalizedAddress } from "enssdk";
+
+import di from "@/di";
+import { builder } from "@/omnigraph-api/builder";
+import { getModelId } from "@/omnigraph-api/lib/get-model-id";
+
+export const EfpAccountMetadataRef = builder.loadableObjectRef("EfpAccountMetadata", {
+  load: (ids: string[]) => {
+    const { ensDb, ensIndexerSchema } = di.context;
+    return ensDb
+      .select()
+      .from(ensIndexerSchema.efpAccountMetadata)
+      .where(inArray(ensIndexerSchema.efpAccountMetadata.id, ids));
+  },
+  toKey: getModelId,
+  cacheResolved: true,
+  sort: true,
+});
+
+export type EfpAccountMetadata = Exclude<typeof EfpAccountMetadataRef.$inferType, string>;
+
+//////////////////////
+// EfpAccountMetadata
+//////////////////////
+EfpAccountMetadataRef.implement({
+  description: 'An EFP `(address, key) -> value` account-metadata entry (e.g. "primary-list").',
+  fields: (t) => ({
+    //////////////////////////
+    // EfpAccountMetadata.id
+    //////////////////////////
+    id: t.field({ type: "String", nullable: false, resolve: (metadata) => metadata.id }),
+
+    ///////////////////////////////
+    // EfpAccountMetadata.chainId
+    ///////////////////////////////
+    chainId: t.field({
+      description: "Chain id of the AccountMetadata contract.",
+      type: "ChainId",
+      nullable: false,
+      resolve: (metadata) => metadata.chainId as ChainId,
+    }),
+
+    ///////////////////////////////////////
+    // EfpAccountMetadata.contractAddress
+    ///////////////////////////////////////
+    contractAddress: t.field({
+      description: "Address of the AccountMetadata contract.",
+      type: "Address",
+      nullable: false,
+      resolve: (metadata) => metadata.contractAddress as NormalizedAddress,
+    }),
+
+    ///////////////////////////////
+    // EfpAccountMetadata.address
+    ///////////////////////////////
+    address: t.field({
+      description: "The account this metadata belongs to.",
+      type: "Address",
+      nullable: false,
+      resolve: (metadata) => metadata.address as NormalizedAddress,
+    }),
+
+    ///////////////////////////
+    // EfpAccountMetadata.key
+    ///////////////////////////
+    key: t.field({
+      description: "The metadata key (UTF-8 string).",
+      type: "String",
+      nullable: false,
+      resolve: (metadata) => metadata.key,
+    }),
+
+    /////////////////////////////
+    // EfpAccountMetadata.value
+    /////////////////////////////
+    value: t.field({
+      description: "The metadata value (raw bytes).",
+      type: "Hex",
+      nullable: false,
+      resolve: (metadata) => metadata.value,
+    }),
+
+    /////////////////////////////////
+    // EfpAccountMetadata.createdAt
+    /////////////////////////////////
+    createdAt: t.field({ type: "BigInt", nullable: false, resolve: (m) => m.createdAt }),
+
+    /////////////////////////////////
+    // EfpAccountMetadata.updatedAt
+    /////////////////////////////////
+    updatedAt: t.field({ type: "BigInt", nullable: false, resolve: (m) => m.updatedAt }),
+  }),
+});

apps/ensapi/src/omnigraph-api/schema/efp-ids.ts

@@ -0,0 +1,22 @@
+import type { NormalizedAddress } from "enssdk";
+import type { Hex } from "viem";
+
+/**
+ * Synthetic composite primary keys for the EFP tables, mirroring the EFP plugin's
+ * `apps/ensindexer/src/plugins/efp/lib/ids.ts`. ENSApi reads ENSDb rows by these ids, so these
+ * formats MUST stay in sync with the indexer.
+ */
+
+/**
+ * `efp_account_metadata` key: `${address}-${key}`. Mirrors the indexer's `accountMetadataId`: the
+ * address is lowercase (a NormalizedAddress) and NUL bytes are stripped from the free-form `key`
+ * (the indexer strips them before writing, so a lookup must strip them too to match the stored id).
+ */
+export function efpAccountMetadataId(address: NormalizedAddress, key: string): string {
+  return `${address.toLowerCase()}-${key.replace(/\0/g, "")}`;
+}
+
+/** `efp_list_storage_locations` key: `${chainId}-${contractAddress}-${slot}` (lowercased hex). */
+export function efpStorageLocationId(chainId: number, contractAddress: Hex, slot: Hex): string {
+  return `${chainId}-${contractAddress.toLowerCase()}-${slot.toLowerCase()}`;
+}

apps/ensapi/src/omnigraph-api/schema/efp-inputs.ts

@@ -0,0 +1,45 @@
+import { builder } from "@/omnigraph-api/builder";
+
+//////////////////////
+// Inputs
+//////////////////////
+
+/**
+ * Filters for the `efp.lists` connection.
+ */
+export const EfpListsWhereInput = builder.inputType("EfpListsWhereInput", {
+  description: "Filter EFP lists by their owner, user, or manager address.",
+  fields: (t) => ({
+    owner: t.field({ type: "Address", description: "The ERC-721 owner of the list NFT." }),
+    user: t.field({ type: "Address", description: "The address allowed to post records." }),
+    manager: t.field({
+      type: "Address",
+      description: "The address allowed to administer the list.",
+    }),
+  }),
+});
+
+/**
+ * Filters for the `efp.listRecords` connection.
+ */
+export const EfpListRecordsWhereInput = builder.inputType("EfpListRecordsWhereInput", {
+  description: "Filter EFP list records.",
+  fields: (t) => ({
+    recordData: t.field({
+      type: "Address",
+      description:
+        "The target address of an address record (recordType 1). Filtering by this answers 'which lists follow this address?'.",
+    }),
+    recordType: t.field({ type: "Int", description: "The EFP record type (1 = address)." }),
+  }),
+});
+
+/**
+ * Filters for the `efp.accountMetadatas` connection.
+ */
+export const EfpAccountMetadatasWhereInput = builder.inputType("EfpAccountMetadatasWhereInput", {
+  description: "Filter EFP account metadata.",
+  fields: (t) => ({
+    address: t.field({ type: "Address", required: true, description: "The account address." }),
+  }),
+});