226 lines
6.6 KiB
Markdown
226 lines
6.6 KiB
Markdown
# 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 network-independent Ethereum wallet
|
|
let wallet = create_ethereum_wallet()?;
|
|
|
|
// Create a wallet with a specific name
|
|
let named_wallet = create_ethereum_wallet_from_name("my_wallet")?;
|
|
|
|
// Create a wallet from a private key
|
|
let imported_wallet = create_ethereum_wallet_from_private_key("0x...")?;
|
|
|
|
// Get the current wallet
|
|
let current_wallet = get_current_ethereum_wallet()?;
|
|
|
|
// Clear wallets
|
|
clear_ethereum_wallets()?;
|
|
|
|
// Legacy functions for backward compatibility
|
|
let wallet = create_ethereum_wallet_for_network(network)?;
|
|
let peaq_wallet = create_peaq_wallet()?;
|
|
let agung_wallet = create_agung_wallet()?;
|
|
```
|
|
|
|
### Network Management
|
|
|
|
The module supports multiple Ethereum networks and provides functionality for managing network configurations:
|
|
|
|
```rust
|
|
// Register a new network
|
|
register_network("Arbitrum", 42161, "https://arb1.arbitrum.io/rpc", "https://arbiscan.io", "ETH", 18);
|
|
|
|
// Remove a network
|
|
remove_network("Arbitrum");
|
|
|
|
// 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 a provider from a network configuration
|
|
let provider = create_provider_from_config(&network)?;
|
|
|
|
// Legacy functions for backward compatibility
|
|
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 on a specific network
|
|
let balance = get_balance("Ethereum", address).await?;
|
|
|
|
// Get the balance using a provider
|
|
let balance = get_balance_with_provider(&provider, address).await?;
|
|
|
|
// Send ETH to an address on a specific network
|
|
let tx_hash = send_eth(&wallet, "Ethereum", to_address, amount).await?;
|
|
|
|
// Legacy function for backward compatibility
|
|
let tx_hash = send_eth_with_provider(&wallet, &provider, to_address, amount).await?;
|
|
|
|
// Format a balance for display
|
|
let formatted = format_balance(balance, &network);
|
|
```
|
|
|
|
### 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(address, abi, network);
|
|
|
|
// Call a read-only function
|
|
let result = call_read_function(&contract, &provider, "balanceOf", tokens).await?;
|
|
|
|
// Call a write function
|
|
let tx_hash = call_write_function(&contract, &wallet, &provider, "transfer", tokens).await?;
|
|
|
|
// Estimate gas for a function call
|
|
let gas = estimate_gas(&contract, &provider, "transfer", tokens).await?;
|
|
```
|
|
|
|
### 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(&abi, function_name, &args)?;
|
|
|
|
// 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)?;
|
|
```
|
|
|
|
## Network Registry
|
|
|
|
The module now includes a centralized network registry that allows for dynamic management of EVM-compatible networks:
|
|
|
|
```rust
|
|
// Built-in networks
|
|
- Gnosis Chain (chain_id: 100, token: xDAI)
|
|
- Peaq Network (chain_id: 3338, token: PEAQ)
|
|
- Agung Network (chain_id: 9990, token: AGNG)
|
|
|
|
// Register a custom network at runtime
|
|
register_network(
|
|
"Polygon",
|
|
137,
|
|
"https://polygon-rpc.com",
|
|
"https://polygonscan.com",
|
|
"MATIC",
|
|
18
|
|
);
|
|
```
|
|
|
|
## Wallet Address Consistency
|
|
|
|
In the new design, Ethereum wallet addresses are consistent across all EVM-compatible networks. This reflects how Ethereum addresses work in reality - the same private key generates the same address on all EVM chains.
|
|
|
|
```rust
|
|
// Create a wallet once
|
|
let wallet = create_ethereum_wallet()?;
|
|
|
|
// Use the same wallet address on any network
|
|
let eth_balance = get_balance("Ethereum", wallet.address).await?;
|
|
let polygon_balance = get_balance("Polygon", wallet.address).await?;
|
|
let gnosis_balance = get_balance("Gnosis", wallet.address).await?;
|
|
```
|
|
|
|
## 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
|
|
- `NoKeypairSelected` - No keypair selected for wallet creation
|
|
- `InvalidKeyLength` - Invalid private key length
|
|
|
|
## 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
|
|
|
|
## Adding a New Network
|
|
|
|
With the new design, adding a new network is as simple as registering it with the network registry:
|
|
|
|
```rust
|
|
// In Rust
|
|
ethereum::register_network(
|
|
"Optimism",
|
|
10,
|
|
"https://mainnet.optimism.io",
|
|
"https://optimistic.etherscan.io",
|
|
"ETH",
|
|
18
|
|
);
|
|
|
|
// In Rhai
|
|
register_network(
|
|
"Optimism",
|
|
10,
|
|
"https://mainnet.optimism.io",
|
|
"https://optimistic.etherscan.io",
|
|
"ETH",
|
|
18
|
|
);
|
|
```
|
|
|
|
No code changes are required to add support for new networks!
|