Aleo Rust SDK

English | 中文

A Rust SDK for interacting with the Aleo blockchain — account management, program loading, local execution with zero-knowledge proof generation, network querying, and transaction broadcasting.

Why this SDK? The official ProvableHQ/aleo-rust has been archived and is no longer maintained. This SDK provides an up-to-date implementation using snarkVM 4.10.0 and the current Aleo testnet v2 JSON-RPC endpoints.

Table of Contents

• Packages
• Features
• Architecture
• Installation
• Quick Start
• Examples
• Roadmap
• CLI Tools
• Related Projects
• Development
• Contributing
• License

Packages

The CLI tool aleo-cli is a separate crate that consumes this SDK.

Features

Architecture

┌─────────────────────────────────────────────────────┐
│                    AleoClient                        │
│   (high-level orchestrator — account, program,       │
│    execute, prove, broadcast in one place)           │
├──────────┬──────────┬──────────┬──────────────────────┤
│  account │  program │ execution│      network         │
│  │        │         │          │                     │
│  │        │         │          │  AleoHttpClient      │
│ PK → VK  │ parse    │ auth     │  ├─ REST (v2)       │
│ CK → ADDR│ inspect  │ execute  │  ├─ JSON-RPC        │
│  │        │ from_net │ prove    │  └─ broadcast       │
│  ▼        │  ▼       │  ▼      │       ▼            │
├──────────┴──────────┴──────────┴──────────────────────┤
│  record                                                │
│  AleoRecord · RecordScanner · RecordManager · CoinSel  │
├────────────────────────────────────────────────────────┤
│              snarkVM 4.10.0 (Process<TestnetV0>)       │
│          reqwest (async HTTP) — tokio runtime         │
└──────────────────────────────────────────────────────┘

Installation

Add to your Cargo.toml:

[dependencies]
aleo-rust-sdk = "0.2.0"
tokio = { version = "1", features = ["full"] }

Requirements:

• Rust 1.85+
• snarkVM 4.10.0 (automatically resolved)
• For proving: ~16 GB RAM recommended

Quick Start

Query testnet (no account needed)

use aleo_rust_sdk::AleoClient;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = AleoClient::new("https://api.explorer.provable.com/v2/testnet")?;

    let height = client.get_block_height().await?;
    let root = client.get_state_root().await?;
    println!("Block height: {height}");
    println!("State root:   {root}");

    Ok(())
}

Generate an account and fetch balance

use aleo_rust_sdk::{AleoClient, AleoAccount};
use snarkvm::prelude::TestRng;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut rng = TestRng::default();
    let mut client = AleoClient::new("https://api.explorer.provable.com/v2/testnet")?;

    // Create a random account
    let account = AleoAccount::new_random(&mut rng)?;
    println!("Address: {}", account.address_str());

    // Set the account on the client
    client.set_account_from_private_key_str(&account.private_key_str())?;

    // Query testnet
    let height = client.get_block_height().await?;
    println!("Block height: {height}");

    // Fetch balance (None if account has no credits)
    let balance = client.get_balance().await?;
    match balance {
        Some(b) => println!("Balance: {b} microcredits"),
        None => println!("No credits found (new account)"),
    }

    Ok(())
}

Full end-to-end transfer pipeline

use aleo_rust_sdk::AleoClient;
use snarkvm::{prelude::TestRng, console::program::ProgramID};
use std::str::FromStr;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut client = AleoClient::new("https://api.explorer.provable.com/v2/testnet")?;
    client.set_account_from_private_key_str("APrivateKey1...")?;

    let transfer_id = client.execute_and_broadcast(
        &client.require_account()?.private_key,
        &ProgramID::from_str("credits.aleo")?,
        "transfer_private",
        vec!["aleo1recipient...", "1000000u64"],
        1000,   // base fee (microcredits)
        0,      // priority fee
    ).await?;

    println!("Transaction: {transfer_id}");
    println!("🔗 https://testnet.explorer.provable.com/transaction/{transfer_id}");
    Ok(())
}

Examples

Run an example:

# Query testnet state (no private key required)
cargo run --example testnet_query

# Full transfer (requires PRIVATE_KEY env var)
export PRIVATE_KEY="APrivateKey1..."
cargo run --example testnet_transfer

# Local dry-run execution
cargo run --example simple_execute

Roadmap

Planned features (in order of priority):

• WASM support — compile SDK for browser/Node.js via wasm-pack
• Transaction history — fetch and decode historical transactions
• Program deployment — deploy and upgrade Aleo programs from Rust
• Mainnet support — add mainnet configuration alongside testnet
• Record merging — join multiple small records into a single larger record
• Batch transfers — send multiple transfers in one transaction
• Type-safe program bindings — generate Rust structs from Aleo program mappings

CLI Tools

The aleo-cli command-line tool is built on top of this SDK:

# Install
cargo install aleo-cli

# Query testnet status
aleo-cli query

# Check account balance
aleo-cli balance aleo1cu0xk4tt99pgxglpqltzk3tmpgh7qftjwukxcmewzpy0fkqghvgsxu0g03

# Generate a new Aleo account
aleo-cli generate

# Send a private transfer
aleo-cli transfer --amount 1.5 --to aleo1recipient...

Related Projects

Development

git clone https://github.com/qiaopengjun5162/aleo-rust-sdk.git
cd aleo-rust-sdk

# Build
just build            # cargo build --all-features
just build-release    # release build

# Test
just test             # cargo nextest run --all-features

# Lint
just check            # cargo check --all-features
just clippy           # cargo clippy -- -D warnings
just format           # cargo fmt --all -- --check

# Generate docs
just docs             # cargo doc --no-deps --open

# Full check suite
just all              # format + check + clippy + test

See CONTRIBUTING.md for detailed guidelines.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on reporting bugs, suggesting features, and submitting code changes.

License

Licensed under either MIT License or Apache-2.0 at your option.