refactor(ensindexer): create a unified way to define a plugin #775

tk-o · 2025-06-08T10:25:07Z

This PR addresses a challenge of defining ENSIndexer plugins with proper type inference.

Related issue:

Review the language we use when referring to various configs #769

Review suggestions:

turn Diff view: Hide whitespace option on

Review order:

apps/ensindexer/src/lib/plugin-helpers.ts
- contains the most important set of changes
apps/ensindexer/src/lib/ponder-helpers.ts
- hosts two functions moved from the plugin-helpers.ts file
apps/ensindexer/src/plugins/index.ts
- new datasource-related helpers
apps/ensindexer/src/plugins/event-handlers.ts
- new way of declaring ENSIndexer event handlers per plugin
apps/ensindexer/src/plugins/basenames/plugin.ts & apps/ensindexer/src/plugins/basenames/event-handlers.ts
apps/ensindexer/src/plugins/lineanames/plugin.ts & apps/ensindexer/src/plugins/lineanames/event-handlers.ts
apps/ensindexer/src/plugins/subgraph/plugin.ts & apps/ensindexer/src/plugins/subgraph/event-handlers.ts
apps/ensindexer/src/plugins/threedns/plugin.ts & apps/ensindexer/src/plugins/threedns/event-handlers.ts
apps/ensindexer/ponder.config.ts
- uses new API for attaching event handlers for active plugins
apps/ensindexer/test/*
docs/*

Key changes:

decouple plugin handlers from plugin config file
- now, all indexing handlers for a plugin must be exported from its own file
  - let's take the basenames plugin as an example: its handlers file must be present at apps/ensindexer/src/plugins/basenames/event-handlers.ts
  - the handlers file must export a function that will later be called from ponder.config.ts for each active plugin
- activating indexing handlers for a plugin can be done with a new helper function called attachPluginEventHandlers
introduce buildPlugin function with automated type inference
- now, every plugin file returns a results of buildPlugin function
- ponder.config.ts file can access Ponder config object for each active plugin by calling its createPonderConfig method

…om function call params

Decouple handlers from plugins. At least for the eager type inference part.

This way, we decouple the plugin handlers definition from the plugin config definition. It allows breaking circular type inference.

changeset-bot · 2025-06-08T10:25:11Z

🦋 Changeset detected

Latest commit: a1ce74d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
ensindexer	Minor
ensadmin	Minor
ensrainbow	Minor
@ensnode/datasources	Minor
@ensnode/ensrainbow-sdk	Minor
@ensnode/ponder-metadata	Minor
@ensnode/ensnode-schema	Minor
@ensnode/ponder-subgraph	Minor
@ensnode/ensnode-sdk	Minor
@ensnode/shared-configs	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-06-08T10:25:12Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
admin.ensnode.io	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 30, 2025 0:11am
ensnode.io	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 30, 2025 0:11am
ensrainbow.io	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 30, 2025 0:11am

apps/ensindexer/src/plugins/index.ts

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

apps/ensindexer/test/plugin-helpers.test.ts

apps/ensindexer/test/ponder-helpers.test.ts

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

… plugin

…ildPlugin` function.

lightwalker-eth

@tk-o Thanks for the updates. I've shared many suggestions for improvement. I'm open to following up on these suggestions in other future PRs. Please make a special effort to ensure none of the suggestions shared are forgotten and all ultimately receive a response.

You're welcome to merge this PR when ready. Please decide for yourself if Matt or I should review this PR once more. Either option is ok from my perspective.

lightwalker-eth · 2025-06-29T10:01:26Z

apps/ensindexer/src/plugins/threedns/event-handlers.ts

+/**
+ * Attach plugin's event handlers for indexing.
+ *
+ * Note: this function is called when the plugin is active.


Please clarify the language here. It's not sufficiently clear or precise. There's too many ways to interpret this.

As I understand, this is what you're trying to say:

Suggested change

* Note: this function is called when the plugin is active.

* Note: this function is called if and only if the plugin is being activated.

Is that right? Or are you trying to say something else?

apps/ensindexer/src/plugins/shared/Resolver.ts

apps/ensindexer/src/plugins/basenames/plugin.ts

apps/ensindexer/src/plugins/index.ts

lightwalker-eth · 2025-06-29T20:59:50Z

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

-      ...((chainId === 31337 || chainId === 1337) && { disableCache: true }),
-    } satisfies NetworkConfig,
-  };
+  createPonderConfig(


Currently we're mixing together our plugin definitions with a lot of Ponder-specific details. It seems there should be a more simple design?

Why couldn't we completely remove explicit reference to Ponder things when we define a plugin, and instead define our own types for our plugins?

For example, imagine we completely separated the following into distinct layers:

Defining an ENSIndexer plugin (using our own types).

Taking an ENSIndexer plugin definition and converting it into a PonderConfig.

In layer (1) listed above, we might:
A. Completely remove the createPonderConfig function.
B. Add a function for getIndexedContracts that returns only the contracts value that is currently returned by createPonderConfig.
C. Add a function for getEventHandlers that returns the record type for mapping between (namespaced) contract names and event handler callback functions. Importantly: this wouldn't ever include an import or call to ponder. Please see my other more detailed feedback about this idea in another comment.

In layer (2) listed above, we might:
A. Take all the values returned by getIndexedContracts for all active plugins and..:
i. Identify the chains being requested for indexing, and then getting the rpcConfigs from the ENSIndexerConfig as needed to build the networks object needed by Ponder.
ii. Build the contracts object needed by Ponder.

Only layer (2) would then need all these complex looking type definitions that Ponder needs, right?

We could refer to Layer (1) as our "Plugin" layer and Layer (2) as our "PonderConfig" layer.

In other words, Layer (1) doesn't need to know about PonderConfigs, because Layer (2) takes the full responsibility for translating from our "Plugins" into the "PonderConfig" that we ultimately pass to Ponder.

lightwalker-eth · 2025-06-29T21:10:15Z

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

+ *
+ * @returns network configuration based on the contract
+ */
+export function networkConfigForContract<CONTRACT_CONFIG extends ContractConfig>(


Why do we need to use a type template here for CONTRACT_CONFIG? Seems we should be fine to remove the use of type templates here?

lightwalker-eth · 2025-06-29T21:11:05Z

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

+ * Builds a ponder#NetworksConfig for a single, specific chain.
+ *
+ * @param {number} chainId
+ * @param rpcConfigs a dictionary of RPC configurations, grouped by chainId


Suggested change

* @param rpcConfigs a dictionary of RPC configurations, grouped by chainId

* @param rpcConfigs a dictionary of RPC configurations, keyed by chainId

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

apps/ensindexer/src/lib/lib-json-metadata.ts

lightwalker-eth

Sharing a few additional ideas for future follow up on enhancements to our plugin system.

lightwalker-eth · 2025-06-30T14:38:08Z

apps/ensindexer/src/plugins/event-handlers.ts

-import { attachLineanamesPluginEventHandlers } from "@/plugins/lineanames/event-handlers";
-import { attachSubgraphPluginEventHandlers } from "@/plugins/subgraph/event-handlers";
-import { attachThreeDNSPluginEventHandlers } from "@/plugins/threedns/event-handlers";
+// Shared Resolver Handlers


There's a future opportunity for us to strengthen the documentation for specifically what it means for handlers to be "shared". Ideally we could also connect this idea to why some handlers are are associated with namespaced contracts and others aren't.

lightwalker-eth · 2025-06-30T14:40:43Z

apps/ensindexer/src/plugins/event-handlers.ts

+import { attachSharedResolverHandlers } from "@/plugins/shared/Resolver";
+
+// Subgraph Handlers
+import { attachSubgraphNameWrapperEventHandlers } from "./subgraph/handlers/NameWrapper";


It seems attractive to separate the following ideas:

The definition of a mapping from an event name with a (namespaced) contract to an event handler function (just a named import for each event handler, not the implementation of those event handlers). This should never make any reference to ponder.on or import ponder.

The registration of the relationship defined in point (1) above with ponder using ponder.on. This imports ponder and calls ponder.on.

The implementation of the event handlers defined in point (1) above. These don't import ponder.

i'm not sure an additional level of abstraction between plugins and ponder would help but we can explore what that would look like. also it's the usage of ponder.on that gives us the inferred types, so another level of abstraction will give us additional type wrangling to do that seems less productive

lightwalker-eth · 2025-06-30T14:42:33Z

apps/ensindexer/src/plugins/event-handlers.ts

+ * handlers. ponder.config.ts will call {@link attachPluginEventHandlers} to conditionally
+ * register a specific plugin's handlers with Ponder.
+ *
+ * NOTE: defined separate from plugin.ts to avoid possible circular dependencies


It would be nice if we could be more specific about exactly what is creating the circular dependencies. As I understand these are caused by our calls to ponder.on. Please see my other comment on this file suggesting to split related logic into 3 distinct layers.

lightwalker-eth · 2025-06-30T14:45:06Z

apps/ensindexer/src/plugins/event-handlers.ts

+    attachSubgraphRegistrarEventHandlers,
+    attachSubgraphRegistryEventHandlers,
+
+    // NOTE: shared Resolver handlers


This is an additional comment on the desire to strengthen our docs and language related to the use of the word "shared" here.

Is it correct to assume that ideas here include how the "shared Resolver handlers" are fundamentally a per-chain concept rather than a per-registry / subregistry concept?

It would be great to better document these ideas.

let's avoid documenting it in every possible location, perhaps we can write some page in the docs and just link to it at these callsites?

lightwalker-eth · 2025-06-30T14:49:19Z

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

+  );

-  ponder.on(ns("BaseRegistrar:Transfer"), async ({ context, event }) => {
+  ponder.on(namespaceContract(pluginName, "BaseRegistrar:Transfer"), async ({ context, event }) => {


Hmm. it seems we're not actually namespacing contracts here. As I understand, we should rename namespaceContract to namespaceEvent. Is that fair?

One idea is to refine our strategy here so that we don't pass in event names such as "BaseRegistrar:Transfer" but instead separate params for "BaseRegistrar" (the contract name), and "Transfer" as the event name, and then pluginName as a 3rd param for the contract namespace.

Then this could be called namespaceEvent. Or perhaps better: make the contract namespace param optional and rename namespaceContract to something like buildEventName or something.

Advice appreciated.

let's keep namespace to imply namespacing behavior, very important here

namespaceEvent or namespaceEventName seems fine

tk-o added 4 commits June 7, 2025 15:42

refactor(ensindexer): make plugin-helpers.ts to read config values fr…

63e586a

…om function call params

refactor(ensindexer): make all plugins with definePlugin helper

9111c79

fix: break circular type inference

672c323

Decouple handlers from plugins. At least for the eager type inference part.

refactor: include activatePluginHandlers helper

aa4b8b0

This way, we decouple the plugin handlers definition from the plugin config definition. It allows breaking circular type inference.

docs: update code comments

5dcac43

vercel bot deployed to Preview – admin.ensnode.io June 8, 2025 10:50 View deployment

vercel bot deployed to Preview – ensrainbow.io June 8, 2025 10:50 View deployment

vercel bot deployed to Preview – ensnode.io June 8, 2025 10:51 View deployment

docs: update code comments

2d4f74a

vercel bot deployed to Preview – ensnode.io June 8, 2025 11:01 View deployment

vercel bot deployed to Preview – ensrainbow.io June 8, 2025 11:02 View deployment

vercel bot deployed to Preview – admin.ensnode.io June 8, 2025 11:03 View deployment

refactor: use plugin helpers for config validation

e3833a1

vercel bot deployed to Preview – admin.ensnode.io June 8, 2025 11:30 View deployment

vercel bot deployed to Preview – ensnode.io June 8, 2025 11:31 View deployment

vercel bot deployed to Preview – ensrainbow.io June 8, 2025 11:32 View deployment

docs: update code comments

437409f

vercel bot deployed to Preview – ensrainbow.io June 8, 2025 12:33 View deployment

tk-o commented Jun 8, 2025

View reviewed changes

vercel bot deployed to Preview – ensnode.io June 8, 2025 12:34 View deployment

vercel bot deployed to Preview – admin.ensnode.io June 8, 2025 12:35 View deployment

docs: update code comments

07cce67

vercel bot deployed to Preview – ensrainbow.io June 9, 2025 07:26 View deployment

vercel bot deployed to Preview – admin.ensnode.io June 9, 2025 07:27 View deployment

vercel bot deployed to Preview – ensnode.io June 9, 2025 07:28 View deployment

refactor(ensindexer): use plugin.ts and hanlders.ts files in each…

73f95d0

… plugin

vercel bot deployed to Preview – admin.ensnode.io June 9, 2025 19:08 View deployment

vercel bot deployed to Preview – ensrainbow.io June 9, 2025 19:09 View deployment

vercel bot deployed to Preview – ensnode.io June 27, 2025 19:36 View deployment

docs(changeset): Apply a unified way of building plugins with the `bu…

0706377

…ildPlugin` function.

vercel bot deployed to Preview – ensrainbow.io June 28, 2025 05:29 View deployment

vercel bot deployed to Preview – ensnode.io June 28, 2025 05:29 View deployment

vercel bot deployed to Preview – admin.ensnode.io June 28, 2025 05:30 View deployment

lightwalker-eth approved these changes Jun 29, 2025

View reviewed changes

shrugs added 10 commits June 30, 2025 11:48

checkpoint: pr updates

e7584a2

rename json metadata and refactor slightly

bd162d4

fix: migrate to namespaceContract

38b0b32

contractNamespace test

20fc4f7

refactor networksForChain and config var name

f765997

fix: shared resolver comments

6f0d571

fix: refactor networkConfigForContract arg order

9d6e0e2

fix: update merge ponder config comment

00546f0

fix: refactor event-handlers registration to be simpler

24a3884

fix: update comments about threedns

1dc11d1

vercel bot deployed to Preview – ensnode.io June 30, 2025 12:01 View deployment

vercel bot deployed to Preview – ensrainbow.io June 30, 2025 12:02 View deployment

fix: revert namespaceContract reserve character check

32b7dea

vercel bot deployed to Preview – ensrainbow.io June 30, 2025 12:03 View deployment

vercel bot deployed to Preview – admin.ensnode.io June 30, 2025 12:04 View deployment

vercel bot deployed to Preview – ensnode.io June 30, 2025 12:05 View deployment

more docs for networksConfigForChain

a1ce74d

vercel bot deployed to Preview – ensnode.io June 30, 2025 12:09 View deployment

vercel bot deployed to Preview – ensrainbow.io June 30, 2025 12:10 View deployment

vercel bot deployed to Preview – admin.ensnode.io June 30, 2025 12:11 View deployment

tk-o merged commit f4d6a6e into main Jun 30, 2025
7 checks passed

tk-o deleted the feat/ensindexer-define-plugin branch June 30, 2025 12:28

github-actions bot mentioned this pull request Jun 25, 2025

Release New Version #797

Merged

lightwalker-eth reviewed Jun 30, 2025

View reviewed changes

	* Note: this function is called when the plugin is active.
	* Note: this function is called if and only if the plugin is being activated.

	* @param rpcConfigs a dictionary of RPC configurations, grouped by chainId
	* @param rpcConfigs a dictionary of RPC configurations, keyed by chainId

refactor(ensindexer): create a unified way to define a plugin #775

refactor(ensindexer): create a unified way to define a plugin #775

Uh oh!

Conversation

tk-o commented Jun 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Jun 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jun 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lightwalker-eth left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lightwalker-eth left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tk-o commented Jun 8, 2025 •

edited

Loading

changeset-bot bot commented Jun 8, 2025 •

edited

Loading

vercel bot commented Jun 8, 2025 •

edited

Loading