refactor(iota-sdk): align examples (#1877)

* refactor(iota-sdk): Align examples

* Highlight the cargo command with a new line

* Empty commit to trigger CI

crates/iota-sdk/README.md

@@ -160,7 +160,7 @@ See the programmable transactions [example](https://github.com/iotaledger/iota/b
    1. Publish the [`games` package(iota/iota_programmability/examples/games)](https://github.com/iotaledger/iota/tree/develop/iota_programmability/examples/games)
       using the IOTA client:
       ```shell
-      iota client publish --path /path-to-iota-source-code/iota_programmability/examples/games --gas-budget 10000
+      iota client publish --gas-budget 1000000000 iota/iota_programmability/examples/games
       ```
    1. Record the package object ID.
 

crates/iota-sdk/examples/coin_read_api.rs

@@ -2,19 +2,21 @@
 // Modifications Copyright (c) 2024 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+//! This example uses the coin read api to showcase the available
+//! functions to retrieve coin related information for a specific address.
+//! The example will use the active address in the wallet (if it exists or
+//! create one if it doesn't) check if it has coins and request coins from the
+//! faucet if there aren't any. If there is no wallet, it will create a wallet
+//! and two addresses, set one address as active, and add 1 IOTA to the active
+//! address. By default, the example will use the Iota testnet network
+//! (fullnode.testnet.iota.io:443).
+//!
+//! cargo run --example coin_read_api
+
 mod utils;
 use futures::{future, stream::StreamExt};
 use utils::setup_for_read;
 
-// This example uses the coin read api to showcase the available
-// functions to retrieve coin related information for a specific address.
-// The example will use the active address in the wallet (if it exists or create
-// one if it doesn't) check if it has coins and request coins from the faucet if
-// there aren't any. If there is no wallet, it will create a wallet and two
-// addresses, set one address as active, and add 1 IOTA to the active address.
-// By default, the example will use the Iota testnet network
-// (fullnode.testnet.iota.io:443).
-
 #[tokio::main]
 async fn main() -> Result<(), anyhow::Error> {
     let (iota, active_address) = setup_for_read().await?;

crates/iota-sdk/examples/event_api.rs

@@ -2,17 +2,19 @@
 // Modifications Copyright (c) 2024 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+//! This example showcases how to use the Event API.
+//! At the end of the program it subscribes to the events
+//! on the Iota testnet and prints every incoming event to
+//! the console. The program will loop until it is force
+//! stopped.
+//!
+//! cargo run --example event_api
+
 mod utils;
 use futures::stream::StreamExt;
 use iota_sdk::{rpc_types::EventFilter, IotaClientBuilder};
 use utils::{setup_for_write, split_coin_digest};
 
-// This example showcases how to use the Event API.
-// At the end of the program it subscribes to the events
-// on the Iota testnet and prints every incoming event to
-// the console. The program will loop until it is force
-// stopped.
-
 #[tokio::main]
 async fn main() -> Result<(), anyhow::Error> {
     let (iota, active_address, _second_address) = setup_for_write().await?;

crates/iota-sdk/examples/governance_api.rs

@@ -2,15 +2,17 @@
 // Modifications Copyright (c) 2024 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+//! This example connects to the Iota testnet
+//! and collects information about the stakes in the network,
+//! the committee information,
+//! lists all the validators' name, description, and iota address,
+//! and prints the reference gas price.
+//!
+//! cargo run --example governance_api
+
 mod utils;
 use utils::setup_for_read;
 
-// This example connects to the Iota testnet
-// and collects information about the stakes in the network,
-// the committee information,
-// lists all the validators' name, description, and iota address,
-// and prints the reference gas price.
-
 #[tokio::main]
 async fn main() -> Result<(), anyhow::Error> {
     let (iota, active_address) = setup_for_read().await?;

crates/iota-sdk/examples/iota_client.rs

@@ -2,17 +2,19 @@
 // Modifications Copyright (c) 2024 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
-use iota_sdk::IotaClientBuilder;
+//! This example shows the few basic ways to connect to a Iota network.
+//! There are several in-built methods for connecting to the
+//! Iota devnet, tesnet, and localnet (running locally),
+//! as well as a custom way for connecting to custom URLs.
+//! The example prints out the API versions of the different networks,
+//! and finally, it prints the list of available RPC methods
+//! and the list of subscriptions.
+//! Note that running this code will fail if there is no Iota network
+//! running locally on the default address: 127.0.0.1:9000
+//!
+//! cargo run --example iota_client
 
-// This example shows the few basic ways to connect to a Iota network.
-// There are several in-built methods for connecting to the
-// Iota devnet, tesnet, and localnet (running locally),
-// as well as a custom way for connecting to custom URLs.
-// The example prints out the API versions of the different networks,
-// and finally, it prints the list of available RPC methods
-// and the list of subscriptions.
-// Note that running this code will fail if there is no Iota network
-// running locally on the default address: 127.0.0.1:9000
+use iota_sdk::IotaClientBuilder;
 
 #[tokio::main]
 async fn main() -> Result<(), anyhow::Error> {

crates/iota-sdk/examples/json_rpc_errors.rs

@@ -2,6 +2,11 @@
 // Modifications Copyright (c) 2024 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+//! This example shows how one can convert RPC errors for further manual
+//! handling.
+//!
+//! cargo run --example json_rpc_errors
+
 mod utils;
 use anyhow::bail;
 use iota_sdk::error::{Error, JsonRpcError};

crates/iota-sdk/examples/programmable_transactions_api.rs

@@ -2,6 +2,22 @@
 // Modifications Copyright (c) 2024 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+//! This example shows how to use programmable transactions to chain multiple
+//! actions into one transaction. Specifically, the example retrieves two
+//! addresses from the local wallet, and then
+//! 1) finds a coin from the active address that has Iota,
+//! 2) splits the coin into one coin of 1000 MICROS and the rest,
+//! 3  transfers the split coin to second Iota address,
+//! 4) signs the transaction,
+//! 5) executes it.
+//! For some of these actions it prints some output.
+//! Finally, at the end of the program it prints the number of coins for the
+//! Iota address that received the coin.
+//! If you run this program several times, you should see the number of coins
+//! for the recipient address increases.
+//!
+//! cargo run --example programmable_transactions_api
+
 mod utils;
 use iota_config::{iota_config_dir, IOTA_KEYSTORE_FILENAME};
 use iota_keys::keystore::{AccountKeystore, FileBasedKeystore};
@@ -16,20 +32,6 @@ use iota_sdk::{
 use shared_crypto::intent::Intent;
 use utils::setup_for_write;
 
-// This example shows how to use programmable transactions to chain multiple
-// actions into one transaction. Specifically, the example retrieves two
-// addresses from the local wallet, and then
-// 1) finds a coin from the active address that has Iota,
-// 2) splits the coin into one coin of 1000 MICROS and the rest,
-// 3  transfers the split coin to second Iota address,
-// 4) signs the transaction,
-// 5) executes it.
-// For some of these actions it prints some output.
-// Finally, at the end of the program it prints the number of coins for the
-// Iota address that received the coin.
-// If you run this program several times, you should see the number of coins
-// for the recipient address increases.
-
 #[tokio::main]
 async fn main() -> Result<(), anyhow::Error> {
     // 1) get the Iota client, the sender and recipient that we will use

crates/iota-sdk/examples/read_api.rs

@@ -2,6 +2,15 @@
 // Modifications Copyright (c) 2024 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+//! This example uses the Read API to get owned objects of an address,
+//! the dynamic fields of an object,
+//! past objects, information about the chain
+//! and the protocol configuration,
+//! the transaction data after executing a transaction,
+//! and finally, the number of transaction blocks known to the server.
+//!
+//! cargo run --example read_api
+
 mod utils;
 use iota_sdk::{
     rpc_types::{
@@ -11,13 +20,6 @@ use iota_sdk::{
 };
 use utils::{setup_for_write, split_coin_digest};
 
-// This example uses the Read API to get owned objects of an address,
-// the dynamic fields of an object,
-// past objects, information about the chain
-// and the protocol configuration,
-// the transaction data after executing a transaction,
-// and finally, the number of transaction blocks known to the server.
-
 #[tokio::main]
 async fn main() -> Result<(), anyhow::Error> {
     let (iota, active_address, _) = setup_for_write().await?;
@@ -30,7 +32,7 @@ async fn main() -> Result<(), anyhow::Error> {
         .get_owned_objects(active_address, None, None, Some(5))
         .await?;
     println!(" *** Owned Objects ***");
-    println!("{:?}", owned_objects);
+    println!("{owned_objects:?}");
     println!(" *** Owned Objects ***\n");
 
     // Dynamic Fields
@@ -40,7 +42,7 @@ async fn main() -> Result<(), anyhow::Error> {
         .get_dynamic_fields(parent_object_id, None, None)
         .await?;
     println!(" *** Dynamic Fields ***");
-    println!("{:?}", dynamic_fields);
+    println!("{dynamic_fields:?}");
     println!(" *** Dynamic Fields ***\n");
     if let Some(dynamic_field_info) = dynamic_fields.data.into_iter().next() {
         println!(" *** First Dynamic Field ***");
@@ -55,11 +57,11 @@ async fn main() -> Result<(), anyhow::Error> {
     let object = owned_objects
         .data
         .first()
-        .unwrap_or_else(|| panic!("No object data for this address {}", active_address));
+        .unwrap_or_else(|| panic!("No object data for this address {active_address}"));
     let object_data = object
         .data
         .as_ref()
-        .unwrap_or_else(|| panic!("No object data for this IotaObjectResponse {:?}", object));
+        .unwrap_or_else(|| panic!("No object data for this IotaObjectResponse {object:?}"));
     let object_id = object_data.object_id;
     let version = object_data.version;
 
@@ -78,7 +80,7 @@ async fn main() -> Result<(), anyhow::Error> {
         .try_get_parsed_past_object(object_id, version, iota_data_options.clone())
         .await?;
     println!(" *** Past Object *** ");
-    println!("{:?}", past_object);
+    println!("{past_object:?}");
     println!(" *** Past Object ***\n");
 
     let iota_get_past_object_request = past_object.clone().into_object()?;
@@ -93,7 +95,7 @@ async fn main() -> Result<(), anyhow::Error> {
         )
         .await?;
     println!(" *** Multi Past Object *** ");
-    println!("{:?}", multi_past_object);
+    println!("{multi_past_object:?}");
     println!(" *** Multi Past Object ***\n");
 
     // Object with options
@@ -103,7 +105,7 @@ async fn main() -> Result<(), anyhow::Error> {
         .await?;
 
     println!(" *** Object with Options *** ");
-    println!("{:?}", object_with_options);
+    println!("{object_with_options:?}");
     println!(" *** Object with Options ***\n");
 
     println!(" *** Chain identifier *** ");
@@ -134,7 +136,7 @@ async fn main() -> Result<(), anyhow::Error> {
         .await?;
     println!("Transaction succeeded: {:?}\n\n", tx_response.status_ok());
 
-    println!("Transaction data: {:?}", tx_response);
+    println!("Transaction data: {tx_response:?}");
 
     let tx_blocks = iota.read_api().get_total_transaction_blocks().await?;
     println!("Total transaction blocks {tx_blocks}");

crates/iota-sdk/examples/sign_tx_guide.rs

@@ -2,6 +2,11 @@
 // Modifications Copyright (c) 2024 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+//! This example walks through the Rust SDK use case described in
+//! https://github.com/iotaledger/iota/blob/develop/docs/content/developer/iota-101/transactions/sign-and-send-txn.mdx
+//!
+//! cargo run --example sign_tx_guide
+
 mod utils;
 use anyhow::anyhow;
 use fastcrypto::{
@@ -27,11 +32,8 @@ use iota_types::{
 };
 use rand::{rngs::StdRng, SeedableRng};
 use shared_crypto::intent::{Intent, IntentMessage};
+use utils::request_tokens_from_faucet;
 
-use crate::utils::request_tokens_from_faucet;
-
-/// This example walks through the Rust SDK use case described in
-/// https://github.com/iotaledger/iota/blob/main/docs/content/guides/developer/iota-101/sign-and-send-txn.mdx
 #[tokio::main]
 async fn main() -> Result<(), anyhow::Error> {
     // set up iota client for the desired network.
@@ -97,7 +99,7 @@ async fn main() -> Result<(), anyhow::Error> {
     // replace `ikp_determ_0` with the variable names above
     let pk = ikp_determ_0.public();
     let sender = IotaAddress::from(&pk);
-    println!("Sender: {:?}", sender);
+    println!("Sender: {sender:?}");
 
     // make sure the sender has a gas coin as an example.
     request_tokens_from_faucet(sender, &iota_client).await?;

crates/iota-sdk/examples/tic_tac_toe.rs

@@ -2,6 +2,10 @@
 // Modifications Copyright (c) 2024 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+//! This example contains code to play the [Tic Tac Toe game](https://github.com/iotaledger/iota/blob/develop/iota_programmability/examples/games/sources/tic_tac_toe.move).
+//! Before running this example, the move package needs to be published.
+//! Follow the instructions in https://github.com/iotaledger/iota/blob/develop/crates/iota-sdk/README.md#tic-tac-toe-quick-start
+
 use std::{
     io::{stdin, stdout, Write},
     path::PathBuf,
@@ -90,7 +94,7 @@ impl TicTacToe {
                     IotaJsonValue::from_str(&player_o.to_string())?,
                 ],
                 None, // The node will pick a gas object belong to the signer if not provided.
-                1000,
+                1000000000,
                 None,
             )
             .await?;
@@ -190,7 +194,7 @@ impl TicTacToe {
                         IotaJsonValue::from_str(&col.to_string())?,
                     ],
                     None,
-                    1000,
+                    100000000,
                     None,
                 )
                 .await?;

crates/iota-sdk/examples/transaction_subscription.rs

@@ -2,16 +2,18 @@
 // Modifications Copyright (c) 2024 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+//! This example showcases how to use the Read API to listen
+//! for transactions. It subscribes to the transactions that
+//! transfer IOTA on the Iota testnet and prints every incoming
+//! transaction to the console. The program will loop until it
+//! is force stopped.
+//!
+//! cargo run --example transaction_subscription
+
 use futures::stream::StreamExt;
 use iota_json_rpc_types::TransactionFilter;
 use iota_sdk::IotaClientBuilder;
 
-// This example showcases how to use the Read API to listen
-// for transactions. It subscribes to the transactions that
-// transfer IOTA on the Iota testnet and prints every incoming
-// transaction to the console. The program will loop until it
-// is force stopped.
-
 #[tokio::main]
 async fn main() -> Result<(), anyhow::Error> {
     let ws = IotaClientBuilder::default()

crates/iota-sdk/examples/utils.rs

@@ -2,6 +2,8 @@
 // Modifications Copyright (c) 2024 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+//! This file contains utility functions for the other examples.
+
 use std::{str::FromStr, time::Duration};
 
 use anyhow::bail;
@@ -287,7 +289,7 @@ pub fn retrieve_wallet() -> Result<WalletContext, anyhow::Error> {
         }
 
         client_config.save(&wallet_conf)?;
-        info!("Client config file is stored in {:?}.", &wallet_conf);
+        info!("Client config file is stored in {wallet_conf:?}.");
     }
 
     let mut keystore = FileBasedKeystore::new(&keystore_path)?;