Model inventory
How the models connect
This is a visual restatement of the model inventory table above: the SourceMetadata/DataQuality provenance layer is attached to every model, and each domain model feeds the feature surfaces listed in its “Used by” row.SourceMetadata — the provenance backbone
Every major model carries at least oneSourceMetadata entry. This lets the UI display data-freshness badges and lets consumers decide how much to trust a value.
Valid sourceType values:
dune_scheduled · dune_cached · alchemy · etherscan · coingecko · bigquery · ai_narrative · computed · mock
Rules:
- Dune data is scheduled/cached, never live. Use
dune_scheduledfor results from a Dune-scheduled run; usedune_cachedwhen served from the cache. bigqueryis the source type for WalletWall-owned analytical snapshots served from Google BigQuery: scheduled, watermark-dated tables that routes read through fixed, byte-bounded contracts. It is never live wallet state. Routes label an owned answer withprovider: "bigquery"(or a source header) and set its data instant to the snapshot watermark; see Data Serving Architecture.alchemy,etherscanandcoingeckoare live per-wallet or market reads and carry the observation time of the request.
DataQuality
Structured quality annotation attached to every model. UsemergeDataQuality() when combining data from multiple sources.
WalletSignal
AWalletSignal is a deterministic, sourced fact about wallet behaviour. It is the atomic unit consumed by the narrative engine and the Whale Watcher workspace.
makeSignalId(walletAddress, signalType, windowStart) produces a stable 8-hex-char ID using djb2 — browser-safe, no crypto dependency.
Factory function examples
Usage examples for the three factory functions above —makeSourceMetadata, makeDataQuality / mergeDataQuality, and makeWalletSignal / makeSignalId:
NarrativeInput / NarrativeCard
NarrativeInput is what you pass to the narrative engine. NarrativeCard is the structured output you store and render.
makeNarrativeCard enforces: headline ≤ 120 chars, keyPoints ≤ 5 entries, caveats non-empty.
HolderWallTile
HolderWallTile represents one holder in the treemap. Holder Wall remains a scheduled Dune surface, so the tile deliberately separates:
historicalSource— always Dune scheduled/cached dataliveSource— optional live delta from supported providers;nullwhen unavailable
HolderWallTile does not contain market-level statistics. Use StableSeerResult for token/pool market lookup.
StableSeerResult
Stable Seer data only. No holder analytics. NowalletAddress field. The following fields are intentionally absent: holderCount, topHolders, holderType.
QuantumExposureScore
A 0–100 composite score. Key constraints enforced by the factory:scoreis clamped to [0, 100]riskBandis derived fromscoreviascoreToRiskBand()caveatsdefaults toREQUIRED_CAVEATS(4 entries) — never emptydisclaimerdefaults toSTANDARD_DISCLAIMER
Fixtures
The model layer ships six ready-to-use fixture objects for tests, Storybook stories, and API fallbacks:High-confidence whale accumulation
Baseline + signal + narrative card.
Regular DeFi user
Medium confidence with estimated prices.
Truncated Dune result
Low confidence, multiple warnings.
ETH whale tile
Dual Dune + Alchemy source.
Trending PEPE
Rising volume, no holder analytics.
Medium-exposure wallet
Full breakdown + caveats.
Provenance UI
Use the data-source badge component for compact source footnotes on cards, metric rows, and preview metadata. It accepts either model-stylesource / dataQuality objects or explicit props:
queryName for user-facing context and only set showQueryId when the ID is intentionally public.
Hard constraints
These are enforced by the test suite:- Dune sources must have
sourceTypeofdune_scheduledordune_cached— never a live type. WalletSignal.caveatsmust be non-empty.NarrativeCard.caveatsmust be non-empty.QuantumExposureScore.caveatsmust be non-empty;disclaimermust be non-empty.StableSeerResultmust not contain holder analytics fields.HolderWallTile.historicalSourcemust be a Dune source type.QuantumExposureScore.scoreis clamped to [0, 100].- No external dependencies — zero
node_modulesimports.
Running tests
Related
Data Serving Architecture
The two data classes behind every
sourceType: live provider reads and scheduled snapshots.Signal Engine
The deterministic fact layer that produces
WalletSignal[] from these models.Data Quality and Observability
The underlying observability and data-quality fields the model layer builds on.
Wallet Evidence Model
The provenance-aware layer on
/api/wallet that follows these same schema conventions.
