feat(ensindexer): introduce initial efp plugin demo

.changeset/upset-glasses-strive.md

@@ -0,0 +1,8 @@
+---
+"@ensnode/datasources": minor
+"@ensnode/ensnode-schema": minor
+"@ensnode/ensnode-sdk": minor
+"ensindexer": minor
+---
+
+Introduce initial `efp` plugin demo that indexes EFP List Tokens and EFP List Storage Locations.

apps/ensindexer/src/api/index.ts

@@ -16,6 +16,7 @@ import {
   fetchPrometheusMetrics,
   makePonderMetdataProvider,
 } from "@/lib/ponder-metadata-provider";
+import { honoEFP } from "@/plugins/efp/lib/api";
 import { ponderMetadata } from "@ensnode/ponder-metadata";
 import {
   buildGraphQLSchema as buildSubgraphGraphQLSchema,
@@ -140,4 +141,7 @@ app.use(
   }),
 );
 
+// Use Hono EFP application for handling EFP-related requests
+app.route("/efp", honoEFP({ db }));
+
 export default app;

apps/ensindexer/src/lib/api-documentation.ts

@@ -305,5 +305,22 @@ const makeApiDocumentation = (isSubgraph: boolean) => {
         value: "Value of the text record",
       },
     ),
+    /**
+     * The following is documentation for packages/ensnode-schema/src/efp.schema.ts
+     */
+    ...generateTypeDocSetWithTypeName("efp_listToken", "EFP List Token", {
+      id: "Unique token ID for an EFP List Token",
+      owner: "The address of the current owner of the EFP List Token  (always lowercase)",
+      lslId:
+        "Value of `EncodedLsl` type (optional, lowercase if present). Stores the ID of the List Storage Location. If the List Storage Location was never created or not in a recognized format, this field value will be `null`.",
+    }),
+    ...generateTypeDocSetWithTypeName("efp_listStorageLocation", "EFP List Storage Location", {
+      id: "ListStorageLocation ID, an `EncodedLsl` value (always lowercase).",
+      chainId:
+        "EVM chain ID of the chain where the EFP list records are stored, an `EFPDeploymentChainId` value.",
+      listRecordsAddress:
+        "Contract address on chainId where the EFP list records are stored  (always lowercase).",
+      slot: "A unique identifier within the List Storage Location, distinguishes between multiple EFP lists stored in the same `EFPListRecords` smart contract by serving as the key in mappings for list operations and metadata.",
+    }),
   });
 };

apps/ensindexer/src/plugins/efp/handlers/EFPListRegistry.ts

@@ -0,0 +1,101 @@
+import { ponder } from "ponder:registry";
+import { efp_listStorageLocation, efp_listToken } from "ponder:schema";
+
+import config from "@/config";
+import type { ENSIndexerPluginHandlerArgs } from "@/lib/plugin-helpers";
+import { PluginName } from "@ensnode/ensnode-sdk";
+import { zeroAddress } from "viem";
+import {
+  decodeListStorageLocationContract,
+  isEncodedLslContract,
+  parseEncodedLsl,
+} from "../lib/lsl";
+import { parseEvmAddress } from "../lib/utils";
+
+export default function ({ pluginNamespace: ns }: ENSIndexerPluginHandlerArgs<PluginName.EFP>) {
+  ///
+  /// EFPListRegistry Handlers
+  ///
+  ponder.on(
+    ns("EFPListRegistry:Transfer"),
+    async function handleEFPListTokenTransfer({ context, event }) {
+      const { tokenId, from: fromAddress, to: toAddress } = event.args;
+
+      // The mint event represents the transfer of ownership of
+      // an EFP List token from the zeroAddress to the new owner's address.
+      if (fromAddress === zeroAddress) {
+        // Create a new EFP List Token with the owner initialized as the token recipient
+        await context.db.insert(efp_listToken).values({
+          id: tokenId,
+          owner: parseEvmAddress(toAddress),
+        });
+      }
+
+      // The burn event represents the transfer of ownership of
+      // an EFP List token from the owner's address to the zero address.
+      else if (toAddress === zeroAddress) {
+        // Delete the burnt EFP List Token
+        await context.db.delete(efp_listToken, { id: tokenId });
+      }
+
+      // If the transfer is not from the zeroAddress,
+      // and the transfer is not to the zeroAddress,
+      // this transfer represents an ownership change.
+      else {
+        // Update the owner of the the List Token that changed ownership
+        await context.db.update(efp_listToken, { id: tokenId }).set({
+          owner: parseEvmAddress(toAddress),
+        });
+      }
+    },
+  );
+
+  ponder.on(
+    ns("EFPListRegistry:UpdateListStorageLocation"),
+    async function handleEFPListStorageLocationUpdate({ context, event }) {
+      const { listStorageLocation: encodedListStorageLocation, tokenId } = event.args;
+      const listToken = await context.db.find(efp_listToken, { id: tokenId });
+
+      // invariant: List Token must exist before its List Storage Location can be updated
+      if (!listToken) {
+        throw new Error(
+          `Cannot update List Storage Location for nonexisting List Token (id: ${tokenId})`,
+        );
+      }
+
+      const encodedLsl = parseEncodedLsl(encodedListStorageLocation);
+      const lslId = encodedLsl;
+
+      // Update the List Token with the new List Storage Location
+      await context.db.update(efp_listToken, { id: tokenId }).set({
+        lslId,
+      });
+
+      // Update the List Storage Location associated with the List Token
+      // if the List Storage Location is in a recognized format
+      if (isEncodedLslContract(encodedLsl)) {
+        try {
+          const lslContract = decodeListStorageLocationContract(config.namespace, encodedLsl);
+
+          // Index the decoded List Storage Location data with a reference to the List Token
+          // created with the currently handled EVM event.
+          // Note: if the List Storage Location with the same ID already exists,
+          // no new changes will be made to the database.
+          await context.db
+            .insert(efp_listStorageLocation)
+            .values({
+              id: lslId,
+              chainId: lslContract.chainId,
+              listRecordsAddress: lslContract.listRecordsAddress,
+              slot: lslContract.slot,
+            })
+            .onConflictDoNothing();
+        } catch {
+          // The `encodedLsl` value could not be decoded.
+          // We can ignore this case, as we have already captured the `encodedLsl` value
+          // in the `efp_listToken` table as the `lslId` value.
+        }
+      }
+    },
+  );
+}

apps/ensindexer/src/plugins/efp/lib/api.ts

@@ -0,0 +1,56 @@
+/**
+ * This Hono application enables the ENSIndexer API to handle requests related to the Ethereum Follow Protocol.
+ */
+
+import { efp_listToken } from "ponder:schema";
+import { Hono } from "hono";
+import { type ReadonlyDrizzle, eq } from "ponder";
+import { type ListTokenId, parseListTokenId } from "./utils";
+
+interface HonoEFP {
+  db: ReadonlyDrizzle<Record<string, unknown>>;
+}
+
+/**
+ * Creates a Hono application with EFP routes.
+ * @returns
+ */
+export function honoEFP({ db }: HonoEFP): Hono {
+  const app = new Hono();
+
+  // Route to handle EFP-related requests
+  app.get("/list/:listTokenId", async function getListTokenById(ctx) {
+    let listTokenId: ListTokenId;
+
+    // Parse the listTokenId from the request parameter
+    try {
+      listTokenId = parseListTokenId(ctx.req.param("listTokenId"));
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      return ctx.json({ error: `Invalid list token ID. ${errorMessage}` }, 400);
+    }
+
+    // Fetch the EFP List Token from the database
+    const listTokens = await db
+      .select()
+      .from(efp_listToken)
+      .where(eq(efp_listToken.id, listTokenId));
+
+    const listToken = listTokens[0];
+
+    if (!listToken) {
+      return ctx.json({ error: `List token with ID ${listTokenId} not found.` }, 404);
+    }
+
+    // Prepare the response DTO
+    // Note: The DTO is a simplified version of the EFP List Token schema.
+    const listTokenDto = {
+      owner: listToken.owner,
+      encodedLsl: listToken.lslId,
+    };
+
+    return ctx.json(listTokenDto, 200);
+  });
+
+  return app;
+}

apps/ensindexer/src/plugins/efp/lib/chains.ts

@@ -0,0 +1,29 @@
+import type { ENSNamespaceId } from "@ensnode/datasources";
+import { base, baseSepolia, mainnet, optimism, optimismSepolia, sepolia } from "viem/chains";
+
+/**
+ * The ChainId of an EFP Deployment..
+ *
+ * EFP has an allowlisted set of supported chains. This allowlisted set is a function of the ENSNamespace.
+ * See {@link getEFPDeploymentChainIds}.
+ */
+export type EFPDeploymentChainId = number;
+
+/**
+ * Get the list of EFP Deployment Chain IDs for the ENS Namespace ID.
+ *
+ * @param ensNamespaceId - ENS Namespace ID to get the EFP Deployment Chain IDs for
+ * @returns list of EFP Deployment Chain IDs on the associated ENS Namespace
+ */
+export function getEFPDeploymentChainIds(ensNamespaceId: ENSNamespaceId): EFPDeploymentChainId[] {
+  switch (ensNamespaceId) {
+    case "mainnet":
+      return [base.id, optimism.id, mainnet.id];
+    case "sepolia":
+      return [baseSepolia.id, optimismSepolia.id, sepolia.id];
+    default:
+      throw new Error(
+        `EFP Deployment chainIds are not defined for the ${ensNamespaceId} ENS Namespace ID`,
+      );
+  }
+}