WIP refactor(ponder-sdk): define a package to consolidate Ponder-related ideas and functionality #1416

tk-o · 2025-12-19T14:11:50Z

Suggested review order: commit-by-commit.

This PR is a substantial change to ENSNode with the following updates:

@ensnode/ponder-metadata package role has been renamed to @ensnode/ponder-sdk with the goal of consolidating Ponder-related functionalities. This is a step towards achieving clean boundary between Ponder framework and the codebase of ENSNode components.

Resolves #908

…ode/ponder-sdk`.

…d in `apps/*`

…s that are currently utilised

…-sdk`

changeset-bot · 2025-12-19T14:11:54Z

🦋 Changeset detected

Latest commit: 3cc7ea4

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

This PR includes changesets to release 14 packages

Name	Type
@ensnode/ponder-sdk	Major
ensindexer	Major
ensadmin	Major
ensrainbow	Major
ensapi	Major
@ensnode/datasources	Major
@ensnode/ensrainbow-sdk	Major
@ensnode/ensnode-schema	Major
@ensnode/ensnode-react	Major
@ensnode/ponder-subgraph	Major
@ensnode/ensnode-sdk	Major
@ensnode/shared-configs	Major
@docs/ensnode	Major
@docs/ensrainbow	Major

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-12-19T14:11:55Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
admin.ensnode.io	Ready	Preview, Comment	Dec 22, 2025 7:32am
ensnode.io	Ready	Preview, Comment	Dec 22, 2025 7:32am
ensrainbow.io	Ready	Preview, Comment	Dec 22, 2025 7:32am

…ndpoints

Awaits for Ponder application to be healthy before building the Indexing Status object

lightwalker-eth

@tk-o Hey thanks for the updates here. Appreciate that this PR is still a draft. Reviewed and shared some early feedback 👍

lightwalker-eth · 2025-12-21T19:23:31Z

packages/ponder-sdk/README.md

@@ -0,0 +1,3 @@
+# Ponder SDK
+
+This package is a set of libraries enabling smooth interaction with Ponder application and data, including shared types, data processing (such as validating data and enforcing invariants), and Ponder-oriented helper functions.


Suggested change

This package is a set of libraries enabling smooth interaction with Ponder application and data, including shared types, data processing (such as validating data and enforcing invariants), and Ponder-oriented helper functions.

This package is a set of utilities for interacting with a Ponder app.

lightwalker-eth · 2025-12-21T19:25:46Z

.changeset/green-deer-tan.md

+"@ensnode/ponder-sdk": minor
+---
+
+Renames `@ensnode/ponder-metadata` package to `@ensnode/ponder-sdk`.


Do we need to make any changes to any of our devops scripts related to publishing packages to NPM or generating release notes?

Additionally, I imagine that we should include a reference to ponder-sdk in the root readme file of the monorepo the way we reference other packages there?

There's no need to change any of our devops scripts.

On the second question, yes, that's a good point 👍

lightwalker-eth · 2025-12-21T19:26:45Z

packages/ponder-sdk/src/client.ts

+  (typeof PonderHealthCheckResults)[keyof typeof PonderHealthCheckResults];
+
+export class PonderClient {
+  #healthCheckResult: PonderHealthCheckResult | undefined;


Please note feedback I shared in another open PR for how all our clients should be stateless.

lightwalker-eth · 2025-12-21T19:34:04Z

packages/ponder-sdk/src/rpc.ts

@@ -1,5 +1,5 @@
 /**
- * Ponder Metadata: RPC
+ * Ponder SDK: RPC


I don't feel good about the abstractions we're building here. It appears that we aren't building clean layers of abstractions and instead are breaking one layer into others in a way that breaks clear lines of responsibility and clean abstractions.

For example:

Why should this package know anything about ENSIndexer?

Where is the public client here coming from? I thought that we were just building a client library that wraps Ponder's APIs?

Why is there any reference to ponder:api here?

For next steps, suggest creating a diagram showing each conceptual layer involved here. How are the layers of responsibility currently defined? How do you suggest we modify the layers of responsibility through this PR?

Suggest to create these diagrams and share with me before advancing other next steps to confirm alignment. Thanks 👍

lightwalker-eth · 2025-12-21T19:35:42Z

apps/ensindexer/src/lib/indexing-status/build-index-status.ts

 ): Promise<OmnichainIndexingStatusSnapshot> {
-  let metrics: PrometheusMetrics;
-  let status: PonderStatus;
+  await waitForPonderApplicationToBecomeHealthy;


Can you please document why this action is suggested to be taken here? Why is it important? What would happen if we didn't do this here?

lightwalker-eth · 2025-12-21T20:30:52Z

packages/ponder-sdk/package.json

+  "description": "A utility library for interacting with Ponder application and data",
  "license": "MIT",
  "repository": {
    "type": "git",


We should update the directory and homepage below.

lightwalker-eth · 2025-12-21T20:31:57Z

packages/ponder-sdk/package.json

    "viem": "catalog:"
  },
  "devDependencies": {
+    "@ensnode/ensnode-sdk": "workspace:*",


Part of what's confusing me is how the ponder-sdk package would have a dependency on the ensnode-sdk package. Potentially ok with it but just struggling to get a clear mental model of the proposed strategy.

We need to take define:

types like BlockRef, ChainId, UnixTimestamp, etc.

deserialization functionality, such that deserializeBlockRef, to parse data coming from Ponder.

zod schema definitions, such that makeChainIdStringSchema to build deserialization logic for Ponder response data model.

We can either import them from @ensnode/ensnode-sdk, or re-define them locally in the @ensnode/ponder-sdk package.

The @ensnode/ponder-sdk is only integrated in the ensindexer application. For that reason, it make sense to import listed dependencies from @ensnode/ensnode-sdk. We can make the @ensnode/ensnode-sdk to be a peer dependency for @ensnode/ponder-sdk. This way we'll ensure that @ensnode/ponder-sdk package remains minimal, but it requires @ensnode/ensnode-sdk package to be provided as well at the integration point (which in our case is ensindexer application).

lightwalker-eth · 2025-12-21T20:33:09Z

packages/ponder-sdk/package.json

  },
  "dependencies": {
-    "@ensnode/ensrainbow-sdk": "workspace:*",
    "drizzle-orm": "catalog:",


Surprised to see drizzle as a dependency of the ponder-sdk package?

Great catch! This must be a legacy config, I don't think it's needed now.

lightwalker-eth · 2025-12-21T20:33:31Z

packages/ponder-sdk/package.json

-    "@ensnode/ensrainbow-sdk": "workspace:*",
    "drizzle-orm": "catalog:",
    "parse-prometheus-text-format": "^1.1.1",
    "viem": "catalog:"


Should we make viem a peer dependency too?

lightwalker-eth · 2025-12-21T20:38:22Z

packages/ponder-sdk/src/client.ts

+   *         ENSNode makes no use of that endpoint.
+   */
+  public ready(): never {
+    throw new Error("Ponder `/ready` endpoint is not supported by this client.");


I'm struggling to understand.

tk-o added 5 commits December 19, 2025 14:29

refactor(packages): rename ponder-metadata to ponder-sdk

5e336e4

docs(changeset): Renames @ensnode/ponder-metadata package to `@ensn…

7beb37e

…ode/ponder-sdk`.

refactor(ponder-sdk): review functionality and keep only the APIs use…

07583d6

…d in `apps/*`

refactor(ensindexer): review "ponder" functionality and keep only API…

5fbf1a5

…s that are currently utilised

refactor(ponder-sdk): move functionality from ensindexer to `ponder…

77d05ad

…-sdk`

tk-o added 2 commits December 19, 2025 17:47

feat(ponder-sdk): implement PonderClient for Ponder-specific HTTP e…

31a715b

…ndpoints

feat(ensindexer): intergrate PonderClient

efd1034

Awaits for Ponder application to be healthy before building the Indexing Status object

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

vercel bot deployed to Preview – ensnode.io December 19, 2025 16:49 View deployment

vercel bot deployed to Preview – admin.ensnode.io December 19, 2025 16:49 View deployment

tk-o changed the title ~~refactor(ponder-sdk): define a package to consolidate Ponder-related ideas and functionality~~ WIP refactor(ponder-sdk): define a package to consolidate Ponder-related ideas and functionality Dec 19, 2025

lightwalker-eth reviewed Dec 21, 2025

View reviewed changes

fix(ponder-sdk): optimize dependencies

3cc7ea4

vercel bot deployed to Preview – ensrainbow.io December 22, 2025 07:31 View deployment

vercel bot deployed to Preview – ensnode.io December 22, 2025 07:32 View deployment

vercel bot deployed to Preview – admin.ensnode.io December 22, 2025 07:32 View deployment

		@@ -0,0 +1,3 @@
		# Ponder SDK

		This package is a set of libraries enabling smooth interaction with Ponder application and data, including shared types, data processing (such as validating data and enforcing invariants), and Ponder-oriented helper functions.

	This package is a set of libraries enabling smooth interaction with Ponder application and data, including shared types, data processing (such as validating data and enforcing invariants), and Ponder-oriented helper functions.
	This package is a set of utilities for interacting with a Ponder app.

WIP refactor(ponder-sdk): define a package to consolidate Ponder-related ideas and functionality #1416

Are you sure you want to change the base?

WIP refactor(ponder-sdk): define a package to consolidate Ponder-related ideas and functionality #1416

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

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

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!

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!

3 participants

tk-o commented Dec 19, 2025 •

edited

Loading

changeset-bot bot commented Dec 19, 2025 •

edited

Loading

vercel bot commented Dec 19, 2025 •

edited

Loading