Data Flow Map

Overview

This map links each major Pharos data domain from upstream source to frontend consumption:

external source -> worker cron / sync -> D1 table or cache key -> API endpoint -> frontend hook -> page(s)

Core Flows

The DEX flow has an additive measured-execution subflow. Pinned Uniswap V3 on Ethereum, Polygon, and Arbitrum, PancakeSwap V3, and Base Aerodrome Slipstream QuoterV2/factory RPC reads, the Fluid resolver adapter, reviewed Curve CryptoSwap get_dy pools, the Ethereum hook-free Uniswap V4 PoolManager/StateView/Quoter shadow adapter, the exact Ethereum legacy Curve 3pool StableSwap get_dy(int128,int128,uint256) deployment, native Solana Raydium CLMM/Orca Whirlpool exact quotes, and reviewed Tron SunSwap V2 factory/reserve plus SUN Smart Router or pinned V2 Router proofs enter worker/src/cron/measured-execution/ through the isolated sync-cl-exit-depth job. Fluid's address-only official ticker rows receive canonical tracked-token metadata only in the bounded target copy, and target construction admits only exact pools on pinned resolver deployments; unsupported chains and identity-poor discovery fingerprints remain unresolved. Curve CryptoSwap activation verifies pinned runtime code/dependency identities and the on-chain coins(i) order before active quotes can become score-eligible. The legacy 3pool path separately binds the pool and main-registry runtime hashes, registry LP token, registry and pool token order, and token decimals at the quote block. Its two counter-stablecoin directions are joined atomically, so a partial packet falls back to the existing reserve simulation instead of satisfying physical-pool coverage. The measured packet remains diagnostic until both directions have three complete and three successful fresh cycles. External pool metadata therefore cannot choose physical quote indices alone. The prior retained-pool target generation is stored in dex_measured_execution_targets; raw proof and validated quote profiles are generation-fenced in dex_measured_execution_quotes. The 10,40 source stage carries this target graph into its exact bounded D1 handoff. The 16,46 sync-dex-liquidity consumer prefers that source slot, reuses that exact stage when retrying after consumption, otherwise falls back to the newest ready stage within 55 minutes, and consumes only a published prior quote generation, exposing proof-free profiles and explicit capability gates through the existing DEX API before charts runs serially. Mature fresh last-known-good profiles can remain route-only across a temporary liquidity shortlist rotation, without re-entering aggregate liquidity inputs; for the 3pool the route compiler reconstructs both sibling directions from the same retained packet or admits neither. A measured target rotation or quote failure leaves an independently complete exact AMM model available instead of attaching a measurement gate to that fallback; unrelated capability gates and actual measured/exact conflicts still fail closed. Native Solana and Tron joins apply explicit reviewed active/shadow registry policy after full proof and current-target validation. Only active native profiles enter the P4 capacity compiler and physical-pool completeness denominator; shadow profiles retain activation-pending, and case-sensitive native pool identities remain case-sensitive through route selection. The reviewed wM/USDC Raydium CLMM policy still captures a pool segment and replays the direct quote's fee, output, and post-swap sqrt price, but it is shadow-only after the first post-activation scoring consumers exceeded the Worker memory limit. Generic Raydium, Orca, Meteora, and unreviewed measured cohorts remain score-ineligible while their activation evidence is pending. Fresh Solana LKG evidence is permitted only after explicit operational collection failure; semantic or malformed rows remain barriers. SunSwap V2's activation and rollback history is incident context only; current registry state is shadow and score-ineligible while target and quote collection continue for revalidation. A Smart Router response containing only multi-hop candidates may use the pinned V2 Router's exact direct-path quote; invalid direct candidates and missing, failed, stale, or identity-mismatched profiles remain target-level fail-closed. SunSwap census rows are excluded from liquidity scoring and price consensus; its latest-only TronGrid state reads are accepted only inside a bounded before/after block bracket.

The private report-cards:fixed-input:exact row is the deterministic compiler-input bridge. It retains the exact V8-shaped input schema only because V9 compilation and replay consume that structure; it is never served as a V8 rating.

Safety Score V9 supply attribution remains on the dedicated +8 trigger. Exact V9 input preparation now runs serially after each successful 16,46 DEX publication and receives that publication's generation ID; compilation runs at 22,52. If the DEX consumer throws, is locked, or deliberately withholds publication, the dependent preparation child records a neutral not-started skip instead of a second synthetic failure; a nominally successful DEX result without an exact generation still fails closed. Preparation rejects a snapshot that does not capture the expected DEX generation, and compilation re-reads the latest accepted DEX generation before enrichment and again before evaluation so an older candidate cannot publish. Delayed or overlapping invocations skip before loading their runner graphs. The supply-attribution producer due interval is quantized below the compiler acceptance window so the quarter-hour trigger grid produces roughly 30-minute healthy captures instead of a 45-minute beat. Compilation requires a finished same-version quarter-hour core slot. An ok slot admits directly; a degraded slot admits only when the durable publication ledger proves that the same Worker published the current stablecoins cache in that slot. The compiler then requires the fixed input's stablecoin timestamp to equal the live cache generation, so isolated row-coverage gaps can become asset-local V9 evidence without allowing stale or no-write stablecoin runs through.

The compiler requires matching fixed-input, peg-provenance, attribution, methodology, and evaluation-build identities. It then evaluates V9 and writes the accepted report-cards:v9 publication with matching health. Global or identity-level failures hold the prior accepted publication. A complete supply-attribution generation that belongs to the same fixed input but finished just after that input's scoring clock is treated as a neutral cadence defer instead of publishing an aggregate-only partial candidate; malformed, rejected, stale, registry, or inventory-incompatible attribution still fails closed through the normal publication gates and records a clause-specific reason. Asset-local producer failures do not freeze unrelated ratings while at least 90% of active assets remain unaffected, and tolerated partial publications remain cron-healthy while surfacing affected assets in metadata. The V9 compiler captures DEX, redemption, and live-reserve load health before fallback filtering. Immediately before canonical persistence, an acceptance fence combines those global source states, the existing active-result and rated-count floors, and newly binding producer-failed deterioration against the last accepted V9 envelope. Producer-failed deterioration becomes a global hold only when fewer than 90% of active assets remain unaffected; isolated failures above that healthy-coverage floor do not freeze unrelated ratings. The accepted publication and current health commit atomically. A held attempt updates only report-cards:v9:publication-health, leaving accepted ratings and timestamps unchanged. The V9-only supply-attribution enrichment may also bind an aggregate asset supply to a reviewed route-ID inventory. The wM observer requires the complete Ethereum, Arbitrum, Base, Plume, and Solana deployment packet, verifies pinned runtime/controller identities at fixed-clock blocks or slots, and conserves the existing aggregate supply while allocating it across routes. The Centrifuge observer applies the same all-or-nothing rule only to the allowlisted JTRSY and ACRDX burn/mint inventories: it binds every official EVM deployment to exact runtime code, a non-proxy implementation slot, and the authorized Centrifuge Spoke, then binds the official Token-2022 Solana mint to its exact direct authority in one finalized context. It never admits lock/mint or adapter inventories whose totalSupply() sums could double-count backing. The XAUT observer binds the configured Tether transparency disclosure to one finalized Ethereum token/treasury/adapter observation and the complete reviewed XAUt0 representation-group inventory. The issuer's totalAuthorized - notIssued amount is admitted as circulating liabilities only when finalized totalSupply() and treasury balanceOf() independently match the two disclosed inputs and quarantined supply is zero. It emits one non-group canonical row and one pooled group row carrying the exact locked share of circulating liabilities and common failure domains, without claiming destination-chain shares. Any missing, duplicate, stale, skewed, issuer/on-chain-mismatched, identity-mismatched, inventory-mismatched, materially unresolved, or non-conserving packet fails closed; V8 and public payloads remain unchanged. Reserve sync may carry a nested V9-only exact route attempt into the redemption-backstop preload and then the V9 extension. The first such path is FPI's Controller Pool observation, which is bound to the same successful issuer collateral adapter result and one pinned Ethereum block. Accepted and rejected attempts remain outside public V8 reserve, redemption, and report-card payload semantics. GET /api/report-cards/v9 exposes the canonical, fully identified V9 publication. The active frontend, yield, Telegram, chain analytics, and V9-compatible history all consume that publication directly. Held V9 remains available only as the last accepted API/UI snapshot with explicit held metadata. Current-data consumers, organic safety alerts, and organic history writes fail closed without falling back to V8; independent depeg and incident pipelines continue.

Scheduling Backbone

Cron expressions are deployed from worker/wrangler.toml; shared/lib/cron-jobs.ts owns canonical schedule/job metadata and shared/lib/scheduled-runner-registry.ts owns expression-to-runner dispatch. Use Worker Infrastructure: Cron Scheduling for execution details and npm run check:cron-sync / npm run check:cron-connections for the authoritative live inventory and connection-budget report.

Freshness Contract (Frontend)

API hooks that use useApiQuery follow the interval supplied by their caller:

• staleTime = interval
• refetchInterval = 2 * interval

Defined centrally in src/hooks/use-api-query.ts. Cron-backed hooks should pass the producer cadence unless a documented route-specific exception applies. Current exceptions include /api/health (1-minute diagnostic polling, not cron-backed) and /api/usds-status (15-minute UI polling over a daily source snapshot).

Notes

• Core aggregate boundary: shared/data/stablecoins/listing-decisions.json classifies the catalog, while shared/lib/stablecoins/aggregate-registry.ts projects active core-stablecoin and cash-equivalent entries for monetary aggregates. PSI, digest market/supply totals, current homepage market cap, chain totals/history, and non-USD share consume that projection. Depeg, DEWS, price, per-asset history, and digest risk-signal lanes continue monitoring every active listing, including variants and stable-value investments. Client ranking filters use the compact listingClass field in coins.client.generated.json, not the full decision ledger. New PSI and digest snapshots identify the aggregate boundary as core-stablecoins-v1 so consumers can distinguish legacy rows.
• DEX price bridge: The half-hourly DEX liquidity cron now rebuilds dex_prices.price_sources_json from the final retained priced-pool surface after dedupe, caps, scoring filters, and unit normalization, publishing one aggregate per protocol. The quarter-hourly pricing cron reads these via loadDexPriceSources() and promotes at most one individually-weighted consensus source per protocol: fluid-dex (weight 3), balancer-dex (weight 3), curve-dex (weight 3), uniswap-v3-dex (weight 2), uniswap-v4-dex (weight 2), raydium-dex (weight 2), orca-dex (weight 2), meteora-dex (weight 2), pancakeswap-dex (weight 2), aerodrome-dex (weight 2), velodrome-dex (weight 2). These promoted protocol sources only enter primary consensus when corroborated or when no non-DEX voices exist, and the overlapping dex-promoted aggregate (weight 1) is withheld whenever at least one promoted protocol candidate passes freshness and TVL validation for the same asset, even if that candidate is then excluded for lack of corroboration. The aggregate DEX fallback enters consensus only when no protocol candidate clears those pre-corroboration checks. DEX admission/merge skip reasons are emitted into logs and cron metadata so stale rows, malformed snapshots, TVL filters, missing registry mappings, and duplicate identities can be traced without scraping the raw tables.
• Abort-aware high-volume publication: DEX liquidity and DEWS persistence pass the cron AbortSignal into chunked D1 batches, retrying D1 operations, and final freshness-sentinel guards. If timeout or lease-loss aborts the run after a partial batch, the run fails before publishing freshness:dex-liquidity, freshness:dews, or the exact DEWS publication pointer. Durable DEWS consumers, canaries, and freshness reporting use the pointer rather than raw MAX(computed_at) rows.
• Cache passthrough endpoints include freshness metadata via _meta and/or X-Data-Age.
• Chain profile pages intentionally coordinate two APIs: GET /api/chains for the summary card and GET /api/stablecoins for composition. The detailed sections stay hidden until both snapshots share the same updatedAt, which keeps incomplete or mismatched data from being presented as a full per-chain breakdown.
• chain_supply_history remains a forward-only internal dataset until the post-2026-04-08 baseline. Earlier rows were written before shared chain-label canonicalization and are not approved for public charting.
• /api/dex-liquidity is meta-aware on the frontend: the page uses worker freshness metadata (and degraded-run Warning headers) rather than client fetch time to assess staleness.
• Liquidity history now carries coverageClass / coverageConfidence; trend and durability consumers should treat low-confidence snapshots as informational, not authoritative baselines.
• dex_liquidity_history is retained for the public 365-day history window; older daily snapshots are pruned during successful sync-dex-liquidity persistence instead of living as an indefinite research archive.
• Transient measured-execution, scoring-stage, liquidity-run, price-run, and pool-staging rows are pruned by their owning producers in bounded oldest-first D1 passes. Cleanup telemetry is additive to cron metadata and cleanup failure cannot invalidate an already successful publication.
• Admin/backfill endpoints bypass edge cache via cacheBypass flags in shared/lib/api-endpoints/.
• The stablecoins cache loader distinguishes ok, degraded, and error states. Operator-facing or published consumers (/status, daily digest, safety snapshot) now fail closed on non-ok cache reads instead of treating broken cache state as an empty valid dataset.
• consensusSources flows from the price-consensus cron stage through the stablecoins cache → /api/stablecoins and /api/peg-summary → useStablecoins / usePegSummary hooks → PriceTransparencyCard on the detail page and CoverageBadge source-count enrichment on the coverage page.
• priceSourceConfidenceProfile flows from DEX-inclusive primary pricing through the stablecoins cache and /api/stablecoins. It is omitted for non-DEX prices and currently remains a data/API transparency field rather than a UI dependency.