Modular Rust System: Key-Value Store, Vault, and EVM Client

A modular, async, and cross-platform cryptographic stack in Rust. Built for both native (desktop/server) and WASM (browser) environments, this system provides secure storage, cryptographic operations, and Ethereum (EVM) client functionality—all with a focus on extensibility, testability, and scripting.

Crate Overview

• kvstore/: Async key-value store trait and implementations (native: sled, WASM: IndexedDB)
• vault/: Cryptographic vault for encrypted keyspaces, key management, and signing; uses kvstore for persistence
• evm_client/: Async EVM RPC client, integrates with vault for secure signing; supports trait-based signers and modular providers
• cli_app/ (planned): Command-line interface for scripting, automation, and Rhai scripting
• web_app/ (planned): WASM web app exposing APIs to JavaScript/browser scripting
• wasm/ (planned): WebAssembly module for browser/extension integration
• browser_extension/ (planned): Browser extension for secure scripting and automation
• rhai scripting (planned): Unified scripting API for both CLI and browser (see docs/rhai_architecture_plan.md)

---

What is Rust Conditional Compilation?

Rust's conditional compilation allows you to write code that only gets included for certain platforms or configurations. This is done using attributes like #[cfg(target_arch = "wasm32")] for WebAssembly, or #[cfg(not(target_arch = "wasm32"))] for native platforms. It enables a single codebase to support multiple targets (such as desktop and browser) with platform-specific logic where needed.

Example:

#[cfg(target_arch = "wasm32")]
// This code only compiles for WebAssembly targets

What is WASM (WebAssembly)?

WebAssembly (WASM) is a binary instruction format for a stack-based virtual machine. It allows code written in languages like Rust, C, or C++ to run at near-native speed in web browsers and other environments. In this project, WASM enables the cryptographic vault to work securely inside the browser, exposing Rust functions to JavaScript and web applications.

---

Directory Structure

Note: Some directories are planned for future extensibility and scripting, and may not exist yet in the current workspace.

.
├── kvstore/            # Key-value store trait and backends
├── vault/              # Cryptographic vault (shared core)
├── evm_client/         # EVM RPC client (shared core)
├── cli_app/            # Command-line tool for Rhai scripts (planned)
├── web_app/            # WASM web app exposing APIs (planned)
├── wasm/               # WebAssembly module for browser/extension (planned)
├── browser_extension/  # Extension source (planned)
├── docs/               # Architecture & usage docs
└── README.md

Architecture Highlights

• Modular and async: All APIs are async and runtime-agnostic (works with both native and WASM targets)
• Conditional backends: Uses Cargo features and cfg for platform-specific storage/networking
• Secure by design: Vault encrypts all key material at rest using modern cryptography
• Extensible: Trait-based APIs for signers and providers, ready for scripting and new integrations
• Tested everywhere: Native and browser (WASM) backends are covered by automated tests and a unified Makefile

---

Conditional Compilation & WASM Support

This project makes extensive use of Rust's conditional compilation to support both native and WebAssembly (WASM) environments with a single codebase. Key points:

• Platform-specific code:

  • Rust's #[cfg(target_arch = "wasm32")] attribute is used to write WASM-specific code, while #[cfg(not(target_arch = "wasm32"))] is for native targets.
  • This pattern is used for struct definitions, method implementations, and even module imports.

• Example: SessionManager

  #[cfg(not(target_arch = "wasm32"))]
  pub struct SessionManager<S: KVStore + Send + Sync> { ... }
  
  #[cfg(target_arch = "wasm32")]
  pub struct SessionManager<S: KVStore> { ... }
  

• WASM Bindings:

  • The wasm_app crate uses wasm-bindgen to expose Rust functions to JavaScript, enabling browser integration.
  • Functions are annotated with #[wasm_bindgen] and exported for use in JS/TS.

• Storage Backends:

  • Native uses sled or other file-based stores.
  • WASM uses IndexedDB (via kvstore::wasm::WasmStore).

• Building for WASM:

  • Use wasm-pack build --target web to build the WASM package.
  • Serve the resulting files with a static server for browser use.

• Testing:

  • Both native and WASM tests are supported. WASM tests can be run in headless browsers using wasm-pack test --headless --firefox or similar commands.

---

Building and Testing

Prerequisites

• Rust (latest stable recommended)
• wasm-pack (for browser tests)
• Firefox or Chrome (for browser testing)

Native Build & Test

cargo build
cargo test

Browser (WASM) Tests

Run all browser tests for all modules:

make test-browser-all

Or run for a specific module:

make test-browser-kvstore
make test-browser-vault
make test-browser-evm-client

Set BROWSER=chrome to use Chrome instead of Firefox.

Scripting & Extensibility

• Rhai scripting: The architecture is ready for ergonomic scripting via Rhai, both in CLI and browser (see docs/rhai_architecture_plan.md)
• Browser extension: Planned support for browser extension scripting and secure key usage

Documentation

• Architecture Overview
• EVM Client Plan
• Rhai Scripting Plan

---

For questions, contributions, or more details, see the architecture docs or open an issue!

• Rust (latest stable recommended)
• For WASM: wasm-pack, Firefox or Chrome (for browser tests)

Native

cargo check --workspace --features kvstore/native

WASM (kvstore only)

cd kvstore
wasm-pack test --headless --firefox --features web

Rhai Scripting System

A unified system for writing and executing Rhai scripts, powered by shared Rust core logic. Supports both local CLI execution and secure browser extension use, with the same business logic compiled to WebAssembly.

---

Project Goals

• Write and run Rhai scripts both locally (CLI) and in the browser (extension).
• Reuse the same Rust core logic (vault, evm_client) across all platforms.
• Sandboxed, secure script execution in both native and WASM environments.

---

Architecture Overview

• Shared Rust Crates:
  • vault/ and evm_client/ implement business logic and expose APIs to Rhai.
  • All logic is reusable in both native and WASM builds.
• CLI Tool (cli/):
  • Runs Rhai scripts from files or stdin using the shared core.
  • Outputs results to the terminal.
• WebAssembly Module (wasm/):
  • Exposes run_rhai(script: &str) -> String via wasm-bindgen.
  • Usable from browser JS and the extension.
• Browser Extension (browser_extension/):
  • UI for entering and running Rhai scripts securely in the browser.
  • Loads the WASM module and displays results.
• Web App Integration:
  • Trusted web apps can send scripts to the extension for execution (via postMessage or WebSocket, with strict origin checks).

---

Usage

CLI

sal-cli run my_script.rhai
# or
cat my_script.rhai | sal-cli run

Browser/Extension

• Enter Rhai code in the extension popup or trusted website.
• Extension loads the WASM module and calls run_rhai(script).
• Result is displayed in the UI.

---

Security

• All script execution is sandboxed via Rhai + WASM.
• Only accepts input from:
  • Extension popup UI
  • Approved websites (via content script)
  • Trusted backend server (if using WebSocket)
• Strict origin and input validation.
• No internal APIs exposed beyond run_rhai(script).

---

Directory Structure

.
├── kvstore/      # Key-value store trait and backends
├── vault/        # Cryptographic vault (shared core)
├── evm_client/   # EVM RPC client (shared core)
├── cli/          # Command-line tool for Rhai scripts
├── wasm/         # WebAssembly module for browser/extension
├── browser_extension/  # Extension source
├── docs/         # Architecture & usage docs
└── README.md

---

Roadmap

• Unified async trait for key-value storage
• Native and WASM backends for kvstore
• Shared Rust core for vault and evm_client
• WASM module exposing run_rhai
• CLI tool for local Rhai script execution
• Browser extension for secure script execution
• Web app integration (postMessage/WebSocket)
• Full end-to-end integration and security review

---

License

MIT OR Apache-2.0