# 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:

```toml
[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

```rust
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:

```rust
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

```rust
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:

```rust
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

```rust
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 batch helpers, while `finalize_upload_merkle` completes a prepared upload from the winning pool hash. Progress-aware variants such as `file_prepare_upload_with_progress`, `finalize_upload_with_progress`, and `finalize_upload_merkle_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

```rust
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_batch, .. } => {
            println!("Merkle depth: {}", prepared_batch.depth);
        }
    }

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

## Error handling

```rust
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:

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

```rust
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](/developers/developing-in-rust/rust.md)
* [Build Directly in Rust](/developers/developing-in-rust/build-directly-in-rust.md)
* [Rust SDK](/developers/sdk/install/reference/language-bindings/rust.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.autonomi.com/developers/developing-in-rust/library-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.