Struct sn_client::Client

pub struct Client { /* private fields */ }

Client API implementation to store and get data.

Implementations

impl Client

pub async fn quick_start(peers: Option<Vec<Multiaddr>>) -> Result<Self, Error>

A quick client with a random secret key and some peers.

pub async fn new( signer: SecretKey, peers: Option<Vec<Multiaddr>>, connection_timeout: Option<Duration>, client_event_broadcaster: Option<ClientEventsBroadcaster> ) -> Result<Self, Error>

Instantiate a new client.

Optionally specify the duration for the connection timeout.

Defaults to 180 seconds.

Arguments

• ‘signer’ - SecretKey
• ‘peers’ - Option<Vec<Multiaddr>>
• ‘connection_timeout’ - Option<Duration> : Specification for client connection timeout set via Optional
• ‘client_event_broadcaster’ - Option<ClientEventsBroadcaster>

Example

use sn_client::{Client, Error};
use bls::SecretKey;
let client = Client::new(SecretKey::random(), None, None, None).await?;

pub fn events_channel(&self) -> ClientEventsReceiver

Get the client events channel.

Return Type:

ClientEventsReceiver

Example

use sn_client::{Client, Error, ClientEvent};
use bls::SecretKey;
let client = Client::new(SecretKey::random(), None, None, None).await?;
// Using client.events_channel() to publish messages
let mut events_channel = client.events_channel();
while let Ok(event) = events_channel.recv().await {
// Handle the event
 }

pub fn sign<T: AsRef<[u8]>>(&self, data: T) -> Signature

Sign the given data.

Arguments

• ‘data’ - bytes; i.e bytes of an sn_registers::Register instance

Return Type:

Signature

Example

use sn_client::{Client, Error};
use bls::SecretKey;

use tracing::callsite::register;
use xor_name::XorName;
use sn_registers::Register;
use sn_protocol::messages::RegisterCmd;
let client = Client::new(SecretKey::random(), None, None, None).await?;

// Set up register prerequisites
let mut rng = rand::thread_rng();
let xorname = XorName::random(&mut rng);
let owner_sk = SecretKey::random();
let owner_pk = owner_sk.public_key();

// set up register
let mut register = Register::new(owner_pk, xorname, Default::default());
let mut register_clone = register.clone();

// Use of client.sign() with register through RegisterCmd::Create
let cmd = RegisterCmd::Create {
   register,
   signature: client.sign(register_clone.bytes()?),
};

pub fn signer(&self) -> &SecretKey

Return a reference to the signer secret key.

Return Type:

SecretKey

Example

use sn_client::{Client, Error};
use bls::SecretKey;
let client = Client::new(SecretKey::random(), None, None, None).await?;
let secret_key_reference = client.signer();

pub fn signer_pk(&self) -> PublicKey

Return the public key of the data signing key.

Return Type:

PublicKey

Example

use sn_client::{Client, Error};
use bls::SecretKey;
let client = Client::new(SecretKey::random(), None, None, None).await?;
let public_key_reference = client.signer_pk();

pub fn set_signer_key(&mut self, sk: SecretKey)

Set the signing key for this client.

Arguments

• ‘sk’ - SecretKey

Example

use sn_client::{Client, Error};
use bls::SecretKey;
let mut client = Client::new(SecretKey::random(), None, None, None).await?;
client.set_signer_key(SecretKey::random());

pub async fn get_signed_register_from_network( &self, address: RegisterAddress, is_verifying: bool ) -> Result<SignedRegister, Error>

Get a register from network

Arguments

• ‘address’ - RegisterAddress
• ‘is_verifying’ - Boolean: If true, we fetch at-least 2 copies from the network with more retry attempts.

Return Type:

Result<SignedRegister>

Example

use sn_client::{Client, Error};
use bls::SecretKey;
use xor_name::XorName;
use sn_registers::RegisterAddress;
// Set up a client
let client = Client::new(SecretKey::random(), None, None, None).await?;
// Set up an address
let mut rng = rand::thread_rng();
let owner = SecretKey::random().public_key();
let xorname = XorName::random(&mut rng);
let address = RegisterAddress::new(xorname, owner);
// Get a signed register
let signed_register = client.get_signed_register_from_network(address,true);

pub async fn get_register( &self, address: RegisterAddress ) -> Result<ClientRegister, Error>

Retrieve a Register from the network.

Arguments

• ‘address’ - RegisterAddress

Return Type:

Result<ClientRegister>

Example

use sn_client::{Client, Error};
use bls::SecretKey;
use xor_name::XorName;
use sn_registers::RegisterAddress;
// Set up a client
let client = Client::new(SecretKey::random(), None, None, None).await?;
// Set up an address
let mut rng = rand::thread_rng();
let owner = SecretKey::random().public_key();
let xorname = XorName::random(&mut rng);
let address = RegisterAddress::new(xorname, owner);
// Get the register
let retrieved_register = client.get_register(address);

pub async fn create_and_pay_for_register( &self, address: XorName, wallet_client: &mut WalletClient, verify_store: bool, perms: Permissions ) -> Result<(ClientRegister, NanoTokens, NanoTokens), Error>

Create a new Register on the Network. Tops up payments and retries if necessary and verification failed

Arguments

• ‘address’ - XorName
• ‘wallet_client’ - WalletClient
• ‘verify_store’ - Boolean
• ‘perms’ - Permissions

Return Type:

Result<(ClientRegister, NanoTokens, NanoTokens)>

Example

use sn_client::{Client, WalletClient, Error};
use tempfile::TempDir;
use bls::SecretKey;
use sn_transfers::{MainSecretKey};
use xor_name::XorName;
use sn_registers::RegisterAddress;
// Set up Client, Wallet, etc
use sn_registers::Permissions;
use sn_transfers::HotWallet;
let client = Client::new(SecretKey::random(), None, None, None).await?;
let tmp_path = TempDir::new()?.path().to_owned();
let mut wallet = HotWallet::load_from_path(&tmp_path,Some(MainSecretKey::new(SecretKey::random())))?;
let mut wallet_client = WalletClient::new(client.clone(), wallet);
// Set up an address
let mut rng = rand::thread_rng();
let owner = SecretKey::random().public_key();
let xorname = XorName::random(&mut rng);
let address = RegisterAddress::new(xorname, owner);
// Example:
    let (mut client_register, _storage_cost, _royalties_fees) = client
        .create_and_pay_for_register(
            xorname,
            &mut wallet_client,
            true,
            Permissions::default(),
        )
        .await?;

pub async fn get_chunk( &self, address: ChunkAddress, show_holders: bool, retry_strategy: Option<RetryStrategy> ) -> Result<Chunk, Error>

Get chunk from chunk address.

Arguments

• ‘address’ - ChunkAddress
• ‘show_holders’ - Boolean
• ‘retry_strategy’ - Option<RetryStrategy> : Uses Quick by default

Return Type:

Result<Chunk>

Example

use sn_client::{Client, Error};
use bls::SecretKey;
use xor_name::XorName;
use sn_protocol::storage::ChunkAddress;
// client
let client = Client::new(SecretKey::random(), None, None, None).await?;
// chunk address
let mut rng = rand::thread_rng();
let xorname = XorName::random(&mut rng);
let chunk_address = ChunkAddress::new(xorname);
// get chunk
let chunk = client.get_chunk(chunk_address,true, None).await?;

pub async fn verify_chunk_stored(&self, chunk: &Chunk) -> Result<(), Error>

Verify if a Chunk is stored by expected nodes on the network. Single local use. Marked Private.

pub async fn verify_register_stored( &self, address: RegisterAddress ) -> Result<SignedRegister, Error>

Verify if a Register is stored by expected nodes on the network.

Arguments

• ‘address’ - RegisterAddress

Return Type:

Result<SignedRegister>

Example

use sn_client::{Client, Error};
use bls::SecretKey;
use xor_name::XorName;
use sn_registers::RegisterAddress;
// Set up Client
let client = Client::new(SecretKey::random(), None, None, None).await?;
// Set up an address
let mut rng = rand::thread_rng();
let owner = SecretKey::random().public_key();
let xorname = XorName::random(&mut rng);
let address = RegisterAddress::new(xorname, owner);
// Verify address is stored
let is_stored = client.verify_register_stored(address).await.is_ok();

pub async fn quickly_check_if_register_stored( &self, address: RegisterAddress ) -> Result<SignedRegister, Error>

Quickly checks if a Register is stored by expected nodes on the network.

To be used for initial register put checks eg, if we expect the data not to exist, we can use it and essentially use the RetryStrategy::Quick under the hood

Example

use sn_client::{Client, Error};
use bls::SecretKey;
use xor_name::XorName;
use sn_registers::RegisterAddress;
// Set up Client
let client = Client::new(SecretKey::random(), None, None, None).await?;
// Set up an address
let mut rng = rand::thread_rng();
let owner = SecretKey::random().public_key();
let xorname = XorName::random(&mut rng);
let address = RegisterAddress::new(xorname, owner);
// Verify address is stored
let is_stored = client.verify_register_stored(address).await.is_ok();

pub async fn get_spend_from_network( &self, address: SpendAddress ) -> Result<SignedSpend, Error>

Get a spend from network.

Arguments

• ‘address’ - SpendAddress

Return Type:

Result<SignedSpend>

Example

use sn_client::{Client, Error};
use bls::SecretKey;
use xor_name::XorName;
use sn_transfers::SpendAddress;
let client = Client::new(SecretKey::random(), None, None, None).await?;
// Create a SpendAddress
let mut rng = rand::thread_rng();
let xorname = XorName::random(&mut rng);
let spend_address = SpendAddress::new(xorname);
// Here we get the spend address
let spend = client.get_spend_from_network(spend_address).await?;
// Example: We can use the spend to get its unique public key:
let unique_pubkey = spend.unique_pubkey();

pub async fn crawl_spend_from_network( &self, address: SpendAddress ) -> Result<SignedSpend, Error>

This is a similar funcation to get_spend_from_network to get a spend from network. Just using different RetryStrategy to improve the performance during crawling.

pub async fn verify_cash_notes_redemptions( &self, main_pubkey: MainPubkey, cashnote_redemptions: &[CashNoteRedemption] ) -> Result<Vec<CashNote>, Error>

This function is used to receive a Vector of CashNoteRedemptions and turn them back into spendable CashNotes. For this we need a network connection. Verify CashNoteRedemptions and rebuild spendable currency from them. Returns an Error::InvalidTransfer if any CashNoteRedemption is not valid Else returns a list of CashNotes that can be spent by the owner.

Arguments

• ‘main_pubkey’ - MainPubkey
• ‘cashnote_redemptions’ - CashNoteRedemption

Return Type:

Result<Vec<CashNote>>

Example

use sn_client::{Client, Error};
use bls::SecretKey;
use sn_transfers::{CashNote, CashNoteRedemption, MainPubkey};
let client = Client::new(SecretKey::random(), None, None, None).await?;
// Create a main public key
let pk = SecretKey::random().public_key();
let main_pub_key = MainPubkey::new(pk);
// Create a Cash Note Redemption Vector
let cash_note = CashNote::from_hex("&hex").unwrap();
let cashNoteRedemption = CashNoteRedemption::from_cash_note(&cash_note).unwrap();
let vector = vec![cashNoteRedemption.clone(), cashNoteRedemption.clone()];
// Verify the cash note redemptions
let cash_notes = client.verify_cash_notes_redemptions(main_pub_key,&vector);

impl Client

pub async fn verify_spend_at( &self, addr: SpendAddress, to_genesis: bool ) -> WalletResult<()>

Verify that a spend is valid on the network. Optionally verify its ancestors as well, all the way to genesis (might take a LONG time)

Prints progress on stdout.

When verifying all the way back to genesis, it only verifies Spends that are ancestors of the given Spend, ignoring all other branches.

This is how the DAG it follows could look like:

             ... --
                    \
             ... ----                  ... --
                      \                       \
Spend0 -> Spend1 -----> Spend2 ---> Spend5 ---> Spend2 ---> Genesis
                  \                           /
                   ---> Spend3 ---> Spend6 ->
                    \            /
                     -> Spend4 ->
                               /
                           ...

depth0    depth1        depth2      depth3      depth4      depth5

This function will return an error if any spend in the way is invalid.

pub async fn follow_spend( &self, spend_addr: SpendAddress ) -> WalletResult<BTreeSet<SpendAddress>>

This function does the opposite of verify_spend. It recursively follows the descendants of a Spend, all the way to unspent Transaction Outputs (UTXOs).

Prints progress on stdout

Starting from Genesis, this amounts to Auditing the entire currency. This is how the DAG it follows could look like:

                                  -> Spend7 ---> UTXO_11
                                /
Genesis -> Spend1 -----> Spend2 ---> Spend5 ---> UTXO_10
                  \
                    ---> Spend3 ---> Spend6 ---> UTXO_9
                    \
                      -> Spend4 ---> UTXO_8

gen0       gen1          gen2        gen3

This function will return the UTXOs (Spend addresses not spent yet) Future calls to this function could start from those UTXOs to avoid re-checking all previously checked branches.

impl Client

pub async fn spend_dag_build_from( &self, spend_addr: SpendAddress, max_depth: Option<u32> ) -> WalletResult<SpendDag>

Builds a SpendDag from a given SpendAddress recursively following descendants all the way to UTxOs Started from Genesis this gives the entire SpendDag of the Network at a certain point in time Once the DAG collected, verifies and records errors in the DAG

pub async fn spend_dag_extend_until( &self, dag: &mut SpendDag, spend_addr: SpendAddress, new_spend: SignedSpend ) -> WalletResult<()>

Extends an existing SpendDag with a new SignedSpend, tracing back the ancestors of that Spend all the way to a known Spend in the DAG or else back to Genesis Verifies the DAG and records faults if any This is useful to keep a partial SpendDag to be able to verify that new spends come from Genesis

             ... --
                    \
             ... ----                  ... --
                      \                       \
Spend0 -> Spend1 -----> Spend2 ---> Spend5 ---> Spend2 ---> Genesis
                  \                           /
                   ---> Spend3 ---> Spend6 ->
                    \            /
                     -> Spend4 ->
                               /
                           ...

pub async fn spend_dag_continue_from_utxos( &self, dag: &mut SpendDag, max_depth: Option<u32> ) -> WalletResult<()>

Extends an existing SpendDag starting from the utxos in this DAG Covers the entirety of currently existing Spends if the DAG was built from Genesis Records errors in the new DAG branches if any Stops gathering after max_depth generations

impl Client

pub async fn send_spends( &self, spend_requests: impl Iterator<Item = &SignedSpend>, verify_store: bool ) -> WalletResult<()>

Send spend requests to the network. This can optionally verify the spends have been correctly stored before returning

Arguments

• spend_requests - Iterator<SignedSpend>
• verify_store - Boolean. Set to true for mandatory verification via a GET request through a Spend on the network.

Example

use sn_client::{Client, WalletClient, Error};
use bls::SecretKey;
use sn_transfers::{HotWallet, MainSecretKey};
let client = Client::new(SecretKey::random(), None, None, None).await?;
let mut wallet = HotWallet::load_from_path(&tmp_path,Some(MainSecretKey::new(SecretKey::random())))?;
// An example of sending storage payment transfers over the network with validation
client.send_spends(wallet.unconfirmed_spend_requests().iter(),true).await?;

pub async fn receive( &self, transfer: &Transfer, wallet: &HotWallet ) -> WalletResult<Vec<CashNote>>

Receive a Transfer, verify and redeem CashNotes from the Network.

Arguments

• transfer: &Transfer - Borrowed value for Transfer
• wallet: &HotWallet - Borrowed value for HotWallet

Return Value

• WalletResult<Vec<CashNote>>

Example

use sn_client::{Client, WalletClient, Error};
use bls::SecretKey;
use sn_transfers::{HotWallet, MainSecretKey};
use tracing::error;
use sn_transfers::Transfer;
let client = Client::new(SecretKey::random(), None, None, None).await?;
let mut wallet = HotWallet::load_from_path(&tmp_path,Some(MainSecretKey::new(SecretKey::random())))?;
let transfer = Transfer::from_hex("13abc").unwrap();
// An example for using client.receive() for cashNotes
let cash_notes = match client.receive(&transfer, &wallet).await {
                Ok(cash_notes) => cash_notes,
                Err(err) => {
                    println!("Failed to verify and redeem transfer: {err:?}");
                    error!("Failed to verify and redeem transfer: {err:?}");
                    return Err(err.into());
                }
            };

pub async fn verify_cashnote(&self, cash_note: &CashNote) -> WalletResult<()>

Verify that the spends referred to (in the CashNote) exist on the network.

Arguments

• cash_note - CashNote

Return value

WalletResult

Example

use sn_client::{Client, WalletClient, Error};
use bls::SecretKey;
use sn_transfers::{HotWallet, MainSecretKey};
use tracing::error;
use sn_transfers::Transfer;
let client = Client::new(SecretKey::random(), None, None, None).await?;
let mut wallet = HotWallet::load_from_path(&tmp_path,Some(MainSecretKey::new(SecretKey::random())))?;
let transfer = Transfer::from_hex("").unwrap();
let cash_notes = client.receive(&transfer, &wallet).await?;
// Verification:
for cash_note in cash_notes {
    println!("{:?}" , client.verify_cashnote(&cash_note).await.unwrap());
}

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a copy of the value.

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

Performs copy-assignment from source.