@namehash/ens-referrals 1.5.1 → 1.7.0

package/dist/v1/index.d.cts

@@ -0,0 +1,1925 @@
+import { Address } from 'viem';
+import { UnixTimestamp, AccountId, PriceUsdc, Duration, PriceEth, SerializedPriceEth, SerializedPriceUsdc, ENSNamespaceId } from '@ensnode/ensnode-sdk';
+
+declare const validateLowercaseAddress: (address: Address) => void;
+declare const normalizeAddress: (address: Address) => Address;
+
+/**
+ * Discriminant values for the award model used in a referral program edition.
+ *
+ * @remarks Clients MUST check `awardModel` before accessing model-specific fields.
+ * Editions with unrecognized `awardModel` values are preserved as
+ * {@link ReferralProgramRulesUnrecognized} during parsing (see
+ * `makeReferralProgramEditionConfigSetArraySchema`). Clients must handle this variant — typically
+ * by skipping those editions with a warning log rather than crashing.
+ */
+declare const ReferralProgramAwardModels: {
+    readonly PieSplit: "pie-split";
+    readonly RevShareLimit: "rev-share-limit";
+    readonly Unrecognized: "unrecognized";
+};
+type ReferralProgramAwardModel = (typeof ReferralProgramAwardModels)[keyof typeof ReferralProgramAwardModels];
+/**
+ * Base fields shared across all referral program rule types.
+ *
+ * Both `ReferralProgramRulesPieSplit` and `ReferralProgramRulesRevShareLimit` are structurally
+ * compatible with this interface, so it can be used wherever only the common fields are needed
+ * (e.g., `assertLeaderboardInputs`).
+ */
+interface BaseReferralProgramRules {
+    /**
+     * Discriminant: identifies the award model for this edition.
+     */
+    awardModel: ReferralProgramAwardModel;
+    /**
+     * The start time of the referral program.
+     */
+    startTime: UnixTimestamp;
+    /**
+     * The end time of the referral program.
+     * @invariant Guaranteed to be greater than or equal to `startTime`
+     */
+    endTime: UnixTimestamp;
+    /**
+     * The account ID of the subregistry for the referral program.
+     */
+    subregistryId: AccountId;
+    /**
+     * URL to the full rules document for these rules.
+     * @example new URL("https://ensawards.org/ens-holiday-awards-rules")
+     */
+    rulesUrl: URL;
+}
+/**
+ * Rules for a referral program 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 processed
+ * by business logic on the backend. When the server introduces a new award model type, older
+ * clients preserve the edition rather than silently dropping it, and downstream code that
+ * encounters this type should skip it with a warning log rather than crashing.
+ */
+interface ReferralProgramRulesUnrecognized extends BaseReferralProgramRules {
+    /**
+     * Discriminant — always `"unrecognized"`.
+     */
+    awardModel: typeof ReferralProgramAwardModels.Unrecognized;
+    /**
+     * The original, unrecognized `awardModel` string received from the server.
+     *
+     * @remarks Preserved for logging and debugging. Never used for business logic.
+     */
+    originalAwardModel: string;
+}
+declare const validateBaseReferralProgramRules: (rules: BaseReferralProgramRules) => void;
+
+interface ReferralProgramRulesPieSplit extends BaseReferralProgramRules {
+    /**
+     * Discriminant: identifies this as a "pie-split" award model edition.
+     *
+     * In pie-split, the top-N referrers split an award pool proportionally
+     * based on their scored duration (with rank-based boost).
+     */
+    awardModel: typeof ReferralProgramAwardModels.PieSplit;
+    /**
+     * The total value of the award pool in USDC.
+     *
+     * NOTE: Awards will actually be distributed in $ENS tokens.
+     */
+    totalAwardPoolValue: PriceUsdc;
+    /**
+     * The maximum number of referrers that will qualify to receive a non-zero `awardPoolShare`.
+     *
+     * @invariant Guaranteed to be a non-negative integer (>= 0)
+     */
+    maxQualifiedReferrers: number;
+}
+declare const validateReferralProgramRulesPieSplit: (rules: ReferralProgramRulesPieSplit) => void;
+declare const buildReferralProgramRulesPieSplit: (totalAwardPoolValue: PriceUsdc, maxQualifiedReferrers: number, startTime: UnixTimestamp, endTime: UnixTimestamp, subregistryId: AccountId, rulesUrl: URL) => ReferralProgramRulesPieSplit;
+
+/**
+ * An admin-imposed disqualification entry of a specific referrer in an edition.
+ */
+interface ReferralProgramEditionDisqualification {
+    /**
+     * The address of the disqualified referrer.
+     *
+     * @invariant Guaranteed to be a valid EVM address in lowercase format.
+     */
+    referrer: Address;
+    /**
+     * A human-readable explanation of why the referrer was disqualified.
+     *
+     * @invariant Must be a non-empty string.
+     */
+    reason: string;
+}
+/**
+ * Base revenue contribution per year of incremental duration.
+ *
+ * Used in `rev-share-limit` qualification and award calculations:
+ * 1 year of incremental duration = $5 in base revenue (base-fee-only, excluding premiums).
+ */
+declare const BASE_REVENUE_CONTRIBUTION_PER_YEAR: PriceUsdc;
+interface ReferralProgramRulesRevShareLimit extends BaseReferralProgramRules {
+    /**
+     * Discriminant: identifies this as a "rev-share-limit" award model edition.
+     *
+     * In rev-share-limit, each qualified referrer receives a share of their base revenue
+     * contribution (base-fee-only: $5 × years of incremental duration), subject to a
+     * pool cap and a minimum qualification threshold.
+     */
+    awardModel: typeof ReferralProgramAwardModels.RevShareLimit;
+    /**
+     * The total value of the award pool in USDC (acts as a cap on total payouts).
+     */
+    totalAwardPoolValue: PriceUsdc;
+    /**
+     * The minimum base revenue contribution required for a referrer to qualify.
+     */
+    minQualifiedRevenueContribution: PriceUsdc;
+    /**
+     * The fraction of the referrer's base revenue contribution that constitutes their potential award.
+     *
+     * @invariant Guaranteed to be a number between 0 and 1 (inclusive)
+     */
+    qualifiedRevenueShare: number;
+    /**
+     * Admin-imposed disqualifications for this edition.
+     * Disqualified referrers receive no awards.
+     *
+     * @invariant No duplicate referrer addresses.
+     */
+    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;
+/**
+ * Determine if a referrer is qualified under rev-share-limit rules.
+ *
+ * A referrer is qualified if they meet the revenue threshold AND are not admin-disqualified.
+ *
+ * @param referrer - The referrer's address.
+ * @param totalBaseRevenueContribution - The referrer's total base revenue contribution.
+ * @param rules - The rev-share-limit rules of the referral program.
+ */
+declare function isReferrerQualifiedRevShareLimit(referrer: Address, totalBaseRevenueContribution: PriceUsdc, rules: ReferralProgramRulesRevShareLimit): boolean;
+
+/**
+ * The rules of a referral program edition.
+ *
+ * Use `awardModel` to discriminate between rule types at runtime:
+ * - `"pie-split"` → {@link ReferralProgramRulesPieSplit}
+ * - `"rev-share-limit"` → {@link ReferralProgramRulesRevShareLimit}
+ * - `"unrecognized"` → {@link ReferralProgramRulesUnrecognized} (client-side forward-compatibility
+ *   placeholder for editions whose `awardModel` string is not known to this client version)
+ *
+ * Internal business logic only handles the known variants (`pie-split`, `rev-share-limit`).
+ * Unrecognized editions should be skipped with a warning log rather than crashing.
+ */
+type ReferralProgramRules = ReferralProgramRulesPieSplit | ReferralProgramRulesRevShareLimit | ReferralProgramRulesUnrecognized;
+
+/**
+ * Referral program edition slug.
+ *
+ * A URL-safe identifier for a referral program edition. Each edition represents
+ * a distinct referral program period with its own rules, leaderboard, and
+ * award distribution.
+ *
+ * @invariant Must contain only lowercase letters (a-z), digits (0-9), and hyphens (-).
+ *            Must not start or end with a hyphen. Pattern: `^[a-z0-9]+(-[a-z0-9]+)*$`
+ *
+ * @example "2025-12" // December 2025 edition
+ * @example "2026-03" // March 2026 edition
+ * @example "holiday-special" // Custom named edition
+ */
+type ReferralProgramEditionSlug = string;
+/**
+ * Represents a referral program edition configuration.
+ */
+interface ReferralProgramEditionConfig {
+    /**
+     * Unique slug identifier for the edition.
+     */
+    slug: ReferralProgramEditionSlug;
+    /**
+     * Human-readable display name for the edition.
+     * @example "ENS Holiday Awards"
+     */
+    displayName: string;
+    /**
+     * The rules that govern this referral program edition.
+     */
+    rules: ReferralProgramRules;
+}
+/**
+ * A map from edition slug to edition configuration.
+ *
+ * Used to store and look up all configured referral program editions.
+ *
+ * @invariant For each key-value pair in the map, the key must equal the value's slug property.
+ *            That is, for all entries: `map.get(key)?.slug === key`
+ */
+type ReferralProgramEditionConfigSet = Map<ReferralProgramEditionSlug, ReferralProgramEditionConfig>;
+/**
+ * Validates that a ReferralProgramEditionConfigSet maintains the invariant
+ * that each map key equals the corresponding config's slug.
+ *
+ * @param configSet - The edition config set to validate
+ * @throws {Error} If any entry violates the invariant (key !== value.slug)
+ */
+declare function validateReferralProgramEditionConfigSet(configSet: ReferralProgramEditionConfigSet): void;
+/**
+ * Builds a new ReferralProgramEditionConfigSet from an array of configs and validates the invariant.
+ *
+ * @param configs - Array of edition configurations to add to the set
+ * @returns A validated edition config set
+ * @throws {Error} If duplicate slugs are detected or if any config would violate the invariant
+ */
+declare function buildReferralProgramEditionConfigSet(configs: ReferralProgramEditionConfig[]): ReferralProgramEditionConfigSet;
+
+/**
+ * The score of a referrer.
+ *
+ * @invariant Guaranteed to be a finite non-negative number (>= 0)
+ */
+type ReferrerScore = number;
+declare const isValidReferrerScore: (score: ReferrerScore) => boolean;
+declare const validateReferrerScore: (score: ReferrerScore) => void;
+
+/**
+ * Metrics for a single referrer, as aggregated from the DB layer.
+ * Independent of other referrers and award model; does not carry an `awardModel` discriminant.
+ */
+interface ReferrerMetrics {
+    /**
+     * The fully lowercase Ethereum address of the referrer.
+     *
+     * @invariant Guaranteed to be a valid EVM address in lowercase format
+     */
+    referrer: Address;
+    /**
+     * The total number of referrals made by the referrer within the {@link ReferralProgramRules}.
+     * @invariant Guaranteed to be a non-negative integer (>= 0)
+     */
+    totalReferrals: number;
+    /**
+     * The total incremental duration (in seconds) of all referrals made by the referrer within
+     * the {@link ReferralProgramRules}.
+     */
+    totalIncrementalDuration: Duration;
+    /**
+     * The total revenue contribution in ETH made to the ENS DAO by all referrals
+     * from this referrer.
+     *
+     * This is the sum of the total cost paid by registrants for all registrar actions
+     * where this address was the referrer.
+     *
+     * @invariant Guaranteed to be a valid PriceEth with non-negative amount (>= 0n)
+     * @invariant Never null (records with null `total` in the database are treated as 0 when summing)
+     */
+    totalRevenueContribution: PriceEth;
+}
+declare const buildReferrerMetrics: (referrer: Address, totalReferrals: number, totalIncrementalDuration: Duration, totalRevenueContribution: PriceEth) => ReferrerMetrics;
+declare const validateReferrerMetrics: (metrics: ReferrerMetrics) => void;
+
+/**
+ * The rank of a referrer relative to all other referrers, where 1 is the
+ * top-ranked referrer.
+ *
+ * @invariant Guaranteed to be a positive integer (> 0)
+ */
+type ReferrerRank = number;
+declare const validateReferrerRank: (rank: ReferrerRank) => void;
+interface ReferrerMetricsForComparison {
+    /**
+     * The total incremental duration (in seconds) of all referrals made by the referrer within
+     * the {@link ReferralProgramRules}.
+     */
+    totalIncrementalDuration: Duration;
+    /**
+     * The fully lowercase Ethereum address of the referrer.
+     *
+     * @invariant Guaranteed to be a valid EVM address in lowercase format.
+     */
+    referrer: Address;
+}
+declare const compareReferrerMetrics: (a: ReferrerMetricsForComparison, b: ReferrerMetricsForComparison) => number;
+/**
+ * Sorts a list of referrers for leaderboard ranking.
+ * Returns a new array — does not mutate the input.
+ */
+declare const sortReferrerMetrics: (referrers: ReferrerMetrics[]) => ReferrerMetrics[];
+
+/**
+ * Represents metrics for a single referrer independent of other referrers,
+ * including a calculation of the referrer's score.
+ */
+interface ScoredReferrerMetricsPieSplit extends ReferrerMetrics {
+    /**
+     * The referrer's score.
+     *
+     * @invariant Guaranteed to be `calcReferrerScorePieSplit(totalIncrementalDuration)`
+     */
+    score: ReferrerScore;
+}
+declare const buildScoredReferrerMetricsPieSplit: (referrer: ReferrerMetrics) => ScoredReferrerMetricsPieSplit;
+declare const validateScoredReferrerMetricsPieSplit: (metrics: ScoredReferrerMetricsPieSplit) => void;
+/**
+ * Extends {@link ScoredReferrerMetricsPieSplit} to include additional metrics relative to all
+ * other referrers on a {@link ReferrerLeaderboardPieSplit} and {@link ReferralProgramRulesPieSplit}.
+ */
+interface RankedReferrerMetricsPieSplit extends ScoredReferrerMetricsPieSplit {
+    /**
+     * The referrer's rank on the {@link ReferrerLeaderboardPieSplit} relative to all other referrers.
+     */
+    rank: ReferrerRank;
+    /**
+     * Identifies if the referrer meets the qualifications of the {@link ReferralProgramRulesPieSplit} to receive a non-zero `awardPoolShare`.
+     *
+     * @invariant true if and only if `rank` is less than or equal to {@link ReferralProgramRulesPieSplit.maxQualifiedReferrers}
+     */
+    isQualified: boolean;
+    /**
+     * The referrer's final score boost.
+     *
+     * @invariant Guaranteed to be a number between 0 and 1 (inclusive)
+     * @invariant Calculated as: `1-((rank-1)/({@link ReferralProgramRulesPieSplit.maxQualifiedReferrers}-1))` if `isQualified` is `true`, else `0`
+     */
+    finalScoreBoost: number;
+    /**
+     * The referrer's final score.
+     *
+     * @invariant Calculated as: `score * (1 + finalScoreBoost)`
+     */
+    finalScore: ReferrerScore;
+}
+declare const validateRankedReferrerMetricsPieSplit: (metrics: RankedReferrerMetricsPieSplit, rules: ReferralProgramRulesPieSplit) => void;
+declare const buildRankedReferrerMetricsPieSplit: (referrer: ScoredReferrerMetricsPieSplit, rank: ReferrerRank, rules: ReferralProgramRulesPieSplit) => RankedReferrerMetricsPieSplit;
+/**
+ * Calculate the share of the award pool for a referrer.
+ * @param referrer - The referrer to calculate the award pool share for.
+ * @param aggregatedMetrics - Aggregated metrics for all referrers.
+ * @returns The referrer's share of the award pool as a number between 0 and 1 (inclusive).
+ */
+declare const calcReferrerAwardPoolSharePieSplit: (referrer: RankedReferrerMetricsPieSplit, aggregatedMetrics: AggregatedReferrerMetricsPieSplit) => number;
+/**
+ * Extends {@link RankedReferrerMetricsPieSplit} to include additional metrics
+ * relative to {@link AggregatedReferrerMetricsPieSplit}.
+ */
+interface AwardedReferrerMetricsPieSplit extends RankedReferrerMetricsPieSplit {
+    /**
+     * The referrer's share of the award pool.
+     *
+     * @invariant Guaranteed to be a number between 0 and 1 (inclusive)
+     * @invariant Calculated as: `finalScore / {@link AggregatedReferrerMetricsPieSplit.grandTotalQualifiedReferrersFinalScore}` if `isQualified` is `true`, else `0`
+     */
+    awardPoolShare: number;
+    /**
+     * The approximate USDC value of the referrer's share of the {@link ReferralProgramRulesPieSplit.totalAwardPoolValue}.
+     *
+     * @invariant Guaranteed to be a valid PriceUsdc with amount between 0 and {@link ReferralProgramRulesPieSplit.totalAwardPoolValue.amount} (inclusive)
+     * @invariant Calculated as: `awardPoolShare` * {@link ReferralProgramRulesPieSplit.totalAwardPoolValue.amount}
+     */
+    awardPoolApproxValue: PriceUsdc;
+}
+declare const validateAwardedReferrerMetricsPieSplit: (referrer: AwardedReferrerMetricsPieSplit, rules: ReferralProgramRulesPieSplit) => void;
+declare const buildAwardedReferrerMetricsPieSplit: (referrer: RankedReferrerMetricsPieSplit, aggregatedMetrics: AggregatedReferrerMetricsPieSplit, rules: ReferralProgramRulesPieSplit) => AwardedReferrerMetricsPieSplit;
+/**
+ * Extends {@link AwardedReferrerMetricsPieSplit} but with rank set to null to represent
+ * a referrer who is not on the leaderboard (has zero referrals within the rules associated with the leaderboard).
+ */
+interface UnrankedReferrerMetricsPieSplit extends Omit<AwardedReferrerMetricsPieSplit, "rank" | "isQualified"> {
+    /**
+     * The referrer is not on the leaderboard and therefore has no rank.
+     */
+    rank: null;
+    /**
+     * Always false for unranked referrers.
+     */
+    isQualified: false;
+}
+declare const validateUnrankedReferrerMetricsPieSplit: (metrics: UnrankedReferrerMetricsPieSplit) => void;
+/**
+ * Build an unranked zero-score referrer record for a referrer address that is not in the leaderboard.
+ *
+ * This is useful when you want to return a referrer record for an address that has no referrals
+ * and is not qualified for the leaderboard.
+ *
+ * @param referrer - The referrer address
+ * @returns An {@link UnrankedReferrerMetricsPieSplit} with zero values for all metrics and null rank
+ */
+declare const buildUnrankedReferrerMetricsPieSplit: (referrer: Address) => UnrankedReferrerMetricsPieSplit;
+
+/**
+ * Represents aggregated metrics for a list of {@link RankedReferrerMetricsPieSplit}.
+ */
+interface AggregatedReferrerMetricsPieSplit {
+    /**
+     * @invariant The sum of `totalReferrals` across all {@link RankedReferrerMetricsPieSplit} in the list.
+     * @invariant Guaranteed to be a non-negative integer (>= 0)
+     */
+    grandTotalReferrals: number;
+    /**
+     * @invariant The sum of `totalIncrementalDuration` across all {@link RankedReferrerMetricsPieSplit} in the list.
+     */
+    grandTotalIncrementalDuration: Duration;
+    /**
+     * The total revenue contribution in ETH to the ENS DAO from all referrals
+     * across all referrers on the leaderboard.
+     *
+     * This is the sum of `totalRevenueContribution` across all {@link RankedReferrerMetricsPieSplit} in the list.
+     *
+     * @invariant Guaranteed to be a valid PriceEth with non-negative amount (>= 0n)
+     */
+    grandTotalRevenueContribution: PriceEth;
+    /**
+     * @invariant The sum of `finalScore` across all {@link RankedReferrerMetricsPieSplit} where `isQualified` is `true`.
+     */
+    grandTotalQualifiedReferrersFinalScore: ReferrerScore;
+    /**
+     * @invariant Identifies the minimum final score required to become a qualified referrer.
+     * @invariant If `rules.maxQualifiedReferrers` is 0, then `minFinalScoreToQualify` is guaranteed to
+     *            be `Number.MAX_SAFE_INTEGER`.
+     * @invariant If `rules.maxQualifiedReferrers` is greater than 0, and there are no current referrers
+     *            matching the `rules`, then `minFinalScoreToQualify` is guaranteed to be `0`.
+     */
+    minFinalScoreToQualify: ReferrerScore;
+}
+declare const validateAggregatedReferrerMetricsPieSplit: (metrics: AggregatedReferrerMetricsPieSplit) => void;
+/**
+ * Builds aggregated pie-split metrics from a complete, globally ranked list of referrers.
+ *
+ * **IMPORTANT: This function expects a complete ranking of all referrers.**
+ *
+ * @param referrers - Must be a complete, globally ranked list of {@link RankedReferrerMetricsPieSplit}
+ *                    where ranks start at 1 and are consecutive.
+ *                    **This must NOT be a paginated or partial slice of the rankings.**
+ *
+ * @param rules - The {@link ReferralProgramRulesPieSplit} object that define qualification criteria,
+ *                including `maxQualifiedReferrers` (the maximum number of referrers
+ *                that can qualify for rewards).
+ *
+ * @returns Aggregated metrics including totals across all referrers and the minimum
+ *          score required to qualify.
+ *
+ * @remarks
+ * - If you need to work with paginated data, aggregate the full ranking first before
+ *   calling this function, or call this function on the complete dataset and then paginate
+ *   the results.
+ * - If `rules.maxQualifiedReferrers === 0`, no referrers can qualify and
+ *   `minFinalScoreToQualify` will be set to `Number.MAX_SAFE_INTEGER`.
+ * - If `referrers` is empty and `rules.maxQualifiedReferrers > 0`,
+ *   `minFinalScoreToQualify` will be set to `0` (anyone can qualify).
+ */
+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.
+ */
+declare const ReferrerEditionMetricsTypeIds: {
+    /**
+     * Represents a referrer who is ranked on the leaderboard.
+     */
+    readonly Ranked: "ranked";
+    /**
+     * Represents a referrer who is not ranked on the leaderboard.
+     */
+    readonly Unranked: "unranked";
+};
+/**
+ * The derived string union of possible {@link ReferrerEditionMetricsTypeIds}.
+ */
+type ReferrerEditionMetricsTypeId = (typeof ReferrerEditionMetricsTypeIds)[keyof typeof ReferrerEditionMetricsTypeIds];
+/**
+ * Referrer edition metrics 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 processed
+ * by business logic on the backend. When the server introduces a new award model type, older
+ * clients preserve the metrics rather than throwing, and downstream code that encounters this type
+ * should handle it gracefully rather than crashing.
+ */
+interface ReferrerEditionMetricsUnrecognized {
+    /**
+     * Discriminant — always `"unrecognized"`.
+     */
+    awardModel: typeof ReferralProgramAwardModels.Unrecognized;
+    /**
+     * The original, unrecognized `awardModel` string received from the server.
+     *
+     * @remarks Preserved for logging and debugging. Never used for business logic.
+     */
+    originalAwardModel: string;
+}
+
+/**
+ * Referrer edition metrics data for a specific referrer address on the pie-split leaderboard.
+ *
+ * Includes the referrer's awarded metrics from the leaderboard plus timestamp.
+ *
+ * Invariants:
+ * - `type` is always {@link ReferrerEditionMetricsTypeIds.Ranked}.
+ * - `awardModel` is always {@link ReferralProgramAwardModels.PieSplit} and equals `rules.awardModel`.
+ *
+ * @see {@link AwardedReferrerMetricsPieSplit}
+ */
+interface ReferrerEditionMetricsRankedPieSplit {
+    /**
+     * Discriminant identifying this as data from a pie-split leaderboard edition.
+     *
+     * @invariant Always equals `rules.awardModel` ({@link ReferralProgramAwardModels.PieSplit}).
+     */
+    awardModel: typeof ReferralProgramAwardModels.PieSplit;
+    /**
+     * The type of referrer edition metrics data.
+     */
+    type: typeof ReferrerEditionMetricsTypeIds.Ranked;
+    /**
+     * The {@link ReferralProgramRulesPieSplit} used to calculate the {@link AwardedReferrerMetricsPieSplit}.
+     */
+    rules: ReferralProgramRulesPieSplit;
+    /**
+     * The awarded referrer metrics from the leaderboard.
+     *
+     * Contains all calculated metrics including score, rank, qualification status,
+     * and award pool share information.
+     */
+    referrer: AwardedReferrerMetricsPieSplit;
+    /**
+     * Aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetricsPieSplit;
+    /**
+     * The status of the referral program ("Scheduled", "Active", or "Closed")
+     * calculated based on the program's timing relative to {@link accurateAsOf}.
+     */
+    status: ReferralProgramStatusId;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerEditionMetricsRankedPieSplit} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+/**
+ * Referrer edition metrics data for a specific referrer address NOT on the pie-split leaderboard.
+ *
+ * Includes the referrer's unranked metrics (with null rank and isQualified: false) plus timestamp.
+ *
+ * Invariants:
+ * - `type` is always {@link ReferrerEditionMetricsTypeIds.Unranked}.
+ * - `awardModel` is always {@link ReferralProgramAwardModels.PieSplit} and equals `rules.awardModel`.
+ *
+ * @see {@link UnrankedReferrerMetricsPieSplit}
+ */
+interface ReferrerEditionMetricsUnrankedPieSplit {
+    /**
+     * Discriminant identifying this as data from a pie-split leaderboard edition.
+     *
+     * @invariant Always equals `rules.awardModel` ({@link ReferralProgramAwardModels.PieSplit}).
+     */
+    awardModel: typeof ReferralProgramAwardModels.PieSplit;
+    /**
+     * The type of referrer edition metrics data.
+     */
+    type: typeof ReferrerEditionMetricsTypeIds.Unranked;
+    /**
+     * The {@link ReferralProgramRulesPieSplit} used to calculate the {@link UnrankedReferrerMetricsPieSplit}.
+     */
+    rules: ReferralProgramRulesPieSplit;
+    /**
+     * The unranked referrer metrics (not on the leaderboard).
+     *
+     * Contains all calculated metrics with rank set to null and isQualified set to false.
+     */
+    referrer: UnrankedReferrerMetricsPieSplit;
+    /**
+     * Aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetricsPieSplit;
+    /**
+     * The status of the referral program ("Scheduled", "Active", or "Closed")
+     * calculated based on the program's timing relative to {@link accurateAsOf}.
+     */
+    status: ReferralProgramStatusId;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerEditionMetricsUnrankedPieSplit} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+/**
+ * All referrer edition metrics variants for the pie-split award model.
+ *
+ * Use `type` to determine if the referrer is ranked or unranked.
+ */
+type ReferrerEditionMetricsPieSplit = ReferrerEditionMetricsRankedPieSplit | ReferrerEditionMetricsUnrankedPieSplit;
+
+/**
+ * Represents a leaderboard with the pie-split award model for any number of referrers.
+ */
+interface ReferrerLeaderboardPieSplit {
+    /**
+     * Discriminant identifying this as a pie-split leaderboard.
+     *
+     * @invariant Always equals `rules.awardModel` ({@link ReferralProgramAwardModels.PieSplit}).
+     */
+    awardModel: typeof ReferralProgramAwardModels.PieSplit;
+    /**
+     * The rules of the referral program that generated the {@link ReferrerLeaderboardPieSplit}.
+     */
+    rules: ReferralProgramRulesPieSplit;
+    /**
+     * The {@link AggregatedReferrerMetricsPieSplit} for all {@link RankedReferrerMetricsPieSplit} values in `referrers`.
+     */
+    aggregatedMetrics: AggregatedReferrerMetricsPieSplit;
+    /**
+     * Ordered map containing `AwardedReferrerMetricsPieSplit` for all referrers with 1 or more
+     * `totalReferrals` within the `rules` as of `accurateAsOf`.
+     *
+     * @invariant Map entries are ordered by `rank` (ascending).
+     * @invariant Map is empty if there are no referrers with 1 or more `totalReferrals`
+     *            within the `rules` as of `accurateAsOf`.
+     * @invariant If a fully-lowercase `Address` is not a key in this map then that `Address` had
+     *            0 `totalReferrals`, `totalIncrementalDuration`, and `score` within the
+     *            `rules` as of `accurateAsOf`.
+     * @invariant Each value in this map is guaranteed to have a non-zero
+     *            `totalReferrals`, `totalIncrementalDuration`, and `score`.
+     */
+    referrers: Map<Address, AwardedReferrerMetricsPieSplit>;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerLeaderboardPieSplit} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+declare const buildReferrerLeaderboardPieSplit: (allReferrers: ReferrerMetrics[], rules: ReferralProgramRulesPieSplit, accurateAsOf: UnixTimestamp) => ReferrerLeaderboardPieSplit;
+
+/**
+ * Extends {@link ReferrerMetrics} with computed base revenue contribution.
+ */
+interface ReferrerMetricsRevShareLimit extends ReferrerMetrics {
+    /**
+     * The referrer's base revenue contribution (base-fee-only: $5 × years of incremental duration).
+     * Used for qualification and award calculation in the rev-share-limit model.
+     *
+     * @invariant Guaranteed to be `priceUsdc(BASE_REVENUE_CONTRIBUTION_PER_YEAR.amount * BigInt(totalIncrementalDuration) / BigInt(SECONDS_PER_YEAR))`
+     */
+    totalBaseRevenueContribution: PriceUsdc;
+}
+declare const validateReferrerMetricsRevShareLimit: (metrics: ReferrerMetricsRevShareLimit) => void;
+declare const buildReferrerMetricsRevShareLimit: (metrics: ReferrerMetrics) => ReferrerMetricsRevShareLimit;
+/**
+ * Extends {@link ReferrerMetricsRevShareLimit} with rank, qualification status, and admin disqualification.
+ */
+interface RankedReferrerMetricsRevShareLimit extends ReferrerMetricsRevShareLimit {
+    /**
+     * The referrer's rank on the {@link ReferrerLeaderboardRevShareLimit} relative to all other referrers.
+     */
+    rank: ReferrerRank;
+    /**
+     * Identifies if the referrer meets the qualifications of the {@link ReferralProgramRulesRevShareLimit} to receive a non-zero `awardPoolShare`.
+     *
+     * @invariant true if and only if `totalBaseRevenueContribution` is greater than or equal to
+     *   {@link ReferralProgramRulesRevShareLimit.minQualifiedRevenueContribution} AND
+     *   {@link isAdminDisqualified} is false.
+     */
+    isQualified: boolean;
+    /**
+     * Whether this referrer has been admin-disqualified from the edition.
+     *
+     * @invariant When true, {@link isQualified} is false.
+     */
+    isAdminDisqualified: boolean;
+    /**
+     * The reason for admin disqualification, or null if not disqualified.
+     *
+     * @invariant null when {@link isAdminDisqualified} is false.
+     * @invariant Non-empty string when {@link isAdminDisqualified} is true.
+     */
+    adminDisqualificationReason: string | null;
+}
+declare const validateRankedReferrerMetricsRevShareLimit: (metrics: RankedReferrerMetricsRevShareLimit, rules: ReferralProgramRulesRevShareLimit) => void;
+declare const buildRankedReferrerMetricsRevShareLimit: (referrer: ReferrerMetricsRevShareLimit, rank: ReferrerRank, rules: ReferralProgramRulesRevShareLimit) => RankedReferrerMetricsRevShareLimit;
+/**
+ * Extends {@link RankedReferrerMetricsRevShareLimit} with approximate award value.
+ */
+interface AwardedReferrerMetricsRevShareLimit extends RankedReferrerMetricsRevShareLimit {
+    /**
+     * The standard (uncapped) USDC award value for this referrer, computed as
+     * `qualifiedRevenueShare × totalBaseRevenueContribution`.
+     *
+     * Represents what the referrer would receive if the pool were unlimited and the referrer were qualified.
+     * Independent of the pool state and qualification status.
+     */
+    standardAwardValue: PriceUsdc;
+    /**
+     * The approximate USDC value of the referrer's award.
+     *
+     * This is the amount actually claimed from the pool by this referrer, capped by
+     * the remaining pool at the time of their qualifying events.
+     *
+     * @invariant Guaranteed to be a valid PriceUsdc with amount between 0 and {@link ReferralProgramRulesRevShareLimit.totalAwardPoolValue.amount} (inclusive)
+     * @invariant Always <= standardAwardValue.amount
+     * @invariant Amount equal to 0 when {@link isAdminDisqualified} is true.
+     */
+    awardPoolApproxValue: PriceUsdc;
+}
+declare const validateAwardedReferrerMetricsRevShareLimit: (metrics: AwardedReferrerMetricsRevShareLimit, rules: ReferralProgramRulesRevShareLimit) => void;
+declare const buildAwardedReferrerMetricsRevShareLimit: (referrer: RankedReferrerMetricsRevShareLimit, standardAwardValue: PriceUsdc, awardPoolApproxValue: PriceUsdc, rules: ReferralProgramRulesRevShareLimit) => AwardedReferrerMetricsRevShareLimit;
+/**
+ * Extends {@link AwardedReferrerMetricsRevShareLimit} but with rank set to null to represent
+ * a referrer who is not on the leaderboard (has zero referrals within the rules associated with the leaderboard).
+ */
+interface UnrankedReferrerMetricsRevShareLimit extends Omit<AwardedReferrerMetricsRevShareLimit, "rank" | "isQualified"> {
+    /**
+     * The referrer is not on the leaderboard and therefore has no rank.
+     */
+    rank: null;
+    /**
+     * Always false for unranked referrers.
+     */
+    isQualified: false;
+}
+declare const validateUnrankedReferrerMetricsRevShareLimit: (metrics: UnrankedReferrerMetricsRevShareLimit, rules: ReferralProgramRulesRevShareLimit) => void;
+/**
+ * Build an unranked zero-metrics rev-share-limit referrer record for an address not on the leaderboard.
+ */
+declare const buildUnrankedReferrerMetricsRevShareLimit: (referrer: Address, rules: ReferralProgramRulesRevShareLimit) => UnrankedReferrerMetricsRevShareLimit;
+
+/**
+ * Represents aggregated metrics for a list of referrers on a rev-share-limit leaderboard.
+ */
+interface AggregatedReferrerMetricsRevShareLimit {
+    /**
+     * @invariant The sum of `totalReferrals` across all referrers in the list.
+     * @invariant Guaranteed to be a non-negative integer (>= 0)
+     */
+    grandTotalReferrals: number;
+    /**
+     * @invariant The sum of `totalIncrementalDuration` across all referrers in the list.
+     */
+    grandTotalIncrementalDuration: Duration;
+    /**
+     * The total revenue contribution in ETH to the ENS DAO from all referrals
+     * across all referrers on the leaderboard.
+     *
+     * This is the sum of `totalRevenueContribution` across all referrers in the list.
+     *
+     * @invariant Guaranteed to be a valid PriceEth with non-negative amount (>= 0n)
+     */
+    grandTotalRevenueContribution: PriceEth;
+    /**
+     * The remaining amount in the award pool after subtracting all qualified awards
+     * claimed during the sequential race processing.
+     *
+     * @invariant Guaranteed to be a valid PriceUsdc with non-negative amount (>= 0n)
+     */
+    awardPoolRemaining: PriceUsdc;
+}
+declare const validateAggregatedReferrerMetricsRevShareLimit: (metrics: AggregatedReferrerMetricsRevShareLimit) => void;
+/**
+ * Builds aggregated rev-share-limit metrics from a complete list of referrers and
+ * the award pool remaining after sequential race processing.
+ *
+ * **IMPORTANT: This function expects a complete list of all referrers.**
+ *
+ * @param referrers - Must be a complete list of referrers with their totals.
+ *                    **This must NOT be a paginated or partial slice.**
+ *
+ * @param awardPoolRemaining - The amount remaining in the award pool after the sequential
+ *                             race algorithm has processed all events.
+ *
+ * @returns Aggregated metrics including totals across all referrers and the award pool remaining.
+ */
+declare const buildAggregatedReferrerMetricsRevShareLimit: (referrers: AwardedReferrerMetricsRevShareLimit[], awardPoolRemaining: PriceUsdc) => AggregatedReferrerMetricsRevShareLimit;
+
+/**
+ * Represents a single raw referral event.
+ *
+ * Used as input to the sequential race algorithm for the rev-share-limit award model.
+ * Events are processed in chronological order to determine award claims from the pool.
+ */
+interface ReferralEvent {
+    /**
+     * The fully lowercase Ethereum address of the referrer.
+     */
+    referrer: Address;
+    /**
+     * Unix seconds block timestamp.
+     */
+    timestamp: UnixTimestamp;
+    /**
+     * 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.
+     */
+    id: string;
+    /**
+     * Duration in seconds contributed by this single referral event.
+     */
+    incrementalDuration: Duration;
+    /**
+     * Revenue contribution in ETH from this single referral event.
+     */
+    incrementalRevenueContribution: PriceEth;
+}
+
+/**
+ * Represents a leaderboard with the rev-share-limit award model for any number of referrers.
+ */
+interface ReferrerLeaderboardRevShareLimit {
+    /**
+     * Discriminant identifying this as a rev-share-limit leaderboard.
+     *
+     * @invariant Always equals `rules.awardModel` ({@link ReferralProgramAwardModels.RevShareLimit}).
+     */
+    awardModel: typeof ReferralProgramAwardModels.RevShareLimit;
+    /**
+     * The rules of the referral program that generated the {@link ReferrerLeaderboardRevShareLimit}.
+     */
+    rules: ReferralProgramRulesRevShareLimit;
+    /**
+     * The {@link AggregatedReferrerMetricsRevShareLimit} for all {@link AwardedReferrerMetricsRevShareLimit} values in `referrers`.
+     */
+    aggregatedMetrics: AggregatedReferrerMetricsRevShareLimit;
+    /**
+     * Ordered map containing {@link AwardedReferrerMetricsRevShareLimit} for all referrers with 1 or more
+     * `totalReferrals` within the `rules` as of `accurateAsOf`.
+     *
+     * @invariant Map entries are ordered by `rank` (ascending).
+     * @invariant Map is empty if there are no referrers with 1 or more `totalReferrals`
+     *            within the `rules` as of `accurateAsOf`.
+     * @invariant If a fully-lowercase `Address` is not a key in this map then that `Address` had
+     *            0 `totalReferrals`, `totalIncrementalDuration`, and `totalRevenueContribution` within the
+     *            `rules` as of `accurateAsOf`.
+     * @invariant Each value in this map is guaranteed to have a non-zero
+     *            `totalReferrals` and `totalIncrementalDuration`.
+     */
+    referrers: Map<Address, AwardedReferrerMetricsRevShareLimit>;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerLeaderboardRevShareLimit} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+/**
+ * Builds a {@link ReferrerLeaderboardRevShareLimit} using a sequential "first-come, first-served"
+ * race algorithm over individual referral events.
+ *
+ * Events are processed in chronological order. When a referrer first crosses the qualification
+ * threshold, they claim ALL accumulated standard award value at once (capped by remaining pool).
+ * After qualifying, each subsequent event claims that event's incremental standard award (also
+ * capped). Once the pool reaches $0, no further awards are issued to anyone.
+ *
+ * @param events - Raw referral events from the database (unsorted; will be sorted internally).
+ * @param rules - The {@link ReferralProgramRulesRevShareLimit} defining the program parameters.
+ * @param accurateAsOf - Timestamp indicating data freshness.
+ */
+declare const buildReferrerLeaderboardRevShareLimit: (events: ReferralEvent[], rules: ReferralProgramRulesRevShareLimit, accurateAsOf: UnixTimestamp) => ReferrerLeaderboardRevShareLimit;
+
+/**
+ * Represents a leaderboard for any number of referrers.
+ *
+ * Use `awardModel` to narrow the specific variant at runtime.
+ */
+type ReferrerLeaderboard = ReferrerLeaderboardPieSplit | ReferrerLeaderboardRevShareLimit;
+
+/**
+ * The default number of referrers per leaderboard page.
+ */
+declare const REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT = 25;
+/**
+ * The maximum number of referrers per leaderboard page.
+ */
+declare const REFERRERS_PER_LEADERBOARD_PAGE_MAX = 100;
+/**
+ * Pagination params for leaderboard queries.
+ */
+interface ReferrerLeaderboardPageParams {
+    /**
+     * Requested referrer leaderboard page number (1-indexed)
+     * @invariant Must be a positive integer (>= 1)
+     * @default 1
+     */
+    page?: number;
+    /**
+     * Maximum number of referrers to return per leaderboard page
+     * @invariant Must be a positive integer (>= 1) and less than or equal to {@link REFERRERS_PER_LEADERBOARD_PAGE_MAX}
+     * @default {@link REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT}
+     */
+    recordsPerPage?: number;
+}
+declare const buildReferrerLeaderboardPageParams: (params: ReferrerLeaderboardPageParams) => Required<ReferrerLeaderboardPageParams>;
+interface ReferrerLeaderboardPageContext extends Required<ReferrerLeaderboardPageParams> {
+    /**
+     * Total number of referrers across all leaderboard pages
+     * @invariant Guaranteed to be a non-negative integer (>= 0)
+     */
+    totalRecords: number;
+    /**
+     * Total number of pages in the leaderboard
+     * @invariant Guaranteed to be a positive integer (>= 1)
+     */
+    totalPages: number;
+    /**
+     * Indicates if there is a next page available
+     * @invariant true if and only if (`page` * `recordsPerPage` < `totalRecords`)
+     */
+    hasNext: boolean;
+    /**
+     * Indicates if there is a previous page available
+     * @invariant true if and only if (`page` > 1)
+     */
+    hasPrev: boolean;
+    /**
+     * The start index of the referrers on the page (0-indexed)
+     *
+     * `undefined` if and only if `totalRecords` is 0.
+     *
+     * @invariant Guaranteed to be a non-negative integer (>= 0)
+     */
+    startIndex?: number;
+    /**
+     * The end index of the referrers on the page (0-indexed)
+     *
+     * `undefined` if and only if `totalRecords` is 0.
+     *
+     * @invariant Guaranteed to be a non-negative integer (>= 0)
+     * @invariant If `totalRecords` is > 0:
+     *            - Guaranteed to be greater than or equal to `startIndex`.
+     *            - Guaranteed to be less than `totalRecords`.
+     */
+    endIndex?: number;
+}
+declare const validateReferrerLeaderboardPageContext: (context: ReferrerLeaderboardPageContext) => void;
+declare const buildReferrerLeaderboardPageContext: (optionalParams: ReferrerLeaderboardPageParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPageContext;
+/**
+ * Base fields shared by all leaderboard page variants.
+ */
+interface BaseReferrerLeaderboardPage {
+    /**
+     * Discriminant identifying the award model for this leaderboard page.
+     */
+    awardModel: ReferralProgramAwardModel;
+    /**
+     * The {@link ReferrerLeaderboardPageContext} of this page relative to the overall leaderboard.
+     */
+    pageContext: ReferrerLeaderboardPageContext;
+    /**
+     * The status of the referral program ("Scheduled", "Active", or "Closed")
+     * calculated based on the program's timing relative to {@link accurateAsOf}.
+     */
+    status: ReferralProgramStatusId;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build this page was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+/**
+ * A leaderboard page whose `awardModel` is not recognized by this client version.
+ *
+ * @remarks
+ * This is a **client-side forward-compatibility** type only. It is never serialized or processed
+ * by business logic on the backend. When the server introduces a new award model type, older
+ * clients preserve the page rather than throwing, and downstream code that encounters this type
+ * should handle it gracefully rather than crashing.
+ */
+interface ReferrerLeaderboardPageUnrecognized extends BaseReferrerLeaderboardPage {
+    /**
+     * Discriminant — always `"unrecognized"`.
+     */
+    awardModel: typeof ReferralProgramAwardModels.Unrecognized;
+    /**
+     * The original, unrecognized `awardModel` string received from the server.
+     *
+     * @remarks Preserved for logging and debugging. Never used for business logic.
+     */
+    originalAwardModel: string;
+}
+/**
+ * Extracts the referrers for the current page from a fully-ranked Map.
+ * Generic over the referrer type so each model variant retains its specific type.
+ */
+declare function sliceReferrers<T>(referrers: Map<Address, T>, pageContext: ReferrerLeaderboardPageContext): T[];
+
+/**
+ * A page of referrers from the pie-split referrer leaderboard.
+ */
+interface ReferrerLeaderboardPagePieSplit extends BaseReferrerLeaderboardPage {
+    /**
+     * Discriminant identifying this as a page from a pie-split leaderboard.
+     *
+     * @invariant Always equals `rules.awardModel` ({@link ReferralProgramAwardModels.PieSplit}).
+     */
+    awardModel: typeof ReferralProgramAwardModels.PieSplit;
+    /**
+     * The {@link ReferralProgramRulesPieSplit} used to generate the {@link ReferrerLeaderboardPieSplit}
+     * that this {@link ReferrerLeaderboardPagePieSplit} comes from.
+     */
+    rules: ReferralProgramRulesPieSplit;
+    /**
+     * Ordered list of {@link AwardedReferrerMetricsPieSplit} for the {@link ReferrerLeaderboardPagePieSplit}
+     * described by {@link pageContext} within the related {@link ReferrerLeaderboardPieSplit}.
+     *
+     * @invariant Array will be empty if `pageContext.totalRecords` is 0.
+     * @invariant Array entries are ordered by `rank` (ascending).
+     */
+    referrers: AwardedReferrerMetricsPieSplit[];
+    /**
+     * The aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetricsPieSplit;
+}
+declare function buildLeaderboardPagePieSplit(pageContext: ReferrerLeaderboardPageContext, leaderboard: ReferrerLeaderboardPieSplit): ReferrerLeaderboardPagePieSplit;
+
+/**
+ * Serialized representation of {@link ReferralProgramRulesPieSplit}.
+ */
+interface SerializedReferralProgramRulesPieSplit extends Omit<ReferralProgramRulesPieSplit, "totalAwardPoolValue" | "rulesUrl"> {
+    totalAwardPoolValue: SerializedPriceUsdc;
+    rulesUrl: string;
+}
+/**
+ * Serialized representation of {@link AggregatedReferrerMetricsPieSplit}.
+ */
+interface SerializedAggregatedReferrerMetricsPieSplit extends Omit<AggregatedReferrerMetricsPieSplit, "grandTotalRevenueContribution"> {
+    grandTotalRevenueContribution: SerializedPriceEth;
+}
+/**
+ * Serialized representation of {@link AwardedReferrerMetricsPieSplit}.
+ */
+interface SerializedAwardedReferrerMetricsPieSplit extends Omit<AwardedReferrerMetricsPieSplit, "totalRevenueContribution" | "awardPoolApproxValue"> {
+    totalRevenueContribution: SerializedPriceEth;
+    awardPoolApproxValue: SerializedPriceUsdc;
+}
+/**
+ * Serialized representation of {@link UnrankedReferrerMetricsPieSplit}.
+ */
+interface SerializedUnrankedReferrerMetricsPieSplit extends Omit<UnrankedReferrerMetricsPieSplit, "totalRevenueContribution" | "awardPoolApproxValue"> {
+    totalRevenueContribution: SerializedPriceEth;
+    awardPoolApproxValue: SerializedPriceUsdc;
+}
+/**
+ * Serialized representation of {@link ReferrerLeaderboardPagePieSplit}.
+ */
+interface SerializedReferrerLeaderboardPagePieSplit extends Omit<ReferrerLeaderboardPagePieSplit, "rules" | "referrers" | "aggregatedMetrics"> {
+    rules: SerializedReferralProgramRulesPieSplit;
+    referrers: SerializedAwardedReferrerMetricsPieSplit[];
+    aggregatedMetrics: SerializedAggregatedReferrerMetricsPieSplit;
+}
+/**
+ * Serialized representation of {@link ReferrerEditionMetricsRankedPieSplit}.
+ */
+interface SerializedReferrerEditionMetricsRankedPieSplit extends Omit<ReferrerEditionMetricsRankedPieSplit, "rules" | "referrer" | "aggregatedMetrics"> {
+    rules: SerializedReferralProgramRulesPieSplit;
+    referrer: SerializedAwardedReferrerMetricsPieSplit;
+    aggregatedMetrics: SerializedAggregatedReferrerMetricsPieSplit;
+}
+/**
+ * Serialized representation of {@link ReferrerEditionMetricsUnrankedPieSplit}.
+ */
+interface SerializedReferrerEditionMetricsUnrankedPieSplit extends Omit<ReferrerEditionMetricsUnrankedPieSplit, "rules" | "referrer" | "aggregatedMetrics"> {
+    rules: SerializedReferralProgramRulesPieSplit;
+    referrer: SerializedUnrankedReferrerMetricsPieSplit;
+    aggregatedMetrics: SerializedAggregatedReferrerMetricsPieSplit;
+}
+/**
+ * Serialized representation of {@link ReferrerEditionMetricsPieSplit}.
+ */
+type SerializedReferrerEditionMetricsPieSplit = SerializedReferrerEditionMetricsRankedPieSplit | SerializedReferrerEditionMetricsUnrankedPieSplit;
+
+/**
+ * Referrer edition metrics data for a specific referrer on a rev-share-limit leaderboard.
+ *
+ * Includes the referrer's awarded metrics from the leaderboard plus timestamp.
+ *
+ * @see {@link AwardedReferrerMetricsRevShareLimit}
+ */
+interface ReferrerEditionMetricsRankedRevShareLimit {
+    /**
+     * Discriminant identifying this as data from a rev-share-limit leaderboard edition.
+     *
+     * @invariant Always equals `rules.awardModel` ({@link ReferralProgramAwardModels.RevShareLimit}).
+     */
+    awardModel: typeof ReferralProgramAwardModels.RevShareLimit;
+    /**
+     * The type of referrer edition metrics data.
+     */
+    type: typeof ReferrerEditionMetricsTypeIds.Ranked;
+    /**
+     * The {@link ReferralProgramRulesRevShareLimit} used to calculate the {@link AwardedReferrerMetricsRevShareLimit}.
+     */
+    rules: ReferralProgramRulesRevShareLimit;
+    /**
+     * The awarded referrer metrics from the leaderboard.
+     *
+     * Contains all calculated metrics including rank, qualification status,
+     * standard award value, and award pool approximate value.
+     */
+    referrer: AwardedReferrerMetricsRevShareLimit;
+    /**
+     * Aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetricsRevShareLimit;
+    /**
+     * The status of the referral program ("Scheduled", "Active", or "Closed")
+     * calculated based on the program's timing relative to {@link accurateAsOf}.
+     */
+    status: ReferralProgramStatusId;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerEditionMetricsRankedRevShareLimit} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+/**
+ * Referrer edition metrics data for a specific referrer address NOT on the rev-share-limit leaderboard.
+ *
+ * Includes the referrer's unranked metrics (with null rank and isQualified: false) plus timestamp.
+ *
+ * @see {@link UnrankedReferrerMetricsRevShareLimit}
+ */
+interface ReferrerEditionMetricsUnrankedRevShareLimit {
+    /**
+     * Discriminant identifying this as data from a rev-share-limit leaderboard edition.
+     *
+     * @invariant Always equals `rules.awardModel` ({@link ReferralProgramAwardModels.RevShareLimit}).
+     */
+    awardModel: typeof ReferralProgramAwardModels.RevShareLimit;
+    /**
+     * The type of referrer edition metrics data.
+     */
+    type: typeof ReferrerEditionMetricsTypeIds.Unranked;
+    /**
+     * The {@link ReferralProgramRulesRevShareLimit} used to calculate the {@link UnrankedReferrerMetricsRevShareLimit}.
+     */
+    rules: ReferralProgramRulesRevShareLimit;
+    /**
+     * The unranked referrer metrics (not on the leaderboard).
+     *
+     * Contains all calculated metrics with rank set to null and isQualified set to false.
+     */
+    referrer: UnrankedReferrerMetricsRevShareLimit;
+    /**
+     * Aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetricsRevShareLimit;
+    /**
+     * The status of the referral program ("Scheduled", "Active", or "Closed")
+     * calculated based on the program's timing relative to {@link accurateAsOf}.
+     */
+    status: ReferralProgramStatusId;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerEditionMetricsUnrankedRevShareLimit} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+/**
+ * All referrer edition metrics variants for the rev-share-limit award model.
+ *
+ * Use `type` to determine if the referrer is ranked or unranked.
+ */
+type ReferrerEditionMetricsRevShareLimit = ReferrerEditionMetricsRankedRevShareLimit | ReferrerEditionMetricsUnrankedRevShareLimit;
+
+/**
+ * A page of referrers from the rev-share-limit referrer leaderboard.
+ */
+interface ReferrerLeaderboardPageRevShareLimit extends BaseReferrerLeaderboardPage {
+    /**
+     * Discriminant identifying this as a page from a rev-share-limit leaderboard.
+     *
+     * @invariant Always equals `rules.awardModel` ({@link ReferralProgramAwardModels.RevShareLimit}).
+     */
+    awardModel: typeof ReferralProgramAwardModels.RevShareLimit;
+    /**
+     * The {@link ReferralProgramRulesRevShareLimit} used to generate the {@link ReferrerLeaderboardRevShareLimit}
+     * that this {@link ReferrerLeaderboardPageRevShareLimit} comes from.
+     */
+    rules: ReferralProgramRulesRevShareLimit;
+    /**
+     * Ordered list of {@link AwardedReferrerMetricsRevShareLimit} for the {@link ReferrerLeaderboardPageRevShareLimit}
+     * described by {@link pageContext} within the related {@link ReferrerLeaderboard}.
+     *
+     * @invariant Array will be empty if `pageContext.totalRecords` is 0.
+     * @invariant Array entries are ordered by `rank` (ascending).
+     */
+    referrers: AwardedReferrerMetricsRevShareLimit[];
+    /**
+     * The aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetricsRevShareLimit;
+}
+declare function buildLeaderboardPageRevShareLimit(pageContext: ReferrerLeaderboardPageContext, leaderboard: ReferrerLeaderboardRevShareLimit): ReferrerLeaderboardPageRevShareLimit;
+
+/**
+ * Serialized representation of {@link ReferralProgramRulesRevShareLimit}.
+ */
+interface SerializedReferralProgramRulesRevShareLimit extends Omit<ReferralProgramRulesRevShareLimit, "totalAwardPoolValue" | "minQualifiedRevenueContribution" | "rulesUrl"> {
+    totalAwardPoolValue: SerializedPriceUsdc;
+    minQualifiedRevenueContribution: SerializedPriceUsdc;
+    rulesUrl: string;
+}
+/**
+ * Serialized representation of {@link AggregatedReferrerMetricsRevShareLimit}.
+ */
+interface SerializedAggregatedReferrerMetricsRevShareLimit extends Omit<AggregatedReferrerMetricsRevShareLimit, "grandTotalRevenueContribution" | "awardPoolRemaining"> {
+    grandTotalRevenueContribution: SerializedPriceEth;
+    awardPoolRemaining: SerializedPriceUsdc;
+}
+/**
+ * Serialized representation of {@link AwardedReferrerMetricsRevShareLimit}.
+ */
+interface SerializedAwardedReferrerMetricsRevShareLimit extends Omit<AwardedReferrerMetricsRevShareLimit, "totalRevenueContribution" | "totalBaseRevenueContribution" | "standardAwardValue" | "awardPoolApproxValue"> {
+    totalRevenueContribution: SerializedPriceEth;
+    totalBaseRevenueContribution: SerializedPriceUsdc;
+    standardAwardValue: SerializedPriceUsdc;
+    awardPoolApproxValue: SerializedPriceUsdc;
+}
+/**
+ * Serialized representation of {@link UnrankedReferrerMetricsRevShareLimit}.
+ */
+interface SerializedUnrankedReferrerMetricsRevShareLimit extends Omit<UnrankedReferrerMetricsRevShareLimit, "totalRevenueContribution" | "totalBaseRevenueContribution" | "standardAwardValue" | "awardPoolApproxValue"> {
+    totalRevenueContribution: SerializedPriceEth;
+    totalBaseRevenueContribution: SerializedPriceUsdc;
+    standardAwardValue: SerializedPriceUsdc;
+    awardPoolApproxValue: SerializedPriceUsdc;
+}
+/**
+ * Serialized representation of {@link ReferrerLeaderboardPageRevShareLimit}.
+ */
+interface SerializedReferrerLeaderboardPageRevShareLimit extends Omit<ReferrerLeaderboardPageRevShareLimit, "rules" | "referrers" | "aggregatedMetrics"> {
+    rules: SerializedReferralProgramRulesRevShareLimit;
+    referrers: SerializedAwardedReferrerMetricsRevShareLimit[];
+    aggregatedMetrics: SerializedAggregatedReferrerMetricsRevShareLimit;
+}
+/**
+ * Serialized representation of {@link ReferrerEditionMetricsRankedRevShareLimit}.
+ */
+interface SerializedReferrerEditionMetricsRankedRevShareLimit extends Omit<ReferrerEditionMetricsRankedRevShareLimit, "rules" | "referrer" | "aggregatedMetrics"> {
+    rules: SerializedReferralProgramRulesRevShareLimit;
+    referrer: SerializedAwardedReferrerMetricsRevShareLimit;
+    aggregatedMetrics: SerializedAggregatedReferrerMetricsRevShareLimit;
+}
+/**
+ * Serialized representation of {@link ReferrerEditionMetricsUnrankedRevShareLimit}.
+ */
+interface SerializedReferrerEditionMetricsUnrankedRevShareLimit extends Omit<ReferrerEditionMetricsUnrankedRevShareLimit, "rules" | "referrer" | "aggregatedMetrics"> {
+    rules: SerializedReferralProgramRulesRevShareLimit;
+    referrer: SerializedUnrankedReferrerMetricsRevShareLimit;
+    aggregatedMetrics: SerializedAggregatedReferrerMetricsRevShareLimit;
+}
+/**
+ * Serialized representation of {@link ReferrerEditionMetricsRevShareLimit}.
+ */
+type SerializedReferrerEditionMetricsRevShareLimit = SerializedReferrerEditionMetricsRankedRevShareLimit | SerializedReferrerEditionMetricsUnrankedRevShareLimit;
+
+/**
+ * Referrer edition metrics data for a specific referrer address.
+ *
+ * Use `awardModel` to narrow the award model variant, then `type` to narrow ranked vs unranked.
+ * When `awardModel` is `"unrecognized"`, the data was produced by a server running a newer
+ * version — use {@link ReferrerEditionMetricsUnrecognized} to access `originalAwardModel`.
+ */
+type ReferrerEditionMetrics = ReferrerEditionMetricsPieSplit | ReferrerEditionMetricsRevShareLimit | ReferrerEditionMetricsUnrecognized;
+/**
+ * Get the edition metrics for a specific referrer from the leaderboard.
+ *
+ * Returns a {@link ReferrerEditionMetricsPieSplit} or {@link ReferrerEditionMetricsRevShareLimit}
+ * with `type: "ranked"` if the referrer is on the leaderboard, or `type: "unranked"` otherwise.
+ *
+ * @param referrer - The referrer address to look up
+ * @param leaderboard - The referrer leaderboard to query
+ * @returns The appropriate {@link ReferrerEditionMetrics}
+ */
+declare const getReferrerEditionMetrics: (referrer: Address, leaderboard: ReferrerLeaderboard) => ReferrerEditionMetrics;
+
+/**
+ * A page of referrers from the referrer leaderboard.
+ *
+ * Use `awardModel` to narrow the specific variant at runtime. Within each variant,
+ * `rules`, `referrers`, and `aggregatedMetrics` are all guaranteed to be from the same model.
+ * When `awardModel` is `"unrecognized"`, the page was produced by a server running a newer
+ * version — use {@link ReferrerLeaderboardPageUnrecognized} to access `originalAwardModel`.
+ */
+type ReferrerLeaderboardPage = ReferrerLeaderboardPagePieSplit | ReferrerLeaderboardPageRevShareLimit | ReferrerLeaderboardPageUnrecognized;
+declare const getReferrerLeaderboardPage: (pageParams: ReferrerLeaderboardPageParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPage;
+
+/**
+ * Request parameters for a referrer leaderboard page query.
+ */
+interface ReferrerLeaderboardPageRequest extends ReferrerLeaderboardPageParams {
+    /** The referral program edition slug */
+    edition: ReferralProgramEditionSlug;
+}
+/**
+ * A status code for a referrer leaderboard page API response.
+ */
+declare const ReferrerLeaderboardPageResponseCodes: {
+    /**
+     * Represents that the requested referrer leaderboard page is available.
+     */
+    readonly Ok: "ok";
+    /**
+     * Represents that the referrer leaderboard data is not available.
+     */
+    readonly Error: "error";
+};
+/**
+ * The derived string union of possible {@link ReferrerLeaderboardPageResponseCodes}.
+ */
+type ReferrerLeaderboardPageResponseCode = (typeof ReferrerLeaderboardPageResponseCodes)[keyof typeof ReferrerLeaderboardPageResponseCodes];
+/**
+ * A referrer leaderboard page response when the data is available.
+ */
+type ReferrerLeaderboardPageResponseOk = {
+    responseCode: typeof ReferrerLeaderboardPageResponseCodes.Ok;
+    data: ReferrerLeaderboardPage;
+};
+/**
+ * A referrer leaderboard page response when the data is not available.
+ */
+type ReferrerLeaderboardPageResponseError = {
+    responseCode: typeof ReferrerLeaderboardPageResponseCodes.Error;
+    error: string;
+    errorMessage: string;
+};
+/**
+ * A referrer leaderboard page API response.
+ *
+ * Use the `responseCode` field to determine the specific type interpretation
+ * at runtime.
+ */
+type ReferrerLeaderboardPageResponse = ReferrerLeaderboardPageResponseOk | ReferrerLeaderboardPageResponseError;
+/**
+ * Maximum number of editions that can be requested in a single {@link ReferrerMetricsEditionsRequest}.
+ */
+declare const MAX_EDITIONS_PER_REQUEST = 20;
+/**
+ * Request parameters for referrer metrics query.
+ */
+interface ReferrerMetricsEditionsRequest {
+    /** The Ethereum address of the referrer to query */
+    referrer: Address;
+    /** Array of edition slugs to query (min 1, max {@link MAX_EDITIONS_PER_REQUEST}, must be distinct) */
+    editions: ReferralProgramEditionSlug[];
+}
+/**
+ * A status code for referrer metrics API responses.
+ */
+declare const ReferrerMetricsEditionsResponseCodes: {
+    /**
+     * Represents that the referrer metrics data for the requested editions is available.
+     */
+    readonly Ok: "ok";
+    /**
+     * Represents that an error occurred while fetching the data.
+     */
+    readonly Error: "error";
+};
+/**
+ * The derived string union of possible {@link ReferrerMetricsEditionsResponseCodes}.
+ */
+type ReferrerMetricsEditionsResponseCode = (typeof ReferrerMetricsEditionsResponseCodes)[keyof typeof ReferrerMetricsEditionsResponseCodes];
+/**
+ * Referrer metrics data for requested editions.
+ *
+ * Maps each requested edition slug to the referrer's metrics for that edition.
+ * Uses Partial because TypeScript cannot know at compile time which specific edition
+ * slugs are requested. At runtime, when responseCode is Ok, all requested edition slugs
+ * are guaranteed to be present in this record.
+ */
+type ReferrerMetricsEditionsData = Partial<Record<ReferralProgramEditionSlug, ReferrerEditionMetrics>>;
+/**
+ * A successful response containing referrer metrics for the requested editions.
+ */
+type ReferrerMetricsEditionsResponseOk = {
+    responseCode: typeof ReferrerMetricsEditionsResponseCodes.Ok;
+    data: ReferrerMetricsEditionsData;
+};
+/**
+ * A referrer metrics editions response when an error occurs.
+ */
+type ReferrerMetricsEditionsResponseError = {
+    responseCode: typeof ReferrerMetricsEditionsResponseCodes.Error;
+    error: string;
+    errorMessage: string;
+};
+/**
+ * A referrer metrics editions API response.
+ *
+ * Use the `responseCode` field to determine the specific type interpretation
+ * at runtime.
+ */
+type ReferrerMetricsEditionsResponse = ReferrerMetricsEditionsResponseOk | ReferrerMetricsEditionsResponseError;
+/**
+ * A status code for referral program edition config set API responses.
+ */
+declare const ReferralProgramEditionConfigSetResponseCodes: {
+    /**
+     * Represents that the edition config set is available.
+     */
+    readonly Ok: "ok";
+    /**
+     * Represents that the edition config set is not available.
+     */
+    readonly Error: "error";
+};
+/**
+ * The derived string union of possible {@link ReferralProgramEditionConfigSetResponseCodes}.
+ */
+type ReferralProgramEditionConfigSetResponseCode = (typeof ReferralProgramEditionConfigSetResponseCodes)[keyof typeof ReferralProgramEditionConfigSetResponseCodes];
+/**
+ * The data payload containing edition configs.
+ * Editions are sorted in descending order by start timestamp.
+ */
+type ReferralProgramEditionConfigSetData = {
+    editions: ReferralProgramEditionConfig[];
+};
+/**
+ * A successful response containing the configured edition config set.
+ */
+type ReferralProgramEditionConfigSetResponseOk = {
+    responseCode: typeof ReferralProgramEditionConfigSetResponseCodes.Ok;
+    data: ReferralProgramEditionConfigSetData;
+};
+/**
+ * An edition config set response when an error occurs.
+ */
+type ReferralProgramEditionConfigSetResponseError = {
+    responseCode: typeof ReferralProgramEditionConfigSetResponseCodes.Error;
+    error: string;
+    errorMessage: string;
+};
+/**
+ * A referral program edition config set API response.
+ *
+ * Use the `responseCode` field to determine the specific type interpretation
+ * at runtime.
+ */
+type ReferralProgramEditionConfigSetResponse = ReferralProgramEditionConfigSetResponseOk | ReferralProgramEditionConfigSetResponseError;
+
+/**
+ * Serialized representation of {@link ReferralProgramRules}.
+ */
+type SerializedReferralProgramRules = SerializedReferralProgramRulesPieSplit | SerializedReferralProgramRulesRevShareLimit;
+/**
+ * Serialized representation of {@link ReferrerLeaderboardPage}.
+ */
+type SerializedReferrerLeaderboardPage = SerializedReferrerLeaderboardPagePieSplit | SerializedReferrerLeaderboardPageRevShareLimit;
+/**
+ * Serialized representation of {@link ReferrerEditionMetrics}.
+ */
+type SerializedReferrerEditionMetrics = SerializedReferrerEditionMetricsPieSplit | SerializedReferrerEditionMetricsRevShareLimit;
+/**
+ * Serialized representation of {@link ReferrerLeaderboardPageResponseError}.
+ *
+ * Note: All fields are already serializable, so this type is identical to the source type.
+ */
+type SerializedReferrerLeaderboardPageResponseError = ReferrerLeaderboardPageResponseError;
+/**
+ * Serialized representation of {@link ReferrerLeaderboardPageResponseOk}.
+ */
+interface SerializedReferrerLeaderboardPageResponseOk extends Omit<ReferrerLeaderboardPageResponseOk, "data"> {
+    data: SerializedReferrerLeaderboardPage;
+}
+/**
+ * Serialized representation of {@link ReferrerLeaderboardPageResponse}.
+ */
+type SerializedReferrerLeaderboardPageResponse = SerializedReferrerLeaderboardPageResponseOk | SerializedReferrerLeaderboardPageResponseError;
+/**
+ * Serialized representation of {@link ReferralProgramEditionConfig}.
+ */
+interface SerializedReferralProgramEditionConfig extends Omit<ReferralProgramEditionConfig, "rules"> {
+    rules: SerializedReferralProgramRules;
+}
+/**
+ * Serialized representation of referrer metrics data for requested editions.
+ * Uses Partial because TypeScript cannot know at compile time which specific edition
+ * slugs are requested. At runtime, when responseCode is Ok, all requested edition slugs
+ * are guaranteed to be present in this record.
+ */
+type SerializedReferrerMetricsEditionsData = Partial<Record<ReferralProgramEditionSlug, SerializedReferrerEditionMetrics>>;
+/**
+ * Serialized representation of {@link ReferrerMetricsEditionsResponseOk}.
+ */
+interface SerializedReferrerMetricsEditionsResponseOk extends Omit<ReferrerMetricsEditionsResponseOk, "data"> {
+    data: SerializedReferrerMetricsEditionsData;
+}
+/**
+ * Serialized representation of {@link ReferrerMetricsEditionsResponseError}.
+ *
+ * Note: All fields are already serializable, so this type is identical to the source type.
+ */
+type SerializedReferrerMetricsEditionsResponseError = ReferrerMetricsEditionsResponseError;
+/**
+ * Serialized representation of {@link ReferrerMetricsEditionsResponse}.
+ */
+type SerializedReferrerMetricsEditionsResponse = SerializedReferrerMetricsEditionsResponseOk | SerializedReferrerMetricsEditionsResponseError;
+/**
+ * Serialized representation of {@link ReferralProgramEditionConfigSetData}.
+ */
+interface SerializedReferralProgramEditionConfigSetData extends Omit<ReferralProgramEditionConfigSetData, "editions"> {
+    editions: SerializedReferralProgramEditionConfig[];
+}
+/**
+ * Serialized representation of {@link ReferralProgramEditionConfigSetResponseOk}.
+ */
+interface SerializedReferralProgramEditionConfigSetResponseOk extends Omit<ReferralProgramEditionConfigSetResponseOk, "data"> {
+    data: SerializedReferralProgramEditionConfigSetData;
+}
+/**
+ * Serialized representation of {@link ReferralProgramEditionConfigSetResponseError}.
+ *
+ * Note: All fields are already serializable, so this type is identical to the source type.
+ */
+type SerializedReferralProgramEditionConfigSetResponseError = ReferralProgramEditionConfigSetResponseError;
+/**
+ * Serialized representation of {@link ReferralProgramEditionConfigSetResponse}.
+ */
+type SerializedReferralProgramEditionConfigSetResponse = SerializedReferralProgramEditionConfigSetResponseOk | SerializedReferralProgramEditionConfigSetResponseError;
+
+/**
+ * Deserialize a {@link ReferrerLeaderboardPageResponse} object.
+ */
+declare function deserializeReferrerLeaderboardPageResponse(maybeResponse: SerializedReferrerLeaderboardPageResponse, valueLabel?: string): ReferrerLeaderboardPageResponse;
+/**
+ * Deserialize a {@link ReferrerMetricsEditionsResponse} object.
+ */
+declare function deserializeReferrerMetricsEditionsResponse(maybeResponse: SerializedReferrerMetricsEditionsResponse, valueLabel?: string): ReferrerMetricsEditionsResponse;
+/**
+ * Deserializes an array of {@link ReferralProgramEditionConfig} objects.
+ */
+declare function deserializeReferralProgramEditionConfigSetArray(maybeArray: unknown, valueLabel?: string): ReferralProgramEditionConfig[];
+/**
+ * Deserialize a {@link ReferralProgramEditionConfigSetResponse} object.
+ */
+declare function deserializeReferralProgramEditionConfigSetResponse(maybeResponse: SerializedReferralProgramEditionConfigSetResponse, valueLabel?: string): ReferralProgramEditionConfigSetResponse;
+
+/**
+ * Serializes a {@link ReferralProgramRules} object.
+ *
+ * @throws if called with a {@link ReferralProgramRulesUnrecognized} — unrecognized editions are
+ *   client-side forward-compatibility placeholders and must never be serialized.
+ */
+declare function serializeReferralProgramRules(rules: ReferralProgramRules): SerializedReferralProgramRules;
+/**
+ * Serializes a {@link ReferralProgramEditionConfig} object.
+ */
+declare function serializeReferralProgramEditionConfig(editionConfig: ReferralProgramEditionConfig): SerializedReferralProgramEditionConfig;
+/**
+ * Serialize a {@link ReferrerLeaderboardPageResponse} object.
+ */
+declare function serializeReferrerLeaderboardPageResponse(response: ReferrerLeaderboardPageResponse): SerializedReferrerLeaderboardPageResponse;
+/**
+ * Serialize a {@link ReferrerMetricsEditionsResponse} object.
+ */
+declare function serializeReferrerMetricsEditionsResponse(response: ReferrerMetricsEditionsResponse): SerializedReferrerMetricsEditionsResponse;
+/**
+ * Serialize a {@link ReferralProgramEditionConfigSetResponse} object.
+ */
+declare function serializeReferralProgramEditionConfigSetResponse(response: ReferralProgramEditionConfigSetResponse): SerializedReferralProgramEditionConfigSetResponse;
+
+/**
+ * Calculate the score of a referrer based on the total incremental duration
+ * (in seconds) of registrations and renewals for direct subnames of .eth
+ * referred by the referrer within the referral program edition.
+ *
+ * Used exclusively in the pie-split award model pipeline.
+ *
+ * @param totalIncrementalDuration - The total incremental duration (in seconds)
+ * of referrals made by a referrer within the {@link ReferralProgramRulesPieSplit}.
+ */
+declare const calcReferrerScorePieSplit: (totalIncrementalDuration: Duration) => ReferrerScore;
+
+/**
+ * Default ENSNode API endpoint URL
+ */
+declare const DEFAULT_ENSNODE_API_URL: "https://api.alpha.ensnode.io";
+/**
+ * Configuration options for ENS Referrals API client
+ */
+interface ClientOptions {
+    /** The ENSNode API URL */
+    url: URL;
+}
+/**
+ * ENS Referrals API Client
+ *
+ * Provides access to ENS Referrals data and leaderboard information.
+ *
+ * @example
+ * ```typescript
+ * // Create client with default options
+ * const client = new ENSReferralsClient();
+ *
+ * // Get referrer leaderboard for December 2025 edition
+ * const leaderboardPage = await client.getReferrerLeaderboardPage({
+ *   edition: "2025-12",
+ *   page: 1,
+ *   recordsPerPage: 25
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom configuration
+ * const client = new ENSReferralsClient({
+ *   url: new URL("https://my-ensnode-instance.com"),
+ * });
+ * ```
+ */
+declare class ENSReferralsClient {
+    private readonly options;
+    static defaultOptions(): ClientOptions;
+    constructor(options?: Partial<ClientOptions>);
+    getOptions(): Readonly<ClientOptions>;
+    /**
+     * Get Referral Program Edition Config Set
+     *
+     * Fetches and deserializes a referral program edition config set from a remote URL.
+     *
+     * @param url - The URL to fetch the edition config set from
+     * @returns A ReferralProgramEditionConfigSet (Map of edition slugs to edition configurations)
+     *
+     * @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`
+     * and skip editions with `"unrecognized"` as appropriate. At least one edition of any kind must
+     * be present, otherwise deserialization throws.
+     *
+     * @throws if the fetch fails
+     * @throws if the response is not valid JSON
+     * @throws if the data doesn't match the expected schema
+     *
+     * @example
+     * ```typescript
+     * const url = new URL("https://example.com/editions.json");
+     * const editionConfigSet = await ENSReferralsClient.getReferralProgramEditionConfigSet(url);
+     * console.log(`Loaded ${editionConfigSet.size} editions`);
+     * ```
+     */
+    static getReferralProgramEditionConfigSet(url: URL): Promise<ReferralProgramEditionConfigSet>;
+    /**
+     * Fetch Referrer Leaderboard Page
+     *
+     * Retrieves a paginated list of referrer leaderboard metrics for a specific referral program edition.
+     *
+     * @param request - Request parameters including edition and pagination
+     * @param request.edition - The referral program edition slug (e.g., "2025-12", "2026-03", or any other configured edition slug)
+     * @param request.page - The page number to retrieve (1-indexed, default: 1)
+     * @param request.recordsPerPage - Number of records per page (default: 25, max: 100)
+     * @returns {ReferrerLeaderboardPageResponse}
+     *
+     * @remarks If the server returns a leaderboard page whose `awardModel` is not recognized by
+     * this client version, it is preserved as {@link ReferrerLeaderboardPageUnrecognized}. Callers
+     * should check `response.data.awardModel` and handle the `"unrecognized"` case accordingly.
+     *
+     * @throws if the ENSNode request fails
+     * @throws if the ENSNode API returns an error response
+     * @throws if the ENSNode response breaks required invariants
+     *
+     * @example
+     * ```typescript
+     * // Get first page of 2025-12 leaderboard with default page size (25 records)
+     * const editionSlug = "2025-12";
+     * const response = await client.getReferrerLeaderboardPage({ edition: editionSlug });
+     * if (response.responseCode === ReferrerLeaderboardPageResponseCodes.Ok) {
+     *   const { awardModel, pageContext, accurateAsOf } = response.data;
+     *   if (awardModel === ReferralProgramAwardModels.Unrecognized) {
+     *     console.log(`Unrecognized award model: ${response.data.originalAwardModel} — skipping`);
+     *   } else {
+     *     const { aggregatedMetrics, referrers, rules } = response.data;
+     *     console.log(`Edition: ${editionSlug}`);
+     *     console.log(`Subregistry: ${rules.subregistryId}`);
+     *     console.log(`Total Referrers: ${pageContext.totalRecords}`);
+     *     console.log(`Page ${pageContext.page} of ${pageContext.totalPages}`);
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get second page of 2026-03 with 50 records per page
+     * const response = await client.getReferrerLeaderboardPage({
+     *   edition: "2026-03",
+     *   page: 2,
+     *   recordsPerPage: 50
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Handle error response (e.g., unknown edition or data not available)
+     * const response = await client.getReferrerLeaderboardPage({ edition: "2025-12" });
+     *
+     * if (response.responseCode === ReferrerLeaderboardPageResponseCodes.Error) {
+     *   console.error(response.error);
+     *   console.error(response.errorMessage);
+     * }
+     * ```
+     */
+    getReferrerLeaderboardPage(request: ReferrerLeaderboardPageRequest): Promise<ReferrerLeaderboardPageResponse>;
+    /**
+     * Fetch Referrer Metrics for Specific Editions
+     *
+     * Retrieves detailed information about a specific referrer for the requested
+     * referral program editions. Returns a record mapping each requested edition slug
+     * to the referrer's metrics for that edition.
+     *
+     * The response data maps edition slugs to referrer metrics. Each edition's entry is a
+     * {@link ReferrerEditionMetrics} discriminated union. Narrow on `awardModel` first to
+     * exclude unrecognized models, then on `type` to distinguish ranked from unranked:
+     *
+     * - `awardModel: "unrecognized"` ({@link ReferrerEditionMetricsUnrecognized}): the server
+     *   returned an award model this client does not recognize. Only `originalAwardModel` is
+     *   available; no model-specific fields are present.
+     * - `type: "ranked"` ({@link ReferrerEditionMetricsTypeIds.Ranked}): the referrer appears on
+     *   the leaderboard. `referrer` contains rank, qualification status, and award share.
+     * - `type: "unranked"` ({@link ReferrerEditionMetricsTypeIds.Unranked}): the referrer has no
+     *   activity in this edition. `referrer` contains zero-value placeholders.
+     *
+     * **Note:** This endpoint does not allow partial success. When `responseCode === Ok`,
+     * all requested editions are guaranteed to be present in the response data. If any
+     * requested edition cannot be returned, the entire request fails with an error.
+     *
+     * @see {@link https://www.npmjs.com/package/@namehash/ens-referrals|@namehash/ens-referrals} for calculation details
+     *
+     * @param request The referrer address and edition slugs to query
+     * @returns {ReferrerMetricsEditionsResponse} Returns the referrer metrics for requested editions
+     *
+     * @remarks If the server returns metrics for an edition whose `awardModel` is not recognized by
+     * this client version, that edition's entry in `response.data` is preserved as
+     * {@link ReferrerEditionMetricsUnrecognized}. Callers should check each edition's `awardModel`
+     * and handle the `"unrecognized"` case accordingly.
+     *
+     * @throws if the ENSNode request fails
+     * @throws if the response data is malformed
+     *
+     * @example
+     * ```typescript
+     * // Get referrer metrics for specific editions
+     * const response = await client.getReferrerMetricsEditions({
+     *   referrer: "0x1234567890123456789012345678901234567890",
+     *   editions: ["2025-12", "2026-01"]
+     * });
+     * if (response.responseCode === ReferrerMetricsEditionsResponseCodes.Ok) {
+     *   // All requested editions are present in response.data
+     *   for (const [editionSlug, detail] of Object.entries(response.data)) {
+     *     console.log(`Edition: ${editionSlug}`);
+     *     if (detail.awardModel === ReferralProgramAwardModels.Unrecognized) {
+     *       console.log(`Unrecognized award model: ${detail.originalAwardModel} — skipping`);
+     *       continue;
+     *     }
+     *     console.log(`Type: ${detail.type}`);
+     *     if (detail.type === ReferrerEditionMetricsTypeIds.Ranked) {
+     *       console.log(`Rank: ${detail.referrer.rank}`);
+     *       console.log(`Award Share: ${detail.referrer.awardPoolShare * 100}%`);
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Access specific edition data directly (edition is guaranteed to exist when OK)
+     * const response = await client.getReferrerMetricsEditions({
+     *   referrer: "0x1234567890123456789012345678901234567890",
+     *   editions: ["2025-12"]
+     * });
+     * if (response.responseCode === ReferrerMetricsEditionsResponseCodes.Ok) {
+     *   const detail = response.data["2025-12"];
+     *   if (detail && detail.awardModel === ReferralProgramAwardModels.Unrecognized) {
+     *     console.log(`Unrecognized award model: ${detail.originalAwardModel} — skipping`);
+     *   } else if (detail && detail.type === ReferrerEditionMetricsTypeIds.Ranked) {
+     *     console.log(`Edition 2025-12 Rank: ${detail.referrer.rank}`);
+     *   } else if (detail) {
+     *     console.log("Referrer is not on the leaderboard for 2025-12");
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Handle error response (e.g., unknown edition or data not available)
+     * const response = await client.getReferrerMetricsEditions({
+     *   referrer: "0x1234567890123456789012345678901234567890",
+     *   editions: ["2025-12", "invalid-edition"]
+     * });
+     *
+     * if (response.responseCode === ReferrerMetricsEditionsResponseCodes.Error) {
+     *   console.error(response.error);
+     *   console.error(response.errorMessage);
+     * }
+     * ```
+     */
+    getReferrerMetricsEditions(request: ReferrerMetricsEditionsRequest): Promise<ReferrerMetricsEditionsResponse>;
+    /**
+     * Get the currently configured referral program edition config set.
+     * 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.
+     *
+     * @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`
+     * 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();
+     *
+     * if (response.responseCode === ReferralProgramEditionConfigSetResponseCodes.Ok) {
+     *   console.log(`Found ${response.data.editions.length} editions`);
+     *   for (const edition of response.data.editions) {
+     *     console.log(`${edition.slug}: ${edition.displayName}`);
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Handle error response
+     * const response = await client.getEditionConfigSet();
+     *
+     * if (response.responseCode === ReferralProgramEditionConfigSetResponseCodes.Error) {
+     *   console.error(response.error);
+     *   console.error(response.errorMessage);
+     * }
+     * ```
+     */
+    getEditionConfigSet(): Promise<ReferralProgramEditionConfigSetResponse>;
+}
+
+/**
+ * Returns the default referral program edition set with pre-built edition configurations.
+ *
+ * This function maps from an ENS namespace to the appropriate subregistry (BaseRegistrar)
+ * and builds the default referral program editions for that namespace.
+ *
+ * @param ensNamespaceId - The ENS namespace slug to get the default editions for
+ * @returns A map of edition slugs to their pre-built edition configurations
+ * @throws Error if the subregistry contract is not found for the given namespace
+ */
+declare function getDefaultReferralProgramEditionConfigSet(ensNamespaceId: ENSNamespaceId): ReferralProgramEditionConfigSet;
+
+/**
+ * Build a URL to the official ENS manager app
+ * where the given {@link Address} is set as the referrer.
+ */
+declare function buildEnsReferralUrl(address: Address): URL;
+
+declare const isInteger: (value: number) => boolean;
+declare const isNonNegativeInteger: (value: number) => boolean;
+declare const isPositiveInteger: (value: number) => boolean;
+declare const validateNonNegativeInteger: (value: number) => void;
+declare const isFiniteNonNegativeNumber: (value: number) => boolean;
+
+declare const validateUnixTimestamp: (timestamp: UnixTimestamp) => void;
+/**
+ * The number of seconds in a year.
+ *
+ * (60 seconds per minute * 60 minutes per hour *
+ *  24 hours per day * 365.2425 days on average per year).
+ */
+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 };