Struct Client 

pub struct Client { /* private fields */ }

Represents a client for the Autonomi network.

Example

To start interacting with the network, use Client::init.

let client = Client::init().await?;

Implementations

impl Client

pub async fn chunk_get(&self, addr: &ChunkAddress) -> Result<Chunk, GetError>

Get a chunk from the network.

pub async fn chunk_put( &self, chunk: &Chunk, payment_option: PaymentOption, ) -> Result<(AttoTokens, ChunkAddress), PutError>

Manually upload a chunk to the network. It is recommended to use the Client::data_put method instead to upload data.

pub async fn chunk_cost( &self, addr: &ChunkAddress, ) -> Result<AttoTokens, CostError>

Get the cost of a chunk.

pub async fn chunk_batch_upload( &self, chunks: Vec<&Chunk>, receipt: &Receipt, ) -> Result<(), PutError>

Upload chunks in batches to the network. This is useful for pre-calculated payment proofs, in case of manual encryption or re-uploading certain chunks that were already paid for.

This method requires a vector of chunks to be uploaded and the payment receipt. It returns a PutError for failures and Ok(()) for successful uploads.

Example

// Step 1: Encrypt your data using self-encryption
let (data_map, chunks) = autonomi::self_encryption::encrypt("Hello, World!".into())?;

// Step 2: Collect all chunks (datamap + content chunks)
let mut all_chunks = vec![&data_map];
all_chunks.extend(chunks.iter());

// Step 3: Get storage quotes for all chunks
let quote = client.get_store_quotes(
    DataTypes::Chunk,
    all_chunks.iter().map(|chunk| (*chunk.address().xorname(), chunk.size())),
).await?;

// Step 4: Pay for all chunks at once and get receipt
wallet.pay_for_quotes(quote.payments()).await.map_err(|err| err.0)?;
let receipt = autonomi::client::payment::receipt_from_store_quotes(quote);

// Step 5: Upload all chunks with the payment receipt
client.chunk_batch_upload(all_chunks, &receipt).await?;

impl Client

pub async fn graph_entry_get( &self, address: &GraphEntryAddress, ) -> Result<GraphEntry, GraphError>

Fetches a GraphEntry from the network.

pub async fn graph_entry_check_existence( &self, address: &GraphEntryAddress, ) -> Result<bool, GraphError>

Check if a graph_entry exists on the network This method is much faster than Client::graph_entry_get This may fail if called immediately after creating the graph_entry, as nodes sometimes take longer to store the graph_entry than this request takes to execute!

pub async fn graph_entry_put( &self, entry: GraphEntry, payment_option: PaymentOption, ) -> Result<(AttoTokens, GraphEntryAddress), GraphError>

Manually puts a GraphEntry to the network.

pub async fn graph_entry_cost( &self, key: &PublicKey, ) -> Result<AttoTokens, CostError>

Get the cost to create a GraphEntry

impl Client

pub async fn pointer_get( &self, address: &PointerAddress, ) -> Result<Pointer, PointerError>

Get a pointer from the network

pub async fn pointer_check_existence( &self, address: &PointerAddress, ) -> Result<bool, PointerError>

Check if a pointer exists on the network This method is much faster than Client::pointer_get This may fail if called immediately after creating the pointer, as nodes sometimes take longer to store the pointer than this request takes to execute!

pub fn pointer_verify(pointer: &Pointer) -> Result<(), PointerError>

Verify a pointer

pub async fn pointer_put( &self, pointer: Pointer, payment_option: PaymentOption, ) -> Result<(AttoTokens, PointerAddress), PointerError>

Manually store a pointer on the network

pub async fn pointer_create( &self, owner: &SecretKey, target: PointerTarget, payment_option: PaymentOption, ) -> Result<(AttoTokens, PointerAddress), PointerError>

Create a new pointer on the network.

Make sure that the owner key is not already used for another pointer as each key is associated with one pointer

pub async fn pointer_update( &self, owner: &SecretKey, target: PointerTarget, ) -> Result<(), PointerError>

Update an existing pointer to point to a new target on the network.

The pointer needs to be created first with Client::pointer_put. This operation is free as the pointer was already paid for at creation. Only the latest version of the pointer is kept on the Network, previous versions will be overwritten and unrecoverable.

pub async fn pointer_update_from( &self, current: &Pointer, owner: &SecretKey, new_target: PointerTarget, ) -> Result<Pointer, PointerError>

Update an existing pointer from a specific pointer

This will increment the counter of the pointer and update the target This function is used internally by Client::pointer_update after the pointer has been retrieved from the network. To skip the retrieval step if you already have the pointer, use this function directly This function will return the new pointer after it has been updated

pub async fn pointer_cost( &self, key: &PublicKey, ) -> Result<AttoTokens, CostError>

Calculate the cost of storing a pointer

impl Client

pub async fn scratchpad_get_from_public_key( &self, public_key: &PublicKey, ) -> Result<Scratchpad, ScratchpadError>

Get Scratchpad from the Network. A Scratchpad is stored at the owner’s public key so we can derive the address from it.

pub async fn scratchpad_get( &self, address: &ScratchpadAddress, ) -> Result<Scratchpad, ScratchpadError>

Get Scratchpad from the Network

pub async fn scratchpad_check_existence( &self, address: &ScratchpadAddress, ) -> Result<bool, ScratchpadError>

Check if a scratchpad exists on the network This method is much faster than Client::scratchpad_get This may fail if called immediately after creating the scratchpad, as nodes sometimes take longer to store the scratchpad than this request takes to execute!

pub fn scratchpad_verify(scratchpad: &Scratchpad) -> Result<(), ScratchpadError>

Verify a scratchpad

pub async fn scratchpad_put( &self, scratchpad: Scratchpad, payment_option: PaymentOption, ) -> Result<(AttoTokens, ScratchpadAddress), ScratchpadError>

Manually store a scratchpad on the network

pub async fn scratchpad_create( &self, owner: &SecretKey, content_type: u64, initial_data: &Bytes, payment_option: PaymentOption, ) -> Result<(AttoTokens, ScratchpadAddress), ScratchpadError>

Create a new scratchpad to the network.

Make sure that the owner key is not already used for another scratchpad as each key is associated with one scratchpad. The data will be encrypted with the owner key before being stored on the network. The content type is used to identify the type of data stored in the scratchpad, the choice is up to the caller.

Returns the cost and the address of the scratchpad.

pub async fn scratchpad_update( &self, owner: &SecretKey, content_type: u64, data: &Bytes, ) -> Result<(), ScratchpadError>

Update an existing scratchpad to the network. The scratchpad needs to be created first with Client::scratchpad_create. This operation is free as the scratchpad was already paid for at creation. Only the latest version of the scratchpad is kept on the Network, previous versions will be overwritten and unrecoverable.

pub async fn scratchpad_update_from( &self, current: &Scratchpad, owner: &SecretKey, content_type: u64, data: &Bytes, ) -> Result<Scratchpad, ScratchpadError>

Update an existing scratchpad from a specific scratchpad

This will increment the counter of the scratchpad and update the content This function is used internally by Client::scratchpad_update after the scratchpad has been retrieved from the network. To skip the retrieval step if you already have the scratchpad, use this function directly This function will return the new scratchpad after it has been updated

pub async fn scratchpad_put_update( &self, scratchpad: Scratchpad, ) -> Result<(), ScratchpadError>

Store a fully formed, pre-signed scratchpad verbatim after verification. This method is intended for updates and does not require payment.

Preconditions:

• The scratchpad must already exist on the network
• The scratchpad signature must be valid (checked by scratchpad_verify)

The scratchpad is stored as-is with no counter increment, re-encryption, or re-signing.

pub async fn scratchpad_cost( &self, owner: &PublicKey, ) -> Result<AttoTokens, CostError>

Get the cost of creating a new Scratchpad

impl Client

pub async fn data_get(&self, data_map: &DataMapChunk) -> Result<Bytes, GetError>

Fetch a blob of (private) data from the network. In-memory only - fails for large files. Use file_download for large files that need streaming.

Example

use autonomi::{Client, Bytes};
let data_fetched = client.data_get(&data_map).await?;

pub async fn data_stream( &self, data_map: &DataMapChunk, ) -> Result<DataStream, GetError>

Stream a blob of (private) data from the network. Returns an Iterator that yields chunks progressively. Use this for large blobs of data like videos to avoid loading everything into memory.

Example

use autonomi::Client;
let stream = client.data_stream(&data_map).await?;
for chunk_result in stream {
    let chunk = chunk_result?;
    // Process chunk...
}

pub async fn data_put( &self, data: Bytes, payment_option: PaymentOption, ) -> Result<(AttoTokens, DataMapChunk), PutError>

Upload a piece of private data to the network. This data will be self-encrypted. The DataMapChunk is not uploaded to the network, keeping the data private.

Returns the DataMapChunk containing the map to the encrypted chunks.

Example

use autonomi::{Client, Bytes};
let data = Bytes::from("Hello, World");
let (total_cost, data_map) = client.data_put(data, wallet).await?;
let data_fetched = client.data_get(&data_map).await?;
assert_eq!(data, data_fetched);

impl Client

pub async fn data_get_public( &self, addr: &DataAddress, ) -> Result<Bytes, GetError>

Fetch a blob of public data from the network. In-memory only - fails for large files. Use file_download_public for large files that need streaming.

pub async fn data_stream_public( &self, addr: &DataAddress, ) -> Result<DataStream, GetError>

Stream a blob of public data from the network. Returns an Iterator that yields chunks progressively. Use this for large blobs of data like videos to avoid loading everything into memory.

Example

use autonomi::Client;
let stream = client.data_stream_public(&addr).await?;
for chunk_result in stream {
    let chunk = chunk_result?;
    // Process chunk...
}

pub async fn data_put_public( &self, data: Bytes, payment_option: PaymentOption, ) -> Result<(AttoTokens, DataAddress), PutError>

Upload a piece of data to the network. This data is publicly accessible.

Returns the Data Address at which the data was stored.

pub async fn data_cost(&self, data: Bytes) -> Result<AttoTokens, CostError>

Get the estimated cost of storing a piece of data.

pub async fn get_cost_estimation( &self, content_addrs: Vec<(XorName, usize)>, ) -> Result<AttoTokens, CostError>

Get the estimated cost of content addresses.

impl Client

pub async fn archive_get( &self, addr: &PrivateArchiveDataMap, ) -> Result<PrivateArchive, GetError>

Fetch a PrivateArchive from the network

pub async fn archive_put( &self, archive: &PrivateArchive, payment_option: PaymentOption, ) -> Result<(AttoTokens, PrivateArchiveDataMap), PutError>

Upload a PrivateArchive to the network

impl Client

pub async fn archive_get_public( &self, addr: &ArchiveAddress, ) -> Result<PublicArchive, GetError>

Fetch an archive from the network

Example

let client = Client::init().await?;
let addr = ArchiveAddress::new(XorName::random(&mut rand::thread_rng()));
let archive = client.archive_get_public(&addr).await?;

pub async fn archive_put_public( &self, archive: &PublicArchive, payment_option: PaymentOption, ) -> Result<(AttoTokens, ArchiveAddress), PutError>

Upload an archive to the network

Example

Create simple archive containing file.txt pointing to random XOR name.

let mut archive = PublicArchive::new();
let data_addr = DataAddress::new(XorName::random(&mut rand::thread_rng()));
archive.add_file(PathBuf::from("file.txt"), data_addr, Metadata::new_with_size(0));
let (cost, address) = client.archive_put_public(&archive, payment).await?;

pub async fn archive_cost( &self, archive: &PublicArchive, ) -> Result<AttoTokens, CostError>

Get the cost to upload an archive

impl Client

pub async fn file_download( &self, data_map: &DataMapChunk, to_dest: PathBuf, ) -> Result<(), DownloadError>

Download private file directly to filesystem. Always uses streaming.

pub async fn dir_download( &self, archive_access: &PrivateArchiveDataMap, to_dest: PathBuf, ) -> Result<(), DownloadError>

Download a private directory from network to local file system

pub async fn dir_content_upload( &self, dir_path: PathBuf, payment_option: PaymentOption, ) -> Result<(AttoTokens, PrivateArchive), UploadError>

Upload the content of all files in a directory to the network. The directory is recursively walked and each file is uploaded to the network.

The datamaps of these (private) files are not uploaded but returned within the PrivateArchive return type.

pub async fn dir_upload( &self, dir_path: PathBuf, payment_option: PaymentOption, ) -> Result<(AttoTokens, PrivateArchiveDataMap), UploadError>

Same as Client::dir_content_upload but also uploads the archive (privately) to the network.

Returns the PrivateArchiveDataMap allowing the private archive to be downloaded from the network.

pub async fn file_content_upload( &self, path: PathBuf, payment_option: PaymentOption, ) -> Result<(AttoTokens, DataMapChunk), UploadError>

Upload the content of a private file to the network. Reads file, splits into chunks, uploads chunks, uploads datamap, returns DataMapChunk (pointing to the datamap)

impl Client

pub async fn file_download_public( &self, data_addr: &DataAddress, to_dest: PathBuf, ) -> Result<(), DownloadError>

Download file from network to local file system

pub async fn dir_download_public( &self, archive_addr: &ArchiveAddress, to_dest: PathBuf, ) -> Result<(), DownloadError>

Download directory from network to local file system

pub async fn dir_content_upload_public( &self, dir_path: PathBuf, payment_option: PaymentOption, ) -> Result<(AttoTokens, PublicArchive), UploadError>

Upload the content of all files in a directory to the network. The directory is recursively walked and each file is uploaded to the network.

The datamaps of these files are uploaded on the network, making the individual files publicly available.

This returns, but does not upload (!),the PublicArchive containing the datamaps of the uploaded files.

pub async fn dir_upload_public( &self, dir_path: PathBuf, payment_option: PaymentOption, ) -> Result<(AttoTokens, ArchiveAddress), UploadError>

Same as Client::dir_content_upload_public but also uploads the archive to the network.

Returns the ArchiveAddress of the uploaded archive.

pub async fn file_content_upload_public( &self, path: PathBuf, payment_option: PaymentOption, ) -> Result<(AttoTokens, DataAddress), UploadError>

Upload the content of a file to the network. Reads file, splits into chunks, uploads chunks, uploads datamap, returns DataAddr (pointing to the datamap)

pub async fn file_cost( &self, path: &PathBuf, ) -> Result<AttoTokens, FileCostError>

Get the cost to upload a file/dir to the network. quick and dirty implementation, please refactor once files are cleanly implemented

impl Client

pub async fn vault_get_user_data( &self, secret_key: &VaultSecretKey, ) -> Result<UserData, UserDataVaultError>

Get the user data from the vault

pub async fn vault_put_user_data( &self, secret_key: &VaultSecretKey, payment_option: PaymentOption, user_data: UserData, ) -> Result<AttoTokens, UserDataVaultError>

Put the user data to the vault

Returns the total cost of the put operation

pub async fn get_user_data_from_vault( &self, secret_key: &VaultSecretKey, ) -> Result<UserData, UserDataVaultError>

👎Deprecated since 0.2.0: Use vault_get_user_data instead

@deprecated Use vault_get_user_data instead. This function will be removed in a future version.

pub async fn put_user_data_to_vault( &self, secret_key: &VaultSecretKey, payment_option: PaymentOption, user_data: UserData, ) -> Result<AttoTokens, UserDataVaultError>

👎Deprecated since 0.2.0: Use vault_put_user_data instead

@deprecated Use vault_put_user_data instead. This function will be removed in a future version.

impl Client

pub async fn vault_get( &self, secret_key: &VaultSecretKey, ) -> Result<(Bytes, VaultContentType), VaultError>

Retrieves and returns a decrypted vault if one exists.

Returns the content type of the bytes in the vault.

pub async fn vault_cost( &self, owner: &VaultSecretKey, max_size: u64, ) -> Result<AttoTokens, VaultError>

Get the cost of creating a new vault A quick estimation of cost: num_of_graph_entry * graph_entry_cost + num_of_scratchpad * scratchpad_cost

pub async fn vault_put( &self, data: Bytes, payment_option: PaymentOption, secret_key: &VaultSecretKey, content_type: VaultContentType, ) -> Result<AttoTokens, VaultError>

Put data into the client’s VaultPacket

Dynamically expand the vault capacity by paying for more space (Scratchpad) when needed.

It is recommended to use the hash of the app name or unique identifier as the content type.

pub async fn vault_expand_capacity( &self, main_secret_key: &MainSecretKey, cur_graphentry_derivation: &DerivationIndex, payment_option: PaymentOption, ) -> Result<(DerivationIndex, Vec<(PublicKey, GraphContent)>, AttoTokens), VaultError>

pub async fn vault_claimed_capacity( &self, main_secret_key: &MainSecretKey, cur_free_graphentry_derivation: DerivationIndex, ) -> Result<(DerivationIndex, Vec<(PublicKey, GraphContent)>), VaultError>

pub async fn fetch_and_decrypt_vault( &self, secret_key: &VaultSecretKey, ) -> Result<(Bytes, VaultContentType), VaultError>

👎Deprecated since 0.2.0: Use vault_get instead

@deprecated Use vault_get instead. This function will be removed in a future version.

pub async fn write_bytes_to_vault( &self, data: Bytes, payment_option: PaymentOption, secret_key: &VaultSecretKey, content_type: VaultContentType, ) -> Result<AttoTokens, VaultError>

👎Deprecated since 0.2.0: Use vault_put instead

@deprecated Use vault_put instead. This function will be removed in a future version.

impl Client

pub fn register_history(&self, addr: &RegisterAddress) -> RegisterHistory

Get the register history, starting from the root to the latest entry.

This returns a RegisterHistory that can be use to get the register values from the history.

RegisterHistory::next can be used to get the values one by one, from the first to the latest entry. RegisterHistory::collect can be used to get all the register values from the history from the first to the latest entry.

impl Client

pub fn register_key_from_name(owner: &SecretKey, name: &str) -> SecretKey

Create a new register key from a SecretKey and a name.

This derives a new SecretKey from the owner’s SecretKey using the name. Note that you will need to keep track of the names you used to create the register key.

pub fn register_value_from_bytes( bytes: &[u8], ) -> Result<RegisterValue, RegisterError>

Create a new RegisterValue from bytes, make sure the bytes are not longer than REGISTER_VALUE_SIZE

pub async fn register_create( &self, owner: &SecretKey, initial_value: RegisterValue, payment_option: PaymentOption, ) -> Result<(AttoTokens, RegisterAddress), RegisterError>

Create a new register with an initial value.

Note that two payments are required, one for the underlying GraphEntry and one for the crate::Pointer

pub async fn register_update( &self, owner: &SecretKey, new_value: RegisterValue, payment_option: PaymentOption, ) -> Result<AttoTokens, RegisterError>

Update the value of a register.

The register needs to be created first with Client::register_create

pub async fn register_get( &self, addr: &RegisterAddress, ) -> Result<RegisterValue, RegisterError>

Get the current value of the register

pub async fn register_cost( &self, owner: &PublicKey, ) -> Result<AttoTokens, CostError>

Get the cost of a register operation. Returns the cost of creation if it doesn’t exist, else returns the cost of an update

impl Client

pub async fn analyze_address( &self, address: &str, verbose: bool, ) -> Result<Analysis, AnalysisError>

Analyze an address and return the type of the address. Can be run in verbose mode to make it talkative (will print information as it works).

pub async fn analyze_address_recursively( &self, address: &str, verbose: bool, ) -> HashMap<String, Result<Analysis, AnalysisError>>

Analyze an address recursively by following all discovered addresses. Returns the list of analyses found. Can be run in verbose mode to make it talkative (will print information as it works).

pub async fn analyze_address_type( &self, address: &str, verbose: bool, ) -> Result<PointerTarget, AnalysisError>

Analyze an address and return the address type (Chunk, Pointer, GraphEntry, Scratchpad)

impl Client

pub async fn get_raw_quotes( &self, data_type: DataTypes, content_addrs: impl Iterator<Item = (XorName, usize)>, ) -> Vec<Result<(XorName, Vec<(PeerId, Addresses, PaymentQuote)>), CostError>>

Get raw quotes from nodes. These quotes do not include actual record prices. You will likely want to use get_store_quotes instead.

pub async fn get_raw_quote_from_peer( &self, content_addr: XorName, peer: PeerInfo, data_type: DataTypes, data_size: usize, ) -> Result<Option<(PeerId, Addresses, PaymentQuote)>, CostError>

Get a raw quote from a specific peer. This quote does not include actual record prices. Returns None if the record already exists and no payment is needed.

Can also be used to get a reward address from a specific peer as it will be embedded in the quote.

pub async fn get_store_quotes( &self, data_type: DataTypes, content_addrs: impl Iterator<Item = (XorName, usize)>, ) -> Result<StoreQuote, CostError>

impl Client

pub async fn get_quotes_for_content_addresses( &self, data_type: DataTypes, content_addrs: impl Iterator<Item = (XorName, usize)> + Clone, ) -> Result<(HashMap<XorName, QuoteForAddress>, Vec<QuotePayment>, Vec<XorName>), PutError>

Available on crate feature external-signer only.

Get quotes for data. Returns a cost map, data payments to be executed and a list of free (already paid for) chunks.

impl Client

pub fn deserialize_data_map(data_map_bytes: &Bytes) -> Result<DataMap, GetError>

Deserialize datamap from bytes, handling both old and new formats

impl Client

pub async fn get_closest_to_address( &self, network_address: impl Into<NetworkAddress>, count: Option<usize>, ) -> Result<Vec<PeerInfo>, NetworkError>

Retrieve the closest peers to the given network address.

Optionally specify a count of peers to retrieve; if None, CLOSE_GROUP+2 peers will be returned.

pub async fn get_record_from_peer( &self, network_address: impl Into<NetworkAddress>, peer: PeerInfo, ) -> Result<Option<Record>, NetworkError>

Get a record directly from a specific peer. Returns:

• Some(Record) if the peer holds the record
• None if the peer doesn’t hold the record or the request fails

pub async fn get_record_and_holders( &self, network_address: impl Into<NetworkAddress>, quorum: Quorum, ) -> Result<(Option<Record>, Vec<PeerId>), NetworkError>

Get a record from the network and the list of peers holding it. Returns the record if successful along with the peers that handed it to us. If the record is not found, the result will be None and an empty list of peers. If the Quorum is not met, the result will be None and the list of peers that did manage to deliver the record. As soon as the quorum is met, the request will complete and the result will be returned. Note that the holders returned is not an exhaustive list of all holders of the record, it only contains the peers that responded to the request before the quorum was met.

pub async fn get_storage_proofs_from_peer( &self, network_address: impl Into<NetworkAddress>, peer: PeerInfo, nonce: u64, difficulty: usize, ) -> Result<Vec<(NetworkAddress, Result<ChunkProof, Error>)>, NetworkError>

Get storage proofs directly from a specific peer. Returns a vector of (NetworkAddress, ChunkProof) tuples

pub async fn get_node_version( &self, peer: PeerInfo, ) -> Result<PackageVersion, String>

impl Client

pub async fn init() -> Result<Self, ConnectError>

Initialize the client with default configuration.

See Client::init_with_config.

pub async fn init_local() -> Result<Self, ConnectError>

Initialize a client that is configured to be local.

See Client::init_with_config.

pub async fn init_alpha() -> Result<Self, ConnectError>

Initialize a client that is configured to be connected to the the alpha network (Impossible Futures).

pub async fn init_with_peers( peers: Vec<Multiaddr>, ) -> Result<Self, ConnectError>

Initialize a client that bootstraps from a list of peers.

If any of the provided peers is a global address, the client will not be local.

// Will set `local` to true.
let client = Client::init_with_peers(vec!["/ip4/127.0.0.1/udp/1234/quic-v1".parse()?]).await?;

pub async fn init_with_config( config: ClientConfig, ) -> Result<Self, ConnectError>

Initialize the client with the given configuration.

This will block until CLOSE_GROUP_SIZE have been added to the routing table.

See ClientConfig.

use autonomi::client::Client;
let client = Client::init_with_config(Default::default()).await?;

pub fn with_strategy(self, strategy: ClientOperatingStrategy) -> Self

Set the ClientOperatingStrategy for the client.

pub fn with_retry_failed(self, retry_failed: u64) -> Self

Set whether to retry failed uploads automatically.

pub fn with_payment_mode(self, payment_mode: PaymentMode) -> Self

Set the payment mode for uploads.

pub fn enable_client_events(&mut self) -> Receiver<ClientEvent>

Receive events from the client.

pub fn evm_network(&self) -> &EvmNetwork

Get the evm network.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.