IOTA Client Library - Node.js binding

Node.js binding to the IOTA client library.

Installation

• Using NPM:

$ npm i @iota/client

• Using yarn:

$ yarn add @iota/client

Requirements

One of the following Node.js version: '10.x', '12.x', '14.x', '15.x', '16.x'

If there is no prebuilt binary available for your system you need Rust and Cargo, to build it yourself. Install them here.

Getting Started

After you linked the library, you can create a Client instance and interface with it.

const { ClientBuilder } = require('@iota/client')
const client = new ClientBuilder()
    .node('https://api.lb-0.h.chrysalis-devnet.iota.cafe')
    .build()
client.getInfo().then(console.log).catch(console.error)

Connecting to a MQTT broker using raw ip doesn't work with TCP. This is a limitation of rustls.

API Reference

ClientBuilder

node(url): ClientBuilder

Adds an IOTA node to the client pool.

Param	Type	Description
url	string	A node URL

Returns the client builder instance for chained calls.

nodeAuth(url, authOptions): ClientBuilder

Adds an IOTA node with authentication to the client pool.

Param	Type	Description
url	string	A node URL
authOptions	NodeAuthOptions	Options for node authentication

Returns the client builder instance for chained calls.

primaryNode(url, [, authOptions]): ClientBuilder

Add a node to always connect first to with optional authentication.

Param	Type	Description
url	string	A node URL
authOptions	NodeAuthOptions	Options for node authentication

Returns the client builder instance for chained calls.

primaryPowNode(url, [, authOptions]): ClientBuilder

Add a node to always connect first to when using remote PoW with optional authentication. Will overwrite the primary node for this case.

Param	Type	Description
url	string	A node URL
authOptions	NodeAuthOptions	Options for node authentication

Returns the client builder instance for chained calls.

permanode(url, [, authOptions]): ClientBuilder

Add a permanode.

Param	Type	Description
url	string	A node URL
authOptions	NodeAuthOptions	Options for node authentication

Returns the client builder instance for chained calls.

nodes(urls): ClientBuilder

Adds a list of IOTA nodes to the client pool.

Param	Type	Description
url	string[]	An array of node URLs

Returns the client builder instance for chained calls.

nodePoolUrls(urls): ClientBuilder

Adds a list of IOTA nodes from node pool URLs to the client pool.

Param	Type	Description
url	string[]	An array of node pool URLs

Returns the client builder instance for chained calls.

network(networkName): ClientBuilder

Set a network to get default nodes for it. Can be "testnet" or "mainnet". Nodes that don't belong to this network are ignored.

Param	Type	Description
networkName	string	The network

Returns the client builder instance for chained calls.

quorum(enabled): ClientBuilder

Defines how many of nodes will be queried at the same time to check for quorum.

Param	Type	Description
enabled	boolean	Define if quourm should be used or not

Returns the client builder instance for chained calls.

quorumSize(size): ClientBuilder

Defines how many of nodes will be queried at the same time to check for quorum.

Param	Type	Description
size	number	The number of nodes that will be queried

Returns the client builder instance for chained calls.

quorumThreshold(threshold): ClientBuilder

Defines the minimum amount of nodes from the quorum pool that need to agree if we want to consider the result true.

Param	Type	Description
threshold	number	Minimum amount of nodes

Returns the client builder instance for chained calls.

brokerOptions(options): ClientBuilder

Sets the options for the MQTT connection with the node.

Param	Type	Description
options	BrokerOptions	The MQTT broker options

Returns the client builder instance for chained calls.

nodeSyncInterval(interval): ClientBuilder

Sets the node syncing interval.

Param	Type	Description
interval	number	The interval for the node syncing process

Returns the client builder instance for chained calls.

disableNodeSync(): ClientBuilder

Disables the node syncing process. Every node will be considered healthy and ready to use.

Returns the client builder instance for chained calls.

offlineMode(): ClientBuilder

Allows creating the client without nodes for offline address generation or signing.

Returns the client builder instance for chained calls.

requestTimeout(timeoutMs): ClientBuilder

Sets the default HTTP request timeout.

Param	Type	Description
timeout	number	The timeout in milliseconds

Returns the client builder instance for chained calls.

apiTimeout(api, timeoutMs): ClientBuilder

Sets the HTTP request timeout for the specified API.

Param	Type	Description
api	'GetHealth' | 'GetInfo' | 'GetTips' | 'PostMessage' | 'PostMessageWithRemotePow' | 'GetOutput' | 'GetMilestone'	The API to set the request timeout
timeout	number	The timeout in milliseconds

Returns the client builder instance for chained calls.

localPow(local): ClientBuilder

Sets the PoW type.

Param	Type	Description
local	boolean	Flag determining if PoW should be done locally or remotely

Returns the client builder instance for chained calls.

build(): Client

Builds the client instance.

Returns a Client instance.

Client

networkInfo(): NetworkInfo

Gets the cached network info.

Returns a NetworkInfo instance.

subscriber(): TopicSubscriber

Gets a handle to the MQTT topic subscriber.

Returns a TopicSubscriber instance.

message(): MessageSender

Initiates the builder to send messages.

Returns a MessageSender instance.

getUnspentAddress(seed): UnspentAddressGetter

Get a valid unspent address.

Param	Type	Description
seed	string	The hex-encoded seed to search

Returns a UnspentAddressGetter instance.

getAddresses(seed): AddressGetter

Find addresses from the seed regardless of their validity.

Param	Type	Description
seed	string	The hex-encoded seed to search

Returns a AddressGetter instance.

findMessages(indexationKeys, messageIds): Promise<Message[]>

Finds all messages associated with the given indexation keys and message ids.

Param	Type	Description
indexationKeys	string[]	The list of indexations keys too search
messageIds	string[]	The list of message ids to search

Returns a promise resolving to the list of the found messages.

getBalance(seed: string): BalanceGetter

Get balance on a given seed and its wallet account index.

Param	Type	Description
seed	string	The hex-encoded seed to search

Returns a BalanceGetter instance.

getAddressBalances(addresses): Promise<AddressBalance[]>

Get the balance in iotas for the given addresses.

Param	Type	Description
addresses	string[]	The list of addresses to search

Returns A promise resolving to the list of { address, balance } pairs.

generateMnemonic()

Returns a random generated Bip39 mnemonic with the English word list.

Returns A String

mnemonicToHexSeed(mnemonic)

Returns the seed hex encoded.

Param	Type	Description
mnemonic	string	Bip39 mnemonic with words from the English word list.

Returns A String

bech32ToHex(bech32)

Returns a parsed hex String from bech32.

Param	Type	Description
bech32	string	The address Bech32 string

Returns A String

hexToBech32(hex, bech32_hrp (optional))

Returns a parsed bech32 address String from a hex encoded address.

Param	Type	Description
address	string	The hex encoded address string
bech32_hrp	string	The Bech32 hrp string

Returns A String

hexPublicKeyToBech32Address(hex, bech32_hrp (optional))

Returns a parsed bech32 address String from a hex encoded public key.

Param	Type	Description
publicKey	string	The hex encoded public key
bech32_hrp	string	The Bech32 hrp string

Returns A String

isAddressValid(address: string): boolean

Checks if a given address is valid.

Param	Type	Description
address	string	The address Bech32 string

Returns A boolean.

getMessageId(message: string): boolean

Returns the message id from a message.

Param	Type	Description
message	string	The message id

Returns the message id.

retry(messageId: string): Promise

Retries (promotes or reattaches) the message associated with the given id.

Param	Type	Description
messageId	string	The id of the message to retry

Returns A promise resolving to the new Message instance.

retryUntilIncluded(messageId: string[, interval: int, maxAttempts: int]): Promise

Retries (promotes or reattaches) the message associated with the given id until it's included in the Tangle. Default interval is 5 seconds and max_attempts is 10.

Param	Type	Description
messageId	string	The id of the message to retry
[options.interval]	int	The interval in seconds in which we retry the message.
[options.maxAttempts]	int	The maximum of attempts we retry the message.

Returns the message ids and Message of reattached messages.

consolidateFunds(seed: string, accountIndex: int, startIndex: int, endIndex: int): Promise

Function to consolidate all funds from a range of addresses to the address with the lowest index in that range

Param	Type	Description
seed	string	The seed
accountIndex	int	The account index.
startIndex	int	The lowest address index, funds will be consolidated to this address.
endIndex	int	The address index until which funds will be consolidated

Returns the address to which the funds got consolidated, if any were available.

getInfo(): Promise

Gets information about the node.

Returns a promise resolving to the NodeInfoWrapper object.

getTips(): Promise<[string, string]>

Gets two non-lazy tips.

Returns a promise resolving to an array of length 2 containing the message ids of the tips.

postMessage(message): Promise

Submits a message.

Param	Type	Description
message	MessageDto	The message to submit

Returns the message identifier.

getMessage(): MessageFinder

Gets a message from its identifier.

Returns an instance of the MessageFinder for choices of response.

getOutput(outputId): Promise

Gets the UTXO outputs associated with the given output id.

Param	Type	Description
outputId	string	The id of the output to search

Returns a promise resolving to the associated OutputMetadata.

findOutputs(outputIds, addresses): Promise<OutputMetadata[]>

Gets the UTXO outputs associated with the given output ids and addresses.

Param	Type	Description
addresses	string[]	The list of addresses to search
outputIds	string[]	The list of output ids to search

Returns a promise resolving to a list of OutputMetadata.

findInputs(addresses, amount): Promise<string[]>

Function to find inputs from addresses for a provided amount (useful for offline signing)

Param	Type	Description
addresses	string[]	The list of addresses to search
amount	number	The balance to search inputs for

Returns a promise resolving to a list of outputIds: string[].

getAddressOutputs(address[, options]): Promise<string[]>

Gets the UTXO outputs associated with the given address.

Param	Type	Description
address	string	The address Bech32 string
[options.includeSpent]	boolean	Whether the query should include spent outputs or not
[options.outputType]	'SignatureLockedSingle' | 'SignatureLockedDustAllowance'	The output type filter

Returns a promise resolving to a list of output ids.

getAddressBalance(address): Promise

Gets the balance of the given address.

Param	Type	Description
address	string	The address Bech32 string

getMilestone(index): Promise

Gets the milestone by the given index.

Param	Type	Description
index	number	The index of the milestone

Returns a promise resolving to the MilestoneMetadata.

getMilestoneUtxoChanges(index): Promise

Gets the utxo changes by the given milestone index.

Param	Type	Description
index	number	The index of the milestone

Returns a promise resolving to the MilestoneUTXOChanges.

getReceipts(): Promise<Receipts[]>

Get all receipts.

Returns a promise resolving to the Receipts.

getReceiptsMigratedAt(index): Promise<Receipts[]>

Get all receipts for a given milestone index

Param	Type	Description
index	number	The index of the milestone

Returns a promise resolving to the Receipts.

getTreasury(): Promise

Get the treasury amount.

Returns a promise resolving to the Treasury.

getIncludedMessage(transactionId): Promise

Get the included message of a transaction.

Param	Type	Description
transactionId	string	The id of the transaction

Returns A promise resolving to the new Message instance.

reattach(messageId): Promise

Reattaches the message associated with the given id.

Param	Type	Description
messageId	string	The id of the message to reattach

Returns A promise resolving to the new Message instance.

promote(messageId): Promise

Promotes the message associated with the given id.

Param	Type	Description
messageId	string	The id of the message to promote

Returns A promise resolving to the new Message instance.

NetworkInfo

Field	Type	Description
network	string	The network
networkId	number	The network hashed
bech32HRP	string	Bech32 HRP for this network
minPoWScore	number	The network's minimum score for PoW
localPow	boolean	Whether we are using local PoW or not

TopicSubscriber

Possible topics:

milestones/latest
milestones/confirmed

messages
messages/referenced
messages/indexation/{index}
messages/{messageId}/metadata
transactions/{transactionId}/included-message

outputs/{outputId}

addresses/{address}/outputs
addresses/ed25519/{address}/outputs

topic(topic): TopicSubscriber

Adds a topic to this manager instance.

Param	Type	Description
topic	string	A MQTT topic

Returns the topic subscriber instance for chained calls.

topics(topic): TopicSubscriber

Adds a list of topics to this manager instance.

Param	Type	Description
topics	string[]	An array of MQTT topics

Returns the topic subscriber instance for chained calls.

subscribe(cb): TopicSubscriber

Subscribe to the provided topics.

Param	Type	Description
cb	function	The topic handler callback in the form of (err, message) => {}

Returns the topic subscriber instance for chained calls.

unsubscribe(cb: Callback): TopicSubscriber

Unsubscribes from the provided topics.

Param	Type	Description
cb	function	A callback executed when the unsubscribe is finished in the form of (err, message) => {}

Returns the topic subscriber instance for chained calls.

MessageSender

Builder to create and submit messages to the Tangle.

index(index): MessageSender

Sets the message indexation. This field is required for indexation payloads.

Param	Type	Description
index	string	number[]

Returns the message submit instance for chained calls.

data(data): MessageSender

Sets the indexation data.

Param	Type	Description
data	string	Uint8Array

Returns the message submit instance for chained calls.

seed(seed): MessageSender

Sets the transaction account seed. This field is required for transaction payloads.

Param	Type	Description
seed	string	The hex-encoded seed of the account to spend

Returns the message submit instance for chained calls.

parents(messageId): MessageSender

Sets 1-8 custom parent message ids.

Param	Type	Description
messageId	string[]	The parents message ids

Returns the message submit instance for chained calls.

accountIndex(index): MessageSender

Sets the account index. This field is required for transactions.

Param	Type	Description
index	number	The account index

Returns the message submit instance for chained calls.

input(transactionId, index): MessageSender

Adds an output to the transaction.

Param	Type	Description
transactionId	string	The transaction id
index	number	The input index

Returns the message submit instance for chained calls.

inputRange(start, end): MessageSender

Defines the range in which to search for addresses fro custom inputs.

Param	Type	Description
start	number	The start index
end	number	The end index

Returns the message submit instance for chained calls.

output(address, amount): MessageSender

Adds an output to the transaction.

Param	Type	Description
address	string	The output address
amount	number	The output amount

Returns the message submit instance for chained calls.

dustAllowanceOutput(address, amount): MessageSender

Adds a dust allowance output to the transaction.

Param	Type	Description
address	string	The output address
amount	number	The output amount

Returns the message submit instance for chained calls.

initialAddressIndex(index): MessageSender

Sets the initial address index to search for balance. Defaults to 0 if the function isn't called.

Param	Type	Description
index	number	The initial address index

Returns the message submit instance for chained calls.

prepareTransaction(index): Promise

Prepares a transaction with the provided inputs.

Returns prepared transaction data that can be signed offline.

signTransaction(preparedTransactionData: PreparedTransactionData, seed: string[, startIndex: number, endIndex: number]): Promise

Sets the initial address index to search for balance. Defaults to 0 if the function isn't called.

Param	Type	Description
preparedTransactionData	PreparedTransactionData	The prepared transaction data from prepareTransaction()
seed	string	The seed
startIndex	number	Start index to find the addresses for signing, default is 0
endIndex	number	End index to find the addresses for signing, default is 100

Returns the signed transaction payload.

finishMessage(Payload): Promise

Creates a message with the provided payload.

Param	Type	Description
payload	Payload	A message payload

Returns a promise resolving to the MessageWrapper.

submit(): Promise

Submits the message.

Returns a promise resolving to the MessageWrapper.

UnspentAddressGetter

Gets a valid unspent address associated with the seed.

accountIndex(index): UnspentAddressGetter

Sets the account index. This field is required.

Param	Type	Description
index	number	The account index

Returns the address getter instance for chained calls.

initialAddressIndex(index): UnspentAddressGetter

Sets the initial address index. Defaults to 0 if the function isn't called.

Param	Type	Description
index	number	The initial address index

Returns the address getter instance for chained calls.

get(): Promise<[Address, number]>

Performs the operation.

Returns a promise resolving to the Address instance and its index.

AddressGetter

Generates addresses with a given seed.

accountIndex(index): AddressGetter

Sets the account index. This field is required.

Param	Type	Description
index	number	The account index

Returns the address finder instance for chained calls.

range(start, end): AddressGetter

Defines the range of addresses to get. Defaults to 0..20 if the function isn't called.

Param	Type	Description
start	number	The first address index
end	number	The last address index

Returns the address finder instance for chained calls.

includeInternal(): AddressGetter

Defines that public and internal address will be returned instead of only public addresses.

Returns the address finder instance for chained calls.

bech32Hrp(bech32Hrp): AddressGetter

Defines the bech32Hrp for the bech32 encoded addresses, required when generating addresses offline(with disableNodeSync()).

Param	Type	Description
bech32Hrp	string	The bech32Hrp for the addresses

Returns the address finder instance for chained calls.

get(): Address[] | [Address, bool][]

Performs the operation.

Returns an array of public Address instances or an array of arrays with an Address and a bool, where the bool defines whether it's an internal address or not.

BalanceGetter

Gets balance on a given seed.

accountIndex(index): BalanceGetter

Sets the account index. This field is required.

Param	Type	Description
index	number	The account index

Returns the balance getter instance for chained calls.

initialAddressIndex(index): BalanceGetter

Sets the initial address index. Defaults to 0 if the function isn't called.

Param	Type	Description
index	number	The initial address index

Returns the balance getter instance for chained calls.

gapLimit(amount): BalanceGetter

Sets the gapLimit to specify how many addresses will be checked each round. If gapLimit amount of addresses in a row have no balance the BalanceGetter will return. Defaults to 20 if the function isn't called.

Param	Type	Description
gapLimit	number	The initial address index

Returns the balance getter instance for chained calls.

get(): Promise

Performs the operation.

Returns a promise resolving to the account balance.

MessageFinder

Gets a message by indexation key or identifier.

initialAddressIndex(index): Promise<string[]>

Param	Type	Description
index	string	The indexation key

Gets a list of message identifiers associated with the given indexation key.

Returns a promise resolving to the list of associated ids.

data(id): Promise

Gets the message object associated with the given identifier.

Param	Type	Description
id	string	The message identifier

Returns a Message object.

raw(id): Promise

Gets the message raw data.

Param	Type	Description
id	string	The message identifier

Returns the message raw data as string.

children(id): Promise<string[]>

Gets the children of the given message.

Param	Type	Description
id	string	The message identifier

Returns the list of message ids of the message children.

metadata(id): Promise

Gets the metadata of the given message.

Param	Type	Description
id	string	The message identifier

Returns a MessageMetadata object.

BrokerOptions

All fields are optional.

Field	Type	Description
automaticDisconnect	boolean	Whether the MQTT broker should be automatically disconnected when all topics are unsubscribed or not.
timeout	number	MQTT connection timeout in secods
useWs	boolean	Defines if websockets should be used (true) or TCP (false)
maxReconnectionAttempts	number	Defines the maximum reconnection attempts before it returns an error
port	number	Defines the port to be used for the MQTT connection

NodeAuthOptions

Field	Type	Description
jwt	string	Optional JSON Web Token.
basicAuthName	string	Optional name for basic authentication
basicAuthPassword	string	Optional password for basic authentication

Address

Field	Type	Description
data	string	Address as a Bech32 string

Message

Field	Type	Description
networkId	number	Network identifier
parents	string[]	Message ids of the message references
payload	Payload | null	Message payload
nonce	number	Message nonce

MessageWrapper

Field	Type	Description
message	Message	Message
messageId	string	The message id

Payload

Field	Type	Description
data	TransactionPayload | IndexationPayload | MilestonePayload | ReceiptPayload	Payload data

TransactionPayload

Field	Type	Description
type	number	Payload type
essence	TransactionPayloadEssence	Transaction essence
unlock_blocks	UnlockBlock[]	Unlock blocks

• TransactionPayloadEssence

Field	Type	Description
type	number	Essence type
inputs	Input[]	Inputs
outputs	Output[]	Outputs
payload	Payload | undefined	Payload for chaining

• Input

Field	Type	Description
type	number	Input type identifier
data	string	The associated output id

• Output

Field	Type	Description
type	number	Output type identifier
data	{ address: string, amount: number }	The output definition

• UnlockBlock

Field	Type	Description
type	number	Unlock block type identifier
data	Ed25519SignatureUnlockBlock | ReferenceUnlockBlock	Unlock block data (signature type or reference index)

• Ed25519SignatureUnlockBlock

Field	Type	Description
type	number	Unlock type identifier
public_key	string	Ed25519 public key
signature	string	Ed25519 signature

• ReferenceUnlockBlock

Field	Type	Description
type	number	Unlock block type identifier
reference	number	Represents the index of a previous unlock block.

IndexationPayload

Field	Type	Description
type	number	Payload type
index	string	Indexation key
data	string	Indexation data as byte array

MilestonePayload

Field	Type	Description
type	number	Payload type identifier
index	number	Milestone index
timestamp	number	Timestamp
parentMessageIds	string[]	Message ids of the messages the milestone references
inclusionMerkleProof	string	Merkle proof
nextPoWScore	number	Next PoW score
nextPoWScoreMilestoneIndex	number	Milestone index at which the nextPoWScore will be used
publicKeys	string[]	public keys
receipt	Payload| null	Optional receipt payload
signatures	string[]	Milestone signatures

MessageDto

Field	Type	Description
parents	string[] | undefined	Message ids of the messages it references. getTips is used by default
payload	PayloadDto	Message payload

PayloadDto

Field	Type	Description
data	TransactionPayloadDto | IndexationPayloadDto	Payload data

TransactionPayloadDto

Field	Type	Description
essence	TransactionPayloadEssenceDto	Transaction essence
unlockBlocks	UnlockBlockDto[]	Unlock blocks

• TransactionPayloadEssenceDto

Field	Type	Description
inputs	string[]	Inputs
outputs	Output[]	Outputs
payload	PayloadDto | undefined	Payload for chaining

• OutputDto

Field	Type	Description
address	string	Output address
amount	amount	Output amount

• UnlockBlockDto

Field	Type	Description
data	Ed25519SignatureUnlockBlockDto | number	Unlock block data (signature type or reference index)

• Ed25519SignatureUnlockBlockDto

Field	Type	Description
publicKey	number[]	Ed25519 public key
signature	number[]	Ed25519 signature

IndexationPayloadDto

Field	Type	Description
index	string	Indexation key
data	string	Indexation data

AddressBalance

Field	Type	Description
address	string	Bech32 encoded address
balance	number	Address balance
dustAllowed	boolean	Dust allowed

MessageMetadata

Field	Type	Description
messageId	string	Message identifier
parents	string[]	Message id of the messages it references
isSolid	boolean	Message solid state
shouldPromote	boolean | undefined	Indicates whether the message should be promoted or not
shouldReattach	boolean | undefined	Indicates whether the message should be reattached or not
referencedByMilestoneIndex	number | undefined	Index of the milestone that references this message
ledgerInclusionState	string | undefined	Ledger inclusion state

NodeInfoWrapper

Field	Type	Description
url	string	Node url
nodeinfo	NodeInfo	NodeInfo

NodeInfo

Field	Type	Description
name	string	Node name
version	string	Node version
isHealthy	boolean	Node health status
networkId	string	Node network identifier
bech32HRP	string	Bech32 HRP for this network
minPoWScore	number	Min PoW score
messagesPerSecond	number	Network stats: Messages per second in the network
referencedMessagesPerSecond	number	Network stats: Referenced messages per second
referencedRate	number	Network stats: referenced rate
latestMilestoneTimestamp	number	Timestamp of the latest milestone
latestMilestoneIndex	number	Index of the latest milestone
confirmedMilestoneIndex	number	Index of the confirmed milestone
pruningIndex	number	Pruning index
features	string[]	List of node features

OutputMetadata

Field	Type	Description
messageId	string	Id of the message associated with the output
transactionId	string	Id of the transaction associated with the output
outputIndex	number	Output index
isSpent	boolean	Output spent state
address	string	Output address
amount	number	Output amount

MilestoneMetadata

Field	Type	Description
milestoneIndex	number	Milestone index
messageId	string	Id of the message associated with the milestone
timestamp	number	Milestone timestamp

MilestoneUTXOChanges

Field	Type	Description
index	number	Milestone index
createdOutputs	string[]	OutputIds from new created outputs
consumedOutputs	string[]	OutputIds from consumed outputs

Receipts

Field	Type	Description
receipt	receipt	Receipt
milestoneIndex	number	Milestone index

Treasury

Field	Type	Description
milestoneId	string	Milestone id
amount	number	Amount