​

Key Management & Recovery Model

Status: Design model + non-custodial guardrails. This document defines the rules the next phase (private-key management and recovery UX) must follow. The current implementation is read-only orchestration only — no key handling, no recovery writes.

WalletWall is a wallet intelligence product. As we move toward helping users act on what they see — rotating keys, configuring recovery, migrating to recovery-aware accounts — we are writing down the non-negotiable boundaries first, so every later feature can be checked against them.

​

Non-custodial guarantees (hard rules)

These are invariants. Code, tests, and copy must never contradict them.

1. WalletWall never stores private keys. Not in the browser, not on a server, not in a database, not in logs.
2. WalletWall never asks for a seed phrase. There is no input, modal, paste target, or API that accepts mnemonic/seed material. Ever.
3. All signing happens through the user’s own wallet provider or a smart account module. WalletWall constructs unsigned, inspectable intents; the wallet (or smart-account validator) signs. WalletWall holds no signing authority.
4. No custodial flows. WalletWall never takes possession, control, or discretionary authority over user funds.
5. Every sensitive flow requires explicit user intent. No silent, batched, or “convenience” actions that move value or change security-critical configuration without a clear, per-action confirmation by the user.

​

Recovery must be one of these shapes

When recovery is implemented, it must be contract-based, guardian-based, passkey-assisted, or MPC-based — never custodial:

• Contract-based — recovery logic lives in a smart account the user owns (e.g. a social-recovery or modular smart account). WalletWall facilitates; the contract enforces.
• Guardian-based — a set of trusted guardians can approve recovery. No single guardian (and certainly not WalletWall) can recover alone.
• Passkey-assisted — device passkeys / WebAuthn provide a second factor or signer, removing the “seed phrase to lose” failure mode.
• MPC-based — signing key is split into shares so no single location holds a complete key.

​

Required properties of any recovery flow

Every recovery (and any security-critical configuration change) must include:

• Simulation first. The user can preview exactly what will happen — which account, which guardians, which timelock — before anything is submitted.
• Timelock. Security-critical actions are delayed, giving the real owner a window to notice and react.
• Cancellation. The owner can cancel a pending recovery/withdrawal during the timelock window.
• Auditability. Every step emits an inspectable, on-chain (or verifiable) record. No hidden state transitions.
• Explicit intent at each step. See hard rule #5.

​

Post-quantum verifier status

The WalletWall Vault prototype models a hybrid classical + post-quantum authorization flow (ML-DSA / FIPS 204, with related SLH-DSA / FIPS 205 research). The on-chain post-quantum verifier hooks are experimental / prototype only and must not be relied upon unless and until independently audited. No copy may claim quantum-proof, quantum-secure, or guaranteed quantum resistance.

​

How the orchestration layer enforces this today

The Wallet Security Orchestration Layer (src/lib/wallet-security/) is the read-only foundation the recovery phase builds on. It:

• Classifies a wallet into a single shared WalletSecurityState (unknown, safe-monitor, signature-exposed, high-value-exposed, dormant-high-value, migration-ready, vault-candidate, recovery-needed) via classifyWalletSecurityState.
• Evaluates vault eligibility (evaluateVaultEligibility) — eligible, recommendedPath, reason, blockers, requiredActions, user-facing disclosure, and developer notes.
• Classifies recovery readiness (classifyRecoveryReadiness) into one of not-applicable, monitor-only, should-rotate, should-migrate-multisig, should-migrate-smart-vault, should-configure-recovery, needs-urgent-migration.
• Reuses existing utilities (quantum-exposure, migration-readiness, quantum-vault-readiness) rather than re-scoring, and performs no writes, no signing, and no key handling.

buildWalletSecurityProfile() unifies the three into one profile and recommends which Vault-route view to show:

​

What remains before implementing private-key management & recovery

• No real recovery writes exist yet; classification is advisory only.
• Wallet connection in the Vault dashboard does not yet run a security scan for the connected address (connected-state classification is conservative until it does).
• Smart-account / guardian module integration, passkey, and MPC paths are design targets, not implementations.
• The post-quantum verifier remains unaudited and experimental.

Until those land, all recovery surfaces stay planning guidance — clearly labelled, non-alarmist, and bound by the hard rules above.