Merge remote-tracking branch 'origin/main' into feat/indexing-metadata-context

Author: tk-o

.changeset/bright-rivers-flow.md

@@ -0,0 +1,5 @@
+---
+"@namehash/ens-referrals": minor
+---
+
+Add `BaseReferralProgramEditionConfig` as the shared parent of `ReferralProgramEditionConfig` and `BaseReferralProgramEditionSummary`.

.changeset/hip-poems-shave.md

@@ -0,0 +1,6 @@
+---
+"@ensnode/integration-test-env": patch
+"@docs/ensnode": patch
+---
+
+Moved docker-compose.yml file to separate `docker` directory, updates docs and cicd-tests

.changeset/quiet-mirrors-shine.md

@@ -0,0 +1,5 @@
+---
+"@namehash/ens-referrals": minor
+---
+
+Expose the per-award-model (`pie-split`, `rev-share-cap`) Zod schemas via `@namehash/ens-referrals/internal`.

.changeset/shiny-tigers-wander.md

@@ -0,0 +1,5 @@
+---
+"@namehash/ens-referrals": minor
+---
+
+Reject overlapping referral program editions: for a given `subregistryId`, no two editions may share any point in time.

README.md

@@ -89,6 +89,14 @@ ENSNode is a modern, multichain indexer for ENS. It supports backwards-compatibl
 
 Documentation for the ENSNode suite of apps is available at [ensnode.io](https://ensnode.io).
 
+## Running with Docker
+
+```bash
+docker compose -f docker/docker-compose.yml up -d
+```
+
+See [`docker/README.md`](docker/README.md) for all use cases and commands.
+
 ## Contributions
 
 We welcome community contributions and feedback—please see [CONTRIBUTING.md](CONTRIBUTING.md) for more information.

apps/ensapi/src/cache/indexing-status.cache.ts

@@ -25,11 +25,11 @@ export const indexingStatusCache = lazyProxy<SWRCache<CrossChainIndexingStatusSn
             if (
               indexingMetadataContext.statusCode !== IndexingMetadataContextStatusCodes.Initialized
             ) {
-              // An indexing status snapshot has not been found in ENSDb yet.
+              // The Indexing Metadata Context has not been initialized in ENSDb yet.
               // This might happen during application startup, i.e. when ENSDb
               // has not yet been populated with the first snapshot.
               // Therefore, throw an error to trigger the subsequent `.catch` handler.
-              throw new Error("Indexing Status snapshot not found in ENSDb yet.");
+              throw new Error("Indexing Metadata Context was uninitialized in ENSDb.");
             }
 
             // The indexing status snapshot has been fetched and successfully validated for caching.
@@ -39,14 +39,14 @@ export const indexingStatusCache = lazyProxy<SWRCache<CrossChainIndexingStatusSn
             return indexingMetadataContext.indexingStatus;
           })
           .catch((error) => {
-            // Either the indexing status snapshot fetch failed, or the indexing status snapshot was not found in ENSDb yet.
+            // Indexing Metadata Context was uninitialized in ENSDb.
             // Therefore, throw an error so that this current invocation of `readCache` will:
             // - Reject the newly fetched response (if any) such that it won't be cached.
             // - Return the most recently cached value from prior invocations, or `null` if no prior invocation successfully cached a value.
             logger.error(
               error,
-              `Error occurred while loading Indexing Status snapshot record from ENSNode Metadata table in ENSDb. ` +
-                `Where clause applied: ("ensIndexerSchemaName" = "${ensDbClient.ensIndexerSchemaName}", "key" = "${EnsNodeMetadataKeys.EnsIndexerIndexingStatus}"). ` +
+              `Error occurred while loading Indexing Metadata Context record from ENSNode Metadata table in ENSDb. ` +
+                `Where clause applied: ("ensIndexerSchemaName" = "${ensDbClient.ensIndexerSchemaName}", "key" = "${EnsNodeMetadataKeys.IndexingMetadataContext}"). ` +
                 `The cached indexing status snapshot (if any) will not be updated.`,
             );
             throw error;

apps/ensapi/src/handlers/ensanalytics/ensanalytics-api.test.ts

@@ -33,6 +33,7 @@ import {
   type ReferralProgramEditionSlug,
   ReferralProgramEditionStatuses,
   ReferralProgramEditionSummariesResponseCodes,
+  type ReferralProgramRulesPieSplit,
   ReferrerEditionMetricsTypeIds,
   type ReferrerLeaderboard,
   ReferrerLeaderboardPageResponseCodes,
@@ -868,20 +869,33 @@ describe("/v1/ensanalytics", () => {
         },
       );
 
-      // Mock caches middleware with a cache for each edition
+      // Each leaderboard carries its edition's own rules so the per-edition summaries don't
+      // collapse onto a single time window and trip the non-overlap invariant on the response.
+      const leaderboardFor = (config: {
+        rules: ReferralProgramRulesPieSplit;
+      }): ReferrerLeaderboard => ({
+        ...emptyReferralLeaderboard,
+        rules: config.rules,
+      });
       const mockEditionsCaches = new Map<ReferralProgramEditionSlug, SWRCache<ReferrerLeaderboard>>(
         [
           [
             "2025-12",
-            { read: async () => emptyReferralLeaderboard } as SWRCache<ReferrerLeaderboard>,
+            {
+              read: async () => leaderboardFor(mockEditionConfigSet.get("2025-12")!),
+            } as SWRCache<ReferrerLeaderboard>,
           ],
           [
             "2026-03",
-            { read: async () => emptyReferralLeaderboard } as SWRCache<ReferrerLeaderboard>,
+            {
+              read: async () => leaderboardFor(mockEditionConfigSet.get("2026-03")!),
+            } as SWRCache<ReferrerLeaderboard>,
           ],
           [
             "2026-06",
-            { read: async () => emptyReferralLeaderboard } as SWRCache<ReferrerLeaderboard>,
+            {
+              read: async () => leaderboardFor(mockEditionConfigSet.get("2026-06")!),
+            } as SWRCache<ReferrerLeaderboard>,
           ],
         ],
       );

apps/ensindexer/.env.local.example

@@ -243,6 +243,7 @@ ENSRAINBOW_URL=http://localhost:3223
 # https://ensnode.io/ensrainbow/usage/available-label-sets
 #
 # LABEL_SET_ID: see https://ensnode.io/ensrainbow/concepts/glossary#label-set-id.
+# Should match ENSRainbow's LABEL_SET_ID.
 LABEL_SET_ID=subgraph
 
 # LABEL_SET_VERSION: see https://ensnode.io/ensrainbow/concepts/glossary#label-set-version.

apps/ensrainbow/.env.local.example

@@ -16,7 +16,7 @@ LOG_LEVEL=info
 DB_SCHEMA_VERSION=3
 
 # Label set ID (see https://ensnode.io/ensrainbow/concepts/glossary#label-set-id)
-LABEL_SET_ID=ens-test-env
+LABEL_SET_ID=subgraph
 
 # Label set version (see https://ensnode.io/ensrainbow/concepts/glossary#label-set-version)
 LABEL_SET_VERSION=0