@namehash/ens-referrals 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -1,15 +1,46 @@
-import { Hex, Address } from 'viem';
+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).
- *
- * Guaranteed to be an integer. May be zero or negative to represent a time at or
+ * 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)
@@ -20,6 +51,263 @@ declare const ENS_HOLIDAY_AWARDS_START_DATE: UnixTimestamp;
  * 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;
+
+/**
+ * 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;
+}
+declare const buildReferrerMetrics: (referrer: Address, totalReferrals: number, totalIncrementalDuration: Duration) => 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;
+
+/**
+ * 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;
+    /**
+     * @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
@@ -48,13 +336,13 @@ declare const ENCODED_REFERRER_BYTE_LENGTH = 32;
  *
  * The initial bytes of correctly encoded referrer value for ENS Holiday Awards.
  */
-declare const encodedReferrerPadding: `0x${string}`;
+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 zeroEncodedReferrer: `0x${string}`;
+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.
@@ -71,10 +359,152 @@ declare function buildEncodedReferrer(address: Address): EncodedReferrer;
  * @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 ReferrerLeaderboardPaginationParams {
+    /**
+     * 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}
+     */
+    itemsPerPage?: number;
+}
+declare const buildReferrerLeaderboardPaginationParams: (params: ReferrerLeaderboardPaginationParams) => Required<ReferrerLeaderboardPaginationParams>;
+interface ReferrerLeaderboardPaginationContext extends Required<ReferrerLeaderboardPaginationParams> {
+    /**
+     * 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` * `itemsPerPage` < `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 validateReferrerLeaderboardPaginationContext: (context: ReferrerLeaderboardPaginationContext) => void;
+declare const buildReferrerLeaderboardPaginationContext: (optionalParams: ReferrerLeaderboardPaginationParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPaginationContext;
+/**
+ * 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 `paginationContext` within the related {@link ReferrerLeaderboard}.
+     *
+     * @invariant Array will be empty if `paginationContext.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 ReferrerLeaderboardPaginationContext} of this {@link ReferrerLeaderboardPage} relative to the overall
+     * {@link ReferrerLeaderboard}.
+     */
+    paginationContext: ReferrerLeaderboardPaginationContext;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerLeaderboardPage} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+declare const getReferrerLeaderboardPage: (paginationParams: ReferrerLeaderboardPaginationParams, 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;
 
-export { ENCODED_REFERRER_BYTE_LENGTH, ENCODED_REFERRER_BYTE_OFFSET, ENS_HOLIDAY_AWARDS_END_DATE, ENS_HOLIDAY_AWARDS_START_DATE, type EncodedReferrer, type UnixTimestamp, buildEncodedReferrer, buildEnsReferralUrl, decodeEncodedReferrer, encodedReferrerPadding, zeroEncodedReferrer };
+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;
+
+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 ReferrerLeaderboard, type ReferrerLeaderboardPage, type ReferrerLeaderboardPaginationContext, type ReferrerLeaderboardPaginationParams, type ReferrerMetrics, type ReferrerMetricsForComparison, type ReferrerRank, type ReferrerScore, SECONDS_PER_YEAR, type ScoredReferrerMetrics, type USDQuantity, type UnixTimestamp, ZERO_ENCODED_REFERRER, buildAggregatedReferrerMetrics, buildAwardedReferrerMetrics, buildEncodedReferrer, buildEnsReferralUrl, buildRankedReferrerMetrics, buildReferralProgramRules, buildReferrerLeaderboard, buildReferrerLeaderboardPaginationContext, buildReferrerLeaderboardPaginationParams, buildReferrerMetrics, buildScoredReferrerMetrics, calcReferrerAwardPoolShare, calcReferrerFinalScore, calcReferrerFinalScoreBoost, calcReferrerFinalScoreMultiplier, calcReferrerScore, compareReferrerMetrics, decodeEncodedReferrer, getReferrerLeaderboardPage, isFiniteNonNegativeNumber, isInteger, isNonNegativeInteger, isPositiveInteger, isReferrerQualified, isValidDuration, isValidReferrerScore, isValidUSDQuantity, normalizeAddress, sortReferrerMetrics, validateAggregatedReferrerMetrics, validateAwardedReferrerMetrics, validateDuration, validateLowercaseAddress, validateNonNegativeInteger, validateRankedReferrerMetrics, validateReferralProgramRules, validateReferrerLeaderboardPaginationContext, validateReferrerMetrics, validateReferrerRank, validateReferrerScore, validateScoredReferrerMetrics, validateUSDQuantity, validateUnixTimestamp };