feat(cross-chain-indexing): enable multiple concurrent plugins

.env.local.example

@@ -5,7 +5,8 @@ RPC_URL_1=https://ethereum-rpc.publicnode.com
 RPC_URL_8453=https://base-rpc.publicnode.com
 RPC_URL_59144=https://linea-rpc.publicnode.com
 
-# Identify which indexer plugin to activate (see `src/plugins` for available plugins)
+# Identify which indexer plugins to activate (see `src/plugins` for available plugins)
+# This is a comma separated list of one or more available plugin names.
 
 # ACTIVE_PLUGINS=eth,base.eth,linea.eth
 # ACTIVE_PLUGINS=base.eth,linea.eth
@@ -18,7 +19,7 @@ ACTIVE_PLUGINS=eth
 #
 # Keeping the database schema unique to the indexer instance is important to
 # 1) speed up indexing after a restart
-# 2) prevent data corruption
+# 2) prevent data corruption from multiple indexer app instances writing state concurrently to the same db schema
 #
 # No two indexer instances can use the same database schema at the same time.
 #

ponder.config.ts

@@ -12,8 +12,8 @@ const plugins = [baseEthPlugin, ethPlugin, lineaEthPlugin] as const;
 // of the indexing handlers
 type AllPluginsConfig = IntersectionOf<(typeof plugins)[number]["config"]>;
 
-// Activates the indexing handlers included in selected active plugins and
-// returns and intersection of their combined config.
+// Activates the indexing handlers of activated plugins and
+// returns the intersection of their combined config.
 function getActivePluginsConfig(): AllPluginsConfig {
   const activePlugins = getActivePlugins(plugins);
 
@@ -28,5 +28,5 @@ function getActivePluginsConfig(): AllPluginsConfig {
 }
 
 // The type of the default export is the intersection of all available plugin
-// configs to each plugin can be correctly typechecked
+// configs so that each plugin can be correctly typechecked
 export default getActivePluginsConfig();

src/handlers/Registry.ts

@@ -5,7 +5,7 @@ import { Block } from "ponder";
 import { type Hex, zeroAddress } from "viem";
 import { makeResolverId } from "../lib/ids";
 import { ROOT_NODE, makeSubnodeNamehash } from "../lib/subname-helpers";
-import { upsertAccount } from "../lib/upserts";
+import { ensureDomainExists, upsertAccount } from "../lib/upserts";
 
 /**
  * Initialize the ENS root node with the zeroAddress as the owner.
@@ -15,15 +15,12 @@ export async function setupRootNode({ context }: { context: Context }) {
   await upsertAccount(context, zeroAddress);
 
   // initialize the ENS root to be owned by the zeroAddress and not migrated
-  await context.db
-    .insert(schema.domain)
-    .values({
-      id: ROOT_NODE,
-      ownerId: zeroAddress,
-      createdAt: 0n,
-      isMigrated: false,
-    })
-    .onConflictDoNothing();
+  await ensureDomainExists(context, {
+    id: ROOT_NODE,
+    ownerId: zeroAddress,
+    createdAt: 0n,
+    isMigrated: false,
+  });
 }
 
 function isDomainEmpty(domain: typeof schema.domain.$inferSelect) {
@@ -104,7 +101,7 @@ export const handleNewOwner =
       await context.db.update(schema.domain, { id: domain.id }).set({ ownerId: owner, isMigrated });
     } else {
       // otherwise create the domain
-      domain = await context.db.insert(schema.domain).values({
+      domain = await ensureDomainExists(context, {
         id: subnode,
         ownerId: owner,
         parentId: node,

src/lib/plugin-helpers.ts

@@ -79,11 +79,11 @@ type PluginNamespacePath<T extends PluginNamespacePath = "/"> =
   | `/${string}`
   | `/${string}${T}`;
 
-/** @var the requested active plugin name (see `src/plugins` for available plugins) */
+/** @var comma separated list of the requested active plugin names (see `src/plugins` for available plugins) */
 export const ACTIVE_PLUGINS = process.env.ACTIVE_PLUGINS;
 
 /**
- * Returns the active plugins list based on the `ACTIVE_PLUGINS` environment variable.
+ * Returns the list of 1 or more active plugins based on the `ACTIVE_PLUGINS` environment variable.
  *
  * The `ACTIVE_PLUGINS` environment variable is a comma-separated list of plugin
  * names. The function returns the plugins that are included in the list.
@@ -92,9 +92,7 @@ export const ACTIVE_PLUGINS = process.env.ACTIVE_PLUGINS;
  * @returns the active plugins
  */
 export function getActivePlugins<T extends { ownedName: string }>(plugins: readonly T[]): T[] {
-  const pluginsToActivateByOwnedName = ACTIVE_PLUGINS
-    ? ACTIVE_PLUGINS.split(",").map((p) => p.toLowerCase())
-    : [];
+  const pluginsToActivateByOwnedName = ACTIVE_PLUGINS ? ACTIVE_PLUGINS.split(",") : [];
 
   if (!pluginsToActivateByOwnedName.length) {
     throw new Error("No active plugins found. Please set the ACTIVE_PLUGINS environment variable.");

src/lib/upserts.ts

@@ -19,3 +19,25 @@ export async function upsertRegistration(
 ) {
   return context.db.insert(schema.registration).values(values).onConflictDoUpdate(values);
 }
+
+/**
+ * Idempotent handler to ensure a domain entity for requested node exists in
+ * the database. It inserts a domain entity if it does not exist. Otherwise,
+ * just returns the existing domain entity from the db.
+ *
+ * @param context ponder context object
+ * @param values domain properties
+ * @returns domain database entity
+ */
+export async function ensureDomainExists(
+  context: Context,
+  values: typeof schema.domain.$inferInsert,
+): Promise<typeof schema.domain.$inferSelect> {
+  const domainEntity = await context.db.insert(schema.domain).values(values).onConflictDoNothing();
+
+  if (!domainEntity) {
+    throw new Error("domain expected");
+  }
+
+  return domainEntity;
+}

src/plugins/README.md

@@ -1,8 +1,8 @@
 # Indexer plugins
 
-This directory contains plugins which allow defining subname-specific processing of blockchain events.
-Only one plugin can be active at a time. Use the `ACTIVE_PLUGINS` env variable to select the active plugin, for example:
+This directory contains plugins which define subname-specific processing of blockchain events.
+One or more plugins are activated at a time. Use the `ACTIVE_PLUGINS` env variable to select the active plugins, for example:
 
 ```
-ACTIVE_PLUGINS=base.eth
+ACTIVE_PLUGINS=eth,base.eth,linea.eth
 ```

src/plugins/base.eth/handlers/Registrar.ts

@@ -4,7 +4,7 @@ import { Block } from "ponder";
 import { Hex, zeroAddress } from "viem";
 import { makeRegistrarHandlers } from "../../../handlers/Registrar";
 import { makeSubnodeNamehash, tokenIdToLabel } from "../../../lib/subname-helpers";
-import { upsertAccount } from "../../../lib/upserts";
+import { ensureDomainExists, upsertAccount } from "../../../lib/upserts";
 import { ownedName, pluginNamespace } from "../ponder.config";
 
 const {
@@ -56,35 +56,39 @@ export default function () {
     // any Registrar:NameRegistered events. in the future we will likely happily upsert domains, but
     // in order to avoid prematurely drifting from subgraph equivalancy, we upsert the domain here,
     // allowing the base indexer to progress.
-    await handleDomainNameInitialized({ context, event });
+    await ensureDomainExists(context, {
+      id: makeSubnodeNamehash(ownedSubnameNode, tokenIdToLabel(event.args.id)),
+      ownerId: event.args.owner,
+      createdAt: event.block.timestamp,
+    });
 
     // after ensuring the domain exists, continue with the standard handler
     return handleNameRegistered({ context, event });
   });
   ponder.on(pluginNamespace("BaseRegistrar:NameRenewed"), handleNameRenewed);
 
   ponder.on(pluginNamespace("BaseRegistrar:Transfer"), async ({ context, event }) => {
-    const { id, from, to } = event.args;
+    // base.eth's BaseRegistrar uses `id` instead of `tokenId`
+    const { id: tokenId, from, to } = event.args;
 
     if (event.args.from === zeroAddress) {
       // The ens-subgraph `handleNameTransferred` handler implementation
       // assumes the domain record exists. However, when an NFT token is
-      // minted, there's no domain record yet created. The very first transfer
-      // event has to initialize the domain record. This is a workaround to
-      // meet the subgraph implementation expectations.
-      await handleDomainNameInitialized({
-        context,
-        event: {
-          ...event,
-          args: { id, owner: to },
-        },
+      // minted, there's no domain entity in the database yet. The very first
+      // transfer event has to ensure the domain entity for the requested
+      // token ID has been inserted into the database. This is a workaround to
+      // meet expectations of the `handleNameTransferred` subgraph
+      // implementation.
+      await ensureDomainExists(context, {
+        id: makeSubnodeNamehash(ownedSubnameNode, tokenIdToLabel(tokenId)),
+        ownerId: to,
+        createdAt: event.block.timestamp,
       });
     }
 
-    // base.eth's BaseRegistrar uses `id` instead of `tokenId`
     await handleNameTransferred({
       context,
-      args: { from, to, tokenId: id },
+      args: { from, to, tokenId },
     });
   });
 

src/plugins/linea.eth/handlers/EthRegistrar.ts

@@ -1,9 +1,8 @@
-import { type Context, ponder } from "ponder:registry";
-import schema from "ponder:schema";
-import { type Block } from "ponder";
-import { Hex, zeroAddress } from "viem";
+import { ponder } from "ponder:registry";
+import { zeroAddress } from "viem";
 import { makeRegistrarHandlers } from "../../../handlers/Registrar";
 import { makeSubnodeNamehash, tokenIdToLabel } from "../../../lib/subname-helpers";
+import { ensureDomainExists } from "../../../lib/upserts";
 import { ownedName, pluginNamespace } from "../ponder.config";
 
 const {
@@ -15,33 +14,6 @@ const {
   ownedSubnameNode,
 } = makeRegistrarHandlers(ownedName);
 
-/**
- * Idempotent handler to insert a domain record when a new domain is
- * initialized. For example, right after an NFT token for the domain
- * is minted.
- *
- * @returns a newly created domain record
- */
-function handleDomainNameInitialized({
-  context,
-  event,
-}: {
-  context: Context;
-  event: { args: { id: bigint; owner: Hex }; block: Block };
-}) {
-  const { id, owner } = event.args;
-  const label = tokenIdToLabel(id);
-  const node = makeSubnodeNamehash(ownedSubnameNode, label);
-  return context.db
-    .insert(schema.domain)
-    .values({
-      id: node,
-      ownerId: owner,
-      createdAt: event.block.timestamp,
-    })
-    .onConflictDoNothing();
-}
-
 export default function () {
   ponder.on(pluginNamespace("BaseRegistrar:NameRegistered"), handleNameRegistered);
   ponder.on(pluginNamespace("BaseRegistrar:NameRenewed"), handleNameRenewed);
@@ -52,15 +24,15 @@ export default function () {
     if (event.args.from === zeroAddress) {
       // The ens-subgraph `handleNameTransferred` handler implementation
       // assumes the domain record exists. However, when an NFT token is
-      // minted, there's no domain record yet created. The very first transfer
-      // event has to initialize the domain record. This is a workaround to
-      // meet the subgraph implementation expectations.
-      await handleDomainNameInitialized({
-        context,
-        event: {
-          ...event,
-          args: { id: tokenId, owner: to },
-        },
+      // minted, there's no domain entity in the database yet. The very first
+      // transfer event has to ensure the domain entity for the requested
+      // token ID has been inserted into the database. This is a workaround to
+      // meet expectations of the `handleNameTransferred` subgraph
+      // implementation.
+      await ensureDomainExists(context, {
+        id: makeSubnodeNamehash(ownedSubnameNode, tokenIdToLabel(tokenId)),
+        ownerId: to,
+        createdAt: event.block.timestamp,
       });
     }