feat(ensindexer): introduce label healing from reverse registry

apps/ensindexer/.env.local.example

@@ -57,3 +57,12 @@ ENSRAINBOW_URL=https://api.ensrainbow.io
 # The ENSIndexer public service URL
 # It is used to generate self-referential URLs in the API responses
 ENSNODE_PUBLIC_URL=http://localhost:42069
+
+# A feature flag to enable or disable reverse address healing
+# If this is set to true, the indexer will attempt to heal reverse addresses
+# for the ENS names that are owned by the address that is being healed.
+# If this is not set, the default value is set to `DEFAULT_HEAL_REVERSE_ADDRESSES`.
+#
+# WARNING: This is a breaking change for the ENS Subgraph compatibility. To avoid
+# breaking changes, set this to `false`.
+HEAL_REVERSE_ADDRESSES=true

apps/ensindexer/src/handlers/Registrar.ts

@@ -1,22 +1,39 @@
 import { type Context } from "ponder:registry";
 import schema from "ponder:schema";
-import { isLabelIndexable, makeSubnodeNamehash } from "@ensnode/utils/subname-helpers";
+import {
+  isLabelIndexable,
+  labelByReverseAddress,
+  makeSubnodeNamehash,
+} from "@ensnode/utils/subname-helpers";
 import type { Labelhash } from "@ensnode/utils/types";
 import { type Hex, labelhash as _labelhash, namehash } from "viem";
 import { createSharedEventValues, upsertAccount, upsertRegistration } from "../lib/db-helpers";
 import { labelByHash } from "../lib/graphnode-helpers";
 import { makeRegistrationId } from "../lib/ids";
-import { EventWithArgs } from "../lib/ponder-helpers";
-import type { OwnedName } from "../lib/types";
+import { EventWithArgs, canHealReverseAddresses } from "../lib/ponder-helpers";
+import type { OwnedName, ReverseRootNode } from "../lib/types";
 
 const GRACE_PERIOD_SECONDS = 7776000n; // 90 days in seconds
 
+interface MakeRegistrarHandlersArgs {
+  ownedName: OwnedName;
+
+  /**
+   * Optional, defines the reverse registrar root node.
+   * Some plugins might not need it at the moment.
+   **/
+  reverseRootNode?: ReverseRootNode;
+}
+
 /**
  * makes a set of shared handlers for a Registrar contract that manages `ownedName`
  *
  * @param ownedName the name that the Registrar contract manages subnames of
  */
-export const makeRegistrarHandlers = (ownedName: OwnedName) => {
+export const makeRegistrarHandlers = ({
+  ownedName,
+  reverseRootNode,
+}: MakeRegistrarHandlersArgs) => {
   const ownedNameNode = namehash(ownedName);
   const sharedEventValues = createSharedEventValues(ownedName);
 
@@ -81,7 +98,18 @@ export const makeRegistrarHandlers = (ownedName: OwnedName) => {
 
       // attempt to heal the label associated with labelhash via ENSRainbow
       // https://github.com/ensdomains/ens-subgraph/blob/c68a889/src/ethRegistrar.ts#L56-L61
-      const healedLabel = await labelByHash(labelhash);
+      let healedLabel = await labelByHash(labelhash);
+
+      // if the label has not healed with ENSRainbow query
+      // and healing label from reverse addresses is enabled, give it a go
+      if (!healedLabel && canHealReverseAddresses()) {
+        healedLabel = labelByReverseAddress({
+          senderAddress: owner,
+          parentNode: node,
+          labelhash,
+          reverseRootNode,
+        });
+      }
 
       // only update the label if it is healed & indexable
       // undefined value means no change to the label

apps/ensindexer/src/handlers/Registry.ts

@@ -1,14 +1,19 @@
 import { Context } from "ponder:registry";
 import schema from "ponder:schema";
 import { encodeLabelhash } from "@ensdomains/ensjs/utils";
-import { ROOT_NODE, isLabelIndexable, makeSubnodeNamehash } from "@ensnode/utils/subname-helpers";
+import {
+  ROOT_NODE,
+  isLabelIndexable,
+  labelByReverseAddress,
+  makeSubnodeNamehash,
+} from "@ensnode/utils/subname-helpers";
 import type { Labelhash, Node } from "@ensnode/utils/types";
 import { type Hex, zeroAddress } from "viem";
 import { createSharedEventValues, upsertAccount, upsertResolver } from "../lib/db-helpers";
 import { labelByHash } from "../lib/graphnode-helpers";
 import { makeResolverId } from "../lib/ids";
-import { EventWithArgs } from "../lib/ponder-helpers";
-import { OwnedName } from "../lib/types";
+import { type EventWithArgs, canHealReverseAddresses } from "../lib/ponder-helpers";
+import type { OwnedName, ReverseRootNode } from "../lib/types";
 
 /**
  * Initializes the ENS root node with the zeroAddress as the owner.
@@ -68,12 +73,22 @@ async function recursivelyRemoveEmptyDomainFromParentSubdomainCount(context: Con
   }
 }
 
+interface MakeRegistryHandlersArgs {
+  ownedName: OwnedName;
+
+  /**
+   * Optional, defines the reverse registrar root node.
+   * Some plugins might not need it at the moment.
+   **/
+  reverseRootNode?: ReverseRootNode;
+}
+
 /**
  * makes a set of shared handlers for a Registry contract that manages `ownedName`
  *
  * @param ownedName the name that the Registry contract manages subnames of
  */
-export const makeRegistryHandlers = (ownedName: OwnedName) => {
+export const makeRegistryHandlers = ({ ownedName, reverseRootNode }: MakeRegistryHandlersArgs) => {
   const sharedEventValues = createSharedEventValues(ownedName);
 
   return {
@@ -124,7 +139,19 @@ export const makeRegistryHandlers = (ownedName: OwnedName) => {
 
           // attempt to heal the label associated with labelhash via ENSRainbow
           // https://github.com/ensdomains/ens-subgraph/blob/c68a889/src/ensRegistry.ts#L112-L116
-          const healedLabel = await labelByHash(labelhash);
+          let healedLabel = await labelByHash(labelhash);
+
+          // if the label has not healed with ENSRainbow query
+          // and healing label from reverse addresses is enabled, give it a go
+          if (!healedLabel && canHealReverseAddresses()) {
+            healedLabel = labelByReverseAddress({
+              senderAddress: event.transaction.from,
+              parentNode: node,
+              labelhash,
+              reverseRootNode,
+            });
+          }
+
           const validLabel = isLabelIndexable(healedLabel) ? healedLabel : undefined;
 
           // to construct `Domain.name` use the parent's name and the label value (encoded if not indexable)

apps/ensindexer/src/lib/plugin-helpers.ts

@@ -1,4 +1,5 @@
 import type { SubregistryContractConfig } from "@ensnode/ens-deployments";
+import type { Node } from "@ensnode/utils/types";
 import type { NetworkConfig } from "ponder";
 import { http, Chain } from "viem";
 import { END_BLOCK, START_BLOCK } from "./globals";
@@ -9,7 +10,7 @@ import {
   rpcEndpointUrl,
   rpcMaxRequestsPerSecond,
 } from "./ponder-helpers";
-import type { OwnedName, PluginName } from "./types";
+import type { OwnedName, PluginName, ReverseRootNode } from "./types";
 
 /**
  * A factory function that returns a function to create a namespaced contract
@@ -172,7 +173,12 @@ export interface PonderENSPlugin<PLUGIN_NAME extends PluginName, CONFIG> {
  */
 export type PonderENSPluginHandlerArgs<OWNED_NAME extends OwnedName> = {
   ownedName: OwnedName;
+
   namespace: ReturnType<typeof createPluginNamespace<OWNED_NAME>>;
+
+  // Optional, defines the reverse registrar root node.
+  // Some plugins might not need it at the moment.
+  reverseRootNode?: OWNED_NAME extends "eth" ? ReverseRootNode : undefined;
 };
 
 /**

apps/ensindexer/src/lib/ponder-helpers.ts

@@ -1,5 +1,5 @@
 import type { Event } from "ponder:registry";
-import DeploymentConfigs, { ENSDeploymentChain } from "@ensnode/ens-deployments";
+import DeploymentConfigs, { type ENSDeploymentChain } from "@ensnode/ens-deployments";
 import { DEFAULT_ENSRAINBOW_URL } from "@ensnode/ensrainbow-sdk";
 import { merge as tsDeepMerge } from "ts-deepmerge";
 
@@ -245,3 +245,49 @@ export const parseRequestedPluginNames = (rawValue?: string): Array<string> => {
 
   return rawValue.split(",");
 };
+
+/**
+ * Feature flag that determines whether the indexer should attempt healing
+ * reverse addresses.
+ *
+ * @returns decision whether to heal reverse addresses
+ */
+export const canHealReverseAddresses = (): boolean => {
+  const envVarName = "HEAL_REVERSE_ADDRESSES";
+  const envVarValue = process.env[envVarName];
+
+  let parsedEnvVarValue: boolean;
+
+  try {
+    parsedEnvVarValue = parseHealReverseAddresses(envVarValue);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+
+    throw new Error(`Error parsing environment variable '${envVarName}': ${errorMessage}.`);
+  }
+
+  return parsedEnvVarValue;
+};
+
+export const DEFAULT_HEAL_REVERSE_ADDRESSES = true;
+
+/**
+ * Parse input value and apply `HEAL_REVERSE_ADDRESSES_DEFAULT` value
+ * if not provided.
+ *
+ * @param rawValue value to be parsed
+ * @returns {boolean} parsed input value
+ */
+export const parseHealReverseAddresses = (rawValue?: string): boolean => {
+  if (!rawValue) {
+    return DEFAULT_HEAL_REVERSE_ADDRESSES;
+  }
+
+  const isValueValid = (v: string): boolean => v === "true" || v === "false";
+
+  if (!isValueValid(rawValue)) {
+    throw new Error(`'${rawValue}' is not a valid value. Expected 'true' or 'false'.`);
+  }
+
+  return rawValue === "true";
+};

apps/ensindexer/src/lib/types.ts

@@ -1,3 +1,5 @@
+import type { Node } from "@ensnode/utils/types";
+
 /**
  * An owned name for a plugin. Must end with `eth`.
  *
@@ -8,6 +10,14 @@
  */
 export type OwnedName = string;
 
+/**
+ * A root node for Reverse registrar. Used to distinguish between plugins that
+ * handle different reverse registrar root nodes. For example `eth` plugin will
+ * have a reverse root node of `namehash("addr.reverse")`, while other plugins
+ * might have different reverse root nodes or none at all.
+ */
+export type ReverseRootNode = Node;
+
 /**
  * In this project we use the notion of 'plugins' to describe which registries and subregistries
  * of a given ENS deployment are being indexed by ponder. In this project, a plugin's name is the

apps/ensindexer/src/plugins/base/handlers/Registrar.ts

@@ -24,7 +24,7 @@ export default function ({ ownedName, namespace }: PonderENSPluginHandlerArgs<"b
     handleNameRenewed,
     handleNameTransferred,
     ownedSubnameNode,
-  } = makeRegistrarHandlers(ownedName);
+  } = makeRegistrarHandlers({ ownedName });
 
   // support NameRegisteredWithRecord for BaseRegistrar as it used by Base's RegistrarControllers
   ponder.on(namespace("BaseRegistrar:NameRegisteredWithRecord"), async ({ context, event }) => {

apps/ensindexer/src/plugins/base/handlers/Registry.ts

@@ -8,7 +8,7 @@ export default function ({ ownedName, namespace }: PonderENSPluginHandlerArgs<"b
     handleNewResolver,
     handleNewTTL,
     handleTransfer,
-  } = makeRegistryHandlers(ownedName);
+  } = makeRegistryHandlers({ ownedName });
 
   ponder.on(namespace("Registry:setup"), setupRootNode);
   ponder.on(namespace("Registry:NewOwner"), handleNewOwner(true));

apps/ensindexer/src/plugins/eth/handlers/EthRegistrar.ts

@@ -13,14 +13,21 @@ import { PonderENSPluginHandlerArgs } from "../../../lib/plugin-helpers";
  */
 const tokenIdToLabelhash = (tokenId: bigint): Labelhash => uint256ToHex32(tokenId);
 
-export default function ({ ownedName, namespace }: PonderENSPluginHandlerArgs<"eth">) {
+export default function ({
+  ownedName,
+  namespace,
+  reverseRootNode,
+}: PonderENSPluginHandlerArgs<"eth">) {
   const {
     handleNameRegistered,
     handleNameRegisteredByController,
     handleNameRenewedByController,
     handleNameRenewed,
     handleNameTransferred,
-  } = makeRegistrarHandlers(ownedName);
+  } = makeRegistrarHandlers({
+    ownedName,
+    reverseRootNode,
+  });
 
   ponder.on(namespace("BaseRegistrar:NameRegistered"), async ({ context, event }) => {
     await handleNameRegistered({

apps/ensindexer/src/plugins/eth/handlers/Registry.ts

@@ -18,13 +18,15 @@ async function shouldIgnoreRegistryOldEvents(context: Context, node: Hex) {
   return domain?.isMigrated ?? false;
 }
 
-export default function ({ ownedName, namespace }: PonderENSPluginHandlerArgs<"eth">) {
-  const {
-    handleNewOwner, //
-    handleNewResolver,
-    handleNewTTL,
-    handleTransfer,
-  } = makeRegistryHandlers(ownedName);
+export default function ({
+  ownedName,
+  namespace,
+  reverseRootNode,
+}: PonderENSPluginHandlerArgs<"eth">) {
+  const { handleNewOwner, handleNewResolver, handleNewTTL, handleTransfer } = makeRegistryHandlers({
+    ownedName,
+    reverseRootNode,
+  });
 
   ponder.on(namespace("RegistryOld:setup"), setupRootNode);
 

apps/ensindexer/src/plugins/eth/ponder.plugin.ts

@@ -1,3 +1,4 @@
+import type { Node } from "@ensnode/utils/types";
 import { createConfig } from "ponder";
 import { DEPLOYMENT_CONFIG } from "../../lib/globals";
 import {
@@ -13,6 +14,9 @@ export const pluginName = "eth" as const;
 // the Registry/Registrar handlers in this plugin manage subdomains of '.eth'
 const ownedName = "eth" as const;
 
+// namehash('addr.reverse')
+const reverseRootNode: Node = "0x91d1777781884d03a6757a803996e38de2a42967fb37eeaca72729271025a9e2";
+
 const { chain, contracts } = DEPLOYMENT_CONFIG[pluginName];
 const namespace = createPluginNamespace(ownedName);
 
@@ -55,6 +59,7 @@ export const config = createConfig({
 export const activate = activateHandlers({
   ownedName,
   namespace,
+  reverseRootNode,
   handlers: [
     import("./handlers/Registry"),
     import("./handlers/EthRegistrar"),

apps/ensindexer/src/plugins/linea/handlers/EthRegistrar.ts

@@ -24,7 +24,7 @@ export default function ({ ownedName, namespace }: PonderENSPluginHandlerArgs<"l
     handleNameRenewed,
     handleNameTransferred,
     ownedSubnameNode,
-  } = makeRegistrarHandlers(ownedName);
+  } = makeRegistrarHandlers({ ownedName });
 
   ponder.on(namespace("BaseRegistrar:NameRegistered"), async ({ context, event }) => {
     await handleNameRegistered({

apps/ensindexer/src/plugins/linea/handlers/Registry.ts

@@ -8,7 +8,7 @@ export default function ({ ownedName, namespace }: PonderENSPluginHandlerArgs<"l
     handleNewResolver,
     handleNewTTL,
     handleTransfer,
-  } = makeRegistryHandlers(ownedName);
+  } = makeRegistryHandlers({ ownedName });
 
   ponder.on(namespace("Registry:setup"), setupRootNode);
   ponder.on(namespace("Registry:NewOwner"), handleNewOwner(true));