@namehash/ens-referrals 1.5.1 → 1.6.0

package/dist/index.js

@@ -122,49 +122,469 @@ var buildAggregatedReferrerMetrics = (referrers, rules) => {
   return result;
 };
 
-// src/currency.ts
-function isValidUSDQuantity(value) {
-  return isFiniteNonNegativeNumber(value);
+// src/api/deserialize.ts
+import { prettifyError } from "zod/v4";
+
+// src/api/zod-schemas.ts
+import { z as z2 } from "zod/v4";
+
+// ../../node_modules/.pnpm/caip@1.1.1/node_modules/caip/dist/index.mjs
+function _extends() {
+  _extends = Object.assign || function(target) {
+    for (var i = 1; i < arguments.length; i++) {
+      var source = arguments[i];
+      for (var key in source) {
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+          target[key] = source[key];
+        }
+      }
+    }
+    return target;
+  };
+  return _extends.apply(this, arguments);
 }
-function validateUSDQuantity(value) {
-  if (!isValidUSDQuantity(value)) {
-    throw new Error(`Invalid USD quantity: ${value}.`);
+var CAIP2 = {
+  name: "chainId",
+  regex: "[-:a-zA-Z0-9]{5,41}",
+  parameters: {
+    delimiter: ":",
+    values: {
+      0: {
+        name: "namespace",
+        regex: "[-a-z0-9]{3,8}"
+      },
+      1: {
+        name: "reference",
+        regex: "[-a-zA-Z0-9]{1,32}"
+      }
+    }
+  }
+};
+var CAIP10 = {
+  name: "accountId",
+  regex: "[-:a-zA-Z0-9]{7,106}",
+  parameters: {
+    delimiter: ":",
+    values: {
+      0: {
+        name: "namespace",
+        regex: "[-a-z0-9]{3,8}"
+      },
+      1: {
+        name: "reference",
+        regex: "[-a-zA-Z0-9]{1,32}"
+      },
+      2: {
+        name: "address",
+        regex: "[a-zA-Z0-9]{1,64}"
+      }
+    }
+  }
+};
+var AssetName$1 = {
+  name: "assetName",
+  regex: "[-:a-zA-Z0-9]{5,73}",
+  parameters: {
+    delimiter: ":",
+    values: {
+      0: {
+        name: "namespace",
+        regex: "[-a-z0-9]{3,8}"
+      },
+      1: {
+        name: "reference",
+        regex: "[-a-zA-Z0-9]{1,64}"
+      }
+    }
+  }
+};
+var CAIP19AssetType = {
+  name: "assetType",
+  regex: "[-:a-zA-Z0-9]{11,115}",
+  parameters: {
+    delimiter: "/",
+    values: {
+      0: CAIP2,
+      1: AssetName$1
+    }
+  }
+};
+var CAIP19AssetId = {
+  name: "assetId",
+  regex: "[-:a-zA-Z0-9]{13,148}",
+  parameters: {
+    delimiter: "/",
+    values: {
+      0: CAIP2,
+      1: AssetName$1,
+      2: {
+        name: "tokenId",
+        regex: "[-a-zA-Z0-9]{1,32}"
+      }
+    }
+  }
+};
+var CAIP = {
+  "2": CAIP2,
+  "10": CAIP10,
+  "19": {
+    assetName: AssetName$1,
+    assetType: CAIP19AssetType,
+    assetId: CAIP19AssetId
+  }
+};
+function splitParams(id, spec) {
+  return id.split(spec.parameters.delimiter);
+}
+function getParams(id, spec) {
+  var arr = splitParams(id, spec);
+  var params = {};
+  arr.forEach(function(value, index) {
+    params[spec.parameters.values[index].name] = value;
+  });
+  return params;
+}
+function joinParams(params, spec) {
+  return Object.values(spec.parameters.values).map(function(parameter) {
+    var param = params[parameter.name];
+    return typeof param === "string" ? param : joinParams(param, parameter);
+  }).join(spec.parameters.delimiter);
+}
+function isValidId(id, spec) {
+  if (!new RegExp(spec.regex).test(id)) return false;
+  var params = splitParams(id, spec);
+  if (params.length !== Object.keys(spec.parameters.values).length) return false;
+  var matches = params.map(function(param, index) {
+    return new RegExp(spec.parameters.values[index].regex).test(param);
+  }).filter(function(x) {
+    return !!x;
+  });
+  if (matches.length !== params.length) return false;
+  return true;
+}
+var ChainId = /* @__PURE__ */ (function() {
+  function ChainId2(params) {
+    if (typeof params === "string") {
+      params = ChainId2.parse(params);
+    }
+    this.namespace = params.namespace;
+    this.reference = params.reference;
+  }
+  ChainId2.parse = function parse(id) {
+    if (!isValidId(id, this.spec)) {
+      throw new Error("Invalid " + this.spec.name + " provided: " + id);
+    }
+    return new ChainId2(getParams(id, this.spec)).toJSON();
+  };
+  ChainId2.format = function format(params) {
+    return joinParams(params, this.spec);
+  };
+  var _proto = ChainId2.prototype;
+  _proto.toString = function toString() {
+    return ChainId2.format(this.toJSON());
+  };
+  _proto.toJSON = function toJSON() {
+    return {
+      namespace: this.namespace,
+      reference: this.reference
+    };
+  };
+  return ChainId2;
+})();
+ChainId.spec = CAIP["2"];
+var AccountId = /* @__PURE__ */ (function() {
+  function AccountId2(params) {
+    if (typeof params === "string") {
+      params = AccountId2.parse(params);
+    }
+    this.chainId = new ChainId(params.chainId);
+    this.address = params.address;
+  }
+  AccountId2.parse = function parse(id) {
+    if (!isValidId(id, this.spec)) {
+      throw new Error("Invalid " + this.spec.name + " provided: " + id);
+    }
+    var _getParams = getParams(id, this.spec), namespace = _getParams.namespace, reference = _getParams.reference, address = _getParams.address;
+    var chainId = new ChainId({
+      namespace,
+      reference
+    });
+    return new AccountId2({
+      chainId,
+      address
+    }).toJSON();
+  };
+  AccountId2.format = function format(params) {
+    var chainId = new ChainId(params.chainId);
+    var splitParams2 = _extends({}, chainId.toJSON(), {
+      address: params.address
+    });
+    return joinParams(splitParams2, this.spec);
+  };
+  var _proto = AccountId2.prototype;
+  _proto.toString = function toString() {
+    return AccountId2.format(this.toJSON());
+  };
+  _proto.toJSON = function toJSON() {
+    return {
+      chainId: this.chainId.toJSON(),
+      address: this.address
+    };
+  };
+  return AccountId2;
+})();
+AccountId.spec = CAIP["10"];
+var AssetName = /* @__PURE__ */ (function() {
+  function AssetName2(params) {
+    if (typeof params === "string") {
+      params = AssetName2.parse(params);
+    }
+    this.namespace = params.namespace;
+    this.reference = params.reference;
+  }
+  AssetName2.parse = function parse(id) {
+    if (!isValidId(id, this.spec)) {
+      throw new Error("Invalid " + this.spec.name + " provided: " + id);
+    }
+    return new AssetName2(getParams(id, this.spec)).toJSON();
+  };
+  AssetName2.format = function format(params) {
+    return joinParams(params, this.spec);
+  };
+  var _proto = AssetName2.prototype;
+  _proto.toString = function toString() {
+    return AssetName2.format(this.toJSON());
+  };
+  _proto.toJSON = function toJSON() {
+    return {
+      namespace: this.namespace,
+      reference: this.reference
+    };
+  };
+  return AssetName2;
+})();
+AssetName.spec = CAIP["19"].assetName;
+var AssetType = /* @__PURE__ */ (function() {
+  function AssetType2(params) {
+    if (typeof params === "string") {
+      params = AssetType2.parse(params);
+    }
+    this.chainId = new ChainId(params.chainId);
+    this.assetName = new AssetName(params.assetName);
+  }
+  AssetType2.parse = function parse(id) {
+    if (!isValidId(id, this.spec)) {
+      throw new Error("Invalid " + this.spec.name + " provided: " + id);
+    }
+    return new AssetType2(getParams(id, this.spec)).toJSON();
+  };
+  AssetType2.format = function format(params) {
+    return joinParams(params, this.spec);
+  };
+  var _proto = AssetType2.prototype;
+  _proto.toString = function toString() {
+    return AssetType2.format(this.toJSON());
+  };
+  _proto.toJSON = function toJSON() {
+    return {
+      chainId: this.chainId.toJSON(),
+      assetName: this.assetName
+    };
+  };
+  return AssetType2;
+})();
+AssetType.spec = CAIP["19"].assetType;
+var AssetId = /* @__PURE__ */ (function() {
+  function AssetId2(params) {
+    if (typeof params === "string") {
+      params = AssetId2.parse(params);
+    }
+    this.chainId = new ChainId(params.chainId);
+    this.assetName = new AssetName(params.assetName);
+    this.tokenId = params.tokenId;
   }
+  AssetId2.parse = function parse(id) {
+    if (!isValidId(id, this.spec)) {
+      throw new Error("Invalid " + this.spec.name + " provided: " + id);
+    }
+    return new AssetId2(getParams(id, this.spec)).toJSON();
+  };
+  AssetId2.format = function format(params) {
+    return joinParams(params, this.spec);
+  };
+  var _proto = AssetId2.prototype;
+  _proto.toString = function toString() {
+    return AssetId2.format(this.toJSON());
+  };
+  _proto.toJSON = function toJSON() {
+    return {
+      chainId: this.chainId.toJSON(),
+      assetName: this.assetName.toJSON(),
+      tokenId: this.tokenId
+    };
+  };
+  return AssetId2;
+})();
+AssetId.spec = CAIP["19"].assetId;
+
+// ../ensnode-sdk/src/shared/zod-schemas.ts
+import { isAddress as isAddress2, isHex, size } from "viem";
+import { z } from "zod/v4";
+
+// ../ensnode-sdk/src/shared/address.ts
+function asLowerCaseAddress(address) {
+  return address.toLowerCase();
 }
 
-// src/encoding.ts
-import { getAddress, pad, size, slice, zeroAddress } from "viem";
-var ENCODED_REFERRER_BYTE_OFFSET = 12;
-var ENCODED_REFERRER_BYTE_LENGTH = 32;
-var EXPECTED_ENCODED_REFERRER_PADDING = pad("0x", {
-  size: ENCODED_REFERRER_BYTE_OFFSET,
-  dir: "left"
+// ../ensnode-sdk/src/shared/zod-schemas.ts
+var makeFiniteNonNegativeNumberSchema = (valueLabel = "Value") => z.number({
+  // NOTE: Zod's implementation of `number` automatically rejects NaN and Infinity values.
+  // and therefore the finite check is implicit.
+  error: `${valueLabel} must be a finite number.`
+}).nonnegative({
+  error: `${valueLabel} must be a non-negative number (>=0).`
 });
-var ZERO_ENCODED_REFERRER = pad("0x", {
-  size: ENCODED_REFERRER_BYTE_LENGTH,
-  dir: "left"
+var makeIntegerSchema = (valueLabel = "Value") => z.int({
+  error: `${valueLabel} must be an integer.`
 });
-function buildEncodedReferrer(address) {
-  const lowercaseAddress = address.toLowerCase();
-  return pad(lowercaseAddress, { size: ENCODED_REFERRER_BYTE_LENGTH, dir: "left" });
-}
-function decodeEncodedReferrer(encodedReferrer) {
-  if (size(encodedReferrer) !== ENCODED_REFERRER_BYTE_LENGTH) {
+var makePositiveIntegerSchema = (valueLabel = "Value") => makeIntegerSchema(valueLabel).positive({
+  error: `${valueLabel} must be a positive integer (>0).`
+});
+var makeNonNegativeIntegerSchema = (valueLabel = "Value") => makeIntegerSchema(valueLabel).nonnegative({
+  error: `${valueLabel} must be a non-negative integer (>=0).`
+});
+var makeDurationSchema = (valueLabel = "Value") => z.number({
+  error: `${valueLabel} must be a number.`
+}).pipe(makeNonNegativeIntegerSchema(valueLabel));
+var makeChainIdSchema = (valueLabel = "Chain ID") => makePositiveIntegerSchema(valueLabel).transform((val) => val);
+var makeLowercaseAddressSchema = (valueLabel = "EVM address") => z.string().check((ctx) => {
+  if (!isAddress2(ctx.value)) {
+    ctx.issues.push({
+      code: "custom",
+      message: `${valueLabel} must be a valid EVM address`,
+      input: ctx.value
+    });
+  }
+}).transform((val) => asLowerCaseAddress(val));
+var makeUnixTimestampSchema = (valueLabel = "Timestamp") => makeIntegerSchema(valueLabel);
+var makeAccountIdSchema = (valueLabel = "AccountId") => z.strictObject({
+  chainId: makeChainIdSchema(`${valueLabel} chain ID`),
+  address: makeLowercaseAddressSchema(`${valueLabel} address`)
+});
+
+// src/leaderboard-page.ts
+var REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT = 25;
+var REFERRERS_PER_LEADERBOARD_PAGE_MAX = 100;
+var validateReferrerLeaderboardPageParams = (params) => {
+  if (params.page !== void 0 && !isPositiveInteger(params.page)) {
     throw new Error(
-      `Encoded referrer value must be represented by ${ENCODED_REFERRER_BYTE_LENGTH} bytes.`
+      `Invalid ReferrerLeaderboardPageParams: ${params.page}. page must be a positive integer.`
     );
   }
-  const padding = slice(encodedReferrer, 0, ENCODED_REFERRER_BYTE_OFFSET);
-  if (padding !== EXPECTED_ENCODED_REFERRER_PADDING) {
-    return zeroAddress;
+  if (params.recordsPerPage !== void 0 && !isPositiveInteger(params.recordsPerPage)) {
+    throw new Error(
+      `Invalid ReferrerLeaderboardPageParams: ${params.recordsPerPage}. recordsPerPage must be a positive integer.`
+    );
   }
-  const decodedReferrer = slice(encodedReferrer, ENCODED_REFERRER_BYTE_OFFSET);
-  try {
-    return getAddress(decodedReferrer);
-  } catch {
-    throw new Error(`Decoded referrer value must be a valid EVM address.`);
+  if (params.recordsPerPage !== void 0 && params.recordsPerPage > REFERRERS_PER_LEADERBOARD_PAGE_MAX) {
+    throw new Error(
+      `Invalid ReferrerLeaderboardPageParams: ${params.recordsPerPage}. recordsPerPage must be less than or equal to ${REFERRERS_PER_LEADERBOARD_PAGE_MAX}.`
+    );
   }
-}
+};
+var buildReferrerLeaderboardPageParams = (params) => {
+  const result = {
+    page: params.page ?? 1,
+    recordsPerPage: params.recordsPerPage ?? REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT
+  };
+  validateReferrerLeaderboardPageParams(result);
+  return result;
+};
+var validateReferrerLeaderboardPageContext = (context) => {
+  validateReferrerLeaderboardPageParams(context);
+  if (!isNonNegativeInteger(context.totalRecords)) {
+    throw new Error(
+      `Invalid ReferrerLeaderboardPageContext: total must be a non-negative integer but is ${context.totalRecords}.`
+    );
+  }
+  const startIndex = (context.page - 1) * context.recordsPerPage;
+  const endIndex = startIndex + context.recordsPerPage;
+  if (!context.hasNext && endIndex < context.totalRecords) {
+    throw new Error(
+      `Invalid ReferrerLeaderboardPageContext: if hasNext is false, endIndex (${endIndex}) must be greater than or equal to total (${context.totalRecords}).`
+    );
+  } else if (context.hasNext && context.page * context.recordsPerPage >= context.totalRecords) {
+    throw new Error(
+      `Invalid ReferrerLeaderboardPageContext: if hasNext is true, endIndex (${endIndex}) must be less than total (${context.totalRecords}).`
+    );
+  }
+  if (!context.hasPrev && context.page !== 1) {
+    throw new Error(
+      `Invalid ReferrerLeaderboardPageContext: if hasPrev is false, page must be the first page (1) but is ${context.page}.`
+    );
+  } else if (context.hasPrev && context.page === 1) {
+    throw new Error(
+      `Invalid ReferrerLeaderboardPageContext: if hasPrev is true, page must not be the first page (1) but is ${context.page}.`
+    );
+  }
+};
+var buildReferrerLeaderboardPageContext = (optionalParams, leaderboard) => {
+  const materializedParams = buildReferrerLeaderboardPageParams(optionalParams);
+  const totalRecords = leaderboard.referrers.size;
+  const totalPages = Math.max(1, Math.ceil(totalRecords / materializedParams.recordsPerPage));
+  if (materializedParams.page > totalPages) {
+    throw new Error(
+      `Invalid ReferrerLeaderboardPageContext: page ${materializedParams.page} exceeds total pages ${totalPages}.`
+    );
+  }
+  if (totalRecords === 0) {
+    return {
+      ...materializedParams,
+      totalRecords: 0,
+      totalPages: 1,
+      hasNext: false,
+      hasPrev: false,
+      startIndex: void 0,
+      endIndex: void 0
+    };
+  }
+  const startIndex = (materializedParams.page - 1) * materializedParams.recordsPerPage;
+  const maxTheoreticalIndexOnPage = startIndex + (materializedParams.recordsPerPage - 1);
+  const endIndex = Math.min(maxTheoreticalIndexOnPage, totalRecords - 1);
+  const hasNext = maxTheoreticalIndexOnPage < totalRecords - 1;
+  const hasPrev = materializedParams.page > 1;
+  const result = {
+    ...materializedParams,
+    totalRecords,
+    totalPages,
+    hasNext,
+    hasPrev,
+    startIndex,
+    endIndex
+  };
+  validateReferrerLeaderboardPageContext(result);
+  return result;
+};
+var getReferrerLeaderboardPage = (pageParams, leaderboard) => {
+  const pageContext = buildReferrerLeaderboardPageContext(pageParams, leaderboard);
+  let referrers;
+  if (pageContext.totalRecords > 0 && typeof pageContext.startIndex !== "undefined" && typeof pageContext.endIndex !== "undefined") {
+    referrers = Array.from(leaderboard.referrers.values()).slice(
+      pageContext.startIndex,
+      pageContext.endIndex + 1
+      // For `slice`, this is exclusive of the element at the index 'end'. We need it to be inclusive, hence plus one.
+    );
+  } else {
+    referrers = [];
+  }
+  return {
+    rules: leaderboard.rules,
+    referrers,
+    aggregatedMetrics: leaderboard.aggregatedMetrics,
+    pageContext,
+    accurateAsOf: leaderboard.accurateAsOf
+  };
+};
 
 // src/rank.ts
 var validateReferrerRank = (rank) => {
@@ -366,6 +786,624 @@ var buildUnrankedReferrerMetrics = (referrer) => {
   return result;
 };
 
+// src/referrer-detail.ts
+var ReferrerDetailTypeIds = {
+  /**
+   * Represents a referrer who is ranked on the leaderboard.
+   */
+  Ranked: "ranked",
+  /**
+   * Represents a referrer who is not ranked on the leaderboard.
+   */
+  Unranked: "unranked"
+};
+var getReferrerDetail = (referrer, leaderboard) => {
+  const awardedReferrerMetrics = leaderboard.referrers.get(referrer);
+  if (awardedReferrerMetrics) {
+    return {
+      type: ReferrerDetailTypeIds.Ranked,
+      rules: leaderboard.rules,
+      referrer: awardedReferrerMetrics,
+      aggregatedMetrics: leaderboard.aggregatedMetrics,
+      accurateAsOf: leaderboard.accurateAsOf
+    };
+  }
+  return {
+    type: ReferrerDetailTypeIds.Unranked,
+    rules: leaderboard.rules,
+    referrer: buildUnrankedReferrerMetrics(referrer),
+    aggregatedMetrics: leaderboard.aggregatedMetrics,
+    accurateAsOf: leaderboard.accurateAsOf
+  };
+};
+
+// src/api/types.ts
+var ReferrerLeaderboardPageResponseCodes = {
+  /**
+   * Represents that the requested referrer leaderboard page is available.
+   */
+  Ok: "ok",
+  /**
+   * Represents that the referrer leaderboard data is not available.
+   */
+  Error: "error"
+};
+var ReferrerDetailResponseCodes = {
+  /**
+   * Represents that the referrer detail data is available.
+   */
+  Ok: "ok",
+  /**
+   * Represents that an error occurred while fetching the data.
+   */
+  Error: "error"
+};
+
+// src/api/zod-schemas.ts
+var makeRevenueContributionSchema = (valueLabel = "RevenueContribution") => z2.coerce.bigint({
+  error: `${valueLabel} must represent a bigint.`
+}).nonnegative({
+  error: `${valueLabel} must not be negative.`
+});
+var makeReferralProgramRulesSchema = (valueLabel = "ReferralProgramRules") => z2.object({
+  totalAwardPoolValue: makeFiniteNonNegativeNumberSchema(`${valueLabel}.totalAwardPoolValue`),
+  maxQualifiedReferrers: makeNonNegativeIntegerSchema(`${valueLabel}.maxQualifiedReferrers`),
+  startTime: makeUnixTimestampSchema(`${valueLabel}.startTime`),
+  endTime: makeUnixTimestampSchema(`${valueLabel}.endTime`),
+  subregistryId: makeAccountIdSchema(`${valueLabel}.subregistryId`)
+});
+var makeAwardedReferrerMetricsSchema = (valueLabel = "AwardedReferrerMetrics") => z2.object({
+  referrer: makeLowercaseAddressSchema(`${valueLabel}.referrer`),
+  totalReferrals: makeNonNegativeIntegerSchema(`${valueLabel}.totalReferrals`),
+  totalIncrementalDuration: makeDurationSchema(`${valueLabel}.totalIncrementalDuration`),
+  totalRevenueContribution: makeRevenueContributionSchema(
+    `${valueLabel}.totalRevenueContribution`
+  ),
+  score: makeFiniteNonNegativeNumberSchema(`${valueLabel}.score`),
+  rank: makePositiveIntegerSchema(`${valueLabel}.rank`),
+  isQualified: z2.boolean(),
+  finalScoreBoost: makeFiniteNonNegativeNumberSchema(`${valueLabel}.finalScoreBoost`).max(
+    1,
+    `${valueLabel}.finalScoreBoost must be <= 1`
+  ),
+  finalScore: makeFiniteNonNegativeNumberSchema(`${valueLabel}.finalScore`),
+  awardPoolShare: makeFiniteNonNegativeNumberSchema(`${valueLabel}.awardPoolShare`).max(
+    1,
+    `${valueLabel}.awardPoolShare must be <= 1`
+  ),
+  awardPoolApproxValue: makeFiniteNonNegativeNumberSchema(`${valueLabel}.awardPoolApproxValue`)
+});
+var makeUnrankedReferrerMetricsSchema = (valueLabel = "UnrankedReferrerMetrics") => z2.object({
+  referrer: makeLowercaseAddressSchema(`${valueLabel}.referrer`),
+  totalReferrals: makeNonNegativeIntegerSchema(`${valueLabel}.totalReferrals`),
+  totalIncrementalDuration: makeDurationSchema(`${valueLabel}.totalIncrementalDuration`),
+  totalRevenueContribution: makeRevenueContributionSchema(
+    `${valueLabel}.totalRevenueContribution`
+  ),
+  score: makeFiniteNonNegativeNumberSchema(`${valueLabel}.score`),
+  rank: z2.null(),
+  isQualified: z2.literal(false),
+  finalScoreBoost: makeFiniteNonNegativeNumberSchema(`${valueLabel}.finalScoreBoost`).max(
+    1,
+    `${valueLabel}.finalScoreBoost must be <= 1`
+  ),
+  finalScore: makeFiniteNonNegativeNumberSchema(`${valueLabel}.finalScore`),
+  awardPoolShare: makeFiniteNonNegativeNumberSchema(`${valueLabel}.awardPoolShare`).max(
+    1,
+    `${valueLabel}.awardPoolShare must be <= 1`
+  ),
+  awardPoolApproxValue: makeFiniteNonNegativeNumberSchema(`${valueLabel}.awardPoolApproxValue`)
+});
+var makeAggregatedReferrerMetricsSchema = (valueLabel = "AggregatedReferrerMetrics") => z2.object({
+  grandTotalReferrals: makeNonNegativeIntegerSchema(`${valueLabel}.grandTotalReferrals`),
+  grandTotalIncrementalDuration: makeDurationSchema(
+    `${valueLabel}.grandTotalIncrementalDuration`
+  ),
+  grandTotalRevenueContribution: makeRevenueContributionSchema(
+    `${valueLabel}.grandTotalRevenueContribution`
+  ),
+  grandTotalQualifiedReferrersFinalScore: makeFiniteNonNegativeNumberSchema(
+    `${valueLabel}.grandTotalQualifiedReferrersFinalScore`
+  ),
+  minFinalScoreToQualify: makeFiniteNonNegativeNumberSchema(
+    `${valueLabel}.minFinalScoreToQualify`
+  )
+});
+var makeReferrerLeaderboardPageContextSchema = (valueLabel = "ReferrerLeaderboardPageContext") => z2.object({
+  page: makePositiveIntegerSchema(`${valueLabel}.page`),
+  recordsPerPage: makePositiveIntegerSchema(`${valueLabel}.recordsPerPage`).max(
+    REFERRERS_PER_LEADERBOARD_PAGE_MAX,
+    `${valueLabel}.recordsPerPage must not exceed ${REFERRERS_PER_LEADERBOARD_PAGE_MAX}`
+  ),
+  totalRecords: makeNonNegativeIntegerSchema(`${valueLabel}.totalRecords`),
+  totalPages: makePositiveIntegerSchema(`${valueLabel}.totalPages`),
+  hasNext: z2.boolean(),
+  hasPrev: z2.boolean(),
+  startIndex: z2.optional(makeNonNegativeIntegerSchema(`${valueLabel}.startIndex`)),
+  endIndex: z2.optional(makeNonNegativeIntegerSchema(`${valueLabel}.endIndex`))
+});
+var makeReferrerLeaderboardPageSchema = (valueLabel = "ReferrerLeaderboardPage") => z2.object({
+  rules: makeReferralProgramRulesSchema(`${valueLabel}.rules`),
+  referrers: z2.array(makeAwardedReferrerMetricsSchema(`${valueLabel}.referrers[record]`)),
+  aggregatedMetrics: makeAggregatedReferrerMetricsSchema(`${valueLabel}.aggregatedMetrics`),
+  pageContext: makeReferrerLeaderboardPageContextSchema(`${valueLabel}.pageContext`),
+  accurateAsOf: makeUnixTimestampSchema(`${valueLabel}.accurateAsOf`)
+});
+var makeReferrerLeaderboardPageResponseOkSchema = (valueLabel = "ReferrerLeaderboardPageResponseOk") => z2.object({
+  responseCode: z2.literal(ReferrerLeaderboardPageResponseCodes.Ok),
+  data: makeReferrerLeaderboardPageSchema(`${valueLabel}.data`)
+});
+var makeReferrerLeaderboardPageResponseErrorSchema = (_valueLabel = "ReferrerLeaderboardPageResponseError") => z2.object({
+  responseCode: z2.literal(ReferrerLeaderboardPageResponseCodes.Error),
+  error: z2.string(),
+  errorMessage: z2.string()
+});
+var makeReferrerLeaderboardPageResponseSchema = (valueLabel = "ReferrerLeaderboardPageResponse") => z2.union([
+  makeReferrerLeaderboardPageResponseOkSchema(valueLabel),
+  makeReferrerLeaderboardPageResponseErrorSchema(valueLabel)
+]);
+var makeReferrerDetailRankedSchema = (valueLabel = "ReferrerDetailRanked") => z2.object({
+  type: z2.literal(ReferrerDetailTypeIds.Ranked),
+  rules: makeReferralProgramRulesSchema(`${valueLabel}.rules`),
+  referrer: makeAwardedReferrerMetricsSchema(`${valueLabel}.referrer`),
+  aggregatedMetrics: makeAggregatedReferrerMetricsSchema(`${valueLabel}.aggregatedMetrics`),
+  accurateAsOf: makeUnixTimestampSchema(`${valueLabel}.accurateAsOf`)
+});
+var makeReferrerDetailUnrankedSchema = (valueLabel = "ReferrerDetailUnranked") => z2.object({
+  type: z2.literal(ReferrerDetailTypeIds.Unranked),
+  rules: makeReferralProgramRulesSchema(`${valueLabel}.rules`),
+  referrer: makeUnrankedReferrerMetricsSchema(`${valueLabel}.referrer`),
+  aggregatedMetrics: makeAggregatedReferrerMetricsSchema(`${valueLabel}.aggregatedMetrics`),
+  accurateAsOf: makeUnixTimestampSchema(`${valueLabel}.accurateAsOf`)
+});
+var makeReferrerDetailResponseOkSchema = (valueLabel = "ReferrerDetailResponse") => z2.object({
+  responseCode: z2.literal(ReferrerDetailResponseCodes.Ok),
+  data: z2.union([
+    makeReferrerDetailRankedSchema(`${valueLabel}.data`),
+    makeReferrerDetailUnrankedSchema(`${valueLabel}.data`)
+  ])
+});
+var makeReferrerDetailResponseErrorSchema = (_valueLabel = "ReferrerDetailResponse") => z2.object({
+  responseCode: z2.literal(ReferrerDetailResponseCodes.Error),
+  error: z2.string(),
+  errorMessage: z2.string()
+});
+var makeReferrerDetailResponseSchema = (valueLabel = "ReferrerDetailResponse") => z2.union([
+  makeReferrerDetailResponseOkSchema(valueLabel),
+  makeReferrerDetailResponseErrorSchema(valueLabel)
+]);
+
+// src/api/deserialize.ts
+function deserializeRevenueContribution(value) {
+  return BigInt(value);
+}
+function deserializeReferralProgramRules(rules) {
+  return rules;
+}
+function deserializeAwardedReferrerMetrics(metrics) {
+  return {
+    referrer: metrics.referrer,
+    totalReferrals: metrics.totalReferrals,
+    totalIncrementalDuration: metrics.totalIncrementalDuration,
+    totalRevenueContribution: deserializeRevenueContribution(metrics.totalRevenueContribution),
+    score: metrics.score,
+    rank: metrics.rank,
+    isQualified: metrics.isQualified,
+    finalScoreBoost: metrics.finalScoreBoost,
+    finalScore: metrics.finalScore,
+    awardPoolShare: metrics.awardPoolShare,
+    awardPoolApproxValue: metrics.awardPoolApproxValue
+  };
+}
+function deserializeUnrankedReferrerMetrics(metrics) {
+  return {
+    referrer: metrics.referrer,
+    totalReferrals: metrics.totalReferrals,
+    totalIncrementalDuration: metrics.totalIncrementalDuration,
+    totalRevenueContribution: deserializeRevenueContribution(metrics.totalRevenueContribution),
+    score: metrics.score,
+    rank: metrics.rank,
+    isQualified: metrics.isQualified,
+    finalScoreBoost: metrics.finalScoreBoost,
+    finalScore: metrics.finalScore,
+    awardPoolShare: metrics.awardPoolShare,
+    awardPoolApproxValue: metrics.awardPoolApproxValue
+  };
+}
+function deserializeAggregatedReferrerMetrics(metrics) {
+  return {
+    grandTotalReferrals: metrics.grandTotalReferrals,
+    grandTotalIncrementalDuration: metrics.grandTotalIncrementalDuration,
+    grandTotalRevenueContribution: deserializeRevenueContribution(
+      metrics.grandTotalRevenueContribution
+    ),
+    grandTotalQualifiedReferrersFinalScore: metrics.grandTotalQualifiedReferrersFinalScore,
+    minFinalScoreToQualify: metrics.minFinalScoreToQualify
+  };
+}
+function deserializeReferrerLeaderboardPage(page) {
+  return {
+    rules: deserializeReferralProgramRules(page.rules),
+    referrers: page.referrers.map(deserializeAwardedReferrerMetrics),
+    aggregatedMetrics: deserializeAggregatedReferrerMetrics(page.aggregatedMetrics),
+    pageContext: page.pageContext,
+    accurateAsOf: page.accurateAsOf
+  };
+}
+function deserializeReferrerDetailRanked(detail) {
+  return {
+    type: detail.type,
+    rules: deserializeReferralProgramRules(detail.rules),
+    referrer: deserializeAwardedReferrerMetrics(detail.referrer),
+    aggregatedMetrics: deserializeAggregatedReferrerMetrics(detail.aggregatedMetrics),
+    accurateAsOf: detail.accurateAsOf
+  };
+}
+function deserializeReferrerDetailUnranked(detail) {
+  return {
+    type: detail.type,
+    rules: deserializeReferralProgramRules(detail.rules),
+    referrer: deserializeUnrankedReferrerMetrics(detail.referrer),
+    aggregatedMetrics: deserializeAggregatedReferrerMetrics(detail.aggregatedMetrics),
+    accurateAsOf: detail.accurateAsOf
+  };
+}
+function deserializeReferrerLeaderboardPageResponse(maybeResponse, valueLabel) {
+  let deserialized;
+  switch (maybeResponse.responseCode) {
+    case "ok": {
+      deserialized = {
+        responseCode: maybeResponse.responseCode,
+        data: deserializeReferrerLeaderboardPage(maybeResponse.data)
+      };
+      break;
+    }
+    case "error":
+      deserialized = maybeResponse;
+      break;
+  }
+  const schema = makeReferrerLeaderboardPageResponseSchema(valueLabel);
+  const parsed = schema.safeParse(deserialized);
+  if (parsed.error) {
+    throw new Error(
+      `Cannot deserialize SerializedReferrerLeaderboardPageResponse:
+${prettifyError(parsed.error)}
+`
+    );
+  }
+  return parsed.data;
+}
+function deserializeReferrerDetailResponse(maybeResponse, valueLabel) {
+  let deserialized;
+  switch (maybeResponse.responseCode) {
+    case "ok": {
+      switch (maybeResponse.data.type) {
+        case "ranked":
+          deserialized = {
+            responseCode: maybeResponse.responseCode,
+            data: deserializeReferrerDetailRanked(maybeResponse.data)
+          };
+          break;
+        case "unranked":
+          deserialized = {
+            responseCode: maybeResponse.responseCode,
+            data: deserializeReferrerDetailUnranked(maybeResponse.data)
+          };
+          break;
+      }
+      break;
+    }
+    case "error":
+      deserialized = maybeResponse;
+      break;
+  }
+  const schema = makeReferrerDetailResponseSchema(valueLabel);
+  const parsed = schema.safeParse(deserialized);
+  if (parsed.error) {
+    throw new Error(`Cannot deserialize ReferrerDetailResponse:
+${prettifyError(parsed.error)}
+`);
+  }
+  return parsed.data;
+}
+
+// src/api/serialize.ts
+function serializeRevenueContribution(revenueContribution) {
+  return revenueContribution.toString();
+}
+function serializeReferralProgramRules(rules) {
+  return rules;
+}
+function serializeAwardedReferrerMetrics(metrics) {
+  return {
+    referrer: metrics.referrer,
+    totalReferrals: metrics.totalReferrals,
+    totalIncrementalDuration: metrics.totalIncrementalDuration,
+    totalRevenueContribution: serializeRevenueContribution(metrics.totalRevenueContribution),
+    score: metrics.score,
+    rank: metrics.rank,
+    isQualified: metrics.isQualified,
+    finalScoreBoost: metrics.finalScoreBoost,
+    finalScore: metrics.finalScore,
+    awardPoolShare: metrics.awardPoolShare,
+    awardPoolApproxValue: metrics.awardPoolApproxValue
+  };
+}
+function serializeUnrankedReferrerMetrics(metrics) {
+  return {
+    referrer: metrics.referrer,
+    totalReferrals: metrics.totalReferrals,
+    totalIncrementalDuration: metrics.totalIncrementalDuration,
+    totalRevenueContribution: serializeRevenueContribution(metrics.totalRevenueContribution),
+    score: metrics.score,
+    rank: metrics.rank,
+    isQualified: metrics.isQualified,
+    finalScoreBoost: metrics.finalScoreBoost,
+    finalScore: metrics.finalScore,
+    awardPoolShare: metrics.awardPoolShare,
+    awardPoolApproxValue: metrics.awardPoolApproxValue
+  };
+}
+function serializeAggregatedReferrerMetrics(metrics) {
+  return {
+    grandTotalReferrals: metrics.grandTotalReferrals,
+    grandTotalIncrementalDuration: metrics.grandTotalIncrementalDuration,
+    grandTotalRevenueContribution: serializeRevenueContribution(
+      metrics.grandTotalRevenueContribution
+    ),
+    grandTotalQualifiedReferrersFinalScore: metrics.grandTotalQualifiedReferrersFinalScore,
+    minFinalScoreToQualify: metrics.minFinalScoreToQualify
+  };
+}
+function serializeReferrerLeaderboardPage(page) {
+  return {
+    rules: serializeReferralProgramRules(page.rules),
+    referrers: page.referrers.map(serializeAwardedReferrerMetrics),
+    aggregatedMetrics: serializeAggregatedReferrerMetrics(page.aggregatedMetrics),
+    pageContext: page.pageContext,
+    accurateAsOf: page.accurateAsOf
+  };
+}
+function serializeReferrerDetailRanked(detail) {
+  return {
+    type: detail.type,
+    rules: serializeReferralProgramRules(detail.rules),
+    referrer: serializeAwardedReferrerMetrics(detail.referrer),
+    aggregatedMetrics: serializeAggregatedReferrerMetrics(detail.aggregatedMetrics),
+    accurateAsOf: detail.accurateAsOf
+  };
+}
+function serializeReferrerDetailUnranked(detail) {
+  return {
+    type: detail.type,
+    rules: serializeReferralProgramRules(detail.rules),
+    referrer: serializeUnrankedReferrerMetrics(detail.referrer),
+    aggregatedMetrics: serializeAggregatedReferrerMetrics(detail.aggregatedMetrics),
+    accurateAsOf: detail.accurateAsOf
+  };
+}
+function serializeReferrerLeaderboardPageResponse(response) {
+  switch (response.responseCode) {
+    case ReferrerLeaderboardPageResponseCodes.Ok:
+      return {
+        responseCode: response.responseCode,
+        data: serializeReferrerLeaderboardPage(response.data)
+      };
+    case ReferrerLeaderboardPageResponseCodes.Error:
+      return response;
+  }
+}
+function serializeReferrerDetailResponse(response) {
+  switch (response.responseCode) {
+    case ReferrerDetailResponseCodes.Ok:
+      switch (response.data.type) {
+        case "ranked":
+          return {
+            responseCode: response.responseCode,
+            data: serializeReferrerDetailRanked(response.data)
+          };
+        case "unranked":
+          return {
+            responseCode: response.responseCode,
+            data: serializeReferrerDetailUnranked(response.data)
+          };
+      }
+      break;
+    case ReferrerDetailResponseCodes.Error:
+      return response;
+  }
+}
+
+// src/client.ts
+var DEFAULT_ENSNODE_API_URL = "https://api.alpha.ensnode.io";
+var ENSReferralsClient = class _ENSReferralsClient {
+  options;
+  static defaultOptions() {
+    return {
+      url: new URL(DEFAULT_ENSNODE_API_URL)
+    };
+  }
+  constructor(options = {}) {
+    this.options = {
+      ..._ENSReferralsClient.defaultOptions(),
+      ...options
+    };
+  }
+  getOptions() {
+    return Object.freeze({
+      url: new URL(this.options.url.href)
+    });
+  }
+  /**
+   * Fetch Referrer Leaderboard Page
+   *
+   * Retrieves a paginated list of referrer leaderboard metrics with contribution percentages.
+   * Each referrer's contribution is calculated as a percentage of the grand totals across all referrers.
+   *
+   * @param request - Pagination parameters
+   * @param request.page - The page number to retrieve (1-indexed, default: 1)
+   * @param request.recordsPerPage - Number of records per page (default: 25, max: 100)
+   * @returns {ReferrerLeaderboardPageResponse}
+   *
+   * @throws if the ENSNode request fails
+   * @throws if the ENSNode API returns an error response
+   * @throws if the ENSNode response breaks required invariants
+   *
+   * @example
+   * ```typescript
+   * // Get first page with default page size (25 records)
+   * const response = await client.getReferrerLeaderboardPage();
+   * if (response.responseCode === ReferrerLeaderboardPageResponseCodes.Ok) {
+   *   const {
+   *     aggregatedMetrics,
+   *     referrers,
+   *     rules,
+   *     pageContext,
+   *     updatedAt
+   *   } = response.data;
+   *   console.log(aggregatedMetrics);
+   *   console.log(referrers);
+   *   console.log(rules);
+   *   console.log(updatedAt);
+   *   console.log(`Page ${pageContext.page} of ${pageContext.totalPages}`);
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Get second page with 50 records per page
+   * const response = await client.getReferrerLeaderboardPage({ page: 2, recordsPerPage: 50 });
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Handle error response, ie. when Referrer Leaderboard is not currently available.
+   * const response = await client.getReferrerLeaderboardPage();
+   *
+   * if (response.responseCode === ReferrerLeaderboardPageResponseCodes.Error) {
+   *   console.error(response.error);
+   *   console.error(response.errorMessage);
+   * }
+   * ```
+   */
+  async getReferrerLeaderboardPage(request) {
+    const url = new URL(`/ensanalytics/referrers`, this.options.url);
+    if (request?.page) url.searchParams.set("page", request.page.toString());
+    if (request?.recordsPerPage)
+      url.searchParams.set("recordsPerPage", request.recordsPerPage.toString());
+    const response = await fetch(url);
+    let responseData;
+    try {
+      responseData = await response.json();
+    } catch {
+      throw new Error("Malformed response data: invalid JSON");
+    }
+    return deserializeReferrerLeaderboardPageResponse(
+      responseData
+    );
+  }
+  /**
+   * Fetch Referrer Detail
+   *
+   * Retrieves detailed information about a specific referrer, whether they are on the
+   * leaderboard or not.
+   *
+   * The response data is a discriminated union type with a `type` field:
+   *
+   * **For referrers on the leaderboard** (`ReferrerDetailRanked`):
+   * - `type`: {@link ReferrerDetailTypeIds.Ranked}
+   * - `referrer`: The `AwardedReferrerMetrics` from @namehash/ens-referrals
+   * - `rules`: The referral program rules
+   * - `aggregatedMetrics`: Aggregated metrics for all referrers on the leaderboard
+   * - `accurateAsOf`: Unix timestamp indicating when the data was last updated
+   *
+   * **For referrers NOT on the leaderboard** (`ReferrerDetailUnranked`):
+   * - `type`: {@link ReferrerDetailTypeIds.Unranked}
+   * - `referrer`: The `UnrankedReferrerMetrics` from @namehash/ens-referrals
+   * - `rules`: The referral program rules
+   * - `aggregatedMetrics`: Aggregated metrics for all referrers on the leaderboard
+   * - `accurateAsOf`: Unix timestamp indicating when the data was last updated
+   *
+   * @see {@link https://www.npmjs.com/package/@namehash/ens-referrals|@namehash/ens-referrals} for calculation details
+   *
+   * @param request The referrer address to query
+   * @returns {ReferrerDetailResponse} Returns the referrer detail response
+   *
+   * @throws if the ENSNode request fails
+   * @throws if the response data is malformed
+   *
+   * @example
+   * ```typescript
+   * // Get referrer detail for a specific address
+   * const response = await client.getReferrerDetail({
+   *   referrer: "0x1234567890123456789012345678901234567890"
+   * });
+   * if (response.responseCode === ReferrerDetailResponseCodes.Ok) {
+   *   const { type, referrer, rules, aggregatedMetrics, accurateAsOf } = response.data;
+   *   console.log(type); // ReferrerDetailTypeIds.Ranked or ReferrerDetailTypeIds.Unranked
+   *   console.log(referrer);
+   *   console.log(accurateAsOf);
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Use discriminated union to check if referrer is ranked
+   * const response = await client.getReferrerDetail({
+   *   referrer: "0x1234567890123456789012345678901234567890"
+   * });
+   * if (response.responseCode === ReferrerDetailResponseCodes.Ok) {
+   *   if (response.data.type === ReferrerDetailTypeIds.Ranked) {
+   *     // TypeScript knows this is ReferrerDetailRanked
+   *     console.log(`Rank: ${response.data.referrer.rank}`);
+   *     console.log(`Qualified: ${response.data.referrer.isQualified}`);
+   *     console.log(`Award Pool Share: ${response.data.referrer.awardPoolShare * 100}%`);
+   *   } else {
+   *     // TypeScript knows this is ReferrerDetailUnranked
+   *     console.log("Referrer is not on the leaderboard (no referrals yet)");
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Handle error response, ie. when Referrer Detail is not currently available.
+   * const response = await client.getReferrerDetail({
+   *   referrer: "0x1234567890123456789012345678901234567890"
+   * });
+   *
+   * if (response.responseCode === ReferrerDetailResponseCodes.Error) {
+   *   console.error(response.error);
+   *   console.error(response.errorMessage);
+   * }
+   * ```
+   */
+  async getReferrerDetail(request) {
+    const url = new URL(
+      `/ensanalytics/referrers/${encodeURIComponent(request.referrer)}`,
+      this.options.url
+    );
+    const response = await fetch(url);
+    let responseData;
+    try {
+      responseData = await response.json();
+    } catch {
+      throw new Error("Malformed response data: invalid JSON");
+    }
+    return deserializeReferrerDetailResponse(responseData);
+  }
+};
+
+// src/currency.ts
+function isValidUSDQuantity(value) {
+  return isFiniteNonNegativeNumber(value);
+}
+function validateUSDQuantity(value) {
+  if (!isValidUSDQuantity(value)) {
+    throw new Error(`Invalid USD quantity: ${value}.`);
+  }
+}
+
 // src/leaderboard.ts
 var buildReferrerLeaderboard = (allReferrers, rules, accurateAsOf) => {
   const uniqueReferrers = allReferrers.map((referrer) => referrer.referrer);
@@ -401,159 +1439,14 @@ var buildReferrerLeaderboard = (allReferrers, rules, accurateAsOf) => {
   };
 };
 
-// src/leaderboard-page.ts
-var REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT = 25;
-var REFERRERS_PER_LEADERBOARD_PAGE_MAX = 100;
-var validateReferrerLeaderboardPageParams = (params) => {
-  if (params.page !== void 0 && !isPositiveInteger(params.page)) {
-    throw new Error(
-      `Invalid ReferrerLeaderboardPageParams: ${params.page}. page must be a positive integer.`
-    );
-  }
-  if (params.recordsPerPage !== void 0 && !isPositiveInteger(params.recordsPerPage)) {
-    throw new Error(
-      `Invalid ReferrerLeaderboardPageParams: ${params.recordsPerPage}. recordsPerPage must be a positive integer.`
-    );
-  }
-  if (params.recordsPerPage !== void 0 && params.recordsPerPage > REFERRERS_PER_LEADERBOARD_PAGE_MAX) {
-    throw new Error(
-      `Invalid ReferrerLeaderboardPageParams: ${params.recordsPerPage}. recordsPerPage must be less than or equal to ${REFERRERS_PER_LEADERBOARD_PAGE_MAX}.`
-    );
-  }
-};
-var buildReferrerLeaderboardPageParams = (params) => {
-  const result = {
-    page: params.page ?? 1,
-    recordsPerPage: params.recordsPerPage ?? REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT
-  };
-  validateReferrerLeaderboardPageParams(result);
-  return result;
-};
-var validateReferrerLeaderboardPageContext = (context) => {
-  validateReferrerLeaderboardPageParams(context);
-  if (!isNonNegativeInteger(context.totalRecords)) {
-    throw new Error(
-      `Invalid ReferrerLeaderboardPageContext: total must be a non-negative integer but is ${context.totalRecords}.`
-    );
-  }
-  const startIndex = (context.page - 1) * context.recordsPerPage;
-  const endIndex = startIndex + context.recordsPerPage;
-  if (!context.hasNext && endIndex < context.totalRecords) {
-    throw new Error(
-      `Invalid ReferrerLeaderboardPageContext: if hasNext is false, endIndex (${endIndex}) must be greater than or equal to total (${context.totalRecords}).`
-    );
-  } else if (context.hasNext && context.page * context.recordsPerPage >= context.totalRecords) {
-    throw new Error(
-      `Invalid ReferrerLeaderboardPageContext: if hasNext is true, endIndex (${endIndex}) must be less than total (${context.totalRecords}).`
-    );
-  }
-  if (!context.hasPrev && context.page !== 1) {
-    throw new Error(
-      `Invalid ReferrerLeaderboardPageContext: if hasPrev is false, page must be the first page (1) but is ${context.page}.`
-    );
-  } else if (context.hasPrev && context.page === 1) {
-    throw new Error(
-      `Invalid ReferrerLeaderboardPageContext: if hasPrev is true, page must not be the first page (1) but is ${context.page}.`
-    );
-  }
-};
-var buildReferrerLeaderboardPageContext = (optionalParams, leaderboard) => {
-  const materializedParams = buildReferrerLeaderboardPageParams(optionalParams);
-  const totalRecords = leaderboard.referrers.size;
-  const totalPages = Math.max(1, Math.ceil(totalRecords / materializedParams.recordsPerPage));
-  if (materializedParams.page > totalPages) {
-    throw new Error(
-      `Invalid ReferrerLeaderboardPageContext: page ${materializedParams.page} exceeds total pages ${totalPages}.`
-    );
-  }
-  if (totalRecords === 0) {
-    return {
-      ...materializedParams,
-      totalRecords: 0,
-      totalPages: 1,
-      hasNext: false,
-      hasPrev: false,
-      startIndex: void 0,
-      endIndex: void 0
-    };
-  }
-  const startIndex = (materializedParams.page - 1) * materializedParams.recordsPerPage;
-  const maxTheoreticalIndexOnPage = startIndex + (materializedParams.recordsPerPage - 1);
-  const endIndex = Math.min(maxTheoreticalIndexOnPage, totalRecords - 1);
-  const hasNext = maxTheoreticalIndexOnPage < totalRecords - 1;
-  const hasPrev = materializedParams.page > 1;
-  const result = {
-    ...materializedParams,
-    totalRecords,
-    totalPages,
-    hasNext,
-    hasPrev,
-    startIndex,
-    endIndex
-  };
-  validateReferrerLeaderboardPageContext(result);
-  return result;
-};
-var getReferrerLeaderboardPage = (pageParams, leaderboard) => {
-  const pageContext = buildReferrerLeaderboardPageContext(pageParams, leaderboard);
-  let referrers;
-  if (pageContext.totalRecords > 0 && typeof pageContext.startIndex !== "undefined" && typeof pageContext.endIndex !== "undefined") {
-    referrers = Array.from(leaderboard.referrers.values()).slice(
-      pageContext.startIndex,
-      pageContext.endIndex + 1
-      // For `slice`, this is exclusive of the element at the index 'end'. We need it to be inclusive, hence plus one.
-    );
-  } else {
-    referrers = [];
-  }
-  return {
-    rules: leaderboard.rules,
-    referrers,
-    aggregatedMetrics: leaderboard.aggregatedMetrics,
-    pageContext,
-    accurateAsOf: leaderboard.accurateAsOf
-  };
-};
-
 // src/link.ts
-import { getAddress as getAddress2 } from "viem";
+import { getAddress } from "viem";
 function buildEnsReferralUrl(address) {
   const ensAppUrl = new URL("https://app.ens.domains");
-  ensAppUrl.searchParams.set("referrer", getAddress2(address));
+  ensAppUrl.searchParams.set("referrer", getAddress(address));
   return ensAppUrl;
 }
 
-// src/referrer-detail.ts
-var ReferrerDetailTypeIds = {
-  /**
-   * Represents a referrer who is ranked on the leaderboard.
-   */
-  Ranked: "ranked",
-  /**
-   * Represents a referrer who is not ranked on the leaderboard.
-   */
-  Unranked: "unranked"
-};
-var getReferrerDetail = (referrer, leaderboard) => {
-  const awardedReferrerMetrics = leaderboard.referrers.get(referrer);
-  if (awardedReferrerMetrics) {
-    return {
-      type: ReferrerDetailTypeIds.Ranked,
-      rules: leaderboard.rules,
-      referrer: awardedReferrerMetrics,
-      aggregatedMetrics: leaderboard.aggregatedMetrics,
-      accurateAsOf: leaderboard.accurateAsOf
-    };
-  }
-  return {
-    type: ReferrerDetailTypeIds.Unranked,
-    rules: leaderboard.rules,
-    referrer: buildUnrankedReferrerMetrics(referrer),
-    aggregatedMetrics: leaderboard.aggregatedMetrics,
-    accurateAsOf: leaderboard.accurateAsOf
-  };
-};
-
 // src/rules.ts
 var ENS_HOLIDAY_AWARDS_START_DATE = 1764547200;
 var ENS_HOLIDAY_AWARDS_END_DATE = 1767225599;
@@ -603,22 +1496,21 @@ var calcReferralProgramStatus = (referralProgramRules, now) => {
   return ReferralProgramStatuses.Active;
 };
 export {
-  ENCODED_REFERRER_BYTE_LENGTH,
-  ENCODED_REFERRER_BYTE_OFFSET,
+  DEFAULT_ENSNODE_API_URL,
+  ENSReferralsClient,
   ENS_HOLIDAY_AWARDS_END_DATE,
   ENS_HOLIDAY_AWARDS_MAX_QUALIFIED_REFERRERS,
   ENS_HOLIDAY_AWARDS_START_DATE,
   ENS_HOLIDAY_AWARDS_TOTAL_AWARD_POOL_VALUE,
-  EXPECTED_ENCODED_REFERRER_PADDING,
   REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT,
   REFERRERS_PER_LEADERBOARD_PAGE_MAX,
   ReferralProgramStatuses,
+  ReferrerDetailResponseCodes,
   ReferrerDetailTypeIds,
+  ReferrerLeaderboardPageResponseCodes,
   SECONDS_PER_YEAR,
-  ZERO_ENCODED_REFERRER,
   buildAggregatedReferrerMetrics,
   buildAwardedReferrerMetrics,
-  buildEncodedReferrer,
   buildEnsReferralUrl,
   buildRankedReferrerMetrics,
   buildReferralProgramRules,
@@ -635,7 +1527,8 @@ export {
   calcReferrerFinalScoreMultiplier,
   calcReferrerScore,
   compareReferrerMetrics,
-  decodeEncodedReferrer,
+  deserializeReferrerDetailResponse,
+  deserializeReferrerLeaderboardPageResponse,
   getReferrerDetail,
   getReferrerLeaderboardPage,
   isFiniteNonNegativeNumber,
@@ -648,6 +1541,8 @@ export {
   isValidRevenueContribution,
   isValidUSDQuantity,
   normalizeAddress,
+  serializeReferrerDetailResponse,
+  serializeReferrerLeaderboardPageResponse,
   sortReferrerMetrics,
   validateAggregatedReferrerMetrics,
   validateAwardedReferrerMetrics,