# 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`](docs/rhai_architecture_plan.md))

## 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

## Building and Testing

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

### Native Build & Test
```sh
cargo build
cargo test
```

### Browser (WASM) Tests
Run all browser tests for all modules:
```sh
make test-browser-all
```
Or run for a specific module:
```sh
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`](docs/rhai_architecture_plan.md))
- **Browser extension**: Planned support for browser extension scripting and secure key usage

## Documentation
- [Architecture Overview](docs/architecture.md)
- [EVM Client Plan](docs/evm_client_architecture_plan.md)
- [Rhai Scripting Plan](docs/rhai_architecture_plan.md)

---

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
```sh
cargo check --workspace --features kvstore/native
```

### WASM (kvstore only)
```sh
cd kvstore
wasm-pack test --headless --firefox --features web
```

# Rhai Scripting System

A unified system for writing and executing [Rhai](https://rhai.rs/) 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
- [x] Unified async trait for key-value storage
- [x] Native and WASM backends for kvstore
- [x] 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