Struct sn_api::Safe

pub struct Safe {
    pub xorurl_base: XorUrlBase,
    // some fields omitted
}

Fields

xorurl_base: XorUrlBase

Implementations

impl Safe

pub async fn auth_app(
    app_id: &str,
    app_name: &str,
    app_vendor: &str,
    endpoint: Option<&str>
) -> Result<Keypair>

Generate an authorisation request string and send it to a SAFE Authenticator. It returns the credentials necessary to connect to the network, encoded in a single string.

pub async fn connect(
    &mut self,
    app_keypair: Option<Keypair>,
    config_path: Option<&Path>,
    bootstrap_config: Option<BootstrapConfig>
) -> Result<()>

Connect to the SAFE Network using the provided auth credentials

impl Safe

pub fn generate_random_ed_keypair(&self) -> Keypair

pub async fn keys_create_and_preload(
    &mut self,
    preload_amount: &str
) -> Result<(String, Keypair)>

pub async fn keys_create_and_preload_from_sk_string(
    &mut self,
    from: &str,
    preload_amount: &str
) -> Result<(String, Keypair)>

pub async fn keys_create_preload_test_coins(
    &mut self,
    preload_amount: &str
) -> Result<(String, Keypair)>

pub async fn keys_balance_from_sk(
    &self,
    secret_key: SecretKey
) -> Result<String>

pub async fn keys_balance_from_url(
    &mut self,
    url: &str,
    secret_key: SecretKey
) -> Result<String>

pub async fn validate_sk_for_url(
    &mut self,
    secret_key: &SecretKey,
    url: &str
) -> Result<String>

pub async fn keys_transfer(
    &mut self,
    amount: &str,
    from_sk_str: Option<&str>,
    to: &str
) -> Result<u64>

Transfer safecoins from one SafeKey to another, to a Wallet, or to a PublicKey

Using a secret key you can send safecoins to a SafeKey, Wallet, or PublicKey.

Example

let mut safe = Safe::default();
    let (key1_xorurl, keypair1) = safe.keys_create_preload_test_coins("14").await.unwrap();
    let (key2_xorurl, keypair2) = safe.keys_create_preload_test_coins("1").await.unwrap();
    let current_balance = safe.keys_balance_from_sk(keypair1.clone().unwrap().sk).await.unwrap();
    assert_eq!("14.000000000", current_balance);

    safe.keys_transfer( "10", Some(&keypair1.clone().unwrap().sk), &key2_xorurl, None ).await.unwrap();
    let from_balance = safe.keys_balance_from_url( &key1_xorurl, &keypair1.unwrap().sk ).await.unwrap();
    assert_eq!("4.000000000", from_balance);
    let to_balance = safe.keys_balance_from_url( &key2_xorurl, &keypair2.unwrap().sk ).await.unwrap();
    assert_eq!("11.000000000", to_balance);

impl Safe

pub async fn sequence_create(
    &mut self,
    data: &[u8],
    name: Option<XorName>,
    type_tag: u64,
    private: bool
) -> Result<XorUrl>

Create a Public Sequence on the network

Example

    let data = b"First in the sequence";
    let xorurl = safe.sequence_create(data, None, 20_000, false).await.unwrap();
    let received_data = safe.sequence_get(&xorurl).await.unwrap();
    assert_eq!(received_data, (0, data.to_vec()));

pub async fn sequence_get(&mut self, url: &str) -> Result<(u64, Vec<u8>)>

Get data from a Public Sequence on the network

Example

    let data = b"First in the sequence";
    let xorurl = safe.sequence_create(data, None, 20_000, false).await.unwrap();
    let received_data = safe.sequence_get(&xorurl).await.unwrap();
    assert_eq!(received_data, (0, data.to_vec()));

pub async fn append_to_sequence(&mut self, url: &str, data: &[u8]) -> Result<()>

Append data to a Public Sequence on the network

Example

    let data1 = b"First in the sequence";
    let xorurl = safe.sequence_create(data1, None, 20_000, false).await.unwrap();
    let data2 = b"Second in the sequence";
    safe.append_to_sequence(&xorurl, data2).await.unwrap();
    let received_data = safe.sequence_get(&xorurl).await.unwrap();
    assert_eq!(received_data, (1, data2.to_vec()));

impl Safe

pub async fn fetch(&mut self, url: &str, range: Range) -> Result<SafeData>

Retrieve data from a safe:// URL

Examples

Fetch FilesContainer relative path file

    let (xorurl, _, _) = safe.files_container_create(Some("../testdata/"), None, true, false, false).await.unwrap();

    let safe_data = safe.fetch( &format!( "{}/test.md", &xorurl.replace("?v=0", "") ), None ).await.unwrap();
    let data_string = match safe_data {
        SafeData::PublicBlob { data, .. } => {
            match String::from_utf8(data) {
                Ok(string) => string,
                Err(e) => panic!("Invalid UTF-8 sequence: {}", e),
            }
        }
        other => panic!(
            "Content type '{:?}' should not have been found. This should be immutable data.",
            other
        )
    };

    assert!(data_string.starts_with("hello tests!"));

pub async fn inspect(&mut self, url: &str) -> Result<Vec<SafeData>>

Inspect a safe:// URL and retrieve metadata information but the actual target content

As opposed to ‘fetch’ function, the actual target content won’t be fetched, and only

the URL will be inspected resolving it as necessary to find the target location.

This is helpful if you are interested in knowing about the target content rather than

trying to revieve the actual content.

Examples

Inspect FilesContainer relative path file

    let (container_xorurl, _, _) = safe.files_container_create(Some("../testdata/"), None, true, false, false).await.unwrap();

    let inspected_content = safe.inspect( &format!( "{}/test.md", &container_xorurl.replace("?v=0", "") ) ).await.unwrap();
    match &inspected_content[0] {
        SafeData::FilesContainer { xorurl, .. } => {
            assert_eq!(*xorurl, container_xorurl);
        }
        other => panic!(
            "Content type '{:?}' should not have been found. This should be a Files Container.",
            other
        )
    };
    match &inspected_content[1] {
        SafeData::PublicBlob { data, media_type, .. } => {
            assert_eq!(*media_type, Some("text/markdown".to_string()));
            assert!(data.is_empty());
        }
        other => panic!(
            "Content type '{:?}' should not have been found. This should be an Immutable Data.",
            other
        )
    };

impl Safe

pub async fn files_container_create(
    &mut self,
    location: Option<&str>,
    dest: Option<&str>,
    recursive: bool,
    follow_links: bool,
    dry_run: bool
) -> Result<(XorUrl, ProcessedFiles, FilesMap)>

Create a FilesContainer.

Example

    safe.connect("", Some("fake-credentials")).await.unwrap();
    let (xorurl, _processed_files, _files_map) = safe.files_container_create(Some("../testdata"), None, true, true, false).await.unwrap();
    assert!(xorurl.contains("safe://"))

pub async fn files_container_get(
    &mut self,
    url: &str
) -> Result<(u64, FilesMap)>

Fetch an existing FilesContainer.

Example

    let (xorurl, _processed_files, _files_map) = safe.files_container_create(Some("../testdata"), None, true, true, false).await.unwrap();
    let (version, files_map) = safe.files_container_get(&xorurl).await.unwrap();
    println!("FilesContainer fetched is at version: {}", version);
    println!("FilesMap of fetched version is: {:?}", files_map);

pub async fn files_container_sync(
    &mut self,
    location: &str,
    url: &str,
    recursive: bool,
    follow_links: bool,
    delete: bool,
    update_nrs: bool,
    dry_run: bool
) -> Result<(u64, ProcessedFiles, FilesMap)>

Sync up local folder with the content on a FilesContainer.

Example

    let (xorurl, _processed_files, _files_map) = safe.files_container_create(Some("../testdata"), None, true, false, false).await.unwrap();
    let (version, new_processed_files, new_files_map) = safe.files_container_sync("../testdata", &xorurl, true, true, false, false, false).await.unwrap();
    println!("FilesContainer synced up is at version: {}", version);
    println!("The local files that were synced up are: {:?}", new_processed_files);
    println!("The FilesMap of the updated FilesContainer now is: {:?}", new_files_map);

pub async fn files_container_add(
    &mut self,
    source_file: &str,
    url: &str,
    force: bool,
    update_nrs: bool,
    follow_links: bool,
    dry_run: bool
) -> Result<(u64, ProcessedFiles, FilesMap)>

Add a file, either a local path or an already uploaded file, on an existing FilesContainer.

Example

    let (xorurl, _processed_files, _files_map) = safe.files_container_create(Some("../testdata"), None, true, true, false).await.unwrap();
    let new_file_name = format!("{}/new_name_test.md", xorurl);
    let (version, new_processed_files, new_files_map) = safe.files_container_add("../testdata/test.md", &new_file_name, false, false, true, false).await.unwrap();
    println!("FilesContainer is now at version: {}", version);
    println!("The local files that were synced up are: {:?}", new_processed_files);
    println!("The FilesMap of the updated FilesContainer now is: {:?}", new_files_map);

pub async fn files_container_add_from_raw(
    &mut self,
    data: &[u8],
    url: &str,
    force: bool,
    update_nrs: bool,
    dry_run: bool
) -> Result<(u64, ProcessedFiles, FilesMap)>

Add a file, from raw bytes, on an existing FilesContainer.

Example

    let (xorurl, _processed_files, _files_map) = safe.files_container_create(Some("../testdata"), None, true, true, false).await.unwrap();
    let new_file_name = format!("{}/new_name_test.md", xorurl);
    let (version, new_processed_files, new_files_map) = safe.files_container_add_from_raw(b"0123456789", &new_file_name, false, false, false).await.unwrap();
    println!("FilesContainer is now at version: {}", version);
    println!("The local files that were synced up are: {:?}", new_processed_files);
    println!("The FilesMap of the updated FilesContainer now is: {:?}", new_files_map);

pub async fn files_container_remove_path(
    &mut self,
    url: &str,
    recursive: bool,
    update_nrs: bool,
    dry_run: bool
) -> Result<(u64, ProcessedFiles, FilesMap)>

Remove a file from an existing FilesContainer.

Example

    let (xorurl, processed_files, files_map) = safe.files_container_create(Some("../testdata/"), None, true, true, false).await.unwrap();
    let remote_file_path = format!("{}/test.md", xorurl);
    let (version, new_processed_files, new_files_map) = safe.files_container_remove_path(&remote_file_path, false, false, false).await.unwrap();
    println!("FilesContainer is now at version: {}", version);
    println!("The files that were removed: {:?}", new_processed_files);
    println!("The FilesMap of the updated FilesContainer now is: {:?}", new_files_map);

pub async fn files_store_public_blob(
    &mut self,
    data: &[u8],
    media_type: Option<&str>,
    dry_run: bool
) -> Result<XorUrl>

Put a Public Blob

Put data blobs onto the network.

Example

    let data = b"Something super good";
    let xorurl = safe.files_store_public_blob(data, Some("text/plain"), false).await.unwrap();
    let received_data = safe.files_get_public_blob(&xorurl, None).await.unwrap();
    assert_eq!(received_data, data);

pub async fn files_get_public_blob(
    &mut self,
    url: &str,
    range: Range
) -> Result<Vec<u8>>

Get a Public Blob

Put data blobs onto the network.

Example

    let data = b"Something super good";
    let xorurl = safe.files_store_public_blob(data, None, false).await.unwrap();
    let received_data = safe.files_get_public_blob(&xorurl, None).await.unwrap();
    assert_eq!(received_data, data);

impl Safe

pub fn parse_url(url: &str) -> Result<SafeUrl>

pub async fn nrs_map_container_add(
    &mut self,
    name: &str,
    link: &str,
    default: bool,
    hard_link: bool,
    dry_run: bool
) -> Result<(u64, XorUrl, ProcessedEntries, NrsMap)>

pub async fn nrs_map_container_create(
    &mut self,
    name: &str,
    link: &str,
    default: bool,
    hard_link: bool,
    dry_run: bool
) -> Result<(XorUrl, ProcessedEntries, NrsMap)>

Create a NrsMapContainer.

Example

    let rand_string: String = thread_rng().sample_iter(&Alphanumeric).take(15).collect();
    let file_xorurl = safe.files_store_public_blob(&vec![], None, false).await.unwrap();
    let (xorurl, _processed_entries, nrs_map_container) = safe.nrs_map_container_create(&rand_string, &file_xorurl, true, false, false).await.unwrap();
    assert!(xorurl.contains("safe://"))

pub async fn nrs_map_container_remove(
    &mut self,
    name: &str,
    dry_run: bool
) -> Result<(u64, XorUrl, ProcessedEntries, NrsMap)>

pub async fn nrs_map_container_get(
    &mut self,
    url: &str
) -> Result<(u64, NrsMap)>

Fetch an existing NrsMapContainer.

Example

    let rand_string: String = thread_rng().sample_iter(&Alphanumeric).take(15).collect();
    let file_xorurl = safe.files_store_public_blob(&vec![], Some("text/plain"), false).await.unwrap();
    let (xorurl, _processed_entries, _nrs_map) = safe.nrs_map_container_create(&rand_string, &file_xorurl, true, false, false).await.unwrap();
    let (version, nrs_map_container) = safe.nrs_map_container_get(&xorurl).await.unwrap();
    assert_eq!(version, 0);
    assert_eq!(nrs_map_container.get_default_link().unwrap(), file_xorurl);

impl Safe

pub async fn wallet_create(&mut self) -> Result<XorUrl>

pub async fn wallet_insert(
    &mut self,
    url: &str,
    name: Option<&str>,
    default: bool,
    sk: &str
) -> Result<String>

pub async fn wallet_balance(&mut self, url: &str) -> Result<String>

pub async fn wallet_get_default_balance(
    &mut self,
    url: &str
) -> Result<(WalletSpendableBalance, u64)>

pub async fn wallet_transfer(
    &mut self,
    amount: &str,
    from_wallet_url: &str,
    to: &str
) -> Result<u64>

Transfer safecoins from one Wallet to another

Using established Wallet and SpendableBalances you can send safecoins between Wallets.

Example

let mut safe = Safe::default();
    let wallet_xorurl = safe.wallet_create().await.unwrap();
    let wallet_xorurl2 = safe.wallet_create().await.unwrap();
    let (key1_xorurl, keypair1) = safe.keys_create_preload_test_coins("14").await.unwrap();
    let (key2_xorurl, keypair2) = safe.keys_create_preload_test_coins("1").await.unwrap();
    safe.wallet_insert(
        &wallet_xorurl,
        Some("frombalance"),
        true,
        &keypair1.clone().unwrap().sk,
    ).await.unwrap();
    let current_balance = safe.wallet_balance(&wallet_xorurl).await.unwrap();
    assert_eq!("14.000000000", current_balance);

    safe.wallet_insert(
        &wallet_xorurl2,
        Some("tobalance"),
        true,
        &keypair2.clone().unwrap().sk,
    ).await.unwrap();


    safe.wallet_transfer( "10", Some(&wallet_xorurl), &wallet_xorurl2, None ).await.unwrap();
    let from_balance = safe.keys_balance_from_url( &key1_xorurl, &keypair1.unwrap().sk ).await.unwrap();
    assert_eq!("4.000000000", from_balance);
    let to_balance = safe.keys_balance_from_url( &key2_xorurl, &keypair2.unwrap().sk ).await.unwrap();
    assert_eq!("11.000000000", to_balance);

pub async fn wallet_get(&mut self, url: &str) -> Result<WalletSpendableBalances>

impl Safe

pub fn new(xorurl_base: Option<XorUrlBase>, timeout: Duration) -> Self

pub fn keypair(&self) -> Keypair

Generate a new random Ed25519 keypair

pub async fn get_my_keypair(&self) -> Result<Keypair>

Retrieve the keypair this instance was instantiated with, i.e. the keypair this instance uses by default to sign each outgoing message

Trait Implementations

impl Clone for Safe

fn clone(&self) -> Safe

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for Safe

fn default() -> Self

Returns the “default value” for a type.