> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletwall.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Holder Wall
> Zoomable treemap of top token holders with rank deltas, leaderboard, wallet drawer, and Quantum Exposure Card.
# Holder Wall
Holder Wall is the ownership map and holder analytics surface of WalletWall. It displays the top holders of a selected token as a zoomable treemap, annotated with rank deltas, wallet labels, and an interactive drawer for per-wallet detail.
Data is powered by Dune Analytics scheduled queries. It is never live streaming.
Aggregate metrics for the current token: total holders tracked, wallets new this week, and the timestamp of the most recent Dune query run.
Zoomable tiles sized by USD balance, split across Active Wallets, Whale Wallets, and Dormant Quantum Wallets tabs.
Top holders in rank order with labels, balances, and rank delta indicators.
Per-wallet detail — ENS, balance, timestamps, and the Quantum Exposure Card — opened from any tile or leaderboard row.
## Data flow
```mermaid theme={null}
flowchart TD
accTitle: Holder Wall data flow from Dune query to treemap and drawer
accDescr: A Dune scheduled query for the active tab supplies holder data. Tile area is derived from balance in USD, or a proxy estimate for Dormant Quantum Wallet tiles. The Redis snapshot store is compared against the current result to derive rank delta badges and the New this week marker. Clicking a tile or leaderboard row opens the wallet drawer, which can route to the Quantum Exposure Card, Coinstellation, or a Stablecoin Vault readiness handoff.
dune["Dune scheduled query
(active tab's feed)"]:::input
redis["Redis snapshot store"]:::datastore
calc["Tile area calc
(balance USD or proxy estimate)"]:::process
rank["Rank delta derivation"]:::process
render["Treemap + leaderboard render"]:::output
tileClick["Tile / row click"]:::process
drawer["Wallet drawer"]:::output
quantum["Quantum Exposure Card"]:::output
coinstellation["Coinstellation graph view"]:::output
vaultHandoff["Stablecoin Vault
readiness handoff"]:::output
dune --> calc
calc --> render
dune --> rank
redis -. "previous snapshot" .-> rank
rank --> render
render --> tileClick
tileClick --> drawer
drawer --> quantum
drawer --> coinstellation
drawer --> vaultHandoff
classDef input fill:#FAFAF0,stroke:#B87333,color:#2B2118,stroke-width:1.5px;
classDef process fill:#B84923,stroke:#6B2412,color:#FFF7E8,stroke-width:1.5px;
classDef output fill:#9AAB89,stroke:#526246,color:#172014,stroke-width:1.5px;
classDef datastore fill:#6F7068,stroke:#3C3D38,color:#FFF7E8,stroke-width:1.5px;
```
*Rank delta badges and the "New this week" marker require the Redis snapshot store; without it, both are omitted. All Dune data is scheduled/cached, never live.*
## KPI strip
A strip at the top of the page surfaces aggregate metrics for the current token: total holders tracked, number of wallets new this week, and the timestamp of the most recent Dune query run. The KPI strip reads from the `metadata` block of the `/api/holder-wall` response.
## Signals panel
Below the KPI strip, a row of **signal cards** summarizes analytical readings for the holder set currently on screen. Each card shows a short label and a one-line summary:
* **Concentration** — how much of the total mapped value the top few entities hold.
* **Entity mix** — the breakdown of holders across classifications (whale, exchange, protocol, institution, unclassified).
* **Data freshness** — whether the underlying Dune data is current or may be stale, with the query run timestamps.
* **Activity / value** — whether the most valuable holders are also the most active, or the two diverge.
* **Quantum exposure** — dormant entities and their mapped stablecoin balance, the wallets most relevant to migration planning.
The signals are derived from the treemap that is currently displayed, so they **respect the active tab and any filters** — narrowing the wall re-computes the cards against the visible subset rather than the whole token.
### Signal click
Clicking a signal card opens a drawer with the full breakdown behind that reading — the headline figure plus the ranked entities that drive it.
The **Quantum exposure** card additionally *reconciles the wall with the signal*: selecting it switches the treemap to the **Dormant Quantum Wallets** tab and clears active filters, so the holders shown below are exactly the dormant entities the card is describing. This prevents the earlier mismatch where the signal could reference dormant wallets while the treemap was still showing a different tab or a filtered subset.
## Treemap layout
Each tile in the treemap represents one holder. Tile area is proportional to the wallet's balance in USD at the time of the last Dune run.
### Tabs
* **Active Wallets** — wallets included in the 48-hour active wallet feed
* **Whale Wallets** — wallets included in the whale trades feed
* **Dormant Quantum Wallets** — wallets sourced from the dormant quantum candidates Dune query. Tile area uses a proxy USD balance estimate (not a live balance). A disclaimer banner renders above the treemap when this tab is active to flag the estimated nature of balance data.
### Rank badges
Each tile carries a rank badge showing absolute rank (1, 2, 3 …) and a delta indicator comparing the wallet's rank in the current snapshot to the previous Redis snapshot.
Rank deltas require the Redis-backed snapshot store to be configured. Without it, delta badges are omitted and the "New this week" count is unavailable.
The rank snapshot is written to Redis on each successful Dune result fetch and compared on the next fetch. Rank delta is a derived field — it is not stored in Dune.
### Tile detail and signals
Large tiles carry a labelled **signal pill** — one of `vault`, `exposed`, `dormant`,
`tracked`, or `estimated` — plus a real transaction-count row. Smaller tiles fall back
to a color-matched square marker so the signal stays legible at any tile size. Signal
colors reuse the shared `Badge` tone washes (translucent background + thin border), so
a signal means the same color here as everywhere else in the app. The detail renders
directly on the live SVG treemap; `estimated` marks tiles whose USD area comes from a
proxy balance estimate rather than a live balance.
### Tile click
Clicking a tile opens the wallet drawer for that address. It also enables navigation to Coinstellation for a full graph view of the wallet's on-chain relationships.
## Leaderboard
The leaderboard panel lists the top holders in rank order with holder labels, balances, and rank delta indicators. The "New this week" marker appears on wallets that were not present in the previous Redis snapshot.
"New this week" is a Redis-derived signal. It reflects wallets that entered the tracked set since the last snapshot write, not wallets that created their Ethereum account this week.
## Filters
The filter bar allows narrowing by wallet category (whale, active, dormant) and by rank range. Filters operate client-side against the current Dune result set.
## Wallet drawer
Clicking any tile or leaderboard row opens a slide-in drawer with per-wallet detail:
* Resolved ENS name (when available)
* Balance and rank (shown as **Proxy value** for Dormant Quantum Wallet tiles, where balance is estimated)
* First seen / last active timestamps
* Link to open Coinstellation for this wallet
* Quantum Exposure Card (see below)
### Dormant Quantum Candidate detail
When the drawer opens for a tile sourced from the dormant quantum candidates query, an additional detail section appears showing:
* Days since last outgoing transaction
* Outgoing transaction count
* Token symbols held
* Exposure type classification (e.g. `dormant`, `quantum_exposed`)
## Quantum Exposure Card in the drawer
The Quantum Exposure Card renders inside the drawer under the "Quantum Intelligence" heading.
* Composite Quantum Exposure Score (0–100)
* Risk band label: Low exposure / Moderate exposure / High exposure / Migration priority / Unknown
* Per-component breakdown: public key exposure, address reuse, signature scheme, value at risk, dormancy, migration readiness risk, recovery path risk
* Behavioral exposure signals (adversarial signals) — only signals with `score >= 0.3` are rendered
* Source caveats and confidence level
A high Quantum Exposure Score does not mean the wallet is currently exploitable. It is a forward-looking heuristic for cryptographic migration planning. See the Quantum Intelligence feature page for full framing.
## Stablecoin Vault handoff
When a valid EVM wallet is open in the wallet drawer (any tab), the drawer can route to the **Stablecoin Vault** readiness assessment at `/stablecoin-vault` with the wallet address in context.
This handoff was added in PR #1003. It applies to wallets where a recognizable EVM address is present. The readiness route is read-only — no wallet connection, signing, or transaction is required.
The Stablecoin Vault entry point surfaces only for valid EVM wallets. Wallets where only a proxy-balance estimate is available (Dormant Quantum Wallet tiles) may still show the entry, but the readiness assessment will carry the appropriate data-quality caveats.
## Data source aliases
| Public alias | Used for |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Active wallet feed | Active Wallets tab — 48-hour active wallet feed |
| Whale trade feed | Whale Wallets tab — whale trade feed |
| Dormant quantum candidates feed | Primary source for the Dormant Quantum Wallets tab — 13-column Dune query with dormancy, exposure, and vault-candidate signals |
| Dormancy exposure feed | Legacy fallback for the Dormant Quantum Wallets tab when the candidates query is unavailable |
| Redis snapshot store | Rank delta snapshots and "New this week" detection |
All Dune data is labeled `Scheduled/Cached` in the UI. The `queryRunAt` timestamp is shown in the KPI strip.
## Related
Large stablecoin and treasury-like wallet monitoring — activity heatmap, adversarial signals, and narrative engine.
The full Quantum Exposure Score specification, migration path table, and approved framing behind the drawer's card.
The wallet relationship graph a tile or leaderboard row links out to.
The read-only readiness assessment the wallet drawer can hand off to for a valid EVM wallet.