Skip to main content

​
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

Never stores private keys

WalletWall never stores private keys. Not in the browser, not on a server, not in a database, not in logs.
2

Never asks for a seed phrase

WalletWall never asks for a seed phrase. There is no input, modal, paste target, or API that accepts mnemonic/seed material. Ever.
3

Signing happens in the user's own wallet

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

No custodial flows. WalletWall never takes possession, control, or discretionary authority over user funds.
5

Explicit intent required

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:
Recovery logic lives in a smart account the user owns (e.g. a social-recovery or modular smart account). WalletWall facilitates; the contract enforces.

​
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 is the read-only foundation the recovery phase builds on. It reuses the existing quantum-exposure, migration-readiness, and quantum-vault-readiness scoring rather than re-scoring, and performs no writes, no signing, and no key handling.
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).
Evaluates vault eligibility — eligible, recommendedPath, reason, blockers, requiredActions, user-facing disclosure, and developer notes.
Classifies recovery readiness into one of not-applicable, monitor-only, should-rotate, should-migrate-multisig, should-migrate-smart-vault, should-configure-recovery, needs-urgent-migration.
The wallet-security profile builder unifies the three into one profile and recommends which Vault-route view to show: The recovery-needed / needs-urgent-migration path is the only one that routes to the Recovery planning panel — every other connection state routes to monitoring, review, or dashboard guidance.

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