@namehash/ens-referrals 0.0.0-next-20260102143513

package/dist/index.d.ts

@@ -0,0 +1,687 @@
+import { Address, Hex } from 'viem';
+
+declare const validateLowercaseAddress: (address: Address) => void;
+declare const normalizeAddress: (address: Address) => Address;
+
+/**
+ * Represents a quantity of USD.
+ *
+ * @invariant Guaranteed to be a finite non-negative number (>= 0)
+ */
+type USDQuantity = number;
+declare function isValidUSDQuantity(value: USDQuantity): boolean;
+declare function validateUSDQuantity(value: USDQuantity): void;
+
+/**
+ * Unix timestamp value
+ *
+ * Represents the number of seconds that have elapsed
+ * since January 1, 1970 (midnight UTC/GMT). May be zero or negative to represent a time at or
+ * before Jan 1, 1970.
+ *
+ * @invariant Guaranteed to be an integer.
+ */
+type UnixTimestamp = number;
+declare const validateUnixTimestamp: (timestamp: UnixTimestamp) => void;
+/**
+ * Duration
+ *
+ * Represents a duration in seconds.
+ *
+ * Guaranteed to be a non-negative integer.
+ */
+type Duration = number;
+/**
+ * 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;
+
+/**
+ * Start date for the ENS Holiday Awards referral program.
+ * 2025-12-01T00:00:00Z (December 1, 2025 at 00:00:00 UTC)
+ */
+declare const ENS_HOLIDAY_AWARDS_START_DATE: UnixTimestamp;
+/**
+ * End date for the ENS Holiday Awards referral program.
+ * 2025-12-31T23:59:59Z (December 31, 2025 at 23:59:59 UTC)
+ */
+declare const ENS_HOLIDAY_AWARDS_END_DATE: UnixTimestamp;
+/**
+ * The maximum number of qualified referrers for ENS Holiday Awards.
+ */
+declare const ENS_HOLIDAY_AWARDS_MAX_QUALIFIED_REFERRERS = 10;
+/**
+ * The total value of the award pool in USD.
+ */
+declare const ENS_HOLIDAY_AWARDS_TOTAL_AWARD_POOL_VALUE: USDQuantity;
+/**
+ * Chain ID
+ *
+ * Represents a unique identifier for a chain.
+ * Guaranteed to be a positive integer.
+ **/
+type ChainId = number;
+/**
+ * Represents an account (contract or EOA) at `address` on chain `chainId`.
+ *
+ * @see https://chainagnostic.org/CAIPs/caip-10
+ */
+interface AccountId {
+    chainId: ChainId;
+    address: Address;
+}
+interface ReferralProgramRules {
+    /**
+     * The total value of the award pool in USD.
+     *
+     * NOTE: Awards will actually be distributed in $ENS tokens.
+     */
+    totalAwardPoolValue: USDQuantity;
+    /**
+     * 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;
+    /**
+     * 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;
+}
+declare const validateReferralProgramRules: (rules: ReferralProgramRules) => void;
+declare const buildReferralProgramRules: (totalAwardPoolValue: USDQuantity, maxQualifiedReferrers: number, startTime: UnixTimestamp, endTime: UnixTimestamp, subregistryId: AccountId) => ReferralProgramRules;
+
+/**
+ * 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;
+/**
+ * Calculate the score of a referrer based on the total incremental duration
+ * (in seconds) of registrations and renewals for direct subnames of .eth
+ * referrered by the referrer within the ENS Holiday Awards period.
+ *
+ * @param totalIncrementalDuration - The total incremental duration (in seconds)
+ * of referrals made by a referrer within the {@link ReferralProgramRules}.
+ * @returns The score of the referrer.
+ */
+declare const calcReferrerScore: (totalIncrementalDuration: Duration) => ReferrerScore;
+
+/**
+ * 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;
+/**
+ * Determine if a referrer with the given `rank` is qualified to receive a non-zero `awardPoolShare` according to the given `rules`.
+ *
+ * @param rank - The rank of the referrer relative to all other referrers on a {@link ReferrerLeaderboard}.
+ * @param rules - The rules of the referral program that generated the `rank`.
+ */
+declare function isReferrerQualified(rank: ReferrerRank, rules: ReferralProgramRules): boolean;
+/**
+ * Calculate the final score boost of a referrer based on their rank.
+ *
+ * @param rank - The rank of the referrer relative to all other referrers, where 1 is the
+ * top-ranked referrer.
+ * @returns The final score boost of the referrer as a number between 0 and 1 (inclusive).
+ */
+declare function calcReferrerFinalScoreBoost(rank: ReferrerRank, rules: ReferralProgramRules): number;
+/**
+ * Calculate the final score multiplier of a referrer based on their rank.
+ *
+ * @param rank - The rank of the referrer relative to all other referrers, where 1 is the
+ * top-ranked referrer.
+ * @returns The final score multiplier of the referrer as a number between 1 and 2 (inclusive).
+ */
+declare function calcReferrerFinalScoreMultiplier(rank: ReferrerRank, rules: ReferralProgramRules): number;
+/**
+ * Calculate the final score of a referrer based on their score and final score boost.
+ *
+ * @param rank - The rank of the referrer relative to all other referrers.
+ * @param totalIncrementalDuration - The total incremental duration (in seconds)
+ * of referrals made by the referrer within the `rules`.
+ * @param rules - The rules of the referral program that generated the `rank`.
+ * @returns The final score of the referrer.
+ */
+declare function calcReferrerFinalScore(rank: ReferrerRank, totalIncrementalDuration: Duration, rules: ReferralProgramRules): ReferrerScore;
+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;
+
+/**
+ * Revenue Contribution
+ *
+ * Represents the total revenue contribution (in Wei) made to the ENS DAO.
+ *
+ * This is the sum of the total cost paid by registrants for registrar actions.
+ * From the perspective of the ENS DAO, this represents revenue received.
+ *
+ * @invariant Guaranteed to be a non-negative bigint value (>= 0n)
+ * @invariant Never null (records with null `total` in the database are treated as 0 when summing)
+ */
+type RevenueContribution = bigint;
+/**
+ * Check if a value is a valid revenue contribution.
+ *
+ * @param value - The value to check
+ * @returns true if the value is a non-negative bigint, false otherwise
+ */
+declare function isValidRevenueContribution(value: unknown): value is RevenueContribution;
+/**
+ * Validate that a value is a valid revenue contribution.
+ *
+ * @param value - The value to validate
+ * @throws {Error} If the value is not a valid revenue contribution
+ */
+declare function validateRevenueContribution(value: unknown): void;
+
+/**
+ * Represents metrics for a single referrer independent of other referrers.
+ */
+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 Wei) 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 non-negative bigint value (>= 0n)
+     * @invariant Never null (records with null `total` in the database are treated as 0 when summing)
+     */
+    totalRevenueContribution: RevenueContribution;
+}
+declare const buildReferrerMetrics: (referrer: Address, totalReferrals: number, totalIncrementalDuration: Duration, totalRevenueContribution: RevenueContribution) => ReferrerMetrics;
+declare const validateReferrerMetrics: (metrics: ReferrerMetrics) => void;
+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 ScoredReferrerMetrics extends ReferrerMetrics {
+    /**
+     * The referrer's score.
+     *
+     * @invariant Guaranteed to be `calcReferrerScore(totalIncrementalDuration)`
+     */
+    score: ReferrerScore;
+}
+declare const buildScoredReferrerMetrics: (referrer: ReferrerMetrics) => ScoredReferrerMetrics;
+declare const validateScoredReferrerMetrics: (metrics: ScoredReferrerMetrics) => void;
+/**
+ * Extends {@link ScoredReferrerMetrics} to include additional metrics
+ * relative to all other referrers on a {@link ReferrerLeaderboard} and {@link ReferralProgramRules}.
+ */
+interface RankedReferrerMetrics extends ScoredReferrerMetrics {
+    /**
+     * The referrer's rank on the {@link ReferrerLeaderboard} relative to all other referrers.
+     */
+    rank: ReferrerRank;
+    /**
+     * Identifies if the referrer meets the qualifications of the {@link ReferralProgramRules} to receive a non-zero `awardPoolShare`.
+     *
+     * @invariant true if and only if `rank` is less than or equal to {@link ReferralProgramRules.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 ReferralProgramRules.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 validateRankedReferrerMetrics: (metrics: RankedReferrerMetrics, rules: ReferralProgramRules) => void;
+declare const buildRankedReferrerMetrics: (referrer: ScoredReferrerMetrics, rank: ReferrerRank, rules: ReferralProgramRules) => RankedReferrerMetrics;
+/**
+ * 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.
+ * @param rules - The rules of the referral program.
+ * @returns The referrer's share of the award pool as a number between 0 and 1 (inclusive).
+ */
+declare const calcReferrerAwardPoolShare: (referrer: RankedReferrerMetrics, aggregatedMetrics: AggregatedReferrerMetrics, rules: ReferralProgramRules) => number;
+/**
+ * Extends {@link RankedReferrerMetrics} to include additional metrics
+ * relative to {@link AggregatedRankedReferrerMetrics}.
+ */
+interface AwardedReferrerMetrics extends RankedReferrerMetrics {
+    /**
+     * The referrer's share of the award pool.
+     *
+     * @invariant Guaranteed to be a number between 0 and 1 (inclusive)
+     * @invariant Calculated as: `finalScore / {@link AggregatedRankedReferrerMetrics.grandTotalQualifiedReferrersFinalScore}` if `isQualified` is `true`, else `0`
+     */
+    awardPoolShare: number;
+    /**
+     * The approximate {@link USDQuantity} of the referrer's share of the {@link ReferralProgramRules.totalAwardPoolValue}.
+     *
+     * @invariant Guaranteed to be a number between 0 and {@link ReferralProgramRules.totalAwardPoolValue} (inclusive)
+     * @invariant Calculated as: `awardPoolShare` * {@link ReferralProgramRules.totalAwardPoolValue}
+     */
+    awardPoolApproxValue: USDQuantity;
+}
+declare const validateAwardedReferrerMetrics: (referrer: AwardedReferrerMetrics, rules: ReferralProgramRules) => void;
+declare const buildAwardedReferrerMetrics: (referrer: RankedReferrerMetrics, aggregatedMetrics: AggregatedReferrerMetrics, rules: ReferralProgramRules) => AwardedReferrerMetrics;
+/**
+ * Extends {@link AwardedReferrerMetrics} 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 UnrankedReferrerMetrics extends Omit<AwardedReferrerMetrics, "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 validateUnrankedReferrerMetrics: (metrics: UnrankedReferrerMetrics) => 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 UnrankedReferrerMetrics} with zero values for all metrics and null rank
+ */
+declare const buildUnrankedReferrerMetrics: (referrer: Address) => UnrankedReferrerMetrics;
+
+/**
+ * Represents aggregated metrics for a list of `RankedReferrerMetrics`.
+ */
+interface AggregatedReferrerMetrics {
+    /**
+     * @invariant The sum of `totalReferrals` across all `RankedReferrerMetrics` in the list.
+     * @invariant Guaranteed to be a non-negative integer (>= 0)
+     */
+    grandTotalReferrals: number;
+    /**
+     * @invariant The sum of `totalIncrementalDuration` across all `RankedReferrerMetrics` in the list.
+     */
+    grandTotalIncrementalDuration: Duration;
+    /**
+     * The total revenue contribution (in Wei) to the ENS DAO from all referrals
+     * across all referrers on the leaderboard.
+     *
+     * This is the sum of `totalRevenueContribution` across all `RankedReferrerMetrics` in the list.
+     *
+     * @invariant Guaranteed to be a non-negative bigint value (>= 0n)
+     */
+    grandTotalRevenueContribution: RevenueContribution;
+    /**
+     * @invariant The sum of `finalScore` across all `RankedReferrerMetrics` 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 validateAggregatedReferrerMetrics: (metrics: AggregatedReferrerMetrics) => void;
+declare const buildAggregatedReferrerMetrics: (referrers: RankedReferrerMetrics[], rules: ReferralProgramRules) => AggregatedReferrerMetrics;
+
+/**
+ * Encoded Referrer
+ *
+ * Represents a "raw" ENS referrer value.
+ *
+ * Guaranteed to be a hex string representation of a 32-byte value.
+ * For ENS Holiday Awards a correctly encoded referrer is
+ * a left-padded lowercase EVM address.
+ */
+type EncodedReferrer = Hex;
+/**
+ * Encoded Referrer byte offset for ENS Holiday Awards.
+ *
+ * The count of left-padded bytes in an {@link EncodedReferrer} value for ENS Holiday Awards.
+ */
+declare const ENCODED_REFERRER_BYTE_OFFSET = 12;
+/**
+ * Encoded Referrer byte length
+ *
+ * The count of bytes the {@link EncodedReferrer} value consists of.
+ */
+declare const ENCODED_REFERRER_BYTE_LENGTH = 32;
+/**
+ * Encoded Referrer Padding for ENS Holiday Awards
+ *
+ * The initial bytes of correctly encoded referrer value for ENS Holiday Awards.
+ */
+declare const EXPECTED_ENCODED_REFERRER_PADDING: Hex;
+/**
+ * Zero Encoded Referrer
+ *
+ * Guaranteed to be a hex string representation of a 32-byte zero value.
+ */
+declare const ZERO_ENCODED_REFERRER: EncodedReferrer;
+/**
+ * Build an {@link EncodedReferrer} value for the given {@link Address}
+ * according to the subjective referrer encoding used for ENS Holiday Awards.
+ */
+declare function buildEncodedReferrer(address: Address): EncodedReferrer;
+/**
+ * Decode an {@link EncodedReferrer} value into a checksummed {@link Address}
+ * according to the subjective referrer encoding used for ENS Holiday Awards.
+ *
+ * @param encodedReferrer - The "raw" {@link EncodedReferrer} value to decode.
+ * @returns The decoded referrer checksummed address.
+ * @throws when encodedReferrer value is not represented by
+ *         {@link ENCODED_REFERRER_BYTE_LENGTH} bytes.
+ * @throws when decodedReferrer is not a valid EVM address.
+ */
+declare function decodeEncodedReferrer(encodedReferrer: EncodedReferrer): Address;
+
+/**
+ * Represents a leaderboard for any number of referrers.
+ */
+interface ReferrerLeaderboard {
+    /**
+     * The rules of the referral program that generated the {@link ReferrerLeaderboard}.
+     */
+    rules: ReferralProgramRules;
+    /**
+     * The {@link AggregatedReferrerMetrics} for all `RankedReferrerMetrics` values in `leaderboard`.
+     */
+    aggregatedMetrics: AggregatedReferrerMetrics;
+    /**
+     * Ordered map containing `AwardedReferrerMetrics` for all referrers with 1 or more
+     * `totalReferrals` within the `rules` as of `updatedAt`.
+     *
+     * @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 `updatedAt`.
+     * @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 `updatedAt`.
+     * @invariant Each value in this map is guaranteed to have a non-zero
+     *            `totalReferrals`, `totalIncrementalDuration`, and `score`.
+     */
+    referrers: Map<Address, AwardedReferrerMetrics>;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerLeaderboard} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+declare const buildReferrerLeaderboard: (allReferrers: ReferrerMetrics[], rules: ReferralProgramRules, accurateAsOf: UnixTimestamp) => ReferrerLeaderboard;
+
+/**
+ * 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` < `total`)
+     */
+    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;
+/**
+ * A page of referrers from the referrer leaderboard.
+ */
+interface ReferrerLeaderboardPage {
+    /**
+     * The {@link ReferralProgramRules} used to generate the {@link ReferrerLeaderboard}
+     * that this {@link ReferrerLeaderboardPage} comes from.
+     */
+    rules: ReferralProgramRules;
+    /**
+     * Ordered list of {@link AwardedReferrerMetrics} for the {@link ReferrerLeaderboardPage}
+     * described by `pageContext` within the related {@link ReferrerLeaderboard}.
+     *
+     * @invariant Array will be empty if `pageContext.totalRecords` is 0.
+     * @invariant Array entries are ordered by `rank` (descending).
+     */
+    referrers: AwardedReferrerMetrics[];
+    /**
+     * Aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetrics;
+    /**
+     * The {@link ReferrerLeaderboardPageContext} of this {@link ReferrerLeaderboardPage} relative to the overall
+     * {@link ReferrerLeaderboard}.
+     */
+    pageContext: ReferrerLeaderboardPageContext;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerLeaderboardPage} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+declare const getReferrerLeaderboardPage: (pageParams: ReferrerLeaderboardPageParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPage;
+
+/**
+ * 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;
+
+/**
+ * The type of referrer detail data.
+ */
+declare const ReferrerDetailTypeIds: {
+    /**
+     * 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 ReferrerDetailTypeIds}.
+ */
+type ReferrerDetailTypeId = (typeof ReferrerDetailTypeIds)[keyof typeof ReferrerDetailTypeIds];
+/**
+ * Referrer detail data for a specific referrer address on the leaderboard.
+ *
+ * Includes the referrer's awarded metrics from the leaderboard plus timestamp.
+ *
+ * Invariants:
+ * - `type` is always {@link ReferrerDetailTypeIds.Ranked}.
+ *
+ * @see {@link AwardedReferrerMetrics}
+ */
+interface ReferrerDetailRanked {
+    /**
+     * The type of referrer detail data.
+     */
+    type: typeof ReferrerDetailTypeIds.Ranked;
+    /**
+     * The {@link ReferralProgramRules} used to calculate the {@link AwardedReferrerMetrics}.
+     */
+    rules: ReferralProgramRules;
+    /**
+     * The awarded referrer metrics from the leaderboard.
+     *
+     * Contains all calculated metrics including score, rank, qualification status,
+     * and award pool share information.
+     */
+    referrer: AwardedReferrerMetrics;
+    /**
+     * Aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetrics;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerDetailData} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+/**
+ * Referrer detail data for a specific referrer address NOT on the leaderboard.
+ *
+ * Includes the referrer's unranked metrics (with null rank and isQualified: false) plus timestamp.
+ *
+ * Invariants:
+ * - `type` is always {@link ReferrerDetailTypeIds.Unranked}.
+ *
+ * @see {@link UnrankedReferrerMetrics}
+ */
+interface ReferrerDetailUnranked {
+    /**
+     * The type of referrer detail data.
+     */
+    type: typeof ReferrerDetailTypeIds.Unranked;
+    /**
+     * The {@link ReferralProgramRules} used to calculate the {@link UnrankedReferrerMetrics}.
+     */
+    rules: ReferralProgramRules;
+    /**
+     * The unranked referrer metrics (not on the leaderboard).
+     *
+     * Contains all calculated metrics with rank set to null and isQualified set to false.
+     */
+    referrer: UnrankedReferrerMetrics;
+    /**
+     * Aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetrics;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link UnrankedReferrerDetailData} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+/**
+ * Referrer detail data for a specific referrer address.
+ *
+ * Use the `type` field to determine the specific type interpretation
+ * at runtime.
+ */
+type ReferrerDetail = ReferrerDetailRanked | ReferrerDetailUnranked;
+/**
+ * Get the detail for a specific referrer from the leaderboard.
+ *
+ * Returns a {@link ReferrerDetailRanked} if the referrer is on the leaderboard,
+ * or a {@link ReferrerDetailUnranked} if the referrer has no referrals.
+ *
+ * @param referrer - The referrer address to look up
+ * @param leaderboard - The referrer leaderboard to query
+ * @returns The appropriate {@link ReferrerDetail} (ranked or unranked)
+ */
+declare const getReferrerDetail: (referrer: Address, leaderboard: ReferrerLeaderboard) => ReferrerDetail;
+
+export { type AccountId, type AggregatedReferrerMetrics, type AwardedReferrerMetrics, type ChainId, type Duration, ENCODED_REFERRER_BYTE_LENGTH, ENCODED_REFERRER_BYTE_OFFSET, ENS_HOLIDAY_AWARDS_END_DATE, ENS_HOLIDAY_AWARDS_MAX_QUALIFIED_REFERRERS, ENS_HOLIDAY_AWARDS_START_DATE, ENS_HOLIDAY_AWARDS_TOTAL_AWARD_POOL_VALUE, EXPECTED_ENCODED_REFERRER_PADDING, type EncodedReferrer, REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT, REFERRERS_PER_LEADERBOARD_PAGE_MAX, type RankedReferrerMetrics, type ReferralProgramRules, type ReferrerDetail, type ReferrerDetailRanked, type ReferrerDetailTypeId, ReferrerDetailTypeIds, type ReferrerDetailUnranked, type ReferrerLeaderboard, type ReferrerLeaderboardPage, type ReferrerLeaderboardPageContext, type ReferrerLeaderboardPageParams, type ReferrerMetrics, type ReferrerMetricsForComparison, type ReferrerRank, type ReferrerScore, type RevenueContribution, SECONDS_PER_YEAR, type ScoredReferrerMetrics, type USDQuantity, type UnixTimestamp, type UnrankedReferrerMetrics, ZERO_ENCODED_REFERRER, buildAggregatedReferrerMetrics, buildAwardedReferrerMetrics, buildEncodedReferrer, buildEnsReferralUrl, buildRankedReferrerMetrics, buildReferralProgramRules, buildReferrerLeaderboard, buildReferrerLeaderboardPageContext, buildReferrerLeaderboardPageParams, buildReferrerMetrics, buildScoredReferrerMetrics, buildUnrankedReferrerMetrics, calcReferrerAwardPoolShare, calcReferrerFinalScore, calcReferrerFinalScoreBoost, calcReferrerFinalScoreMultiplier, calcReferrerScore, compareReferrerMetrics, decodeEncodedReferrer, getReferrerDetail, getReferrerLeaderboardPage, isFiniteNonNegativeNumber, isInteger, isNonNegativeInteger, isPositiveInteger, isReferrerQualified, isValidDuration, isValidReferrerScore, isValidRevenueContribution, isValidUSDQuantity, normalizeAddress, sortReferrerMetrics, validateAggregatedReferrerMetrics, validateAwardedReferrerMetrics, validateDuration, validateLowercaseAddress, validateNonNegativeInteger, validateRankedReferrerMetrics, validateReferralProgramRules, validateReferrerLeaderboardPageContext, validateReferrerMetrics, validateReferrerRank, validateReferrerScore, validateRevenueContribution, validateScoredReferrerMetrics, validateUSDQuantity, validateUnixTimestamp, validateUnrankedReferrerMetrics };