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