feat: Add SessionManager for ergonomic key management

2025-05-16 00:15:07 +03:00
parent 791752c3a5
commit 73233ec69b
10 changed files with 870 additions and 4 deletions
--- a/docs/evm_client_architecture_plan.md
+++ b/docs/evm_client_architecture_plan.md
@@ -0,0 +1,188 @@
+# EVM Client Architecture & Implementation Plan
+
+## Project Goal
+Build a cross-platform (native + WASM) EVM client that can:
+- Interact with multiple EVM-compatible networks/providers
+- Use pluggable signing backends (e.g., SessionManager, hardware wallets, mocks)
+- Integrate seamlessly with Rhai scripting and the rest of the modular Rust workspace
+
+---
+
+## Requirements & Principles
+- **Async, modular, and testable**: All APIs are async and trait-based
+- **Cross-platform**: Native (Rust) and WASM (browser) support
+- **Multi-network**: Support for multiple EVM networks/providers, switchable at runtime
+- **Pluggable signing**: No direct dependency on vault/session; uses a generic Signer trait
+- **Consistency**: Follows conventions in architecture.md and other project docs
+- **Scripting**: Exposes ergonomic API for both Rust and Rhai scripting
+
+---
+
+## Recommended File Structure
+
+```
+evm_client/
+├── Cargo.toml
+└── src/
+    ├── lib.rs           # Public API
+    ├── provider.rs      # EvmProvider abstraction
+    ├── client.rs        # EvmClient struct
+    ├── signer.rs        # Signer trait
+    └── utils.rs         # Helpers (e.g., HTTP, WASM glue)
+```
+
+---
+
+## 1. Pluggable Signer Trait
+
+```rust
+// signer.rs
+#[async_trait::async_trait]
+pub trait Signer {
+    async fn sign(&self, message: &[u8]) -> Result<Vec<u8>, EvmError>;
+    fn address(&self) -> String;
+}
+```
+
+- `SessionManager` in vault implements this trait.
+- Any other backend (mock, hardware wallet, etc.) can implement it.
+
+---
+
+## 2. EvmProvider Abstraction
+
+```rust
+// provider.rs
+pub enum EvmProvider {
+    Http { name: String, url: String, chain_id: u64 },
+    // Future: WebSocket, Infura, etc.
+}
+
+impl EvmProvider {
+    pub async fn send_raw_transaction<S: Signer>(&self, tx: &Transaction, signer: &S) -> Result<TxHash, EvmError> {
+        let raw_tx = tx.sign(signer).await?;
+        let body = format!("{{\"raw\":\"{}\"}}", hex::encode(&raw_tx));
+        match self {
+            EvmProvider::Http { url, .. } => {
+                http_post(url, &body).await
+            }
+        }
+    }
+}
+```
+
+---
+
+## 3. EvmClient Struct & API
+
+```rust
+// client.rs
+use std::collections::HashMap;
+
+pub struct EvmClient<S: Signer> {
+    providers: HashMap<String, EvmProvider>,
+    current: String,
+    signer: S,
+}
+
+impl<S: Signer> EvmClient<S> {
+    pub fn new(signer: S) -> Self {
+        Self {
+            providers: HashMap::new(),
+            current: String::new(),
+            signer,
+        }
+    }
+    pub fn add_provider(&mut self, key: String, provider: EvmProvider) {
+        self.providers.insert(key, provider);
+    }
+    pub fn set_current(&mut self, key: &str) -> Result<(), EvmError> {
+        if self.providers.contains_key(key) {
+            self.current = key.to_string();
+            Ok(())
+        } else {
+            Err(EvmError::UnknownNetwork)
+        }
+    }
+    pub fn current_provider(&self) -> Option<&EvmProvider> {
+        self.providers.get(&self.current)
+    }
+    pub async fn send_transaction(&self, tx: Transaction) -> Result<TxHash, EvmError> {
+        let provider = self.current_provider().ok_or(EvmError::NoNetwork)?;
+        provider.send_raw_transaction(&tx, &self.signer).await
+    }
+}
+```
+
+---
+
+## 4. Cross-Platform Networking (Native + WASM)
+
+```rust
+// utils.rs
+pub async fn http_post(url: &str, body: &str) -> Result<TxHash, EvmError> {
+    #[cfg(not(target_arch = "wasm32"))]
+    {
+        let resp = reqwest::Client::new().post(url).body(body.to_owned()).send().await?;
+        // parse response...
+        Ok(parse_tx_hash(resp.text().await?))
+    }
+    #[cfg(target_arch = "wasm32")]
+    {
+        let resp = gloo_net::http::Request::post(url).body(body).send().await?;
+        // parse response...
+        Ok(parse_tx_hash(resp.text().await?))
+    }
+}
+```
+
+---
+
+## 5. Rhai Scripting Integration
+
+```rust
+// rhai_bindings.rs
+pub fn register_rhai_api(engine: &mut Engine) {
+    engine.register_type::<EvmClient<MySigner>>();
+    engine.register_fn("add_network", EvmClient::add_provider);
+    engine.register_fn("switch_network", EvmClient::set_current);
+    engine.register_fn("send_tx", EvmClient::send_transaction);
+}
+```
+
+---
+
+## 6. Usage Example
+
+```rust
+use evm_client::{EvmClient, EvmProvider, Signer};
+use vault::SessionManager;
+
+let mut client = EvmClient::new(session_manager);
+client.add_provider("mainnet".into(), EvmProvider::Http { name: "Ethereum Mainnet".into(), url: "...".into(), chain_id: 1 });
+client.add_provider("polygon".into(), EvmProvider::Http { name: "Polygon".into(), url: "...".into(), chain_id: 137 });
+client.set_current("polygon")?;
+let tx_hash = client.send_transaction(tx).await?;
+```
+
+---
+
+## 7. Compliance & Consistency
+- **Async/trait-based**: Like kvstore/vault, all APIs are async and trait-based
+- **No direct dependencies**: Uses generic Signer, not vault/session directly
+- **Cross-platform**: Uses conditional networking for native/WASM
+- **Modular/testable**: Clear separation of provider, client, and signer logic
+- **Rhai scripting**: Exposes ergonomic scripting API
+- **Follows architecture.md**: Modular, layered, reusable, and extensible
+
+---
+
+## 8. Open Questions / TODOs
+- How to handle provider-specific errors and retries?
+- Should we support WebSocket providers in v1?
+- What subset of EVM JSON-RPC should be exposed to Rhai?
+- How to best test WASM networking in CI?
+
+---
+
+*Last updated: 2025-05-16*
--- a/docs/rhai_architecture_plan.md
+++ b/docs/rhai_architecture_plan.md
@@ -0,0 +1,341 @@
+# Rhai Scripting System Architecture & Implementation Plan
+
+## Project Goal
+
+Build a system that allows users to write and execute Rhai scripts both:
+- **Locally via a CLI**, and
+- **In the browser via a browser extension**
+
+using the same core logic (the `vault` and `evm_client` crates), powered by a Rust WebAssembly module.
+
+---
+
+## Requirements & Architecture
+
+### 1. Shared Rust Libraries
+- **Core Libraries:**
+  - `vault/`: Cryptographic vault and session management
+  - `evm_client/`: EVM RPC client
+- **Responsibilities:**
+  - Implement business logic
+  - Expose functions to the Rhai scripting engine
+  - Reusable in both native CLI and WebAssembly builds
+
+### 2. Recommended File Structure
+
+```
+rhai_sandbox_workspace/
+├── Cargo.toml              # Workspace manifest
+├── vault/                  # Shared logic + Rhai bindings
+│   ├── Cargo.toml
+│   └── src/
+│       ├── lib.rs          # Public API (all core logic)
+│       ├── rhai_bindings.rs# Rhai registration (shared)
+│       └── utils.rs        # Any helpers
+├── cli/                    # CLI runner
+│   ├── Cargo.toml
+│   └── src/
+│       └── main.rs
+├── wasm/                   # Wasm runner using same API
+│   ├── Cargo.toml
+│   └── src/
+│       └── lib.rs
+├── browser-extension/      # (optional) Extension frontend
+│   ├── manifest.json
+│   ├── index.html
+│   └── index.js
+```
+
+### 3. Code Organization for Shared Rhai Bindings
+
+**In `vault/src/lib.rs`:**
+```rust
+pub mod rhai_bindings;
+pub use rhai_bindings::register_rhai_api;
+
+pub fn fib(n: i64) -> i64 {
+    if n < 2 { n } else { fib(n - 1) + fib(n - 2) }
+}
+```
+
+**In `vault/src/rhai_bindings.rs`:**
+```rust
+use rhai::{Engine, RegisterFn};
+use crate::fib;
+
+pub fn register_rhai_api(engine: &mut Engine) {
+    engine.register_fn("fib", fib);
+}
+```
+
+**Using in CLI (`cli/src/main.rs`):**
+```rust
+use rhai::Engine;
+use vault::register_rhai_api;
+use std::env;
+use std::fs;
+
+fn main() {
+    let args: Vec<String> = env::args().collect();
+    if args.len() != 2 {
+        eprintln!("Usage: cli <script.rhai>");
+        return;
+    }
+    let script = fs::read_to_string(&args[1]).expect("Failed to read script");
+    let mut engine = Engine::new();
+    register_rhai_api(&mut engine);
+    match engine.eval::<i64>(&script) {
+        Ok(result) => println!("Result: {}", result),
+        Err(e) => eprintln!("Error: {}", e),
+    }
+}
+```
+
+**Using in WASM (`wasm/src/lib.rs`):**
+```rust
+use wasm_bindgen::prelude::*;
+use rhai::Engine;
+use vault::register_rhai_api;
+
+#[wasm_bindgen]
+pub fn run_rhai(script: &str) -> JsValue {
+    let mut engine = Engine::new();
+    register_rhai_api(&mut engine);
+    match engine.eval_expression::<i64>(script) {
+        Ok(res) => JsValue::from_f64(res as f64),
+        Err(e) => JsValue::from_str(&format!("Error: {}", e)),
+    }
+}
+```
+
+**Benefits:**
+- Single source of truth for Rhai bindings (`register_rhai_api`)
+- Easy to expand: add more Rust functions and register in one place
+- Works seamlessly across CLI and WASM
+- Encourages code reuse and maintainability
+
+**This approach fully adheres to the principles in `architecture.md`**:
+- Modular, layered design
+- Code reuse across targets
+- Shared business logic for both native and WASM
+- Clean separation of platform-specific code
+
+### 4. Native CLI Tool (`cli/`)
+- Accepts `.rhai` script file or stdin
+- Uses shared libraries to run the script via the Rhai engine
+- Outputs the result to the terminal
+
+### 5. WebAssembly Module (`wasm/`)
+- Uses the same core library for Rhai logic
+- Exposes a `run_rhai(script: &str) -> String` function via `wasm_bindgen`
+- Usable from browser-based JS (e.g., `import { run_rhai }`)
+
+### 4. Browser Extension (`browser_extension/`)
+- UI for user to enter Rhai code after loading keyspace and selecting keypair (using SessionManager)
+- Loads the WebAssembly module
+- Runs user input through `run_rhai(script)`
+- Displays the result or error
+- **Security:**
+  - Only allows script input from:
+    - Trusted websites (via content script injection)
+    - Extension popup UI---
+
+## EVM Client Integration: Pluggable Signer Pattern
+
+---
+
+## Cross-Platform, Multi-Network EvmClient Design
+
+To be consistent with the rest of the project and adhere to the architecture and modularity principles, the `evm_client` crate should:
+- Use async APIs and traits for all network and signing operations
+- Support both native and WASM (browser) environments via conditional compilation
+- Allow dynamic switching between multiple EVM networks/providers at runtime
+- Avoid direct dependencies on vault/session, using the pluggable Signer trait
+- Expose a clear, ergonomic API for both Rust and Rhai scripting
+
+### 1. EvmProvider Abstraction
+```rust
+pub enum EvmProvider {
+    Http { name: String, url: String, chain_id: u64 },
+    // Future: WebSocket, Infura, etc.
+}
+```
+
+### 2. EvmClient Struct
+```rust
+use std::collections::HashMap;
+
+pub struct EvmClient<S: Signer> {
+    providers: HashMap<String, EvmProvider>,
+    current: String,
+    signer: S,
+}
+
+impl<S: Signer> EvmClient<S> {
+    pub fn new(signer: S) -> Self {
+        Self {
+            providers: HashMap::new(),
+            current: String::new(),
+            signer,
+        }
+    }
+    pub fn add_provider(&mut self, key: String, provider: EvmProvider) {
+        self.providers.insert(key, provider);
+    }
+    pub fn set_current(&mut self, key: &str) -> Result<(), EvmError> {
+        if self.providers.contains_key(key) {
+            self.current = key.to_string();
+            Ok(())
+        } else {
+            Err(EvmError::UnknownNetwork)
+        }
+    }
+    pub fn current_provider(&self) -> Option<&EvmProvider> {
+        self.providers.get(&self.current)
+    }
+    pub async fn send_transaction(&self, tx: Transaction) -> Result<TxHash, EvmError> {
+        let provider = self.current_provider().ok_or(EvmError::NoNetwork)?;
+        provider.send_raw_transaction(&tx, &self.signer).await
+    }
+}
+```
+
+### 3. Provider Networking (Native + WASM)
+```rust
+impl EvmProvider {
+    pub async fn send_raw_transaction<S: Signer>(&self, tx: &Transaction, signer: &S) -> Result<TxHash, EvmError> {
+        let raw_tx = tx.sign(signer).await?;
+        let body = format!("{{\"raw\":\"{}\"}}", hex::encode(&raw_tx));
+        match self {
+            EvmProvider::Http { url, .. } => {
+                http_post(url, &body).await
+            }
+        }
+    }
+}
+
+// Cross-platform HTTP POST
+pub async fn http_post(url: &str, body: &str) -> Result<TxHash, EvmError> {
+    #[cfg(not(target_arch = "wasm32"))]
+    {
+        let resp = reqwest::Client::new().post(url).body(body.to_owned()).send().await?;
+        // parse response...
+        Ok(parse_tx_hash(resp.text().await?))
+    }
+    #[cfg(target_arch = "wasm32")]
+    {
+        let resp = gloo_net::http::Request::post(url).body(body).send().await?;
+        // parse response...
+        Ok(parse_tx_hash(resp.text().await?))
+    }
+}
+```
+
+### 4. Rhai Scripting Integration
+- Expose `add_network`, `switch_network`, and `send_tx` functions to the Rhai engine via the shared bindings pattern.
+- Example:
+```rust
+pub fn register_rhai_api(engine: &mut Engine) {
+    engine.register_type::<EvmClient<MySigner>>();
+    engine.register_fn("add_network", EvmClient::add_provider);
+    engine.register_fn("switch_network", EvmClient::set_current);
+    engine.register_fn("send_tx", EvmClient::send_transaction);
+}
+```
+
+### 5. Consistency and Compliance
+- **Async, modular, and testable:** All APIs are async and trait-based, just like kvstore/vault.
+- **No direct dependencies:** EvmClient is generic over signing backend, like other crates.
+- **Cross-platform:** Uses conditional compilation for networking, ensuring WASM and native support.
+- **Clear separation:** Network and signing logic are independent, allowing easy extension and testing.
+
+This design fits seamlessly with your project’s architecture and modularity goals.
+
+### 5. Web App Integration
+- Enable trusted web apps to send Rhai scripts to the extension, using one or both of:
+
+#### Option A: Direct (Client-side)
+- Web apps use `window.postMessage()` or DOM events
+- Extension listens via content script
+- Validates origin before running the script
+
+#### Option B: Server-based (WebSocket)
+- Both extension and web app connect to a backend WebSocket server
+- Web app sends script to server
+- Server routes it to the right connected extension client
+- Extension executes the script and returns the result
+
+### 6. Security Considerations
+- All script execution is sandboxed via Rhai + Wasm
+- Only allow input from:
+  - Extension popup
+  - Approved websites or servers
+- Validate origins and inputs strictly
+- Do not expose internal APIs beyond `run_rhai(script)`
+
+---
+
+## High-Level Component Diagram
+
+```
+-------------------+     +-------------------+
+|   CLI Tool        |     |  Browser Extension|
+|  (cli/)           |     |  (browser_ext/)   |
+---------+---------+     +---------+---------+
+          |                         |
+          |        +----------------+
+          |        |
+---------v---------+
+|   WASM Module     |   <--- Shared Rust Core (vault, evm_client)
+|   (wasm/)         |
+---------+---------+
+          |
+---------v---------+
+|  Rhai Engine      |
+-------------------+
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Core Library Integration
+- Ensure all business logic (vault & evm_client) is accessible from both native and WASM targets.
+- Expose required functions to Rhai engine.
+
+### Phase 2: CLI Tool
+- Implement CLI that loads and runs Rhai scripts using the shared core.
+- Add support for stdin and file input.
+
+### Phase 3: WASM Module
+- Build WASM module exposing `run_rhai`.
+- Integrate with browser JS via `wasm_bindgen`.
+
+### Phase 4: Browser Extension
+- UI for script input and result display.
+- Integrate WASM module and SessionManager.
+- Secure script input (popup and trusted sites only).
+
+### Phase 5: Web App Integration
+- Implement postMessage and/or WebSocket protocol for trusted web apps to send scripts.
+- Validate origins and handle results.
+
+---
+
+## Open Questions / TODOs
+- What subset of the vault/evm_client API should be exposed to Rhai?
+- What are the best practices for sandboxing Rhai in WASM?
+- How will user authentication/session be handled between extension and web app?
+- How will error reporting and logging work across boundaries?
+
+---
+
+## References
+- [Rhai scripting engine](https://rhai.rs/)
+- [wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/)
+- [WebExtension APIs](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions)
+- [Rust + WASM Book](https://rustwasm.github.io/book/)
+
+---
+
+*Last updated: 2025-05-15*