IOTA Trust Hierarchies

Install the Library

If your project does not contain it already, install the peer dependency @iota/iota-sdk as well.

npm install @iota/iota-sdk

You can install the latest alpha version of the library by running the following command:

npm install @iota/hierarchies@alpha

Build the Library

Alternatively, you can build the bindings yourself if you have Rust installed. If not, refer to rustup.rs for the installation.

Requirements

• Node.js (>= v20)
• Rust (>= 1.65)
• Cargo (>= 1.65)
• for running example: a local network node with the IOTA hierarchies package deployed as being described here

1. Install Local Tooling

If you want to build the library from source you have to install additional build tools locally.

Install wasm-bindgen-cli

First you need to install wasm-bindgen-cli. A manual installation is required because we use the Weak References feature, which wasm-pack does not expose.

cargo install --force wasm-bindgen-cli

Install wasm-opt

To reduce the size of the wasm package, it is optimized with wasm-opt, which is part of binaryen.

You can either download a release of binaryen and make the bin folder available in your PATH or check if your operating system tooling offers a more convenient way of installing the binaries like APT, Homebrew, etc.

Some examples:

• Linux via APT: sudo apt-get update && sudo apt-get -y install binaryen (taken from here)
• MacOS via Homebrew: brew install binaryen (see Homebrew entry)

2. Install Dependencies

After installing local tooling, you can install the necessary dependencies using the following command:

npm install

3. Build

You can build the bindings for node.js using the following command:

npm run build:nodejs

You can build the bindings for the web using the following command:

npm run build:web

Web Usage

The web version of this library requires explicit WASM initialization before any other function can be used. Call and await the init() function once during your application startup:

import { HierarchiesClientReadOnly, init } from "@iota/hierarchies/web";
import { getFullnodeUrl, IotaClient } from "@iota/iota-sdk/client";

// Initialize the WASM module (required, must be awaited before any other usage)
await init();

const iotaClient = new IotaClient({ url: getFullnodeUrl("testnet") });
const client = await HierarchiesClientReadOnly.create(iotaClient);

If you are using a bundler like Vite, pass the WASM URL explicitly:

import { init } from "@iota/hierarchies/web";
import wasmUrl from "@iota/hierarchies/web/hierarchies_wasm_bg.wasm?url";

await init(wasmUrl);

Note: The Node.js version (@iota/hierarchies/node) does not require calling init() — the WASM module is loaded automatically.