@helixnetwork/core v1.0.0-alpha.8

@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)

Composes API object from it's components

core.createAddNeighbors(provider)

Returns: function - addNeighbors

core.addNeighbors(uris, callback)

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

• INVALID_URI: Invalid uri
• Fetch error

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)

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

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)

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

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)

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

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)

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

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)

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

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)

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

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)

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

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)

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

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)

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

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)

Returns: function - getTransactionStrings

core.getTransactionStrings(hashes, callback)

Fulfil: TxHex[] - Transaction txs Reject: Error{}

• INVALID_TRANSACTION_HASH: Invalid hash
• Fetch error

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)

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

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

Example

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

core.createGetInputs(provider)

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

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)

Returns: function - getLatestInclusion

core.getLatestInclusion(transactions, tips, callback)

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

• INVALID_HASH: Invalid transaction hash
• Fetch error

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)

Returns: function - getNeighbors

core.getNeighbors(callback)

Fulfil: Neighbors
Reject: Error

• Fetch error

Returns list of connected neighbors.

core.createGetNewAddress(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

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)

Returns: function - getNodeInfo

core.getNodeInfo(callback)

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

• Fetch error

Returns information about connected node by calling getNodeInfo command.

Example

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

core.createGetTips(provider)

Returns: function - getTips

core.getTips(callback)

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

• Fetch error

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)

Returns: function - getTransactionObjects

core.getTransactionObjects(hashes, callback)

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

• INVALID_TRANSACTION_HASH
• Fetch error

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

Example

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

core.createGetTransactionsToApprove(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

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)

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

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)

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

Properties

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)

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

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)

Returns: function - removeNeighbors

core.removeNeighbors(uris, callback)

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

• INVALID_URI: Invalid uri
• Fetch error

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)

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

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)

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

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)

Returns: function - storeAndBroadcast

core.storeAndBroadcast(txs, callback)

Fulfil: TxHex[] Attached transaction txs
Reject: Error

• INVALID_ATTACHED_TX_HEX: Invalid attached txs
• Fetch error

| 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)

Returns: function - storeTransactions

core.storeTransactions(txs, callback)

Fullfil: TxHex[] Attached transaction txs
Reject: Error

• INVALID_ATTACHED_TX_HEX: Invalid attached txs
• Fetch error

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)

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

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.

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

Returns: Hash - Address txs