Refined rev-share-limit variable names

.changeset/bright-foxes-dance.md

@@ -0,0 +1,5 @@
+---
+"@namehash/ens-referrals": minor
+---
+
+Rename rev-share-limit API fields for clarity: `minQualifiedRevenueContribution` → `minBaseRevenueContribution`, `qualifiedRevenueShare` → `maxBaseRevenueShare`, `standardAwardValue` → `uncappedAwardValue`, `awardPoolApproxValue` → `cappedAwardValue`.

packages/ens-referrals/README.md

@@ -98,11 +98,11 @@ if (response.responseCode === ReferrerLeaderboardPageResponseCodes.Ok) {
 
     if (leaderboardPage.awardModel === ReferralProgramAwardModels.RevShareLimit) {
       console.log(
-        `Min Qualified Revenue Contribution: ${leaderboardPage.rules.minQualifiedRevenueContribution}`,
+        `Min Base Revenue Contribution: ${leaderboardPage.rules.minBaseRevenueContribution}`,
       );
-      console.log(`Qualified Revenue Share: ${leaderboardPage.rules.qualifiedRevenueShare}`);
+      console.log(`Max Base Revenue Share: ${leaderboardPage.rules.maxBaseRevenueShare}`);
       console.log(
-        `Tentative award for the best referrer: ${firstReferrer !== null ? firstReferrer.awardPoolApproxValue : noReferrersFallback}`,
+        `Tentative award for the best referrer: ${firstReferrer !== null ? firstReferrer.cappedAwardValue : noReferrersFallback}`,
       );
     }
   }
@@ -146,7 +146,7 @@ if (response.responseCode === ReferrerMetricsEditionsResponseCodes.Ok) {
       console.log(
         `Referrer's total base revenue contribution: ${detail.referrer.totalBaseRevenueContribution}`,
       );
-      console.log(`Referrer's standard award value: ${detail.referrer.standardAwardValue}`);
+      console.log(`Referrer's uncapped award value: ${detail.referrer.uncappedAwardValue}`);
     }
   }
 }

packages/ens-referrals/src/v1/api/zod-schemas.test.ts

@@ -44,8 +44,8 @@ describe("makeReferralProgramEditionConfigSetArraySchema", () => {
     rules: {
       awardModel: ReferralProgramAwardModels.RevShareLimit,
       totalAwardPoolValue: parseUsdc("500"),
-      minQualifiedRevenueContribution: parseUsdc("10"),
-      qualifiedRevenueShare: 0.5,
+      minBaseRevenueContribution: parseUsdc("10"),
+      maxBaseRevenueShare: 0.5,
       startTime: 1000000,
       endTime: 2000000,
       subregistryId,
@@ -93,13 +93,13 @@ describe("makeReferralProgramEditionConfigSetArraySchema", () => {
     const rules = revShareLimit!.rules as {
       awardModel: typeof ReferralProgramAwardModels.RevShareLimit;
       totalAwardPoolValue: { amount: bigint; currency: string };
-      minQualifiedRevenueContribution: { amount: bigint; currency: string };
-      qualifiedRevenueShare: number;
+      minBaseRevenueContribution: { amount: bigint; currency: string };
+      maxBaseRevenueShare: number;
     };
     expect(rules.totalAwardPoolValue).toBeDefined();
-    expect(rules.minQualifiedRevenueContribution).toBeDefined();
-    expect(typeof rules.qualifiedRevenueShare).toBe("number");
-    expect(rules.qualifiedRevenueShare).toBe(0.5);
+    expect(rules.minBaseRevenueContribution).toBeDefined();
+    expect(typeof rules.maxBaseRevenueShare).toBe("number");
+    expect(rules.maxBaseRevenueShare).toBe(0.5);
     expect(revShareLimit!.rules.areAwardsDistributed).toBe(
       revShareLimitEdition.rules.areAwardsDistributed,
     );
@@ -215,8 +215,8 @@ describe("makeReferrerLeaderboardPageSchema", () => {
     rules: {
       awardModel: ReferralProgramAwardModels.RevShareLimit,
       totalAwardPoolValue: parseUsdc("2000"),
-      minQualifiedRevenueContribution: parseUsdc("10"),
-      qualifiedRevenueShare: 0.5,
+      minBaseRevenueContribution: parseUsdc("10"),
+      maxBaseRevenueShare: 0.5,
       startTime: 1000000,
       endTime: 2000000,
       subregistryId,
@@ -325,8 +325,8 @@ describe("makeReferralProgramEditionSummarySchema", () => {
     rules: {
       awardModel: ReferralProgramAwardModels.RevShareLimit,
       totalAwardPoolValue: parseUsdc("2000"),
-      minQualifiedRevenueContribution: parseUsdc("10"),
-      qualifiedRevenueShare: 0.5,
+      minBaseRevenueContribution: parseUsdc("10"),
+      maxBaseRevenueShare: 0.5,
       startTime: 1000000,
       endTime: 2000000,
       subregistryId,
@@ -507,8 +507,8 @@ describe("makeReferrerEditionMetricsSchema", () => {
       rules: {
         awardModel: ReferralProgramAwardModels.RevShareLimit,
         totalAwardPoolValue: parseUsdc("2000"),
-        minQualifiedRevenueContribution: parseUsdc("10"),
-        qualifiedRevenueShare: 0.5,
+        minBaseRevenueContribution: parseUsdc("10"),
+        maxBaseRevenueShare: 0.5,
         startTime: 1000000,
         endTime: 2000000,
         subregistryId,
@@ -523,8 +523,8 @@ describe("makeReferrerEditionMetricsSchema", () => {
         totalBaseRevenueContribution: parseUsdc("150"),
         rank: 1,
         isQualified: true,
-        standardAwardValue: parseUsdc("200"),
-        awardPoolApproxValue: parseUsdc("200"),
+        uncappedAwardValue: parseUsdc("200"),
+        cappedAwardValue: parseUsdc("200"),
         isAdminDisqualified: false,
         adminDisqualificationReason: null,
       },

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

@@ -35,8 +35,8 @@ export function serializeReferralProgramRulesRevShareLimit(
   return {
     awardModel: rules.awardModel,
     totalAwardPoolValue: serializePriceUsdc(rules.totalAwardPoolValue),
-    minQualifiedRevenueContribution: serializePriceUsdc(rules.minQualifiedRevenueContribution),
-    qualifiedRevenueShare: rules.qualifiedRevenueShare,
+    minBaseRevenueContribution: serializePriceUsdc(rules.minBaseRevenueContribution),
+    maxBaseRevenueShare: rules.maxBaseRevenueShare,
     startTime: rules.startTime,
     endTime: rules.endTime,
     subregistryId: rules.subregistryId,
@@ -74,8 +74,8 @@ export function serializeAwardedReferrerMetricsRevShareLimit(
     totalBaseRevenueContribution: serializePriceUsdc(metrics.totalBaseRevenueContribution),
     rank: metrics.rank,
     isQualified: metrics.isQualified,
-    standardAwardValue: serializePriceUsdc(metrics.standardAwardValue),
-    awardPoolApproxValue: serializePriceUsdc(metrics.awardPoolApproxValue),
+    uncappedAwardValue: serializePriceUsdc(metrics.uncappedAwardValue),
+    cappedAwardValue: serializePriceUsdc(metrics.cappedAwardValue),
     isAdminDisqualified: metrics.isAdminDisqualified,
     adminDisqualificationReason: metrics.adminDisqualificationReason,
   };
@@ -95,8 +95,8 @@ export function serializeUnrankedReferrerMetricsRevShareLimit(
     totalBaseRevenueContribution: serializePriceUsdc(metrics.totalBaseRevenueContribution),
     rank: metrics.rank,
     isQualified: metrics.isQualified,
-    standardAwardValue: serializePriceUsdc(metrics.standardAwardValue),
-    awardPoolApproxValue: serializePriceUsdc(metrics.awardPoolApproxValue),
+    uncappedAwardValue: serializePriceUsdc(metrics.uncappedAwardValue),
+    cappedAwardValue: serializePriceUsdc(metrics.cappedAwardValue),
     isAdminDisqualified: metrics.isAdminDisqualified,
     adminDisqualificationReason: metrics.adminDisqualificationReason,
   };

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

@@ -20,10 +20,10 @@ import type { ReferralProgramRulesRevShareLimit } from "../rules";
 export interface SerializedReferralProgramRulesRevShareLimit
   extends Omit<
     ReferralProgramRulesRevShareLimit,
-    "totalAwardPoolValue" | "minQualifiedRevenueContribution" | "rulesUrl"
+    "totalAwardPoolValue" | "minBaseRevenueContribution" | "rulesUrl"
   > {
   totalAwardPoolValue: SerializedPriceUsdc;
-  minQualifiedRevenueContribution: SerializedPriceUsdc;
+  minBaseRevenueContribution: SerializedPriceUsdc;
   rulesUrl: string;
 }
 
@@ -47,13 +47,13 @@ export interface SerializedAwardedReferrerMetricsRevShareLimit
     AwardedReferrerMetricsRevShareLimit,
     | "totalRevenueContribution"
     | "totalBaseRevenueContribution"
-    | "standardAwardValue"
-    | "awardPoolApproxValue"
+    | "uncappedAwardValue"
+    | "cappedAwardValue"
   > {
   totalRevenueContribution: SerializedPriceEth;
   totalBaseRevenueContribution: SerializedPriceUsdc;
-  standardAwardValue: SerializedPriceUsdc;
-  awardPoolApproxValue: SerializedPriceUsdc;
+  uncappedAwardValue: SerializedPriceUsdc;
+  cappedAwardValue: SerializedPriceUsdc;
 }
 
 /**
@@ -64,13 +64,13 @@ export interface SerializedUnrankedReferrerMetricsRevShareLimit
     UnrankedReferrerMetricsRevShareLimit,
     | "totalRevenueContribution"
     | "totalBaseRevenueContribution"
-    | "standardAwardValue"
-    | "awardPoolApproxValue"
+    | "uncappedAwardValue"
+    | "cappedAwardValue"
   > {
   totalRevenueContribution: SerializedPriceEth;
   totalBaseRevenueContribution: SerializedPriceUsdc;
-  standardAwardValue: SerializedPriceUsdc;
-  awardPoolApproxValue: SerializedPriceUsdc;
+  uncappedAwardValue: SerializedPriceUsdc;
+  cappedAwardValue: SerializedPriceUsdc;
 }
 
 /**

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

@@ -41,12 +41,11 @@ export const makeReferralProgramRulesRevShareLimitSchema = (
   makeBaseReferralProgramRulesSchema(valueLabel).safeExtend({
     awardModel: z.literal(ReferralProgramAwardModels.RevShareLimit),
     totalAwardPoolValue: makePriceUsdcSchema(`${valueLabel}.totalAwardPoolValue`),
-    minQualifiedRevenueContribution: makePriceUsdcSchema(
-      `${valueLabel}.minQualifiedRevenueContribution`,
+    minBaseRevenueContribution: makePriceUsdcSchema(`${valueLabel}.minBaseRevenueContribution`),
+    maxBaseRevenueShare: makeFiniteNonNegativeNumberSchema(`${valueLabel}.maxBaseRevenueShare`).max(
+      1,
+      `${valueLabel}.maxBaseRevenueShare must be <= 1`,
     ),
-    qualifiedRevenueShare: makeFiniteNonNegativeNumberSchema(
-      `${valueLabel}.qualifiedRevenueShare`,
-    ).max(1, `${valueLabel}.qualifiedRevenueShare must be <= 1`),
     disqualifications: z
       .array(
         makeReferralProgramEditionDisqualificationSchema(`${valueLabel}.disqualifications[item]`),
@@ -80,31 +79,35 @@ export const makeAwardedReferrerMetricsRevShareLimitSchema = (
       ),
       rank: makePositiveIntegerSchema(`${valueLabel}.rank`),
       isQualified: z.boolean(),
-      standardAwardValue: makePriceUsdcSchema(`${valueLabel}.standardAwardValue`),
-      awardPoolApproxValue: makePriceUsdcSchema(`${valueLabel}.awardPoolApproxValue`),
+      uncappedAwardValue: makePriceUsdcSchema(`${valueLabel}.uncappedAwardValue`),
+      cappedAwardValue: makePriceUsdcSchema(`${valueLabel}.cappedAwardValue`),
       isAdminDisqualified: z.boolean(),
       adminDisqualificationReason: z
         .string()
         .trim()
         .min(1, `${valueLabel}.adminDisqualificationReason must not be empty`)
         .nullable(),
     })
-    .refine((data) => data.awardPoolApproxValue.amount <= data.standardAwardValue.amount, {
-      message: `${valueLabel}.awardPoolApproxValue must be <= ${valueLabel}.standardAwardValue`,
-      path: ["awardPoolApproxValue"],
+    .refine((data) => data.cappedAwardValue.amount <= data.uncappedAwardValue.amount, {
+      message: `${valueLabel}.cappedAwardValue must be <= ${valueLabel}.uncappedAwardValue`,
+      path: ["cappedAwardValue"],
     })
     .refine(
       (data) =>
         !data.isAdminDisqualified ||
-        (data.isQualified === false && data.awardPoolApproxValue.amount === 0n),
+        (data.isQualified === false && data.cappedAwardValue.amount === 0n),
       {
-        message: `When ${valueLabel}.isAdminDisqualified is true, isQualified must be false and awardPoolApproxValue.amount must be 0`,
+        message: `When ${valueLabel}.isAdminDisqualified is true, isQualified must be false and cappedAwardValue.amount must be 0`,
         path: ["isAdminDisqualified"],
       },
     )
     .refine((data) => data.isAdminDisqualified === (data.adminDisqualificationReason !== null), {
       message: `${valueLabel}.adminDisqualificationReason must be non-null iff isAdminDisqualified is true`,
       path: ["adminDisqualificationReason"],
+    })
+    .refine((data) => data.isQualified || data.cappedAwardValue.amount === 0n, {
+      message: `${valueLabel}.cappedAwardValue must be 0 when isQualified is false`,
+      path: ["cappedAwardValue"],
     });
 
 /**
@@ -124,18 +127,22 @@ export const makeUnrankedReferrerMetricsRevShareLimitSchema = (
       ),
       rank: z.null(),
       isQualified: z.literal(false),
-      standardAwardValue: makePriceUsdcSchema(`${valueLabel}.standardAwardValue`),
-      awardPoolApproxValue: makePriceUsdcSchema(`${valueLabel}.awardPoolApproxValue`),
+      uncappedAwardValue: makePriceUsdcSchema(`${valueLabel}.uncappedAwardValue`),
+      cappedAwardValue: makePriceUsdcSchema(`${valueLabel}.cappedAwardValue`),
       isAdminDisqualified: z.boolean(),
       adminDisqualificationReason: z
         .string()
         .trim()
         .min(1, `${valueLabel}.adminDisqualificationReason must not be empty`)
         .nullable(),
     })
-    .refine((data) => data.awardPoolApproxValue.amount <= data.standardAwardValue.amount, {
-      message: `${valueLabel}.awardPoolApproxValue must be <= ${valueLabel}.standardAwardValue`,
-      path: ["awardPoolApproxValue"],
+    .refine((data) => data.uncappedAwardValue.amount === 0n, {
+      message: `${valueLabel}.uncappedAwardValue must be 0 for unranked referrers`,
+      path: ["uncappedAwardValue"],
+    })
+    .refine((data) => data.cappedAwardValue.amount === 0n, {
+      message: `${valueLabel}.cappedAwardValue must be 0 for unranked referrers`,
+      path: ["cappedAwardValue"],
     })
     .refine((data) => data.isAdminDisqualified === (data.adminDisqualificationReason !== null), {
       message: `${valueLabel}.adminDisqualificationReason must be non-null iff isAdminDisqualified is true`,