feat(ensanalytics): referrer details endpoint #1318

Goader · 2025-11-26T18:14:23Z

closes: #1262

This PR introduces a new referrer detail endpoint API that allows querying individual referrer information, whether they are ranked on the leaderboard or not.

Changes:

@namehash/ens-referrals package:

Added getReferrerDetail() function to retrieve detail for a specific referrer address
Added ReferrerDetail discriminated union type (ReferrerDetailRanked | ReferrerDetailUnranked)
Added UnrankedReferrerMetrics interface for referrers not on the leaderboard (rank: null, isQualified: false)
Added buildUnrankedReferrerMetrics() helper to create zero-score referrer records
Added validateUnrankedReferrerMetrics() validation function
Renamed pagination types from "Pagination" to "Page" for consistency (ReferrerLeaderboardPaginationParams → ReferrerLeaderboardPageParams)

@ensnode/ensnode-sdk package:

Added getReferrerDetail() method to ENSNodeClient class
Added ReferrerDetailRequest and ReferrerDetailResponse types
Added ReferrerDetailResponseCodes enum (Ok, Error)
Added Zod schemas for validation (makeReferrerDetailResponseSchema, makeReferrerDetailRankedSchema, makeReferrerDetailUnrankedSchema)
Added serialization/deserialization functions (serializeReferrerDetailResponse, deserializeReferrerDetailResponse)
Updated pagination type names to match referrals package changes

ensapi package:

Added new endpoint: GET /ensanalytics/referrers/:referrer
Returns ranked referrer metrics if the referrer exists on the leaderboard
Returns unranked referrer metrics (zero-score) if the referrer is not on the leaderboard
Includes aggregated metrics and accurateAsOf timestamp in both cases
Proper error handling with 503 status when leaderboard data is unavailable

changeset-bot · 2025-11-26T18:14:27Z

🦋 Changeset detected

Latest commit: 3a3fc72

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

This PR includes changesets to release 15 packages

Name	Type
@namehash/ens-referrals	Minor
@ensnode/ensnode-sdk	Minor
ensapi	Minor
ensadmin	Minor
ensindexer	Minor
ensrainbow	Minor
@ensnode/ensnode-react	Minor
@ensnode/ensrainbow-sdk	Minor
@ensnode/datasources	Minor
@ensnode/ponder-metadata	Minor
@ensnode/ensnode-schema	Minor
@ensnode/ponder-subgraph	Minor
@ensnode/shared-configs	Minor
@docs/ensnode	Minor
@docs/ensrainbow	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-11-26T18:14:28Z

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

Project	Deployment	Preview	Comments	Updated (UTC)
admin.ensnode.io	Ready	Preview	Comment	Dec 7, 2025 3:12pm
ensnode.io	Ready	Preview	Comment	Dec 7, 2025 3:12pm
ensrainbow.io	Ready	Preview	Comment	Dec 7, 2025 3:12pm

…not qualified

Goader · 2025-12-03T17:06:39Z

apps/ensapi/src/lib/ensanalytics/referrer-leaderboard/mocks.ts

  referrers: new Map([
    [
-      "0x538e35b2888ed5b[c58cf2825d76cf6265aa4e31e",
+      "0x538e35b2888ed5bc58cf2825d76cf6265aa4e31e",


probably a bug from earlier

lightwalker-eth

@Goader Hey overall looking really good. Shared a few suggestions 👍

lightwalker-eth · 2025-12-03T22:19:53Z

packages/ens-referrals/src/referrer-metrics.ts

+ * Extends {@link AwardedReferrerMetrics} but with rank set to null to represent
+ * a referrer who is not on the leaderboard (has zero referrals).
+ */
+export interface UnrankedReferrerMetrics


Nicely done 👍

lightwalker-eth · 2025-12-03T22:20:15Z

packages/ens-referrals/src/referrer-metrics.ts

+  rank: null;
+
+  /**
+   * Always false for unranked referrers since they don't qualify for awards.


Suggested change

* Always false for unranked referrers since they don't qualify for awards.

* Always false for unranked referrers.

lightwalker-eth · 2025-12-03T22:20:49Z

packages/ens-referrals/src/referrer-metrics.ts

+export interface UnrankedReferrerMetrics
+  extends Omit<AwardedReferrerMetrics, "rank" | "isQualified"> {
+  /**
+   * The referrer's rank on the leaderboard is null because they are not on the leaderboard.


Suggested change

* The referrer's rank on the leaderboard is null because they are not on the leaderboard.

* The referrer is not on the leaderboard and therefore has no rank.

lightwalker-eth · 2025-12-03T22:21:27Z

packages/ens-referrals/src/referrer-metrics.ts

+
+/**
+ * Extends {@link AwardedReferrerMetrics} but with rank set to null to represent
+ * a referrer who is not on the leaderboard (has zero referrals).


Suggested change

* a referrer who is not on the leaderboard (has zero referrals).

* a referrer who is not on the leaderboard (has zero referrals within the rules associated with the leaderboard).

lightwalker-eth · 2025-12-03T22:24:29Z

packages/ens-referrals/src/referrer-detail.ts

+ *
+ * @see {@link AwardedReferrerMetrics}
+ */
+export interface ReferrerDetailData {


Suggested change

export interface ReferrerDetailData {

export interface ReferrerDetailRanked {

packages/ens-referrals/src/referrer-metrics.ts

lightwalker-eth · 2025-12-03T22:40:51Z

apps/ensapi/src/handlers/ensanalytics-api.ts

+
+    // If referrer not found, create an unranked zero-score referrer record
+    // with rank: null and isQualified: false
+    const unrankedReferrerMetrics = buildUnrankedReferrerMetrics(referrer);


I'm thinking perhaps this idea should move directly into the leaderboard. Ex: you ask the leaderboard to get the details of referrer X and the leaderboard then internally gives you back a ranked or unranked referrer as appropriate.

lightwalker-eth · 2025-12-03T22:43:09Z

apps/ensapi/src/handlers/ensanalytics-api.ts

+});
+
+// Get referrer detail for a specific address
+app.get("/referrer/:referrer", validate("param", referrerAddressSchema), async (c) => {


Suggested change

app.get("/referrer/:referrer", validate("param", referrerAddressSchema), async (c) => {

app.get("/referrers/:referrer", validate("param", referrerAddressSchema), async (c) => {

Goal: Align with the existing API endpoint. One is for paginating through all referrers, then if you add this extra detail in the path it ideally should give the details of one specific referrer.

lightwalker-eth · 2025-12-03T22:43:41Z

apps/ensapi/src/handlers/ensanalytics-api.ts

+      } satisfies ReferrerDetailResponse),
+    );
+  } catch (error) {
+    logger.error({ error }, "Error in /ensanalytics/referrer/:referrer endpoint");


See feedback above on path

lightwalker-eth · 2025-12-03T22:46:35Z

packages/ensnode-sdk/src/client.ts

+   * });
+   * if (response.responseCode === ReferrerDetailResponseCodes.Ok) {
+   *   const { referrer } = response.data;
+   *   if (referrer.rank !== null) {


Please see related feedback about adding a type field which we could use to more explicitly distinguish between ranked vs unranked.

lightwalker-eth · 2025-12-04T12:08:50Z

@Goader Hey, as part of this PR could you please also look for other places in our existing code where terminology might be refined. For example I was just looking through our existing code and saw this:

https://github.com/namehash/ensnode/blob/main/packages/ensnode-sdk/src/client.ts#L366-L418

Here terminology improvements can include:

Rename getReferrerLeaderboard to getReferrerLeaderboardPage
Rename ReferrerLeaderboardPaginationRequest to ReferrerLeaderboardPageRequest
etc..

lightwalker-eth

@Goader Hey great updates 🚀

I shared a few small suggestions.

Could you please also add changesets as necessary for this PR?

After that, please take the lead to merge this PR 🚀 Thanks!

lightwalker-eth · 2025-12-06T22:30:53Z

packages/ensnode-sdk/src/ensanalytics/types.ts

 * Request parameters for a referrer leaderboard page query.
 */
-export interface ReferrerLeaderboardPaginationRequest extends ReferrerLeaderboardPaginationParams {}
+export interface ReferrerLeaderboardPageRequest extends ReferrerLeaderboardPaginationParams {}


Suggested change

export interface ReferrerLeaderboardPageRequest extends ReferrerLeaderboardPaginationParams {}

export interface ReferrerLeaderboardPageRequest extends ReferrerLeaderboardPageParams {}

lightwalker-eth · 2025-12-06T22:44:04Z

apps/ensapi/src/handlers/ensanalytics-api.ts

+          error: "Internal Server Error",
+          errorMessage: "Failed to load referrer leaderboard data.",
+        } satisfies ReferrerDetailResponse),
+        500,


Suggested change

error: "Internal Server Error",

errorMessage: "Failed to load referrer leaderboard data.",

} satisfies ReferrerDetailResponse),

500,

error: "Service Unavailable",

errorMessage: "Referrer leaderboard data has not been successfully cached yet.",

} satisfies ReferrerDetailResponse),

503,

lightwalker-eth · 2025-12-06T22:48:13Z

packages/ens-referrals/src/referrer-metrics.ts

+ * @param referrer - The referrer address
+ * @returns An {@link UnrankedReferrerMetrics} with zero values for all metrics and null rank
+ */
+export const buildUnrankedReferrerMetrics = (referrer: Address): UnrankedReferrerMetrics => {


I assume we aren't using this anywhere anymore based on the new logic in getReferrerDetail?

It is used in getReferrerDetail, and I think it should stay that way to avoid mixing logic. I also added a verification function for buildUnrankedReferrerMetrics similarly to other build... functions.

feat: added referrer details endpoint

30e7983

Goader self-assigned this Nov 26, 2025

Merge remote-tracking branch 'origin' into feat/referrer-detail-api

8361248

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

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

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

added unranked referrer interface and handling of referrers that are …

7143b59

…not qualified

vercel bot deployed to Preview – ensrainbow.io December 3, 2025 17:00 View deployment

vercel bot deployed to Preview – ensnode.io December 3, 2025 17:00 View deployment

vercel bot deployed to Preview – admin.ensnode.io December 3, 2025 17:00 View deployment

Goader commented Dec 3, 2025

View reviewed changes

updated client with unranked referrer handling

ca85777

vercel bot deployed to Preview – ensrainbow.io December 3, 2025 17:25 View deployment

Merge remote-tracking branch 'origin' into feat/referrer-detail-api

b30afaf

vercel bot deployed to Preview – ensnode.io December 3, 2025 17:25 View deployment

vercel bot deployed to Preview – admin.ensnode.io December 3, 2025 17:25 View deployment

vercel bot deployed to Preview – ensrainbow.io December 3, 2025 17:26 View deployment

vercel bot deployed to Preview – ensnode.io December 3, 2025 17:27 View deployment

vercel bot deployed to Preview – admin.ensnode.io December 3, 2025 17:27 View deployment

Goader marked this pull request as ready for review December 3, 2025 17:27

Goader requested a review from a team as a code owner December 3, 2025 17:27

Goader requested review from lightwalker-eth and tk-o December 3, 2025 17:27

lightwalker-eth reviewed Dec 3, 2025

View reviewed changes

feedback applied

865fa72

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

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

vercel bot had a problem deploying to Preview – admin.ensnode.io December 6, 2025 16:33 Failure

Merge remote-tracking branch 'origin' into feat/referrer-detail-api

9ede4d5

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

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

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

Goader requested a review from lightwalker-eth December 6, 2025 16:41

lightwalker-eth approved these changes Dec 7, 2025

View reviewed changes

lightwalker-eth mentioned this pull request Dec 7, 2025

ENSAnalytics endpoints with detailed statistics for a specific address #1262

Closed

7 tasks

Goader added 3 commits December 7, 2025 16:00

Merge remote-tracking branch 'origin' into feat/referrer-detail-api

90f137a

feedback applied

28c4b9f

docs(changeset):

9cd6a6c

vercel bot deployed to Preview – ensrainbow.io December 7, 2025 15:04 View deployment

vercel bot deployed to Preview – ensnode.io December 7, 2025 15:05 View deployment

vercel bot deployed to Preview – admin.ensnode.io December 7, 2025 15:05 View deployment

changesets

3a3fc72

vercel bot deployed to Preview – ensrainbow.io December 7, 2025 15:11 View deployment

vercel bot deployed to Preview – ensnode.io December 7, 2025 15:12 View deployment

vercel bot deployed to Preview – admin.ensnode.io December 7, 2025 15:12 View deployment

Goader merged commit e35600f into main Dec 7, 2025
10 checks passed

Goader deleted the feat/referrer-detail-api branch December 7, 2025 15:33

github-actions bot mentioned this pull request Dec 7, 2025

Release New Version #1342

Merged

	* Always false for unranked referrers since they don't qualify for awards.
	* Always false for unranked referrers.

	* The referrer's rank on the leaderboard is null because they are not on the leaderboard.
	* The referrer is not on the leaderboard and therefore has no rank.

	* a referrer who is not on the leaderboard (has zero referrals).
	* a referrer who is not on the leaderboard (has zero referrals within the rules associated with the leaderboard).

	export interface ReferrerDetailData {
	export interface ReferrerDetailRanked {

	app.get("/referrer/:referrer", validate("param", referrerAddressSchema), async (c) => {
	app.get("/referrers/:referrer", validate("param", referrerAddressSchema), async (c) => {

	export interface ReferrerLeaderboardPageRequest extends ReferrerLeaderboardPaginationParams {}
	export interface ReferrerLeaderboardPageRequest extends ReferrerLeaderboardPageParams {}

feat(ensanalytics): referrer details endpoint #1318

feat(ensanalytics): referrer details endpoint #1318

Uh oh!

Conversation

Goader commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

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

Uh oh!

Uh oh!

Choose a reason for hiding this comment

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!

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!

lightwalker-eth commented Dec 4, 2025

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Goader commented Nov 26, 2025 •

edited

Loading

changeset-bot bot commented Nov 26, 2025 •

edited

Loading

vercel bot commented Nov 26, 2025 •

edited

Loading