chore(examples): align client examples

sdk/.env.example

@@ -1,8 +1,9 @@
-NON_SECURE_USE_OF_DEVELOPMENT_MNEMONIC_1="endorse answer radar about source reunion marriage tag sausage weekend frost daring base attack because joke dream slender leisure group reason prepare broken river"
-NON_SECURE_USE_OF_DEVELOPMENT_MNEMONIC_2="width scatter jaguar sponsor erosion enable cave since ancient first garden royal luggage exchange ritual exotic play wall clinic ride autumn divert spin exchange"
-NON_SECURE_USE_OF_DEVELOPMENT_SEED_1=0x256a818b2aac458941f7274985a410e57fb750f3a3a67969ece5bd9ae7eef5b2
-NON_SECURE_USE_OF_DEVELOPMENT_SEED_2=0x256a818b2aac458941f7274985a410e57fb750f3a3a67969ece5bd9ae7eef5b3
-STRONGHOLD_PASSWORD="some_hopefully_secure_password"
+# URLs
 NODE_URL="https://api.testnet.shimmer.network"
 FAUCET_URL="https://faucet.testnet.shimmer.network/api/enqueue"
 EXPLORER_URL="https://explorer.shimmer.network/testnet"
+
+# Credentials (only to be used in the SDK examples)
+NON_SECURE_USE_OF_DEVELOPMENT_MNEMONIC_1="endorse answer radar about source reunion marriage tag sausage weekend frost daring base attack because joke dream slender leisure group reason prepare broken river"
+NON_SECURE_USE_OF_DEVELOPMENT_MNEMONIC_2="width scatter jaguar sponsor erosion enable cave since ancient first garden royal luggage exchange ritual exotic play wall clinic ride autumn divert spin exchange"
+STRONGHOLD_PASSWORD="24?drowssap"

sdk/Cargo.toml

@@ -73,6 +73,7 @@ wasm-bindgen-futures = { version = "0.4.36", default-features = false, optional
 
 [dev-dependencies]
 iota-sdk = { path = ".", default-features = false, features = [ "rand" ] }
+tokio = { version = "1.28.2", default-features = false, features = [ "fs", "macros", "rt", "time", "sync" ] }
 
 dotenvy = { version = "0.15.7", default-features = false }
 fern-logger = { version = "0.5.0", default-features = false }
@@ -230,6 +231,23 @@ name = "transaction"
 path = "examples/client/block/transaction.rs"
 required-features = [ "client" ]
 
+# High Level examples
+
+[[example]]
+name = "address_consolidation"
+path = "examples/client/high_level/consolidation.rs"
+required-features = [ "client" ]
+
+[[example]]
+name = "inputs_from_transaction_id"
+path = "examples/client/high_level/inputs_from_transaction_id.rs"
+required-features = [ "client" ]
+
+[[example]]
+name = "search_address"
+path = "examples/client/high_level/search_address.rs"
+required-features = [ "client" ]
+
 # Node API core examples
 
 [[example]]
@@ -392,8 +410,13 @@ required-features = [ "client" ]
 #######
 
 [[example]]
-name = "generate_addresses"
-path = "examples/client/01_generate_addresses.rs"
+name = "client_list_addresses"
+path = "examples/client/01_list_addresses.rs"
+required-features = [ "client" ]
+
+[[example]]
+name = "02_address_balance"
+path = "examples/client/02_address_balance.rs"
 required-features = [ "client" ]
 
 [[example]]

sdk/examples/client/01_generate_addresses.rs → sdk/examples/client/01_list_addresses.rs

@@ -1,9 +1,14 @@
 // Copyright 2021 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
-//! TODO: Example description
+//! This example shows how to list the generated addresses of an account.
 //!
-//! `cargo run --example generate_addresses --release -- [NODE_URL]`
+//! Rename `.env.example` to `.env` first, then run the command:
+//! ```sh
+//! cargo run --release --example client_list_addresses
+//! ```
+
+use std::env;
 
 use iota_sdk::client::{
     api::GetAddressesOptions,
@@ -16,26 +21,21 @@ async fn main() -> Result<()> {
     // This example uses secrets in environment variables for simplicity which should not be done in production.
     dotenvy::dotenv().ok();
 
-    // Take the node URL from command line argument or use one from env as default.
-    let node_url = std::env::args()
-        .nth(1)
-        .unwrap_or_else(|| std::env::var("NODE_URL").unwrap());
-
-    // Create a client instance
+    // Create a client instance.
     let client = Client::builder()
-        .with_node(&node_url)? // Insert your node URL here
+        .with_node(&env::var("NODE_URL").unwrap())?
         .finish()
         .await?;
 
     let secret_manager =
-        SecretManager::try_from_mnemonic(std::env::var("NON_SECURE_USE_OF_DEVELOPMENT_MNEMONIC_1").unwrap())?;
+        SecretManager::try_from_mnemonic(env::var("NON_SECURE_USE_OF_DEVELOPMENT_MNEMONIC_1").unwrap())?;
 
     // Generate addresses with default account index and range
     let addresses = secret_manager
         .generate_ed25519_addresses(GetAddressesOptions::from_client(&client).await?)
         .await?;
 
-    println!("List of generated public addresses:");
+    println!("List of generated public addresses (default):");
     println!("{addresses:#?}\n");
 
     // Generate addresses with custom account index and range
@@ -48,7 +48,7 @@ async fn main() -> Result<()> {
         )
         .await?;
 
-    println!("List of generated public addresses:\n");
+    println!("List of generated public addresses (0..4):\n");
     println!("{addresses:#?}\n");
 
     // Generate internal addresses with custom account index and range

sdk/examples/client/02_get_address_balance.rs → sdk/examples/client/02_address_balance.rs

@@ -1,71 +1,74 @@
 // Copyright 2021 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
-//! In this example we will get the outputs of an address that have no additional unlock conditions and sum the amounts
-//! and native tokens.
+//! This example shows how to get the outputs of an address that have no additional unlock conditions, and sum the
+//! amounts and native tokens.
 //!
-//! `cargo run --example 02_get_address_balance --release`
+//! Rename `.env.example` to `.env` first, then run the command:
+//! ```sh
+//! cargo run --release --example 02_address_balance
+//! ```
 
-use iota_sdk::client::{
-    block::output::{NativeTokensBuilder, Output},
-    node_api::indexer::query_parameters::QueryParameter,
-    secret::{mnemonic::MnemonicSecretManager, SecretManager},
-    Client, Result,
+use std::env;
+
+use iota_sdk::{
+    client::{
+        api::GetAddressesOptions, node_api::indexer::query_parameters::QueryParameter, secret::SecretManager, Client,
+        Result,
+    },
+    types::block::output::NativeTokensBuilder,
 };
 
 #[tokio::main]
 async fn main() -> Result<()> {
     // This example uses secrets in environment variables for simplicity which should not be done in production.
     dotenvy::dotenv().ok();
 
-    let node_url = std::env::var("NODE_URL").unwrap();
-
-    // Create a client instance
+    // Create a client instance.
     let client = Client::builder()
-        .with_node(&node_url)? // Insert your node URL here
+        .with_node(&env::var("NODE_URL").unwrap())?
         .finish()
         .await?;
 
     let secret_manager =
-        MnemonicSecretManager::try_from_mnemonic(std::env::var("NON_SECURE_USE_OF_DEVELOPMENT_MNEMONIC_1").unwrap())?;
-
-    let token_supply = client.get_token_supply().await?;
+        SecretManager::try_from_mnemonic(env::var("NON_SECURE_USE_OF_DEVELOPMENT_MNEMONIC_1").unwrap())?;
 
     // Generate the first address
-    let addresses = client
-        .get_addresses(&SecretManager::Mnemonic(secret_manager))
-        .with_account_index(0)
-        .with_range(0..1)
-        .finish()
+    let addresses = secret_manager
+        .generate_ed25519_addresses(
+            GetAddressesOptions::from_client(&client)
+                .await?
+                .with_account_index(0)
+                .with_range(0..1),
+        )
         .await?;
 
     // Get output ids of outputs that can be controlled by this address without further unlock constraints
     let output_ids_response = client
         .basic_output_ids([
-            QueryParameter::Address(addresses[0].clone()),
+            QueryParameter::Address(addresses[0]),
             QueryParameter::HasExpiration(false),
             QueryParameter::HasTimelock(false),
             QueryParameter::HasStorageDepositReturn(false),
         ])
         .await?;
 
     // Get the outputs by their id
-    let outputs_responses = client.get_outputs(output_ids_response.items).await?;
+    let outputs_responses = client.get_outputs(&output_ids_response.items).await?;
 
     // Calculate the total amount and native tokens
     let mut total_amount = 0;
     let mut total_native_tokens = NativeTokensBuilder::new();
     for output_response in outputs_responses {
-        let output = Output::try_from_dto(&output_response.output, token_supply)?;
-
+        let output = output_response.output();
         if let Some(native_tokens) = output.native_tokens() {
             total_native_tokens.add_native_tokens(native_tokens.clone())?;
         }
         total_amount += output.amount();
     }
 
     println!(
-        "Outputs controlled by {} have: {:?}i and native tokens: {:?}",
+        "Outputs controlled by {} have: {:?}i and native tokens:\n{:#?}",
         addresses[0],
         total_amount,
         total_native_tokens.finish_vec()?

sdk/examples/client/block/00_block_no_payload.rs

@@ -3,18 +3,21 @@
 
 //! This example sends a block with no payload.
 //!
-//! `cargo run --example block_no_payload --release -- [NODE URL]`
+//! Rename `.env.example` to `.env` first, then run the command:
+//! ```sh
+//! cargo run --release --example block_no_payload
+//! ```
+
+use std::env;
 
 use iota_sdk::client::{Client, Result};
 
 #[tokio::main]
 async fn main() -> Result<()> {
-    // Take the node URL from command line argument or use one from env as default.
-    let node_url = std::env::args().nth(1).unwrap_or_else(|| {
-        // This example uses secrets in environment variables for simplicity which should not be done in production.
-        dotenvy::dotenv().ok();
-        std::env::var("NODE_URL").unwrap()
-    });
+    // This example uses secrets in environment variables for simplicity which should not be done in production.
+    dotenvy::dotenv().ok();
+
+    let node_url = env::var("NODE_URL").unwrap();
 
     // Create a client with that node.
     let client = Client::builder().with_node(&node_url)?.finish().await?;
@@ -26,7 +29,7 @@ async fn main() -> Result<()> {
 
     println!(
         "Block with no payload sent: {}/block/{}",
-        std::env::var("EXPLORER_URL").unwrap(),
+        env::var("EXPLORER_URL").unwrap(),
         block.id()
     );
 

sdk/examples/client/block/01_block_confirmation_time.rs

@@ -3,18 +3,21 @@
 
 //! This example sends a block and returns the time at which it got confirmed.
 //!
-//! `cargo run --example block_confirmation_time --release -- [NODE URL]`
+//! Rename `.env.example` to `.env` first, then run the command:
+//! ```sh
+//! cargo run --release --example block_confirmation_time
+//! ```
+
+use std::env;
 
 use iota_sdk::client::{Client, Result};
 
 #[tokio::main]
 async fn main() -> Result<()> {
-    // Take the node URL from command line argument or use one from env as default.
-    let node_url = std::env::args().nth(1).unwrap_or_else(|| {
-        // This example uses secrets in environment variables for simplicity which should not be done in production.
-        dotenvy::dotenv().ok();
-        std::env::var("NODE_URL").unwrap()
-    });
+    // This example uses secrets in environment variables for simplicity which should not be done in production.
+    dotenvy::dotenv().ok();
+
+    let node_url = env::var("NODE_URL").unwrap();
 
     // Create a client with that node.
     let client = Client::builder().with_node(&node_url)?.finish().await?;
@@ -26,10 +29,10 @@ async fn main() -> Result<()> {
     println!("{block:#?}");
 
     // Try to check if the block has been confirmed.
-    let _ = client.retry_until_included(&block_id, None, None).await?;
+    client.retry_until_included(&block_id, None, None).await?;
     println!(
         "Block with no payload included: {}/block/{}",
-        std::env::var("EXPLORER_URL").unwrap(),
+        env::var("EXPLORER_URL").unwrap(),
         block_id
     );
 

sdk/examples/client/block/02_block_custom_parents.rs

@@ -3,33 +3,37 @@
 
 //! This example sends a block, with custom parents, which can be used for promoting.
 //!
-//! `cargo run --example block_custom_parents --release -- [NODE URL]`
+//! Rename `.env.example` to `.env` first, then run the command:
+//! ```sh
+//! cargo run --release --example block_custom_parents
+//! ```
+
+use std::env;
 
 use iota_sdk::client::{Client, Result};
 
 #[tokio::main]
 async fn main() -> Result<()> {
-    // Take the node URL from command line argument or use one from env as default.
-    let node_url = std::env::args().nth(1).unwrap_or_else(|| {
-        // This example uses secrets in environment variables for simplicity which should not be done in production.
-        dotenvy::dotenv().ok();
-        std::env::var("NODE_URL").unwrap()
-    });
+    // This example uses secrets in environment variables for simplicity which should not be done in production.
+    dotenvy::dotenv().ok();
+
+    let node_url = env::var("NODE_URL").unwrap();
 
     // Create a client with that node.
     let client = Client::builder().with_node(&node_url)?.finish().await?;
 
     // Use tips as custom parents.
-    let parents = client.get_tips().await?;
+    let tips = client.get_tips().await?;
+    println!("Custom tips:\n{tips:#?}");
 
     // Create and send the block with custom parents.
-    let block = client.block().with_parents(parents)?.finish().await?;
+    let block = client.block().with_parents(tips)?.finish().await?;
 
     println!("{block:#?}");
 
     println!(
         "Block with custom parents sent: {}/block/{}",
-        std::env::var("EXPLORER_URL").unwrap(),
+        env::var("EXPLORER_URL").unwrap(),
         block.id()
     );
 

sdk/examples/client/block/03_block_custom_payload.rs

@@ -3,7 +3,12 @@
 
 //! This example sends a block with a custom payload.
 //!
-//! `cargo run --example block_custom_payload --release -- [NODE URL]`
+//! Rename `.env.example` to `.env` first, then run the command:
+//! ```sh
+//! cargo run --release --example block_custom_payload
+//! ```
+
+use std::env;
 
 use iota_sdk::{
     client::{Client, Result},
@@ -12,18 +17,16 @@ use iota_sdk::{
 
 #[tokio::main]
 async fn main() -> Result<()> {
-    // Take the node URL from command line argument or use one from env as default.
-    let node_url = std::env::args().nth(1).unwrap_or_else(|| {
-        // This example uses secrets in environment variables for simplicity which should not be done in production.
-        dotenvy::dotenv().ok();
-        std::env::var("NODE_URL").unwrap()
-    });
+    // This example uses secrets in environment variables for simplicity which should not be done in production.
+    dotenvy::dotenv().ok();
+
+    let node_url = env::var("NODE_URL").unwrap();
 
     // Create a client with that node.
     let client = Client::builder().with_node(&node_url)?.finish().await?;
 
     // Create a custom payload.
-    let tagged_data_payload = TaggedDataPayload::new(b"Your tag".to_vec(), b"Your data".to_vec())?;
+    let tagged_data_payload = TaggedDataPayload::new(*b"Your tag", *b"Your data")?;
 
     // Create and send the block with the custom payload.
     let block = client
@@ -35,7 +38,7 @@ async fn main() -> Result<()> {
 
     println!(
         "Block with custom payload sent: {}/block/{}",
-        std::env::var("EXPLORER_URL").unwrap(),
+        env::var("EXPLORER_URL").unwrap(),
         block.id()
     );