Add docs

examples/hero_vault/README.md

@@ -11,15 +11,18 @@ Hero Vault provides cryptographic operations including:
 - Digital signatures (signing and verification)
 - Symmetric encryption (key generation, encryption, decryption)
 - Ethereum wallet functionality
+- Smart contract interactions
+- Key-value store with encryption
 
-## Directory Structure
+## Example Files
 
-- `rhai/` - Rhai script examples demonstrating Hero Vault functionality
-  - `example.rhai` - Basic example demonstrating key management, signing, and encryption
-  - `advanced_example.rhai` - Advanced example with error handling and more complex operations
-  - `key_persistence_example.rhai` - Demonstrates creating and saving a key space to disk
-  - `load_existing_space.rhai` - Shows how to load a previously created key space and use its keypairs
-  - `README.md` - Documentation for the Rhai scripting API
+- `example.rhai` - Basic example demonstrating key management, signing, and encryption
+- `advanced_example.rhai` - Advanced example with error handling, conditional logic, and more complex operations
+- `key_persistence_example.rhai` - Demonstrates creating and saving a key space to disk
+- `load_existing_space.rhai` - Shows how to load a previously created key space and use its keypairs
+- `contract_example.rhai` - Demonstrates loading a contract ABI and interacting with smart contracts
+- `agung_send_transaction.rhai` - Demonstrates sending native tokens on the Agung network
+- `agung_contract_with_args.rhai` - Shows how to interact with contracts with arguments on Agung
 
 ## Running the Examples
 
@@ -27,7 +30,7 @@ You can run the examples using the `herodo` tool that comes with the SAL project
 
 ```bash
 # Run a single example
-herodo --path rhai/example.rhai
+herodo --path example.rhai
 
 # Run all examples using the provided script
 ./run_examples.sh
@@ -37,6 +40,16 @@ herodo --path rhai/example.rhai
 
 Key spaces are stored in the `~/.hero-vault/key-spaces/` directory by default. Each key space is stored in a separate JSON file named after the key space (e.g., `my_space.json`).
 
+## Ethereum Functionality
+
+The Hero Vault module provides comprehensive Ethereum wallet functionality:
+
+- Creating and managing wallets for different networks
+- Sending ETH transactions
+- Checking balances
+- Interacting with smart contracts (read and write functions)
+- Support for multiple networks (Ethereum, Gnosis, Peaq, Agung, etc.)
+
 ## Security
 
 Key spaces are encrypted with ChaCha20Poly1305 using a key derived from the provided password. The encryption ensures that the key material is secure at rest.
@@ -46,4 +59,6 @@ Key spaces are encrypted with ChaCha20Poly1305 using a key derived from the prov
 1. **Use Strong Passwords**: Since the security of your key spaces depends on the strength of your passwords, use strong, unique passwords.
 2. **Backup Key Spaces**: Regularly backup your key spaces directory to prevent data loss.
 3. **Script Organization**: Split your scripts into logical units, with separate scripts for key creation and key usage.
-4. **Error Handling**: Always check the return values of functions to ensure operations succeeded before proceeding.
+4. **Error Handling**: Always check the return values of functions to ensure operations succeeded before proceeding.
+5. **Network Selection**: When working with Ethereum functionality, be explicit about which network you're targeting to avoid confusion.
+6. **Gas Management**: For Ethereum transactions, consider gas costs and set appropriate gas limits.

examples/hero_vault/agung_simple_transfer.rhai

@@ -1,68 +0,0 @@
-// Example Rhai script for testing a simple ETH transfer on Agung network
-// This script demonstrates how to use send_eth with the private key
-
-// Step 1: Set up wallet and network
-let space_name = "agung_simple_transfer_demo";
-let password = "secure_password123";
-let private_key = "0xf3976cfd4e0705cf90014f18140c14850bee210d4d609d49eb84eecc36fc5f38";
-let network_name = "agung";
-
-print("=== Testing Simple ETH Transfer on Agung Network ===\n");
-
-// Create a key space
-print("Creating key space: " + space_name);
-if create_key_space(space_name, password) {
-    print("✓ Key space created successfully");
-    
-    // Create a keypair
-    print("\nCreating keypair...");
-    if create_keypair("transfer_key", password) {
-        print("✓ Created contract keypair");
-        
-        // Create a wallet from the private key for the Agung network
-        print("\nCreating wallet from private key for Agung network...");
-        if create_wallet_from_private_key_for_network(private_key, network_name) {
-            print("✓ Wallet created successfully");
-            
-            // Get the wallet address
-            let wallet_address = get_wallet_address_for_network(network_name);
-            print("Wallet address: " + wallet_address);
-            
-            // Check wallet balance
-            print("\nChecking wallet balance...");
-            let balance = get_balance(network_name, wallet_address);
-            if balance != "" {
-                print("Wallet balance: " + balance + " wei");
-                
-                // Define a recipient address for the transfer
-                // Using a random valid address on the network
-                let recipient = "0x7267B587E4416537060C6bF0B06f6Fd421106650";
-                let amount = "1000000000000000"; // 0.001 ETH
-                
-                print("\nAttempting to transfer " + amount + " wei to " + recipient);
-                
-                // Send ETH
-                let tx_hash = send_eth(network_name, recipient, amount);
-                
-                if tx_hash != "" {
-                    print("✓ Transaction sent successfully");
-                    print("Transaction hash: " + tx_hash);
-                    print("You can view the transaction at: " + get_network_explorer_url(network_name) + "/tx/" + tx_hash);
-                } else {
-                    print("✗ Failed to send transaction");
-                    print("This could be due to insufficient funds or other errors.");
-                }
-            } else {
-                print("✗ Failed to get wallet balance");
-            }
-        } else {
-            print("✗ Failed to create wallet from private key");
-        }
-    } else {
-        print("✗ Failed to create keypair");
-    }
-} else {
-    print("✗ Failed to create key space");
-}
-
-print("\nSimple transfer test completed");

src/hero_vault/README.md

@@ -0,0 +1,160 @@
+# Hero Vault Cryptography Module
+
+The Hero Vault module provides comprehensive cryptographic functionality for the SAL project, including key management, digital signatures, symmetric encryption, Ethereum wallet operations, and a secure key-value store.
+
+## Module Structure
+
+The Hero Vault module is organized into several submodules:
+
+- `error.rs` - Error types for cryptographic operations
+- `keypair/` - ECDSA keypair management functionality
+- `symmetric/` - Symmetric encryption using ChaCha20Poly1305
+- `ethereum/` - Ethereum wallet and smart contract functionality
+- `kvs/` - Encrypted key-value store
+
+## Key Features
+
+### Key Space Management
+
+The module provides functionality for creating, loading, and managing key spaces. A key space is a secure container for cryptographic keys, which can be encrypted and stored on disk.
+
+```rust
+// Create a new key space
+let space = KeySpace::new("my_space", "secure_password")?;
+
+// Save the key space to disk
+space.save()?;
+
+// Load a key space from disk
+let loaded_space = KeySpace::load("my_space", "secure_password")?;
+```
+
+### Keypair Management
+
+The module provides functionality for creating, selecting, and using ECDSA keypairs for digital signatures.
+
+```rust
+// Create a new keypair in the active key space
+let keypair = space.create_keypair("my_keypair", "secure_password")?;
+
+// Select a keypair for use
+space.select_keypair("my_keypair")?;
+
+// List all keypairs in the active key space
+let keypairs = space.list_keypairs()?;
+```
+
+### Digital Signatures
+
+The module provides functionality for signing and verifying messages using ECDSA.
+
+```rust
+// Sign a message using the selected keypair
+let signature = space.sign("This is a message to sign")?;
+
+// Verify a signature
+let is_valid = space.verify("This is a message to sign", &signature)?;
+```
+
+### Symmetric Encryption
+
+The module provides functionality for symmetric encryption using ChaCha20Poly1305.
+
+```rust
+// Generate a new symmetric key
+let key = space.generate_key()?;
+
+// Encrypt a message
+let encrypted = space.encrypt(&key, "This is a secret message")?;
+
+// Decrypt a message
+let decrypted = space.decrypt(&key, &encrypted)?;
+```
+
+### Ethereum Wallet Functionality
+
+The module provides comprehensive Ethereum wallet functionality, including:
+
+- Creating and managing wallets for different networks
+- Sending ETH transactions
+- Checking balances
+- Interacting with smart contracts
+
+```rust
+// Create an Ethereum wallet
+let wallet = EthereumWallet::new(keypair)?;
+
+// Get the wallet address
+let address = wallet.get_address()?;
+
+// Send ETH
+let tx_hash = wallet.send_eth("0x1234...", "1000000000000000")?;
+
+// Check balance
+let balance = wallet.get_balance("0x1234...")?;
+```
+
+### Smart Contract Interactions
+
+The module provides functionality for interacting with smart contracts on EVM-based blockchains.
+
+```rust
+// Load a contract ABI
+let contract = Contract::new(provider, "0x1234...", abi)?;
+
+// Call a read-only function
+let result = contract.call_read("balanceOf", vec!["0x5678..."])?;
+
+// Call a write function
+let tx_hash = contract.call_write("transfer", vec!["0x5678...", "1000"])?;
+```
+
+### Key-Value Store
+
+The module provides an encrypted key-value store for securely storing sensitive data.
+
+```rust
+// Create a new store
+let store = KvStore::new("my_store", "secure_password")?;
+
+// Set a value
+store.set("api_key", "secret_api_key")?;
+
+// Get a value
+let api_key = store.get("api_key")?;
+```
+
+## Error Handling
+
+The module uses a comprehensive error type (`CryptoError`) for handling errors that can occur during cryptographic operations:
+
+- `InvalidKeyLength` - Invalid key length
+- `EncryptionFailed` - Encryption failed
+- `DecryptionFailed` - Decryption failed
+- `SignatureFormatError` - Signature format error
+- `KeypairAlreadyExists` - Keypair already exists
+- `KeypairNotFound` - Keypair not found
+- `NoActiveSpace` - No active key space
+- `NoKeypairSelected` - No keypair selected
+- `SerializationError` - Serialization error
+- `InvalidAddress` - Invalid address format
+- `ContractError` - Smart contract error
+
+## Ethereum Networks
+
+The module supports multiple Ethereum networks, including:
+
+- Gnosis Chain
+- Peaq Network
+- Agung Network
+
+## Security Considerations
+
+- Key spaces are encrypted with ChaCha20Poly1305 using a key derived from the provided password
+- Private keys are never stored in plaintext
+- The module uses secure random number generation for key creation
+- All cryptographic operations use well-established libraries and algorithms
+
+## Examples
+
+For examples of how to use the Hero Vault module, see the `examples/hero_vault` directory.

src/hero_vault/ethereum/README.md

@@ -0,0 +1,160 @@
+# Hero Vault Ethereum Module
+
+The Ethereum module provides functionality for creating and managing Ethereum wallets and interacting with smart contracts on EVM-based blockchains.
+
+## Module Structure
+
+The Ethereum module is organized into several components:
+
+- `wallet.rs` - Core Ethereum wallet implementation
+- `networks.rs` - Network registry and configuration
+- `provider.rs` - Provider creation and management
+- `transaction.rs` - Transaction-related functionality
+- `storage.rs` - Wallet storage functionality
+- `contract.rs` - Smart contract interaction functionality
+- `contract_utils.rs` - Utilities for contract interactions
+
+## Key Features
+
+### Wallet Management
+
+The module provides functionality for creating and managing Ethereum wallets:
+
+```rust
+// Create a new Ethereum wallet for a specific network
+let wallet = create_ethereum_wallet_for_network("Ethereum")?;
+
+// Create a wallet for specific networks
+let peaq_wallet = create_peaq_wallet()?;
+let agung_wallet = create_agung_wallet()?;
+
+// Create a wallet with a specific name
+let named_wallet = create_ethereum_wallet_from_name_for_network("my_wallet", "Gnosis")?;
+
+// Create a wallet from a private key
+let imported_wallet = create_ethereum_wallet_from_private_key("0x...")?;
+
+// Get the current wallet for a network
+let current_wallet = get_current_ethereum_wallet_for_network("Ethereum")?;
+
+// Clear wallets
+clear_ethereum_wallets()?;
+clear_ethereum_wallets_for_network("Gnosis")?;
+```
+
+### Network Management
+
+The module supports multiple Ethereum networks and provides functionality for managing network configurations:
+
+```rust
+// Get a network configuration by name
+let network = get_network_by_name("Ethereum")?;
+
+// Get the proper network name (normalized)
+let name = get_proper_network_name("eth")?; // Returns "Ethereum"
+
+// List all available network names
+let networks = list_network_names()?;
+
+// Get all network configurations
+let all_networks = get_all_networks()?;
+```
+
+### Provider Management
+
+The module provides functionality for creating and managing Ethereum providers:
+
+```rust
+// Create a provider for a specific network
+let provider = create_provider("Ethereum")?;
+
+// Create providers for specific networks
+let gnosis_provider = create_gnosis_provider()?;
+let peaq_provider = create_peaq_provider()?;
+let agung_provider = create_agung_provider()?;
+```
+
+### Transaction Management
+
+The module provides functionality for managing Ethereum transactions:
+
+```rust
+// Get the balance of an address
+let balance = get_balance("Ethereum", "0x...")?;
+
+// Send ETH to an address
+let tx_hash = send_eth("Ethereum", "0x...", "1000000000000000")?;
+
+// Format a balance for display
+let formatted = format_balance(balance, 18)?; // Convert wei to ETH
+```
+
+### Smart Contract Interactions
+
+The module provides functionality for interacting with smart contracts:
+
+```rust
+// Load a contract ABI from JSON
+let abi = load_abi_from_json(json_string)?;
+
+// Create a contract instance
+let contract = Contract::new(provider, "0x...", abi)?;
+
+// Call a read-only function
+let result = call_read_function(contract, "balanceOf", vec!["0x..."])?;
+
+// Call a write function
+let tx_hash = call_write_function(contract, "transfer", vec!["0x...", "1000"])?;
+
+// Estimate gas for a function call
+let gas = estimate_gas(contract, "transfer", vec!["0x...", "1000"])?;
+```
+
+### Contract Utilities
+
+The module provides utilities for working with contract function arguments and return values:
+
+```rust
+// Convert Rhai values to Ethereum tokens
+let token = convert_rhai_to_token(value)?;
+
+// Prepare function arguments
+let args = prepare_function_arguments(function, vec![arg1, arg2])?;
+
+// Convert Ethereum tokens to Rhai values
+let rhai_value = convert_token_to_rhai(token)?;
+
+// Convert a token to a dynamic value
+let dynamic = token_to_dynamic(token)?;
+```
+
+## Supported Networks
+
+The module supports multiple Ethereum networks, including:
+
+- Gnosis Chain
+- Peaq Network
+- Agung Network
+
+Each network has its own configuration, including:
+
+- RPC URL
+- Chain ID
+- Explorer URL
+- Native currency symbol and decimals
+
+## Error Handling
+
+The module uses the `CryptoError` type for handling errors that can occur during Ethereum operations:
+
+- `InvalidAddress` - Invalid Ethereum address format
+- `ContractError` - Smart contract interaction error
+
+## Examples
+
+For examples of how to use the Ethereum module, see the `examples/hero_vault` directory, particularly:
+
+- `contract_example.rhai` - Demonstrates loading a contract ABI and interacting with smart contracts
+- `agung_simple_transfer.rhai` - Shows how to perform a simple ETH transfer on the Agung network
+- `agung_send_transaction.rhai` - Demonstrates sending transactions on the Agung network
+- `agung_contract_with_args.rhai` - Shows how to interact with contracts with arguments on Agung

src/hero_vault/keypair/README.md

@@ -0,0 +1,187 @@
+# Hero Vault Keypair Module
+
+The Keypair module provides functionality for creating, managing, and using ECDSA keypairs for digital signatures and other cryptographic operations.
+
+## Module Structure
+
+The Keypair module is organized into:
+
+- `implementation.rs` - Core implementation of the KeyPair and KeySpace types
+- `mod.rs` - Module exports and public interface
+
+## Key Types
+
+### KeyPair
+
+The `KeyPair` type represents an ECDSA keypair used for digital signatures and other cryptographic operations.
+
+```rust
+pub struct KeyPair {
+    // Private fields
+    // ...
+}
+
+impl KeyPair {
+    // Create a new random keypair
+    pub fn new() -> Result<Self, CryptoError>;
+    
+    // Create a keypair from an existing private key
+    pub fn from_private_key(private_key: &[u8]) -> Result<Self, CryptoError>;
+    
+    // Get the public key
+    pub fn public_key(&self) -> &[u8];
+    
+    // Sign a message
+    pub fn sign(&self, message: &[u8]) -> Result<Vec<u8>, CryptoError>;
+    
+    // Verify a signature
+    pub fn verify(&self, message: &[u8], signature: &[u8]) -> Result<bool, CryptoError>;
+    
+    // Derive an Ethereum address from the public key
+    pub fn to_ethereum_address(&self) -> Result<String, CryptoError>;
+    
+    // Export the private key (should be used with caution)
+    pub fn export_private_key(&self) -> Result<Vec<u8>, CryptoError>;
+}
+```
+
+### KeySpace
+
+The `KeySpace` type represents a secure container for multiple keypairs, which can be encrypted and stored on disk.
+
+```rust
+pub struct KeySpace {
+    // Private fields
+    // ...
+}
+
+impl KeySpace {
+    // Create a new key space
+    pub fn new(name: &str, password: &str) -> Result<Self, CryptoError>;
+    
+    // Load a key space from disk
+    pub fn load(name: &str, password: &str) -> Result<Self, CryptoError>;
+    
+    // Save the key space to disk
+    pub fn save(&self) -> Result<(), CryptoError>;
+    
+    // Create a new keypair in the key space
+    pub fn create_keypair(&mut self, name: &str, password: &str) -> Result<&KeyPair, CryptoError>;
+    
+    // Select a keypair for use
+    pub fn select_keypair(&mut self, name: &str) -> Result<&KeyPair, CryptoError>;
+    
+    // Get the currently selected keypair
+    pub fn current_keypair(&self) -> Result<&KeyPair, CryptoError>;
+    
+    // List all keypairs in the key space
+    pub fn list_keypairs(&self) -> Result<Vec<String>, CryptoError>;
+    
+    // Get a keypair by name
+    pub fn get_keypair(&self, name: &str) -> Result<&KeyPair, CryptoError>;
+    
+    // Remove a keypair from the key space
+    pub fn remove_keypair(&mut self, name: &str) -> Result<(), CryptoError>;
+    
+    // Rename a keypair
+    pub fn rename_keypair(&mut self, old_name: &str, new_name: &str) -> Result<(), CryptoError>;
+    
+    // Get the name of the key space
+    pub fn name(&self) -> &str;
+}
+```
+
+## Key Features
+
+### Key Space Management
+
+The module provides functionality for creating, loading, and managing key spaces:
+
+```rust
+// Create a new key space
+let mut space = KeySpace::new("my_space", "secure_password")?;
+
+// Save the key space to disk
+space.save()?;
+
+// Load a key space from disk
+let mut loaded_space = KeySpace::load("my_space", "secure_password")?;
+```
+
+### Keypair Management
+
+The module provides functionality for creating, selecting, and using keypairs:
+
+```rust
+// Create a new keypair in the key space
+let keypair = space.create_keypair("my_keypair", "secure_password")?;
+
+// Select a keypair for use
+space.select_keypair("my_keypair")?;
+
+// Get the currently selected keypair
+let current = space.current_keypair()?;
+
+// List all keypairs in the key space
+let keypairs = space.list_keypairs()?;
+
+// Get a keypair by name
+let keypair = space.get_keypair("my_keypair")?;
+
+// Remove a keypair from the key space
+space.remove_keypair("my_keypair")?;
+
+// Rename a keypair
+space.rename_keypair("my_keypair", "new_name")?;
+```
+
+### Digital Signatures
+
+The module provides functionality for signing and verifying messages using ECDSA:
+
+```rust
+// Sign a message using the selected keypair
+let keypair = space.current_keypair()?;
+let signature = keypair.sign("This is a message to sign".as_bytes())?;
+
+// Verify a signature
+let is_valid = keypair.verify("This is a message to sign".as_bytes(), &signature)?;
+```
+
+### Ethereum Address Derivation
+
+The module provides functionality for deriving Ethereum addresses from keypairs:
+
+```rust
+// Derive an Ethereum address from a keypair
+let keypair = space.current_keypair()?;
+let address = keypair.to_ethereum_address()?;
+```
+
+## Security Considerations
+
+- Key spaces are encrypted with ChaCha20Poly1305 using a key derived from the provided password
+- Private keys are never stored in plaintext
+- The module uses secure random number generation for key creation
+- All cryptographic operations use well-established libraries and algorithms
+
+## Error Handling
+
+The module uses the `CryptoError` type for handling errors that can occur during keypair operations:
+
+- `InvalidKeyLength` - Invalid key length
+- `SignatureFormatError` - Signature format error
+- `KeypairAlreadyExists` - Keypair already exists
+- `KeypairNotFound` - Keypair not found
+- `NoActiveSpace` - No active key space
+- `NoKeypairSelected` - No keypair selected
+- `SerializationError` - Serialization error
+
+## Examples
+
+For examples of how to use the Keypair module, see the `examples/hero_vault` directory, particularly:
+
+- `example.rhai` - Basic example demonstrating key management and signing
+- `advanced_example.rhai` - Advanced example with error handling
+- `key_persistence_example.rhai` - Demonstrates creating and saving a key space to disk
+- `load_existing_space.rhai` - Shows how to load a previously created key space

src/hero_vault/kvs/README.md

@@ -0,0 +1,167 @@
+# Hero Vault Key-Value Store Module
+
+The Key-Value Store (KVS) module provides an encrypted key-value store for securely storing sensitive data.
+
+## Module Structure
+
+The KVS module is organized into:
+
+- `store.rs` - Core implementation of the key-value store
+- `error.rs` - Error types specific to the KVS module
+- `mod.rs` - Module exports and public interface
+
+## Key Types
+
+### KvStore
+
+The `KvStore` type represents an encrypted key-value store:
+
+```rust
+pub struct KvStore {
+    // Private fields
+    // ...
+}
+
+impl KvStore {
+    // Create a new store
+    pub fn new(name: &str, password: &str) -> Result<Self, CryptoError>;
+    
+    // Load a store from disk
+    pub fn load(name: &str, password: &str) -> Result<Self, CryptoError>;
+    
+    // Save the store to disk
+    pub fn save(&self) -> Result<(), CryptoError>;
+    
+    // Set a value
+    pub fn set(&mut self, key: &str, value: &str) -> Result<(), CryptoError>;
+    
+    // Get a value
+    pub fn get(&self, key: &str) -> Result<Option<String>, CryptoError>;
+    
+    // Delete a value
+    pub fn delete(&mut self, key: &str) -> Result<(), CryptoError>;
+    
+    // Check if a key exists
+    pub fn has(&self, key: &str) -> Result<bool, CryptoError>;
+    
+    // List all keys
+    pub fn keys(&self) -> Result<Vec<String>, CryptoError>;
+    
+    // Clear all values
+    pub fn clear(&mut self) -> Result<(), CryptoError>;
+    
+    // Get the name of the store
+    pub fn name(&self) -> &str;
+}
+```
+
+## Key Features
+
+### Store Management
+
+The module provides functionality for creating, loading, and managing key-value stores:
+
+```rust
+// Create a new store
+let mut store = KvStore::new("my_store", "secure_password")?;
+
+// Save the store to disk
+store.save()?;
+
+// Load a store from disk
+let mut loaded_store = KvStore::load("my_store", "secure_password")?;
+```
+
+### Value Management
+
+The module provides functionality for managing values in the store:
+
+```rust
+// Set a value
+store.set("api_key", "secret_api_key")?;
+
+// Get a value
+let api_key = store.get("api_key")?;
+
+// Delete a value
+store.delete("api_key")?;
+
+// Check if a key exists
+let exists = store.has("api_key")?;
+
+// List all keys
+let keys = store.keys()?;
+
+// Clear all values
+store.clear()?;
+```
+
+## Technical Details
+
+### Encryption
+
+The KVS module uses the Symmetric Encryption module to encrypt all values stored in the key-value store. This ensures that sensitive data is protected at rest.
+
+The encryption process:
+
+1. A master key is derived from the provided password using PBKDF2
+2. Each value is encrypted using ChaCha20Poly1305 with a unique key derived from the master key and the value's key
+3. The encrypted values are stored in a JSON file on disk
+
+### Storage Format
+
+The key-value store is stored in a JSON file with the following structure:
+
+```json
+{
+  "name": "my_store",
+  "salt": "base64-encoded-salt",
+  "values": {
+    "key1": "base64-encoded-encrypted-value",
+    "key2": "base64-encoded-encrypted-value",
+    ...
+  }
+}
+```
+
+The file is stored in the `~/.hero-vault/stores/` directory by default.
+
+## Security Considerations
+
+- Use strong passwords to protect the key-value store
+- The security of the store depends on the strength of the password
+- Consider the security implications of storing sensitive data on disk
+- Regularly backup the store to prevent data loss
+
+## Error Handling
+
+The module uses the `CryptoError` type for handling errors that can occur during key-value store operations:
+
+- `EncryptionFailed` - Encryption failed
+- `DecryptionFailed` - Decryption failed
+- `SerializationError` - Serialization error
+
+## Examples
+
+For examples of how to use the KVS module, see the `examples/hero_vault` directory. While there may not be specific examples for the KVS module, the general pattern of usage is similar to the key space management examples.
+
+A basic usage example:
+
+```rust
+// Create a new store
+let mut store = KvStore::new("my_store", "secure_password")?;
+
+// Set some values
+store.set("api_key", "secret_api_key")?;
+store.set("access_token", "secret_access_token")?;
+
+// Save the store to disk
+store.save()?;
+
+// Later, load the store
+let loaded_store = KvStore::load("my_store", "secure_password")?;
+
+// Get a value
+let api_key = loaded_store.get("api_key")?;
+println!("API Key: {}", api_key.unwrap_or_default());
+```

src/hero_vault/symmetric/README.md

@@ -0,0 +1,98 @@
+# Hero Vault Symmetric Encryption Module
+
+The Symmetric Encryption module provides functionality for symmetric encryption and decryption using the ChaCha20Poly1305 algorithm.
+
+## Module Structure
+
+The Symmetric Encryption module is organized into:
+
+- `implementation.rs` - Core implementation of symmetric encryption functionality
+- `mod.rs` - Module exports and public interface
+
+## Key Features
+
+### Key Generation
+
+The module provides functionality for generating secure symmetric keys:
+
+```rust
+// Generate a new symmetric key
+let key = generate_key()?;
+```
+
+### Encryption
+
+The module provides functionality for encrypting data using ChaCha20Poly1305:
+
+```rust
+// Encrypt data
+let encrypted = encrypt(&key, "This is a secret message")?;
+```
+
+### Decryption
+
+The module provides functionality for decrypting data encrypted with ChaCha20Poly1305:
+
+```rust
+// Decrypt data
+let decrypted = decrypt(&key, &encrypted)?;
+```
+
+### Password-Based Key Derivation
+
+The module provides functionality for deriving encryption keys from passwords:
+
+```rust
+// Derive a key from a password
+let key = derive_key_from_password(password, salt)?;
+```
+
+## Technical Details
+
+### ChaCha20Poly1305
+
+The module uses the ChaCha20Poly1305 authenticated encryption with associated data (AEAD) algorithm, which provides both confidentiality and integrity protection.
+
+ChaCha20 is a stream cipher designed by Daniel J. Bernstein, which is combined with the Poly1305 message authentication code to provide authenticated encryption.
+
+Key features of ChaCha20Poly1305:
+
+- 256-bit key
+- 96-bit nonce (used once)
+- Authentication tag to verify integrity
+- High performance on modern processors
+- Resistance to timing attacks
+
+### Key Derivation
+
+For password-based encryption, the module uses the PBKDF2 (Password-Based Key Derivation Function 2) algorithm to derive encryption keys from passwords.
+
+Key features of PBKDF2:
+
+- Configurable iteration count to increase computational cost
+- Salt to prevent rainbow table attacks
+- Configurable output key length
+- Uses HMAC-SHA256 as the underlying pseudorandom function
+
+## Security Considerations
+
+- Always use a unique key for each encryption operation
+- Never reuse nonces with the same key
+- Store keys securely
+- Use strong passwords for password-based encryption
+- Consider the security implications of storing encrypted data
+
+## Error Handling
+
+The module uses the `CryptoError` type for handling errors that can occur during symmetric encryption operations:
+
+- `InvalidKeyLength` - Invalid key length
+- `EncryptionFailed` - Encryption failed
+- `DecryptionFailed` - Decryption failed
+
+## Examples
+
+For examples of how to use the Symmetric Encryption module, see the `examples/hero_vault` directory, particularly:
+
+- `example.rhai` - Basic example demonstrating symmetric encryption
+- `advanced_example.rhai` - Advanced example with error handling