sal-modular/docs/architecture.md

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
• Crate and Module Structure
• Design Rationale
• Vault Crate Design
• Async, WASM, and Integration
• 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.