@namehash/ens-referrals 1.10.1 → 1.11.1

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) {
@@ -484,6 +490,34 @@ var makeAccountIdSchema = (valueLabel = "AccountId") => z.strictObject({
   address: makeNormalizedAddressSchema(`${valueLabel} address`)
 });
 
+// ../ensnode-sdk/src/indexing-status/omnichain-indexing-status-snapshot.ts
+var OmnichainIndexingStatusIds = {
+  /**
+   * Represents that omnichain indexing is not ready to begin yet because
+   * ENSIndexer is in its initialization phase and the data to build a "true"
+   * {@link OmnichainIndexingStatusSnapshot} is still being loaded.
+   */
+  Unstarted: "omnichain-unstarted",
+  /**
+   * Represents that omnichain indexing is in an overall "backfill" status because
+   * - At least one indexed chain has a `chainStatus` of
+   *   {@link ChainIndexingStatusIds.Backfill}; and
+   * - No indexed chain has a `chainStatus` of {@link ChainIndexingStatusIds.Following}.
+   */
+  Backfill: "omnichain-backfill",
+  /**
+   * Represents that omnichain indexing is in an overall "following" status because
+   * at least one indexed chain has a `chainStatus` of
+   * {@link ChainIndexingStatusIds.Following}.
+   */
+  Following: "omnichain-following",
+  /**
+   * Represents that omnichain indexing has completed because all indexed chains have
+   * a `chainStatus` of {@link ChainIndexingStatusIds.Completed}.
+   */
+  Completed: "omnichain-completed"
+};
+
 // ../ensnode-sdk/src/shared/serialize.ts
 function serializePrice(price) {
   return {
@@ -504,6 +538,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);
@@ -710,6 +800,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`),
@@ -735,12 +834,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(),
@@ -1321,10 +1417,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(
@@ -1341,12 +1433,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") => {
@@ -1357,7 +1444,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) => {
@@ -1398,6 +1485,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;
   });
 };
@@ -1438,6 +1534,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),
@@ -1503,6 +1608,36 @@ ${prettifyError(parsed.error)}
   return parsed.data;
 }
 
+// src/api/prerequisites.ts
+var ensAnalyticsRequiredPlugins = [
+  "subgraph" /* Subgraph */,
+  "basenames" /* Basenames */,
+  "lineanames" /* Lineanames */,
+  "registrars" /* Registrars */
+];
+function hasEnsAnalyticsConfigSupport(config) {
+  const supported = ensAnalyticsRequiredPlugins.every((plugin) => config.plugins.includes(plugin));
+  if (supported) return { supported };
+  return {
+    supported: false,
+    reason: `The ENSAnalytics API requires all of the following plugins to be activated in the connected ENSNode's Config: ${ensAnalyticsRequiredPlugins.map((plugin) => `'${plugin}'`).join(", ")}.`
+  };
+}
+var ensAnalyticsSupportedIndexingStatusIds = [
+  OmnichainIndexingStatusIds.Completed,
+  OmnichainIndexingStatusIds.Following
+];
+function hasEnsAnalyticsIndexingStatusSupport(omnichainIndexingStatusId) {
+  const supported = ensAnalyticsSupportedIndexingStatusIds.some(
+    (supportedIndexingStatusId) => supportedIndexingStatusId === omnichainIndexingStatusId
+  );
+  if (supported) return { supported };
+  return {
+    supported: false,
+    reason: `The ENSAnalytics API requires the connected ENSNode's Indexing Status to be one of the following: ${ensAnalyticsSupportedIndexingStatusIds.join(", ")}.`
+  };
+}
+
 // src/award-models/pie-split/api/serialize.ts
 function serializeReferralProgramRulesPieSplit(rules) {
   return {
@@ -1917,31 +2052,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)) {
@@ -2237,7 +2347,7 @@ var buildUnrankedReferrerMetricsPieSplit = (referrer) => {
 };
 
 // src/award-models/pie-split/leaderboard.ts
-var buildReferrerLeaderboardPieSplit = (allReferrers, rules, accurateAsOf) => {
+var buildReferralEditionSnapshotPieSplit = (allReferrers, rules, accurateAsOf) => {
   assertLeaderboardInputs(allReferrers, rules, accurateAsOf);
   const sortedReferrers = sortReferrerMetrics(allReferrers);
   const scoredReferrers = sortedReferrers.map((r) => buildScoredReferrerMetricsPieSplit(r));
@@ -2249,7 +2359,14 @@ var buildReferrerLeaderboardPieSplit = (allReferrers, rules, accurateAsOf) => {
     (r) => buildAwardedReferrerMetricsPieSplit(r, aggregatedMetrics, rules)
   );
   const referrers = new Map(awardedReferrers.map((r) => [r.referrer, r]));
-  return { awardModel: rules.awardModel, rules, aggregatedMetrics, referrers, accurateAsOf };
+  const leaderboard = {
+    awardModel: rules.awardModel,
+    rules,
+    aggregatedMetrics,
+    referrers,
+    accurateAsOf
+  };
+  return { awardModel: rules.awardModel, leaderboard };
 };
 
 // src/award-models/pie-split/leaderboard-page.ts
@@ -2527,9 +2644,14 @@ function sortReferralEvents(events) {
 }
 
 // src/award-models/rev-share-cap/leaderboard.ts
-var buildReferrerLeaderboardRevShareCap = (events, rules, accurateAsOf) => {
+var buildReferralEditionSnapshotRevShareCap = (events, rules, accurateAsOf) => {
   const sortedEvents = sortReferralEvents(events);
+  const adminActionByReferrer = /* @__PURE__ */ new Map();
+  for (const action of rules.adminActions) {
+    adminActionByReferrer.set(action.referrer, action);
+  }
   const referrerStates = /* @__PURE__ */ new Map();
+  const accountingRecords = [];
   let awardPoolRemaining = rules.awardPool;
   for (const event of sortedEvents) {
     const referrerId = event.referrer;
@@ -2550,27 +2672,65 @@ var buildReferrerLeaderboardRevShareCap = (events, rules, accurateAsOf) => {
       referrerState.totalRevenueContribution,
       event.incrementalRevenueContribution
     );
-    const totalBaseRevenue = calcBaseRevenueContribution(
+    const hasQualifiedBefore = referrerState.hasQualified;
+    const awardPoolRemainingBefore = awardPoolRemaining;
+    const adminAction = adminActionByReferrer.get(referrerId);
+    const adminDisqualification = adminAction?.actionType === AdminActionTypes.Disqualification ? adminAction : null;
+    const accumulatedBaseRevenueContribution = 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);
+    const incrementalBaseRevenueContribution = calcBaseRevenueContribution(
+      rules,
+      event.incrementalDuration
+    );
+    const isNowQualified = isReferrerQualifiedRevShareCap(
+      referrerId,
+      accumulatedBaseRevenueContribution,
+      rules
+    );
+    let incrementalTentativeAward = priceUsdc(0n);
+    if (isNowQualified && !hasQualifiedBefore) {
+      const accumulatedUncappedAward = scalePrice(
+        accumulatedBaseRevenueContribution,
+        rules.maxBaseRevenueShare
+      );
+      incrementalTentativeAward = minPrice(accumulatedUncappedAward, awardPoolRemainingBefore);
       referrerState.hasQualified = true;
-    } else if (referrerState.hasQualified) {
-      const incrementalBaseRevenue = calcBaseRevenueContribution(rules, event.incrementalDuration);
+    } else if (hasQualifiedBefore) {
       const incrementalUncappedAward = scalePrice(
-        incrementalBaseRevenue,
+        incrementalBaseRevenueContribution,
         rules.maxBaseRevenueShare
       );
-      const incrementalCappedAward = minPrice(incrementalUncappedAward, awardPoolRemaining);
-      referrerState.cappedAward = addPrices(referrerState.cappedAward, incrementalCappedAward);
-      awardPoolRemaining = subtractPrice(awardPoolRemaining, incrementalCappedAward);
+      incrementalTentativeAward = minPrice(incrementalUncappedAward, awardPoolRemainingBefore);
     }
+    referrerState.cappedAward = addPrices(referrerState.cappedAward, incrementalTentativeAward);
+    awardPoolRemaining = subtractPrice(awardPoolRemaining, incrementalTentativeAward);
+    const tentativeAward = {
+      incrementalRevenueContribution: event.incrementalRevenueContribution,
+      accumulatedRevenueContribution: referrerState.totalRevenueContribution,
+      incrementalBaseRevenueContribution,
+      accumulatedBaseRevenueContribution,
+      awardPoolRemaining: awardPoolRemainingBefore,
+      disqualified: adminDisqualification !== null,
+      ...adminDisqualification !== null && {
+        disqualificationReason: adminDisqualification.reason
+      },
+      maxRevShare: rules.maxBaseRevenueShare,
+      effectiveBaseRevShare: incrementalBaseRevenueContribution.amount === 0n ? 0 : Number(incrementalTentativeAward.amount) / Number(incrementalBaseRevenueContribution.amount),
+      incrementalTentativeAward
+    };
+    accountingRecords.push({
+      registrarActionId: event.id,
+      timestamp: event.timestamp,
+      name: event.name,
+      actionType: event.actionType,
+      transactionHash: event.transactionHash,
+      registrant: event.registrant,
+      referrer: referrerId,
+      incrementalDuration: event.incrementalDuration,
+      tentativeAward
+    });
   }
   const sortedEntries = [...referrerStates.entries()].sort(
     ([referrerIdA, referrerStateA], [referrerIdB, referrerStateB]) => {
@@ -2616,7 +2776,17 @@ var buildReferrerLeaderboardRevShareCap = (events, rules, accurateAsOf) => {
     awardPoolRemaining
   );
   const referrers = new Map(awardedReferrers.map((r) => [r.referrer, r]));
-  return { awardModel: rules.awardModel, rules, aggregatedMetrics, referrers, accurateAsOf };
+  return {
+    awardModel: rules.awardModel,
+    leaderboard: {
+      awardModel: rules.awardModel,
+      rules,
+      aggregatedMetrics,
+      referrers,
+      accurateAsOf
+    },
+    accountingRecords
+  };
 };
 
 // src/award-models/rev-share-cap/leaderboard-page.ts
@@ -3065,13 +3235,13 @@ export {
   buildLeaderboardPageRevShareCap,
   buildRankedReferrerMetricsPieSplit,
   buildRankedReferrerMetricsRevShareCap,
+  buildReferralEditionSnapshotPieSplit,
+  buildReferralEditionSnapshotRevShareCap,
   buildReferralProgramEditionConfigSet,
   buildReferralProgramRulesPieSplit,
   buildReferralProgramRulesRevShareCap,
   buildReferrerLeaderboardPageContext,
   buildReferrerLeaderboardPageParams,
-  buildReferrerLeaderboardPieSplit,
-  buildReferrerLeaderboardRevShareCap,
   buildReferrerMetrics,
   buildReferrerMetricsRevShareCap,
   buildScoredReferrerMetricsPieSplit,
@@ -3088,8 +3258,11 @@ export {
   deserializeReferralProgramEditionSummariesResponse,
   deserializeReferrerLeaderboardPageResponse,
   deserializeReferrerMetricsEditionsResponse,
+  findOverlappingEditionPair,
   getReferrerEditionMetrics,
   getReferrerLeaderboardPage,
+  hasEnsAnalyticsConfigSupport,
+  hasEnsAnalyticsIndexingStatusSupport,
   isFiniteNonNegativeNumber,
   isInteger,
   isNonNegativeInteger,