@iota/sdk NPM | npm.io

IOTA SDK Library - Node.js binding

IOTA SDK Library - Node.js binding

Requirements

These are requirements for building the binary.

Please ensure you have installed the required dependencies for the library for Rust code, as well as the following:

Python < 3.11
Yarn v1

Windows

On Windows, you will also need an LLVM. Our workflow uses https://github.com/llvm/llvm-project/releases/download/llvmorg-16.0.6/LLVM-16.0.6-win64.exe. You may also need to set an environment variable RUSTFLAGS to -C target-feature=+crt-static.

Getting Started

Installation Using a Package Manager

To install the library with yarn, you only need to run the following:

yarn add @iota/sdk

Install the Binding from Source

Installing the Node.js bindings requires a supported version of Node and Rust.

This will guide you in any dependencies and running the build.

Build nodejs bindings

If you have already installed the project and only want to run the build, run the following:

yarn run build

This command uses the napi build utility to run the Rust build and copy the built library into ./build/Release/index.node. Prebuild requires that the binary is in build/Release as though it was built with node-gyp.

Client Usage

The following example creates a Client instance connected to the Shimmer Testnet, and retrieves the node's information by calling Client.getNodeInfo(), and then print the node's information.

const { Client, initLogger } = require('@iota/sdk');

async function run() {
    initLogger();

    const client = await Client.create({
        nodes: ['https://api.testnet.shimmer.network'],
    });

    try {
        const nodeInfo = await client.getNodeInfo();
        console.log('Node info: ', nodeInfo);
    } catch (error) {
        console.error('Error: ', error);
    }
}

void run().then(() => process.exit());

Wallet Usage

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

import {  Wallet, CoinType, WalletOptions } from '@iota/sdk';

const walletOptions: WalletOptions = {
    storagePath: `Alice`, // A name to associate with the created wallet.
    clientOptions: {
        nodes: ['https://api.testnet.shimmer.network'], // The node to connect to.
    },
    coinType: CoinType.Shimmer,
    secretManager: {
        // Setup Stronghold secret manager
        stronghold: {
            snapshotPath: 'vault.stronghold', //  The path to store the wallet snapshot.
            password: 'a-secure-password', // A password to encrypt the stored data. WARNING: Never hardcode passwords in production code.
        },
    },
};
const wallet = await Wallet.create(walletOptions);

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:

cd examples
yarn run-example ./[example folder]/[example file]

Where [example file] is the file name from the example folder. For example:

node examples/client/00_get_info.ts

API Reference

You can find the API reference for the Node.js bindings in the IOTA Wiki.

Available Scripts

In the project directory, you can run the following:

`yarn install`

Installs the project, including running yarn run build.

`yarn build`

Builds the Node addon (index.node) from source.

`yarn test`

Runs the unit tests by calling cargo test. You can learn more about adding tests to your Rust code from the Rust book.

`yarn create-api-docs`

This is mainly just used to create the API docs in the Wiki. Executed locally it will generate a docs folder in the current working directory with the API docs.

Important Files and Directories

Cargo.toml
The Cargo manifest file informs the cargo command.
index.node
The Node addon - i.e., a binary Node module - is generated by building the project. This is the main module for this package, as dictated by the "main" key in package.json.
Under the hood, a Node addon is a dynamically-linked shared object. The "build" script produces this file by copying it from within the target/ directory, which is where the Rust build produces the shared object.
package.json
The npm manifest file, which informs the yarn command.
src/
The directory tree that contains the Rust source code for the project.
src/lib.rs
The Rust library's main module.
target/
Binary artifacts generated by the Rust build.