Architecture Decisions (ADRs)

Short, focused records of wallet-critical architecture and security decisions. Use these ADRs to understand why the system looks the way it does today.

What is an ADR?

Architectural Decision Records (ADRs) capture important technical decisions, their context, trade-offs, and consequences. They live alongside the code in the monorepo so contributors and reviewers can track how the design has evolved over time.

All ADRs for the extension + @keetanetwork/wallet-core live under docs/adr/ in the Keythings Wallet monorepo.

Current ADRs

  • ADR 001 — Wallet Secret Storage and IndexedDB Boundaries
    Documents how mnemonics and seeds are wrapped by the secure-store module using Argon2id + AES-GCM, stored in an IndexedDB database, and kept separate from non-secret state like history and UI metadata.
    docs/adr/001-storage-secrets-and-indexeddb.md
  • ADR 002 — Network Provider Selection and Mapping
    Explains the separation between user-facing networks (KeetaNetworkName = 'test' | 'main') and SDK networks (KeetaSdkNetwork), and why all mappings flow throughmapNetworkToSDK.
    docs/adr/002-network-provider-selection.md
  • ADR 003 — Permission and Capability Model for dApps
    Describes the KeetaCapability = 'read' | 'sign' | 'transact' | 'network' model, origin-scoped capability tokens, and how RPCs are guarded by capabilities + approvals.
    docs/adr/003-permission-and-capability-model.md

Template

To propose a new ADR, copy the template and increment the number:

docs/adr/000-template.md

Keep ADRs short and focused. Link to relevant PRs, design docs, and Keeta knowledge base pages instead of duplicating them.

When to add or update an ADR

  • Changing how secrets are stored, derived, or unlocked.
  • Adding or deprecating wallet RPCs or capability types.
  • Reworking MV3 entrypoints or message contracts between inpage/content/background.
  • Introducing new network environments or changing provider selection rules.

Minor refactors or implementation details usually do not need an ADR; substantial behaviour or trust boundary changes should have one.

6 of 33