Expand description
The Aleo Rust SDK provides a set of tools for deploying and executing programs as well as tools for communicating with the Aleo Network.
§Aleo Network Interaction
Users of the SDK can interact with the Aleo network via the AleoAPIClient struct.
The Aleo Network has nodes within the network which provide a REST API for interacting with the network. The AleoAPIClient struct provides a 1:1 mapping of those REST API endpoints as well as several convenience methods for interacting with the network.
Some key usages of the Aleo API client are:
- Finding records to spend in value transfers, program executions and program deployments
- Locating programs deployed on the network
- Sending transactions to the network
- Inspecting chain data such as block content, transaction content, etc.
§Example Usage
use aleo_rust::AleoAPIClient;
use snarkvm_console::{
account::PrivateKey,
network::Testnet3,
};
use rand::thread_rng;
// Create a client that interacts with the testnet3 program
let api_client = AleoAPIClient::<Testnet3>::testnet3();
// FIND A PROGRAM ON THE ALEO NETWORK
let hello = api_client.get_program("hello.aleo").unwrap();
println!("Hello program: {hello:?}");
// FIND RECORDS THAT BELONG TO A PRIVATE KEY
let mut rng = thread_rng();
// Create a private key (in practice, this would be an existing user's private key)
let private_key = PrivateKey::new(&mut rng).unwrap();
// Get the latest block height
let end_height = api_client.latest_height().unwrap();
// Look back 1000 blocks
let start_height = end_height - 1000u32;
// Find records with these gate amounts (requires an account with a balance)
let amounts_to_find = vec![100u64, 200u64];
let records = api_client.get_unspent_records(&private_key, (start_height..end_height), None, Some(&amounts_to_find)).unwrap();
§Program Execution and Deployment
The Aleo ProgramManager provides a set of tools for deploying and executing programs locally and on the Aleo Network.
The RecordFinder struct is used in conjunction with the ProgramManager to find records to spend in value transfers and program execution/deployments fees.
The program deployment and execution flow are shown in the example below.
§Example Usage
use aleo_rust::{
AleoAPIClient, Encryptor, ProgramManager, RecordFinder,
snarkvm_types::{Address, PrivateKey, Testnet3, Program},
TransferType
};
use rand::thread_rng;
use std::str::FromStr;
// Create the necessary components to create the program manager
let mut rng = thread_rng();
// Create an api client to query the network state
let api_client = AleoAPIClient::<Testnet3>::testnet3();
// Create a private key (in practice, this would be a user's private key)
let private_key = PrivateKey::<Testnet3>::new(&mut rng).unwrap();
// Encrypt the private key with a password
let private_key_ciphertext = Encryptor::<Testnet3>::encrypt_private_key_with_secret(&private_key, "password").unwrap();
// Create the program manager
// (Note: An optional local directory can be provided to manage local program data)
let mut program_manager = ProgramManager::<Testnet3>::new(None, Some(private_key_ciphertext), Some(api_client), None, false).unwrap();
// ------------------
// EXECUTE PROGRAM STEPS
// ------------------
let record_finder = RecordFinder::<Testnet3>::new(AleoAPIClient::testnet3());
// Set the fee for the deployment transaction (in units of microcredits)
let fee_microcredits = 300000;
// Find a record to fund the deployment fee (requires an account with a balance)
let fee_record = record_finder.find_one_record(&private_key, fee_microcredits, None).unwrap();
// Execute the function `hello` of the hello.aleo program with the arguments 5u32 and 3u32.
// Specify 0 for the fee and provide a password to decrypt the private key stored in the program manager
program_manager.execute_program("hello.aleo", "hello", ["5u32", "3u32"].into_iter(), 0, Some(fee_record), Some("password"), None).unwrap();
// ------------------
// DEPLOY PROGRAM STEPS
// ------------------
// Note - Deployment requires a mandatory deployment fee, so an account with an existing
// balance is required to deploy a program
// Create a program name (note: change this to something unique)
let program_name = "yourownprogram.aleo";
// Create a test program
let test_program = format!("program {};\n\nfunction hello:\n input r0 as u32.public;\n input r1 as u32.private;\n add r0 r1 into r2;\n output r2 as u32.private;\n", program_name);
// Create a program object from the program string
let program = Program::from_str(&test_program).unwrap();
// Add the program to the program manager (this can also be done by providing a path to
// the program on disk when the program manager is created)
program_manager.add_program(&program).unwrap();
// Create a record finder to find records to fund the deployment fee
let record_finder = RecordFinder::<Testnet3>::new(AleoAPIClient::testnet3());
// Set the fee for the deployment transaction (in units of microcredits)
let fee_microcredits = 300000;
// Find a record to fund the deployment fee (requires an account with a balance)
let fee_record = record_finder.find_one_record(&private_key, fee_microcredits, None).unwrap();
// Deploy the program to the network
program_manager.deploy_program(program_name, fee_microcredits, Some(fee_record), Some("password")).unwrap();
// Wait several minutes.. then check the program exists on the network
let api_client = AleoAPIClient::<Testnet3>::testnet3();
let program_on_chain = api_client.get_program(program_name).unwrap();
let program_on_chain_name = program_on_chain.id().to_string();
assert_eq!(&program_on_chain_name, program_name);
// ------------------
// TRANSFER STEPS
// ------------------
// Create a recipient (in practice, the recipient would send their address to the sender)
let recipient_key = PrivateKey::<Testnet3>::new(&mut rng).unwrap();
let recipient_address = Address::try_from(recipient_key).unwrap();
// Create amount and fee (both in units of microcredits)
let amount = 30000;
let fee = 100;
// Find records to fund the transfer
let (amount_record, fee_record) = record_finder.find_amount_and_fee_records(amount, fee, &private_key).unwrap();
// Create a transfer
program_manager.transfer(amount, fee, recipient_address, TransferType::Private, Some("password"), Some(amount_record), Some(fee_record)).unwrap();
This API is currently under active development and is expected to change in the future in order to provide a more streamlined experience for program execution and deployment.
Re-exports§
pub use snarkvm_types::*;
Modules§
- Tools for working with Aleo Accounts
- API clients for interacting with Aleo Network endpoints
- Tools for deploying, executing, and managing programs on the Aleo network
- Re-export of crucial types from the snarkVM crate
Structs§
- Aleo API client for interacting with the Aleo Beacon API
- Tool for encrypting and decrypting Aleo key material into ciphertext
- Program management object for loading programs for building, execution, and deployment
- Helper struct for finding records on chain during program development
Enums§
- The possible states of a program on chain as compared to the local program of the same name
- Transfer Type to Perform
Traits§
- A trait providing convenient methods for accessing the amount of Aleo present in a record