Added ENS currency to ensnode-sdk (#2017)

Author: Goader

.changeset/eager-otters-wave.md

@@ -0,0 +1,5 @@
+---
+"@ensnode/ensnode-sdk": minor
+---
+
+Add `$ENS Tokens` as a supported currency in `@ensnode/ensnode-sdk`: `CurrencyIds.ENSTokens`, `PriceEnsTokens`/`SerializedPriceEnsTokens` types, and the `priceEnsTokens`, `parseEnsTokens`, `serializePriceEnsTokens`, `deserializePriceEnsTokens` helpers.

packages/ensnode-sdk/src/shared/currencies.test.ts

@@ -11,12 +11,15 @@ import {
   minPrice,
   type Price,
   type PriceDai,
+  type PriceEnsTokens,
   type PriceEth,
   type PriceUsdc,
   parseDai,
+  parseEnsTokens,
   parseEth,
   parseUsdc,
   priceDai,
+  priceEnsTokens,
   priceEth,
   priceUsdc,
   scalePrice,
@@ -31,6 +34,12 @@ describe("Currencies", () => {
         name: "ETH",
         decimals: 18,
       } satisfies CurrencyInfo);
+
+      expect(getCurrencyInfo(CurrencyIds.ENSTokens)).toStrictEqual({
+        id: CurrencyIds.ENSTokens,
+        name: "$ENS Tokens",
+        decimals: 18,
+      } satisfies CurrencyInfo);
     });
   });
 
@@ -61,6 +70,15 @@ describe("Currencies", () => {
     });
   });
 
+  describe("priceEnsTokens", () => {
+    it("returns correct Price object", () => {
+      expect(priceEnsTokens(1n)).toStrictEqual({
+        amount: 1n,
+        currency: CurrencyIds.ENSTokens,
+      } satisfies PriceEnsTokens);
+    });
+  });
+
   describe("isPriceCurrencyEqual", () => {
     it("returns true when two prices have the same currency", () => {
       expect(isPriceCurrencyEqual(priceEth(1n), priceEth(1n))).toBe(true);
@@ -199,6 +217,13 @@ describe("Currencies", () => {
         expect(result.amount).toBe(500000000000000000n);
       });
 
+      it("should preserve ENSTokens currency type and scale correctly", () => {
+        const price: PriceEnsTokens = priceEnsTokens(1000000000000000000n);
+        const result: PriceEnsTokens = scalePrice(price, 0.5);
+        expect(result.currency).toBe("ENSTokens");
+        expect(result.amount).toBe(500000000000000000n);
+      });
+
       it("should preserve currency when scaling by 1", () => {
         const price = priceUsdc(1000000n);
         const result = scalePrice(price, 1);
@@ -239,6 +264,12 @@ describe("Currencies", () => {
         const result: PriceDai = scalePrice(price, 0.5);
         expect(result.currency).toBe("DAI");
       });
+
+      it("should preserve PriceEnsTokens type", () => {
+        const price: PriceEnsTokens = priceEnsTokens(1000000000000000000n);
+        const result: PriceEnsTokens = scalePrice(price, 0.5);
+        expect(result.currency).toBe("ENSTokens");
+      });
     });
 
     describe("error handling", () => {
@@ -536,4 +567,100 @@ describe("Currencies", () => {
       });
     });
   });
+
+  describe("parseEnsTokens", () => {
+    describe("correct format and decimals", () => {
+      it("should return PriceEnsTokens type with correct currency", () => {
+        const result = parseEnsTokens("1");
+        expect(result).toHaveProperty("currency", CurrencyIds.ENSTokens);
+        expect(result).toHaveProperty("amount");
+        expect(result.currency).toBe(CurrencyIds.ENSTokens);
+        expect(typeof result.amount).toBe("bigint");
+      });
+
+      it("should use 18 decimals from getCurrencyInfo", () => {
+        const currencyInfo = getCurrencyInfo(CurrencyIds.ENSTokens);
+        expect(currencyInfo.decimals).toBe(18);
+
+        // Test that it uses 18 decimals by parsing a value with 18 decimal places
+        const result = parseEnsTokens("1.123456789012345678");
+        expect(result.amount).toBe(1123456789012345678n);
+      });
+
+      it("should parse integer ENSTokens values correctly", () => {
+        expect(parseEnsTokens("1")).toEqual({
+          currency: CurrencyIds.ENSTokens,
+          amount: 1000000000000000000n, // 1 $ENS = 10^18 smallest units
+        } satisfies PriceEnsTokens);
+
+        expect(parseEnsTokens("0")).toEqual({
+          currency: CurrencyIds.ENSTokens,
+          amount: 0n,
+        } satisfies PriceEnsTokens);
+
+        expect(parseEnsTokens("123")).toEqual({
+          currency: CurrencyIds.ENSTokens,
+          amount: 123000000000000000000n,
+        } satisfies PriceEnsTokens);
+      });
+
+      it("should parse decimal ENSTokens values correctly", () => {
+        expect(parseEnsTokens("123.456789012345678")).toEqual({
+          currency: CurrencyIds.ENSTokens,
+          amount: 123456789012345678000n,
+        } satisfies PriceEnsTokens);
+
+        expect(parseEnsTokens("0.001")).toEqual({
+          currency: CurrencyIds.ENSTokens,
+          amount: 1000000000000000n,
+        } satisfies PriceEnsTokens);
+
+        expect(parseEnsTokens("0.5")).toEqual({
+          currency: CurrencyIds.ENSTokens,
+          amount: 500000000000000000n,
+        } satisfies PriceEnsTokens);
+      });
+
+      it("should handle small ENSTokens values (minimum unit)", () => {
+        expect(parseEnsTokens("0.000000000000000001")).toEqual({
+          currency: CurrencyIds.ENSTokens,
+          amount: 1n, // 1 smallest unit
+        } satisfies PriceEnsTokens);
+      });
+
+      it("should handle maximum precision (18 decimal places)", () => {
+        expect(parseEnsTokens("1.123456789012345678")).toEqual({
+          currency: CurrencyIds.ENSTokens,
+          amount: 1123456789012345678n,
+        } satisfies PriceEnsTokens);
+      });
+    });
+
+    describe("error handling", () => {
+      it("should throw on invalid format", () => {
+        expect(() => parseEnsTokens("abc")).toThrow();
+        expect(() => parseEnsTokens("1.2.3")).toThrow();
+      });
+
+      it("should throw on empty string", () => {
+        expect(() => parseEnsTokens("")).toThrow("amount must be a non-negative decimal string");
+      });
+
+      it("should throw on whitespace-only string", () => {
+        expect(() => parseEnsTokens("   ")).toThrow("amount must be a non-negative decimal string");
+        expect(() => parseEnsTokens("\t")).toThrow("amount must be a non-negative decimal string");
+        expect(() => parseEnsTokens("\n")).toThrow("amount must be a non-negative decimal string");
+      });
+
+      it("should throw on negative values", () => {
+        expect(() => parseEnsTokens("-1")).toThrow("amount must be a non-negative decimal string");
+        expect(() => parseEnsTokens("-0.5")).toThrow(
+          "amount must be a non-negative decimal string",
+        );
+        expect(() => parseEnsTokens("-123.456")).toThrow(
+          "amount must be a non-negative decimal string",
+        );
+      });
+    });
+  });
 });

packages/ensnode-sdk/src/shared/currencies.ts

@@ -11,6 +11,7 @@ export const CurrencyIds = {
   ETH: "ETH",
   USDC: "USDC",
   DAI: "DAI",
+  ENSTokens: "ENSTokens",
 } as const;
 
 export type CurrencyId = (typeof CurrencyIds)[keyof typeof CurrencyIds];
@@ -46,7 +47,13 @@ export interface PriceUsdc {
   amount: CurrencyAmount;
 }
 
-export type Price = PriceEth | PriceDai | PriceUsdc;
+export interface PriceEnsTokens {
+  currency: typeof CurrencyIds.ENSTokens;
+
+  amount: CurrencyAmount;
+}
+
+export type Price = PriceEth | PriceDai | PriceUsdc | PriceEnsTokens;
 
 /**
  * Serialized representation of {@link PriceEth}.
@@ -69,10 +76,21 @@ export interface SerializedPriceUsdc extends Omit<PriceUsdc, "amount"> {
   amount: SerializedCurrencyAmount;
 }
 
+/**
+ * Serialized representation of {@link PriceEnsTokens}.
+ */
+export interface SerializedPriceEnsTokens extends Omit<PriceEnsTokens, "amount"> {
+  amount: SerializedCurrencyAmount;
+}
+
 /**
  * Serialized representation of {@link Price}.
  */
-export type SerializedPrice = SerializedPriceEth | SerializedPriceDai | SerializedPriceUsdc;
+export type SerializedPrice =
+  | SerializedPriceEth
+  | SerializedPriceDai
+  | SerializedPriceUsdc
+  | SerializedPriceEnsTokens;
 
 export interface CurrencyInfo {
   id: CurrencyId;
@@ -96,6 +114,11 @@ const currencyInfo: Record<CurrencyId, CurrencyInfo> = {
     name: "Dai Stablecoin",
     decimals: 18,
   },
+  [CurrencyIds.ENSTokens]: {
+    id: CurrencyIds.ENSTokens,
+    name: "$ENS Tokens",
+    decimals: 18,
+  },
 };
 
 /**
@@ -135,6 +158,16 @@ export function priceDai(amount: Price["amount"]): PriceDai {
   };
 }
 
+/**
+ * Create price in ENS Tokens for given amount.
+ */
+export function priceEnsTokens(amount: Price["amount"]): PriceEnsTokens {
+  return {
+    amount,
+    currency: CurrencyIds.ENSTokens,
+  };
+}
+
 /**
  * Check if two prices have the same currency.
  */
@@ -382,3 +415,30 @@ export function parseDai(value: string): PriceDai {
   const amount = parseUnits(value, currencyInfo.decimals);
   return priceDai(amount);
 }
+
+/**
+ * Parses a string representation of ENS Tokens into a {@link PriceEnsTokens} object.
+ *
+ * Uses {@link getCurrencyInfo} to get the correct number of decimals (18) for ENS Tokens
+ * and {@link parseUnits} from viem to convert the decimal string to a bigint.
+ *
+ * **Note:** Values with more than 18 decimal places will be truncated/rounded by viem's `parseUnits`.
+ *
+ * @param value - The decimal string to parse (e.g., "123.456789012345678" for 123.456789012345678 ENS Tokens)
+ * @returns A PriceEnsTokens object with the amount in the smallest unit (18 decimals)
+ *
+ * @throws {Error} If value is empty, whitespace-only or untrimmed
+ * @throws {Error} If value represents a negative number
+ * @throws {Error} If value is not a valid decimal string (e.g., "abc", "1.2.3")
+ *
+ * @example
+ * parseEnsTokens("123.456789012345678") // returns { currency: "ENSTokens", amount: 123456789012345678000n }
+ * parseEnsTokens("1") // returns { currency: "ENSTokens", amount: 1000000000000000000n }
+ * parseEnsTokens("0.001") // returns { currency: "ENSTokens", amount: 1000000000000000n }
+ */
+export function parseEnsTokens(value: string): PriceEnsTokens {
+  validateAmountToParse(value);
+  const currencyInfo = getCurrencyInfo(CurrencyIds.ENSTokens);
+  const amount = parseUnits(value, currencyInfo.decimals);
+  return priceEnsTokens(amount);
+}

packages/ensnode-sdk/src/shared/deserialize.ts

@@ -1,7 +1,7 @@
 import type { AccountId, ChainId, ChainIdString, Duration, UrlString } from "enssdk";
 import z, { prettifyError } from "zod/v4";
 
-import type { PriceDai, PriceEth, PriceUsdc } from "./currencies";
+import type { PriceDai, PriceEnsTokens, PriceEth, PriceUsdc } from "./currencies";
 import type { BlockNumber, BlockRef, Datetime } from "./types";
 import {
   makeAccountIdStringSchema,
@@ -11,6 +11,7 @@ import {
   makeDatetimeSchema,
   makeDurationSchema,
   makePriceDaiSchema,
+  makePriceEnsTokensSchema,
   makePriceEthSchema,
   makePriceUsdcSchema,
   makeUnixTimestampSchema,
@@ -140,3 +141,17 @@ export function deserializePriceDai(maybePrice: unknown, valueLabel?: string): P
 
   return parsed.data;
 }
+
+export function deserializePriceEnsTokens(
+  maybePrice: unknown,
+  valueLabel?: string,
+): PriceEnsTokens {
+  const schema = makePriceEnsTokensSchema(valueLabel);
+  const parsed = schema.safeParse(maybePrice);
+
+  if (parsed.error) {
+    throw new Error(`Cannot deserialize PriceEnsTokens:\n${prettifyError(parsed.error)}\n`);
+  }
+
+  return parsed.data;
+}

packages/ensnode-sdk/src/shared/serialize.ts

@@ -3,10 +3,12 @@ import type { ChainId, ChainIdString, DatetimeISO8601, UrlString } from "enssdk"
 import type {
   Price,
   PriceDai,
+  PriceEnsTokens,
   PriceEth,
   PriceUsdc,
   SerializedPrice,
   SerializedPriceDai,
+  SerializedPriceEnsTokens,
   SerializedPriceEth,
   SerializedPriceUsdc,
 } from "./currencies";
@@ -63,3 +65,10 @@ export function serializePriceUsdc(price: PriceUsdc): SerializedPriceUsdc {
 export function serializePriceDai(price: PriceDai): SerializedPriceDai {
   return serializePrice(price) as SerializedPriceDai;
 }
+
+/**
+ * Serializes a {@link PriceEnsTokens} object.
+ */
+export function serializePriceEnsTokens(price: PriceEnsTokens): SerializedPriceEnsTokens {
+  return serializePrice(price) as SerializedPriceEnsTokens;
+}

packages/ensnode-sdk/src/shared/zod-schemas.test.ts

@@ -2,7 +2,14 @@ import { asLiteralLabel, encodeLabelHash, labelhashLiteralLabel } from "enssdk";
 import { describe, expect, it } from "vitest";
 import { prettifyError, type ZodSafeParseResult } from "zod/v4";
 
-import { CurrencyIds, priceDai, priceEth, priceUsdc, type SerializedPrice } from "./currencies";
+import {
+  CurrencyIds,
+  priceDai,
+  priceEnsTokens,
+  priceEth,
+  priceUsdc,
+  type SerializedPrice,
+} from "./currencies";
 import {
   makeBooleanStringSchema,
   makeChainIdSchema,
@@ -149,6 +156,13 @@ describe("ENSIndexer: Shared", () => {
         } satisfies SerializedPrice),
       ).toStrictEqual(priceDai(123n));
 
+      expect(
+        makePriceSchema().parse({
+          amount: "456",
+          currency: CurrencyIds.ENSTokens,
+        } satisfies SerializedPrice),
+      ).toStrictEqual(priceEnsTokens(456n));
+
       expect(
         formatParseError(
           makePriceSchema().safeParse({
@@ -166,7 +180,7 @@ describe("ENSIndexer: Shared", () => {
             currency: "BTC",
           } satisfies SerializedPrice),
         ),
-      ).toMatch(/Price currency must be one of ETH, USDC, DAI/i);
+      ).toMatch(/Price currency must be one of ETH, USDC, DAI, ENSTokens/i);
     });
 
     describe("NormalizedAddress", () => {