@namehash/ens-referrals 1.7.0 → 1.8.0

package/dist/v1/index.d.cts

@@ -49,6 +49,12 @@ interface BaseReferralProgramRules {
      * @example new URL("https://ensawards.org/ens-holiday-awards-rules")
      */
     rulesUrl: URL;
+    /**
+     * Whether the awards for this edition have been distributed.
+     *
+     * When `true` and `now > endTime`, the status transitions from `AwardsReview` to `Closed`.
+     */
+    areAwardsDistributed: boolean;
 }
 /**
  * Rules for a referral program edition whose `awardModel` is not recognized by this client version.
@@ -95,7 +101,7 @@ interface ReferralProgramRulesPieSplit extends BaseReferralProgramRules {
     maxQualifiedReferrers: number;
 }
 declare const validateReferralProgramRulesPieSplit: (rules: ReferralProgramRulesPieSplit) => void;
-declare const buildReferralProgramRulesPieSplit: (totalAwardPoolValue: PriceUsdc, maxQualifiedReferrers: number, startTime: UnixTimestamp, endTime: UnixTimestamp, subregistryId: AccountId, rulesUrl: URL) => ReferralProgramRulesPieSplit;
+declare const buildReferralProgramRulesPieSplit: (totalAwardPoolValue: PriceUsdc, maxQualifiedReferrers: number, startTime: UnixTimestamp, endTime: UnixTimestamp, subregistryId: AccountId, rulesUrl: URL, areAwardsDistributed: boolean) => ReferralProgramRulesPieSplit;
 
 /**
  * An admin-imposed disqualification entry of a specific referrer in an edition.
@@ -153,7 +159,7 @@ interface ReferralProgramRulesRevShareLimit extends BaseReferralProgramRules {
     disqualifications: ReferralProgramEditionDisqualification[];
 }
 declare const validateReferralProgramRulesRevShareLimit: (rules: ReferralProgramRulesRevShareLimit) => void;
-declare const buildReferralProgramRulesRevShareLimit: (totalAwardPoolValue: PriceUsdc, minQualifiedRevenueContribution: PriceUsdc, qualifiedRevenueShare: number, startTime: UnixTimestamp, endTime: UnixTimestamp, subregistryId: AccountId, rulesUrl: URL, disqualifications?: ReferralProgramEditionDisqualification[]) => ReferralProgramRulesRevShareLimit;
+declare const buildReferralProgramRulesRevShareLimit: (totalAwardPoolValue: PriceUsdc, minQualifiedRevenueContribution: PriceUsdc, qualifiedRevenueShare: number, startTime: UnixTimestamp, endTime: UnixTimestamp, subregistryId: AccountId, rulesUrl: URL, areAwardsDistributed: boolean, disqualifications?: ReferralProgramEditionDisqualification[]) => ReferralProgramRulesRevShareLimit;
 /**
  * Determine if a referrer is qualified under rev-share-limit rules.
  *
@@ -194,6 +200,13 @@ type ReferralProgramRules = ReferralProgramRulesPieSplit | ReferralProgramRulesR
  * @example "holiday-special" // Custom named edition
  */
 type ReferralProgramEditionSlug = string;
+/**
+ * Regex pattern that all {@link ReferralProgramEditionSlug} values must match.
+ *
+ * Allows lowercase letters (a-z), digits (0-9), and hyphens (-).
+ * Must not start or end with a hyphen.
+ */
+declare const REFERRAL_PROGRAM_EDITION_SLUG_PATTERN: RegExp;
 /**
  * Represents a referral program edition configuration.
  */
@@ -474,38 +487,6 @@ declare const validateAggregatedReferrerMetricsPieSplit: (metrics: AggregatedRef
  */
 declare const buildAggregatedReferrerMetricsPieSplit: (referrers: RankedReferrerMetricsPieSplit[], rules: ReferralProgramRulesPieSplit) => AggregatedReferrerMetricsPieSplit;
 
-/**
- * The type of referral program's status.
- */
-declare const ReferralProgramStatuses: {
-    /**
-     * Represents a referral program that has been announced, but hasn't started yet.
-     */
-    readonly Scheduled: "Scheduled";
-    /**
-     * Represents a currently ongoing referral program.
-     */
-    readonly Active: "Active";
-    /**
-     * Represents a referral program that has already ended.
-     */
-    readonly Closed: "Closed";
-};
-/**
- * The derived string union of possible {@link ReferralProgramStatuses}.
- */
-type ReferralProgramStatusId = (typeof ReferralProgramStatuses)[keyof typeof ReferralProgramStatuses];
-/**
- * Calculate the status of the referral program based on the current date
- * and program's timeframe available in its rules.
- *
- * @param referralProgramRules - Related referral program's rules containing
- * program's start date and end date.
- *
- * @param now - Current date in {@link UnixTimestamp} format.
- */
-declare const calcReferralProgramStatus: (referralProgramRules: ReferralProgramRules, now: UnixTimestamp) => ReferralProgramStatusId;
-
 /**
  * The type of referrer edition metrics data.
  */
@@ -545,6 +526,51 @@ interface ReferrerEditionMetricsUnrecognized {
     originalAwardModel: string;
 }
 
+/**
+ * The type of referral program edition's status.
+ */
+declare const ReferralProgramEditionStatuses: {
+    /**
+     * Represents a referral program edition that has been announced, but hasn't started yet.
+     */
+    readonly Scheduled: "Scheduled";
+    /**
+     * Represents a currently ongoing referral program edition.
+     */
+    readonly Active: "Active";
+    /**
+     * Represents a referral program edition that is still within its active window
+     * but whose award pool has been fully consumed.
+     *
+     * @note Not all award models may support this status.
+     */
+    readonly Exhausted: "Exhausted";
+    /**
+     * Represents a referral program edition that has passed its end time but whose awards have not yet
+     * been distributed. The edition is in a review window before full closure.
+     *
+     * Transitions to {@link ReferralProgramEditionStatuses.Closed} once `areAwardsDistributed` is set to `true`.
+     */
+    readonly AwardsReview: "AwardsReview";
+    /**
+     * Represents a referral program edition that has already ended and whose awards have been distributed.
+     */
+    readonly Closed: "Closed";
+};
+/**
+ * The derived string union of possible {@link ReferralProgramEditionStatuses}.
+ */
+type ReferralProgramEditionStatusId = (typeof ReferralProgramEditionStatuses)[keyof typeof ReferralProgramEditionStatuses];
+/**
+ * Calculate the base status of a referral program edition using only its rules and
+ * the current time (makes no consideration of the awards possibly being exhausted).
+ *
+ * @param rules - Related referral program's rules containing program's start/end date and
+ *   `areAwardsDistributed` flag.
+ * @param now - Current date in {@link UnixTimestamp} format.
+ */
+declare const calcBaseReferralProgramEditionStatus: (rules: BaseReferralProgramRules, now: UnixTimestamp) => ReferralProgramEditionStatusId;
+
 /**
  * Referrer edition metrics data for a specific referrer address on the pie-split leaderboard.
  *
@@ -583,10 +609,10 @@ interface ReferrerEditionMetricsRankedPieSplit {
      */
     aggregatedMetrics: AggregatedReferrerMetricsPieSplit;
     /**
-     * The status of the referral program ("Scheduled", "Active", or "Closed")
+     * The status of the referral program edition
      * calculated based on the program's timing relative to {@link accurateAsOf}.
      */
-    status: ReferralProgramStatusId;
+    status: ReferralProgramEditionStatusId;
     /**
      * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerEditionMetricsRankedPieSplit} was accurate as of.
      */
@@ -629,10 +655,10 @@ interface ReferrerEditionMetricsUnrankedPieSplit {
      */
     aggregatedMetrics: AggregatedReferrerMetricsPieSplit;
     /**
-     * The status of the referral program ("Scheduled", "Active", or "Closed")
+     * The status of the referral program edition
      * calculated based on the program's timing relative to {@link accurateAsOf}.
      */
-    status: ReferralProgramStatusId;
+    status: ReferralProgramEditionStatusId;
     /**
      * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerEditionMetricsUnrankedPieSplit} was accurate as of.
      */
@@ -645,6 +671,53 @@ interface ReferrerEditionMetricsUnrankedPieSplit {
  */
 type ReferrerEditionMetricsPieSplit = ReferrerEditionMetricsRankedPieSplit | ReferrerEditionMetricsUnrankedPieSplit;
 
+/**
+ * Base fields shared by all edition summary variants.
+ */
+interface BaseReferralProgramEditionSummary {
+    /**
+     * Discriminant: identifies the award model for this edition.
+     *
+     * @invariant Always equals `rules.awardModel`.
+     */
+    awardModel: ReferralProgramAwardModel;
+    /**
+     * Unique slug identifier for the edition.
+     */
+    slug: ReferralProgramEditionSlug;
+    /**
+     * Human-readable display name for the edition.
+     */
+    displayName: string;
+    /**
+     * The current runtime status of the edition.
+     */
+    status: ReferralProgramEditionStatusId;
+    /**
+     * The rules for this edition. Per-model subtypes narrow this to their specific rules type.
+     */
+    rules: BaseReferralProgramRules;
+}
+/**
+ * Edition summary for an edition whose `awardModel` is not recognized by this client version.
+ *
+ * @remarks
+ * This is a **client-side forward-compatibility** type only. It is never serialized or produced
+ * by the server. When the server sends a new award model, older clients preserve the edition
+ * summary rather than crashing, and downstream code should handle it gracefully.
+ */
+interface ReferralProgramEditionSummaryUnrecognized extends BaseReferralProgramEditionSummary {
+    /**
+     * Discriminant — always `"unrecognized"`.
+     */
+    awardModel: typeof ReferralProgramAwardModels.Unrecognized;
+    /**
+     * The unrecognized rules — preserves `originalAwardModel` for logging/debugging.
+     */
+    rules: ReferralProgramRulesUnrecognized;
+}
+declare const validateBaseReferralProgramEditionSummary: (summary: BaseReferralProgramEditionSummary) => void;
+
 /**
  * Represents a leaderboard with the pie-split award model for any number of referrers.
  */
@@ -684,6 +757,28 @@ interface ReferrerLeaderboardPieSplit {
 }
 declare const buildReferrerLeaderboardPieSplit: (allReferrers: ReferrerMetrics[], rules: ReferralProgramRulesPieSplit, accurateAsOf: UnixTimestamp) => ReferrerLeaderboardPieSplit;
 
+/**
+ * Edition summary for a `pie-split` referral program edition.
+ */
+interface ReferralProgramEditionSummaryPieSplit extends BaseReferralProgramEditionSummary {
+    /**
+     * Discriminant — always `"pie-split"`.
+     *
+     * @invariant Always equals `rules.awardModel` ({@link ReferralProgramAwardModels.PieSplit}).
+     */
+    awardModel: typeof ReferralProgramAwardModels.PieSplit;
+    /**
+     * The pie-split rules for this edition.
+     */
+    rules: ReferralProgramRulesPieSplit;
+}
+declare const validateEditionSummaryPieSplit: (summary: ReferralProgramEditionSummaryPieSplit) => void;
+/**
+ * Build a {@link ReferralProgramEditionSummaryPieSplit} from a pie-split edition config and the
+ * edition's leaderboard.
+ */
+declare function buildEditionSummaryPieSplit(slug: ReferralProgramEditionSlug, displayName: string, rules: ReferralProgramRulesPieSplit, leaderboard: ReferrerLeaderboardPieSplit): ReferralProgramEditionSummaryPieSplit;
+
 /**
  * Extends {@link ReferrerMetrics} with computed base revenue contribution.
  */
@@ -841,15 +936,10 @@ interface ReferralEvent {
     /**
      * Registrar action ID.
      *
-     * A deterministic and globally unique identifier for the "logical registrar action"
-     * associated with the ReferralEvent.
-     *
-     * A Ponder-encoded checkpoint string that uniquely and deterministically identifies
-     * this event. Encodes all ordering-relevant properties:
-     * `blockTimestamp → chainId → blockNumber → transactionIndex → eventType → eventIndex`
-     *
-     * This field alone is sufficient to establish a total chronological ordering over
-     * all referral events.
+     * @invariant Deterministic and globally unique identifier for the "logical registrar action"
+     *   associated with this ReferralEvent.
+     * @invariant Sorting by this value achieves a chronological ordering of each registrar action
+     *   by the order they were executed onchain.
      */
     id: string;
     /**
@@ -1003,10 +1093,9 @@ interface BaseReferrerLeaderboardPage {
      */
     pageContext: ReferrerLeaderboardPageContext;
     /**
-     * The status of the referral program ("Scheduled", "Active", or "Closed")
-     * calculated based on the program's timing relative to {@link accurateAsOf}.
+     * The status of the referral program edition.
      */
-    status: ReferralProgramStatusId;
+    status: ReferralProgramEditionStatusId;
     /**
      * The {@link UnixTimestamp} of when the data used to build this page was accurate as of.
      */
@@ -1124,6 +1213,12 @@ interface SerializedReferrerEditionMetricsUnrankedPieSplit extends Omit<Referrer
  * Serialized representation of {@link ReferrerEditionMetricsPieSplit}.
  */
 type SerializedReferrerEditionMetricsPieSplit = SerializedReferrerEditionMetricsRankedPieSplit | SerializedReferrerEditionMetricsUnrankedPieSplit;
+/**
+ * Serialized representation of {@link ReferralProgramEditionSummaryPieSplit}.
+ */
+interface SerializedReferralProgramEditionSummaryPieSplit extends Omit<ReferralProgramEditionSummaryPieSplit, "rules"> {
+    rules: SerializedReferralProgramRulesPieSplit;
+}
 
 /**
  * Referrer edition metrics data for a specific referrer on a rev-share-limit leaderboard.
@@ -1159,10 +1254,10 @@ interface ReferrerEditionMetricsRankedRevShareLimit {
      */
     aggregatedMetrics: AggregatedReferrerMetricsRevShareLimit;
     /**
-     * The status of the referral program ("Scheduled", "Active", or "Closed")
+     * The status of the referral program edition
      * calculated based on the program's timing relative to {@link accurateAsOf}.
      */
-    status: ReferralProgramStatusId;
+    status: ReferralProgramEditionStatusId;
     /**
      * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerEditionMetricsRankedRevShareLimit} was accurate as of.
      */
@@ -1201,10 +1296,10 @@ interface ReferrerEditionMetricsUnrankedRevShareLimit {
      */
     aggregatedMetrics: AggregatedReferrerMetricsRevShareLimit;
     /**
-     * The status of the referral program ("Scheduled", "Active", or "Closed")
+     * The status of the referral program edition
      * calculated based on the program's timing relative to {@link accurateAsOf}.
      */
-    status: ReferralProgramStatusId;
+    status: ReferralProgramEditionStatusId;
     /**
      * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerEditionMetricsUnrankedRevShareLimit} was accurate as of.
      */
@@ -1217,6 +1312,38 @@ interface ReferrerEditionMetricsUnrankedRevShareLimit {
  */
 type ReferrerEditionMetricsRevShareLimit = ReferrerEditionMetricsRankedRevShareLimit | ReferrerEditionMetricsUnrankedRevShareLimit;
 
+/**
+ * Edition summary for a `rev-share-limit` referral program edition.
+ *
+ * Includes `awardPoolRemaining` so consumers can display pool exhaustion state
+ * without needing to fetch the full leaderboard.
+ */
+interface ReferralProgramEditionSummaryRevShareLimit extends BaseReferralProgramEditionSummary {
+    /**
+     * Discriminant — always `"rev-share-limit"`.
+     *
+     * @invariant Always equals `rules.awardModel` ({@link ReferralProgramAwardModels.RevShareLimit}).
+     */
+    awardModel: typeof ReferralProgramAwardModels.RevShareLimit;
+    /**
+     * The rev-share-limit rules for this edition.
+     */
+    rules: ReferralProgramRulesRevShareLimit;
+    /**
+     * The remaining award pool after sequential race processing.
+     *
+     * When `0n`, the edition's status will be {@link ReferralProgramEditionStatuses.Exhausted}
+     * if the edition is still within its active window.
+     */
+    awardPoolRemaining: PriceUsdc;
+}
+declare const validateEditionSummaryRevShareLimit: (summary: ReferralProgramEditionSummaryRevShareLimit) => void;
+/**
+ * Build a {@link ReferralProgramEditionSummaryRevShareLimit} from a rev-share-limit edition
+ * config and the edition's leaderboard.
+ */
+declare function buildEditionSummaryRevShareLimit(slug: ReferralProgramEditionSlug, displayName: string, rules: ReferralProgramRulesRevShareLimit, leaderboard: ReferrerLeaderboardRevShareLimit): ReferralProgramEditionSummaryRevShareLimit;
+
 /**
  * A page of referrers from the rev-share-limit referrer leaderboard.
  */
@@ -1308,6 +1435,13 @@ interface SerializedReferrerEditionMetricsUnrankedRevShareLimit extends Omit<Ref
  * Serialized representation of {@link ReferrerEditionMetricsRevShareLimit}.
  */
 type SerializedReferrerEditionMetricsRevShareLimit = SerializedReferrerEditionMetricsRankedRevShareLimit | SerializedReferrerEditionMetricsUnrankedRevShareLimit;
+/**
+ * Serialized representation of {@link ReferralProgramEditionSummaryRevShareLimit}.
+ */
+interface SerializedReferralProgramEditionSummaryRevShareLimit extends Omit<ReferralProgramEditionSummaryRevShareLimit, "rules" | "awardPoolRemaining"> {
+    rules: SerializedReferralProgramRulesRevShareLimit;
+    awardPoolRemaining: SerializedPriceUsdc;
+}
 
 /**
  * Referrer edition metrics data for a specific referrer address.
@@ -1329,6 +1463,21 @@ type ReferrerEditionMetrics = ReferrerEditionMetricsPieSplit | ReferrerEditionMe
  */
 declare const getReferrerEditionMetrics: (referrer: Address, leaderboard: ReferrerLeaderboard) => ReferrerEditionMetrics;
 
+/**
+ * Runtime summary of a referral program edition, enriched with current status and pool data.
+ *
+ * Use `awardModel` to discriminate between variants at runtime.
+ */
+type ReferralProgramEditionSummary = ReferralProgramEditionSummaryPieSplit | ReferralProgramEditionSummaryRevShareLimit | ReferralProgramEditionSummaryUnrecognized;
+/**
+ * Build a runtime edition summary from an edition config and the edition's leaderboard.
+ * Dispatches to the appropriate per-model builder based on `leaderboard.awardModel`.
+ *
+ * @param config - The edition configuration (provides `slug` and `displayName`).
+ * @param leaderboard - The resolved leaderboard for this edition.
+ */
+declare function buildEditionSummary(config: ReferralProgramEditionConfig, leaderboard: ReferrerLeaderboard): ReferralProgramEditionSummary;
+
 /**
  * A page of referrers from the referrer leaderboard.
  *
@@ -1448,51 +1597,51 @@ type ReferrerMetricsEditionsResponseError = {
  */
 type ReferrerMetricsEditionsResponse = ReferrerMetricsEditionsResponseOk | ReferrerMetricsEditionsResponseError;
 /**
- * A status code for referral program edition config set API responses.
+ * A status code for referral program edition summaries API responses.
  */
-declare const ReferralProgramEditionConfigSetResponseCodes: {
+declare const ReferralProgramEditionSummariesResponseCodes: {
     /**
-     * Represents that the edition config set is available.
+     * Represents that the edition summaries are available.
      */
     readonly Ok: "ok";
     /**
-     * Represents that the edition config set is not available.
+     * Represents that the edition summaries are not available.
      */
     readonly Error: "error";
 };
 /**
- * The derived string union of possible {@link ReferralProgramEditionConfigSetResponseCodes}.
+ * The derived string union of possible {@link ReferralProgramEditionSummariesResponseCodes}.
  */
-type ReferralProgramEditionConfigSetResponseCode = (typeof ReferralProgramEditionConfigSetResponseCodes)[keyof typeof ReferralProgramEditionConfigSetResponseCodes];
+type ReferralProgramEditionSummariesResponseCode = (typeof ReferralProgramEditionSummariesResponseCodes)[keyof typeof ReferralProgramEditionSummariesResponseCodes];
 /**
- * The data payload containing edition configs.
+ * The data payload containing edition summaries.
  * Editions are sorted in descending order by start timestamp.
  */
-type ReferralProgramEditionConfigSetData = {
-    editions: ReferralProgramEditionConfig[];
+type ReferralProgramEditionSummariesData = {
+    editions: ReferralProgramEditionSummary[];
 };
 /**
- * A successful response containing the configured edition config set.
+ * A successful response containing edition summaries.
  */
-type ReferralProgramEditionConfigSetResponseOk = {
-    responseCode: typeof ReferralProgramEditionConfigSetResponseCodes.Ok;
-    data: ReferralProgramEditionConfigSetData;
+type ReferralProgramEditionSummariesResponseOk = {
+    responseCode: typeof ReferralProgramEditionSummariesResponseCodes.Ok;
+    data: ReferralProgramEditionSummariesData;
 };
 /**
- * An edition config set response when an error occurs.
+ * An edition summaries response when an error occurs.
  */
-type ReferralProgramEditionConfigSetResponseError = {
-    responseCode: typeof ReferralProgramEditionConfigSetResponseCodes.Error;
+type ReferralProgramEditionSummariesResponseError = {
+    responseCode: typeof ReferralProgramEditionSummariesResponseCodes.Error;
     error: string;
     errorMessage: string;
 };
 /**
- * A referral program edition config set API response.
+ * A referral program edition summaries API response.
  *
  * Use the `responseCode` field to determine the specific type interpretation
  * at runtime.
  */
-type ReferralProgramEditionConfigSetResponse = ReferralProgramEditionConfigSetResponseOk | ReferralProgramEditionConfigSetResponseError;
+type ReferralProgramEditionSummariesResponse = ReferralProgramEditionSummariesResponseOk | ReferralProgramEditionSummariesResponseError;
 
 /**
  * Serialized representation of {@link ReferralProgramRules}.
@@ -1523,11 +1672,9 @@ interface SerializedReferrerLeaderboardPageResponseOk extends Omit<ReferrerLeade
  */
 type SerializedReferrerLeaderboardPageResponse = SerializedReferrerLeaderboardPageResponseOk | SerializedReferrerLeaderboardPageResponseError;
 /**
- * Serialized representation of {@link ReferralProgramEditionConfig}.
+ * Serialized representation of {@link ReferralProgramEditionSummary}.
  */
-interface SerializedReferralProgramEditionConfig extends Omit<ReferralProgramEditionConfig, "rules"> {
-    rules: SerializedReferralProgramRules;
-}
+type SerializedReferralProgramEditionSummary = SerializedReferralProgramEditionSummaryPieSplit | SerializedReferralProgramEditionSummaryRevShareLimit;
 /**
  * Serialized representation of referrer metrics data for requested editions.
  * Uses Partial because TypeScript cannot know at compile time which specific edition
@@ -1552,27 +1699,27 @@ type SerializedReferrerMetricsEditionsResponseError = ReferrerMetricsEditionsRes
  */
 type SerializedReferrerMetricsEditionsResponse = SerializedReferrerMetricsEditionsResponseOk | SerializedReferrerMetricsEditionsResponseError;
 /**
- * Serialized representation of {@link ReferralProgramEditionConfigSetData}.
+ * Serialized representation of {@link ReferralProgramEditionSummariesData}.
  */
-interface SerializedReferralProgramEditionConfigSetData extends Omit<ReferralProgramEditionConfigSetData, "editions"> {
-    editions: SerializedReferralProgramEditionConfig[];
+interface SerializedReferralProgramEditionSummariesData extends Omit<ReferralProgramEditionSummariesData, "editions"> {
+    editions: SerializedReferralProgramEditionSummary[];
 }
 /**
- * Serialized representation of {@link ReferralProgramEditionConfigSetResponseOk}.
+ * Serialized representation of {@link ReferralProgramEditionSummariesResponseOk}.
  */
-interface SerializedReferralProgramEditionConfigSetResponseOk extends Omit<ReferralProgramEditionConfigSetResponseOk, "data"> {
-    data: SerializedReferralProgramEditionConfigSetData;
+interface SerializedReferralProgramEditionSummariesResponseOk extends Omit<ReferralProgramEditionSummariesResponseOk, "data"> {
+    data: SerializedReferralProgramEditionSummariesData;
 }
 /**
- * Serialized representation of {@link ReferralProgramEditionConfigSetResponseError}.
+ * Serialized representation of {@link ReferralProgramEditionSummariesResponseError}.
  *
  * Note: All fields are already serializable, so this type is identical to the source type.
  */
-type SerializedReferralProgramEditionConfigSetResponseError = ReferralProgramEditionConfigSetResponseError;
+type SerializedReferralProgramEditionSummariesResponseError = ReferralProgramEditionSummariesResponseError;
 /**
- * Serialized representation of {@link ReferralProgramEditionConfigSetResponse}.
+ * Serialized representation of {@link ReferralProgramEditionSummariesResponse}.
  */
-type SerializedReferralProgramEditionConfigSetResponse = SerializedReferralProgramEditionConfigSetResponseOk | SerializedReferralProgramEditionConfigSetResponseError;
+type SerializedReferralProgramEditionSummariesResponse = SerializedReferralProgramEditionSummariesResponseOk | SerializedReferralProgramEditionSummariesResponseError;
 
 /**
  * Deserialize a {@link ReferrerLeaderboardPageResponse} object.
@@ -1587,9 +1734,9 @@ declare function deserializeReferrerMetricsEditionsResponse(maybeResponse: Seria
  */
 declare function deserializeReferralProgramEditionConfigSetArray(maybeArray: unknown, valueLabel?: string): ReferralProgramEditionConfig[];
 /**
- * Deserialize a {@link ReferralProgramEditionConfigSetResponse} object.
+ * Deserialize a {@link ReferralProgramEditionSummariesResponse} object.
  */
-declare function deserializeReferralProgramEditionConfigSetResponse(maybeResponse: SerializedReferralProgramEditionConfigSetResponse, valueLabel?: string): ReferralProgramEditionConfigSetResponse;
+declare function deserializeReferralProgramEditionSummariesResponse(maybeResponse: SerializedReferralProgramEditionSummariesResponse, valueLabel?: string): ReferralProgramEditionSummariesResponse;
 
 /**
  * Serializes a {@link ReferralProgramRules} object.
@@ -1599,9 +1746,12 @@ declare function deserializeReferralProgramEditionConfigSetResponse(maybeRespons
  */
 declare function serializeReferralProgramRules(rules: ReferralProgramRules): SerializedReferralProgramRules;
 /**
- * Serializes a {@link ReferralProgramEditionConfig} object.
+ * Serializes a {@link ReferralProgramEditionSummary} object.
+ *
+ * @throws if called with a {@link ReferralProgramEditionSummaryUnrecognized} — unrecognized
+ *   summaries are client-side forward-compatibility placeholders and must never be serialized.
  */
-declare function serializeReferralProgramEditionConfig(editionConfig: ReferralProgramEditionConfig): SerializedReferralProgramEditionConfig;
+declare function serializeReferralProgramEditionSummary(summary: ReferralProgramEditionSummary): SerializedReferralProgramEditionSummary;
 /**
  * Serialize a {@link ReferrerLeaderboardPageResponse} object.
  */
@@ -1611,9 +1761,9 @@ declare function serializeReferrerLeaderboardPageResponse(response: ReferrerLead
  */
 declare function serializeReferrerMetricsEditionsResponse(response: ReferrerMetricsEditionsResponse): SerializedReferrerMetricsEditionsResponse;
 /**
- * Serialize a {@link ReferralProgramEditionConfigSetResponse} object.
+ * Serialize a {@link ReferralProgramEditionSummariesResponse} object.
  */
-declare function serializeReferralProgramEditionConfigSetResponse(response: ReferralProgramEditionConfigSetResponse): SerializedReferralProgramEditionConfigSetResponse;
+declare function serializeReferralProgramEditionSummariesResponse(response: ReferralProgramEditionSummariesResponse): SerializedReferralProgramEditionSummariesResponse;
 
 /**
  * Calculate the score of a referrer based on the total incremental duration
@@ -1627,6 +1777,29 @@ declare function serializeReferralProgramEditionConfigSetResponse(response: Refe
  */
 declare const calcReferrerScorePieSplit: (totalIncrementalDuration: Duration) => ReferrerScore;
 
+/**
+ * Calculate the status of a `pie-split` referral program.
+ *
+ * Delegates entirely to {@link calcBaseReferralProgramEditionStatus} — pie-split has no additional
+ * runtime conditions that affect status beyond the time-based lifecycle.
+ *
+ * @param rules - The pie-split rules for the edition.
+ * @param now - Current date in {@link UnixTimestamp} format.
+ */
+declare const calcReferralProgramEditionStatusPieSplit: (rules: ReferralProgramRulesPieSplit, now: UnixTimestamp) => ReferralProgramEditionStatusId;
+
+/**
+ * Calculate the status of a `rev-share-limit` referral program.
+ *
+ * Returns `Exhausted` when the program is `Active` but its award pool has been fully consumed
+ * (`awardPoolRemaining.amount === 0n`). Otherwise delegates to {@link calcBaseReferralProgramEditionStatus}.
+ *
+ * @param rules - The rev-share-limit rules for the edition.
+ * @param now - Current date in {@link UnixTimestamp} format.
+ * @param aggregatedMetrics - The aggregated leaderboard metrics, used to check `awardPoolRemaining`.
+ */
+declare const calcReferralProgramEditionStatusRevShareLimit: (rules: ReferralProgramRulesRevShareLimit, now: UnixTimestamp, aggregatedMetrics: AggregatedReferrerMetricsRevShareLimit) => ReferralProgramEditionStatusId;
+
 /**
  * Default ENSNode API endpoint URL
  */
@@ -1850,22 +2023,22 @@ declare class ENSReferralsClient {
      */
     getReferrerMetricsEditions(request: ReferrerMetricsEditionsRequest): Promise<ReferrerMetricsEditionsResponse>;
     /**
-     * Get the currently configured referral program edition config set.
+     * Get the currently configured referral program edition summaries.
      * Editions are sorted in descending order by start timestamp (most recent first).
      *
-     * @returns A response containing the edition config set, or an error response if unavailable.
+     * @returns A response containing edition summaries, or an error response if unavailable.
      *
      * @remarks Editions whose `rules.awardModel` is not recognized by this client version are
-     * preserved as {@link ReferralProgramRulesUnrecognized}. The returned map includes all
-     * editions — recognized and unrecognized alike. Callers should check `editionConfig.rules.awardModel`
+     * preserved as {@link ReferralProgramEditionSummaryUnrecognized}. The returned response includes all
+     * editions — recognized and unrecognized alike. Callers should check `edition.awardModel`
      * and skip editions with `"unrecognized"` as appropriate. At least one edition of any kind must
      * be present, otherwise deserialization throws.
      *
      * @example
      * ```typescript
-     * const response = await client.getEditionConfigSet();
+     * const response = await client.getEditionSummaries();
      *
-     * if (response.responseCode === ReferralProgramEditionConfigSetResponseCodes.Ok) {
+     * if (response.responseCode === ReferralProgramEditionSummariesResponseCodes.Ok) {
      *   console.log(`Found ${response.data.editions.length} editions`);
      *   for (const edition of response.data.editions) {
      *     console.log(`${edition.slug}: ${edition.displayName}`);
@@ -1876,15 +2049,15 @@ declare class ENSReferralsClient {
      * @example
      * ```typescript
      * // Handle error response
-     * const response = await client.getEditionConfigSet();
+     * const response = await client.getEditionSummaries();
      *
-     * if (response.responseCode === ReferralProgramEditionConfigSetResponseCodes.Error) {
+     * if (response.responseCode === ReferralProgramEditionSummariesResponseCodes.Error) {
      *   console.error(response.error);
      *   console.error(response.errorMessage);
      * }
      * ```
      */
-    getEditionConfigSet(): Promise<ReferralProgramEditionConfigSetResponse>;
+    getEditionSummaries(): Promise<ReferralProgramEditionSummariesResponse>;
 }
 
 /**
@@ -1922,4 +2095,4 @@ declare const SECONDS_PER_YEAR: Duration;
 declare function isValidDuration(duration: Duration): boolean;
 declare function validateDuration(duration: Duration): void;
 
-export { type AggregatedReferrerMetricsPieSplit, type AggregatedReferrerMetricsRevShareLimit, type AwardedReferrerMetricsPieSplit, type AwardedReferrerMetricsRevShareLimit, BASE_REVENUE_CONTRIBUTION_PER_YEAR, type BaseReferralProgramRules, type BaseReferrerLeaderboardPage, type ClientOptions, DEFAULT_ENSNODE_API_URL, ENSReferralsClient, MAX_EDITIONS_PER_REQUEST, REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT, REFERRERS_PER_LEADERBOARD_PAGE_MAX, type RankedReferrerMetricsPieSplit, type RankedReferrerMetricsRevShareLimit, type ReferralEvent, type ReferralProgramAwardModel, ReferralProgramAwardModels, type ReferralProgramEditionConfig, type ReferralProgramEditionConfigSet, type ReferralProgramEditionConfigSetData, type ReferralProgramEditionConfigSetResponse, type ReferralProgramEditionConfigSetResponseCode, ReferralProgramEditionConfigSetResponseCodes, type ReferralProgramEditionConfigSetResponseError, type ReferralProgramEditionConfigSetResponseOk, type ReferralProgramEditionDisqualification, type ReferralProgramEditionSlug, type ReferralProgramRules, type ReferralProgramRulesPieSplit, type ReferralProgramRulesRevShareLimit, type ReferralProgramRulesUnrecognized, type ReferralProgramStatusId, ReferralProgramStatuses, type ReferrerEditionMetrics, type ReferrerEditionMetricsPieSplit, type ReferrerEditionMetricsRankedPieSplit, type ReferrerEditionMetricsRankedRevShareLimit, type ReferrerEditionMetricsRevShareLimit, type ReferrerEditionMetricsTypeId, ReferrerEditionMetricsTypeIds, type ReferrerEditionMetricsUnrankedPieSplit, type ReferrerEditionMetricsUnrankedRevShareLimit, type ReferrerEditionMetricsUnrecognized, type ReferrerLeaderboard, type ReferrerLeaderboardPage, type ReferrerLeaderboardPageContext, type ReferrerLeaderboardPageParams, type ReferrerLeaderboardPagePieSplit, type ReferrerLeaderboardPageRequest, type ReferrerLeaderboardPageResponse, type ReferrerLeaderboardPageResponseCode, ReferrerLeaderboardPageResponseCodes, type ReferrerLeaderboardPageResponseError, type ReferrerLeaderboardPageResponseOk, type ReferrerLeaderboardPageRevShareLimit, type ReferrerLeaderboardPageUnrecognized, type ReferrerLeaderboardPieSplit, type ReferrerLeaderboardRevShareLimit, type ReferrerMetrics, type ReferrerMetricsEditionsData, type ReferrerMetricsEditionsRequest, type ReferrerMetricsEditionsResponse, type ReferrerMetricsEditionsResponseCode, ReferrerMetricsEditionsResponseCodes, type ReferrerMetricsEditionsResponseError, type ReferrerMetricsEditionsResponseOk, type ReferrerMetricsForComparison, type ReferrerMetricsRevShareLimit, type ReferrerRank, type ReferrerScore, SECONDS_PER_YEAR, type ScoredReferrerMetricsPieSplit, type SerializedAggregatedReferrerMetricsPieSplit, type SerializedAggregatedReferrerMetricsRevShareLimit, type SerializedAwardedReferrerMetricsPieSplit, type SerializedAwardedReferrerMetricsRevShareLimit, type SerializedReferralProgramEditionConfig, type SerializedReferralProgramEditionConfigSetData, type SerializedReferralProgramEditionConfigSetResponse, type SerializedReferralProgramEditionConfigSetResponseError, type SerializedReferralProgramEditionConfigSetResponseOk, type SerializedReferralProgramRules, type SerializedReferralProgramRulesPieSplit, type SerializedReferralProgramRulesRevShareLimit, type SerializedReferrerEditionMetrics, type SerializedReferrerEditionMetricsPieSplit, type SerializedReferrerEditionMetricsRankedPieSplit, type SerializedReferrerEditionMetricsRankedRevShareLimit, type SerializedReferrerEditionMetricsRevShareLimit, type SerializedReferrerEditionMetricsUnrankedPieSplit, type SerializedReferrerEditionMetricsUnrankedRevShareLimit, type SerializedReferrerLeaderboardPage, type SerializedReferrerLeaderboardPagePieSplit, type SerializedReferrerLeaderboardPageResponse, type SerializedReferrerLeaderboardPageResponseError, type SerializedReferrerLeaderboardPageResponseOk, type SerializedReferrerLeaderboardPageRevShareLimit, type SerializedReferrerMetricsEditionsData, type SerializedReferrerMetricsEditionsResponse, type SerializedReferrerMetricsEditionsResponseError, type SerializedReferrerMetricsEditionsResponseOk, type SerializedUnrankedReferrerMetricsPieSplit, type SerializedUnrankedReferrerMetricsRevShareLimit, type UnrankedReferrerMetricsPieSplit, type UnrankedReferrerMetricsRevShareLimit, buildAggregatedReferrerMetricsPieSplit, buildAggregatedReferrerMetricsRevShareLimit, buildAwardedReferrerMetricsPieSplit, buildAwardedReferrerMetricsRevShareLimit, buildEnsReferralUrl, buildLeaderboardPagePieSplit, buildLeaderboardPageRevShareLimit, buildRankedReferrerMetricsPieSplit, buildRankedReferrerMetricsRevShareLimit, buildReferralProgramEditionConfigSet, buildReferralProgramRulesPieSplit, buildReferralProgramRulesRevShareLimit, buildReferrerLeaderboardPageContext, buildReferrerLeaderboardPageParams, buildReferrerLeaderboardPieSplit, buildReferrerLeaderboardRevShareLimit, buildReferrerMetrics, buildReferrerMetricsRevShareLimit, buildScoredReferrerMetricsPieSplit, buildUnrankedReferrerMetricsPieSplit, buildUnrankedReferrerMetricsRevShareLimit, calcReferralProgramStatus, calcReferrerAwardPoolSharePieSplit, calcReferrerScorePieSplit, compareReferrerMetrics, deserializeReferralProgramEditionConfigSetArray, deserializeReferralProgramEditionConfigSetResponse, deserializeReferrerLeaderboardPageResponse, deserializeReferrerMetricsEditionsResponse, getDefaultReferralProgramEditionConfigSet, getReferrerEditionMetrics, getReferrerLeaderboardPage, isFiniteNonNegativeNumber, isInteger, isNonNegativeInteger, isPositiveInteger, isReferrerQualifiedRevShareLimit, isValidDuration, isValidReferrerScore, normalizeAddress, serializeReferralProgramEditionConfig, serializeReferralProgramEditionConfigSetResponse, serializeReferralProgramRules, serializeReferrerLeaderboardPageResponse, serializeReferrerMetricsEditionsResponse, sliceReferrers, sortReferrerMetrics, validateAggregatedReferrerMetricsPieSplit, validateAggregatedReferrerMetricsRevShareLimit, validateAwardedReferrerMetricsPieSplit, validateAwardedReferrerMetricsRevShareLimit, validateBaseReferralProgramRules, validateDuration, validateLowercaseAddress, validateNonNegativeInteger, validateRankedReferrerMetricsPieSplit, validateRankedReferrerMetricsRevShareLimit, validateReferralProgramEditionConfigSet, validateReferralProgramRulesPieSplit, validateReferralProgramRulesRevShareLimit, validateReferrerLeaderboardPageContext, validateReferrerMetrics, validateReferrerMetricsRevShareLimit, validateReferrerRank, validateReferrerScore, validateScoredReferrerMetricsPieSplit, validateUnixTimestamp, validateUnrankedReferrerMetricsPieSplit, validateUnrankedReferrerMetricsRevShareLimit };
+export { type AggregatedReferrerMetricsPieSplit, type AggregatedReferrerMetricsRevShareLimit, type AwardedReferrerMetricsPieSplit, type AwardedReferrerMetricsRevShareLimit, BASE_REVENUE_CONTRIBUTION_PER_YEAR, type BaseReferralProgramEditionSummary, type BaseReferralProgramRules, type BaseReferrerLeaderboardPage, type ClientOptions, DEFAULT_ENSNODE_API_URL, ENSReferralsClient, MAX_EDITIONS_PER_REQUEST, REFERRAL_PROGRAM_EDITION_SLUG_PATTERN, REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT, REFERRERS_PER_LEADERBOARD_PAGE_MAX, type RankedReferrerMetricsPieSplit, type RankedReferrerMetricsRevShareLimit, type ReferralEvent, type ReferralProgramAwardModel, ReferralProgramAwardModels, type ReferralProgramEditionConfig, type ReferralProgramEditionConfigSet, type ReferralProgramEditionDisqualification, type ReferralProgramEditionSlug, type ReferralProgramEditionStatusId, ReferralProgramEditionStatuses, type ReferralProgramEditionSummariesData, type ReferralProgramEditionSummariesResponse, type ReferralProgramEditionSummariesResponseCode, ReferralProgramEditionSummariesResponseCodes, type ReferralProgramEditionSummariesResponseError, type ReferralProgramEditionSummariesResponseOk, type ReferralProgramEditionSummary, type ReferralProgramEditionSummaryPieSplit, type ReferralProgramEditionSummaryRevShareLimit, type ReferralProgramEditionSummaryUnrecognized, type ReferralProgramRules, type ReferralProgramRulesPieSplit, type ReferralProgramRulesRevShareLimit, type ReferralProgramRulesUnrecognized, type ReferrerEditionMetrics, type ReferrerEditionMetricsPieSplit, type ReferrerEditionMetricsRankedPieSplit, type ReferrerEditionMetricsRankedRevShareLimit, type ReferrerEditionMetricsRevShareLimit, type ReferrerEditionMetricsTypeId, ReferrerEditionMetricsTypeIds, type ReferrerEditionMetricsUnrankedPieSplit, type ReferrerEditionMetricsUnrankedRevShareLimit, type ReferrerEditionMetricsUnrecognized, type ReferrerLeaderboard, type ReferrerLeaderboardPage, type ReferrerLeaderboardPageContext, type ReferrerLeaderboardPageParams, type ReferrerLeaderboardPagePieSplit, type ReferrerLeaderboardPageRequest, type ReferrerLeaderboardPageResponse, type ReferrerLeaderboardPageResponseCode, ReferrerLeaderboardPageResponseCodes, type ReferrerLeaderboardPageResponseError, type ReferrerLeaderboardPageResponseOk, type ReferrerLeaderboardPageRevShareLimit, type ReferrerLeaderboardPageUnrecognized, type ReferrerLeaderboardPieSplit, type ReferrerLeaderboardRevShareLimit, type ReferrerMetrics, type ReferrerMetricsEditionsData, type ReferrerMetricsEditionsRequest, type ReferrerMetricsEditionsResponse, type ReferrerMetricsEditionsResponseCode, ReferrerMetricsEditionsResponseCodes, type ReferrerMetricsEditionsResponseError, type ReferrerMetricsEditionsResponseOk, type ReferrerMetricsForComparison, type ReferrerMetricsRevShareLimit, type ReferrerRank, type ReferrerScore, SECONDS_PER_YEAR, type ScoredReferrerMetricsPieSplit, type SerializedAggregatedReferrerMetricsPieSplit, type SerializedAggregatedReferrerMetricsRevShareLimit, type SerializedAwardedReferrerMetricsPieSplit, type SerializedAwardedReferrerMetricsRevShareLimit, type SerializedReferralProgramEditionSummariesData, type SerializedReferralProgramEditionSummariesResponse, type SerializedReferralProgramEditionSummariesResponseError, type SerializedReferralProgramEditionSummariesResponseOk, type SerializedReferralProgramEditionSummary, type SerializedReferralProgramEditionSummaryPieSplit, type SerializedReferralProgramEditionSummaryRevShareLimit, type SerializedReferralProgramRules, type SerializedReferralProgramRulesPieSplit, type SerializedReferralProgramRulesRevShareLimit, type SerializedReferrerEditionMetrics, type SerializedReferrerEditionMetricsPieSplit, type SerializedReferrerEditionMetricsRankedPieSplit, type SerializedReferrerEditionMetricsRankedRevShareLimit, type SerializedReferrerEditionMetricsRevShareLimit, type SerializedReferrerEditionMetricsUnrankedPieSplit, type SerializedReferrerEditionMetricsUnrankedRevShareLimit, type SerializedReferrerLeaderboardPage, type SerializedReferrerLeaderboardPagePieSplit, type SerializedReferrerLeaderboardPageResponse, type SerializedReferrerLeaderboardPageResponseError, type SerializedReferrerLeaderboardPageResponseOk, type SerializedReferrerLeaderboardPageRevShareLimit, type SerializedReferrerMetricsEditionsData, type SerializedReferrerMetricsEditionsResponse, type SerializedReferrerMetricsEditionsResponseError, type SerializedReferrerMetricsEditionsResponseOk, type SerializedUnrankedReferrerMetricsPieSplit, type SerializedUnrankedReferrerMetricsRevShareLimit, type UnrankedReferrerMetricsPieSplit, type UnrankedReferrerMetricsRevShareLimit, buildAggregatedReferrerMetricsPieSplit, buildAggregatedReferrerMetricsRevShareLimit, buildAwardedReferrerMetricsPieSplit, buildAwardedReferrerMetricsRevShareLimit, buildEditionSummary, buildEditionSummaryPieSplit, buildEditionSummaryRevShareLimit, buildEnsReferralUrl, buildLeaderboardPagePieSplit, buildLeaderboardPageRevShareLimit, buildRankedReferrerMetricsPieSplit, buildRankedReferrerMetricsRevShareLimit, buildReferralProgramEditionConfigSet, buildReferralProgramRulesPieSplit, buildReferralProgramRulesRevShareLimit, buildReferrerLeaderboardPageContext, buildReferrerLeaderboardPageParams, buildReferrerLeaderboardPieSplit, buildReferrerLeaderboardRevShareLimit, buildReferrerMetrics, buildReferrerMetricsRevShareLimit, buildScoredReferrerMetricsPieSplit, buildUnrankedReferrerMetricsPieSplit, buildUnrankedReferrerMetricsRevShareLimit, calcBaseReferralProgramEditionStatus, calcReferralProgramEditionStatusPieSplit, calcReferralProgramEditionStatusRevShareLimit, calcReferrerAwardPoolSharePieSplit, calcReferrerScorePieSplit, compareReferrerMetrics, deserializeReferralProgramEditionConfigSetArray, deserializeReferralProgramEditionSummariesResponse, deserializeReferrerLeaderboardPageResponse, deserializeReferrerMetricsEditionsResponse, getDefaultReferralProgramEditionConfigSet, getReferrerEditionMetrics, getReferrerLeaderboardPage, isFiniteNonNegativeNumber, isInteger, isNonNegativeInteger, isPositiveInteger, isReferrerQualifiedRevShareLimit, isValidDuration, isValidReferrerScore, normalizeAddress, serializeReferralProgramEditionSummariesResponse, serializeReferralProgramEditionSummary, serializeReferralProgramRules, serializeReferrerLeaderboardPageResponse, serializeReferrerMetricsEditionsResponse, sliceReferrers, sortReferrerMetrics, validateAggregatedReferrerMetricsPieSplit, validateAggregatedReferrerMetricsRevShareLimit, validateAwardedReferrerMetricsPieSplit, validateAwardedReferrerMetricsRevShareLimit, validateBaseReferralProgramEditionSummary, validateBaseReferralProgramRules, validateDuration, validateEditionSummaryPieSplit, validateEditionSummaryRevShareLimit, validateLowercaseAddress, validateNonNegativeInteger, validateRankedReferrerMetricsPieSplit, validateRankedReferrerMetricsRevShareLimit, validateReferralProgramEditionConfigSet, validateReferralProgramRulesPieSplit, validateReferralProgramRulesRevShareLimit, validateReferrerLeaderboardPageContext, validateReferrerMetrics, validateReferrerMetricsRevShareLimit, validateReferrerRank, validateReferrerScore, validateScoredReferrerMetricsPieSplit, validateUnixTimestamp, validateUnrankedReferrerMetricsPieSplit, validateUnrankedReferrerMetricsRevShareLimit };