feat(ensindexer): introduce initial `efp` plugin demo #771

tk-o · 2025-06-04T09:32:57Z

This PR introduces an initial ENSNode plugin demo for indexing the Ethereum Follow Protocol.

Suggested review order:

packages/datasources/src/* & packages/ensnode-sdk/src/utils/types.ts
packages/ensnode-schema/src/efp.schema.ts & apps/ensindexer/src/lib/api-documentation.ts
apps/ensindexer/src/plugins/efp/efp.plugin.ts
apps/ensindexer/src/plugins/efp/lib/utils.ts
apps/ensindexer/src/plugins/efp/lib/chains.ts
apps/ensindexer/src/plugins/efp/lib/lsl.ts
apps/ensindexer/src/plugins/efp/lib/api.ts
apps/ensindexer/src/plugins/efp/handlers/EFPListRegistry.ts

Most important features:

indexing the List Registry contract, including
- Transfer event (handled event variants: mint, ownership change, burn)
- UpdateListStorageLocation event
  - when encoded LSL data can be decoded, we insert its decoded representation to efp_listStorageLocation table
  - otherwise, we store its encoded representation in efp_unrecognizedListStorageLocation table
GET /efp/list/:listTokenId route returns basic information about a requested List Token (including its encoded LSL, if available)

Most important changes:

New EFPBase datasource added to the mainnet ENS Namespace object and to the sepolia ENS Namespace object;
- covers the EFPListRegistry contract on, respectively, Base and Base Sepolia chains.
A new efp plugin created;
- uses the EFPRoot datasource only (as the EFPListRegistry contract has only been present on Base chain)
- defines a EPF plugin specific ponder schema (see packages/ensnode-schema/src/efp.schema.ts file),
- stores information about a new List being minted (checking if event.args.from is the zeroAddress),
- if possible, indexes List Storage Location data when handling the UpdateListStorageLocation event,
  - uses schema-based parsing method to ensure 100% data safety before indexing,
  - sometimes the encoded listStorageLocation value cannot be parsed successfully — in this case, we store it in its original encoded form on the relevant List Token entity
- always sets the related List Token with the current token ID for a List Storage Location entity
- GQL schema documentation was updated to cover the new schema fields
- API router allows defining custom routes under /efp path

vercel · 2025-06-04T09:33:01Z

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 24, 2025 7:22pm
ensnode.io	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 24, 2025 7:22pm
ensrainbow.io	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 24, 2025 7:22pm

changeset-bot · 2025-06-04T09:33:02Z

🦋 Changeset detected

Latest commit: a35833c

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

This PR includes changesets to release 10 packages

Name	Type
@ensnode/datasources	Minor
@ensnode/ensnode-schema	Minor
@ensnode/ensnode-sdk	Minor
ensindexer	Minor
ensadmin	Minor
ensrainbow	Minor
@ensnode/ensrainbow-sdk	Minor
@ensnode/ponder-metadata	Minor
@ensnode/ponder-subgraph	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

This is a plugin demonstrating ENSNode's capability to index the Ethereum Follow Protocol data.

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

lightwalker-eth

@tk-o Awesome to see this! Reviewed and shared a few suggestions 👍

apps/ensindexer/src/plugins/efp/handlers/EFPListRegistry.ts

apps/ensindexer/ponder.schema.ts

apps/ensindexer/src/plugins/efp/handlers/EFPListRegistry.ts

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

djstrong · 2025-06-04T16:07:33Z

BugBot run

cursor

Bug: Type Mismatch Between Functions

The getDatasources function's return type was changed from Datasource[] to Record<DatasourceName, Datasource>, but the getIndexedChainIds function still expects Datasource[] as input. This type mismatch causes a runtime error when getIndexedChainIds(getDatasources(...)) is called, as getIndexedChainIds attempts to call .map() on the object returned by getDatasources.

apps/ensindexer/src/lib/plugin-helpers.ts#L116-L143

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

Lines 116 to 143 in 57ef002

    
            */ 
        
           export function getDatasources( 
        
             config: Pick<ENSIndexerConfig, "ensDeploymentChain" | "plugins">, 
        
           ): Record<DatasourceName, Datasource> { 
        
             const requiredDatasourceNames = getRequiredDatasourceNames(config.plugins); 
        
             const ensDeployment = getENSDeployment(config.ensDeploymentChain); 
        
             const ensDeploymentDatasources = Object.entries(ensDeployment) as Array< 
        
               [DatasourceName, Datasource] 
        
             >; 
        
             const datasources = {} as Record<DatasourceName, Datasource>; 
        
             for (let [datasourceName, datasource] of ensDeploymentDatasources) { 
        
               if (requiredDatasourceNames.includes(datasourceName)) { 
        
                 datasources[datasourceName] = datasource; 
        
               } 
        
             } 
        
             return datasources; 
        
           } 
        
           /** 
        
            * Get a list of unique indexed chain IDs for selected plugin names. 
        
            */ 
        
           export function getIndexedChainIds(datasources: Datasource[]): number[] { 
        
             const indexedChainIds = datasources.map((datasource) => datasource.chain.id); 
        
             return uniq(indexedChainIds); 
        
           }

Fix in Cursor

BugBot free trial expires on June 9, 2025
You have used $0.00 of your $5.00 spend limit so far. Manage your spend limit in the Cursor dashboard.

Was this report helpful? Give feedback by reacting with 👍 or 👎

lightwalker-eth

@tk-o Hey super updates! Reviewed and shared some additional suggestions 👍

packages/ensnode-schema/src/efp.schema.ts

apps/ensindexer/src/plugins/efp/handlers/EFPListRegistry.ts

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

lightwalker-eth

@tk-o Good to see the improvements here 👍 Thanks!

Reviewed and shared feedback.

lightwalker-eth · 2025-06-23T21:40:23Z

packages/datasources/src/lib/types.ts

  Lineanames: "lineanames",
  ThreeDNSOptimism: "threedns-optimism",
  ThreeDNSBase: "threedns-base",
+  EFPRoot: "efp-root",


Suggested change

EFPRoot: "efp-root",

EFPRoot: "efproot",

Goal: enhance alignment with the ENSRoot.

Perhaps we should change the value for ENSRoot to be ens-root so we enhance alignment across all DatasourceNames entries?

@tk-o sure I'm good with that 👍

packages/ensnode-schema/src/efp.schema.ts

apps/ensindexer/src/plugins/efp/handlers/EFPListRegistry.ts

packages/ensnode-schema/src/efp.schema.ts

lightwalker-eth

@tk-o Thanks for your updates 👍 Reviewed and shared feedback.

lightwalker-eth · 2025-06-25T12:57:16Z

apps/ensindexer/src/lib/api-documentation.ts

+        "EVM chain ID of the chain where the EFP list records are stored, an `EFPDeploymentChainId` value.",
+      listRecordsAddress:
+        "Contract address on chainId where the EFP list records are stored  (always lowercase).",
+      slot: "A unique identifier within the List Storage Location, distinguishes between multiple EFP lists stored in the same `EFPListRecords` smart contract by serving as the key in mappings for list operations and metadata.",


Suggested change

slot: "A unique identifier within the List Storage Location, distinguishes between multiple EFP lists stored in the same `EFPListRecords` smart contract by serving as the key in mappings for list operations and metadata.",

slot: "A unique identifier distinguishing between multiple EFP lists stored in the same `EFPListRecords` smart contract.",

Is that fair?

lightwalker-eth · 2025-06-25T13:00:58Z

apps/ensindexer/src/lib/api-documentation.ts

+      lslId:
+        "Value of `EncodedLsl` type (optional, lowercase if present). Stores the ID of the List Storage Location. If the List Storage Location was never created or not in a recognized format, this field value will be `null`.",
    }),
    ...generateTypeDocSetWithTypeName("efp_listStorageLocation", "EFP List Storage Location", {


Suggested change

...generateTypeDocSetWithTypeName("efp_listStorageLocation", "EFP List Storage Location", {

...generateTypeDocSetWithTypeName("efp_listStorageLocation", "EFP List Storage Locations with recognized formatting", {

Is that fair?

lightwalker-eth · 2025-06-25T13:01:42Z

apps/ensindexer/src/lib/api-documentation.ts

    /**
     * The following is documentation for packages/ensnode-schema/src/efp.schema.ts
     */
    ...generateTypeDocSetWithTypeName("efp_listToken", "EFP List Token", {


Suggested change

...generateTypeDocSetWithTypeName("efp_listToken", "EFP List Token", {

...generateTypeDocSetWithTypeName("efp_listToken", "EFP List Tokens", {

lightwalker-eth · 2025-06-25T13:03:48Z

apps/ensindexer/src/lib/api-documentation.ts

     * The following is documentation for packages/ensnode-schema/src/efp.schema.ts
     */
    ...generateTypeDocSetWithTypeName("efp_listToken", "EFP List Token", {
      id: "Unique token ID for an EFP List Token",


Suggested change

id: "Unique token ID for an EFP List Token",

id: "Unique token ID for the ERC-721A NFT representing the EFP List Token",

lightwalker-eth · 2025-06-25T13:06:23Z

apps/ensindexer/src/lib/api-documentation.ts

-      slot: "The 32-byte value that specifies the storage slot of the EFP list records within the listRecordsAddress contract. This disambiguates multiple lists stored within the same contract and de-couples it from the EFP List NFT token id which is stored on the EFP deployment root chain and inaccessible on other chains.",
-      listTokenId: "Unique identifier for this EFP list token",
-      listToken: "A reference to the related ListToken entity",
+      id: "ListStorageLocation ID, an `EncodedLsl` value (always lowercase).",


Suggested change

id: "ListStorageLocation ID, an `EncodedLsl` value (always lowercase).",

recognizedLsl: "ListStorageLocation with a recognized valid `EncodedLsl` value (always lowercase).",

What do you think?

I find it nice to avoid introducing additional terminology for "lsl id". Instead, in my current understanding, we have lsl, and a subset of lsl we index will be "recognized". All lsl we index will be found in the efp_listToken table, while only the recognized ones will be found in the efp_listStorageLocation table.

lightwalker-eth · 2025-06-25T14:23:53Z

apps/ensindexer/src/plugins/efp/lib/api.ts

@@ -0,0 +1,56 @@
+/**
+ * This Hono application enables the ENSIndexer API to handle requests related to the Ethereum Follow Protocol.


Suggested change

* This Hono application enables the ENSIndexer API to handle requests related to the Ethereum Follow Protocol.

* This Hono application demonstrates a draft proof-of-concept for how custom API handlers can be defined to operate on indexed Ethereum Follow Protocol data.

lightwalker-eth · 2025-06-25T14:25:24Z

apps/ensindexer/src/plugins/efp/lib/api.ts

+import { type ListTokenId, parseListTokenId } from "./utils";
+
+interface HonoEFP {
+  db: ReadonlyDrizzle<Record<string, unknown>>;


I'm not so familiar with Drizzle. Are we supposed to pass in the overall schema we define in another file here to help give Drizzle full type system knowledge?

Appreciate your advice.

lightwalker-eth · 2025-06-25T14:29:11Z

apps/ensindexer/src/api/index.ts

Suggested change

// Use Hono EFP application for handling EFP-related requests

// Activate the draft proof-of-concept Hono app for handling EFP-related API requests

lightwalker-eth · 2025-06-25T14:36:06Z

apps/ensindexer/src/plugins/efp/handlers/EFPListRegistry.ts

+              listRecordsAddress: lslContract.listRecordsAddress,
+              slot: lslContract.slot,
+            })
+            .onConflictDoNothing();


Please see my other comments about suggested data model changes.

I think we want to remove this onConflictDoNothing and change this from an insert operation to an upsert operation.

lightwalker-eth · 2025-06-25T14:37:13Z

apps/ensindexer/src/plugins/efp/handlers/EFPListRegistry.ts

+            })
+            .onConflictDoNothing();
+        } catch {
+          // The `encodedLsl` value could not be decoded.


Please see my other comments about suggested data model changes.

Based on those suggestions, I believe here we want to perform a delete operation in the efp_listStorageLocation table to handle the case that the previous LSL for the List Token was recognized but the new value isn't.

vercel bot deployed to Preview – admin.ensnode.io June 4, 2025 09:33 View deployment

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

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

feat(ensindexer): introduce the efp plugin

5cb40d1

This is a plugin demonstrating ENSNode's capability to index the Ethereum Follow Protocol data.

tk-o force-pushed the feat/efp-plugin branch from b14e445 to 5cb40d1 Compare June 4, 2025 09:44

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

vercel bot deployed to Preview – admin.ensnode.io June 4, 2025 09:46 View deployment

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

tk-o commented Jun 4, 2025

View reviewed changes

apps/ensindexer/src/lib/plugin-helpers.ts Outdated Show resolved Hide resolved

docs(ensindexer): efp plugin schema docs update

114021e

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

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

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

lightwalker-eth reviewed Jun 4, 2025

View reviewed changes

tk-o added 2 commits June 4, 2025 15:57

docs(ensindexer): align code docs (comments) across all plugins

797e7de

refactor(ensindexer): move efp schema into ensnode-schema package

4dc678c

vercel bot deployed to Preview – admin.ensnode.io June 4, 2025 14:09 View deployment

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

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

feat(ensindexer): extends the efp schema and document it well

57ef002

tk-o force-pushed the feat/efp-plugin branch from a3aa20b to 57ef002 Compare June 4, 2025 14:18

vercel bot deployed to Preview – ensnode.io June 4, 2025 14:24 View deployment

vercel bot deployed to Preview – admin.ensnode.io June 4, 2025 14:25 View deployment

vercel bot deployed to Preview – ensrainbow.io June 4, 2025 14:25 View deployment

cursor bot reviewed Jun 4, 2025

View reviewed changes

lightwalker-eth reviewed Jun 4, 2025

View reviewed changes

lightwalker-eth changed the title ~~feat(ensindexer): introduce the efp plugin~~ feat(ensindexer): introduce initial efp plugin demo Jun 4, 2025

vercel bot deployed to Preview – admin.ensnode.io June 23, 2025 17:34 View deployment

vercel bot deployed to Preview – ensnode.io June 23, 2025 17:35 View deployment

lightwalker-eth requested changes Jun 23, 2025

View reviewed changes

tk-o mentioned this pull request Jun 24, 2025

refactor(datasources): define ENSNamespaceId enum #804

Merged

tk-o added 2 commits June 24, 2025 13:37

Merge remote-tracking branch 'origin/main' into feat/efp-plugin

42e18e0

Merge remote-tracking branch 'origin/main' into feat/efp-plugin

d57197f

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

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

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

apply pr feedback

fd4bfc2

vercel bot deployed to Preview – ensnode.io June 24, 2025 18:18 View deployment

vercel bot deployed to Preview – ensrainbow.io June 24, 2025 18:18 View deployment

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

tk-o added 2 commits June 24, 2025 21:08

feat(ensindexer): setup EFP API routes

03d55bc

Merge remote-tracking branch 'origin/main' into feat/efp-plugin

0040037

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

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

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

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

tk-o force-pushed the feat/efp-plugin branch from db47124 to 9be4a9b Compare June 24, 2025 19:16

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

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

update types

a35833c

tk-o force-pushed the feat/efp-plugin branch from 9be4a9b to a35833c Compare June 24, 2025 19:19

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

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

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

lightwalker-eth requested changes Jun 25, 2025

View reviewed changes

lightwalker-eth mentioned this pull request Jul 3, 2025

Seaport Sales Plugin #832

Closed

lightwalker-eth mentioned this pull request Aug 6, 2025

832-seaport-sales-plugin #872

Closed

	*/
	export function getDatasources(
	config: Pick<ENSIndexerConfig, "ensDeploymentChain" \| "plugins">,
	): Record<DatasourceName, Datasource> {
	const requiredDatasourceNames = getRequiredDatasourceNames(config.plugins);
	const ensDeployment = getENSDeployment(config.ensDeploymentChain);
	const ensDeploymentDatasources = Object.entries(ensDeployment) as Array<
	[DatasourceName, Datasource]
	>;
	const datasources = {} as Record<DatasourceName, Datasource>;

	for (let [datasourceName, datasource] of ensDeploymentDatasources) {
	if (requiredDatasourceNames.includes(datasourceName)) {
	datasources[datasourceName] = datasource;
	}
	}

	return datasources;
	}

	/**
	* Get a list of unique indexed chain IDs for selected plugin names.
	*/
	export function getIndexedChainIds(datasources: Datasource[]): number[] {
	const indexedChainIds = datasources.map((datasource) => datasource.chain.id);

	return uniq(indexedChainIds);
	}

	slot: "A unique identifier within the List Storage Location, distinguishes between multiple EFP lists stored in the same `EFPListRecords` smart contract by serving as the key in mappings for list operations and metadata.",
	slot: "A unique identifier distinguishing between multiple EFP lists stored in the same `EFPListRecords` smart contract.",

	...generateTypeDocSetWithTypeName("efp_listStorageLocation", "EFP List Storage Location", {
	...generateTypeDocSetWithTypeName("efp_listStorageLocation", "EFP List Storage Locations with recognized formatting", {

	id: "Unique token ID for an EFP List Token",
	id: "Unique token ID for the ERC-721A NFT representing the EFP List Token",

	id: "ListStorageLocation ID, an `EncodedLsl` value (always lowercase).",
	recognizedLsl: "ListStorageLocation with a recognized valid `EncodedLsl` value (always lowercase).",

		@@ -0,0 +1,56 @@
		/**
		* This Hono application enables the ENSIndexer API to handle requests related to the Ethereum Follow Protocol.

	* This Hono application enables the ENSIndexer API to handle requests related to the Ethereum Follow Protocol.
	* This Hono application demonstrates a draft proof-of-concept for how custom API handlers can be defined to operate on indexed Ethereum Follow Protocol data.

	// Use Hono EFP application for handling EFP-related requests
	// Activate the draft proof-of-concept Hono app for handling EFP-related API requests

feat(ensindexer): introduce initial efp plugin demo #771

Are you sure you want to change the base?

feat(ensindexer): introduce initial efp plugin demo #771

Uh oh!

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

lightwalker-eth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

djstrong commented Jun 4, 2025

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Bug: Type Mismatch Between Functions

Uh oh!

lightwalker-eth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

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!

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!

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

feat(ensindexer): introduce initial `efp` plugin demo #771

feat(ensindexer): introduce initial `efp` plugin demo #771

tk-o commented Jun 4, 2025 •

edited

Loading

vercel bot commented Jun 4, 2025 •

edited

Loading

changeset-bot bot commented Jun 4, 2025 •

edited

Loading