@namehash/ens-referrals 1.10.0 → 1.11.0

package/dist/index.js

@@ -353,7 +353,8 @@ function scaleBigintByNumber(value, scaleFactor) {
 var CurrencyIds = {
   ETH: "ETH",
   USDC: "USDC",
-  DAI: "DAI"
+  DAI: "DAI",
+  ENSTokens: "ENSTokens"
 };
 var currencyInfo = {
   [CurrencyIds.ETH]: {
@@ -370,6 +371,11 @@ var currencyInfo = {
     id: CurrencyIds.DAI,
     name: "Dai Stablecoin",
     decimals: 18
+  },
+  [CurrencyIds.ENSTokens]: {
+    id: CurrencyIds.ENSTokens,
+    name: "$ENS Tokens",
+    decimals: 18
   }
 };
 function priceEth(amount) {
@@ -384,6 +390,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 {
@@ -465,6 +510,62 @@ import z3 from "zod/v4";
 // src/award-models/shared/api/zod-schemas.ts
 import z2 from "zod/v4";
 
+// 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);
@@ -671,6 +772,15 @@ var calcBaseReferralProgramEditionStatus = (rules, now) => {
 };
 
 // src/award-models/shared/api/zod-schemas.ts
+var makeReferralProgramEditionSlugSchema = (valueLabel = "ReferralProgramEditionSlug") => z2.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") => z2.object({
+  slug: makeReferralProgramEditionSlugSchema(`${valueLabel}.slug`),
+  displayName: z2.string().min(1, `${valueLabel}.displayName must not be empty`),
+  rules: makeBaseReferralProgramRulesSchema(`${valueLabel}.rules`)
+});
 var makeBaseReferralProgramRulesSchema = (valueLabel) => z2.object({
   awardModel: z2.string(),
   startTime: makeUnixTimestampSchema(`${valueLabel}.startTime`),
@@ -696,12 +806,9 @@ var makeReferrerLeaderboardPageContextSchema = (valueLabel = "ReferrerLeaderboar
   endIndex: z2.optional(makeNonNegativeIntegerSchema(`${valueLabel}.endIndex`))
 });
 var makeReferralProgramStatusSchema = (_valueLabel = "status") => z2.enum(ReferralProgramEditionStatuses);
-var makeBaseReferralProgramEditionSummarySchema = (valueLabel) => z2.object({
+var makeBaseReferralProgramEditionSummarySchema = (valueLabel) => makeBaseReferralProgramEditionConfigSchema(valueLabel).safeExtend({
   awardModel: z2.string(),
-  slug: z2.string().min(1, `${valueLabel}.slug must not be empty`),
-  displayName: z2.string().min(1, `${valueLabel}.displayName must not be empty`),
-  status: makeReferralProgramStatusSchema(`${valueLabel}.status`),
-  rules: makeBaseReferralProgramRulesSchema(`${valueLabel}.rules`)
+  status: makeReferralProgramStatusSchema(`${valueLabel}.status`)
 });
 var makeBaseReferrerLeaderboardPageSchema = (valueLabel) => z2.object({
   awardModel: z2.string(),
@@ -938,6 +1045,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
@@ -1277,10 +1389,6 @@ var makeReferrerEditionMetricsSchema = (valueLabel = "ReferrerEditionMetrics") =
     };
   });
 };
-var makeReferralProgramEditionSlugSchema = (valueLabel = "ReferralProgramEditionSlug") => z5.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") => z5.object({
   responseCode: z5.literal(ReferrerMetricsEditionsResponseCodes.Ok),
   data: z5.record(
@@ -1297,12 +1405,7 @@ var makeReferrerMetricsEditionsResponseSchema = (valueLabel = "ReferrerMetricsEd
   makeReferrerMetricsEditionsResponseOkSchema(valueLabel),
   makeReferrerMetricsEditionsResponseErrorSchema(valueLabel)
 ]);
-var makeReferralProgramEditionConfigBaseSchema = (valueLabel) => z5.object({
-  slug: makeReferralProgramEditionSlugSchema(`${valueLabel}.slug`),
-  displayName: z5.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") => {
@@ -1313,7 +1416,7 @@ var makeReferralProgramEditionConfigSetArraySchema = (valueLabel = "ReferralProg
   const looseItemSchema = z5.looseObject({
     rules: z5.looseObject({ awardModel: z5.string() })
   });
-  const unrecognizedBaseSchema = makeReferralProgramEditionConfigBaseSchema(
+  const unrecognizedBaseSchema = makeBaseReferralProgramEditionConfigSchema(
     `${valueLabel}[edition]`
   );
   return z5.array(looseItemSchema).transform((items, ctx) => {
@@ -1354,6 +1457,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;
   });
 };
@@ -1394,6 +1506,15 @@ var makeReferralProgramEditionSummarySchema = (valueLabel = "ReferralProgramEdit
 };
 var makeReferralProgramEditionSummariesDataSchema = (valueLabel = "ReferralProgramEditionSummariesData") => z5.object({
   editions: z5.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") => z5.object({
   responseCode: z5.literal(ReferralProgramEditionSummariesResponseCodes.Ok),
@@ -1873,31 +1994,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)) {
@@ -2296,8 +2392,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(
@@ -2306,8 +2403,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,
@@ -2481,71 +2579,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(
@@ -2560,14 +2658,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 };
@@ -3032,6 +3130,7 @@ export {
   buildUnrankedReferrerMetricsPieSplit,
   buildUnrankedReferrerMetricsRevShareCap,
   calcBaseReferralProgramEditionStatus,
+  calcBaseRevenueContribution,
   calcReferralProgramEditionStatusPieSplit,
   calcReferralProgramEditionStatusRevShareCap,
   calcReferrerAwardPoolSharePieSplit,
@@ -3041,6 +3140,7 @@ export {
   deserializeReferralProgramEditionSummariesResponse,
   deserializeReferrerLeaderboardPageResponse,
   deserializeReferrerMetricsEditionsResponse,
+  findOverlappingEditionPair,
   getReferrerEditionMetrics,
   getReferrerLeaderboardPage,
   isFiniteNonNegativeNumber,