The official JavaScript client library for interacting with the Tangle

About ◈ Prerequisites ◈ Installation ◈ Getting started ◈ API reference ◈ Examples ◈ Supporting the project ◈ Joining the discussion

About

This is the official JavaScript client library, which allows you to do the following:

• Create transactions
• Sign transactions
• Generate addresses
• Interact with an IRI node

This is beta software, so there may be performance and stability issues. Please report any issues in our issue tracker.

Prerequisites

To use the library, your computer must have one of the following supported versions of Node.js:

• Node.js 10 or higher. Recommended version is latest LTS.
• Node.js 8

To install library packages, your computer must have one of the following package managers:

• npm (Included in Node.js downloads)
• Yarn

A package.json file is required. It can be generated with npm init or yarn init

Installation

To install the IOTA JavaScript client library and its dependencies, you can use one of the following options:

• Install the library with npm

  npm install @iota/core
  

• Install the library with Yarn

  yarn add @iota/core
  

Getting started

After you've installed the library, you can connect to an IRI and interface with it.

An extended guide can be found on our documentation portal, we strongly recommend you to go here for starting off. A quick starting tutorial is shown below.

To connect to a local IRI node, do the following:

import { composeAPI } from '@iota/core'

const iota = composeAPI({
    provider: 'http://localhost:14265'
})

iota.getNodeInfo()
    .then(info => console.log(info))
    .catch(error => {
        console.log(`Request error: ${error.message}`)
    })

API reference

For details on all available API methods, see the reference page.

• .composeApi([settings])

• .addNeighbors(uris, [callback])

• .attachToTangle(trunkTransaction, branchTransaction, minWeightMagnitude, trytes, [callback])

• .broadcastBundle(tailTransactionHash, [callback])

• .broadcastTransactions(trytes, [callback])

• .checkConsistency(transactions, [options], [callback])

• .findTransactionObjects(query, [callback])

• .findTransactions(query, [callback])

• .getAccountData(seed, options, [callback])

• .getBalances(addresses, [callback])

• .getBundle(tailTransactionHash, [callback])

• .getInclusionStates(transactions, [callback])

• .getInputs(seed, [options], [callback])

• .getNeighbors([callback])

• .getNewAddress(seed, [options], [callback])

• .getNodeInfo([callback])

• getTransactionObjects(hashes, [callback])

• .getTransactionsToApprove(depth, [reference], [callback])

• .getTrytes(hashes, [callback])

• .isPromotable(tail, [callback])

• .prepareTransfers(seed, transfers, [options], [callback])

• .promoteTransaction(tail, depth, minWeightMagnitude, transfer, [options], [callback])

• .removeNeighbors(uris, [callback])

• .replayBundle(tail, depth, minWeightMagnitude, [callback])

• .sendTrytes(trytes, depth, minWeightMagnitude, [reference], [callback])

• .storeAndBroadcast(trytes, [callback])

• .storeTransactions(trytes, [callback])

• .traverseBundle(trunkTransaction, [bundle], [callback])

• .generateAddress(seed, index, [security], [checksum])

Examples

We have a list of test cases in the examples directory that you can use as a reference when developing apps with IOTA.

Here's how you could send a zero-value transaction and read the message in it from the Tangle, using the library. For the guides, see the documentation portal.

const Iota = require('@iota/core');
const Converter = require('@iota/converter');
const Extract = require('@iota/extract-json')
​
// Connect to a node
const iota = Iota.composeAPI({
  provider: 'https://nodes.devnet.thetangle.org:443'
});
​
const depth = 3;
const minimumWeightMagnitude = 9;
​
// Define a seed and an address.
// These do not need to belong to anyone or have IOTA tokens.
// They must only contain a mamximum of 81 trytes
// or 90 trytes with a valid checksum
const address =
  'HEQLOWORLDHELLOWORLDHELLOWORLDHELLOWORLDHELLOWORLDHELLOWORLDHELLOWORLDHELLOWOR99D';
const seed =
  'PUEOTSEITFEVEWCWBTSIZM9NKRGJEIMXTULBACGFRQK9IMGICLBKW9TTEVSDQMGWKBXPVCBMMCXWMNPDX';
​
// Define a JSON message to send.
// This message must include only ASCII characters.
const message = JSON.stringify({"message": "Hello world"});
​
// Convert the message to trytes
const messageInTrytes = Converter.asciiToTrytes(message);
​
// Define a zero-value transaction object
// that sends the message to the address
const transfers = [
  {
    value: 0,
    address: address,
    message: messageInTrytes
  }
];
​
// Create a bundle from the `transfers` array
// and send the transaction to the node
iota
  .prepareTransfers(seed, transfers)
  .then(trytes => iota.sendTrytes(trytes, depth, minimumWeightMagnitude))
  .then(bundle => {
    // The message can be read from the Tangle, using the tail transaction hash
    const tailTransactionHash = bundle[0].hash; // NOLIVEQNRHIIRPDPHYTGJOVSGOUXVAACDNAPNTTRFNNCVNJMDZFPURTDNVTAKHPSLSJRYZGQHYBBAE999
​
    console.log(tailTransactionHash);
​
    // Get the tail transaction's bundle from the Tangle
    return iota.getBundle(tailTransactionHash)
      .then(bundle => {
        // Get your hello world message from the transaction's `signatureMessageFragment` field and print it to the console
        console.log(JSON.parse(Extract.extractJson(bundle)));
      })
  })
  .catch(err => {
    console.error(err)
  });

Supporting the project

If the IOTA JavaScript client library has been useful to you and you feel like contributing, consider posting a bug report, feature request or a pull request.

See the contributing guidelines for more information.

Cloning and bootstrapping the repository on GitHub

1. Click the Fork button in the top-right corner

2. Clone your fork and change directory into it

3. Bootstrap your environment by doing the following:

   npm run init
   

This step will download all dependencies, build and link the packages together. iota.js uses Lerna to manage multiple packages. You can re-bootstrap your setup at any point with lerna bootstrap command.

Running tests

Make your changes on a single package or across multiple packages and test the system by running the following from the root directory:

npm test

To run tests of specific package, change directory into the package's directory and run npm test from there.

Updating documentation

Please update the documention when needed by editing JSDoc annotations and running npm run docs from the root directory.

Joining the discussion

If you want to get involved in the community, need help with getting setup, have any issues related with the library or just want to discuss IOTA, Distributed Registry Technology (DRT) and IoT with other people, feel free to join our Discord.