Feat: simplify vault API and update docs

docs/architecture.md

@@ -0,0 +1,79 @@
+# Architecture Overview
+
+This document describes the architecture and design rationale for the modular Rust system, including the `kvstore`, `vault`, and `evm_client` crates, as well as the CLI and WASM/web-app targets.
+
+## Table of Contents
+- [Summary](#summary)
+- [Crate and Module Structure](#crate-and-module-structure)
+- [Design Rationale](#design-rationale)
+- [Vault Crate Design](#vault-crate-design)
+- [Async, WASM, and Integration](#async-wasm-and-integration)
+- [Diagrams & References](#diagrams--references)
+
+---
+
+## Summary
+This system is organized as a Rust workspace with three core crates:
+- `kvstore`: Abstract, async key-value storage for both native and WASM environments.
+- `vault`: Manages encrypted keyspaces and cryptographic operations, using `kvstore` for persistence.
+- `evm_client`: Ethereum RPC client, signs transactions using keys from `vault`.
+
+Front-end targets:
+- CLI (with Rhai scripting)
+- WASM/web-app (with JS interop)
+
+---
+
+## Crate and Module Structure
+- **Workspace:** Top-level `Cargo.toml` lists all member crates.
+- **Features & cfg:** Use Cargo features and `#[cfg]` attributes for platform-specific code (e.g., `sled` for native, `idb` for WASM).
+- **Dependencies:**
+  - `kvstore` uses `sled` (native) and `idb` (WASM).
+  - `vault` uses `kvstore` and crypto crates (`chacha20poly1305`, `pbkdf2`, etc.).
+  - `evm_client` uses `vault` and Ethereum libraries (e.g., `alloy`).
+  - CLI uses Rhai and async runtime (e.g., Tokio).
+  - Web app uses `wasm-bindgen` and exposes Rust APIs to JS.
+
+---
+
+## Design Rationale
+### Improvements in the New Implementation
+- **Async/Await API:** All operations are async, supporting non-blocking I/O for both WASM and native environments.
+- **Backend Abstraction:** The `KVStore` trait abstracts over multiple storage backends, enabling cross-platform support and easier testing.
+- **Separation of Concerns:**
+  - `kvstore` handles only storage.
+  - `vault` is responsible for encryption, decryption, and password management.
+- **WASM and Native Support:** Out-of-the-box support for both browser (IndexedDB) and native (sled) environments.
+- **Cleaner, Testable Design:** Each layer is independently testable and mockable.
+
+### Why Encryption and Password Protection are in Vault
+- **Single Responsibility:** `kvstore` is for storage; `vault` handles security.
+- **Flexibility:** Encryption algorithms and policies can evolve in `vault` without changing storage.
+- **Security:** Cryptography is isolated in `vault`, reducing attack surface and easing audits.
+- **Cross-Platform Consistency:** Same vault logic regardless of storage backend.
+
+---
+
+## Vault Crate Design
+- **Encrypted Keyspace:** Password-protected, supports multiple keypairs (e.g., secp256k1, Ed25519).
+- **Crypto APIs:** Async functions for key management, signing, encryption/decryption.
+- **Storage:** Uses `kvstore` for persistence; re-encrypts and stores the keyspace as a blob.
+- **WASM Compatibility:** Uses Rust crypto crates that support `wasm32-unknown-unknown`.
+
+---
+
+## Async, WASM, and Integration
+- **Exports:** Use `#[wasm_bindgen]` to expose async functions to JS.
+- **Async runtime:** Use `wasm_bindgen_futures::spawn_local` in the browser.
+- **Interop:** JS and Rust communicate via Promises and `JsValue`.
+- **CLI:** Uses Rhai scripting and async runtime.
+
+---
+
+## Diagrams & References
+- See included diagrams for crate relationships and message-passing patterns.
+- Design patterns and best practices are drawn from Rust async and WASM guidelines.
+
+---
+
+*This document merges and replaces content from the previous `Architecture.md` and `kvstore-vault-architecture.md`. For further details on implementation, see `vault_impl_plan.md`.*