Create new "Referrals" API

[lightwalker-eth]

Background

• Currently, the following features are powered by our "Registrar Actions" API:
  • The "ENS Referral Live Feed" at https://ensawards.org/ens-referral-program and https://ensawards.org/ens-referral-program/live-feed
  • Each ENS Advocate Detail Page, such as https://ensawards.org/advocate/0x7e491cde0fbf08e51f54c4fb6b9e24afbd18966d
• Currently, these UIs don't provide any detailed accounting of the award calculations for each referral.

Goals

• For the scope of this issue, we want to create an all new "Referrals" API that would replace the use of the "Registrar Actions" API in the contexts listed in the "Background" section above.
• Enable the ENSAwards site to make an update where all existing functionality is retained through the new "Referrals" API and all use of the "Registrar Actions" API within the ENSAwards site can be removed.
  • ENSAwards should be able to stop making use of the EnsApiClient to ask for "Registrar Actions" data.
  • ENSAwards should instead be able to make use of the ‎ENSReferralsClient to ask for "Referrals" data.
• Update the new "Referrals" API so that (compared with the Registrar Actions API) it exposes query params that are more aligned with the other referral-related APIs supported by ‎ENSReferralsClient.
  • A number of additional specializations and updates to the "Referrals" API will be planned and executed in separate future issues (such as to provide a detailed accounting of the award calculations for each referral). However, for the scope of this issue, we are generally working only to make this new "Referrals" API exist.

New API

1. Suggest to make the new "Referrals" API endpoint available through a route such as /v1/ensanalytics/referrals

Query Param Refinements (for new "Referrals" API)

1. withReferral: Remove this as a query param. Instead, within the backend implementation of the new "Referrals" API, we should act as if this param is always set to true. The backend implementation of the new "Referrals" API, we should exclusively return referrals that are associated with one of the configured editions.
2. byDecodedReferrer: Rename this query param to referrer. We should retain the ability to optionally filter by a referrer. This is needed for the "ENS Advocate" detail pages on ENSAwards.
3. beginTimestamp and endTimestamp: Let's completely remove these as query params for now. We aren't using them currently and it will introduce complexity with some of our future steps to keep them.
4. byParentNode: Remove this as a query param. Instead, within the backend implementation of the new "Referrals" API, we should exclusively return referrals that are associated with one of the configured editions.
5. All of the pagination-related query params: Please advise your suggested handling for this. Should we continue implementing this as offset-based pagination, or should we change to implementing this as cursor-based pagination? I assume that for now we would want to continue implementing the same offset-based pagination strategy?
   1. Note the ways we're already using the "Registrar Actions" API on ENSAwards that are referenced above in the "Background Info" section. We need to continue delivering those features.
6. We should continue to only support sorting by latest referrals, newest first.

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

• Provide detailed referral award accounting #1797

🔗 Related PRs

#1554 - ENS Referrals API Versioning [merged]
#1712 - rev-share-limit Referral Program Disqualification [merged]
#1849 - chore(ens-referrals): Update readme [merged]
#1912 - Removing Default Referral Program Rule Set [merged]
#1938 - Using NormalizedAddress in referral program logic [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!