Add retention adapter type backed by a stateful indexing service

adapters/types.ts

@@ -217,10 +217,27 @@ export enum AdapterType {
   NFT_VOLUME = 'nft-volume',
   ACTIVE_USERS = 'active-users',
   NEW_USERS = 'new-users',
+  RETENTION = 'retention',
   LIQUIDATIONS = 'liquidations',
 }
 
-export type FetchResult = FetchResultVolume & FetchResultFees & FetchResultAggregators & FetchResultOptions & FetchResultIncentives & FetchResultActiveUsers & FetchResultNewUsers & FetchResultLiquidations
+// Rolling weekly cohort retention. Each day ends a complete 7-day return window;
+// W4 / W12 compare it with the same 7-day window shifted 4 / 12 weeks earlier.
+// Rates are not stored — FE / backend compute them from the counts:
+//   wallet retention = ReturnedWallets / CohortWallets
+//   volume retention = ReturnedVolume  / CohortVolume   (can exceed 100%)
+export type FetchResultRetention = FetchResultBase & {
+  dailyRetentionW4CohortWallets?: FetchResponseValue
+  dailyRetentionW4ReturnedWallets?: FetchResponseValue
+  dailyRetentionW4CohortVolume?: FetchResponseValue
+  dailyRetentionW4ReturnedVolume?: FetchResponseValue
+  dailyRetentionW12CohortWallets?: FetchResponseValue
+  dailyRetentionW12ReturnedWallets?: FetchResponseValue
+  dailyRetentionW12CohortVolume?: FetchResponseValue
+  dailyRetentionW12ReturnedVolume?: FetchResponseValue
+};
+
+export type FetchResult = FetchResultVolume & FetchResultFees & FetchResultAggregators & FetchResultOptions & FetchResultIncentives & FetchResultActiveUsers & FetchResultNewUsers & FetchResultLiquidations & FetchResultRetention
 
 export const whitelistedDimensionKeys = new Set([
   'startTimestamp', 'chain', 'timestamp', 'block',
@@ -230,6 +247,8 @@ export const whitelistedDimensionKeys = new Set([
   'tokenIncentives',
   'dailyOtherIncome', 'dailyOperatingIncome', 'dailyNetIncome',, 'dailyPremiumVolume', 'dailyNotionalVolume',
   'dailyActiveUsers', 'dailyNewUsers', 'dailyTransactionsCount', 'dailyGasUsed',
+  'dailyRetentionW4CohortWallets', 'dailyRetentionW4ReturnedWallets', 'dailyRetentionW4CohortVolume', 'dailyRetentionW4ReturnedVolume',
+  'dailyRetentionW12CohortWallets', 'dailyRetentionW12ReturnedWallets', 'dailyRetentionW12CohortVolume', 'dailyRetentionW12ReturnedVolume',
   'dailyCollateralLiquidated', 'dailyLiquidationVolume',
 ])
 export const accumulativeKeySet = new Set([
@@ -243,4 +262,4 @@ export interface IJSON<T> {
   [key: string]: T
 }
 
-export const ADAPTER_TYPES = Object.values(AdapterType).filter((adapterType: any) => adapterType !== AdapterType.PROTOCOLS)
+export const ADAPTER_TYPES = Object.values(AdapterType).filter((adapterType: any) => adapterType !== AdapterType.PROTOCOLS)

cli/interactive.js

@@ -13,6 +13,7 @@ const ADAPTER_TYPES = [
   'fees', 'dexs', 'incentives', 'aggregators', 'options', 'open-interest',
   'aggregator-derivatives', 'bridge-aggregators', 'normalized-volume',
   'nft-volume', 'active-users', 'new-users', 'liquidations',
+  'retention',
 ]
 const ADAPTER_TYPE_SET = new Set(ADAPTER_TYPES)
 const EXCLUDE_NAMES = new Set(['index', 'README', 'GUIDELINES', '.gitkeep'])

helpers/retention.ts

@@ -0,0 +1,226 @@
+import type { FetchOptions, FetchResultRetention, SimpleAdapter } from "../adapters/types";
+
+const DAY = 86400;
+const FIRST_HORIZON_WEEKS = 4;
+
+export interface RetentionDuneSqlSource {
+  id: string;
+  type: "duneSql";
+  /** Raw read-only SQL. The backend replaces the two required day tokens. */
+  sql: string;
+  output: {
+    day: string;
+    wallet: string;
+    volumeUsd: string;
+  };
+}
+
+export interface RetentionEvmStaticTargets {
+  type: "static";
+  addresses: string[];
+}
+
+export interface RetentionAccessControlRoleMember {
+  role: string;
+  member: string;
+}
+
+export interface RetentionAccessControlRoleChange
+  extends RetentionAccessControlRoleMember {
+  blockNumber: number;
+  logIndex: number;
+  isGrant: boolean;
+}
+
+export interface RetentionAccessControlHistory {
+  /** Day whose start corresponds to activeAtStart. */
+  startDay: string;
+  /** First day whose registry events must be queried live by the backend. */
+  liveFromDay: string;
+  activeAtStart: RetentionAccessControlRoleMember[];
+  changesBeforeLive: RetentionAccessControlRoleChange[];
+}
+
+export interface RetentionEvmAccessControlTargets {
+  type: "accessControlRegistry";
+  address: string;
+  roles: string[];
+  grantedTopic0: string;
+  revokedTopic0: string;
+  history: RetentionAccessControlHistory;
+}
+
+export type RetentionEvmTargets =
+  | RetentionEvmStaticTargets
+  | RetentionEvmAccessControlTargets;
+
+export interface RetentionEvmEventField {
+  type: "address" | "bytes32" | "uint256";
+  topic?: number;
+  dataWord?: number;
+}
+
+export interface RetentionEvmEventSource {
+  id: string;
+  type: "evmEvents";
+  targets: RetentionEvmTargets;
+  event: {
+    /** Human-readable ABI for reviewers; topic0 is the RPC filter. */
+    abi: string;
+    topic0: string;
+    fields: Record<string, RetentionEvmEventField>;
+  };
+  where?: Array<{ field: string; equals: string }>;
+  output: {
+    wallet: string;
+    volumeUsd: { field: string; decimals: number };
+  };
+}
+
+export type RetentionSource = RetentionDuneSqlSource | RetentionEvmEventSource;
+
+export interface RetentionManifest {
+  project: string;
+  chain: string;
+  stateVersion: number;
+  observationStart: string;
+  firstCohortStart: string;
+  /** Delay after a UTC day ends before its source data is safe to index. */
+  dataAvailabilityLagHours: number;
+  maxQueryDays?: number;
+  methodology: string;
+  sources: RetentionSource[];
+}
+
+/**
+ * Validates manifest dates, numeric bounds, and source IDs.
+ * @returns The validated manifest unchanged.
+ */
+export function defineRetentionManifest(
+  manifest: RetentionManifest,
+): RetentionManifest {
+  validateDate(manifest.project, "observationStart", manifest.observationStart);
+  validateDate(manifest.project, "firstCohortStart", manifest.firstCohortStart);
+  if (manifest.firstCohortStart < manifest.observationStart) {
+    throw new Error(`${manifest.project}: firstCohortStart precedes observationStart`);
+  }
+  if (
+    !Number.isFinite(manifest.dataAvailabilityLagHours) ||
+    manifest.dataAvailabilityLagHours < 0
+  ) {
+    throw new Error(
+      `${manifest.project}: dataAvailabilityLagHours must be a non-negative number`,
+    );
+  }
+  if (!Number.isInteger(manifest.stateVersion) || manifest.stateVersion < 1) {
+    throw new Error(`${manifest.project}: stateVersion must be a positive integer`);
+  }
+  if (
+    manifest.maxQueryDays !== undefined &&
+    (!Number.isInteger(manifest.maxQueryDays) || manifest.maxQueryDays < 1)
+  ) {
+    throw new Error(`${manifest.project}: maxQueryDays must be a positive integer`);
+  }
+  if (!Array.isArray(manifest.sources) || manifest.sources.length === 0) {
+    throw new Error(`${manifest.project}: sources must be a non-empty array`);
+  }
+  const sourceIds = new Set<string>();
+  for (const source of manifest.sources) {
+    if (!source.id || sourceIds.has(source.id)) {
+      throw new Error(`${manifest.project}: source ids must be non-empty and unique`);
+    }
+    sourceIds.add(source.id);
+  }
+  return manifest;
+}
+
+/** Creates the normal DefiLlama adapter. Its fetch is a read-only state-service call. */
+export function createRetentionFetchAdapter(
+  manifest: RetentionManifest,
+): SimpleAdapter {
+  const start = addDays(
+    manifest.firstCohortStart,
+    FIRST_HORIZON_WEEKS * 7 + 6,
+  );
+
+  return {
+    version: 1,
+    chains: [manifest.chain],
+    start,
+    methodology: manifest.methodology,
+    fetch: (options: FetchOptions) => fetchRetentionMetrics(manifest, options),
+  };
+}
+
+async function fetchRetentionMetrics(
+  manifest: RetentionManifest,
+  options: FetchOptions,
+): Promise<FetchResultRetention> {
+  const baseUrl = process.env.RETENTION_API_URL?.replace(/\/$/, "");
+  if (!baseUrl) {
+    throw new Error("RETENTION_API_URL is required to fetch retention metrics");
+  }
+
+  const url = new URL(
+    `${baseUrl}/v1/retention/${encodeURIComponent(manifest.project)}/${options.dateString}`,
+  );
+  url.searchParams.set("stateVersion", String(manifest.stateVersion));
+  const response = await fetch(url);
+  const body = await response.text();
+  if (!response.ok) {
+    throw new Error(
+      `${manifest.project}: retention backend returned ${response.status}: ${body.slice(0, 300)}`,
+    );
+  }
+
+  const result = JSON.parse(body) as FetchResultRetention;
+  validateMetrics(manifest.project, result);
+  return result;
+}
+
+function validateMetrics(project: string, result: FetchResultRetention): void {
+  if (!result || typeof result !== "object") {
+    throw new Error(`${project}: retention backend returned a non-object result`);
+  }
+  const w4Keys = [
+    "dailyRetentionW4CohortWallets",
+    "dailyRetentionW4ReturnedWallets",
+    "dailyRetentionW4CohortVolume",
+    "dailyRetentionW4ReturnedVolume",
+  ] as const;
+  const w12Keys = [
+    "dailyRetentionW12CohortWallets",
+    "dailyRetentionW12ReturnedWallets",
+    "dailyRetentionW12CohortVolume",
+    "dailyRetentionW12ReturnedVolume",
+  ] as const;
+  for (const key of w4Keys) {
+    const value = result[key];
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+      throw new Error(`${project}: retention backend returned invalid ${key}`);
+    }
+  }
+  const presentW12Keys = w12Keys.filter((key) => result[key] !== undefined);
+  if (presentW12Keys.length !== 0 && presentW12Keys.length !== w12Keys.length) {
+    throw new Error(`${project}: retention backend returned a partial W12 result`);
+  }
+  for (const key of presentW12Keys) {
+    const value = result[key];
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+      throw new Error(`${project}: retention backend returned invalid ${key}`);
+    }
+  }
+}
+
+function validateDate(project: string, field: string, value: string): void {
+  const parsed = Date.parse(`${value}T00:00:00Z`);
+  if (!Number.isFinite(parsed) || new Date(parsed).toISOString().slice(0, 10) !== value) {
+    throw new Error(`${project}: invalid ${field} ${value}`);
+  }
+}
+
+function addDays(value: string, days: number): string {
+  return new Date(Date.parse(`${value}T00:00:00Z`) + days * DAY * 1000)
+    .toISOString()
+    .slice(0, 10);
+}

retention/collector-crypt/index.ts

@@ -0,0 +1,101 @@
+import { CHAIN } from "../../helpers/chains";
+import {
+  createRetentionFetchAdapter,
+  defineRetentionManifest,
+} from "../../helpers/retention";
+
+// Wallet and volume retention (W4/W12) for Collector Crypt on Solana.
+//
+// A pack purchase is a USDC transfer into one of the on-chain gacha sinks. Each
+// query scans only the requested date range of tokens_solana.transfers.
+// Both sinks are observed: the current one went live on 2025-12-07, while its
+// predecessor carries the history before that. Without it every buyer who
+// migrated across would look like a brand new wallet.
+// - Sink labels and transfers: https://solscan.io/account/GachaNgyXTU3zFogQ8Z5jR2BLXs8215X2AtEH18VxJq3
+// - First transaction on the current sink (2025-12-07): https://solscan.io/tx/2iSpTcqEc85tjD6VJ4i9Q9NCvEdf8pZ3axSw287FSmpgVahpErv5911ntuALUGxvzYCBTNZ28vhHrXBsJeatXjq6
+// - Solana USDC mint: https://solscan.io/token/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
+//
+// The fiat/credit-card rail (96DULv…, part of TEAM_ADDRESSES) is deliberately not
+// a sink: those top-ups settle off-chain in bundles and carry no per-buyer
+// identity, so card purchases are out of scope - a narrower perimeter than
+// fees/collector-crypt.
+const USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+
+// Kept local so loading this manifest does not execute the existing Allium fee adapter.
+const GACHA_ONCHAIN_ADDRESSES = [
+  "GachazZscHZ5bn3vnq1yEC4zpYdhAYJBzuKJwSJksc9z", // decommissioned pre-Dec-2025, kept for history
+  "GachaNgyXTU3zFogQ8Z5jR2BLXs8215X2AtEH18VxJq3", // primary on-chain sink
+];
+
+// Protocol-controlled wallets excluded from buyer cohorts. This is the same
+// public exclusion set used by fees/collector-crypt.
+const TEAM_ADDRESSES = [
+  "BAxTk97HsaJqbnbFmTiQTaL4KSRvJ8Y65ArZCsP6vA5M",
+  "21KhtC7y2JGYvwc8dcGqTdbrudbM8fgMPJsVwxRQqdY8",
+  "DFEstpYN3fsz93AC9v2ujzPPngPgodqH2xxopuyfSsAE",
+  "HW2HRqN1pXQGH9GfP9xet4XwqtLqFyYGDNRKjUAVgh9u",
+  "HighJBfnAaqH9cKkeMErQFJZ4ATxQJwxqFupX6zaKTns",
+  "LGNDXqcm6U57QQ6Ad7icZ6oizkAVKRWrw97KwZy5nVf",
+  "EpicWWZspT1trKndbDDr29ULViN56rN5vofWSKZp8ePF",
+  "Mid9NeCpPNxP59fAdsLgMLy7BYexxXFw52ZP58Jrney",
+  "Lowq9dkpY43VpjfYeRjtKfGA6JtB7HaMmwQgXkjHLvN",
+  "Low6UekJP3QrFVMfNRTL8CPK2SiGFhvp57sgF2pkmVu",
+  "miDtj3vgdxVykHzRyFwyG8MXpvK8eQqamSLVdBr7WPt",
+  "HiGHqwYddP5N2waqUmXPdaASpMpUEvfqPr2fSawctEb",
+  "epiC3zkqa1RfcPMMM1Kc8m3GZGDwF2RmjbfA3g1BBjn",
+  "LGNDfXQFMiRMz3qqTNAREmRFQutMvazqqRrzn5i98uj",
+  "SPrT7eFrCM9UJ4j7Xf9iktKCoBwJjfykFbiNbRsKQm8",
+  "Cc4pHGnoaRWL1WnHsV517T3YvQn5gLDBMiuVXkF9rZhK",
+  "8373hLiAEXxaJ3oV7SRzx4KHwurEg9rEG98tUPj1sdtX",
+  "onePMfirJs2Rx3eixoPnjY6NHiaC74pkQ2k313K2Lxs",
+  "SportGmqffp9zC3VZV7Wwz6s2nCkEB5Q3nVwKGU4esD",
+  "DQPERZ9e86pNJ4mhUnCEP8V75yxZofsipoVrRWT5Wdxd",
+  "cc3novbXuNSe292qKH2gGhxToaWjuBvJbA7zQf8NVxi",
+  "GachaNgyXTU3zFogQ8Z5jR2BLXs8215X2AtEH18VxJq3",
+  "GachazZscHZ5bn3vnq1yEC4zpYdhAYJBzuKJwSJksc9z",
+  "96DULv1BqYfe5wyMr6pVUNC6Uyrtj6yr3tNi6VtfwW9s",
+  "jrS7Pbn38wKiPsXbyNhGCr3icfXuJxdytZr1N4TwdFu",
+];
+
+const sinks = GACHA_ONCHAIN_ADDRESSES.map((address) => `'${address}'`).join(", ");
+const excluded = TEAM_ADDRESSES.map((address) => `'${address}'`).join(", ");
+
+const purchases = {
+  id: "pack-purchases",
+  type: "duneSql" as const,
+  sql: `
+SELECT cast(date_trunc('day', t.block_time) AS date) AS day,
+       t.from_owner AS wallet,
+       sum(t.amount_display) AS volume_usd
+FROM tokens_solana.transfers t
+WHERE t.block_date >= date '{{fromDay}}' AND t.block_date < date '{{toDayExclusive}}'
+  AND t.token_mint_address = '${USDC_MINT}'
+  AND t.to_owner IN (${sinks})
+  AND t.from_owner IS NOT NULL
+  AND t.from_owner NOT IN (${excluded})
+  AND t.amount_display > 0
+GROUP BY 1, 2
+  `,
+  output: {
+    day: "day",
+    wallet: "wallet",
+    volumeUsd: "volume_usd",
+  },
+};
+
+export const retentionManifest = defineRetentionManifest({
+  project: "collector-crypt",
+  chain: CHAIN.SOLANA,
+  stateVersion: 1,
+  observationStart: "2025-01-01",
+  // The current sink went live on Sunday 2025-12-07; cohorts start with the next
+  // full UTC week, backed by eleven months of predecessor history.
+  firstCohortStart: "2025-12-08",
+  // Dune's indexed Solana tables can trail the completed UTC day.
+  dataAvailabilityLagHours: 10,
+  sources: [purchases],
+  methodology:
+    "Daily rolling weekly cohort retention for Collector Crypt on Solana. Each daily row ends a complete seven-day return window; W4 and W12 compare it with the same seven-day window shifted 4 or 12 weeks earlier. The cohort contains wallets whose first observed USDC pack purchase into one of the on-chain gacha sinks occurred in that earlier window, with team and treasury wallets excluded. Purchases paid by card settle off-chain in bundled top-ups without a per-buyer identity and are not counted. Activity is observed from 2025-01-01 across both the current sink and its predecessor, so buyers who migrated to the 2025-12-07 sink are not counted as new; cohorts start on 2025-12-08.",
+});
+
+export default createRetentionFetchAdapter(retentionManifest);