herocode/herolib_rust
10
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'development_hero_vault'

Browse Source 
* development_hero_vault:
  Add docs
  Support conatrcts call args in rhai bindings
  remove obsolete print
  feat: support interacting with smart contracts on EVM-based blockchains
  refactor and add peaq support
  feat: introduce hero_vault
This commit is contained in:
despiegk
2025-05-12 06:10:05 +03:00
parent 516d0177e7 7298645368
commit 992481ce1b
41 changed files with 5177 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
examples/hero_vault/README.md Normal file
View File

@@ -0,0 +1,64 @@
# 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
- Smart contract interactions
- Key-value store with encryption
## Example Files
- `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
You can run the examples using the `herodo` tool that comes with the SAL project:
```bash
# Run a single example
herodo --path 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`).
## 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.
## 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.
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.

233
examples/hero_vault/advanced_example.rhai Normal file
View File

@@ -0,0 +1,233 @@
// Advanced Rhai script example for Hero Vault Cryptography Module
// This script demonstrates conditional logic, error handling, and more complex operations
// Function to create a key space with error handling
fn setup_key_space(name, password) {
print("Attempting: Create key space: " + name);
let result = create_key_space(name, password);
if result {
print("✅ Create key space succeeded!");
return true;
} else {
print("❌ Create key space failed!");
}
return false;
}
// Function to create and select a keypair
fn setup_keypair(name, password) {
print("Attempting: Create keypair: " + name);
let result = create_keypair(name, password);
if result {
print("✅ Create keypair succeeded!");
print("Attempting: Select keypair: " + name);
let selected = select_keypair(name);
if selected {
print("✅ Select keypair succeeded!");
return true;
} else {
print("❌ Select keypair failed!");
}
} else {
print("❌ Create keypair failed!");
}
return false;
}
// Function to sign multiple messages
fn sign_messages(messages) {
let signatures = [];
for message in messages {
print("Signing message: " + message);
print("Attempting: Sign message");
let signature = sign(message);
if signature != "" {
print("✅ Sign message succeeded!");
signatures.push(#{
message: message,
signature: signature
});
} else {
print("❌ Sign message failed!");
}
}
return signatures;
}
// Function to verify signatures
fn verify_signatures(signed_messages) {
let results = [];
for item in signed_messages {
let message = item.message;
let signature = item.signature;
print("Verifying signature for: " + message);
print("Attempting: Verify signature");
let is_valid = verify(message, signature);
if is_valid {
print("✅ Verify signature succeeded!");
} else {
print("❌ Verify signature failed!");
}
results.push(#{
message: message,
valid: is_valid
});
}
return results;
}
// Function to encrypt multiple messages
fn encrypt_messages(messages) {
// Generate a symmetric key
print("Attempting: Generate symmetric key");
let key = generate_key();
if key == "" {
print("❌ Generate symmetric key failed!");
return [];
}
print("✅ Generate symmetric key succeeded!");
print("Using key: " + key);
let encrypted_messages = [];
for message in messages {
print("Encrypting message: " + message);
print("Attempting: Encrypt message");
let encrypted = encrypt(key, message);
if encrypted != "" {
print("✅ Encrypt message succeeded!");
encrypted_messages.push(#{
original: message,
encrypted: encrypted,
key: key
});
} else {
print("❌ Encrypt message failed!");
}
}
return encrypted_messages;
}
// Function to decrypt messages
fn decrypt_messages(encrypted_messages) {
let decrypted_messages = [];
for item in encrypted_messages {
let encrypted = item.encrypted;
let key = item.key;
let original = item.original;
print("Decrypting message...");
print("Attempting: Decrypt message");
let decrypted = decrypt(key, encrypted);
if decrypted != false {
let success = decrypted == original;
decrypted_messages.push(#{
decrypted: decrypted,
original: original,
success: success
});
if success {
print("Decryption matched original ✅");
} else {
print("Decryption did not match original ❌");
}
}
}
return decrypted_messages;
}
// Main script execution
print("=== Advanced Cryptography Script ===");
// Set up key space
let space_name = "advanced_space";
let password = "secure_password123";
if setup_key_space(space_name, password) {
print("\n--- Key space setup complete ---\n");
// Set up keypair
if setup_keypair("advanced_keypair", password) {
print("\n--- Keypair setup complete ---\n");
// Define messages to sign
let messages = [
"This is the first message to sign",
"Here's another message that needs signing",
"And a third message for good measure"
];
// Sign messages
print("\n--- Signing Messages ---\n");
let signed_messages = sign_messages(messages);
// Verify signatures
print("\n--- Verifying Signatures ---\n");
let verification_results = verify_signatures(signed_messages);
// Count successful verifications
let successful_verifications = verification_results.filter(|r| r.valid).len();
print("Successfully verified " + successful_verifications + " out of " + verification_results.len() + " signatures");
// Encrypt messages
print("\n--- Encrypting Messages ---\n");
let encrypted_messages = encrypt_messages(messages);
// Decrypt messages
print("\n--- Decrypting Messages ---\n");
let decryption_results = decrypt_messages(encrypted_messages);
// Count successful decryptions
let successful_decryptions = decryption_results.filter(|r| r.success).len();
print("Successfully decrypted " + successful_decryptions + " out of " + decryption_results.len() + " messages");
// Create Ethereum wallet
print("\n--- Creating Ethereum Wallet ---\n");
print("Attempting: Create Ethereum wallet");
let wallet_created = create_ethereum_wallet();
if wallet_created {
print("✅ Create Ethereum wallet succeeded!");
print("Attempting: Get Ethereum address");
let address = get_ethereum_address();
if address != "" {
print("✅ Get Ethereum address succeeded!");
print("Ethereum wallet address: " + address);
} else {
print("❌ Get Ethereum address failed!");
}
} else {
print("❌ Create Ethereum wallet failed!");
}
print("\n=== Script execution completed successfully! ===");
} else {
print("Failed to set up keypair. Aborting script.");
}
} else {
print("Failed to set up key space. Aborting script.");
}

152
examples/hero_vault/agung_contract_with_args.rhai Normal file
View File

@@ -0,0 +1,152 @@
// Example Rhai script for testing contract functions with arguments on Agung network
// This script demonstrates how to use call_contract_read and call_contract_write with arguments
// Step 1: Set up wallet and network
let space_name = "agung_contract_args_demo";
let password = "secure_password123";
let private_key = "51c194d20bcd25360a3aa94426b3b60f738007e42f22e1bc97821c65c353e6d2";
let network_name = "agung";
print("=== Testing Contract Functions With Arguments 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("contract_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 simple ERC-20 token contract ABI (partial)
let token_abi = `[
{
"constant": true,
"inputs": [],
"name": "name",
"outputs": [{"name": "", "type": "string"}],
"payable": false,
"stateMutability": "view",
"type": "function"
},
{
"constant": true,
"inputs": [],
"name": "symbol",
"outputs": [{"name": "", "type": "string"}],
"payable": false,
"stateMutability": "view",
"type": "function"
},
{
"constant": true,
"inputs": [],
"name": "decimals",
"outputs": [{"name": "", "type": "uint8"}],
"payable": false,
"stateMutability": "view",
"type": "function"
},
{
"constant": true,
"inputs": [{"name": "_owner", "type": "address"}],
"name": "balanceOf",
"outputs": [{"name": "balance", "type": "uint256"}],
"payable": false,
"stateMutability": "view",
"type": "function"
},
{
"constant": false,
"inputs": [{"name": "_to", "type": "address"}, {"name": "_value", "type": "uint256"}],
"name": "transfer",
"outputs": [{"name": "", "type": "bool"}],
"payable": false,
"stateMutability": "nonpayable",
"type": "function"
}
]`;
// For this example, we'll use a test token contract on Agung
let token_address = "0x7267B587E4416537060C6bF0B06f6Fd421106650";
print("\nLoading contract ABI...");
let contract = load_contract_abi(network_name, token_address, token_abi);
if contract != "" {
print("✓ Contract loaded successfully");
// First, let's try to read some data from the contract
print("\nReading contract data...");
// Try to get token name (no arguments)
let token_name = call_contract_read(contract, "name");
print("Token name: " + token_name);
// Try to get token symbol (no arguments)
let token_symbol = call_contract_read(contract, "symbol");
print("Token symbol: " + token_symbol);
// Try to get token decimals (no arguments)
let token_decimals = call_contract_read(contract, "decimals");
print("Token decimals: " + token_decimals);
// Try to get token balance (with address argument)
print("\nCalling balanceOf with address argument...");
let balance = call_contract_read(contract, "balanceOf", [wallet_address]);
print("Token balance: " + balance);
// Now, let's try to execute a write function with arguments
print("\nExecuting contract write function with arguments...");
// Define a recipient address and amount for the transfer
// Using a random valid address on the network
let recipient = "0xEEdf3468E8F232A7a03D49b674bA44740C8BD8Be";
let amount = 1000000; // Changed from string to number for uint256 compatibility
print("Attempting to transfer " + amount + " tokens to " + recipient);
// Call the transfer function with arguments
let tx_hash = call_contract_write(contract, "transfer", [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, contract issues, or other errors.");
}
} else {
print("✗ Failed to load contract");
}
} 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("\nContract function with arguments test completed");

104
examples/hero_vault/agung_send_transaction.rhai Normal file
View File

@@ -0,0 +1,104 @@
// Script to create an Agung wallet from a private key and send tokens
// This script demonstrates how to create a wallet from a private key and send tokens
// Define the private key and recipient address
let private_key = "0x9ecfd58eca522b0e7c109bf945966ee208cd6d593b1dc3378aedfdc60b64f512";
let recipient_address = "0xf400f9c3F7317e19523a5DB698Ce67e7a7E083e2";
print("=== Agung Wallet Transaction Demo ===");
print(`From private key: ${private_key}`);
print(`To address: ${recipient_address}`);
// First, create a key space and keypair (required for the wallet infrastructure)
let space_name = "agung_transaction_demo";
let password = "demo_password";
// Create a new key space
if !create_key_space(space_name, password) {
print("Failed to create key space");
return;
}
// Create a keypair
if !create_keypair("demo_keypair", password) {
print("Failed to create keypair");
return;
}
// Select the keypair
if !select_keypair("demo_keypair") {
print("Failed to select keypair");
return;
}
print("\nCreated and selected keypair successfully");
// Clear any existing Agung wallets to avoid conflicts
if clear_wallets_for_network("agung") {
print("Cleared existing Agung wallets");
} else {
print("Failed to clear existing Agung wallets");
return;
}
// Create a wallet from the private key directly
print("\n=== Creating Wallet from Private Key ===");
// Create a wallet from the private key for the Agung network
if create_wallet_from_private_key_for_network(private_key, "agung") {
print("Successfully created wallet from private key for Agung network");
// Get the wallet address
let wallet_address = get_wallet_address_for_network("agung");
print(`Wallet address: ${wallet_address}`);
// Create a provider for the Agung network
let provider_id = create_agung_provider();
if provider_id != "" {
print("Successfully created Agung provider");
// Check the wallet balance first
let wallet_address = get_wallet_address_for_network("agung");
let balance_wei = get_balance("agung", wallet_address);
if balance_wei == "" {
print("Failed to get wallet balance");
print("This could be due to network issues or other errors.");
return;
}
print(`Current wallet balance: ${balance_wei} wei`);
// Convert 1 AGNG to wei (1 AGNG = 10^18 wei)
// Use string representation for large numbers
let amount_wei_str = "1000000000000000000"; // 1 AGNG in wei as a string
// Check if we have enough balance
if parse_int(balance_wei) < parse_int(amount_wei_str) {
print(`Insufficient balance to send ${amount_wei_str} wei (1 AGNG)`);
print(`Current balance: ${balance_wei} wei`);
print("Please fund the wallet before attempting to send a transaction");
return;
}
print(`Attempting to send ${amount_wei_str} wei (1 AGNG) to ${recipient_address}`);
// Send the transaction using the blocking implementation
let tx_hash = send_eth("agung", recipient_address, amount_wei_str);
if tx_hash != "" {
print(`Transaction sent with hash: ${tx_hash}`);
print(`You can view the transaction at: ${get_network_explorer_url("agung")}/tx/${tx_hash}`);
} else {
print("Transaction failed");
print("This could be due to insufficient funds, network issues, or other errors.");
print("Check the logs for more details.");
}
} else {
print("Failed to create Agung provider");
}
} else {
print("Failed to create wallet from private key");
}
print("\nAgung transaction demo completed");

98
examples/hero_vault/contract_example.rhai Normal file
View File

@@ -0,0 +1,98 @@
// Example Rhai script for interacting with smart contracts using Hero Vault
// This script demonstrates loading a contract ABI and interacting with a contract
// Step 1: Set up wallet and network
let space_name = "contract_demo_space";
let password = "secure_password123";
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("contract_key", password) {
print("✓ Created contract keypair");
}
// Step 2: Create an Ethereum wallet for Gnosis Chain
print("\nCreating Ethereum wallet...");
if create_ethereum_wallet() {
print("✓ Ethereum wallet created");
let address = get_ethereum_address();
print("Ethereum address: " + address);
// Step 3: Define a simple ERC-20 ABI (partial)
let erc20_abi = `[
{
"constant": true,
"inputs": [],
"name": "name",
"outputs": [{"name": "", "type": "string"}],
"payable": false,
"stateMutability": "view",
"type": "function"
},
{
"constant": true,
"inputs": [],
"name": "symbol",
"outputs": [{"name": "", "type": "string"}],
"payable": false,
"stateMutability": "view",
"type": "function"
},
{
"constant": true,
"inputs": [],
"name": "decimals",
"outputs": [{"name": "", "type": "uint8"}],
"payable": false,
"stateMutability": "view",
"type": "function"
},
{
"constant": true,
"inputs": [{"name": "owner", "type": "address"}],
"name": "balanceOf",
"outputs": [{"name": "", "type": "uint256"}],
"payable": false,
"stateMutability": "view",
"type": "function"
}
]`;
// Step 4: Load the contract ABI
print("\nLoading contract ABI...");
let contract = load_contract_abi("Gnosis", "0x4ECaBa5870353805a9F068101A40E0f32ed605C6", erc20_abi);
if contract != "" {
print("✓ Contract loaded successfully");
// Step 5: Call read-only functions
print("\nCalling read-only functions...");
// Get token name
let token_name = call_contract_read(contract, "name");
print("Token name: " + token_name);
// Get token symbol
let token_symbol = call_contract_read(contract, "symbol");
print("Token symbol: " + token_symbol);
// Get token decimals
let token_decimals = call_contract_read(contract, "decimals");
print("Token decimals: " + token_decimals);
// For now, we're just demonstrating the basic structure
} else {
print("✗ Failed to load contract");
}
} else {
print("✗ Failed to create Ethereum wallet");
}
} else {
print("✗ Failed to create key space");
}
print("\nContract example completed");

85
examples/hero_vault/example.rhai Normal file
View File

@@ -0,0 +1,85 @@
// Example Rhai script for Hero Vault Cryptography Module
// This script demonstrates key management, signing, and encryption
// Step 1: Create and manage a key space
let space_name = "demo_space";
let password = "secure_password123";
print("Creating key space: " + space_name);
if create_key_space(space_name, password) {
print("✓ Key space created successfully");
// Step 2: Create and use keypairs
print("\nCreating keypairs...");
if create_keypair("signing_key", password) {
print("✓ Created signing keypair");
}
if create_keypair("encryption_key", password) {
print("✓ Created encryption keypair");
}
// List all keypairs
let keypairs = list_keypairs();
print("Available keypairs: " + keypairs);
// Step 3: Sign a message
print("\nPerforming signing operations...");
if select_keypair("signing_key") {
print("✓ Selected signing keypair");
let message = "This is a secure message that needs to be signed";
print("Message: " + message);
let signature = sign(message);
print("Signature: " + signature);
// Verify the signature
let is_valid = verify(message, signature);
if is_valid {
print("Signature verification: ✓ Valid");
} else {
print("Signature verification: ✗ Invalid");
}
}
// Step 4: Encrypt and decrypt data
print("\nPerforming encryption operations...");
// Generate a symmetric key
let sym_key = generate_key();
print("Generated symmetric key: " + sym_key);
// Encrypt a message
let secret = "This is a top secret message that must be encrypted";
print("Original message: " + secret);
let encrypted_data = encrypt(sym_key, secret);
print("Encrypted data: " + encrypted_data);
// Decrypt the message
let decrypted_data = decrypt(sym_key, encrypted_data);
print("Decrypted message: " + decrypted_data);
// Verify decryption was successful
if decrypted_data == secret {
print("✓ Encryption/decryption successful");
} else {
print("✗ Encryption/decryption failed");
}
// Step 5: Create an Ethereum wallet
print("\nCreating Ethereum wallet...");
if select_keypair("encryption_key") {
print("✓ Selected keypair for Ethereum wallet");
if create_ethereum_wallet() {
print("✓ Ethereum wallet created");
let address = get_ethereum_address();
print("Ethereum address: " + address);
}
}
print("\nScript execution completed successfully!");
}

65
examples/hero_vault/key_persistence_example.rhai Normal file
View File

@@ -0,0 +1,65 @@
// Example Rhai script demonstrating key space persistence for Hero Vault
// This script shows how to create, save, and load key spaces
// Step 1: Create a key space
let space_name = "persistent_space";
let password = "secure_password123";
print("Creating key space: " + space_name);
if create_key_space(space_name, password) {
print("✓ Key space created successfully");
// Step 2: Create keypairs in this space
print("\nCreating keypairs...");
if create_keypair("persistent_key1", password) {
print("✓ Created first keypair");
}
if create_keypair("persistent_key2", password) {
print("✓ Created second keypair");
}
// List all keypairs
let keypairs = list_keypairs();
print("Available keypairs: " + keypairs);
// Step 3: Clear the session (simulate closing and reopening the CLI)
print("\nClearing session (simulating restart)...");
// Note: In a real script, you would exit here and run a new script
// For demonstration purposes, we'll continue in the same script
// Step 4: Load the key space from disk
print("\nLoading key space from disk...");
if load_key_space(space_name, password) {
print("✓ Key space loaded successfully");
// Verify the keypairs are still available
let loaded_keypairs = list_keypairs();
print("Keypairs after loading: " + loaded_keypairs);
// Step 5: Use a keypair from the loaded space
print("\nSelecting and using a keypair...");
if select_keypair("persistent_key1") {
print("✓ Selected keypair");
let message = "This message was signed using a keypair from a loaded key space";
let signature = sign(message);
print("Message: " + message);
print("Signature: " + signature);
// Verify the signature
let is_valid = verify(message, signature);
if is_valid {
print("Signature verification: ✓ Valid");
} else {
print("Signature verification: ✗ Invalid");
}
}
} else {
print("✗ Failed to load key space");
}
} else {
print("✗ Failed to create key space");
}
print("\nScript execution completed!");

65
examples/hero_vault/load_existing_space.rhai Normal file
View File

@@ -0,0 +1,65 @@
// Example Rhai script demonstrating loading an existing key space for Hero Vault
// This script shows how to load a previously created key space and use its keypairs
// Define the key space name and password
let space_name = "persistent_space";
let password = "secure_password123";
print("Loading existing key space: " + space_name);
// Load the key space from disk
if load_key_space(space_name, password) {
print("✓ Key space loaded successfully");
// List available keypairs
let keypairs = list_keypairs();
print("Available keypairs: " + keypairs);
// Use both keypairs to sign different messages
if select_keypair("persistent_key1") {
print("\nUsing persistent_key1:");
let message1 = "Message signed with the first keypair";
let signature1 = sign(message1);
print("Message: " + message1);
print("Signature: " + signature1);
let is_valid1 = verify(message1, signature1);
if is_valid1 {
print("Verification: ✓ Valid");
} else {
print("Verification: ✗ Invalid");
}
}
if select_keypair("persistent_key2") {
print("\nUsing persistent_key2:");
let message2 = "Message signed with the second keypair";
let signature2 = sign(message2);
print("Message: " + message2);
print("Signature: " + signature2);
let is_valid2 = verify(message2, signature2);
if is_valid2 {
print("Verification: ✓ Valid");
} else {
print("Verification: ✗ Invalid");
}
}
// Create an Ethereum wallet using one of the keypairs
print("\nCreating Ethereum wallet from persistent keypair:");
if select_keypair("persistent_key1") {
if create_ethereum_wallet() {
print("✓ Ethereum wallet created");
let address = get_ethereum_address();
print("Ethereum address: " + address);
} else {
print("✗ Failed to create Ethereum wallet");
}
}
} else {
print("✗ Failed to load key space. Make sure you've run key_persistence_example.rhai first.");
}
print("\nScript execution completed!");