@helixnetwork/core

Core functionality to interact with the Helix network. Includes methods for:

• Generating addresses
• Creating, attaching and broadcasting transactions
• Querying for transactions
• Monitoring balances
• Monitoring inclusion states and consistency of transactions
• Promoting and reattaching pending transactions

Installation

Install using npm:

npm install @helixnetwork/core

or using yarn:

yarn add @helixnetwork/core

API Reference

• core

  • .composeApi([settings])

  • .createAddNeighbors(provider)

  • .addNeighbors(uris, [callback])

  • .createAttachToTangle(provider)

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

  • .createBroadcastBundle(provider)

  • .broadcastBundle(tailTransactionHash, [callback])

  • .createBroadcastTransactions(provider)

  • .broadcastTransactions(txs, [callback])

  • .createCheckConsistency(provider)

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

  • .createFindTransactionObjects(provider)

  • .findTransactionObjects(query, [callback])

  • .createFindTransactions(provider)

  • .findTransactions(query, [callback])

  • .createGetAccountData(provider)

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

  • .createGetBalances(provider)

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

  • .createGetBundle(provider)

  • .getBundle(tailTransactionHash, [callback])

  • .createGetTransactionStrings(provider)

  • .getTransactionStrings(hashes, [callback])

  • .createGetInclusionStates(provider)

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

  • .createGetInputs(provider)

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

  • .createGetLatestInclusion(provider)

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

  • .createGetNeighbors(provider)

  • .getNeighbors([callback])

  • .createGetNewAddress(provider)

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

  • .createGetNodeInfo(provider)

  • .getNodeInfo([callback])

  • .createGetTips(provider)

  • .getTips([callback])

  • .createGetTransactionObjects(provider)

  • .getTransactionObjects(hashes, [callback])

  • .createGetTransactionsToApprove(provider)

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

  • .createIsPromotable(provider, [depth])

  • .isPromotable(tail, [callback])

  • .createPrepareTransfers([provider])

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

  • .createPromoteTransaction(provider, [attachFn])

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

  • .createRemoveNeighbors(provider)

  • .removeNeighbors(uris, [callback])

  • .createReplayBundle(provider)

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

  • .createSendTxHex(provider)

  • .sendTxHex(txs, depth, minWeightMagnitude, [reference], [callback])

  • .createStoreAndBroadcast(provider)

  • .storeAndBroadcast(txs, [callback])

  • .createStoreTransactions(provider)

  • .storeTransactions(txs, [callback])

  • .createTraverseBundle(provider)

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

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

core.composeApi([settings])

| Param | Type | Default | Description | | --- | --- | --- | --- | | [settings] | object | function | {} | provider | Connection settings or provider factory | | [settings.provider] | string | "http://localhost:14265" | Uri of the node | | [settings.attachToTangle] | function | | Function to override attachToTangle with | | [settings.apiVersion] | string | number | 1 | helix.api version to be sent as X-HELIX-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 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, txs, [callback])

Fulfil: TransactionTxHex[] Array of transaction txs 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_HBYTES: Invalid transaction txs
• 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 | | txs | Array.<TransactionTxHex> | List of transaction txs | | [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 txs and overwrites the following fields:

• hash
• nonce
• attachmentTimestamp
• attachmentTimsetampLowerBound
• attachmentTimestampUpperBound

This method can be replaced with a local equivelant such as < in development > or remote PoW-Integrator.

trunkTransaction and branchTransaction hashes are given by getTransactionToApprove.

Example

getTransactionsToApprove(depth)
  .then(({ trunkTransaction, branchTransaction }) =>
    attachToTangle(trunkTransaction, branchTransaction, minWightMagnitude, txs)
  )
  .then(attachedTxHex => {
    // ...
  })
  .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

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

core.createBroadcastTransactions(provider)

| Param | Type | Description | | --- | --- | --- | | provider | Provider | Network provider |

Returns: function - broadcastTransactions

core.broadcastTransactions(txs, [callback])

Fulfil: HBytes[] Attached transaction txs
Reject: Error

• INVALID_ATTACHED_TX_HEX: Invalid array of attached txs
• Fetch error

| Param | Type | Description | | --- | --- | --- | | txs | Array.<TransactionTxHex> | Attached Transaction txs | | [callback] | Callback | Optional callback |

Broadcasts an list of attached transaction txs 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 PoW-Integrator, which is a development tool.

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

Persist the transaction txs in local storage before calling this command for first time, to ensure that reattachment is possible, until your bundle has been included.

Example

broadcastTransactions(txs)
  .then(txs => {
     // ...
  })
  .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 a helix node |

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.addresses] | Array.<Hash> | List of approvees | | [callback] | Callback | Optional callback |

Wrapper function for findTransactions and getTransactionStrings. 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 a helix node |

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.addresses] | 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 a helix node. |

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 a helix node. |

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.createGetTransactionStrings(provider)

| Param | Type | Description | | --- | --- | --- | | provider | Provider | Network provider |

Returns: function - getTransactionStrings

core.getTransactionStrings(hashes, [callback])

Fulfil: TxHex[] - Transaction txs 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 txs given a list of transaction hashes, by calling getTransactionStrings command.

Example

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

core.createGetInclusionStates(provider)

| Param | Type | Description | | --- | --- | --- | | provider | Provider | Network provider for accessing a helix node |

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 a helix node |

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 a helix node |

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 64 txs long seed | | [options] | object | | | | [options.index] | number | 0 | Key index to start search at | | [options.security] | number | 1 | Security level | | [options.checksum] | boolean | false | Deprecated Flag to include 8-txs 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 txs, 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(minWightMagnitude, txs, { transactionsToApprove })
  )
  .then(storeAndBroadcast)
  .catch(err => {
    // handle errors here
  })

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 txs Returns bundle txs
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 txs | | [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 txs 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.

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 helix node by calling removeNeighbors command. Assumes removeNeighbors command is available on the node.

This method has temporary effect until your helix 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.createSendTxHex(provider)

| Param | Type | Description | | --- | --- | --- | | provider | Provider | Network provider |

Returns: function - sendTxHex

core.sendTxHex(txs, depth, minWeightMagnitude, [reference], [callback])

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

• txs
• INVALID_DEPTH
• INVALID_MIN_WEIGHT_MAGNITUDE
• Fetch error, if connected to network

| Param | Type | Description | | --- | --- | --- | | txs | Array.<HBytes> | List of txs 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 txs.

Example

prepareTransfers(seed, transfers)
  .then(txs => sendHBytes(txs, depth, minWeightMagnitude))
  .then(transactions => {
    // ...
  })
  .catch(err => {
    // ...
  })

core.createStoreAndBroadcast(provider)

| Param | Type | | --- | --- | | provider | Provider |

Returns: function - storeAndBroadcast

core.storeAndBroadcast(txs, [callback])

Fulfil: TxHex[] Attached transaction txs
Reject: Error

• INVALID_ATTACHED_TX_HEX: Invalid attached txs
• Fetch error

| Param | Type | Description | | --- | --- | --- |

| txs | Array.<TxHex> | Attached transaction txs | | [callback] | Callback | Optional callback |

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

Note: Persist the transaction txs 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(txs, [callback])

Fullfil: TxHex[] Attached transaction txs
Reject: Error

• INVALID_ATTACHED_TX_HEX: Invalid attached txs
• Fetch error

| Param | Type | Description | | --- | --- | --- | | txs | Array.<HBytes> | Attached transaction txs | | [callback] | Callback | Optional callback |

Persists a list of attached transaction txs 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 PoW-Integrator.

Persist the transaction txs in local storage before calling this command, to ensure 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])

Todo

• [ ] set default security to 2 in future.

| Param | Type | Default | Description | | --- | --- | --- | --- | | seed | string | | | | index | number | | Private key index | | [security] | number | 1 | Security level of the private key | | [checksum] | boolean | false | Flag to add 0txs checksum |

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

Returns: Hash - Address txs