80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
# 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`.*
|