Live, per-wallet state
What does this wallet hold and do right now? Request-time observations from configured on-chain and
market-data sources, with observation time and source metadata attached.
Scheduled, analytical snapshots
What do cohorts of wallets look like over a window? Answered from tables WalletWall builds on a
schedule: WalletWall-owned BigQuery snapshots, and Dune query results warmed into a cache.
Two classes of data
The Model Layer records the class on every value as a
sourceType
(alchemy, etherscan, bigquery, dune_scheduled, dune_cached, …), and the
Wallet Evidence Model turns provider state into per-claim
status so that an unavailable reading never becomes a confident zero.
Why WalletWall owns its analytical data
In production, until October 2026 every scheduled analytic was served from Dune. In August 2026 WalletWall decided to build the analytical surfaces it depends on most as owned tables in Google BigQuery, computed from public blockchain datasets, and to serve them through contracts the application controls. The first surfaces moved in October 2026, one at a time:- Owned schemas and lineage. Each table has a declared schema, a watermark that says exactly how far it is complete, and a refresh that can be replayed and reconciled against its public source.
- Cost that is bounded in code. Every statement, refresh run and request-time read carries a byte ceiling the deployment cannot raise.
- Independence from a single third-party query platform. The migration moved one surface at a time, each behind its own switch with the previous source kept as the fallback.
How a request is served
Every migrated route follows the same shape. The owned read is one fixed statement, bounded in bytes and time; everything that could go wrong falls through to the route’s previous source, while it still has one.Stable Seer’s large flows and volume sparklines have finished this path. Their selector and their Dune
fallback were removed in November 2026: the owned table is their only source, and a read that cannot
be served answers
503. The legacy branches below no longer apply to those two routes.1
The route reads its own switch
Each route that still has a previous source has its own selector with exactly three values:
legacy (the default when unset), shadow and bigquery. Nothing else selects a source — not
the presence of a credential, not another route’s switch. Rolling such a route back means setting
its selector to legacy or removing it; no table, grant or job changes.2
One fixed, bounded read
The route runs a single
SELECT whose text is a constant in the code. Four of the five reads take
no parameters at all. The one keyed read (the quantum signature snapshot) passes the wallet as a
named query parameter, so a request value never enters the SQL text. Every read sends a 64 MiB
byte ceiling, waits at most 5 seconds for BigQuery and 6 seconds end to end.3
The result is judged before it is served
A read must return its whole result in one page (the client never follows a page token and
checks the reported row total), and the snapshot’s watermark must be inside the surface’s
staleness tolerance. A result that fails either check is not served and is not cached.
4
Serve with a label, or fall back
An owned answer is labelled (
provider: "bigquery" in the body, or a source header for the
list-shaped route) and carries the watermark as its data instant. Any failure, refusal,
incomplete or stale read falls through to the route’s unchanged legacy path, which answers
exactly as it did before the migration.Fixed runtime-read contracts
The request-time reads are deliberately small and deliberately rigid. Tests pin the whole contract.What every runtime read is
What every runtime read is
- A single
SELECTstatement with an explicitLIMIT, embedded as a constant in its route. - Addressed to exactly the owned snapshot tables the runtime identity may read — seven relations in five WalletWall-owned datasets, and no public dataset.
- Sent with a 64 MiB
maximumBytesBilledceiling, a 5-second BigQuery wait and a 6-second request deadline, all code constants. - Executed through one client module, the only file in the application that reaches the BigQuery API, using the synchronous query endpoint only.
What no runtime read can do
What no runtime read can do
- Write, create, alter or delete anything: the runtime identity holds read-only grants on the serving tables and the watermarks they are judged by, and nothing on the lease or build tables.
- Run arbitrary SQL: there is no path from a request to a statement. The keyed read accepts one
named
STRINGparameter, validated for shape before the credential is even resolved. - Exceed its budget silently: an over-ceiling query is refused by BigQuery without charge, and the client refuses before sending if the ceiling is missing or above the code-owned maximum.
- Follow a second result page: a result larger than the page it asked for is treated as a failure, not truncated. This rule exists because, on 2026-10-24, a 671-row result was once served as its first 500 rows.
The byte ceiling has two layers
The byte ceiling has two layers
The client enforces a code-owned absolute maximum of 4 GiB for any statement it will ever
send; configuration can select a lower value but never a higher one. Every serving read sends
64 MiB. The gap is intentional: the 4 GiB figure bounds a runaway statement, the 64 MiB figure is
the honest size of a snapshot read. Anything that needs more than a few tens of megabytes to answer
is transformation work, and it belongs in the scheduled refresh, not in a request.
Validated snapshots and cohorts
Each surface serves a small, precomputed table that a scheduled refresh built and verified. The request-time read never aggregates history; it reads the latest validated snapshot.
A snapshot is only ever written whole: the refresh verifies the window it loaded before it advances the
watermark, and a cohort or range is published with one atomic statement. The
refresh model explains those guarantees.
Safe fallback behaviour
Fallback is designed to be boring. On a route that still has a previous source, the owned path can only make a response better; it can never make a request fail in a new way.- The legacy path is unchanged. When the owned read cannot answer, the route runs exactly the code it ran before the migration and returns exactly that response, without the BigQuery label. What that answer holds depends on the legacy source’s own state: the Dune stablecoin and multichain schedules behind the holdings and signature feeds stopped refreshing on 3 August 2026, so a fallback there serves an explicit empty or unknown answer — never a fresh-looking number.
- A route with no previous source says so. Large flows and volume sparklines answer
503when their owned read cannot be served, and the page hides the section. A200with an empty list is a read that succeeded, dated by its watermark. For large flows it says only that the newest rows the read returns hold nothing for that symbol, not that the symbol had no large flow in the week. - Failures are remembered briefly. After a failed, empty or malformed owned read the route starts no new owned read for five minutes, so a BigQuery problem costs at most a dozen reads an hour per instance. A stale snapshot does not trip that breaker, because it is already cached and costs no more reads.
- Stale is not served as current. A snapshot past its tolerance is not served at all; between the warning threshold and the tolerance it is served with an explicit warning.
- Absence is not safety. The keyed signature read answers “not observed signing on a covered chain in the window” for a wallet with no row, dated by the snapshot window, and never substitutes the legacy population for it. An absence that cannot be dated falls back.
- Shadow mode is invisible to the client. In
shadow, the legacy path answers first; the owned read runs after the response is sent, at most once per five minutes per instance, and only allow-listed numbers and closed-vocabulary outcomes are logged — never an address or a hash.
Source provenance in responses
Runtime identity, at the level of principle
- The web runtime reads BigQuery without a stored key. Each request’s platform identity token is exchanged at Google’s Security Token Service for a short-lived access token, and the federated identity itself holds the grants. A service-account key path exists only as an explicit fallback.
- The runtime identity holds the right to run jobs and read-only access to the serving tables and the watermarks they are judged by, and nothing else: no dataset-wide grant, no access to the lease or build tables, no permission to change IAM.
- Refresh work runs under a separate identity with a narrow custom role that can read and update the tables it maintains but cannot create, delete or alter them. The two identities never share a credential.
- No user value is interpolated into SQL. Request values travel as validated, typed query parameters, and only one read accepts any.
- Credentials, project identifiers and infrastructure names are not part of this documentation.
What serves from BigQuery today
Status recorded on 1 November 2026 from the live routes’ own source labels and the migration runbooks. The wallet-activity row was updated after its 2 November 2026 cutover, and the two Stable Seer rows when their fallback was removed in November 2026. A route’s label is authoritative for the response you are holding; this table is a dated snapshot.
Holder Wall, peg history, the quantum dormancy feed and the
exposure-report cohorts remain scheduled Dune surfaces warmed into a cache once a day; the Whale
Watcher 12-week baseline and the value-at-risk and migration-readiness feeds remain scheduled Dune
surfaces read cache-aside. The Dune queries reference lists them.
Dune today
Dune remains a scheduled, cached source. Dune schedules materialise results on Dune’s side; a daily warmer copies the feeds on its list into a cache, and the remaining feeds are read cache-aside. No public route executes a Dune query. A cold cache on a cache-aside feed triggers one result read only when an operator has enabled result reads; otherwise the feed answers empty. The UI labels every Dune-sourced value Scheduled/Cached.Where to go next
Data Foundation Refresh Model
How the snapshots are built: slices, watermarks, the single-runner lease, byte budgets and atomic publication.
BigQuery Serving & Canary
How a surface is promoted from shadow to primary: readiness gates, probes, rollback.
Data Quality and Observability
The provider roles, observability fields and source-confidence map behind every response.
Dune queries
The scheduled Dune feeds that remain, their cadence and staleness thresholds.

