Skip to content

Latest commit

 

History

History
237 lines (177 loc) · 6.36 KB

README.md

File metadata and controls

237 lines (177 loc) · 6.36 KB

IOTA SDK Library - WebAssembly Bindings

WebAssembly (Wasm) bindings for TypeScript/JavaScript to the IOTA SDK library.

Which Bindings to Choose?

The IOTA SDK library also offers dedicated Node.js bindings. The differences with this package are outlined below.

NOTE: Use the Node.js bindings if you can. The Wasm bindings are more portable and exist to support browser environments.

Wasm bindings Node.js bindings
Environment Node.js, browsers Node.js
Installation - Rust, Cargo required*
Performance ✔️ ✔️✔️
Ledger Nano ✔️
Rocksdb ✔️
Stronghold ✔️
  • The Node.js bindings only need to be compiled during yarn install if a pre-compiled binary is not available for your platform.

Requirements

  • One of the following Node.js versions: '16.x', '18.x';
  • wasm-bindgen (cargo install wasm-bindgen-cli);

Getting Started

Installing Using a Package Manager

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

yarn add @iota/sdk-wasm

Web Setup

The library loads the compiled Wasm file with an HTTP GET request, so the iota_sdk_wasm_bg.wasm file must be copied to the root of the distribution folder.

A bundler such as webpack or rollup is recommended.

Rollup

  1. Install rollup-plugin-copy:

    yarn add rollup-plugin-copy --save-dev
  2. Add the plugin to your rollup.config.js:

    // Include the copy plugin.
    import copy from 'rollup-plugin-copy'
    
    // ...
    
    // Add the copy plugin to the `plugins` array:
    copy({
      targets: [{
        src: 'node_modules/@iota/sdk-wasm/web/wasm/iota_sdk_wasm_bg.wasm',
        dest: 'public',
        rename: 'iota_sdk_wasm_bg.wasm'
      }]
    })

Webpack

  1. Install copy-webpack-plugin:

    yarn add copy-webpack-plugin --save-dev
  2. Add the plugin to your webpack.config.js:

    // Include the copy plugin.
    const CopyWebPlugin = require('copy-webpack-plugin');
    
    // ...
    
    experiments: {
        // futureDefaults: true, // includes asyncWebAssembly, topLevelAwait etc.
        asyncWebAssembly: true
    }
    
    // Add the copy plugin to the `plugins` array:
    plugins: [
        new CopyWebPlugin({
          patterns: [
            {
              from: 'node_modules/@iota/sdk-wasm/web/wasm/iota_sdk_wasm_bg.wasm',
              to: 'iota_sdk_wasm_bg.wasm'
            }
          ]
        }),
        // other plugins...
    ]

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.

Node.js

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

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());

Web

import init, {Client, initLogger} from "@iota/sdk-wasm/web";

init().then(async () => {
    initLogger();

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

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

// Default path to load is "iota_sdk_wasm_bg.wasm", 
// but you can override it by passing a path explicitly.
//
// init("./static/iota_sdk_wasm_bg.wasm").then(...)

Wallet Usage

The following example will create a new Wallet Account that connects to the Shimmer Testnet using the MnemonicSecretManager by calling the Wallet.createAccount(data) function.

Node.js

const { Wallet, CoinType } = require('@iota/sdk-wasm/node');

async function run() {
    try {
        const wallet = new Wallet({
            storagePath: './my-database',
            coinType: CoinType.Shimmer,
            clientOptions: {
                nodes: ['https://api.testnet.shimmer.network'],
            },
            secretManager: {
                mnemonic: "my development mnemonic",
            },
        });

        const account = await wallet.createAccount({
            alias: 'Alice',
        });

        const addresses = await account.addresses();
        console.log(addresses);
    } catch (err) { console.error }
}

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

Web

import init, {Wallet, CoinType} from "@iota/sdk-wasm/web";

init().then(async () => {
    const wallet = new Wallet({
        storagePath: './my-database',
        coinType: CoinType.Shimmer,
        clientOptions: {
            nodes: ['https://api.testnet.shimmer.network'],
        },
        secretManager: {
            mnemonic: "my development mnemonic",
        },
    });

    const account = await wallet.createAccount({
        alias: 'Alice',
    });

    const addresses = await account.addresses();
    console.log(addresses);
}).catch(console.error);

// Default path to load is "iota_sdk_wasm_bg.wasm", 
// but you can override it by passing a path explicitly.
//
// init("./static/iota_sdk_wasm_bg.wasm").then(...)

API Reference

If you are using the Wasm binding, you use the Node.js API reference in the IOTA Wiki.