Add data model customizability for specific referral program editions

[lightwalker-eth]

Idea 1

• Introduce a new enum for the idea of a "Referral Program Data Model Type".
• For now, we might introduce just 2 values. Ex: pie-split and rev-share-limit. pie-split could be used for the data model associated with ENS Holiday Awards. rev-share-limit can be the data model associated with the NEW edition we are working to launch.

Idea 2

• Update the data model for ReferralProgramRules to add a field for dataModelType that holds one of the values described above.
• Logic in our zod schemas must accept unrecognized "Referral Program Data Model Type" values. This is important for change management. It must be a responsibility of API clients to gracefully handle unrecognized "Referral Program Data Model Type" values. Servers must be free to introduce new "Referral Program Data Model Type" values without clients breaking.
• The above idea about client responsibilities should be explicitly documented in all the relevant places.
• ReferralProgramRules needs to become a discriminated type union on the dataModelType field. If the value in the field is pie-split then we should retain the existing fields. However, if the value is rev-share-limit then we need to make the following updates:
  • Remove maxQualifiedReferrers.
  • Add a field for minQualifiedRevenueContribution of type PriceUsdc. This field identifies how much "qualified revenue" a referrer must contribute within the edition in order to become qualified for awards. For now you can set this value to $500.
  • Add a field for qualifiedRevenueShare of type number. This value must be in the range of 0 to 1 inclusive and represents the percent of "qualified revenue" associated with a referral would be credited to the referrer if they become a qualified referrer. For now you can set this value to 0.5 (50%).

Idea 3

• Update the data model for AggregatedReferrerMetrics. We need to make it possible to have distinct data models for AggregatedReferrerMetrics depending on the "Referral Program Data Model Type".
• One quick idea for achieving this is to use the discriminated type union strategy here. You can add a field such as dataModelType and then define AggregatedReferrerMetricsPieSplit and AggregatedReferrerMetricsRevShareLimit and then define AggregatedReferrerMetrics as a union of those two types.
• AggregatedReferrerMetricsPieSplit can match our existing data model with the exception of adding the new dataModelType field.
• AggregatedReferrerMetricsRevShareLimit should be updated as follows:
  • Remove grandTotalQualifiedReferrersFinalScore
  • Remove minFinalScoreToQualify
  • Add a field for awardPoolRemaining of type PriceUsdc. This field can have the responsibility for identifying how much of the award pool remains (if any). The reason why "...limit" is in the data model type identifier is because there's a limit to the award pool in this award strategy. Once the pool runs out, it runs out.

Idea 4

• Update the data model for ReferrerMetrics. We need to make it possible to define all the data models in "referrer-metrics.ts" in different ways depending on the "Referral Program Data Model Type".
• If the "Referral Program Data Model Type" is pie-split then we can continue using the existing logic and data model.
• If the "Referral Program Data Model Type" is rev-share-limit then we want to make changes to all the data models and logic in this file including:
  • Add a new field for totalQualifiedRevenueContribution which is distinct from the existing totalRevenueContribution field. Specifically, here we need need to measure "qualified revenue" just purely as a function of incremental duration: We say that each year of incremental duration is worth $5 USDC of "qualified revenue". The goal for this idea is it excludes the revenue from short-name premiums and temporary premiums from being counted. The benefit of excluding that is how it defends against incentivising certain behaviour in the referral program that may not provide sufficient benefits to the ENS DAO.

Idea 5

• We need the ability to use different strategies for how isReferrerQualified works. If the "Referral Program Data Model Type" is pie-split then we can continue using the existing logic. However, if it is rev-share-limit then it needs to be based on if the referrer has made "qualified revenue contributions" >= to minQualifiedRevenueContribution.

[coderabbitai]

🔗 Related PRs

#1562 - Mature Price Models for "v1" ENSAnalytics [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!