iota.js

IOTA JavaScript monorepo

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.

|Table of contents| |:----| | Prerequisites | Installing the library| | Getting started | | API reference | Examples| |Supporting the project| |Joining the discussion| | License|

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

Installing the library

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.

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, threshold, [callback])

• .getBundle(tailTransactionHash, [callback])

• .getInclusionStates(transactions, tips, [callback])

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

• .getLatestInclusion(transactions, tips, [callback])

• .getNeighbors([callback])

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

• .getNodeInfo([callback])

• getTips([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

As well as the following examples, you can take a look at our examples directory for more.

Creating and broadcasting transactions

This example shows you how to create and send a transaction to an IRI node by calling the prepareTransfers method and piping the prepared bundle to the sendTrytes method.

import { composeAPI } from '@iota/core'

const iota = composeAPI({
    provider: 'http://localhost:14265' // replace with your IRI node.
})

// Must be truly random & 81-trytes long.
const seed = ' your seed here '

// Array of transfers which defines transfer recipients and value transferred in IOTAs.
const transfers = [{
    address: ' recipient address here ',
    value: 1000, // 1Ki
    tag: '', // optional tag of `0-27` trytes
    message: '' // optional message in trytes
}]

// Depth or how far to go for tip selection entry point.
const depth = 3 

// Difficulty of Proof-of-Work required to attach transaction to tangle.
// Minimum value on mainnet is `14`, `7` on spamnet and `9` on devnet and other testnets.
const minWeightMagnitude = 14

// Prepare a bundle and signs it.
iota.prepareTransfers(seed, transfers)
    .then(trytes => {
        // Persist trytes locally before sending to network.
        // This allows for reattachments and prevents key reuse if trytes can't
        // be recovered by querying the network after broadcasting.

        // Does tip selection, attaches to tangle by doing PoW and broadcasts.
        return iota.sendTrytes(trytes, depth, minWeightMagnitude)
    })
    .then(bundle => {
        console.log(`Published transaction with tail hash: ${bundle[0].hash}`)
        console.log(`Bundle: ${bundle}`)
    })
    .catch(err => {
        // handle errors here
    })

Creating custom API methods

1. Install an IRI HTTP client:

   npm install @iota/http-client

2. Create an API method:

   import { createHttpClient } from '@iota/http-client'
   import { createGetNodeInfo } from '@iota/core'
   
   const client = createHttpClient({
       provider: 'http://localhost:14265'
   })
   
   const getNodeInfo = createGetNodeInfo(client)

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.

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.

License

The MIT license can be found here.