feat(ensapi): introduce Name Tokens API #1358

tk-o · 2025-12-05T20:32:08Z

Suggested review order: commit-by-commit.

This PR introduces new Name Tokens API route.

Example: `finalroll.eth` (minted, wrapped)

Example request:

GET /api/name-tokens?name=finalroll.eth
GET /api/name-tokens?domainId=0x57bda742b7d14316ce9f4f90a4a6035b741057e90ffa1d078ac6e24b1c1028df

Example response:

{
  "responseCode": "ok",
  "registeredNameTokens": {
    "domainId": "0x57bda742b7d14316ce9f4f90a4a6035b741057e90ffa1d078ac6e24b1c1028df",
    "name": "finalroll.eth",
    "tokens": [
      {
        "domainAsset": {
          "assetId": {
            "assetNamespace": "erc721",
            "contract": {
              "chainId": 1,
              "address": "0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85"
            },
            "tokenId": "0x5dc22117a784fc74bc3d4df34423ac78eabc534a3d233be07950b82fa68fcac7"
          },
          "domainId": "0x57bda742b7d14316ce9f4f90a4a6035b741057e90ffa1d078ac6e24b1c1028df"
        },
        "ownership": {
          "ownershipType": "proxy",
          "owner": {
            "chainId": 1,
            "address": "0xd4416b13d2b3a9abae7acd5d6c2bbdbe25686401"
          }
        },
        "mintStatus": "minted"
      },
      {
        "domainAsset": {
          "assetId": {
            "assetNamespace": "erc1155",
            "contract": {
              "chainId": 1,
              "address": "0xd4416b13d2b3a9abae7acd5d6c2bbdbe25686401"
            },
            "tokenId": "0x57bda742b7d14316ce9f4f90a4a6035b741057e90ffa1d078ac6e24b1c1028df"
          },
          "domainId": "0x57bda742b7d14316ce9f4f90a4a6035b741057e90ffa1d078ac6e24b1c1028df"
        },
        "ownership": {
          "ownershipType": "effective",
          "owner": {
            "chainId": 1,
            "address": "0x27c9b34eb43523447d3e1bcf26f009d814522687"
          }
        },
        "mintStatus": "minted"
      }
    ],
    "expiresAt": 1796731799,
    "accurateAsOf": 1765280254
  }
}

Example: `tko.eth` (unwrapped, expired)

Example request:

GET /api/name-tokens?name=tko.eth
GET /api/name-tokens?domainId=0xaf20e732cb67b5895d3a9516990611765a4ee138ebdadb60410539beb1dc42bb

Example response:

{
  "responseCode": "ok",
  "registeredNameTokens": {
    "domainId": "0xaf20e732cb67b5895d3a9516990611765a4ee138ebdadb60410539beb1dc42bb",
    "name": "tko.eth",
    "tokens": [
      {
        "domainAsset": {
          "assetId": {
            "assetNamespace": "erc721",
            "contract": {
              "chainId": 1,
              "address": "0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85"
            },
            "tokenId": "0x2376b3952dc704bc0cbebbdab63e4b510d63a1234f5910f12362f5b34bdcc704"
          },
          "domainId": "0xaf20e732cb67b5895d3a9516990611765a4ee138ebdadb60410539beb1dc42bb"
        },
        "ownership": {
          "ownershipType": "effective",
          "owner": {
            "chainId": 1,
            "address": "0xd0ed779af7e3063c9121590c1f6a90396a22b824"
          }
        },
        "mintStatus": "minted"
      }
    ],
    "expiresAt": 1758748175,
    "accurateAsOf": 1765280339
  }
}

Builds on top of #1357

TODOs

~~Pagination support? Might not be required, though. Saw up to two name token records while testing. Most of the names will have just a single associated name token record.~~
- Not required
only merge this PR if refactor: serialized representations for AccountId and AssetId #1374 is approved to be merged. The refactor: serialized representations for AccountId and AssetId #1374 must be merged right after feat(ensapi): introduce Name Tokens API #1358.

Followup on

When there were no tokens found for the requested name, the response shoul be a 200 success where we just return an empty array of name tokens.
Think of better name (if any) for RegisteredNameTokens entity that's returned by Name Tokens API.
Set explicit order of name tokens in the response.
Handle the edge-case found by @lightwalker-eth in ENS app.

vercel · 2025-12-05T20:32:12Z

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 10, 2025 5:29pm
ensnode.io	Ready	Preview	Comment	Dec 10, 2025 5:29pm
ensrainbow.io	Ready	Preview	Comment	Dec 10, 2025 5:29pm

changeset-bot · 2025-12-05T20:32:12Z

🦋 Changeset detected

Latest commit: b5d0cdc

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

This PR includes changesets to release 14 packages

Name	Type
@ensnode/ensnode-react	Minor
ensapi	Minor
@ensnode/ensnode-sdk	Minor
ensindexer	Minor
ensadmin	Minor
ensrainbow	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

apps/ensindexer/src/plugins/registrars/ethnames/lib/registrar-helpers.ts

Also, fixes deserialization bug.

lightwalker-eth

@tk-o Really happy to see this! Shared some suggestions and feedback. Appreciate your efforts to help make this API amazing 🫡

apps/ensapi/src/handlers/name-tokens-api.ts

packages/ensnode-sdk/src/registrars/basenames-subregistry.ts

packages/ensnode-sdk/src/ens/names.test.ts

packages/ensnode-sdk/src/api/name-tokens/response.ts

packages/ensnode-sdk/src/tokenscope/name-token.ts

…endpoint

simplify name tokens api data model

Add `domainId` request param for Name Tokens API route

Update `NameTokensResponseError` variant types.

define request schema

Update code docs for `RegisteredNameTokens`

Introduce Name Token ownership concept

…r `AccountId` type.

…odule.

lightwalker-eth

@tk-o Hey great job! 🚀 Shared feedback please take the lead to merge this once ready 👍

apps/ensapi/src/handlers/name-tokens-api.ts

lightwalker-eth · 2025-12-09T16:59:54Z

apps/ensapi/src/handlers/name-tokens-api.ts

+  // Return 404 response with error code for unknown name context when
+  // the no name tokens were found for the domain ID associated with
+  // the requested name.
+  if (!registeredNameTokens) {


I don't believe this should be a 404 error case.

Shouldn't it be a 200 success where we just return an empty array of name tokens?

lightwalker-eth · 2025-12-09T17:00:50Z

packages/ensnode-react/src/hooks/useNameTokens.ts

+
+  return useQuery({
+    ...queryOptions,
+    refetchInterval: false, // no refetching - assume data is immutable until a full page refresh


I thought we had a different strategy for this idea on other hooks we've implemented?

@lightwalker-eth, your previous feedback on that setting param:

In packages/ensnode-react/src/hooks/useNameTokens.ts:

+ refetchInterval: 60 * 1000, // 60 seconds - latest Name Tokens change infrequently

No, the results do not change frequently.

I would say it should be assumed to be effectively immutable until a full page refresh.

refetchInterval: false guarantees there query is immutable until the full page refresh.

@tk-o I was referring to ASSUME_IMMUTABLE_QUERY that we built. I assume that's what we want to use here?

packages/ensnode-sdk/src/api/name-tokens/response.ts

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

packages/ensnode-sdk/src/api/name-tokens/response.ts

+   *    c) Is no longer wrapped by the NameWrapper, and is also no longer
+   *       minted by the BaseRegistrar (both tokens now burned by sending to
+   *       the null address).
+   */


There's another edge case to consider which is defined here: https://namehash.slack.com/archives/C08BMPFUUDD/p1765288628066849

Cross-posting for clarity:

We may want to track independent expiresAt values for each NameToken. This can help us with goals including:

The specific case we're discussing here, where we need the ability to represent that a particular NameToken 's registration lifecycle has expired, even though the token itself is still technically minted.

The additional case where the expiration time of a name in the NameWrapper can go out of sync with the expiration time of a name in the BaseRegistrar.

apps/ensapi/src/handlers/name-tokens-api.ts

Replaced with `getNameWrapperAccounts` from ENSNode SDK.

Update code docs

…endpoint

lightwalker-eth

@tk-o Looks great, I'm happy to merge this. Please take the lead to merge this and then we can follow up on comments in another PR 👍

apps/ensapi/src/handlers/name-tokens-api.ts

lightwalker-eth · 2025-12-10T17:17:18Z

apps/ensapi/src/handlers/name-tokens-api.ts

  if (request.name !== undefined) {
    const { name } = request;

+    // return 404 when the requested name was the ENS Root


Suggested change

// return 404 when the requested name was the ENS Root

// return 404 when the requested name was the ENS Root as otherwise

// the call below to `getParentNameFQDN` will throw an error

lightwalker-eth · 2025-12-10T17:20:20Z

packages/ensnode-sdk/src/api/name-tokens/response.ts

   *
-   * The latest Registration Lifecycle for a node referenced in
-   * `token.domainAsset.domainId`.
+   * The latest Registration Lifecycle for a node referenced in `domainId`.


Suggested change

* The latest Registration Lifecycle for a node referenced in `domainId`.

* The latest Registration Lifecycle for the node referenced in `domainId`.

lightwalker-eth · 2025-12-10T17:20:55Z

packages/ensnode-sdk/src/tokenscope/name-token.ts

 */
 export const NameTokenOwnershipTypes = {
+  /**
+   * Name Token is owned by NameWrapper account.


Suggested change

* Name Token is owned by NameWrapper account.

* The owner of this Name Token is a NameWrapper account.

lightwalker-eth · 2025-12-10T17:21:23Z

packages/ensnode-sdk/src/tokenscope/name-token.ts

+  /**
+   * Name Token is owned fully onchain.
+   *
+   * This ownership type can only apply to direct subnames of `.eth`


Suggested change

* This ownership type can only apply to direct subnames of `.eth`

* Currently, this ownership type only applies to direct subnames of `.eth`

lightwalker-eth · 2025-12-10T17:30:31Z

packages/ensnode-react/src/hooks/useNameTokens.ts

+
+  return useQuery({
+    ...queryOptions,
+    refetchInterval: false, // no refetching - assume data is immutable until a full page refresh


@tk-o I was referring to ASSUME_IMMUTABLE_QUERY that we built. I assume that's what we want to use here?

lightwalker-eth · 2025-12-10T17:31:39Z

packages/ensnode-sdk/src/api/name-tokens/response.ts

+/**
+ * Name Tokens for a registered name.
+ */
+export interface RegisteredNameTokens {


Maybe then it's just a NameTokensResponse?

lightwalker-eth · 2025-12-10T17:32:50Z

apps/ensapi/src/lib/name-tokens/find-name-tokens-for-domain.ts

+ * Find all Name Tokens for the registered domain by domain ID,
+ * accurate as of `accurateAsOf`.
+ *
+ * @returns {RegisteredNameTokens} if some tokens associated with


When we action the follow-ups on this PR, Suggest we change all this "NameTokensNotIndexed" stuff to the more simple idea: "NameTokensUnknown"

lightwalker-eth · 2025-12-10T17:38:04Z

packages/ensnode-sdk/src/api/name-tokens/response.ts

+  /**
+   * Name Tokens for the requested name.
+   */
+  nameTokens: RegisteredNameToken[];


Appreciate that complexity. We should be able to improve this once we transition the expiresAt field into being a field for each NameToken in the response.

lightwalker-eth · 2025-12-10T17:39:29Z

packages/ensnode-sdk/src/api/name-tokens/response.ts

+   *  - Order of name tokens follows the order of onchain events that were
+   *    indexed when a token was minted, or burned.


@tk-o The more I think about it, the more I think we should just simplify this and say that the order of tokens returned in the response is undefined and not add any sort rules to it. There's no special need or goal for sort rules here.

tk-o added 3 commits December 5, 2025 21:29

feat(ensnode-sdk): introduce api/name-tokens module

22ac966

feat(ensindexer): integrate ENSNode SDK registrar helpers

5899433

feat(ensapi): introduce Name Tokens API handler

470e8ff

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

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

fix recursion error

2ebbf4b

vercel bot deployed to Preview – ensrainbow.io December 5, 2025 21:47 View deployment

vercel bot deployed to Preview – ensnode.io December 5, 2025 21:48 View deployment

vercel bot deployed to Preview – admin.ensnode.io December 5, 2025 21:48 View deployment

tk-o commented Dec 5, 2025

View reviewed changes

apps/ensindexer/src/plugins/registrars/ethnames/lib/registrar-helpers.ts Outdated Show resolved Hide resolved

feat(ensnode-react): introduce useNameTokens hook

b775be3

Also, fixes deserialization bug.

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

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

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

lightwalker-eth reviewed Dec 6, 2025

View reviewed changes

tk-o added 8 commits December 8, 2025 10:37

Merge remote-tracking branch 'origin/main' into feat/name-tokens-api-…

cea3654

…endpoint

Merge remote-tracking branch 'origin/main' into feat/name-tokens-api-…

a2297f8

…endpoint

apply pr feedback

e127318

simplify name tokens api data model

apply pr feedback

ba83145

Add `domainId` request param for Name Tokens API route

apply pr feedback

4ae0a36

Update `NameTokensResponseError` variant types.

apply pr feedback

264cabe

define request schema

apply pr feedback

dc01a9a

Update code docs for `RegisteredNameTokens`

apply pr feedback

c092977

Introduce Name Token ownership concept

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

vercel bot deployed to Preview – ensnode.io December 9, 2025 11:29 View deployment

vercel bot deployed to Preview – admin.ensnode.io December 9, 2025 11:29 View deployment

tk-o changed the title ~~WIP feat(ensapi): introduce Name Tokens API~~ feat(ensapi): introduce Name Tokens API Dec 9, 2025

tk-o mentioned this pull request Dec 9, 2025

refactor: serialized representations for AccountId and AssetId #1374

Merged

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

tk-o added 7 commits December 9, 2025 19:51

docs(changeset): Updates serialization and deserialization methods fo…

8c6b860

…r `AccountId` type.

docs(changeset): Introduces the NameToken concept to tokenscope m…

986659d

…odule.

docs(changeset): Introduces name-token submodule to api module.

8bd3169

docs(changeset): Implements nameTokens method on ENSNodeClient.

8f78b58

docs(changeset): Implements useNameTokens hook.

bbfaf09

docs(changeset): Implements updated type system from ENSNode SDK.

20997e0

docs(changeset): Introduces Name Tokens API.

6becf36

vercel bot deployed to Preview – ensrainbow.io December 9, 2025 18:59 View deployment

vercel bot deployed to Preview – ensnode.io December 9, 2025 18:59 View deployment

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

lightwalker-eth approved these changes Dec 9, 2025

View reviewed changes

tk-o added 3 commits December 10, 2025 15:34

fix(ensapi.name-tokens-api): ENS Root name case

f08b2c4

fix(ensapi.name-tokens-api): replace getNameWrapperAddresses function

69447d6

Replaced with `getNameWrapperAccounts` from ENSNode SDK.

apply pr feedback

9fe55a9

Update code docs

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

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

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

Merge remote-tracking branch 'origin/main' into feat/name-tokens-api-…

6603c61

…endpoint

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

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

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

Merge remote-tracking branch 'origin/main' into feat/name-tokens-api-…

b5d0cdc

…endpoint

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

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

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

lightwalker-eth approved these changes Dec 10, 2025

View reviewed changes

tk-o merged commit f64dad6 into main Dec 10, 2025
10 checks passed

tk-o deleted the feat/name-tokens-api-endpoint branch December 10, 2025 19:59

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

Release New Version #1380

Merged

	// return 404 when the requested name was the ENS Root
	// return 404 when the requested name was the ENS Root as otherwise
	// the call below to `getParentNameFQDN` will throw an error

	* The latest Registration Lifecycle for a node referenced in `domainId`.
	* The latest Registration Lifecycle for the node referenced in `domainId`.

	* Name Token is owned by NameWrapper account.
	* The owner of this Name Token is a NameWrapper account.

	* This ownership type can only apply to direct subnames of `.eth`
	* Currently, this ownership type only applies to direct subnames of `.eth`

		* - Order of name tokens follows the order of onchain events that were
		* indexed when a token was minted, or burned.

feat(ensapi): introduce Name Tokens API #1358

feat(ensapi): introduce Name Tokens API #1358

Uh oh!

Conversation

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

Uh oh!

TODOs

Followup on

Uh oh!

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

Uh oh!

Uh oh!

changeset-bot bot commented Dec 5, 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!

lightwalker-eth left a comment

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lightwalker-eth left a comment

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!

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

tk-o commented Dec 5, 2025 •

edited

Loading

vercel bot commented Dec 5, 2025 •

edited

Loading

changeset-bot bot commented Dec 5, 2025 •

edited

Loading