Introduce Referral Program Cycles

[lightwalker-eth]

Background

• To accelerate shipping ENS Holiday Awards before Dec 1, 2025 we built a simplified API / data model that assumed only a single referral program cycle.
• Our plan has always been to support many (!!) referral program cycles.

Prerequisites / Change Management Notes

• All ideas in this issue should apply exclusively to the "v1" implementation of referral-related APIs. No changes should be made to the "v0" implementations. See issue 1520 for details.

Goals / Suggested Action Items

• All references to "ENS Holiday Awards" related constants in ens-referrals or ensapi should be removed (with the sole exception of any such constants that are critical to retain for not breaking "v0" implementations).
  • If any such constants are critical to retain for not breaking "v0" implementations, a follow-up issue should be logged to help us remember the need to follow up on removing them later.
• The ENS_HOLIDAY_AWARDS_START and ENS_HOLIDAY_AWARDS_END environment variables should be removed from ensapi. The "config" data model in ENSApi should be updated accordingly.
• An enum-like type (such as the one defined here for ReferralProgramStatuses and ReferralProgramStatusId) should be defined for the concept of a "Referral Program Cycle Id".
  • We should define the following values in this enum: cycle-1 (for ENS Holiday Awards, Dec 2025) and cycle-2 (for March, 2026). We will add more values later.
  • NOTE: these "Referral Program Cycle Id" values will have a number of purposes, including serving as "slug" values that are passed between frontend <> backend in the new "v1" APIs we are going to build for referral data.
• A data model should be defined in ens-referrals for the concept of a "Referral Program Cycle". Each instance of such an object should include fields for:
  • id (a "Referral Program Cycle Id")
  • displayName (a string value, such as "ENS Holiday Awards" for cycle-1 or "March 2026" for cycle-2)
  • rules (a ReferralProgramRules -- I believe you're already familiar with how to define the hardcoded rules for cycle-1. For cycle-2, suggest to make it the same as cycle-1 for now with the exception of updating the display name and setting the start and end dates for March 2026)
  • rulesUrl (a fully qualified URL to where the full human-readable rules for the associated referral program cycle can be found. For example: "https://ensawards.org/ens-holiday-awards-rules".
• A data model should be defined in ens-referrals for the concept of a "Referral Program Cycle Set". Each instance of such an object should be a map from "Referral Program Cycle Id" to a "Referral Program Cycle" with a matching "Referral Program Cycle Id" value.
• ens-referrals should export a utility function called something like getReferralProgramCycleSet that returns the default / hardcoded / official definitions of all "Referral Program Cycles" we are implementing (so far just cycle-1 and cycle-2).
• A new, more scalable strategy should be implemented for loading dynamic rule configurations into ENSApi:
  • Note above how we are removing the ENS_HOLIDAY_AWARDS_START and ENS_HOLIDAY_AWARDS_END environment variables.
  • Suggested strategy (open to other ideas):
    • Update the "config" data model for ENSApi so that it includes a field of type "Referral Program Cycle Set".
    • Introduce a new environment variable to ensapi: CUSTOM_REFERRAL_PROGRAM_CYCLES.
      • Add documentation for it into the env.local.example file for ENSApi.
    • This environment variable should be optional.
    • If not defined, the "Referral Program Cycle Set" in the ENSApi config should be set to the default / hardcoded / official definitions returned by getReferralProgramCycleSet.
    • If defined, it should be a URL to a JSON file containing the JSON serialized representation of a "Referral Program Cycle Set".
      • If defined, but not a valid URL, ENSApi should crash with a helpful error message.
      • If defined, but the URL cannot be successfully fetched on the first attempt for any reason, ENSApi should crash with a helpful error message.
      • If defined, but an attempt to use Zod to deserialize the contents of the provided file from JSON into the serialized representation of a "Referral Program Cycle Set" for any reason, ENSApi should crash with a helpful error message.
      • If all the steps above are successful, then a custom "Referral Program Cycle Set" was successfully loaded into memory by ENSApi. The "Referral Program Cycle Set" in the ENSApi config should be set to this custom value.
    • Note: The strategy above aims to provide us with a high-degree of flexibility in the future for how we can test / preview various new cycles / rules / etc. I believe such flexibility will be valuable for our next steps that has a lot of additional complexity coming.
• Update the "v1" implementation of the referral-related APIs:
  • A new middleware for loading referral leaderboards into memory should be created that supports the ability to build any number of referral leaderboards into memory, one for each "Referral Program Cycle" in the "Referral Program Cycle Set" in the ENSApi config. (note how each referral program cycle should have a distinct leaderboard!)
    • Note: For now, don't worry about the scalability of how this would work with lots of leaderboards to build. We have a good solution for solving this in a separate future issue / PR.
  • Create an updated /referrers route that returns a page from the leaderboard.
    • Suggest we rename this route. Suggest something such as /referral-leaderboard
    • Add another query param such as cycle to this API for a param to identify the specific "Referral Program Cycle Id" being requested.
    • If the server receives a request for a "Referral Program Cycle Id" it does not recognize based on the "Referral Program Cycle Set" preloaded into memory in the ENSApi config, it should return a 404 error.
    • If the server recognizes the "Referral Program Cycle Id", it should return the requested page from the requested leaderboard.
  • Create an updated /referrers/:referrer route.
    • Suggest we rename this route. Suggest something such as /referral-leaderboard:referrer.
    • Suggest we update the data model returned by this route.
      • Currently it returns a ReferrerDetail but this only includes info about a single referral program cycle.
      • Therefore, suggest we update the data model this returns so that it is a Record (JSON) / Map (TypeScript) of all the "Referral Program Cycle Id" from all the "Referral Program Cycle Set" preloaded into memory in the ENSApi config to a "Referrer Detail" object containing the referrer's performance on each of the referral program cycles.
    • Note: The main goal for this updated API is to implement a new tab on an enhanced version of a "Referrer Detail" page on ENSAwards, where the tab would show the status of the referrer across all referral program cycles.