> ## 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.

# Whale Watcher

> Large stablecoin and treasury-like wallet monitoring for vault-readiness review — activity heatmap, adversarial signals, narrative engine, holdings strip, and protocol affinity bar.

# Whale Watcher

Whale Watcher is a supporting signal surface for Stablecoin Vault readiness. It focuses on large stablecoin and treasury-like wallet monitoring, assembling multiple analytical layers for a single wallet address into one view — activity history, behavioral signals, AI-assisted narratives, token holdings, and protocol usage patterns — so the movement of significant wallets can be carried into a vault-readiness review. It is a read-only intelligence surface: no custody, no wallet keys, no account required.

## Homepage signal feed

The homepage includes an illustrative Whale Watcher signal feed. It animates
sample on-chain alert rows and links into the Whale Watcher route when a row is
selected.

The feed is a product-navigation preview, not a live provider stream and not a
Dune query result. It should be documented and described as illustrative sample
activity only. The full workspace remains the source-backed surface: scheduled
Dune activity, live wallet provider samples, deterministic signals, and
source/caveat badges are rendered after a wallet is opened.

## Workspace layout

The workspace is organized into vertical sections, top to bottom:

<Steps>
  <Step title="Wallet header">
    ENS, address, and observability badge.
  </Step>

  <Step title="12-week activity heatmap">
    Per-day on-chain activity intensity over a rolling window.
  </Step>

  <Step title="Adversarial signals panel">
    Deterministic behavioral exposure heuristics.
  </Step>

  <Step title="Narrative cards">
    Template-based, optionally AI-rewritten, summaries of the signals.
  </Step>

  <Step title="Quantum Exposure section">
    Quantum Exposure Card and Quantum Vault Readiness Card.
  </Step>

  <Step title="Wallet holdings strip">
    Token portfolio, as balances or trading exposure.
  </Step>

  <Step title="Protocol affinity bar">
    Share of on-chain volume by DeFi protocol.
  </Step>
</Steps>

## Data flow: activity data to narrative

```mermaid theme={null}
flowchart TD
    accTitle: Whale Watcher data flow from activity data to narrative
    accDescr: The Dune 12-week activity query, or the 48-hour active-wallet fallback when the 12-week query is not configured, supplies the historical wallet baseline. Live wallet events from Alchemy or Etherscan are combined with that baseline by the signal engine to produce WalletSignal facts. The narrative engine templates those facts into narrative cards, with an optional AI layer that may rewrite prose but must leave evidence values unchanged. The same WalletSignal facts also feed the Protocol Affinity Bar.
    duneActivity["Dune 12-week activity query"]:::input
    duneFallback["Dune 48h active-wallet<br/>fallback"]:::input
    liveEvents["Live wallet events<br/>(Alchemy / Etherscan)"]:::input
    baseline["HistoricalWalletBaseline<br/>(may be null)"]:::process
    signalEngine["Signal engine"]:::process
    facts["WalletSignal facts"]:::output
    narrativeEngine["Narrative engine<br/>(template-based)"]:::process
    aiLayer["Optional AI rewrite<br/>(evidence unchanged)"]:::decision
    cards["Narrative cards"]:::output
    affinity["Protocol Affinity Bar"]:::output
    duneActivity --> baseline
    duneFallback -. "fallback when 12-week<br/>query unset" .-> baseline
    baseline --> signalEngine
    liveEvents --> signalEngine
    signalEngine --> facts
    facts --> narrativeEngine
    narrativeEngine --> aiLayer
    aiLayer --> cards
    facts --> affinity
    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 decision fill:#D6A85A,stroke:#8A5A1F,color:#2B2118,stroke-width:1.5px;
    classDef output fill:#9AAB89,stroke:#526246,color:#172014,stroke-width:1.5px;
```

*Signals degrade gracefully when the baseline is `null`. AI narrative rewriting is optional and only active when a provider key is configured. See [Signal Engine](/architecture/signal-engine) for the full taxonomy.*

## 12-week activity heatmap

The heatmap visualizes per-day on-chain activity intensity over a 12-week rolling window. Each cell represents one day; color intensity corresponds to the `intensity_score` field from the Dune scheduled query.

<Warning>
  The 12-week heatmap requires `DUNE_QUERY_12WK_ACTIVE_WALLETS` to be configured. Without it, the workspace falls back to displaying 48h activity data from `DUNE_QUERY_48H_ACTIVE_WALLETS` only. The full heatmap grid is not available in fallback mode.
</Warning>

While Dune data loads, the activity section shows a skeleton heatmap grid with the label "Indexing scheduled wallet activity." and a `syncing` badge. The full grid renders once the scheduled query response is available.

<AccordionGroup>
  <Accordion title="Expected Dune row fields (16 columns)" icon="table">
    `address`, `label`, `category`, `tx_count_48h`, `unique_receivers_48h`, `usd_volume_48h`, `last_seen`, `activity_tier`, `activity_day`, `week_number`, `day_of_week`, `tx_count_day`, `unique_receivers_day`, `usd_volume_day`, `intensity_score`, `day_activity_tier`
  </Accordion>
</AccordionGroup>

## Adversarial signals

Adversarial signals are behavioral exposure heuristics derived from wallet transaction history and the 12-week Dune activity data. They are computed by the behavioral-signals engine.

These are deterministic, explainable heuristics. They are not findings of wrongdoing and do not imply intent, identity, or legal status.

<Tabs>
  <Tab title="Extraction-style activity">
    **Signal key:** `extractionStyleActivityRisk`

    A single large outgoing movement dominates observed outgoing volume.
  </Tab>

  <Tab title="Counterparty concentration">
    **Signal key:** `counterpartyConcentrationRisk`

    Activity is concentrated among one or very few counterparties.
  </Tab>

  <Tab title="Relay routing exposure">
    **Signal key:** `relayRoutingExposure`

    Incoming value is closely followed by outgoing value to different addresses.
  </Tab>

  <Tab title="Activity ramp">
    **Signal key:** `activityRampRisk`

    Recent on-chain activity is sharply elevated relative to a prior baseline.
  </Tab>

  <Tab title="Asset/value ambiguity">
    **Signal key:** `assetValueAmbiguityRisk`

    Token or value fields are ambiguous, missing, or unverifiable.
  </Tab>
</Tabs>

Each signal carries:

* `score` (0.0–1.0)
* `confidence` — reflects data completeness, not accusatory certainty
* `reason` — observation language only ("resembles", "may indicate", "increases exposure")
* `evidence` — the underlying on-chain data fields that produced the score

Signals with `score < 0.3` are computed but not displayed. When no signal meets the rendering threshold, the UI shows a low-noise empty state.

## Narrative engine

Narrative cards are produced by the narrative engine. The engine converts `WalletSignal[]` facts from the signal engine into structured `NarrativeCard` objects.

The narrative engine is deterministic — it templates from signal evidence fields and never invents numbers, protocols, or chains. An optional AI layer may rewrite the prose but must leave evidence values unchanged.

<Info>
  AI narrative generation is optional. If no AI provider key (`OPENROUTER_API_KEY`, `OPENAI_API_KEY`, or `ANTHROPIC_API_KEY`) is configured, the workspace displays template-based narratives only.
</Info>

Each narrative card shows:

* Headline (≤120 characters, derived from primary signal evidence)
* Body and key points
* Data source badges with freshness information
* Confidence level and caveats

## Wallet Holdings Strip

The Wallet Holdings Strip displays the wallet's token portfolio — either as balance-denominated positions or as trading exposure — depending on the Dune query shape configured.

<Warning>
  The Wallet Holdings Strip requires `DUNE_QUERY_WALLET_PORTFOLIO` to be configured. Wallets not present in the query result set silently show no holdings strip (`inDataset: false`).
</Warning>

Two query shapes are supported automatically:

| Shape                       | Required columns                                                                                      |
| --------------------------- | ----------------------------------------------------------------------------------------------------- |
| Option A (balance)          | `wallet_address`, `token_symbol`, `token_address`, `balance`, `balance_usd`                           |
| Option B (trading exposure) | `wallet_address`, `token_symbol`, `token_address`, `total_traded_usd`, `trade_count`, `last_trade_at` |

## Protocol Affinity Bar

The Protocol Affinity Bar shows the fraction of the wallet's on-chain volume that flowed through each DeFi protocol (Uniswap, Aave, Curve, etc.). It is derived from the baseline and live event data assembled by the signal engine.

## Quantum section

The Quantum Exposure section in Whale Watcher renders two cards stacked vertically:

* **Quantum Exposure Card** — composite score ring, per-component breakdown, behavioral signals, source caveats, and the policy simulator.
* **Quantum Vault Readiness Card** — recovery readiness signals, dormancy feed findings, and the **Migration Path panel**. The migration path is derived at render time by the migration-readiness recommender using the wallet's exposure score, value at risk, dormancy, and wallet structure. It recommends one of: `monitor`, `fresh-wallet`, `split-wallet`, `multisig`, `treasury-custody`, or `vault-prototype`. When `vault-prototype` is recommended, the panel surfaces a vault candidate row and the WalletWall Vault research disclosure automatically.

See [Quantum Intelligence](/features/quantum-intelligence) for the full score specification, migration path table, and approved framing.

## Signal engine dependency

Whale Watcher depends on the signal engine to produce `WalletSignal[]` facts before narratives and the Protocol Affinity Bar can be rendered. The signal engine requires:

* A `HistoricalWalletBaseline` from the Dune scheduled query (may be `null` — signals degrade gracefully)
* Live wallet events from Alchemy or Etherscan

See [Signal Engine](/architecture/signal-engine) for the full taxonomy and confidence rules.

## Related

<Columns cols={2}>
  <Card title="Holder Wall" icon="chart-tree-map" href="/features/holder-wall">
    Ownership map and holder analytics — treemap, leaderboard, and wallet drawer.
  </Card>

  <Card title="Quantum Intelligence" icon="atom" href="/features/quantum-intelligence">
    The full Quantum Exposure Score specification, migration path table, and approved framing behind the Quantum Exposure section.
  </Card>

  <Card title="Signal Engine" icon="wave-square" href="/architecture/signal-engine">
    The deterministic fact layer that produces `WalletSignal[]` from Dune baselines and live wallet events.
  </Card>

  <Card title="Stablecoin Vault & Vault Simulator" icon="vault" href="/features/vault">
    The vault-readiness review that Whale Watcher's signals feed into.
  </Card>
</Columns>