From 9f4bc3014c7c6617247c8ad01974f2dae4b47f1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thoralf=20M=C3=BCller?= Date: Tue, 5 Sep 2023 10:22:20 +0200 Subject: [PATCH 1/7] Update getting started started examples and link to them --- README.md | 60 +------------------ .../nodejs-old/examples/getting-started.js | 3 +- .../nodejs/examples/client/getting-started.ts | 23 +++++++ .../nodejs/examples/wallet/getting-started.ts | 60 +++++++++++++++++++ bindings/python/README.md | 11 +--- .../python/examples/client/getting_started.py | 8 +++ .../python/examples/wallet/getting-started.py | 3 +- sdk/Cargo.toml | 5 ++ sdk/examples/client/getting_started.rs | 23 +++++++ sdk/examples/wallet/getting_started.rs | 47 ++++++--------- 10 files changed, 145 insertions(+), 98 deletions(-) create mode 100644 bindings/nodejs/examples/client/getting-started.ts create mode 100644 bindings/nodejs/examples/wallet/getting-started.ts create mode 100644 bindings/python/examples/client/getting_started.py create mode 100644 sdk/examples/client/getting_started.rs diff --git a/README.md b/README.md index b9ed9063cc..584846b15e 100644 --- a/README.md +++ b/README.md @@ -123,22 +123,7 @@ the [Shimmer Testnet](https://api.testnet.shimmer.network), and retrieves the no calling [`Client.get_info()`](https://docs.rs/iota-sdk/latest/iota_sdk/client/core/struct.Client.html#method.get_info), and then print the node's information. -```rust -use iota_sdk::client::{Client, Result}; - -#[tokio::main] -async fn main() -> Result<()> { - let client = Client::builder() - .with_node("https://api.testnet.shimmer.network")? // Insert your node URL here - .finish() - .await?; - - let info = client.get_info().await?; - println!("Node Info: {info:?}"); - - Ok(()) -} -``` +[sdk/examples/client/getting_started.rs](sdk/examples/client/getting_started.rs) ## Wallet Usage @@ -148,48 +133,7 @@ that connects to the [Shimmer Testnet](https://api.testnet.shimmer.network) usin [`StrongholdSecretManager`](https://docs.rs/iota-sdk/latest/iota_sdk/client/secret/stronghold/type.StrongholdSecretManager.html) to store a mnemonic. For this `features = ["stronghold"]` is needed in the Cargo.toml import. To persist the wallet in a database, `"rocksdb"` can be added. -```rust -use iota_sdk::{ - client::{ - constants::SHIMMER_COIN_TYPE, - secret::{stronghold::StrongholdSecretManager, SecretManager}, - }, - wallet::{ClientOptions, Result, Wallet}, -}; - -#[tokio::main] -async fn main() -> Result<()> { - // Setup Stronghold secret manager. - // WARNING: Never hardcode passwords in production code. - let secret_manager = StrongholdSecretManager::builder() - .password("password".to_owned()) // A password to encrypt the stored data. - .build("vault.stronghold")?; // The path to store the account snapshot. - - let client_options = ClientOptions::new().with_node("https://api.testnet.shimmer.network")?; - - // Set up and store the wallet. - let wallet = Wallet::builder() - .with_secret_manager(SecretManager::Stronghold(secret_manager)) - .with_client_options(client_options) - .with_coin_type(SHIMMER_COIN_TYPE) - .finish() - .await?; - - // Generate a mnemonic and store it in the Stronghold vault. - // INFO: It is best practice to back up the mnemonic somewhere secure. - let mnemonic = wallet.generate_mnemonic()?; - wallet.store_mnemonic(mnemonic).await?; - - // Create an account. - let account = wallet - .create_account() - .with_alias("Alice") // A name to associate with the created account. - .finish() - .await?; - - Ok(()) -} -``` +[sdk/examples/wallet/getting_started.rs](sdk/examples/wallet/getting_started.rs) ## Examples diff --git a/bindings/nodejs-old/examples/getting-started.js b/bindings/nodejs-old/examples/getting-started.js index 2c0aa2acc9..d511889011 100644 --- a/bindings/nodejs-old/examples/getting-started.js +++ b/bindings/nodejs-old/examples/getting-started.js @@ -34,9 +34,10 @@ async function main() { const manager = new AccountManager(accountManagerOptions); - // Generate a mnemonic and store it in the Stronghold vault. + // Generate a mnemonic and store its seed in the Stronghold vault. // INFO: It is best practice to back up the mnemonic somewhere secure. const mnemonic = await manager.generateMnemonic(); + console.log("Mnemonic:" + mnemonic); await manager.storeMnemonic(mnemonic); // Create an account. diff --git a/bindings/nodejs/examples/client/getting-started.ts b/bindings/nodejs/examples/client/getting-started.ts new file mode 100644 index 0000000000..41ec7270c4 --- /dev/null +++ b/bindings/nodejs/examples/client/getting-started.ts @@ -0,0 +1,23 @@ +// Copyright 2023 IOTA Stiftung +// SPDX-License-Identifier: Apache-2.0 + +import { Client } from '@iota/sdk'; + +// Run with command: +// yarn run-example ./client/getting-started.ts + +// In this example we will get information about the node +async function run() { + const client = new Client({ + nodes: ['https://api.testnet.shimmer.network'], + }); + + try { + const nodeInfo = (await client.getInfo()).nodeInfo; + console.log(nodeInfo); + } catch (error) { + console.error('Error: ', error); + } +} + +run().then(() => process.exit()); diff --git a/bindings/nodejs/examples/wallet/getting-started.ts b/bindings/nodejs/examples/wallet/getting-started.ts new file mode 100644 index 0000000000..bc403365d8 --- /dev/null +++ b/bindings/nodejs/examples/wallet/getting-started.ts @@ -0,0 +1,60 @@ +// Copyright 2023 IOTA Stiftung +// SPDX-License-Identifier: Apache-2.0 + +import { Wallet, CoinType, WalletOptions, Utils } from '@iota/sdk'; + +// Run with command: +// yarn run-example ./wallet/getting-started.ts + +// A name to associate with the created account. +const WALLET_DB_PATH = 'getting-started-db'; + +// A name to associate with the created account. +const ACCOUNT_ALIAS = 'Alice'; + +// The node to connect to. +const NODE_URL = 'https://api.testnet.shimmer.network'; + +// A password to encrypt the stored data. +// WARNING: Never hardcode passwords in production code. +const STRONGHOLD_PASSWORD = 'a-secure-password'; + +// The path to store the account snapshot. +const STRONGHOLD_SNAPSHOT_PATH = 'vault.stronghold'; + +async function main() { + const walletOptions: WalletOptions = { + storagePath: WALLET_DB_PATH, + clientOptions: { + nodes: [NODE_URL], + }, + coinType: CoinType.Shimmer, + secretManager: { + stronghold: { + snapshotPath: STRONGHOLD_SNAPSHOT_PATH, + password: STRONGHOLD_PASSWORD, + }, + }, + }; + + const wallet = new Wallet(walletOptions); + + // Generate a mnemonic and store its seed in the Stronghold vault. + // INFO: It is best practice to back up the mnemonic somewhere secure. + const mnemonic = Utils.generateMnemonic(); + console.log('Mnemonic:' + mnemonic); + await wallet.storeMnemonic(mnemonic); + + // Create an account. + const account = await wallet.createAccount({ + alias: ACCOUNT_ALIAS, + }); + + // Get the first address and print it. + const address = (await account.addresses())[0]; + console.log(`Address: ${address.address}\n`); + + process.exit(0); +} + +main(); diff --git a/bindings/python/README.md b/bindings/python/README.md index 31218ec834..b31264926e 100644 --- a/bindings/python/README.md +++ b/bindings/python/README.md @@ -66,16 +66,7 @@ the [Shimmer Testnet](https://api.testnet.shimmer.network), and retrieves the no calling [`Client.get_info()`](https://wiki.iota.org/shimmer/iota-sdk/references/python/iota_sdk/client/_node_core_api/#get_info), and then print the node's information. -```python -from iota_sdk import Client - -# Create a Client instance -client = Client(nodes=['https://api.testnet.shimmer.network']) - -# Get the node info -node_info = client.get_info() -print(f'{node_info}') -``` +[examples/client/getting_started.py](examples/client/getting_started.py) ## Wallet Usage diff --git a/bindings/python/examples/client/getting_started.py b/bindings/python/examples/client/getting_started.py new file mode 100644 index 0000000000..94d56433a3 --- /dev/null +++ b/bindings/python/examples/client/getting_started.py @@ -0,0 +1,8 @@ +from iota_sdk import Client + +# Create a Client instance +client = Client(nodes=['https://api.testnet.shimmer.network']) + +# Get the node info +node_info = client.get_info() +print(f'{node_info}') diff --git a/bindings/python/examples/wallet/getting-started.py b/bindings/python/examples/wallet/getting-started.py index 1bdd4e056d..92dcc06ac3 100644 --- a/bindings/python/examples/wallet/getting-started.py +++ b/bindings/python/examples/wallet/getting-started.py @@ -34,9 +34,10 @@ secret_manager=secret_manager ) -# Generate a mnemonic and store it in the Stronghold vault. +# Generate a mnemonic and store its seed in the Stronghold vault. # INFO: It is best practice to back up the mnemonic somewhere secure. mnemonic = Utils.generate_mnemonic() +print(f'Mnemonic: {mnemonic}') wallet.store_mnemonic(mnemonic) # Create an account. diff --git a/sdk/Cargo.toml b/sdk/Cargo.toml index 791550ea69..d815e46f46 100644 --- a/sdk/Cargo.toml +++ b/sdk/Cargo.toml @@ -624,6 +624,11 @@ name = "get_block" path = "examples/client/get_block.rs" required-features = ["client"] +[[example]] +name = "getting_started" +path = "examples/client/getting_started.rs" +required-features = ["client"] + [[example]] name = "ledger_nano" path = "examples/client/ledger_nano.rs" diff --git a/sdk/examples/client/getting_started.rs b/sdk/examples/client/getting_started.rs new file mode 100644 index 0000000000..eeabcaa57b --- /dev/null +++ b/sdk/examples/client/getting_started.rs @@ -0,0 +1,23 @@ +// Copyright 2023 IOTA Stiftung +// SPDX-License-Identifier: Apache-2.0 + +//! This examples shows how to get the node info. +//! +//! ```sh +//! cargo run --release --example getting_started +//! ``` + +use iota_sdk::client::{Client, Result}; + +#[tokio::main] +async fn main() -> Result<()> { + let client = Client::builder() + .with_node("https://api.testnet.shimmer.network")? // Insert your node URL here + .finish() + .await?; + + let info = client.get_info().await?; + println!("Node Info: {info:?}"); + + Ok(()) +} diff --git a/sdk/examples/wallet/getting_started.rs b/sdk/examples/wallet/getting_started.rs index abecbe039a..69468337fb 100644 --- a/sdk/examples/wallet/getting_started.rs +++ b/sdk/examples/wallet/getting_started.rs @@ -4,8 +4,6 @@ //! In this example we will create a new wallet, a mnemonic, and an initial account. Then, we'll print the first address //! of that account. //! -//! Make sure there's no `STRONGHOLD_SNAPSHOT_PATH` file and no `WALLET_DB_PATH` folder yet! -//! //! Rename `.env.example` to `.env` first, then run the command: //! ```sh //! cargo run --release --all-features --example wallet_getting_started @@ -21,45 +19,38 @@ use iota_sdk::{ #[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(); - - // Setup Stronghold secret_manager + // Setup Stronghold secret manager. + // WARNING: Never hardcode passwords in production code. let secret_manager = StrongholdSecretManager::builder() - .password(std::env::var("STRONGHOLD_PASSWORD").unwrap()) - .build(std::env::var("STRONGHOLD_SNAPSHOT_PATH").unwrap())?; + .password("password".to_owned()) // A password to encrypt the stored data. + .build("vault.stronghold")?; // The path to store the account snapshot. - let client_options = ClientOptions::new().with_node(&std::env::var("NODE_URL").unwrap())?; + let client_options = ClientOptions::new().with_node("https://api.testnet.shimmer.network")?; - // Create the wallet + // Set up and store the wallet. let wallet = Wallet::builder() .with_secret_manager(SecretManager::Stronghold(secret_manager)) - .with_storage_path(&std::env::var("WALLET_DB_PATH").unwrap()) .with_client_options(client_options) .with_coin_type(SHIMMER_COIN_TYPE) + .with_storage_path("getting-started-db") .finish() .await?; - // Generate a mnemonic and store it in the Stronghold vault - // INFO: It is best practice to back up the mnemonic somewhere secure + // Generate a mnemonic and store its seed in the Stronghold vault. + // INFO: It is best practice to back up the mnemonic somewhere secure. let mnemonic = wallet.generate_mnemonic()?; - wallet.store_mnemonic(mnemonic.clone()).await?; - println!("Created a wallet from the mnemonic:\n'{}'", mnemonic.as_ref()); + println!("Mnemonic: {}", mnemonic.as_ref()); + wallet.store_mnemonic(mnemonic).await?; - // Create an account - let alias = "Alice"; - let account = wallet.create_account().with_alias(alias).finish().await?; - println!("Created account '{alias}'"); + // Create an account. + let account = wallet + .create_account() + .with_alias("Alice") // A name to associate with the created account. + .finish() + .await?; - // Display the adresses in the account (only 1 for a new account) - let addresses = account.addresses().await?; - println!( - "{alias}'s addresses:\n{:#?}", - addresses - .iter() - .map(|addr| addr.address().to_string()) - .collect::>() - ); + let first_address = &account.addresses().await?[0]; + println!("{}", first_address.address()); Ok(()) } From eb3109af9f8011228338302699f7a48da1e9590c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thoralf=20M=C3=BCller?= Date: Tue, 5 Sep 2023 13:10:53 +0200 Subject: [PATCH 2/7] Update wallet getting started --- bindings/python/README.md | 21 +-------------------- 1 file changed, 1 insertion(+), 20 deletions(-) diff --git a/bindings/python/README.md b/bindings/python/README.md index b31264926e..f73adfc047 100644 --- a/bindings/python/README.md +++ b/bindings/python/README.md @@ -76,26 +76,7 @@ that connects to the [Shimmer Testnet](https://api.testnet.shimmer.network) usin [`StrongholdSecretManager`](https://wiki.iota.org/shimmer/iota-sdk/references/python/iota_sdk/secret_manager/#strongholdsecretmanager-objects) to safely store a seed derived from a mnemonic, and then print the account's information. -```python -from iota_sdk import Wallet, StrongholdSecretManager, CoinType, ClientOptions - -# This example creates a new database and account - -client_options = ClientOptions(nodes=['https://api.testnet.shimmer.network']) - -secret_manager = StrongholdSecretManager( - "wallet.stronghold", "some_hopefully_secure_password") - -wallet = Wallet('./alice-walletdb', client_options, - CoinType.SHIMMER, secret_manager) - -# Store the mnemonic in the Stronghold snapshot. This only needs to be done once -account = wallet.store_mnemonic("flame fever pig forward exact dash body idea link scrub tennis minute " + - "surge unaware prosper over waste kitten ceiling human knife arch situate civil") - -account = wallet.create_account('Alice') -print(account.get_metadata()) -``` +[examples/wallet/getting_started.py](examples/wallet/getting_started.py) ## Examples From 50426c07bb156e6aa5fa0c243187be4ca9d62627 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thoralf=20M=C3=BCller?= Date: Tue, 5 Sep 2023 13:11:45 +0200 Subject: [PATCH 3/7] snake_case --- .../examples/wallet/{getting-started.py => getting_started.py} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename bindings/python/examples/wallet/{getting-started.py => getting_started.py} (100%) diff --git a/bindings/python/examples/wallet/getting-started.py b/bindings/python/examples/wallet/getting_started.py similarity index 100% rename from bindings/python/examples/wallet/getting-started.py rename to bindings/python/examples/wallet/getting_started.py From a3a18b406428b6dc5813b655ae7159105ef8f530 Mon Sep 17 00:00:00 2001 From: Thoralf-M <46689931+Thoralf-M@users.noreply.github.com> Date: Tue, 5 Sep 2023 13:19:29 +0200 Subject: [PATCH 4/7] Update sdk/examples/client/getting_started.rs Co-authored-by: Thibault Martinez --- sdk/examples/client/getting_started.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/examples/client/getting_started.rs b/sdk/examples/client/getting_started.rs index eeabcaa57b..dce63ed8ff 100644 --- a/sdk/examples/client/getting_started.rs +++ b/sdk/examples/client/getting_started.rs @@ -4,7 +4,7 @@ //! This examples shows how to get the node info. //! //! ```sh -//! cargo run --release --example getting_started +//! cargo run --release --example client_getting_started //! ``` use iota_sdk::client::{Client, Result}; From 2543d0bc0eca207c1c04de099bdf674829ee3eef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thoralf=20M=C3=BCller?= Date: Tue, 5 Sep 2023 13:20:07 +0200 Subject: [PATCH 5/7] consistency --- sdk/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/Cargo.toml b/sdk/Cargo.toml index d815e46f46..20af48245b 100644 --- a/sdk/Cargo.toml +++ b/sdk/Cargo.toml @@ -625,7 +625,7 @@ path = "examples/client/get_block.rs" required-features = ["client"] [[example]] -name = "getting_started" +name = "client_getting_started" path = "examples/client/getting_started.rs" required-features = ["client"] From 4e663d54ccd57b51428b86d797798d7ea885e741 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thoralf=20M=C3=BCller?= Date: Tue, 5 Sep 2023 15:00:06 +0200 Subject: [PATCH 6/7] Fix comment --- bindings/nodejs/examples/wallet/getting-started.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bindings/nodejs/examples/wallet/getting-started.ts b/bindings/nodejs/examples/wallet/getting-started.ts index bc403365d8..1913122e68 100644 --- a/bindings/nodejs/examples/wallet/getting-started.ts +++ b/bindings/nodejs/examples/wallet/getting-started.ts @@ -6,7 +6,7 @@ import { Wallet, CoinType, WalletOptions, Utils } from '@iota/sdk'; // Run with command: // yarn run-example ./wallet/getting-started.ts -// A name to associate with the created account. +// The database path. const WALLET_DB_PATH = 'getting-started-db'; // A name to associate with the created account. From 500b09ea09e5ddcb4377fe229ee765b7f5843788 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thoralf=20M=C3=BCller?= Date: Wed, 6 Sep 2023 10:15:31 +0200 Subject: [PATCH 7/7] Clean readmes --- README.md | 12 ++---------- bindings/python/README.md | 12 ++---------- 2 files changed, 4 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 584846b15e..c0df14bca9 100644 --- a/README.md +++ b/README.md @@ -117,21 +117,13 @@ iota-sdk = { git = "https://github.com/iotaledger/iota-sdk", branch = "develop" ## Client Usage -The following example creates a [`Client`](https://docs.rs/iota-sdk/latest/iota_sdk/client/core/struct.Client.html) -instance connected to -the [Shimmer Testnet](https://api.testnet.shimmer.network), and retrieves the node's information by -calling [`Client.get_info()`](https://docs.rs/iota-sdk/latest/iota_sdk/client/core/struct.Client.html#method.get_info), -and then print the node's information. +The following example creates a Client instance connected to the Shimmer Testnet, and retrieves the node's information by calling `Client.get_info()`, and then print the node's information. [sdk/examples/client/getting_started.rs](sdk/examples/client/getting_started.rs) ## Wallet Usage -The following example will create a -new [`Wallet`](https://docs.rs/iota-sdk/latest/iota_sdk/wallet/core/struct.Wallet.html) [`Account`](https://docs.rs/iota-sdk/latest/iota_sdk/wallet/account/struct.Account.html) -that connects to the [Shimmer Testnet](https://api.testnet.shimmer.network) using the -[`StrongholdSecretManager`](https://docs.rs/iota-sdk/latest/iota_sdk/client/secret/stronghold/type.StrongholdSecretManager.html) -to store a mnemonic. For this `features = ["stronghold"]` is needed in the Cargo.toml import. To persist the wallet in a database, `"rocksdb"` can be added. +The following example will create a new Wallet Account using a StrongholdSecretManager. For this `features = ["stronghold"]` is needed in the Cargo.toml import. To persist the wallet in a database, `"rocksdb"` can be added. [sdk/examples/wallet/getting_started.rs](sdk/examples/wallet/getting_started.rs) diff --git a/bindings/python/README.md b/bindings/python/README.md index f73adfc047..ada5663e67 100644 --- a/bindings/python/README.md +++ b/bindings/python/README.md @@ -60,21 +60,13 @@ Python binding to the [iota-sdk library](/README.md). ## Client Usage -The following example creates a [`Client`](https://wiki.iota.org/shimmer/iota-sdk/references/python/iota_sdk/client/) -instance connected to -the [Shimmer Testnet](https://api.testnet.shimmer.network), and retrieves the node's information by -calling [`Client.get_info()`](https://wiki.iota.org/shimmer/iota-sdk/references/python/iota_sdk/client/_node_core_api/#get_info), -and then print the node's information. +The following example creates a Client instance connected to the Shimmer Testnet, and retrieves the node's information by calling `Client.get_info()`, and then print the node's information. [examples/client/getting_started.py](examples/client/getting_started.py) ## Wallet Usage -The following example will create a -new [`Wallet`](https://wiki.iota.org/shimmer/iota-sdk/references/python/iota_sdk/wallet/) [`Account`](https://wiki.iota.org/shimmer/iota-sdk/references/python/iota_sdk/wallet/account/) -that connects to the [Shimmer Testnet](https://api.testnet.shimmer.network) using the -[`StrongholdSecretManager`](https://wiki.iota.org/shimmer/iota-sdk/references/python/iota_sdk/secret_manager/#strongholdsecretmanager-objects) -to safely store a seed derived from a mnemonic, and then print the account's information. +The following example will create a new Wallet Account using a StrongholdSecretManager, and then print the account's information. [examples/wallet/getting_started.py](examples/wallet/getting_started.py)