proper rev-share-limit race implemented

Author: Goader

apps/ensapi/src/lib/ensanalytics/referrer-leaderboard/database-v1.ts

@@ -1,9 +1,10 @@
 import {
   buildReferrerMetrics,
+  type ReferralEvent,
   type ReferralProgramRules,
   type ReferrerMetrics,
 } from "@namehash/ens-referrals/v1";
-import { and, count, desc, eq, gte, isNotNull, lte, ne, sql, sum } from "drizzle-orm";
+import { and, asc, count, desc, eq, gte, isNotNull, lte, ne, sql, sum } from "drizzle-orm";
 import { type Address, zeroAddress } from "viem";
 
 import * as schema from "@ensnode/ensnode-schema";
@@ -93,3 +94,71 @@ export const getReferrerMetrics = async (
     throw new Error(`Failed to fetch referrer metrics from database: ${errorMessage}`);
   }
 };
+
+/**
+ * Get raw referral events from the database for the sequential race algorithm (V1 API).
+ *
+ * Returns individual rows (no GROUP BY) ordered chronologically for deterministic race processing.
+ *
+ * @param rules - The referral program rules for filtering registrar actions
+ * @returns A promise that resolves to an array of {@link ReferralEvent} values.
+ * @throws Error if the database query fails.
+ */
+export const getReferralEvents = async (rules: ReferralProgramRules): Promise<ReferralEvent[]> => {
+  try {
+    const records = await db
+      .select({
+        referrer: schema.registrarActions.decodedReferrer,
+        timestamp: schema.registrarActions.timestamp,
+        blockNumber: schema.registrarActions.blockNumber,
+        transactionHash: schema.registrarActions.transactionHash,
+        incrementalDuration: schema.registrarActions.incrementalDuration,
+        // Note: Using raw SQL for COALESCE because Drizzle doesn't natively support it yet.
+        // See: https://github.com/drizzle-team/drizzle-orm/issues/3708
+        total: sql<string>`COALESCE(${schema.registrarActions.total}, 0)`.as("total"),
+      })
+      .from(schema.registrarActions)
+      .where(
+        and(
+          // Filter by timestamp range
+          gte(schema.registrarActions.timestamp, BigInt(rules.startTime)),
+          lte(schema.registrarActions.timestamp, BigInt(rules.endTime)),
+          // Filter by decodedReferrer not null
+          isNotNull(schema.registrarActions.decodedReferrer),
+          // Filter by decodedReferrer not zero address
+          ne(schema.registrarActions.decodedReferrer, zeroAddress),
+          // Filter by subregistryId matching the provided subregistryId
+          eq(schema.registrarActions.subregistryId, formatAccountId(rules.subregistryId)),
+        ),
+      )
+      .orderBy(
+        asc(schema.registrarActions.timestamp),
+        asc(schema.registrarActions.blockNumber),
+        asc(schema.registrarActions.transactionHash),
+      );
+
+    // Type assertion: The WHERE clause in the query above guarantees non-null values for:
+    // 1. `referrer` is guaranteed to be non-null due to isNotNull filter
+    interface NonNullRecord {
+      referrer: Address;
+      timestamp: bigint;
+      blockNumber: bigint;
+      transactionHash: `0x${string}`;
+      incrementalDuration: bigint;
+      total: string;
+    }
+
+    return (records as NonNullRecord[]).map((record) => ({
+      referrer: record.referrer,
+      timestamp: Number(record.timestamp),
+      blockNumber: record.blockNumber,
+      transactionHash: record.transactionHash,
+      incrementalDuration: Number(record.incrementalDuration),
+      incrementalRevenueContribution: priceEth(BigInt(record.total)),
+    }));
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    logger.error({ error }, "Failed to fetch referral events from database");
+    throw new Error(`Failed to fetch referral events from database: ${errorMessage}`);
+  }
+};

apps/ensapi/src/lib/ensanalytics/referrer-leaderboard/get-referrer-leaderboard-v1.ts

@@ -1,16 +1,22 @@
 import {
-  buildReferrerLeaderboard,
+  buildReferrerLeaderboardPieSplit,
+  buildReferrerLeaderboardRevShareLimit,
+  ReferralProgramAwardModels,
   type ReferralProgramRules,
   type ReferrerLeaderboard,
 } from "@namehash/ens-referrals/v1";
 
 import type { UnixTimestamp } from "@ensnode/ensnode-sdk";
 
-import { getReferrerMetrics } from "./database-v1";
+import { getReferralEvents, getReferrerMetrics } from "./database-v1";
 
 /**
  * Builds a `ReferralLeaderboard` from the database using the provided referral program rules (V1 API).
  *
+ * Dispatches to the appropriate model-specific builder based on `rules.awardModel`:
+ * - PieSplit: uses aggregated referrer metrics (GROUP BY query).
+ * - RevShareLimit: uses raw referral events (no GROUP BY) for the sequential race algorithm.
+ *
  * @param rules - The referral program rules for filtering registrar actions
  * @param accurateAsOf - The {@link UnixTimestamp} of when the data used to build the {@link ReferrerLeaderboard} was accurate as of.
  * @returns A promise that resolves to a {@link ReferrerLeaderboard}
@@ -20,6 +26,14 @@ export async function getReferrerLeaderboard(
   rules: ReferralProgramRules,
   accurateAsOf: UnixTimestamp,
 ): Promise<ReferrerLeaderboard> {
-  const allReferrers = await getReferrerMetrics(rules);
-  return buildReferrerLeaderboard(allReferrers, rules, accurateAsOf);
+  switch (rules.awardModel) {
+    case ReferralProgramAwardModels.PieSplit: {
+      const allReferrers = await getReferrerMetrics(rules);
+      return buildReferrerLeaderboardPieSplit(allReferrers, rules, accurateAsOf);
+    }
+    case ReferralProgramAwardModels.RevShareLimit: {
+      const events = await getReferralEvents(rules);
+      return buildReferrerLeaderboardRevShareLimit(events, rules, accurateAsOf);
+    }
+  }
 }

packages/ens-referrals/src/v1/api/deserialize.ts

@@ -34,10 +34,7 @@ export function deserializeReferrerLeaderboardPageResponse(
     );
   }
 
-  // The Zod schema includes passthrough catch-alls for unknown award model types,
-  // making its inferred output type wider than ReferrerLeaderboardPageResponse.
-  // This assertion is safe: the schema validates all known fields correctly.
-  return parsed.data as unknown as ReferrerLeaderboardPageResponse;
+  return parsed.data;
 }
 
 /**
@@ -56,8 +53,7 @@ export function deserializeReferrerMetricsEditionsResponse(
     );
   }
 
-  // Same passthrough-widened type assertion as above.
-  return parsed.data as unknown as ReferrerMetricsEditionsResponse;
+  return parsed.data;
 }
 
 /**
@@ -76,7 +72,9 @@ export function deserializeReferralProgramEditionConfigSetArray(
     );
   }
 
-  // Same passthrough-widened type assertion as above.
+  // makeReferralProgramRulesSchema uses .passthrough() for forward compatibility with unknown award
+  // model types, widening its output to { awardModel: string } & Record<string, unknown>.
+  // This assertion is safe: the schema validates all known fields correctly.
   return parsed.data as unknown as ReferralProgramEditionConfig[];
 }
 
@@ -96,6 +94,6 @@ export function deserializeReferralProgramEditionConfigSetResponse(
     );
   }
 
-  // Same passthrough-widened type assertion as above.
+  // Same reason as deserializeReferralProgramEditionConfigSetArray above.
   return parsed.data as unknown as ReferralProgramEditionConfigSetResponse;
 }

packages/ens-referrals/src/v1/award-models/rev-share-limit/aggregations.ts

@@ -1,46 +1,38 @@
-import {
-  type Duration,
-  type PriceEth,
-  type PriceUsdc,
-  priceEth,
-  priceUsdc,
-  scalePrice,
-} from "@ensnode/ensnode-sdk";
+import { type Duration, type PriceEth, type PriceUsdc, priceEth } from "@ensnode/ensnode-sdk";
 import { makePriceEthSchema, makePriceUsdcSchema } from "@ensnode/ensnode-sdk/internal";
 
 import { validateNonNegativeInteger } from "../../number";
 import { validateDuration } from "../../time";
-import type { RankedReferrerMetricsRevShareLimit } from "./metrics";
-import type { ReferralProgramRulesRevShareLimit } from "./rules";
+import type { AwardedReferrerMetricsRevShareLimit } from "./metrics";
 
 /**
- * Represents aggregated metrics for a list of {@link RankedReferrerMetricsRevShareLimit}.
+ * Represents aggregated metrics for a list of referrers on a rev-share-limit leaderboard.
  */
 export interface AggregatedReferrerMetricsRevShareLimit {
   /**
-   * @invariant The sum of `totalReferrals` across all {@link RankedReferrerMetricsRevShareLimit} in the list.
+   * @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 {@link RankedReferrerMetricsRevShareLimit} in the list.
+   * @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 {@link RankedReferrerMetricsRevShareLimit} in the list.
+   * 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 the total potential awards
-   * (capped at 0 if total potential awards exceed the pool).
+   * 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)
    */
@@ -75,65 +67,41 @@ export const validateAggregatedReferrerMetricsRevShareLimit = (
 };
 
 /**
- * Builds aggregated rev-share-limit metrics from a complete, globally ranked list of referrers.
+ * 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 ranking of all referrers.**
+ * **IMPORTANT: This function expects a complete list of all referrers.**
  *
- * @param referrers - Must be a complete, globally ranked list of {@link RankedReferrerMetricsRevShareLimit}
- *                    where ranks start at 1 and are consecutive.
- *                    **This must NOT be a paginated or partial slice of the rankings.**
+ * @param referrers - Must be a complete list of referrers with their totals.
+ *                    **This must NOT be a paginated or partial slice.**
  *
- * @param rules - The {@link ReferralProgramRulesRevShareLimit} object that define qualification criteria.
+ * @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.
- *
- * @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.
  */
 export const buildAggregatedReferrerMetricsRevShareLimit = (
-  referrers: RankedReferrerMetricsRevShareLimit[],
-  rules: ReferralProgramRulesRevShareLimit,
-): { aggregatedMetrics: AggregatedReferrerMetricsRevShareLimit; scalingFactor: number } => {
+  referrers: AwardedReferrerMetricsRevShareLimit[],
+  awardPoolRemaining: PriceUsdc,
+): AggregatedReferrerMetricsRevShareLimit => {
   let grandTotalReferrals = 0;
   let grandTotalIncrementalDuration = 0;
   let grandTotalRevenueContributionAmount = 0n;
-  let totalPotentialAwardsAmount = 0n;
 
   for (const referrer of referrers) {
     grandTotalReferrals += referrer.totalReferrals;
     grandTotalIncrementalDuration += referrer.totalIncrementalDuration;
     grandTotalRevenueContributionAmount += referrer.totalRevenueContribution.amount;
-    if (referrer.isQualified) {
-      const potentialAward = scalePrice(
-        referrer.totalBaseRevenueContribution,
-        rules.qualifiedRevenueShare,
-      );
-      totalPotentialAwardsAmount += potentialAward.amount;
-    }
   }
 
-  const scalingFactor =
-    totalPotentialAwardsAmount > 0n
-      ? Math.min(1, Number(rules.totalAwardPoolValue.amount) / Number(totalPotentialAwardsAmount))
-      : 1;
-
-  const cappedTotalPotentialAwards =
-    totalPotentialAwardsAmount < rules.totalAwardPoolValue.amount
-      ? totalPotentialAwardsAmount
-      : rules.totalAwardPoolValue.amount;
-
-  const awardPoolRemainingAmount = rules.totalAwardPoolValue.amount - cappedTotalPotentialAwards;
-
   const aggregatedMetrics = {
     grandTotalReferrals,
     grandTotalIncrementalDuration,
     grandTotalRevenueContribution: priceEth(grandTotalRevenueContributionAmount),
-    awardPoolRemaining: priceUsdc(awardPoolRemainingAmount),
+    awardPoolRemaining,
   } satisfies AggregatedReferrerMetricsRevShareLimit;
 
   validateAggregatedReferrerMetricsRevShareLimit(aggregatedMetrics);
 
-  return { aggregatedMetrics, scalingFactor };
+  return aggregatedMetrics;
 };

packages/ens-referrals/src/v1/award-models/rev-share-limit/api/serialize.ts

@@ -67,6 +67,7 @@ export function serializeAwardedReferrerMetricsRevShareLimit(
     totalBaseRevenueContribution: serializePriceUsdc(metrics.totalBaseRevenueContribution),
     rank: metrics.rank,
     isQualified: metrics.isQualified,
+    standardAwardValue: serializePriceUsdc(metrics.standardAwardValue),
     awardPoolApproxValue: serializePriceUsdc(metrics.awardPoolApproxValue),
   };
 }
@@ -85,6 +86,7 @@ export function serializeUnrankedReferrerMetricsRevShareLimit(
     totalBaseRevenueContribution: serializePriceUsdc(metrics.totalBaseRevenueContribution),
     rank: metrics.rank,
     isQualified: metrics.isQualified,
+    standardAwardValue: serializePriceUsdc(metrics.standardAwardValue),
     awardPoolApproxValue: serializePriceUsdc(metrics.awardPoolApproxValue),
   };
 }

packages/ens-referrals/src/v1/award-models/rev-share-limit/api/serialized-types.ts

@@ -43,10 +43,14 @@ export interface SerializedAggregatedReferrerMetricsRevShareLimit
 export interface SerializedAwardedReferrerMetricsRevShareLimit
   extends Omit<
     AwardedReferrerMetricsRevShareLimit,
-    "totalRevenueContribution" | "totalBaseRevenueContribution" | "awardPoolApproxValue"
+    | "totalRevenueContribution"
+    | "totalBaseRevenueContribution"
+    | "standardAwardValue"
+    | "awardPoolApproxValue"
   > {
   totalRevenueContribution: SerializedPriceEth;
   totalBaseRevenueContribution: SerializedPriceUsdc;
+  standardAwardValue: SerializedPriceUsdc;
   awardPoolApproxValue: SerializedPriceUsdc;
 }
 
@@ -56,10 +60,14 @@ export interface SerializedAwardedReferrerMetricsRevShareLimit
 export interface SerializedUnrankedReferrerMetricsRevShareLimit
   extends Omit<
     UnrankedReferrerMetricsRevShareLimit,
-    "totalRevenueContribution" | "totalBaseRevenueContribution" | "awardPoolApproxValue"
+    | "totalRevenueContribution"
+    | "totalBaseRevenueContribution"
+    | "standardAwardValue"
+    | "awardPoolApproxValue"
   > {
   totalRevenueContribution: SerializedPriceEth;
   totalBaseRevenueContribution: SerializedPriceUsdc;
+  standardAwardValue: SerializedPriceUsdc;
   awardPoolApproxValue: SerializedPriceUsdc;
 }