IOTA SDK Library

The IOTA SDK is a Rust-based project that provides a convenient and efficient way to interact with nodes in the Shimmer and IOTA networks running the Stardust protocol. It consists of two main modules: client and wallet.

Table of Contents

• Requirements
  • Dependencies
• Getting Started
  • Install the IOTA SDK
• Client
• Wallet
• Examples
• API Reference
• Contribute
• License

Features

• Client module: The client module in the IOTA SDK offers low-level functions that allow you to have fine-grained control over your interactions with Shimmer nodes. The module is stateless. It provides access to the underlying API endpoints and enables advanced operations such as custom message construction and direct communication with the network.

• Wallet module: The wallet module in the IOTA SDK provides high-level functions for managing accounts, generating addresses, creating transactions, and interacting with the Shimmer network. It offers a user-friendly interface for developers to build applications on the Shimmer network. It is stateful, and it can optionally interact with IOTA Stronghold for seed handling, storage, and state backup.

• Bindings: The IOTA SDK includes bindings for Python, Node.js, and WASM, which allow you to use the SDK in your preferred programming language. These bindings provide seamless integration with existing projects, enabling cross-platform compatibility and flexibility.

Branching Structure for Development

This library follows the following branching strategy:

Branch	Description
develop	Ongoing development for future releases of the staging networks. This branch gets merged into staging on release.
production	The latest releases for the IOTA network.
staging	The latest releases for the Shimmer network.
other	Other branches that may reflect current projects. Like develop, they will find their way into staging once they are ready.

Before You Start

This file is focused on the Rust core SDK. Please refer to the Python, Node.js and Wasm instructions if you want information on installing and using them.

Requirements

The IOTA SDK requires Rust and Cargo. You can find installation instructions in the Rust documentation.

We recommend that you update the Rust compiler to the latest stable version first:

rustup update stable

Dependencies

You must also install cmake, clang, and openssl. You may need to install additional build tools on your system to run the build process successfully using Cargo.

Windows

You can download cmake from the official website. You can install openssl with vcpkg or chocolatey.

• Installing openssl with vcpkg:

./vcpkg.exe install openssl:x64-windows
./vcpkg.exe integrate install
# You may want to add this to the system environment variables since you'll need it to compile the crate
set VCPKGRS_DYNAMIC=1

• Installing openssl with chocolatey:

choco install openssl
# You may need to set the OPENSSL_DIR environment variable
set OPENSSL_DIR="C:\Program Files\OpenSSL-Win64"

macOS

You can install cmake and openssl with Homebrew:

brew install cmake [email protected]

Linux

You can install cmake, clang, and openssl with your distro's package manager or download them from their websites. On Debian and Ubuntu, you will also need the build-essential and libudev-dev packages.

Getting Started

Install the IOTA SDK

To start using the IOTA SDK in your Rust project, you can include the following dependencies in your Cargo.toml file:

[dependencies]
iota-sdk = { git = "https://github.com/iotaledger/iota-sdk" branch = "develop" }

Client Usage

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.

use iota_sdk::client::{
    Client,
};

#[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(())
}

Wallet Usage

The following example will create a new Wallet Account that connects to the Shimmer Testnet using the StrongholdSecretManager to store a mnemonic.

use iota_sdk::{
    client::{
        constants::SHIMMER_COIN_TYPE,
        secret::{stronghold::StrongholdSecretManager, SecretManager},
    },
    wallet::{ClientOptions, Result, Wallet},
};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<()> {
    // Setup Stronghold secret manager.
    // WARNING: Never hardcode passwords in production code.
    let secret_manager = StrongholdSecretManager::builder()
        .password("password") // A password to encrypt the stored data. 
        .build(PathBuf::from("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(())
}

Examples

You can use the provided code examples to get acquainted with the IOTA SDK. You can use the following command to run any example:

cargo run --example example_name --release

Where example_name is the name from the Cargo.toml name from the example folder. For example:

cargo run --example node_api_core_get_info --release 

You can get a list of the available code examples with the following command:

cargo run --example

API Reference

You can find the IOTA SDK Rust API Reference is in the IOTA SDK crate documentation.

Contribute

If you find any issues or have suggestions for improvements, please open an issue on the GitHub repository. You can also submit pull requests with bug fixes, new features, or documentation enhancements.

Before contributing, please read and adhere to the code of conduct.

License

The IOTA SDK is open-source software licensed under Apache License 2.0. For more information, please read the LICENSE.