@namehash/ens-referrals 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NameHash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# ENS Referrals
+
+This package provides utilities for working with ENS Referrals, including useful types and utility functions.
+
+## Installation
+
+```bash
+npm install @namehash/ens-referrals viem
+```
+
+### Basic Usage
+
+```typescript
+import {
+  buildEncodedReferrer,
+  decodeEncodedReferrer,
+  buildEnsReferralUrl
+} from "@namehash/ens-referrals";
+import type { Address } from 'viem';
+
+const referrerAddress: Address = "0xd8da6bf26964af9d7eed9e03e53415d37aa96045";
+
+// Build an encoded referrer value (according to the subjective referrer encoding used for ENS Holiday Awards)
+const encodedReferrer = buildEncodedReferrer(referrerAddress); // 0x000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045
+
+// Decode an encoded referrer value (according to the subjective referrer encoding used for ENS Holiday Awards)
+const decodedReferrer = decodeEncodedReferrer(encodedReferrer); // 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+
+// Build a referrer URL to the official ENS manager app
+const referrerUrl = buildEnsReferralUrl(referrerAddress).toString(); // https://app.ens.domains/?referrer=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+```

package/dist/index.cjs

@@ -0,0 +1,77 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ENCODED_REFERRER_BYTE_LENGTH: () => ENCODED_REFERRER_BYTE_LENGTH,
+  ENCODED_REFERRER_BYTE_OFFSET: () => ENCODED_REFERRER_BYTE_OFFSET,
+  ENS_HOLIDAY_AWARDS_END_DATE: () => ENS_HOLIDAY_AWARDS_END_DATE,
+  ENS_HOLIDAY_AWARDS_START_DATE: () => ENS_HOLIDAY_AWARDS_START_DATE,
+  buildEncodedReferrer: () => buildEncodedReferrer,
+  buildEnsReferralUrl: () => buildEnsReferralUrl,
+  decodeEncodedReferrer: () => decodeEncodedReferrer,
+  encodedReferrerPadding: () => encodedReferrerPadding,
+  zeroEncodedReferrer: () => zeroEncodedReferrer
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/constants.ts
+var ENS_HOLIDAY_AWARDS_START_DATE = 1764547200;
+var ENS_HOLIDAY_AWARDS_END_DATE = 1767225599;
+
+// src/referrer.ts
+var import_viem = require("viem");
+var ENCODED_REFERRER_BYTE_OFFSET = 12;
+var ENCODED_REFERRER_BYTE_LENGTH = 32;
+var encodedReferrerPadding = (0, import_viem.pad)("0x", {
+  size: ENCODED_REFERRER_BYTE_OFFSET,
+  dir: "left"
+});
+var zeroEncodedReferrer = (0, import_viem.pad)("0x", {
+  size: ENCODED_REFERRER_BYTE_LENGTH,
+  dir: "left"
+});
+function buildEncodedReferrer(address) {
+  const lowercaseAddress = address.toLowerCase();
+  return (0, import_viem.pad)(lowercaseAddress, { size: ENCODED_REFERRER_BYTE_LENGTH, dir: "left" });
+}
+function decodeEncodedReferrer(encodedReferrer) {
+  if ((0, import_viem.size)(encodedReferrer) !== ENCODED_REFERRER_BYTE_LENGTH) {
+    throw new Error(
+      `Encoded referrer value must be represented by ${ENCODED_REFERRER_BYTE_LENGTH} bytes.`
+    );
+  }
+  const padding = (0, import_viem.slice)(encodedReferrer, 0, ENCODED_REFERRER_BYTE_OFFSET);
+  if (padding !== encodedReferrerPadding) {
+    return import_viem.zeroAddress;
+  }
+  const decodedReferrer = (0, import_viem.slice)(encodedReferrer, ENCODED_REFERRER_BYTE_OFFSET);
+  try {
+    return (0, import_viem.getAddress)(decodedReferrer);
+  } catch {
+    throw new Error(`Decoded referrer value must be a valid EVM address.`);
+  }
+}
+function buildEnsReferralUrl(address) {
+  const ensAppUrl = new URL("https://app.ens.domains");
+  ensAppUrl.searchParams.set("referrer", (0, import_viem.getAddress)(address));
+  return ensAppUrl;
+}
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/constants.ts","../src/referrer.ts"],"sourcesContent":["export * from \"./constants\";\nexport * from \"./referrer\";\n","/**\n * Unix timestamp value\n *\n * Represents the number of seconds that have elapsed\n * since January 1, 1970 (midnight UTC/GMT).\n *\n * Guaranteed to be an integer. May be zero or negative to represent a time at or\n * before Jan 1, 1970.\n */\nexport type UnixTimestamp = number;\n\n/**\n * Start date for the ENS Holiday Awards referral program.\n * 2025-12-01T00:00:00Z (December 1, 2025 at 00:00:00 UTC)\n */\nexport const ENS_HOLIDAY_AWARDS_START_DATE: UnixTimestamp = 1764547200;\n\n/**\n * End date for the ENS Holiday Awards referral program.\n * 2025-12-31T23:59:59Z (December 31, 2025 at 23:59:59 UTC)\n */\nexport const ENS_HOLIDAY_AWARDS_END_DATE: UnixTimestamp = 1767225599;\n","import { type Address, getAddress, type Hex, pad, size, slice, zeroAddress } from \"viem\";\n\n/**\n * Encoded Referrer\n *\n * Represents a \"raw\" ENS referrer value.\n *\n * Guaranteed to be a hex string representation of a 32-byte value.\n * For ENS Holiday Awards a correctly encoded referrer is\n * a left-padded lowercase EVM address.\n */\nexport type EncodedReferrer = Hex;\n\n/**\n * Encoded Referrer byte offset for ENS Holiday Awards.\n *\n * The count of left-padded bytes in an {@link EncodedReferrer} value for ENS Holiday Awards.\n */\nexport const ENCODED_REFERRER_BYTE_OFFSET = 12;\n\n/**\n * Encoded Referrer byte length\n *\n * The count of bytes the {@link EncodedReferrer} value consists of.\n */\nexport const ENCODED_REFERRER_BYTE_LENGTH = 32;\n\n/**\n * Encoded Referrer Padding for ENS Holiday Awards\n *\n * The initial bytes of correctly encoded referrer value for ENS Holiday Awards.\n */\nexport const encodedReferrerPadding = pad(\"0x\", {\n  size: ENCODED_REFERRER_BYTE_OFFSET,\n  dir: \"left\",\n});\n\n/**\n * Zero Encoded Referrer\n *\n * Guaranteed to be a hex string representation of a 32-byte zero value.\n */\nexport const zeroEncodedReferrer = pad(\"0x\", {\n  size: ENCODED_REFERRER_BYTE_LENGTH,\n  dir: \"left\",\n});\n\n/**\n * Build an {@link EncodedReferrer} value for the given {@link Address}\n * according to the subjective referrer encoding used for ENS Holiday Awards.\n */\nexport function buildEncodedReferrer(address: Address): EncodedReferrer {\n  const lowercaseAddress = address.toLowerCase() as Address;\n\n  return pad(lowercaseAddress, { size: ENCODED_REFERRER_BYTE_LENGTH, dir: \"left\" });\n}\n\n/**\n * Decode an {@link EncodedReferrer} value into a checksummed {@link Address}\n * according to the subjective referrer encoding used for ENS Holiday Awards.\n *\n * @param encodedReferrer - The \"raw\" {@link EncodedReferrer} value to decode.\n * @returns The decoded referrer checksummed address.\n * @throws when encodedReferrer value is not represented by\n *         {@link ENCODED_REFERRER_BYTE_LENGTH} bytes.\n * @throws when decodedReferrer is not a valid EVM address.\n */\nexport function decodeEncodedReferrer(encodedReferrer: EncodedReferrer): Address {\n  // Invariant: encoded referrer must be of expected size\n  if (size(encodedReferrer) !== ENCODED_REFERRER_BYTE_LENGTH) {\n    throw new Error(\n      `Encoded referrer value must be represented by ${ENCODED_REFERRER_BYTE_LENGTH} bytes.`,\n    );\n  }\n\n  const padding = slice(encodedReferrer, 0, ENCODED_REFERRER_BYTE_OFFSET);\n\n  // return zero address if the padding of encoded referrer is not correct\n  // for ENS Holiday Awards\n  if (padding !== encodedReferrerPadding) {\n    return zeroAddress;\n  }\n\n  const decodedReferrer = slice(encodedReferrer, ENCODED_REFERRER_BYTE_OFFSET);\n\n  try {\n    // return checksummed address\n    return getAddress(decodedReferrer);\n  } catch {\n    throw new Error(`Decoded referrer value must be a valid EVM address.`);\n  }\n}\n\n/**\n * Build a URL to the official ENS manager app\n * where the given {@link Address} is set as the referrer.\n */\nexport function buildEnsReferralUrl(address: Address): URL {\n  const ensAppUrl = new URL(\"https://app.ens.domains\");\n\n  ensAppUrl.searchParams.set(\"referrer\", getAddress(address));\n\n  return ensAppUrl;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACeO,IAAM,gCAA+C;AAMrD,IAAM,8BAA6C;;;ACrB1D,kBAAkF;AAkB3E,IAAM,+BAA+B;AAOrC,IAAM,+BAA+B;AAOrC,IAAM,6BAAyB,iBAAI,MAAM;AAAA,EAC9C,MAAM;AAAA,EACN,KAAK;AACP,CAAC;AAOM,IAAM,0BAAsB,iBAAI,MAAM;AAAA,EAC3C,MAAM;AAAA,EACN,KAAK;AACP,CAAC;AAMM,SAAS,qBAAqB,SAAmC;AACtE,QAAM,mBAAmB,QAAQ,YAAY;AAE7C,aAAO,iBAAI,kBAAkB,EAAE,MAAM,8BAA8B,KAAK,OAAO,CAAC;AAClF;AAYO,SAAS,sBAAsB,iBAA2C;AAE/E,UAAI,kBAAK,eAAe,MAAM,8BAA8B;AAC1D,UAAM,IAAI;AAAA,MACR,iDAAiD,4BAA4B;AAAA,IAC/E;AAAA,EACF;AAEA,QAAM,cAAU,mBAAM,iBAAiB,GAAG,4BAA4B;AAItE,MAAI,YAAY,wBAAwB;AACtC,WAAO;AAAA,EACT;AAEA,QAAM,sBAAkB,mBAAM,iBAAiB,4BAA4B;AAE3E,MAAI;AAEF,eAAO,wBAAW,eAAe;AAAA,EACnC,QAAQ;AACN,UAAM,IAAI,MAAM,qDAAqD;AAAA,EACvE;AACF;AAMO,SAAS,oBAAoB,SAAuB;AACzD,QAAM,YAAY,IAAI,IAAI,yBAAyB;AAEnD,YAAU,aAAa,IAAI,gBAAY,wBAAW,OAAO,CAAC;AAE1D,SAAO;AACT;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,80 @@
+import { Hex, Address } from 'viem';
+
+/**
+ * Unix timestamp value
+ *
+ * Represents the number of seconds that have elapsed
+ * since January 1, 1970 (midnight UTC/GMT).
+ *
+ * Guaranteed to be an integer. May be zero or negative to represent a time at or
+ * before Jan 1, 1970.
+ */
+type UnixTimestamp = number;
+/**
+ * Start date for the ENS Holiday Awards referral program.
+ * 2025-12-01T00:00:00Z (December 1, 2025 at 00:00:00 UTC)
+ */
+declare const ENS_HOLIDAY_AWARDS_START_DATE: UnixTimestamp;
+/**
+ * End date for the ENS Holiday Awards referral program.
+ * 2025-12-31T23:59:59Z (December 31, 2025 at 23:59:59 UTC)
+ */
+declare const ENS_HOLIDAY_AWARDS_END_DATE: UnixTimestamp;
+
+/**
+ * Encoded Referrer
+ *
+ * Represents a "raw" ENS referrer value.
+ *
+ * Guaranteed to be a hex string representation of a 32-byte value.
+ * For ENS Holiday Awards a correctly encoded referrer is
+ * a left-padded lowercase EVM address.
+ */
+type EncodedReferrer = Hex;
+/**
+ * Encoded Referrer byte offset for ENS Holiday Awards.
+ *
+ * The count of left-padded bytes in an {@link EncodedReferrer} value for ENS Holiday Awards.
+ */
+declare const ENCODED_REFERRER_BYTE_OFFSET = 12;
+/**
+ * Encoded Referrer byte length
+ *
+ * The count of bytes the {@link EncodedReferrer} value consists of.
+ */
+declare const ENCODED_REFERRER_BYTE_LENGTH = 32;
+/**
+ * Encoded Referrer Padding for ENS Holiday Awards
+ *
+ * The initial bytes of correctly encoded referrer value for ENS Holiday Awards.
+ */
+declare const encodedReferrerPadding: `0x${string}`;
+/**
+ * Zero Encoded Referrer
+ *
+ * Guaranteed to be a hex string representation of a 32-byte zero value.
+ */
+declare const zeroEncodedReferrer: `0x${string}`;
+/**
+ * Build an {@link EncodedReferrer} value for the given {@link Address}
+ * according to the subjective referrer encoding used for ENS Holiday Awards.
+ */
+declare function buildEncodedReferrer(address: Address): EncodedReferrer;
+/**
+ * Decode an {@link EncodedReferrer} value into a checksummed {@link Address}
+ * according to the subjective referrer encoding used for ENS Holiday Awards.
+ *
+ * @param encodedReferrer - The "raw" {@link EncodedReferrer} value to decode.
+ * @returns The decoded referrer checksummed address.
+ * @throws when encodedReferrer value is not represented by
+ *         {@link ENCODED_REFERRER_BYTE_LENGTH} bytes.
+ * @throws when decodedReferrer is not a valid EVM address.
+ */
+declare function decodeEncodedReferrer(encodedReferrer: EncodedReferrer): Address;
+/**
+ * Build a URL to the official ENS manager app
+ * where the given {@link Address} is set as the referrer.
+ */
+declare function buildEnsReferralUrl(address: Address): URL;
+
+export { ENCODED_REFERRER_BYTE_LENGTH, ENCODED_REFERRER_BYTE_OFFSET, ENS_HOLIDAY_AWARDS_END_DATE, ENS_HOLIDAY_AWARDS_START_DATE, type EncodedReferrer, type UnixTimestamp, buildEncodedReferrer, buildEnsReferralUrl, decodeEncodedReferrer, encodedReferrerPadding, zeroEncodedReferrer };

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import { Hex, Address } from 'viem';
+
+/**
+ * Unix timestamp value
+ *
+ * Represents the number of seconds that have elapsed
+ * since January 1, 1970 (midnight UTC/GMT).
+ *
+ * Guaranteed to be an integer. May be zero or negative to represent a time at or
+ * before Jan 1, 1970.
+ */
+type UnixTimestamp = number;
+/**
+ * Start date for the ENS Holiday Awards referral program.
+ * 2025-12-01T00:00:00Z (December 1, 2025 at 00:00:00 UTC)
+ */
+declare const ENS_HOLIDAY_AWARDS_START_DATE: UnixTimestamp;
+/**
+ * End date for the ENS Holiday Awards referral program.
+ * 2025-12-31T23:59:59Z (December 31, 2025 at 23:59:59 UTC)
+ */
+declare const ENS_HOLIDAY_AWARDS_END_DATE: UnixTimestamp;
+
+/**
+ * Encoded Referrer
+ *
+ * Represents a "raw" ENS referrer value.
+ *
+ * Guaranteed to be a hex string representation of a 32-byte value.
+ * For ENS Holiday Awards a correctly encoded referrer is
+ * a left-padded lowercase EVM address.
+ */
+type EncodedReferrer = Hex;
+/**
+ * Encoded Referrer byte offset for ENS Holiday Awards.
+ *
+ * The count of left-padded bytes in an {@link EncodedReferrer} value for ENS Holiday Awards.
+ */
+declare const ENCODED_REFERRER_BYTE_OFFSET = 12;
+/**
+ * Encoded Referrer byte length
+ *
+ * The count of bytes the {@link EncodedReferrer} value consists of.
+ */
+declare const ENCODED_REFERRER_BYTE_LENGTH = 32;
+/**
+ * Encoded Referrer Padding for ENS Holiday Awards
+ *
+ * The initial bytes of correctly encoded referrer value for ENS Holiday Awards.
+ */
+declare const encodedReferrerPadding: `0x${string}`;
+/**
+ * Zero Encoded Referrer
+ *
+ * Guaranteed to be a hex string representation of a 32-byte zero value.
+ */
+declare const zeroEncodedReferrer: `0x${string}`;
+/**
+ * Build an {@link EncodedReferrer} value for the given {@link Address}
+ * according to the subjective referrer encoding used for ENS Holiday Awards.
+ */
+declare function buildEncodedReferrer(address: Address): EncodedReferrer;
+/**
+ * Decode an {@link EncodedReferrer} value into a checksummed {@link Address}
+ * according to the subjective referrer encoding used for ENS Holiday Awards.
+ *
+ * @param encodedReferrer - The "raw" {@link EncodedReferrer} value to decode.
+ * @returns The decoded referrer checksummed address.
+ * @throws when encodedReferrer value is not represented by
+ *         {@link ENCODED_REFERRER_BYTE_LENGTH} bytes.
+ * @throws when decodedReferrer is not a valid EVM address.
+ */
+declare function decodeEncodedReferrer(encodedReferrer: EncodedReferrer): Address;
+/**
+ * Build a URL to the official ENS manager app
+ * where the given {@link Address} is set as the referrer.
+ */
+declare function buildEnsReferralUrl(address: Address): URL;
+
+export { ENCODED_REFERRER_BYTE_LENGTH, ENCODED_REFERRER_BYTE_OFFSET, ENS_HOLIDAY_AWARDS_END_DATE, ENS_HOLIDAY_AWARDS_START_DATE, type EncodedReferrer, type UnixTimestamp, buildEncodedReferrer, buildEnsReferralUrl, decodeEncodedReferrer, encodedReferrerPadding, zeroEncodedReferrer };

package/dist/index.js

@@ -0,0 +1,54 @@
+// src/constants.ts
+var ENS_HOLIDAY_AWARDS_START_DATE = 1764547200;
+var ENS_HOLIDAY_AWARDS_END_DATE = 1767225599;
+
+// src/referrer.ts
+import { getAddress, pad, size, slice, zeroAddress } from "viem";
+var ENCODED_REFERRER_BYTE_OFFSET = 12;
+var ENCODED_REFERRER_BYTE_LENGTH = 32;
+var encodedReferrerPadding = pad("0x", {
+  size: ENCODED_REFERRER_BYTE_OFFSET,
+  dir: "left"
+});
+var zeroEncodedReferrer = pad("0x", {
+  size: ENCODED_REFERRER_BYTE_LENGTH,
+  dir: "left"
+});
+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) {
+    throw new Error(
+      `Encoded referrer value must be represented by ${ENCODED_REFERRER_BYTE_LENGTH} bytes.`
+    );
+  }
+  const padding = slice(encodedReferrer, 0, ENCODED_REFERRER_BYTE_OFFSET);
+  if (padding !== encodedReferrerPadding) {
+    return zeroAddress;
+  }
+  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.`);
+  }
+}
+function buildEnsReferralUrl(address) {
+  const ensAppUrl = new URL("https://app.ens.domains");
+  ensAppUrl.searchParams.set("referrer", getAddress(address));
+  return ensAppUrl;
+}
+export {
+  ENCODED_REFERRER_BYTE_LENGTH,
+  ENCODED_REFERRER_BYTE_OFFSET,
+  ENS_HOLIDAY_AWARDS_END_DATE,
+  ENS_HOLIDAY_AWARDS_START_DATE,
+  buildEncodedReferrer,
+  buildEnsReferralUrl,
+  decodeEncodedReferrer,
+  encodedReferrerPadding,
+  zeroEncodedReferrer
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants.ts","../src/referrer.ts"],"sourcesContent":["/**\n * Unix timestamp value\n *\n * Represents the number of seconds that have elapsed\n * since January 1, 1970 (midnight UTC/GMT).\n *\n * Guaranteed to be an integer. May be zero or negative to represent a time at or\n * before Jan 1, 1970.\n */\nexport type UnixTimestamp = number;\n\n/**\n * Start date for the ENS Holiday Awards referral program.\n * 2025-12-01T00:00:00Z (December 1, 2025 at 00:00:00 UTC)\n */\nexport const ENS_HOLIDAY_AWARDS_START_DATE: UnixTimestamp = 1764547200;\n\n/**\n * End date for the ENS Holiday Awards referral program.\n * 2025-12-31T23:59:59Z (December 31, 2025 at 23:59:59 UTC)\n */\nexport const ENS_HOLIDAY_AWARDS_END_DATE: UnixTimestamp = 1767225599;\n","import { type Address, getAddress, type Hex, pad, size, slice, zeroAddress } from \"viem\";\n\n/**\n * Encoded Referrer\n *\n * Represents a \"raw\" ENS referrer value.\n *\n * Guaranteed to be a hex string representation of a 32-byte value.\n * For ENS Holiday Awards a correctly encoded referrer is\n * a left-padded lowercase EVM address.\n */\nexport type EncodedReferrer = Hex;\n\n/**\n * Encoded Referrer byte offset for ENS Holiday Awards.\n *\n * The count of left-padded bytes in an {@link EncodedReferrer} value for ENS Holiday Awards.\n */\nexport const ENCODED_REFERRER_BYTE_OFFSET = 12;\n\n/**\n * Encoded Referrer byte length\n *\n * The count of bytes the {@link EncodedReferrer} value consists of.\n */\nexport const ENCODED_REFERRER_BYTE_LENGTH = 32;\n\n/**\n * Encoded Referrer Padding for ENS Holiday Awards\n *\n * The initial bytes of correctly encoded referrer value for ENS Holiday Awards.\n */\nexport const encodedReferrerPadding = pad(\"0x\", {\n  size: ENCODED_REFERRER_BYTE_OFFSET,\n  dir: \"left\",\n});\n\n/**\n * Zero Encoded Referrer\n *\n * Guaranteed to be a hex string representation of a 32-byte zero value.\n */\nexport const zeroEncodedReferrer = pad(\"0x\", {\n  size: ENCODED_REFERRER_BYTE_LENGTH,\n  dir: \"left\",\n});\n\n/**\n * Build an {@link EncodedReferrer} value for the given {@link Address}\n * according to the subjective referrer encoding used for ENS Holiday Awards.\n */\nexport function buildEncodedReferrer(address: Address): EncodedReferrer {\n  const lowercaseAddress = address.toLowerCase() as Address;\n\n  return pad(lowercaseAddress, { size: ENCODED_REFERRER_BYTE_LENGTH, dir: \"left\" });\n}\n\n/**\n * Decode an {@link EncodedReferrer} value into a checksummed {@link Address}\n * according to the subjective referrer encoding used for ENS Holiday Awards.\n *\n * @param encodedReferrer - The \"raw\" {@link EncodedReferrer} value to decode.\n * @returns The decoded referrer checksummed address.\n * @throws when encodedReferrer value is not represented by\n *         {@link ENCODED_REFERRER_BYTE_LENGTH} bytes.\n * @throws when decodedReferrer is not a valid EVM address.\n */\nexport function decodeEncodedReferrer(encodedReferrer: EncodedReferrer): Address {\n  // Invariant: encoded referrer must be of expected size\n  if (size(encodedReferrer) !== ENCODED_REFERRER_BYTE_LENGTH) {\n    throw new Error(\n      `Encoded referrer value must be represented by ${ENCODED_REFERRER_BYTE_LENGTH} bytes.`,\n    );\n  }\n\n  const padding = slice(encodedReferrer, 0, ENCODED_REFERRER_BYTE_OFFSET);\n\n  // return zero address if the padding of encoded referrer is not correct\n  // for ENS Holiday Awards\n  if (padding !== encodedReferrerPadding) {\n    return zeroAddress;\n  }\n\n  const decodedReferrer = slice(encodedReferrer, ENCODED_REFERRER_BYTE_OFFSET);\n\n  try {\n    // return checksummed address\n    return getAddress(decodedReferrer);\n  } catch {\n    throw new Error(`Decoded referrer value must be a valid EVM address.`);\n  }\n}\n\n/**\n * Build a URL to the official ENS manager app\n * where the given {@link Address} is set as the referrer.\n */\nexport function buildEnsReferralUrl(address: Address): URL {\n  const ensAppUrl = new URL(\"https://app.ens.domains\");\n\n  ensAppUrl.searchParams.set(\"referrer\", getAddress(address));\n\n  return ensAppUrl;\n}\n"],"mappings":";AAeO,IAAM,gCAA+C;AAMrD,IAAM,8BAA6C;;;ACrB1D,SAAuB,YAAsB,KAAK,MAAM,OAAO,mBAAmB;AAkB3E,IAAM,+BAA+B;AAOrC,IAAM,+BAA+B;AAOrC,IAAM,yBAAyB,IAAI,MAAM;AAAA,EAC9C,MAAM;AAAA,EACN,KAAK;AACP,CAAC;AAOM,IAAM,sBAAsB,IAAI,MAAM;AAAA,EAC3C,MAAM;AAAA,EACN,KAAK;AACP,CAAC;AAMM,SAAS,qBAAqB,SAAmC;AACtE,QAAM,mBAAmB,QAAQ,YAAY;AAE7C,SAAO,IAAI,kBAAkB,EAAE,MAAM,8BAA8B,KAAK,OAAO,CAAC;AAClF;AAYO,SAAS,sBAAsB,iBAA2C;AAE/E,MAAI,KAAK,eAAe,MAAM,8BAA8B;AAC1D,UAAM,IAAI;AAAA,MACR,iDAAiD,4BAA4B;AAAA,IAC/E;AAAA,EACF;AAEA,QAAM,UAAU,MAAM,iBAAiB,GAAG,4BAA4B;AAItE,MAAI,YAAY,wBAAwB;AACtC,WAAO;AAAA,EACT;AAEA,QAAM,kBAAkB,MAAM,iBAAiB,4BAA4B;AAE3E,MAAI;AAEF,WAAO,WAAW,eAAe;AAAA,EACnC,QAAQ;AACN,UAAM,IAAI,MAAM,qDAAqD;AAAA,EACvE;AACF;AAMO,SAAS,oBAAoB,SAAuB;AACzD,QAAM,YAAY,IAAI,IAAI,yBAAyB;AAEnD,YAAU,aAAa,IAAI,YAAY,WAAW,OAAO,CAAC;AAE1D,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@namehash/ens-referrals",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Utilities for ENS Referrals.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/namehash/ensnode.git",
+    "directory": "packages/ens-referrals"
+  },
+  "homepage": "https://github.com/namehash/ensnode/tree/main/packages/ens-referrals",
+  "keywords": [
+    "ENS",
+    "Referrals"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "default": "./dist/index.cjs",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "viem": "^2.22.13"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "viem": "^2.22.13",
+    "vitest": "^4.0.2",
+    "@ensnode/shared-configs": "1.0.0"
+  },
+  "scripts": {
+    "prepublish": "tsup",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}