Struct Client 

pub struct Client { /* private fields */ }

Client for the Autonomi decentralized network.

Provides high-level APIs for storing and retrieving chunks and files on the network.

Implementations

impl Client

pub async fn prepare_chunk_payment( &self, content: Bytes, ) -> Result<Option<PreparedChunk>>

Prepare a single chunk for batch payment.

Collects quotes and uses node-reported prices without making any on-chain transaction. Returns Ok(None) if the chunk is already stored on the network.

Errors

Returns an error if quote collection or payment construction fails.

pub async fn batch_pay( &self, prepared: Vec<PreparedChunk>, ) -> Result<(Vec<PaidChunk>, String, u128)>

Pay for multiple chunks in a single EVM transaction.

Flattens all quote payments from the prepared chunks into one wallet.pay_for_quotes() call, then maps transaction hashes back to per-chunk PaymentProof bytes.

Errors

Returns an error if the wallet is not configured or the on-chain payment fails. Returns (paid_chunks, storage_cost_atto, gas_cost_wei).

pub async fn batch_upload_chunks( &self, chunks: Vec<Bytes>, ) -> Result<(Vec<XorName>, String, u128)>

Upload chunks in waves with pipelined EVM payments.

Processes chunks in waves of PAYMENT_WAVE_SIZE (64). Within each wave:

1. Prepare: collect quotes for all chunks concurrently
2. Pay: single EVM transaction for the whole wave
3. Store: concurrent chunk replication to close group

Stores from wave N overlap with quote collection for wave N+1 via tokio::join!.

Errors

Returns an error if any payment or store operation fails. Returns (addresses, total_storage_cost_atto, total_gas_cost_wei).

pub async fn batch_upload_chunks_with_events( &self, chunks: Vec<Bytes>, progress: Option<&Sender<UploadEvent>>, stored_offset: usize, file_total: usize, ) -> Result<(Vec<XorName>, String, u128)>

Same as Client::batch_upload_chunks but sends UploadEvent::ChunkStored events as each chunk is stored, enabling per-chunk progress bars.

stored_offset is the number of chunks already stored in previous waves (so events report cumulative progress). file_total is the total chunk count across ALL waves (for the total field in events).

impl Client

pub async fn chunk_put(&self, content: Bytes) -> Result<XorName>

Store a chunk on the Autonomi network with payment.

Checks if the chunk already exists before paying. If it does, returns the address immediately without incurring on-chain costs. Otherwise collects quotes, pays on-chain, then stores with proof to CLOSE_GROUP_MAJORITY peers.

Errors

Returns an error if payment or the network operation fails.

pub async fn chunk_put_with_proof( &self, content: Bytes, proof: Vec<u8>, target_peer: &PeerId, peer_addrs: &[MultiAddr], ) -> Result<XorName>

Store a chunk on the Autonomi network with a pre-built payment proof.

Sends to a single peer. Callers that need replication across the close group should use chunk_put_to_close_group instead.

Errors

Returns an error if the network operation fails.

pub async fn chunk_get(&self, address: &XorName) -> Result<Option<DataChunk>>

Retrieve a chunk from the Autonomi network.

Queries all peers in the close group for the chunk address, returning the first successful response. This handles the case where the storing peer differs from the first peer returned by DHT routing.

Errors

Returns an error if the network operation fails.

pub async fn build_peer_pool_for( &self, addresses: &[XorName], ) -> Result<PeerPool>

Build a reusable pool of peers suitable for fetching any chunk in addresses.

Performs ONE close-group lookup at the median address of the batch and returns the resulting peer set. On a network where find_closest_peers dominates per-chunk wall-clock (e.g. live Autonomi mainnet today), reusing this pool across many GETs via chunk_get_with_pool gives a measured ~1.5x speedup on 32-chunk downloads and grows with batch size.

The pool is “best-effort”: peers are the close group of the median XorName, which closely overlaps the close group of any nearby address. Chunks whose actual close group has rotated can still be fetched via the per-chunk fallback in chunk_get_with_pool.

Errors

Returns an error if addresses is empty or if the DHT lookup fails.

pub async fn chunk_get_with_pool( &self, address: &XorName, pool: &PeerPool, ) -> Result<Option<DataChunk>>

Fetch a chunk, trying the supplied pool’s peers first.

Falls back to a per-chunk close-group lookup if none of the pool peers have the chunk (or all pool peers are unreachable). Pair with build_peer_pool_for to amortize a single DHT walk across many GETs.

Cache, integrity verification, and per-peer outcome reporting behave identically to chunk_get.

Errors

Returns an error if all peers (pool + fallback close group) fail with non-recoverable errors.

pub async fn chunk_exists(&self, address: &XorName) -> Result<bool>

Check if a chunk exists on the network.

Errors

Returns an error if the network operation fails.

impl Client

pub async fn data_upload(&self, content: Bytes) -> Result<DataUploadResult>

Upload in-memory data to the network using self-encryption.

The content is encrypted and split into chunks, each stored as a content-addressed chunk on the network. Returns a DataMap that can be used to retrieve and decrypt the data.

Errors

Returns an error if encryption fails or any chunk cannot be stored.

pub async fn data_upload_with_mode( &self, content: Bytes, mode: PaymentMode, ) -> Result<DataUploadResult>

Upload in-memory data with a specific payment mode.

When mode is Auto and the chunk count >= threshold, or when mode is Merkle, this buffers all chunks and pays via a single merkle batch transaction. Otherwise falls back to per-chunk payment.

Errors

Returns an error if encryption fails or any chunk cannot be stored.

pub async fn data_prepare_upload( &self, content: Bytes, ) -> Result<PreparedUpload>

Phase 1 of external-signer data upload: encrypt and collect quotes.

Encrypts in-memory data via self-encryption, then collects storage quotes for each chunk without making any on-chain payment. Returns a PreparedUpload containing the data map and a PaymentIntent with the payment details for external signing.

After the caller signs and submits the payment transaction, call Client::finalize_upload with the tx hashes to complete storage.

Errors

Returns an error if encryption fails or quote collection fails.

pub async fn data_map_store(&self, data_map: &DataMap) -> Result<[u8; 32]>

Store a DataMap on the network as a public chunk.

The serialized DataMap is stored as a regular content-addressed chunk. Anyone who knows the returned address can retrieve and use the DataMap to download the original data.

Errors

Returns an error if serialization or the chunk store fails.

pub async fn data_map_fetch(&self, address: &[u8; 32]) -> Result<DataMap>

Fetch a DataMap from the network by its chunk address.

Retrieves the chunk at address and deserializes it as a DataMap.

Errors

Returns an error if the chunk is not found or deserialization fails.

pub async fn data_download(&self, data_map: &DataMap) -> Result<Bytes>

Download and decrypt data from the network using its DataMap.

Retrieves all chunks referenced by the data map, then decrypts and reassembles the original content. Fetches chunks concurrently; the fan-out is sized by the adaptive controller’s fetch channel and ramps up under healthy conditions.

Errors

Returns an error if any chunk cannot be retrieved or decryption fails.

impl Client

pub async fn file_upload(&self, path: &Path) -> Result<FileUploadResult>

Upload a file to the network using streaming self-encryption.

Automatically selects merkle batch payment for files that produce 64+ chunks (saves gas). Encrypted chunks are spilled to a temp directory so peak memory stays at ~256 MB regardless of file size.

Errors

Returns an error if the file cannot be read, encryption fails, or any chunk cannot be stored.

pub async fn estimate_upload_cost( &self, path: &Path, mode: PaymentMode, progress: Option<Sender<UploadEvent>>, ) -> Result<UploadCostEstimate>

Estimate the cost of uploading a file without actually uploading.

Encrypts the file to determine chunk count and sizes, then requests a single quote from the network for a representative chunk. The per-chunk price is extrapolated to the total chunk count.

The estimate is fast (~2-5s) and does not require a wallet. Spilled chunks are cleaned up automatically when the function returns.

Gas cost is an advisory heuristic, not a live gas-oracle query. It is derived from realistic per-transaction budgets (GAS_PER_WAVE_TX, GAS_PER_MERKLE_TX) priced at ARBITRUM_GAS_PRICE_WEI. Real gas varies with network conditions.

If the first sampled chunk is already stored on the network, the function retries with subsequent chunk addresses (up to ESTIMATE_SAMPLE_CAP). If every sampled address reports stored, a Error::CostEstimationInconclusive is returned so callers can decide how to react rather than trust a bogus “free” estimate. Only when every address in the file is stored do we return a zero-cost estimate.

Errors

Returns an error if the file cannot be read, encryption fails, the network cannot provide a quote, or every sampled chunk is already stored (Error::CostEstimationInconclusive).

pub async fn file_prepare_upload(&self, path: &Path) -> Result<PreparedUpload>

Phase 1 of external-signer upload: encrypt file and prepare chunks.

Equivalent to Client::file_prepare_upload_with_visibility with Visibility::Private — see that method for details.

pub async fn file_prepare_upload_with_visibility( &self, path: &Path, visibility: Visibility, ) -> Result<PreparedUpload>

Phase 1 of external-signer upload with explicit Visibility control.

Equivalent to Client::file_prepare_upload_with_progress with progress: None — see that method for details.

pub async fn file_prepare_upload_with_progress( &self, path: &Path, visibility: Visibility, progress: Option<Sender<UploadEvent>>, ) -> Result<PreparedUpload>

Phase 1 of external-signer upload with progress events.

Requires an EVM network (for contract price queries) but NOT a wallet. Returns a PreparedUpload containing the data map, prepared chunks, and a PaymentIntent that the external signer uses to construct and submit the on-chain payment transaction.

When visibility is Visibility::Public, the serialized DataMap is bundled into the payment batch as an additional chunk and its address is recorded on the returned PreparedUpload. After Client::finalize_upload (or _merkle) succeeds, that address is surfaced via FileUploadResult::data_map_address so the uploader can share a single address from which anyone can retrieve the file.

When progress is Some, UploadEvents are emitted on the channel during encryption (UploadEvent::Encrypting / UploadEvent::Encrypted) and per-chunk quoting (UploadEvent::ChunkQuoted). Storage events are emitted later by Client::finalize_upload_with_progress / Client::finalize_upload_merkle_with_progress.

Memory note: Encryption uses disk spilling for bounded memory, but the returned PreparedUpload holds all chunk content in memory (each PreparedChunk contains a Bytes with the full chunk data). This is inherent to the two-phase external-signer protocol — the chunks must stay in memory until Client::finalize_upload stores them. For very large files, prefer Client::file_upload which streams directly.

Errors

Returns an error if there is insufficient disk space, the file cannot be read, encryption fails, or quote collection fails.

pub async fn finalize_upload( &self, prepared: PreparedUpload, tx_hash_map: &HashMap<QuoteHash, TxHash>, ) -> Result<FileUploadResult>

Phase 2 of external-signer upload (wave-batch): finalize with externally-signed tx hashes.

Takes a PreparedUpload that used wave-batch payment and a map of quote_hash -> tx_hash provided by the external signer after on-chain payment. Builds payment proofs and stores chunks on the network.

Errors

Returns an error if the prepared upload used merkle payment (use Client::finalize_upload_merkle instead), proof construction fails, or any chunk cannot be stored.

pub async fn finalize_upload_with_progress( &self, prepared: PreparedUpload, tx_hash_map: &HashMap<QuoteHash, TxHash>, progress: Option<Sender<UploadEvent>>, ) -> Result<FileUploadResult>

Phase 2 of external-signer upload (wave-batch) with progress events.

Same as Client::finalize_upload but emits UploadEvent::ChunkStored on the provided channel as each chunk is successfully stored.

Errors

Same as Client::finalize_upload.

pub async fn finalize_upload_merkle( &self, prepared: PreparedUpload, winner_pool_hash: [u8; 32], ) -> Result<FileUploadResult>

Phase 2 of external-signer upload (merkle): finalize with winner pool hash.

Takes a PreparedUpload that used merkle payment and the winner_pool_hash returned by the on-chain merkle payment transaction. Generates proofs and stores chunks on the network.

Errors

Returns an error if the prepared upload used wave-batch payment (use Client::finalize_upload instead), proof generation fails, or any chunk cannot be stored.

pub async fn finalize_upload_merkle_with_progress( &self, prepared: PreparedUpload, winner_pool_hash: [u8; 32], progress: Option<Sender<UploadEvent>>, ) -> Result<FileUploadResult>

Phase 2 of external-signer upload (merkle) with progress events.

Same as Client::finalize_upload_merkle but emits UploadEvent::ChunkStored on the provided channel as each chunk is successfully stored.

Errors

Same as Client::finalize_upload_merkle.

pub async fn file_upload_with_mode( &self, path: &Path, mode: PaymentMode, ) -> Result<FileUploadResult>

Upload a file with a specific payment mode.

Before encryption, checks that the temp directory has enough free disk space for the spilled chunks (~1.1× source file size).

Encrypted chunks are spilled to a temp directory during encryption so that only their 32-byte addresses stay in memory. At upload time, chunks are read back one wave at a time (~64 × 4 MB ≈ 256 MB peak).

Errors

Returns an error if there is insufficient disk space, the file cannot be read, encryption fails, or any chunk cannot be stored.

pub async fn file_upload_with_progress( &self, path: &Path, mode: PaymentMode, progress: Option<Sender<UploadEvent>>, ) -> Result<FileUploadResult>

Upload a file with progress events sent to the given channel.

Same as Client::file_upload_with_mode but sends UploadEvents to the provided channel for UI progress feedback.

pub async fn file_download( &self, data_map: &DataMap, output: &Path, ) -> Result<u64>

Download and decrypt a file from the network, writing it to disk.

Uses streaming_decrypt so that only one batch of chunks lives in memory at a time, avoiding OOM on large files. Chunks are fetched concurrently within each batch, then decrypted data is written to disk incrementally.

Returns the number of bytes written.

Panics

Requires a multi-threaded Tokio runtime (flavor = "multi_thread"). Will panic if called from a current_thread runtime because streaming_decrypt takes a synchronous callback that must bridge back to async via block_in_place.

Errors

Returns an error if any chunk cannot be retrieved, decryption fails, or the file cannot be written.

pub async fn file_download_with_progress( &self, data_map: &DataMap, output: &Path, progress: Option<Sender<DownloadEvent>>, ) -> Result<u64>

Download and decrypt a file with progress events.

Same as Client::file_download but sends DownloadEvents for UI feedback.

Progress reporting:

1. Resolves hierarchical DataMaps to the root level first (reports as ChunksFetched with total: 0 during resolution)
2. Once the root DataMap is known, sends total_chunks with accurate count
3. Fetches data chunks with accurate fetched/total progress

impl Client

pub fn should_use_merkle(&self, chunk_count: usize, mode: PaymentMode) -> bool

Determine whether to use merkle payments for a given batch size.

pub async fn pay_for_merkle_batch( &self, addresses: &[[u8; 32]], data_type: u32, data_size: u64, ) -> Result<MerkleBatchPaymentResult>

Pay for a batch of chunks using merkle batch payment.

Builds a merkle tree, collects candidate pools, pays on-chain in one tx, and returns per-chunk proofs. Splits into sub-batches if > MAX_LEAVES.

Does NOT pre-filter already-stored chunks (nodes handle AlreadyExists gracefully on PUT). This avoids N sequential GET round-trips before payment.

Errors

Returns an error if the batch is too small, candidate collection fails, on-chain payment fails, or proof generation fails.

pub async fn prepare_merkle_batch_external( &self, addresses: &[[u8; 32]], data_type: u32, data_size: u64, ) -> Result<PreparedMerkleBatch>

Phase 1 of external-signer merkle payment: prepare batch without paying.

Builds the merkle tree, collects candidate pools from the network, and returns the data needed for the on-chain payment call. Requires EvmNetwork but NOT a wallet.

impl Client

pub async fn pay_for_storage( &self, address: &[u8; 32], data_size: u64, data_type: u32, ) -> Result<(Vec<u8>, Vec<(PeerId, Vec<MultiAddr>)>)>

Pay for storage and return the serialized payment proof bytes.

This orchestrates the full payment flow:

1. Collect CLOSE_GROUP_SIZE quotes from closest peers
2. Build SingleNodePayment using node-reported prices (median 3x, others 0)
3. Pay on-chain via the wallet
4. Serialize PaymentProof with transaction hashes

Errors

Returns an error if the wallet is not set, quotes cannot be collected, on-chain payment fails, or serialization fails. Returns (proof_bytes, quoted_peers). quoted_peers are the CLOSE_GROUP_SIZE peers that provided quotes — callers should store the chunk to at least CLOSE_GROUP_MAJORITY of these peers.

pub async fn approve_token_spend(&self) -> Result<()>

Approve the wallet to spend tokens on the payment vault contract.

This must be called once before any payments can be made. Approves U256::MAX (unlimited) spending.

Errors

Returns an error if the wallet is not set or the approval transaction fails.

impl Client

pub async fn get_store_quotes( &self, address: &[u8; 32], data_size: u64, data_type: u32, ) -> Result<Vec<(PeerId, Vec<MultiAddr>, PaymentQuote, Amount)>>

Get storage quotes from the closest peers for a given address.

Queries 2x CLOSE_GROUP_SIZE peers from the DHT for fault tolerance, requests quotes from all of them concurrently, and returns the CLOSE_GROUP_SIZE closest successful responders sorted by XOR distance.

Returns Error::AlreadyStored early if CLOSE_GROUP_MAJORITY peers report the chunk is already stored.

Errors

Returns an error if insufficient quotes can be collected.

impl Client

pub fn from_node(node: Arc<P2PNode>, config: ClientConfig) -> Self

Create a client connected to the given P2P node.

pub async fn connect( bootstrap_peers: &[SocketAddr], config: ClientConfig, ) -> Result<Self>

Create a client connected to bootstrap peers.

Threads config.allow_loopback and config.ipv6 through to Network::new, which controls the saorsa-transport local and ipv6 flags on the underlying CoreNodeConfig. See ClientConfig::allow_loopback and ClientConfig::ipv6 for details.

Errors

Returns an error if the P2P node cannot be created or bootstrapping fails.

pub fn with_wallet(self, wallet: Wallet) -> Self

Set the wallet for payment operations.

Also populates the EVM network from the wallet so that token approvals work without a separate with_evm_network call.

pub fn with_evm_network(self, network: Network) -> Self

Set the EVM network without requiring a wallet.

This enables token approval and contract interactions for external-signer flows where the private key lives outside Rust.

pub fn config(&self) -> &ClientConfig

Get the client configuration.

pub fn config_mut(&mut self) -> &mut ClientConfig

Get a mutable reference to the client configuration.

pub fn network(&self) -> &Network

Get a reference to the network layer.

pub fn wallet(&self) -> Option<&Arc<Wallet>>

Get the wallet, if configured.

pub fn chunk_cache(&self) -> &ChunkCache

Get a reference to the chunk cache.

pub fn controller(&self) -> &AdaptiveController

Adaptive concurrency controller. Hot loops read controller().<channel>.current() to size their fan-out and call .observe(...) on each completion.

pub fn save_adaptive_snapshot(&self)

Persist the current adaptive snapshot to disk so the next Client::connect warm-starts at the learned values instead of cold defaults. Best effort — failures log and are discarded. Idempotent. Safe to call from a Drop impl or an explicit shutdown hook.

Trait Implementations

impl Drop for Client

fn drop(&mut self)

Executes the destructor for this type.