feat(ensv2): HCA-aware Event.sender + filter + docs (#2014)

Author: shrugs

.changeset/hca-aware-events.md

@@ -0,0 +1,5 @@
+---
+"ensapi": minor
+---
+
+Adds HCA-aware `Event.sender` to the Omnigraph API alongside the existing `Event.from`. For ENSv2 events that emit an explicit `sender`/`owner`/`account`/ERC1155 `operator` argument, `Event.sender` is set from that argument (the HCA Smart Account address, if used) and falls back to `tx.from` otherwise. Adds a `sender` filter to `EventsWhereInput`. `Account.events` now filters by `sender` (HCA-aware) instead of `tx.from`. Documents HCA-aware semantics on `Domain.owner`, `Registration.registrant`/`unregistrant`, and `*.PermissionsUser.user`.

apps/ensapi/src/lib/resolution/execute-operations.ts

@@ -6,6 +6,7 @@ import {
   type Hex,
   type Name,
   type RecordVersion,
+  toNormalizedAddress,
 } from "enssdk";
 import {
   ContractFunctionExecutionError,
@@ -161,6 +162,6 @@ export function interpretOperationWithRawResult(call: Operation, raw: unknown):
       return { ...call, result: size(data) === 0 ? null : { contentType, data } };
     }
     case "interfaceImplementer":
-      return { ...call, result: interpretAddress(raw as Address) };
+      return { ...call, result: interpretAddress(toNormalizedAddress(raw as string)) };
   }
 }

apps/ensapi/src/omnigraph-api/lib/find-events/find-events-resolver.ts

@@ -26,8 +26,10 @@ interface EventsWhere {
   timestamp_gte?: bigint | null;
   /** Filter to events at or before this timestamp. */
   timestamp_lte?: bigint | null;
-  /** Filter to events sent by this address. */
+  /** Filter to events whose `tx.from` matches. Not HCA-aware. */
   from?: Address | null;
+  /** Filter to events whose HCA-aware `sender` matches. */
+  sender?: Address | null;
 }
 
 /**
@@ -49,6 +51,7 @@ function eventsWhereConditions(where?: EventsWhere | null): SQL | undefined {
       ? lte(ensIndexerSchema.event.timestamp, where.timestamp_lte)
       : undefined,
     where.from ? eq(ensIndexerSchema.event.from, where.from) : undefined,
+    where.sender ? eq(ensIndexerSchema.event.sender, where.sender) : undefined,
   );
 }
 

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

@@ -99,7 +99,7 @@ describe("Account.events", () => {
     expect(events.length).toBeGreaterThan(0);
 
     for (const event of events) {
-      expect(event.from).toBe(DEVNET_DEPLOYER);
+      expect(event.sender).toBe(DEVNET_DEPLOYER);
     }
   });
 });

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

@@ -90,13 +90,14 @@ AccountRef.implement({
     // Account.events
     //////////////////
     events: t.connection({
-      description: "All Events for which this Account is the sender (i.e. `Transaction.from`).",
+      description:
+        "All Events for which this Account is the HCA-aware `sender` (i.e. `Event.sender`).",
       type: EventRef,
       args: {
         where: t.arg({ type: AccountEventsWhereInput }),
       },
       resolve: (parent, args) =>
-        resolveFindEvents({ ...args, where: { ...args.where, from: parent.id } }),
+        resolveFindEvents({ ...args, where: { ...args.where, sender: parent.id } }),
     }),
 
     ///////////////////////

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

@@ -177,7 +177,8 @@ DomainInterfaceRef.implement({
     ////////////////
     owner: t.field({
       type: AccountRef,
-      description: "The owner of this Domain.",
+      description:
+        "If this is an ENSv1Domain, this is the effective owner of the Domain. If this is an ENSv2Domain, this is the on-chain owner address (the HCA account address if used).",
       nullable: true,
       resolve: (parent) => parent.ownerId,
     }),

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

@@ -95,12 +95,23 @@ EventRef.implement({
     // Event.from
     //////////////
     from: t.field({
-      description: "Identifies the sender of the Transaction within which this Event was emitted.",
+      description:
+        "Identifies the sender of the Transaction within which this Event was emitted (`tx.from`). Never HCA-aware — always the EOA/relayer that submitted the transaction. Use `Event.sender` for the HCA-aware actor.",
       type: "Address",
       nullable: false,
       resolve: (parent) => parent.from,
     }),
 
+    ////////////////
+    // Event.sender
+    ////////////////
+    sender: t.field({
+      description: "The HCA account address if used, otherwise Transaction.from.",
+      type: "Address",
+      nullable: false,
+      resolve: (parent) => parent.sender,
+    }),
+
     ////////////
     // Event.to
     ////////////
@@ -160,7 +171,7 @@ EventRef.implement({
 
 /**
  * Shared filter for events connections. Used by Domain.events, Resolver.events, Permissions.events,
- * and Account.events (which excludes `from` since it's implied).
+ * and Account.events (which excludes `sender` since it's implied).
  */
 export const EventsWhereInput = builder.inputType("EventsWhereInput", {
   description: "Filter conditions for an events connection.",
@@ -180,16 +191,22 @@ export const EventsWhereInput = builder.inputType("EventsWhereInput", {
     }),
     from: t.field({
       type: "Address",
-      description: "Filter to events sent by this address.",
+      description:
+        "Filter to events whose `tx.from` matches. Not HCA-aware — use `sender` to filter by the HCA account address.",
+    }),
+    sender: t.field({
+      type: "Address",
+      description:
+        "Filter to events whose `sender` matches: the HCA account address if used, otherwise Transaction.from.",
     }),
   }),
 });
 
 /**
- * Like EventsWhereInput but without `from` (used where `from` is implied, e.g. Account.events).
+ * Like EventsWhereInput but without `sender` (used where `sender` is implied, e.g. Account.events).
  */
 export const AccountEventsWhereInput = builder.inputType("AccountEventsWhereInput", {
-  description: "Filter conditions for Account.events (where `from` is implied by the Account).",
+  description: "Filter conditions for Account.events (where `sender` is implied by the Account).",
   fields: (t) => ({
     selector_in: t.field({
       type: ["Hex"],
@@ -204,5 +221,10 @@ export const AccountEventsWhereInput = builder.inputType("AccountEventsWhereInpu
       type: "BigInt",
       description: "Filter to events at or before this UnixTimestamp.",
     }),
+    from: t.field({
+      type: "Address",
+      description:
+        "Filter to events whose `tx.from` matches. Not HCA-aware — the Account's HCA-aware filter is applied via `sender = Account.id`.",
+    }),
   }),
 });

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

@@ -260,7 +260,8 @@ PermissionsUserRef.implement({
     // PermissionsUser.user
     ////////////////////////
     user: t.field({
-      description: "The User for whom these Roles are granted.",
+      description:
+        "The user/grantee address this Permission is granted to (the HCA account address if used).",
       type: AccountRef,
       nullable: false,
       resolve: (parent) => parent.user,

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

@@ -140,7 +140,8 @@ RegistrationInterfaceRef.implement({
     // Registration.registrant
     ///////////////////////////
     registrant: t.field({
-      description: "The Registrant of a Registration, if exists.",
+      description:
+        "The Registrant of a Registration, if exists. For ENSv2 Registrations, the protocol-emitted registrant address (the HCA account address if used).",
       type: AccountRef,
       nullable: true,
       resolve: (parent) => parent.registrantId,
@@ -150,7 +151,8 @@ RegistrationInterfaceRef.implement({
     // Registration.unregistrant
     /////////////////////////////
     unregistrant: t.field({
-      description: "The Unregistrant of a Registration, if exists.",
+      description:
+        "The Unregistrant of a Registration, if exists. For ENSv2 Registrations, the protocol-emitted unregistrant address (the HCA account address if used).",
       type: AccountRef,
       nullable: true,
       resolve: (parent) => parent.unregistrantId,

apps/ensapi/src/omnigraph-api/schema/registry-permissions-user.ts

@@ -49,7 +49,8 @@ RegistryPermissionsUserRef.implement({
     // RegistryPermissionsUser.user
     /////////////////////////////////
     user: t.field({
-      description: "The User for whom these Roles are granted.",
+      description:
+        "The user/grantee address this Permission is granted to (the HCA account address if used).",
       type: AccountRef,
       nullable: false,
       resolve: (parent) => parent.user,