Skip to main content
WalletWall answers two different kinds of question, and it serves them from two different kinds of data. Keeping the two apart is the architectural rule every other data page builds on.

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.
A cached or scheduled result is never presented as live. Every response names its source class and carries the instant its data is true for, so the UI can label it and a reader can tell a snapshot from a reading.

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.
The result is not “BigQuery instead of Dune”. It is a layered serving model in which the surfaces with the highest value and the highest query cost run on owned snapshots, the remaining scheduled feeds stay on Dune, and live wallet state stays on provider reads.

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.
  • A single SELECT statement with an explicit LIMIT, 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 maximumBytesBilled ceiling, 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.
  • 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 STRING parameter, 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 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 503 when their owned read cannot be served, and the page hides the section. A 200 with 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.