You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|`supplySource`|`string \| undefined`| Supply data source: `"defillama"` or `"coingecko-fallback"`|
88
90
|`price`|`number \| null`| Current price in USD |
89
91
|`circulating`|`Record<string, number>`| Current supply in USD, keyed by pegType (e.g. `{ "peggedUSD": 138000000 }`) |
90
92
|`circulatingPrevDay`|`Record<string, number>`| Supply 24 h ago |
@@ -597,6 +599,42 @@ Each element uses `digestText` (note: differs from the singular `/api/daily-dige
597
599
598
600
---
599
601
602
+
### `GET /api/digest-snapshot`
603
+
604
+
Contextual data snapshot for a specific digest date — includes the digest's input data, active depeg events, and blacklist events for that day. Used by SSG builds for individual digest pages.
605
+
606
+
**Cache:** slow
607
+
608
+
**Required query parameter**
609
+
610
+
| Param | Type | Description |
611
+
|-------|------|-------------|
612
+
|`date`|`string`| Date in `YYYY-MM-DD` format (required) |
@@ -629,6 +671,7 @@ Worker health check. Reports cache freshness and blacklist table integrity. Not
629
671
|`caches`|`Record<string, CacheStatus>`| Per-cache freshness status |
630
672
|`blacklist.totalEvents`|`number`| Total events in blacklist table |
631
673
|`blacklist.missingAmounts`|`number`| Events where `amount` is null (should be 0) |
674
+
|`circuits`|`Record<string, CircuitRecord>`| Per-source circuit breaker states. Keys: `defillama-stablecoins`, `defillama-coins`, `defillama-yields`, `defillama-protocols`, `coingecko-prices`, `coingecko-mcap`. Empty until first cron run |
632
675
633
676
**`CacheStatus`**
634
677
@@ -639,8 +682,8 @@ Worker health check. Reports cache freshness and blacklist table integrity. Not
639
682
|`healthy`|`boolean`|`true` when `ageSeconds / maxAge ≤ 1.5`|
640
683
641
684
**Overall status logic:**
642
-
-`healthy` — worst cache ratio ≤ 1.5
643
-
-`degraded` — worst ratio between 1.5 and 2
685
+
-`healthy` — worst cache ratio ≤ 1.5 and no open circuits
686
+
-`degraded` — worst ratio between 1.5 and 2, or any circuit is open
644
687
-`stale` — worst ratio > 2
645
688
646
689
---
@@ -664,7 +707,7 @@ Daily Pharos Stability Index (PSI) scores. The PSI is a composite ecosystem heal
Copy file name to clipboardExpand all lines: docs/data-pipeline.md
+28-4Lines changed: 28 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,13 +2,24 @@
2
2
3
3
## Supply Pipeline
4
4
5
-
Supply data uses a simple two-source model:
5
+
Supply data uses a two-source model with automatic fallback:
6
6
7
7
-**DefiLlama** — primary source for all stablecoins tracked by DefiLlama's stablecoin API
8
-
-**CoinGecko market cap** — used only for gold/silver/fiat tokens that DefiLlama doesn't track (e.g. XAUT, PAXG, KAU)
8
+
-**CoinGecko market cap** — used for gold/silver/fiat tokens that DefiLlama doesn't track (e.g. XAUT, PAXG, KAU), and as a **full supply fallback** when the DefiLlama stablecoins API is down (circuit breaker triggers `fallbackToCgSupply()`)
9
9
10
10
No on-chain overrides, no CMC supply patches, no manual supply corrections.
11
11
12
+
### Circuit Breakers
13
+
14
+
All external data sources are protected by per-source circuit breakers (`worker/src/lib/circuit-breaker.ts`). State is persisted in the D1 `cache` table under keys like `circuit:defillama-stablecoins`.
15
+
16
+
-**Open threshold**: 3 consecutive failures
17
+
-**Probe interval**: 30 minutes (one request allowed to test recovery)
18
+
-**Alerts**: Webhook alert fires on open and close transitions
19
+
-**Health impact**: Any open circuit triggers `degraded` status on `/api/health`
The **list** endpoint (`stablecoins.llama.fi/stablecoins`) returns `circulating` values **already in USD** for all peg types — `peggedRUB`, `peggedEUR`, `peggedJPY`, etc. are all denominated in USD despite their key names.
@@ -19,7 +30,20 @@ Do **not** multiply list endpoint values by price — that would double-convert
19
30
20
31
## Price Enrichment Pipeline
21
32
22
-
`enrichMissingPrices()` in `worker/src/cron/enrich-prices.ts` uses a 5-pass system for assets with missing or zero prices:
33
+
### Dual-Primary Price Validation
34
+
35
+
Before the enrichment pipeline runs, `fetchDualPrimaryPrices()` fetches prices from both the DefiLlama coins API and CoinGecko `/simple/price`**in parallel** for all assets with a valid `geckoId`. It cross-validates within 50 basis points:
36
+
37
+
-**Both agree (≤50 bps)** → `priceConfidence: "high"`, use DL price
2.**Pass 2:** CoinGecko ID -> DefiLlama CoinGecko proxy
@@ -84,7 +108,7 @@ The live `/price/` endpoint requires no API key and has no documented rate limit
84
108
85
109
## Stability Index (PSI) Computation
86
110
87
-
`computeAndStoreStabilityIndex()` in `worker/src/cron/stability-index.ts` runs daily at 07:55 UTC and computes a composite ecosystem health score (0–100). Formula: `Score = 100 − severity − breadth − freezes + trend`. See `docs/stability-index.md` for full algorithm, calibration examples, and band definitions.
111
+
`computeAndStoreStabilityIndex()` in `worker/src/cron/stability-index.ts` runs every 15 minutes and computes a composite ecosystem health score (0–100). Formula: `Score = 100 − severity − breadth + trend`. See `docs/stability-index.md` for full algorithm, calibration examples, and band definitions.
0 commit comments