Skip to content

Latest commit

 

History

History
2060 lines (1507 loc) · 68.9 KB

api_reference.md

File metadata and controls

2060 lines (1507 loc) · 68.9 KB
Raw

Modules

bundle-validator
bundle
checksum
converter
core
extract-json
http-client
multisig
signing
transaction-converter
transaction
unit-converter
validators

Objects

API : object

bundle-validator

bundle-validator~validateSignatures(bundle)

Param Type
bundle Array.<Transaction>

Validates all signatures of a bundle.

bundle-validator~isBundle(bundle)

Param Type
bundle Array.<Transaction>

Checks if a bundle is syntactically valid. Validates signatures and overall structure.

bundle

bundle~createBundle(entries)

Param Type Description
entries Array.<BundleEntry> Entries of single or multiple transactions with the same address

Creates a bunlde with given transaction entries.

Returns: Array.<Transaction> - List of transactions in the bundle

bundle~addEntry(transactions, entry)

Param Type Default Description
transactions Array.<Transaction> List of transactions currently in the bundle
entry object Entry of single or multiple transactions with the same address
[entry.length] number 1 Entry length, which indicates how many transactions in the bundle will occupy
[entry.address] string Address, defaults to all-9s
[entry.value] number 0 Value to transfer in IOTAs
[entry.signatureMessageFragments] Array.<string> Array of signature message fragments trytes, defaults to all-9s
[entry.timestamp] number Transaction timestamp, defaults to Math.floor(Date.now() / 1000)
[entry.tag] string Optional Tag, defaults to null tag (all-9s)

Creates a bunlde with given transaction entries

Returns: Array.<Transaction> - Bundle

bundle~addTrytes(transactions, fragments, [offset])

Param Type Default Description
transactions Array.<Transaction> Transactions in the bundle
fragments Array.<Trytes> Message signature fragments to add
[offset] number 0 Optional offset to start appending signature message fragments

Adds a list of trytes in the bundle starting at offset

Returns: Array.<Transaction> - Transactions of finalized bundle

bundle~finalizeBundle(transactions)

Param Type Description
transactions Array.<Transaction> Transactions in the bundle

Finalizes the bundle by calculating the bundle hash

Returns: Array.<Transaction> - Transactions of finalized bundle

checksum

checksum~isValidChecksum(addressWithChecksum)

Param Type
addressWithChecksum string

Validates the checksum of the given address trytes.

converter

converter.asciiToTrytes(input)

Param Type Description
input string ascii input

Converts an ascii encoded string to trytes.

How conversion works:

An ascii value of 1 Byte can be represented in 2 Trytes:

  1. We get the decimal unicode value of an individual ASCII character.

  2. From the decimal value, we then derive the two tryte values by calculating the tryte equivalent (e.g.: 100 is expressed as 19 + 3 * 27), given that tryte alphabet contains 27 trytes values: a. The first tryte value is the decimal value modulo 27 (which is the length of the alphabet). b. The second value is the remainder of decimal value - first value devided by 27.

  3. The two values returned from Step 2. are then input as indices into the available trytes alphabet (9ABCDEFGHIJKLMNOPQRSTUVWXYZ), to get the correct tryte value.

Example:

Lets say we want to convert ascii character Z.

  1. Z has a decimal unicode value of 90.

  2. 90 can be represented as 9 + 3 * 27. To make it simpler: a. First value is 90 % 27 = 9. b. Second value is (90 - 9) / 27 = 3.

  3. Our two values are 9 and 3. To get the tryte value now we simply insert it as indices into the tryte alphabet: a. The first tryte value is '9ABCDEFGHIJKLMNOPQRSTUVWXYZ'[9] = I b. The second tryte value is '9ABCDEFGHIJKLMNOPQRSTUVWXYZ'[3] = C

Therefore ascii character Z is represented as IC in trytes.

Returns: string - string of trytes

converter.trytesToAscii(trytes)

Param Type Description
trytes string trytes

Converts trytes of even length to an ascii string

Returns: string - string in ascii

converter.trits(input)

Param Type Description
input String | Number Tryte string or value to be converted.

Converts trytes or values to trits

Returns: Int8Array - trits

converter.trytes(trits)

Param Type
trits Int8Array

Converts trits to trytes

Returns: String - trytes

converter.value(trits)

Param Type
trits Int8Array

Converts trits into an integer value

converter.fromValue(value)

Param Type
value Number

Converts an integer value to trits

Returns: Int8Array - trits

core

core.composeApi([settings])

Param Type Default Description
[settings] object | function {} provider
[settings.provider] string "http://localhost:14265" Uri of IRI node
[settings.attachToTangle] function Function to override attachToTangle with
[settings.apiVersion] string | number 1 IOTA Api version to be sent as X-IOTA-API-Version header.
[settings.requestBatchSize] number 1000 Number of search values per request.

Composes API object from it's components

core.createAddNeighbors(provider)

Param Type Description
provider Provider Network provider

Returns: function - addNeighbors

core.addNeighbors(uris, [callback])

Fulfil: number Number of neighbors that were added
Reject: Error

  • INVALID_URI: Invalid uri
  • Fetch error
Param Type Description
uris Array List of URI's
[callback] Callback Optional callback

Adds a list of neighbors to the connected IRI node by calling addNeighbors command. Assumes addNeighbors command is available on the node.

addNeighbors has temporary effect until your node relaunches.

Example

addNeighbors(['udp://148.148.148.148:14265'])
  .then(numAdded => {
    // ...
  }).catch(err => {
    // ...
  })

core.createAttachToTangle(provider)

Param Type Description
provider Provider Network provider

Returns: function - attachToTangle

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

Fulfil: TransactionTrytes[] Array of transaction trytes with nonce and attachment timestamps
Reject: Error

  • INVALID_TRUNK_TRANSACTION: Invalid trunkTransaction
  • INVALID_BRANCH_TRANSACTION: Invalid branchTransaction
  • INVALID_MIN_WEIGHT_MAGNITUDE: Invalid minWeightMagnitude argument
  • INVALID_TRANSACTION_TRYTES: Invalid transaction trytes
  • INVALID_TRANSACTIONS_TO_APPROVE: Invalid transactions to approve
  • Fetch error
Param Type Description
trunkTransaction Hash Trunk transaction as returned by getTransactionsToApprove
branchTransaction Hash Branch transaction as returned by getTransactionsToApprove
minWeightMagnitude number Number of minimun trailing zeros in tail transaction hash
trytes Array.<TransactionTrytes> List of transaction trytes
[callback] Callback Optional callback

Performs the Proof-of-Work required to attach a transaction to the Tangle by calling attachToTangle command. Returns list of transaction trytes and overwrites the following fields:

  • hash
  • nonce
  • attachmentTimestamp
  • attachmentTimsetampLowerBound
  • attachmentTimestampUpperBound

This method can be replaced with a local equivelant such as ccurl.interface.js in node.js, curl.lib.js which works on WebGL 2 enabled browsers or remote PoWbox.

trunkTransaction and branchTransaction hashes are given by getTransactionToApprove.

Note: Persist the transaction trytes in local storage before calling this command, to ensure that reattachment is possible, until your bundle has been included.

Example

getTransactionsToApprove(depth)
  .then(({ trunkTransaction, branchTransaction }) =>
    attachToTangle(trunkTransaction, branchTransaction, minWeightMagnitude, trytes)
  )
  .then(attachedTrytes => {
    // ...
  })
  .catch(err => {
    // ...
  })

core.createBroadcastBundle(provider)

Param Type Description
provider Provider Network provider

Returns: function - broadcastBundle

core.broadcastBundle(tailTransactionHash, [callback])

Fulfil: Transaction[] List of transaction objects
Reject: Error

  • INVALID_HASH: Invalid tail transaction hash
  • INVALID_BUNDLE: Invalid bundle
  • Fetch error
Param Type Description
tailTransactionHash Hash Tail transaction hash
[callback] Callback Optional callback

Re-broadcasts all transactions in a bundle given the tail transaction hash. It might be useful when transactions did not properly propagate, particularly in the case of large bundles.

Example

broadcastBundle(tailHash)
  .then(transactions => {
     // ...
  })
  .catch(err => {
    // ...
  })

core.createBroadcastTransactions(provider)

Param Type Description
provider Provider Network provider

Returns: function - broadcastTransactions

core.broadcastTransactions(trytes, [callback])

Fulfil: Trytes[] Attached transaction trytes
Reject: Error

  • INVALID_ATTACHED_TRYTES: Invalid array of attached trytes
  • Fetch error
Param Type Description
trytes Array.<TransactionTrytes> Attached Transaction trytes
[callback] Callback Optional callback

Broadcasts an list of attached transaction trytes to the network by calling boradcastTransactions command. Tip selection and Proof-of-Work must be done first, by calling getTransactionsToApprove and attachToTangle or an equivalent attach method or remote PoWbox, which is a development tool.

You may use this method to increase odds of effective transaction propagation.

Note: Persist the transaction trytes in local storage before calling this command, to ensure that reattachment is possible, until your bundle has been included.

Example

broadcastTransactions(trytes)
  .then(trytes => {
     // ...
  })
  .catch(err => {
    // ...
  })

core.createCheckConsistency(provider)

Param Type Description
provider Provider Network provider

Returns: function - checkConsistency

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

Fulfil: boolean Consistency state of given transaction or co-consistency of given transactions.
Reject: Error

  • INVALID_TRANSACTION_HASH: Invalid transaction hash
  • Fetch error
  • Reason for returning false, if called with options.rejectWithReason
Param Type Description
transactions Hash | Array.<Hash> Tail transaction hash (hash of transaction with currentIndex=0), or array of tail transaction hashes.
[options] object Options
[options.rejectWithReason] boolean Enables rejection if state is false, with reason as error message
[callback] Callback Optional callback.

Checks if a transaction is consistent or a set of transactions are co-consistent, by calling checkConsistency command. Co-consistent transactions and the transactions that they approve (directly or inderectly), are not conflicting with each other and rest of the ledger.

As long as a transaction is consistent it might be accepted by the network. In case transaction is inconsistent, it will not be accepted, and a reattachment is required by calling replaybundle.

Example

checkConsistency(tailHash)
  .then(isConsistent => {
    // ...
  })
  .catch(err => {
    // ...
  })

Example

Example with checkConsistency & isPromotable

Consistent transactions might remain pending due to networking issues, or if not referenced by recent milestones issued by Coordinator. Therefore checkConsistency with a time heuristic can determine if a transaction should be promoted or reattached. This functionality is abstracted in isPromotable.

const isAboveMaxDepth = attachmentTimestamp => (
   // Check against future timestamps
   attachmentTimestamp < Date.now() &&
   // Check if transaction wasn't issued before last 6 milestones
   // Milestones are being issued every ~2mins
   Date.now() - attachmentTimestamp < 11 * 60 * 1000
)

const isPromotable = ({ hash, attachmentTimestamp }) => (
  checkConsistency(hash)
     .then(isConsistent => (
       isConsistent &&
       isAboveMaxDepth(attachmentTimestamp)
     ))
)

core.createFindTransactionObjects(provider)

Param Type Description
provider Provider Network provider for accessing IRI

Returns: function - findTransactionObjects

core.findTransactionObjects(query, [callback])

Fulfil: Transaction[] Array of transaction objects
Reject: Error

  • INVALID_SEARCH_KEY
  • INVALID_HASH: Invalid bundle hash
  • INVALID_TRANSACTION_HASH: Invalid approvee transaction hash
  • INVALID_ADDRESS: Invalid address
  • INVALID_TAG: Invalid tag
  • Fetch error
Param Type Description
query object
[query.addresses] Array.<Hash> List of addresses
[query.bundles] Array.<Hash> List of bundle hashes
[query.tags] Array.<Tag> List of tags
[query.approvees] Array.<Hash> List of approvees
[callback] Callback Optional callback

Wrapper function for findTransactions and getTrytes. Searches for transactions given a query object with addresses, tags and approvees fields. Multiple query fields are supported and findTransactionObjects returns intersection of results.

Example
Searching for transactions by address:

findTransactionObjects({ addresses: ['ADR...'] })
   .then(transactions => {
       // ...
   })
   .catch(err => {
       // ...
   })

core.createFindTransactions(provider)

Param Type Description
provider Provider Network provider for accessing IRI

Returns: function - findTransactionObjects

core.findTransactions(query, [callback])

Fulfil: Hash[] Array of transaction hashes
Reject: Error

  • INVALID_SEARCH_KEY
  • INVALID_HASH: Invalid bundle hash
  • INVALID_TRANSACTION_HASH: Invalid approvee transaction hash
  • INVALID_ADDRESS: Invalid address
  • INVALID_TAG: Invalid tag
  • Fetch error
Param Type Description
query object
[query.addresses] Array.<Hash> List of addresses
[query.bundles] Array.<Hash> List of bundle hashes
[query.tags] Array.<Tag> List of tags
[query.approvees] Array.<Hash> List of approvees
[callback] Callback Optional callback

Searches for transaction hashes by calling findTransactions command. It allows to search for transactions by passing a query object with addresses, tags and approvees fields. Multiple query fields are supported and findTransactions returns intersection of results.

Example

findTransactions({ addresses: ['ADRR...'] })
   .then(hashes => {
       // ...
   })
   .catch(err => {
       // handle errors here
   })

core.createGetAccountData(provider)

Param Type Description
provider Provider Network provider for accessing IRI

Returns: function - getAccountData

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

Fulfil: AccountData
Reject: Error

  • INVALID_SEED
  • INVALID_START_OPTION
  • INVALID_START_END_OPTIONS: Invalid combination of start & end options`
  • Fetch error
Param Type Default Description
seed string
options object
[options.start] number 0 Starting key index
[options.security] number 0 Security level to be used for getting inputs and addresses
[options.end] number Ending key index
[callback] Callback Optional callback

Returns an AccountData object, containing account information about addresses, transactions, inputs and total account balance.

Example

getAccountData(seed, {
   start: 0,
   security: 2
})
  .then(accountData => {
    const { addresses, inputs, transactions, balance } = accountData
    // ...
  })
  .catch(err => {
    // ...
  })

core.createGetBalances(provider)

Param Type Description
provider Provider Network provider

Returns: function - getBalances

core.getBalances(addresses, threshold, [callback])

Fulfil: Balances Object with list of balances and corresponding milestone
Reject: Error

  • INVALID_HASH: Invalid address
  • INVALID_THRESHOLD: Invalid threshold
  • Fetch error
Param Type Description
addresses Array.<Hash> List of addresses
threshold number Confirmation threshold, currently 100 should be used
[callback] Callback Optional callback

Fetches confirmed balances of given addresses at the latest solid milestone, by calling getBalances command.

Example

getBalances([address], 100)
  .then(({ balances }) => {
    // ...
  })
  .catch(err => {
    // ...
  })

core.createGetBundle(provider)

Param Type Description
provider Provider Network provider for accessing IRI

Returns: function - getBundle

core.getBundle(tailTransactionHash, [callback])

Fulfil: Transaction[] Bundle as array of transaction objects
Reject: Error

  • INVALID_TRANSACTION_HASH
  • INVALID_TAIL_HASH: Provided transaction is not tail (currentIndex !== 0)
  • INVALID_BUNDLE: Bundle is syntactically invalid
  • Fetch error
Param Type Description
tailTransactionHash Hash Tail transaction hash
[callback] Callback Optional callback

Fetches and validates the bundle given a tail transaction hash, by calling traverseBundle and traversing through trunkTransaction.

Example

getBundle(tail)
   .then(bundle => {
       // ...
   })
   .catch(err => {
       // handle errors
   })

core.createGetInclusionStates(provider)

Param Type Description
provider Provider Network provider for accessing IRI

Returns: function - getInclusionStates

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

Fulfil: boolean[] Array of inclusion state
Reject: Error

  • INVALID_TRANSACTION_HASH: Invalid hashes or tips
  • Fetch error
Param Type Description
transactions Array.<Hash> List of transaction hashes
tips Array.<Hash> List of tips to check if transactions are referenced by
[callback] Callback Optional callback

Fetches inclusion states of given list of transactions, by calling getInclusionStates command.

Example

getInclusionStates(transactions)
  .then(states => {
    // ...
  })
  .catch(err => {
    // ...
  })

core.createGetInputs(provider)

Param Type Description
provider Provider Network provider for accessing IRI

Returns: function - getInputs

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

Fulfil: Inputs Inputs object containg a list of [Address](Address) objects and totalBalance field
Reject: Error

  • INVALID_SEED
  • INVALID_SECURITY_LEVEL
  • INVALID_START_OPTION
  • INVALID_START_END_OPTIONS
  • INVALID_THRESHOLD
  • INSUFFICIENT_BALANCE
  • Fetch error
Param Type Default Description
seed string
[options] object
[options.start] number 0 Index offset indicating from which address we start scanning for balance
[options.end] number Last index up to which we stop scanning
[options.security] number 2 Security level of inputs
[options.threshold] threshold Minimum amount of balance required
[callback] Callback Optional callback

Creates and returns an Inputs object by generating addresses and fetching their latest balance.

Example

getInputs(seed, { start: 0, threhold })
  .then(({ inputs, totalBalance }) => {
    // ...
  })
  .catch(err => {
    if (err.message === errors.INSUFFICIENT_BALANCE) {
       // ...
    }
    // ...
  })

core.createGetLatestInclusion(provider)

Param Type Description
provider Provider Network provider for accessing IRI

Returns: function - getLatestInclusion

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

Fulfil: boolean[] List of inclusion states
Reject: Error

  • INVALID_HASH: Invalid transaction hash
  • Fetch error
Param Type Description
transactions Array.<Hash> List of transactions hashes
tips number List of tips to check if transactions are referenced by
[callback] Callback Optional callback

Fetches inclusion states of given transactions and a list of tips, by calling getInclusionStates on latestSolidSubtangleMilestone.

Example

getLatestInclusion(hashes)
   .then(states => {
       // ...
   })
   .catch(err => {
       // handle error
   })

core.createGetNeighbors(provider)

Param Type Description
provider Provider Network provider

Returns: function - getNeighbors

core.getNeighbors([callback])

Fulfil: Neighbors
Reject: Error

  • Fetch error
Param Type Description
[callback] Callback Optional callback

Returns list of connected neighbors.

core.createGetNewAddress(provider)

Param Type Description
provider Provider Network provider

Returns: function - getNewAddress

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

Fulfil: Hash|Hash[] New (unused) address or list of addresses up to (and including) first unused address
Reject: Error

  • INVALID_SEED
  • INVALID_START_OPTION
  • INVALID_SECURITY
  • Fetch error
Param Type Default Description
seed string At least 81 trytes long seed
[options] object
[options.index] number 0 Key index to start search at
[options.security] number 2 Security level
[options.checksum] boolean false Deprecated Flag to include 9-trytes checksum or not
[options.total] number Deprecated Number of addresses to generate.
[options.returnAll] boolean false Deprecated Flag to return all addresses, from start up to new address.
[callback] Callback Optional callback

Generates and returns a new address by calling findTransactions until the first unused address is detected. This stops working after a snapshot.

Example

getNewAddress(seed, { index })
  .then(address => {
    // ...
  })
  .catch(err => {
    // ...
  })

core.createGetNodeInfo(provider)

Param Type Description
provider Provider Network provider

Returns: function - getNodeInfo

core.getNodeInfo([callback])

Fulfil: NodeInfo Object with information about connected node.
Reject: Error

  • Fetch error
Param Type Description
[callback] Callback Optional callback

Returns information about connected node by calling getNodeInfo command.

Example

getNodeInfo()
  .then(info => console.log(info))
  .catch(err => {
    // ...
  })

core.createGetTips(provider)

Param Type Description
provider Provider Network provider

Returns: function - getTips

core.getTips([callback])

Fulfil: Hash[] List of tip hashes
Reject: Error

  • Fetch error
Param Type Description
[callback] Callback Optional callback

Returns a list of tips (transactions not referenced by other transactions), as seen by the connected node.

Example

getTips()
  .then(tips => {
    // ...
  })
  .catch(err => {
    // ...
  })

core.createGetTransactionObjects(provider)

Param Type Description
provider Provider Network provider

Returns: function - getTransactionObjects

core.getTransactionObjects(hashes, [callback])

Fulfil: Transaction[] - List of transaction objects
Reject: Error

  • INVALID_TRANSACTION_HASH
  • Fetch error
Param Type Description
hashes Array.<Hash> Array of transaction hashes
[callback] function Optional callback

Fetches the transaction objects, given an array of transaction hashes.

Example

getTransactionObjects(hashes)
  .then(transactions => {
    // ...
  })
  .catch(err => {
    // handle errors
  })

core.createGetTransactionsToApprove(provider)

Param Type Description
provider Provider Network provider

Returns: function - getTransactionsToApprove

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

Fulfil: trunkTransaction, branchTransaction A pair of approved transactions
Reject: Error

  • INVALID_DEPTH
  • INVALID_REFERENCE_HASH: Invalid reference hash
  • Fetch error
Param Type Description
depth number The depth at which Random Walk starts. A value of 3 is typically used by wallets, meaning that RW starts 3 milestones back.
[reference] Hash Optional reference transaction hash
[callback] Callback Optional callback

Does the tip selection by calling getTransactionsToApprove command. Returns a pair of approved transactions, which are chosen randomly after validating the transaction trytes, the signatures and cross-checking for conflicting transactions.

Tip selection is executed by a Random Walk (RW) starting at random point in given depth ending up to the pair of selected tips. For more information about tip selection please refer to the whitepaper.

The reference option allows to select tips in a way that the reference transaction is being approved too. This is useful for promoting transactions, for example with promoteTransaction.

Example

const depth = 3
const minWeightMagnitude = 14

getTransactionsToApprove(depth)
  .then(transactionsToApprove =>
     attachToTangle(minWeightMagnitude, trytes, { transactionsToApprove })
  )
  .then(storeAndBroadcast)
  .catch(err => {
    // handle errors here
  })

core.createGetTrytes(provider)

Param Type Description
provider Provider Network provider

Returns: function - getTrytes

core.getTrytes(hashes, [callback])

Fulfil: Trytes[] - Transaction trytes
Reject: Error{}

  • INVALID_TRANSACTION_HASH: Invalid hash
  • Fetch error
Param Type Description
hashes Array.<Hash> List of transaction hashes
[callback] Callback Optional callback

Fetches the transaction trytes given a list of transaction hashes, by calling getTrytes command.

Example

getTrytes(hashes)
  // Parsing as transaction objects
  .then(trytes => asTransactionObjects(hashes)(trytes))
  .then(transactions => {
    // ...
  })
  .catch(err => {
    // ...
  })

core.createIsPromotable(provider, [depth])

Param Type Default Description
provider Provider Network provider
[depth] number 6 Depth up to which promotion is effective.

Returns: function - isPromotable

core.isPromotable(tail, [callback])

Fulfil: boolean Consistency state of transaction or co-consistency of transactions
Reject: Error

  • INVALID_HASH: Invalid hash
  • INVALID_DEPTH: Invalid depth
  • Fetch error
Param Type Description
tail Hash Tail transaction hash
[callback] Callback Optional callback

Checks if a transaction is promotable, by calling checkConsistency and verifying that attachmentTimestamp is above a lower bound. Lower bound is calculated based on number of milestones issued since transaction attachment.

Example

Example with promotion and reattachments

Using isPromotable to determine if transaction can be promoted or should be reattached

// We need to monitor inclusion states of all tail transactions (original tail & reattachments)
const tails = [tail]

getLatestInclusion(tails)
  .then(states => {
    // Check if none of transactions confirmed
    if (states.indexOf(true) === -1) {
      const tail = tails[tails.length - 1] // Get latest tail hash

      return isPromotable(tail)
        .then(isPromotable => isPromotable
          ? promoteTransaction(tail, 3, 14)
          : replayBundle(tail, 3, 14)
            .then(([reattachedTail]) => {
              const newTailHash = reattachedTail.hash

              // Keeping track of all tail hashes to check confirmation
              tails.push(newTailHash)

              // Promote the new tail...
            })
    }
  }).catch(err => {
    // ...
  })

core.createPrepareTransfers([provider])

Param Type Description
[provider] Provider Optional network provider to fetch inputs and remainder address. In case this is omitted, proper input objects and remainder should be passed to prepareTransfers, if required.

Create a prepareTransfers function by passing an optional newtowrk provider. It is possible to prepare and sign transactions offline, by omitting the provider option.

Returns: function - prepareTransfers

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

Fulfil: array trytes Returns bundle trytes
Reject: Error

  • INVALID_SEED
  • INVALID_TRANSFER_ARRAY
  • INVALID_INPUT
  • INVALID_REMAINDER_ADDRESS
  • INSUFFICIENT_BALANCE
  • NO_INPUTS
  • SENDING_BACK_TO_INPUTS
  • Fetch error, if connected to network
Param Type Default Description
seed string
transfers object
[options] object
[options.inputs] Array.<Input> Inputs used for signing. Needs to have correct security, keyIndex and address value
[options.inputs[].address] Hash Input address trytes
[options.inputs[].keyIndex] number Key index at which address was generated
[options.inputs[].security] number 2 Security level
[options.inputs[].balance] number Balance in iotas
[options.address] Hash Remainder address
[options.security] Number Security level to be used for getting inputs and reminder address
[callback] function Optional callback

Properties

Name Type Description
[options.hmacKey] Hash HMAC key used for attaching an HMAC

Prepares the transaction trytes by generating a bundle, filling in transfers and inputs, adding remainder and signing. It can be used to generate and sign bundles either online or offline. For offline usage, please see createPrepareTransfers which creates a prepareTransfers without a network provider.

Note: After calling this method, persist the returned transaction trytes in local storage. Only then you should broadcast to the network. This will allow for reattachments and prevent key reuse if trytes can't be recovered by querying the network after broadcasting.

core.createPromoteTransaction(provider, [attachFn])

Param Type Description
provider Provider Network provider
[attachFn] function Optional AttachToTangle function to override the default method.

Returns: function - promoteTransaction

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

Fulfil: Transaction[]
Reject: Error

  • INCONSISTENT SUBTANGLE: In this case promotion has no effect and reatchment is required.
  • Fetch error
Param Type Description
tail string
depth int
minWeightMagnitude int
transfer array
[options] object
[options.delay] number Delay between spam transactions in ms
[options.interrupt] boolean | function Interrupt signal, which can be a function that evaluates to boolean
[callback] function

Promotes a transaction by adding other transactions (spam by default) on top of it. Will promote maximum transfers on top of the current one with delay interval. Promotion is interruptable through interrupt option.

core.createRemoveNeighbors(provider)

Param Type Description
provider Provider Network provider

Returns: function - removeNeighbors

core.removeNeighbors(uris, [callback])

Fulfil: number Number of neighbors that were removed
Reject: Error

  • INVALID_URI: Invalid uri
  • Fetch error
Param Type Description
uris Array List of URI's
[callback] Callback Optional callback

Removes a list of neighbors from the connected IRI node by calling removeNeighbors command. Assumes removeNeighbors command is available on the node.

This method has temporary effect until your IRI node relaunches.

core.createReplayBundle(provider)

Param Type Description
provider Provider Network provider

Returns: function - replayBundle

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

Fulfil: Transaction[]
Reject: Error

  • INVALID_DEPTH
  • INVALID_MIN_WEIGHT_MAGNITUDE
  • INVALID_TRANSACTION_HASH
  • INVALID_BUNDLE
  • Fetch error
Param Type Description
tail Hash Tail transaction hash. Tail transaction is the transaction in the bundle with currentIndex == 0.
depth number The depth at which Random Walk starts. A value of 3 is typically used by wallets, meaning that RW starts 3 milestones back.
minWeightMagnitude number Minimum number of trailing zeros in transaction hash. This is used by attachToTangle function to search for a valid nonce. Currently is 14 on mainnet & spamnnet and 9 on most other testnets.
[callback] Callback Optional callback

Reattaches a transfer to tangle by selecting tips & performing the Proof-of-Work again. Reattachments are usefull in case original transactions are pending, and can be done securely as many times as needed.

Example

replayBundle(tail)
  .then(transactions => {
    // ...
  })
  .catch(err => {
    // ...
  })
})

core.createSendTrytes(provider)

Param Type Description
provider Provider Network provider

Returns: function - sendTrytes

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

Fulfil: Transaction[] Returns list of attached transactions
Reject: Error

  • INVALID_TRANSACTION_TRYTES
  • INVALID_DEPTH
  • INVALID_MIN_WEIGHT_MAGNITUDE
  • Fetch error, if connected to network
Param Type Description
trytes Array.<Trytes> List of trytes to attach, store & broadcast
depth number Depth
minWeightMagnitude number Min weight magnitude
[reference] string Optional reference hash
[callback] Callback Optional callback

Attaches to tanlge, stores and broadcasts a list of transaction trytes.

Note: Persist the transaction trytes in local storage before calling this command, to ensure that reattachment is possible, until your bundle has been included.

Example

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.

    return iota.sendTrytes(trytes, depth, minWeightMagnitude)
  })
  .then(transactions => {
    // ...
  })
  .catch(err => {
    // ...
  })

core.createStoreAndBroadcast(provider)

Param Type
provider Provider

Returns: function - storeAndBroadcast

core.storeAndBroadcast(trytes, [callback])

Fulfil: Trytes[] Attached transaction trytes
Reject: Error

  • INVALID_ATTACHED_TRYTES: Invalid attached trytes
  • Fetch error
Param Type Description
trytes Array.<Trytes> Attached transaction trytes
[callback] Callback Optional callback

Stores and broadcasts a list of attached transaction trytes by calling storeTransactions and broadcastTransactions.

Note: Persist the transaction trytes in local storage before calling this command, to ensure that reattachment is possible, until your bundle has been included.

Any transactions stored with this command will eventaully be erased, as a result of a snapshot.

core.createStoreTransactions(provider)

Param Type Description
provider Provider Network provider

Returns: function - storeTransactions

core.storeTransactions(trytes, [callback])

Fullfil: Trytes[] Attached transaction trytes
Reject: Error

  • INVALID_ATTACHED_TRYTES: Invalid attached trytes
  • Fetch error
Param Type Description
trytes Array.<Trytes> Attached transaction trytes
[callback] Callback Optional callback

Persists a list of attached transaction trytes in the store of connected node by calling storeTransactions command. Tip selection and Proof-of-Work must be done first, by calling getTransactionsToApprove and attachToTangle or an equivalent attach method or remote PoWbox.

Note: Persist the transaction trytes in local storage before calling this command, to ensure that reattachment is possible, until your bundle has been included.

Any transactions stored with this command will eventaully be erased, as a result of a snapshot.

core.createTraverseBundle(provider)

Param Type
provider Provider

Returns: function - traverseBundle

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

Fulfil: Transaction[] Bundle as array of transaction objects
Reject: Error

  • INVALID_TRANSACTION_HASH
  • INVALID_TAIL_HASH: Provided transaction is not tail (currentIndex !== 0)
  • INVALID_BUNDLE: Bundle is syntactically invalid
  • Fetch error
Param Type Default Description
trunkTransaction Hash Trunk transaction, should be tail (currentIndex == 0)
[bundle] Hash [] List of accumulated transactions
[callback] Callback Optional callback

Fetches the bundle of a given the tail transaction hash, by traversing through trunkTransaction. It does not validate the bundle.

Example

traverseBundle(tail)
   .then(bundle => {
       // ...
   })
   .catch(err => {
       // handle errors
   })

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

Param Type Default Description
seed string
index number Private key index
[security] number 2 Security level of the private key
[checksum] boolean false Flag to add 9trytes checksum

Generates an address deterministically, according to the given seed, index and security level.

Returns: Hash - Address trytes

extract-json

extract-json~extractJson(bundle)

Param Type
bundle array

Takes a bundle as input and from the signatureMessageFragments extracts the correct JSON data which was encoded and sent with the transaction. Supports the following forms of JSON encoded values:

  • "{ \"message\": \"hello\" }"\
  • "[1, 2, 3]"
  • "true", "false" & "null"
  • `""hello""
  • 123

Example

try {
  const msg = JSON.parse(extractJson(bundle))
} catch (err) {
  err.msg == errors.INVALID_BUNDLE
  // Invalid bundle or invalid encoded JSON
}

Example
Example with getBundle:

getBundle(tailHash)
  .then(bundle => {
     const msg = JSON.parse(extractJson(bundle))
     // ...
  })
  .catch((err) => {
     // Handle network & extraction errors
  })

http-client

http-client.send(command, [uri], [apiVersion])

Fulil: Object - Response
Reject: Error - Request error

Param Type Default
command Command
[uri] String http://localhost:14265
[apiVersion] String | Number 1

Sends an http request to a specified host.

Returns: Promise

http-client~send

Param Type
command object

Returns: object - response

http-client~setSettings

Param Type Default Description
[settings] object {}
[settings.provider] string "http://localhost:14265" Uri of IRI node
[settings.apiVersion] string | number 1 IOTA Api version to be sent as X-IOTA-API-Version header.
[settings.requestBatchSize] number 1000 Number of search values per request.

http-client~createHttpClient([settings])

Param Type Default Description
[settings] object {}
[settings.provider] string "http://localhost:14265" Uri of IRI node
[settings.apiVersion] string | number 1 IOTA Api version to be sent as X-IOTA-API-Version header.
[settings.requestBatchSize] number 1000 Number of search values per request.

Create an http client to access IRI http API.

Returns: Object

multisig

multisig.Address

multisig.Multisig

signing

signing~subseed(seed, index)

Param Type Description
seed Int8Array Seed trits
index number Private key index

Returns: Int8Array - subseed trits

signing~key(subseed, length)

Param Type Description
subseed Int8Array Subseed trits
length number Private key length

Returns: Int8Array - Private key trits

signing~digests(key)

Param Type Description
key Int8Array Private key trits

signing~address(digests)

Param Type Description
digests Int8Array Digests trits

Returns: Int8Array - Address trits

signing~digest(normalizedBundleFragment, signatureFragment)

Param Type Description
normalizedBundleFragment array Normalized bundle fragment
signatureFragment Int8Array Signature fragment trits

Returns: Int8Array - Digest trits

signing~signatureFragment(normalizeBundleFragment, keyFragment)

Param Type Description
normalizeBundleFragment array normalized bundle fragment
keyFragment keyFragment key fragment trits

Returns: Int8Array - Signature Fragment trits

signing~validateSignatures(expectedAddress, signatureFragments, bundleHash)

Param Type Description
expectedAddress string Expected address trytes
signatureFragments array Array of signatureFragments trytes
bundleHash string Bundle hash trytes

signing~normalizedBundleHash(bundlehash)

Param Type Description
bundlehash Hash Bundle hash trytes

Normalizes the bundle hash, with resulting digits summing to zero.

Returns: Int8Array - Normalized bundle hash

transaction-converter

transaction-converter~asTransactionTrytes(transactions)

Param Type Description
transactions Transaction | Array.<Transaction> Transaction object(s)

Converts a transaction object or a list of those into transaction trytes.

Returns: Trytes | Array.<Trytes> - Transaction trytes

transaction-converter~asTransactionObject(trytes)

Param Type Description
trytes Trytes Transaction trytes

Converts transaction trytes of 2673 trytes into a transaction object.

Returns: Transaction - Transaction object

transaction-converter~asTransactionObjects([hashes])

Param Type Description
[hashes] Array.<Hash> Optional list of known hashes. Known hashes are directly mapped to transaction objects, otherwise all hashes are being recalculated.

Converts a list of transaction trytes into list of transaction objects. Accepts a list of hashes and returns a mapper. In cases hashes are given, the mapper function map them to converted objects.

Returns: function - transactionObjectsMapper

transaction-converter~transactionObjectsMapper(trytes)

Param Type Description
trytes Array.<Trytes> List of transaction trytes to convert

Maps the list of given hashes to a list of converted transaction objects.

Returns: Array.<Transaction> - List of transaction objects with hashes

transaction

transaction~transactionHash(trits)

Param Type Description
trits Int8Array Int8Array of 8019 transaction trits

Calculates the transaction hash out of 8019 transaction trits.

Returns: Hash - Transaction hash

transaction~isTransaction(tx)

Param Type
tx object

Checks if input is valid transaction object.

transaction~isTailTransaction(transaction)

Param Type
transaction object

Checks if given transaction object is tail transaction. A tail transaction is one with currentIndex=0.

transaction~isTransactionHash(hash, mwm)

Param Type
hash string
mwm number

Checks if input is correct transaction hash (81 trytes)

transaction~isTransactionTrytes(trytes, minWeightMagnitude)

Param Type
trytes string
minWeightMagnitude number

Checks if input is correct transaction trytes (2673 trytes)

transaction~isAttachedTrytes(trytes)

Param Type
trytes string

Checks if input is valid attached transaction trytes. For attached transactions last 241 trytes are non-zero.

unit-converter

unit-converter~convertUnits(value, fromUnit, toUnit)

Param Type Description
value string | int | float
fromUnit string Name of original value unit
toUnit string Name of unit wich we convert to

Converts accross IOTA units. Valid unit names are: i, Ki, Mi, Gi, Ti, Pi

validators

validators~isAddress(address)

Param Type Description
address string Address trytes, with checksum

Checks integrity of given address by validating the checksum.

API

API.setSettings(settings)

Param Type Description
settings object Provider settings object
[settings.provider] string Http uri of IRI node
[settings.attachToTangle] function Function to override attachToTangle with

Defines network provider configuration and attachToTangle method.

API.overrideAttachToTangle(attachToTangle)

Param Type Description
attachToTangle function Function to override attachToTangle with

Overides default attachToTangle with a local equivalent or PoWBox