Skip to content

Latest commit

 

History

History
 
 

nodejs

README.md

IOTA SDK Library - Node.js binding

Table of contents

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 cargo-cp-artifact 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.getInfo(), and then print the node's information.

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

async function run() {
    initLogger();

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

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

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

Wallet Usage

The following example will create a new Wallet Account 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 account.
    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 account snapshot.
            password: 'a-secure-password', // A password to encrypt the stored data. WARNING: Never hardcode passwords in production code.
        },
    },
};
const wallet = new Wallet(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.

Learn More

To learn more about Neon, see the Neon documentation.

To learn more about Rust, see the Rust documentation.

To learn more about Node, see the Node documentation.