Refine docs for makeRegistrationId (#88)

Proposes refined documentation for makeRegistrationId.

apps/ensnode/src/lib/ids.ts

@@ -15,27 +15,40 @@ export const makeEventId = (blockNumber: bigint, logIndex: number, transferIndex
 /**
  * Makes a cross-registrar unique registration ID.
  *
- * A Registration record's id is historically the labelhash of the label
- * directly under the name the Registrar manages (i.e. for a registration
- * of test.eth, a Registration's id is labelhash('test')). Because the original
- * subgraph implementation didn't consider indexing any Registrars besides
- * the .eth Registrar, this leaves no room in the namespace for Registration
- * records from other Registrars (like the base.eth and linea.eth Registrars).
- * To account for this, while preserving backwards compatibility, Registration
- * records created for the .eth Registrar use labelhash as id and those created by
- * any other Registrar use node (i.e. namehash(test.base.eth) to avoid
- * collisions that would otherwise occur.
+ * The ENS Subgraph has the potential to index "selected data" for any ENS name
+ * (ex: through the Registry or the NameWrapper). However, the "selected data"
+ * indexed by the ENS Subgraph varies depending on attributes of the name. For
+ * example, the ENS Subgraph only indexes Registration records for direct
+ * subnames of ".eth". This allows the ENS Subgraph to assign distinct
+ * Registration ids using only the labelhash of the direct subname being
+ * registered. (i.e. for the registration of "test.eth", the Registration's id
+ * is `labelhash('test'))`.
+ *
+ * ENSNode (with multiple plugins activated) indexes Registration records from
+ * multiple Registrars (like the base.eth and linea.eth Registrars). Therefore,
+ * we use this function to avoid Registration id collisions that would otherwise
+ * occur. (i.e. this function provides unique registration ids for "test.eth",
+ * "test.base.eth", and "test.linea.eth", etc.
  *
  * @param registrarName the name of the registrar issuing the registration
- * @param labelHash the labelHash of the direct subname of `registrarName` that was registered
+ * @param labelHash the labelHash of the subname that was registered directly
+ *                  beneath `registrarName`
  * @param node the node of the full name that was registered
+ * @returns a unique registration id
  */
 export const makeRegistrationId = (registrarName: string, labelHash: Labelhash, node: Node) => {
   if (registrarName === "eth") {
-    // To keep subgraph compatibility, we still use labelhash for `eth` registrar name
+    // For the "v1" of ENSNode (at a minimum) we want to preserve backwards
+    // compatibility with Registration id's issued by the ENS Subgraph.
+    // In the future we'll explore more fundamental solutions to avoiding
+    // Registration id collissions. For now are consciously mixing `labelHash`
+    // and `node` (namehash) values as registration ids. Both are keccak256
+    // hashes, so we take advantage of the odds of a collision being
+    // practically zero.
     return labelHash;
+  } else {
+    // Avoid collisions between Registrations for the same direct subname from
+    // different Registrars.
+    return node;
   }
-
-  // Otherwise, we use the node to ensure registration ID uniqueness
-  return node;
 };

package.json

@@ -4,6 +4,7 @@
   "private": true,
   "packageManager": "[email protected]",
   "scripts": {
+    "lint": "biome check --write .",
     "lint:ci": "biome ci"
   },
   "devDependencies": {