​

Wallet Risk Report Model

​

Three report-shaped objects — do not confuse them

​

Schema shape

WalletRiskReport {
  reportType: 'walletwall.wallet-risk-report'
  reportVersion: 'v1'
  subject: { address, chain }
  generatedAt: string | null          // caller-supplied; the model never reads a clock
  modelVersions: { ... }              // which composed pipeline produced each dimension
  status: 'assessed' | 'insufficient_evidence'
  overall: {
    riskTier: TIER_KEYS.* | null      // risk-tiers.js — no new tier taxonomy
    riskTierLabel: string | null
    recommendation: RECOMMENDATION_KEYS.*
    compositeScoreNote: string        // explicit "no single composite score" statement
  }
  dimensions: {
    quantum: Dimension
    concentration: Dimension
    dormancyActivity: Dimension
    behavior: Dimension
  }
  evidenceConfidence: { overall, scorable, reasons, perDimension }
  dataSources: [{ id, type, freshness, queryRunAt, cachedAt }]
  missingEvidence: string[]
  riskDrivers: string[]               // RISK_DRIVER_KEYS values only
  recommendedNextActions: string[]    // deterministic, read-only-verb copy
  boundaries: { custodyClaim: false, yieldClaim: false, insuranceClaim: false, quantumProofClaim: false, productionVaultClaim }
  disclaimers: string[]               // non-strippable; always non-empty
  narrative: null                     // ALWAYS null in v1 — see "AI narrative" below
}

Dimension {
  status: 'observed' | 'partial' | 'unknown'
  confidence: 'high' | 'medium' | 'low'
  scorable: boolean
  reasonCodes: string[]               // src/lib/wallet-evidence/evidence-quality.js SCORING_REASON_CODES
  source: string                      // which existing module/function produced this
  value: object | null
}

​

What each dimension actually is

​

The overall readiness tier

​

Deterministic vs. inferred vs. unavailable

​

Honesty rules (enforced by tests)

• Unknown is never zero. A dimension with no evidence reports status: 'unknown', not a fabricated 'monitor'/0/false.
• Stale/conflicting evidence lowers confidence, not necessarily severity. A stale Dune dormancy fact downgrades dimensions.dormancyActivity.confidence, but does not by itself change overall.riskTier.
• If nothing can be honestly assessed, the report says so structurally — status: 'insufficient_evidence', overall.riskTier: null, overall.recommendation: 'unsupported' — never a fabricated tier.
• The client cannot inject any computed field. The read-only API (GET /api/wallet-risk-report?address=0x…) never reads a request body, and the only client-controlled input is the wallet address itself.
• Dune data is never described as live. dataSources[].type distinguishes dune_scheduled from live_provider; the app-wide Dune spend-path rules (docs/operations/dune-spend-path-controls.md) apply unchanged — this endpoint only reads Dune’s cache, never executes or reads live results.
• Mock/demo data is never served as a real report. Unlike /api/wallet, this endpoint does not fall back to mockWalletProvider when no live provider key is configured — the concentration and behavior dimensions honestly degrade to unknown instead.
• The report can never read more confident than the canonical Whale Watcher page for the same wallet snapshot. dimensions.behavior.confidence is capped by the SAME evaluateWhaleInvariants/resolveWhaleConfidence composition WhaleWatcher.jsx’s buildLedgerProps applies — a cross-domain invariant failure (an internally contradictory priced-movement sample) marks status: 'partial' and surfaces INVARIANT_FAILED in reasonCodes, the same way it would show a data-quality warning on the live page (see AUDIT-WALLET-RISK-WHALE-BYPASS in data-foundation-audit.md). This is enforced for every consumer built on top of the report — CSV/JSON export, Portfolio Assessment, and the /api/analyze narrative payload (which withholds transferVolumeUsd/netFlowUsd rather than sending an invariant-tainted figure to the AI provider as if it were trustworthy).

​

Deferred work (intentional v1 scope)

• Quantum Exposure Score pipeline (deriveWalletSignatureExposure → deriveQuantumExposureScore). That pipeline has never been server-composed anywhere in this codebase; wiring it here would mean writing new composition logic rather than reusing an existing one. v1 composes the already fully server-composed Quantum Vault Readiness pipeline instead.
• Dune 12-week Whale Watcher cohort baseline. The behavior dimension currently relies only on live wallet transactions (when a provider key is configured) for its baseline; most report subjects are outside the curated 12-week active-wallet cohort anyway.
• ENS resolution. The endpoint requires a raw 0x address; resolve via /api/resolve-wallet first.
• Report persistence, cryptographic signing, or a database. Every call still recomputes the report fresh from current cache/live state. A client-only, unsigned content-hash share/export lane exists (src/lib/wallet-risk-report-share.js) — it is integrity-only (detects tampering with the shared payload), not authenticity/signed, mirroring how the UI’s own integrity badge and share controls describe it. This is distinct from the Readiness Packet’s cryptographically signed sharing.
• Portfolio / multi-wallet batching.

​

Related