@namehash/ens-referrals 1.10.0 → 1.11.0

package/dist/index.cjs

@@ -69,6 +69,7 @@ __export(index_exports, {
   buildUnrankedReferrerMetricsPieSplit: () => buildUnrankedReferrerMetricsPieSplit,
   buildUnrankedReferrerMetricsRevShareCap: () => buildUnrankedReferrerMetricsRevShareCap,
   calcBaseReferralProgramEditionStatus: () => calcBaseReferralProgramEditionStatus,
+  calcBaseRevenueContribution: () => calcBaseRevenueContribution,
   calcReferralProgramEditionStatusPieSplit: () => calcReferralProgramEditionStatusPieSplit,
   calcReferralProgramEditionStatusRevShareCap: () => calcReferralProgramEditionStatusRevShareCap,
   calcReferrerAwardPoolSharePieSplit: () => calcReferrerAwardPoolSharePieSplit,
@@ -78,6 +79,7 @@ __export(index_exports, {
   deserializeReferralProgramEditionSummariesResponse: () => deserializeReferralProgramEditionSummariesResponse,
   deserializeReferrerLeaderboardPageResponse: () => deserializeReferrerLeaderboardPageResponse,
   deserializeReferrerMetricsEditionsResponse: () => deserializeReferrerMetricsEditionsResponse,
+  findOverlappingEditionPair: () => findOverlappingEditionPair,
   getReferrerEditionMetrics: () => getReferrerEditionMetrics,
   getReferrerLeaderboardPage: () => getReferrerLeaderboardPage,
   isFiniteNonNegativeNumber: () => isFiniteNonNegativeNumber,
@@ -477,7 +479,8 @@ function scaleBigintByNumber(value, scaleFactor) {
 var CurrencyIds = {
   ETH: "ETH",
   USDC: "USDC",
-  DAI: "DAI"
+  DAI: "DAI",
+  ENSTokens: "ENSTokens"
 };
 var currencyInfo = {
   [CurrencyIds.ETH]: {
@@ -494,6 +497,11 @@ var currencyInfo = {
     id: CurrencyIds.DAI,
     name: "Dai Stablecoin",
     decimals: 18
+  },
+  [CurrencyIds.ENSTokens]: {
+    id: CurrencyIds.ENSTokens,
+    name: "$ENS Tokens",
+    decimals: 18
   }
 };
 function priceEth(amount) {
@@ -508,6 +516,45 @@ function priceUsdc(amount) {
     currency: CurrencyIds.USDC
   };
 }
+function isPriceCurrencyEqual(priceA, priceB) {
+  return priceA.currency === priceB.currency;
+}
+function addPrices(...prices) {
+  const firstPrice = prices[0];
+  const allPricesInSameCurrency = prices.every((price) => isPriceCurrencyEqual(firstPrice, price));
+  if (allPricesInSameCurrency === false) {
+    throw new Error("All prices must have the same currency to be added together.");
+  }
+  const { currency } = firstPrice;
+  return prices.reduce(
+    (acc, price) => ({
+      amount: acc.amount + price.amount,
+      currency
+    }),
+    {
+      amount: 0n,
+      currency: firstPrice.currency
+    }
+  );
+}
+function subtractPrice(a, b) {
+  if (!isPriceCurrencyEqual(a, b)) {
+    throw new Error("All prices must have the same currency to be subtracted.");
+  }
+  const resultAmount = a.amount - b.amount;
+  if (resultAmount < 0n) {
+    throw new Error("subtractPrice result must be non-negative.");
+  }
+  return { amount: resultAmount, currency: a.currency };
+}
+function minPrice(...prices) {
+  const firstPrice = prices[0];
+  const allPricesInSameCurrency = prices.every((price) => isPriceCurrencyEqual(firstPrice, price));
+  if (allPricesInSameCurrency === false) {
+    throw new Error("All prices must have the same currency to be compared.");
+  }
+  return prices.reduce((acc, price) => price.amount < acc.amount ? price : acc);
+}
 function scalePrice(price, scaleFactor) {
   const scaledAmount = scaleBigintByNumber(price.amount, scaleFactor);
   return {
@@ -589,6 +636,62 @@ var import_v43 = __toESM(require("zod/v4"), 1);
 // src/award-models/shared/api/zod-schemas.ts
 var import_v42 = __toESM(require("zod/v4"), 1);
 
+// src/edition.ts
+var REFERRAL_PROGRAM_EDITION_SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function validateReferralProgramEditionConfigSet(configSet) {
+  const violation = Array.from(configSet.entries()).find(([key, config]) => key !== config.slug);
+  if (violation) {
+    const [key, config] = violation;
+    throw new Error(
+      `Edition config set invariant violation: map key "${key}" does not match config.slug "${config.slug}"`
+    );
+  }
+  const overlap = findOverlappingEditionPair(Array.from(configSet.values()));
+  if (overlap) {
+    const [a, b] = overlap;
+    throw new Error(
+      `Edition config set invariant violation: editions "${a.slug}" and "${b.slug}" have overlapping time ranges for subregistryId ${a.rules.subregistryId.chainId}:${a.rules.subregistryId.address} (startTime and endTime are inclusive)`
+    );
+  }
+}
+function findOverlappingEditionPair(editions) {
+  const byRegistry = /* @__PURE__ */ new Map();
+  for (const edition of editions) {
+    const key = `${edition.rules.subregistryId.chainId}:${edition.rules.subregistryId.address}`;
+    const group = byRegistry.get(key);
+    if (group) {
+      group.push(edition);
+    } else {
+      byRegistry.set(key, [edition]);
+    }
+  }
+  for (const group of byRegistry.values()) {
+    if (group.length < 2) continue;
+    group.sort((a, b) => a.rules.startTime - b.rules.startTime);
+    for (let i = 1; i < group.length; i++) {
+      const prev = group[i - 1];
+      const curr = group[i];
+      if (curr.rules.startTime <= prev.rules.endTime) {
+        return [prev, curr];
+      }
+    }
+  }
+  return null;
+}
+function buildReferralProgramEditionConfigSet(configs) {
+  const slugCounts = configs.reduce((counts, config) => {
+    counts.set(config.slug, (counts.get(config.slug) || 0) + 1);
+    return counts;
+  }, /* @__PURE__ */ new Map());
+  const duplicates = Array.from(slugCounts.entries()).filter(([_, count]) => count > 1).map(([slug, count]) => `"${slug}" (${count} occurrences)`);
+  if (duplicates.length > 0) {
+    throw new Error(`Duplicate edition config slugs detected: ${duplicates.join(", ")}`);
+  }
+  const configSet = new Map(configs.map((config) => [config.slug, config]));
+  validateReferralProgramEditionConfigSet(configSet);
+  return configSet;
+}
+
 // src/number.ts
 var isInteger = (value) => {
   return Number.isInteger(value);
@@ -795,6 +898,15 @@ var calcBaseReferralProgramEditionStatus = (rules, now) => {
 };
 
 // src/award-models/shared/api/zod-schemas.ts
+var makeReferralProgramEditionSlugSchema = (valueLabel = "ReferralProgramEditionSlug") => import_v42.default.string().min(1, `${valueLabel} must not be empty`).regex(
+  REFERRAL_PROGRAM_EDITION_SLUG_PATTERN,
+  `${valueLabel} must contain only lowercase letters, digits, and hyphens. Must not start or end with a hyphen.`
+);
+var makeBaseReferralProgramEditionConfigSchema = (valueLabel = "BaseReferralProgramEditionConfig") => import_v42.default.object({
+  slug: makeReferralProgramEditionSlugSchema(`${valueLabel}.slug`),
+  displayName: import_v42.default.string().min(1, `${valueLabel}.displayName must not be empty`),
+  rules: makeBaseReferralProgramRulesSchema(`${valueLabel}.rules`)
+});
 var makeBaseReferralProgramRulesSchema = (valueLabel) => import_v42.default.object({
   awardModel: import_v42.default.string(),
   startTime: makeUnixTimestampSchema(`${valueLabel}.startTime`),
@@ -820,12 +932,9 @@ var makeReferrerLeaderboardPageContextSchema = (valueLabel = "ReferrerLeaderboar
   endIndex: import_v42.default.optional(makeNonNegativeIntegerSchema(`${valueLabel}.endIndex`))
 });
 var makeReferralProgramStatusSchema = (_valueLabel = "status") => import_v42.default.enum(ReferralProgramEditionStatuses);
-var makeBaseReferralProgramEditionSummarySchema = (valueLabel) => import_v42.default.object({
+var makeBaseReferralProgramEditionSummarySchema = (valueLabel) => makeBaseReferralProgramEditionConfigSchema(valueLabel).safeExtend({
   awardModel: import_v42.default.string(),
-  slug: import_v42.default.string().min(1, `${valueLabel}.slug must not be empty`),
-  displayName: import_v42.default.string().min(1, `${valueLabel}.displayName must not be empty`),
-  status: makeReferralProgramStatusSchema(`${valueLabel}.status`),
-  rules: makeBaseReferralProgramRulesSchema(`${valueLabel}.rules`)
+  status: makeReferralProgramStatusSchema(`${valueLabel}.status`)
 });
 var makeBaseReferrerLeaderboardPageSchema = (valueLabel) => import_v42.default.object({
   awardModel: import_v42.default.string(),
@@ -1062,6 +1171,11 @@ var buildReferralProgramRulesRevShareCap = (awardPool, minBaseRevenueContributio
   validateReferralProgramRulesRevShareCap(result);
   return result;
 };
+function calcBaseRevenueContribution(rules, duration) {
+  return priceUsdc(
+    rules.baseAnnualRevenueContribution.amount * BigInt(duration) / BigInt(SECONDS_PER_YEAR)
+  );
+}
 function isReferrerQualifiedRevShareCap(referrer, totalBaseRevenueContribution, rules) {
   const isAdminDisqualified = rules.adminActions.some(
     (a) => a.referrer === referrer && a.actionType === AdminActionTypes.Disqualification
@@ -1401,10 +1515,6 @@ var makeReferrerEditionMetricsSchema = (valueLabel = "ReferrerEditionMetrics") =
     };
   });
 };
-var makeReferralProgramEditionSlugSchema = (valueLabel = "ReferralProgramEditionSlug") => import_v45.default.string().min(1, `${valueLabel} must not be empty`).regex(
-  /^[a-z0-9]+(-[a-z0-9]+)*$/,
-  `${valueLabel} must contain only lowercase letters, digits, and hyphens. Must not start or end with a hyphen.`
-);
 var makeReferrerMetricsEditionsResponseOkSchema = (valueLabel = "ReferrerMetricsEditionsResponseOk") => import_v45.default.object({
   responseCode: import_v45.default.literal(ReferrerMetricsEditionsResponseCodes.Ok),
   data: import_v45.default.record(
@@ -1421,12 +1531,7 @@ var makeReferrerMetricsEditionsResponseSchema = (valueLabel = "ReferrerMetricsEd
   makeReferrerMetricsEditionsResponseOkSchema(valueLabel),
   makeReferrerMetricsEditionsResponseErrorSchema(valueLabel)
 ]);
-var makeReferralProgramEditionConfigBaseSchema = (valueLabel) => import_v45.default.object({
-  slug: makeReferralProgramEditionSlugSchema(`${valueLabel}.slug`),
-  displayName: import_v45.default.string().min(1, `${valueLabel}.displayName must not be empty`),
-  rules: makeBaseReferralProgramRulesSchema(`${valueLabel}.rules`)
-});
-var makeReferralProgramEditionConfigSchema = (valueLabel = "ReferralProgramEditionConfig") => makeReferralProgramEditionConfigBaseSchema(valueLabel).safeExtend({
+var makeReferralProgramEditionConfigSchema = (valueLabel = "ReferralProgramEditionConfig") => makeBaseReferralProgramEditionConfigSchema(valueLabel).safeExtend({
   rules: makeReferralProgramRulesSchema(`${valueLabel}.rules`)
 });
 var makeReferralProgramEditionConfigSetArraySchema = (valueLabel = "ReferralProgramEditionConfigSetArray") => {
@@ -1437,7 +1542,7 @@ var makeReferralProgramEditionConfigSetArraySchema = (valueLabel = "ReferralProg
   const looseItemSchema = import_v45.default.looseObject({
     rules: import_v45.default.looseObject({ awardModel: import_v45.default.string() })
   });
-  const unrecognizedBaseSchema = makeReferralProgramEditionConfigBaseSchema(
+  const unrecognizedBaseSchema = makeBaseReferralProgramEditionConfigSchema(
     `${valueLabel}[edition]`
   );
   return import_v45.default.array(looseItemSchema).transform((items, ctx) => {
@@ -1478,6 +1583,15 @@ var makeReferralProgramEditionConfigSetArraySchema = (valueLabel = "ReferralProg
       }
       slugs.add(edition.slug);
     }
+    const overlap = findOverlappingEditionPair(result);
+    if (overlap) {
+      const [a, b] = overlap;
+      ctx.addIssue({
+        code: "custom",
+        message: `${valueLabel}: editions "${a.slug}" and "${b.slug}" have overlapping time ranges for subregistryId ${a.rules.subregistryId.chainId}:${a.rules.subregistryId.address} (startTime and endTime are inclusive)`
+      });
+      return [];
+    }
     return result;
   });
 };
@@ -1518,6 +1632,15 @@ var makeReferralProgramEditionSummarySchema = (valueLabel = "ReferralProgramEdit
 };
 var makeReferralProgramEditionSummariesDataSchema = (valueLabel = "ReferralProgramEditionSummariesData") => import_v45.default.object({
   editions: import_v45.default.array(makeReferralProgramEditionSummarySchema(`${valueLabel}.editions[edition]`))
+}).superRefine((data, ctx) => {
+  const overlap = findOverlappingEditionPair(data.editions);
+  if (!overlap) return;
+  const [a, b] = overlap;
+  ctx.addIssue({
+    code: "custom",
+    path: ["editions"],
+    message: `${valueLabel}: editions "${a.slug}" and "${b.slug}" have overlapping time ranges for subregistryId ${a.rules.subregistryId.chainId}:${a.rules.subregistryId.address} (startTime and endTime are inclusive)`
+  });
 });
 var makeReferralProgramEditionSummariesResponseOkSchema = (valueLabel = "ReferralProgramEditionSummariesResponseOk") => import_v45.default.object({
   responseCode: import_v45.default.literal(ReferralProgramEditionSummariesResponseCodes.Ok),
@@ -1997,31 +2120,6 @@ var buildAggregatedReferrerMetricsPieSplit = (referrers, rules) => {
   return result;
 };
 
-// src/edition.ts
-var REFERRAL_PROGRAM_EDITION_SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-function validateReferralProgramEditionConfigSet(configSet) {
-  const violation = Array.from(configSet.entries()).find(([key, config]) => key !== config.slug);
-  if (violation) {
-    const [key, config] = violation;
-    throw new Error(
-      `Edition config set invariant violation: map key "${key}" does not match config.slug "${config.slug}"`
-    );
-  }
-}
-function buildReferralProgramEditionConfigSet(configs) {
-  const slugCounts = configs.reduce((counts, config) => {
-    counts.set(config.slug, (counts.get(config.slug) || 0) + 1);
-    return counts;
-  }, /* @__PURE__ */ new Map());
-  const duplicates = Array.from(slugCounts.entries()).filter(([_, count]) => count > 1).map(([slug, count]) => `"${slug}" (${count} occurrences)`);
-  if (duplicates.length > 0) {
-    throw new Error(`Duplicate edition config slugs detected: ${duplicates.join(", ")}`);
-  }
-  const configSet = new Map(configs.map((config) => [config.slug, config]));
-  validateReferralProgramEditionConfigSet(configSet);
-  return configSet;
-}
-
 // src/award-models/shared/edition-summary.ts
 var validateBaseReferralProgramEditionSummary = (summary) => {
   if (!REFERRAL_PROGRAM_EDITION_SLUG_PATTERN.test(summary.slug)) {
@@ -2420,8 +2518,9 @@ var validateReferrerMetricsRevShareCap = (metrics, rules) => {
   makePriceUsdcSchema("ReferrerMetricsRevShareCap.totalBaseRevenueContribution").parse(
     metrics.totalBaseRevenueContribution
   );
-  const expectedTotalBaseRevenueContribution = priceUsdc(
-    rules.baseAnnualRevenueContribution.amount * BigInt(metrics.totalIncrementalDuration) / BigInt(SECONDS_PER_YEAR)
+  const expectedTotalBaseRevenueContribution = calcBaseRevenueContribution(
+    rules,
+    metrics.totalIncrementalDuration
   );
   if (metrics.totalBaseRevenueContribution.amount !== expectedTotalBaseRevenueContribution.amount) {
     throw new Error(
@@ -2430,8 +2529,9 @@ var validateReferrerMetricsRevShareCap = (metrics, rules) => {
   }
 };
 var buildReferrerMetricsRevShareCap = (metrics, rules) => {
-  const totalBaseRevenueContribution = priceUsdc(
-    rules.baseAnnualRevenueContribution.amount * BigInt(metrics.totalIncrementalDuration) / BigInt(SECONDS_PER_YEAR)
+  const totalBaseRevenueContribution = calcBaseRevenueContribution(
+    rules,
+    metrics.totalIncrementalDuration
   );
   const result = {
     ...metrics,
@@ -2605,71 +2705,71 @@ function sortReferralEvents(events) {
 }
 
 // src/award-models/rev-share-cap/leaderboard.ts
-var bigintMin = (a, b) => a < b ? a : b;
 var buildReferrerLeaderboardRevShareCap = (events, rules, accurateAsOf) => {
   const sortedEvents = sortReferralEvents(events);
   const referrerStates = /* @__PURE__ */ new Map();
-  let awardPoolRemaining = rules.awardPool.amount;
+  let awardPoolRemaining = rules.awardPool;
   for (const event of sortedEvents) {
-    const referrer = event.referrer;
-    let state = referrerStates.get(referrer);
-    if (!state) {
-      state = {
+    const referrerId = event.referrer;
+    let referrerState = referrerStates.get(referrerId);
+    if (!referrerState) {
+      referrerState = {
         totalReferrals: 0,
         totalIncrementalDuration: 0,
-        totalRevenueContributionAmount: 0n,
-        wasQualified: false,
-        cappedAwardAmount: 0n
+        totalRevenueContribution: priceEth(0n),
+        hasQualified: false,
+        cappedAward: priceUsdc(0n)
       };
-      referrerStates.set(referrer, state);
-    }
-    state.totalReferrals += 1;
-    state.totalIncrementalDuration += event.incrementalDuration;
-    state.totalRevenueContributionAmount += event.incrementalRevenueContribution.amount;
-    const totalBaseRevenueAmount = rules.baseAnnualRevenueContribution.amount * BigInt(state.totalIncrementalDuration) / BigInt(SECONDS_PER_YEAR);
-    const isNowQualified = isReferrerQualifiedRevShareCap(
-      referrer,
-      priceUsdc(totalBaseRevenueAmount),
-      rules
-    );
-    if (isNowQualified && !state.wasQualified) {
-      const accumulatedUncappedAward = scalePrice(
-        priceUsdc(totalBaseRevenueAmount),
-        rules.maxBaseRevenueShare
-      ).amount;
-      const incrementalCappedAward = bigintMin(accumulatedUncappedAward, awardPoolRemaining);
-      state.cappedAwardAmount += incrementalCappedAward;
-      awardPoolRemaining -= incrementalCappedAward;
-      state.wasQualified = true;
-    } else if (state.wasQualified) {
-      const incrementalBaseRevenueAmount = rules.baseAnnualRevenueContribution.amount * BigInt(event.incrementalDuration) / BigInt(SECONDS_PER_YEAR);
+      referrerStates.set(referrerId, referrerState);
+    }
+    referrerState.totalReferrals += 1;
+    referrerState.totalIncrementalDuration += event.incrementalDuration;
+    referrerState.totalRevenueContribution = addPrices(
+      referrerState.totalRevenueContribution,
+      event.incrementalRevenueContribution
+    );
+    const totalBaseRevenue = calcBaseRevenueContribution(
+      rules,
+      referrerState.totalIncrementalDuration
+    );
+    const isNowQualified = isReferrerQualifiedRevShareCap(referrerId, totalBaseRevenue, rules);
+    if (isNowQualified && !referrerState.hasQualified) {
+      const accumulatedUncappedAward = scalePrice(totalBaseRevenue, rules.maxBaseRevenueShare);
+      const incrementalCappedAward = minPrice(accumulatedUncappedAward, awardPoolRemaining);
+      referrerState.cappedAward = addPrices(referrerState.cappedAward, incrementalCappedAward);
+      awardPoolRemaining = subtractPrice(awardPoolRemaining, incrementalCappedAward);
+      referrerState.hasQualified = true;
+    } else if (referrerState.hasQualified) {
+      const incrementalBaseRevenue = calcBaseRevenueContribution(rules, event.incrementalDuration);
       const incrementalUncappedAward = scalePrice(
-        priceUsdc(incrementalBaseRevenueAmount),
+        incrementalBaseRevenue,
         rules.maxBaseRevenueShare
-      ).amount;
-      const incrementalCappedAward = bigintMin(incrementalUncappedAward, awardPoolRemaining);
-      state.cappedAwardAmount += incrementalCappedAward;
-      awardPoolRemaining -= incrementalCappedAward;
+      );
+      const incrementalCappedAward = minPrice(incrementalUncappedAward, awardPoolRemaining);
+      referrerState.cappedAward = addPrices(referrerState.cappedAward, incrementalCappedAward);
+      awardPoolRemaining = subtractPrice(awardPoolRemaining, incrementalCappedAward);
     }
   }
-  const sortedEntries = [...referrerStates.entries()].sort(([a, stateA], [b, stateB]) => {
-    if (stateB.cappedAwardAmount !== stateA.cappedAwardAmount) {
-      return stateB.cappedAwardAmount > stateA.cappedAwardAmount ? 1 : -1;
-    }
-    if (stateB.totalIncrementalDuration !== stateA.totalIncrementalDuration) {
-      return stateB.totalIncrementalDuration - stateA.totalIncrementalDuration;
+  const sortedEntries = [...referrerStates.entries()].sort(
+    ([referrerIdA, referrerStateA], [referrerIdB, referrerStateB]) => {
+      if (referrerStateB.cappedAward.amount !== referrerStateA.cappedAward.amount) {
+        return referrerStateB.cappedAward.amount > referrerStateA.cappedAward.amount ? 1 : -1;
+      }
+      if (referrerStateB.totalIncrementalDuration !== referrerStateA.totalIncrementalDuration) {
+        return referrerStateB.totalIncrementalDuration - referrerStateA.totalIncrementalDuration;
+      }
+      if (referrerIdB > referrerIdA) return 1;
+      if (referrerIdB < referrerIdA) return -1;
+      return 0;
     }
-    if (b > a) return 1;
-    if (b < a) return -1;
-    return 0;
-  });
+  );
   const awardedReferrers = sortedEntries.map(
-    ([referrerAddr, state], index) => {
+    ([referrerId, referrerState], index) => {
       const baseMetrics = buildReferrerMetrics(
-        referrerAddr,
-        state.totalReferrals,
-        state.totalIncrementalDuration,
-        priceEth(state.totalRevenueContributionAmount)
+        referrerId,
+        referrerState.totalReferrals,
+        referrerState.totalIncrementalDuration,
+        referrerState.totalRevenueContribution
       );
       const revShareMetrics = buildReferrerMetricsRevShareCap(baseMetrics, rules);
       const rankedMetrics = buildRankedReferrerMetricsRevShareCap(
@@ -2684,14 +2784,14 @@ var buildReferrerLeaderboardRevShareCap = (events, rules, accurateAsOf) => {
       return buildAwardedReferrerMetricsRevShareCap(
         rankedMetrics,
         uncappedAward,
-        priceUsdc(state.cappedAwardAmount),
+        referrerState.cappedAward,
         rules
       );
     }
   );
   const aggregatedMetrics = buildAggregatedReferrerMetricsRevShareCap(
     awardedReferrers,
-    priceUsdc(awardPoolRemaining)
+    awardPoolRemaining
   );
   const referrers = new Map(awardedReferrers.map((r) => [r.referrer, r]));
   return { awardModel: rules.awardModel, rules, aggregatedMetrics, referrers, accurateAsOf };