feat: introduce hero_vault

examples/hero_vault/README.md

@@ -0,0 +1,49 @@
+# Hero Vault Cryptography Examples
+
+This directory contains examples demonstrating the Hero Vault cryptography functionality integrated into the SAL project.
+
+## Overview
+
+Hero Vault provides cryptographic operations including:
+
+- Key space management (creation, loading, encryption, decryption)
+- Keypair management (creation, selection, listing)
+- Digital signatures (signing and verification)
+- Symmetric encryption (key generation, encryption, decryption)
+- Ethereum wallet functionality
+
+## Directory Structure
+
+- `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
+
+## Running the Examples
+
+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
+
+# Run all examples using the provided script
+./run_examples.sh
+```
+
+## Key Space Storage
+
+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`).
+
+## 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.
+
+## Best Practices
+
+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.