Rust Library Reference

ant-core is the native Rust library for building directly on Autonomi without the daemon.

Install

Use ant-core as a local dependency from an ant-client checkout:

[dependencies]
ant-core = { path = "../ant-client/ant-core" }
bytes = "1"
tokio = { version = "1", features = ["full"] }

For same-machine devnets or local testnets, set ClientConfig { allow_loopback: true, ..ClientConfig::default() } before Client::connect. Keep the default false on public networks.

Connect to the network

use ant_core::data::{Client, ClientConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect(&["1.2.3.4:12000".parse()?], ClientConfig::default()).await?;
    let _ = client;
    Ok(())
}

To enable paid operations, attach a wallet:

use ant_core::data::{Client, ClientConfig, EvmNetwork, Wallet};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect(&["1.2.3.4:12000".parse()?], ClientConfig::default()).await?;
    let wallet = Wallet::new_from_private_key(EvmNetwork::ArbitrumOne, "0xprivate_key...")?;
    let client = client.with_wallet(wallet);
    client.approve_token_spend().await?;
    Ok(())
}

Store and retrieve data

use ant_core::data::{Client, ClientConfig, EvmNetwork, Wallet};
use bytes::Bytes;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect(&["1.2.3.4:12000".parse()?], ClientConfig::default()).await?;
    let wallet = Wallet::new_from_private_key(EvmNetwork::ArbitrumOne, "0xprivate_key...")?;
    let client = client.with_wallet(wallet);
    client.approve_token_spend().await?;

    let result = client.data_upload(Bytes::from("hello autonomi")).await?;
    let content = client.data_download(&result.data_map).await?;

    assert_eq!(content, Bytes::from("hello autonomi"));
    Ok(())
}

To make uploaded data publicly retrievable by address, store and later fetch the DataMap:

use ant_core::data::{Client, ClientConfig, EvmNetwork, Wallet};
use bytes::Bytes;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect(&["1.2.3.4:12000".parse()?], ClientConfig::default()).await?;
    let wallet = Wallet::new_from_private_key(EvmNetwork::ArbitrumOne, "0xprivate_key...")?;
    let client = client.with_wallet(wallet);
    client.approve_token_spend().await?;

    let result = client.data_upload(Bytes::from("hello autonomi")).await?;

    let public_address = client.data_map_store(&result.data_map).await?;
    let public_data_map = client.data_map_fetch(&public_address).await?;
    let downloaded = client.data_download(&public_data_map).await?;

    assert_eq!(downloaded, Bytes::from("hello autonomi"));
    Ok(())
}

File operations

use ant_core::data::{Client, ClientConfig, EvmNetwork, PaymentMode, Wallet};
use std::path::Path;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect(&["1.2.3.4:12000".parse()?], ClientConfig::default()).await?;
    let wallet = Wallet::new_from_private_key(EvmNetwork::ArbitrumOne, "0xprivate_key...")?;
    let client = client.with_wallet(wallet);
    client.approve_token_spend().await?;

    let result = client.file_upload_with_mode(Path::new("photo.jpg"), PaymentMode::Merkle).await?;
    let address = client.data_map_store(&result.data_map).await?;
    let data_map = client.data_map_fetch(&address).await?;
    client.file_download(&data_map, Path::new("photo_copy.jpg")).await?;
    Ok(())
}

External signer flows

The native Rust library exposes both wave-batch and Merkle-batch external payment helpers.

For wave-batch uploads, data_prepare_upload, data_prepare_upload_with_visibility, file_prepare_upload, and finalize_upload prepare the upload, collect quotes, and later store the chunks after an external signer returns transaction hashes. Use data_prepare_upload_with_visibility(content, Visibility::Public) to bundle the DataMap chunk into the same payment batch and receive its network address in the FileUploadResult after finalize.

For Merkle batches, prepare_merkle_batch_external and finalize_merkle_batch expose the low-level single-batch helpers, while finalize_upload_merkle completes a prepared upload from one winning pool hash. An upload larger than a single Merkle tree (256 fresh chunks, roughly 1 GiB) spans several batches: prepare_merkle_batches_external returns the batches to pay, and finalize_upload_merkle_multi completes the upload from a Vec of per-batch winner-hash entries aligned to those batches — one entry per batch, in order, with None marking a batch the signer did not pay. At least one batch must be paid, or the call returns a payment error; the chunks of an unpaid batch surface through the partial-upload error once the paid batches store. Progress-aware variants such as file_prepare_upload_with_progress, finalize_upload_with_progress, finalize_upload_merkle_with_progress, and finalize_upload_merkle_multi_with_progress are also available when you need UI feedback during long-running uploads.

Key types

Type	Description
ant_core::data::Client	Main network client
ant_core::data::ClientConfig	Quote, Merkle batch store (merkle_store_timeout_secs, 270 s default), and chunk retrieve (chunk_get_timeout_secs) timeouts; concurrency limits; loopback policy. Non-Merkle chunk PUT response timeout is set by an internal STORE_RESPONSE_TIMEOUT constant, not via this struct.
ant_core::data::PaymentMode	Auto, Merkle, or Single
ant_core::data::DataMap	Private retrieval map for uploaded data
ant_core::data::LocalDevnet	Local development helper
ant_core::data::Wallet	EVM wallet used for paid operations
ant_core::data::PreparedUpload	Two-phase upload state used by external-signer flows
ant_core::data::ExternalPaymentInfo	External payment details for prepared uploads
ant_core::data::PreparedMerkleBatch	Prepared Merkle batch data for external signing
ant_core::data::Visibility	Upload visibility: Private (DataMap returned to caller) or Public (DataMap bundled into payment batch and stored on-network)

External signer example

use ant_core::data::{Client, ClientConfig, ExternalPaymentInfo};
use bytes::Bytes;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect(&["1.2.3.4:12000".parse()?], ClientConfig::default()).await?;
    let prepared = client.data_prepare_upload(Bytes::from("hello autonomi")).await?;

    match &prepared.payment_info {
        ExternalPaymentInfo::WaveBatch { payment_intent, .. } => {
            println!("Need to pay {} atto", payment_intent.total_amount);
        }
        ExternalPaymentInfo::Merkle { prepared_batches, .. } => {
            println!("Merkle batches: {}", prepared_batches.len());
        }
    }

    let tx_hashes: HashMap<_, _> = HashMap::new();
    let _ = tx_hashes;
    Ok(())
}

Error handling

use ant_core::data::{Client, ClientConfig, Error};
use bytes::Bytes;

#[tokio::main]
async fn main() {
    let client = Client::connect(&["1.2.3.4:12000".parse().unwrap()], ClientConfig::default())
        .await
        .unwrap();

    match client.data_upload(Bytes::from("hello")).await {
        Ok(result) => println!("{}", result.chunks_stored),
        Err(Error::Payment(message)) => println!("{message}"),
        Err(Error::InsufficientPeers(message)) => println!("{message}"),
        Err(error) => println!("{error}"),
    }
}

Local development

The library also exports LocalDevnet for local development flows:

Enable the ant-core devnet feature before you use this section:

[dependencies]
ant-core = { path = "../ant-client/ant-core", features = ["devnet"] }

use ant_core::data::LocalDevnet;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut devnet = LocalDevnet::start_minimal().await?;
    let client = devnet.create_funded_client().await?;
    let _ = client;
    devnet.shutdown().await?;
    Ok(())
}

Related pages

• Developing in Rust

• Build Directly in Rust

• Rust SDK