Add docs

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.