Rust `algonaut`

A Rust SDK for the Algorand blockchain. Pre-1.0 — the API is stabilising but still moves between minor versions.

Highlights

Async clients for algod v2, kmd v1, and indexer v2
Transaction builders for payments, asset config / transfer / freeze / clawback, application calls, key registration, and state proofs
ARC-4 ABI types, method invocation, and an AtomicTransactionComposer with simulate + execute
TEAL compile / disassemble + V3 source-map decoder
Cucumber acceptance suite that exercises the algorand-sdk-testing harness end-to-end

Quickstart

use algonaut::algod::v2::Algod;
use algonaut_core::MicroAlgos;
use algonaut_transaction::{Pay, TxnBuilder, account::Account};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let algod = Algod::new(
        "http://localhost:4001",
        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    )?;

    let alice = Account::from_mnemonic(
        "fire enlist diesel stamp nuclear chunk student stumble call snow flock brush \
         example slab guide choice option recall south kangaroo hundred matrix school \
         above zero",
    )?;
    let bob = "2FMLYJHYQWRHMFKRHKTKX5UNB5DGO65U57O3YVLWUJWKRE4YYJYC2CWWBY".parse()?;

    let params = algod.txn_params().await?;
    let tx = TxnBuilder::with(
        &params,
        Pay::new(alice.address(), bob, MicroAlgos(123_456)).build(),
    )
    .build()?;

    let signed = alice.sign_transaction(tx)?;
    let resp = algod.send_txn(&signed).await?;
    println!("submitted: {}", resp.tx_id);
    Ok(())
}

Workspace layout

Crate	Purpose
`algonaut`	Top-level convenience crate; re-exports the rest
`algonaut_algod`	Generated client for the algod v2 REST API
`algonaut_kmd`	Client for the key-management daemon
`algonaut_indexer`	Client for the indexer v2 REST API
`algonaut_core`	Core types: `Address`, `MicroAlgos`, `Round`, keys, multisig
`algonaut_crypto`	Ed25519 sign/verify (via `ed25519-dalek`) and BIP-39 mnemonics
`algonaut_transaction`	Transaction builders and the `AtomicTransactionComposer`
`algonaut_abi`	ARC-4 ABI types, method encoding, TEAL source-map decoder
`algonaut_encoding`	Shared `serde` visitors and base32/base64 helpers
`algonaut_model`	Hand-written response models shared between the clients

Running the examples

/examples has a wide set of runnable programs.

cp examples.env .env       # ALGOD_URL, KMD_URL, INDEXER_URL, mnemonics
cargo run --example quickstart

If you see Error: NotPresent, your environment variables aren't set — cp examples.env .env and edit as needed.

Running the test suite

make setup           # rustfmt + clippy + lefthook hooks
make ci              # fmt-check, clippy, unit tests, build, integration compile-check
./test-harness.sh up # boot a local algorand sandbox (ports 60000/60001/60002)
make integration     # run the cucumber suite against the sandbox

See docs/adr/ for the architectural decisions behind the cross-SDK cucumber wiring, the simulate / dryrun builders, the V3 source-map decoder, and the dual-format (JSON/msgpack) domain-type serialization.

Changelog

See CHANGELOG.md.

Contributing

Read the contribution guidelines before opening a PR. The pre-commit hook runs make ci; commit messages follow Conventional Commits.

Acknowledgements

This crate is based on the work of @mraof.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Asset attribution

Ferris Algonaut is licensed under a Creative Commons Attribution 4.0 International License. Rust algonaut's logo is based on Font Awesome's icon and licensed under a Creative Commons Attribution 4.0 International License.

algonaut 0.6.0

Rust algonaut