Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Latest commit

 

History

History
executable file
·
1954 lines (1432 loc) · 65.2 KB

api_reference.md

File metadata and controls

executable file
·
1954 lines (1432 loc) · 65.2 KB

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 signle 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-0s
[entry.value] number 0 Value to transfer in HLX
[entry.signatureMessageFragments] Array.<string> Array of signature message fragment bytes, defaults to all-0s
[entry.timestamp] number Transaction timestamp, defaults to Math.floor(Date.now() / 1000)
[entry.tag] string Optional Tag, defaults to null tag (all-0s)

Creates a bunlde with given transaction entries

Returns: Array.<Transaction> - Bundle

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

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

Adds a list of txs 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 txs.

converter

Documentation on the new conversions are currently in works.

core

core.composeApi([settings])

Param Type Default Description
[settings] object | function {} provider
[settings.provider] string "http://localhost:14700" 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])

Fulfill: 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_TRYTES: 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 pow.interface.js in node.js, pow.lib which works on WebGL 2 enabled browsers 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])

Fulfill: TxHex[] Attached transactions (txs)
Reject: Error

  • INVALID_ATTACHED_TRYTES: Invalid array of attached txs
  • Fetch error
Param Type Description

| txs | Array.<TransactionTxHex> | Attached 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 PoWbox, 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 approovee 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.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 32 txs 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 0-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 = 2

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

core.createGetTransactionStrings(provider)

Param Type Description
provider Provider Network provider

Returns: function - getTransactionStrings

core.getTransactionStrings(hashes, [callback])

Fulfil: String[] - Transaction strings (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 strings 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.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 a helix node node by calling removeNeighbors command. Assumes removeNeighbors command is available on the node.

This method has temporary effect until your a helix node 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. MWM is currently set to 2 on the testnet.
[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.createSendTransactionStrings(provider)

Param Type Description
provider Provider Network provider

Returns: function - sendTransactionStrings

core.sendTransactionStrings(txs, 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
txs Array.<TxHex> List of transactions (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 => sendTransactionStrings(txs, depth, minWeightMagnitude))
  .then(transactions => {
    // ...
  })
  .catch(err => {
    // ...
  })

core.createStoreAndBroadcast(provider)

Param Type
provider Provider

Returns: function - storeAndBroadcast

core.storeAndBroadcast(txs, [callback])

Fulfill: TxHex[] Attached txs Reject: Error

  • INVALID_ATTACHED_TRYTES: 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 transactions (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])

Fulfill: TxHex[] Attached transaction txs
Reject: Error

  • INVALID_ATTACHED_TRYTES: Invalid attached txs
  • Fetch error
Param Type Description

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

Persists a list of attached transactions (txs) in the store of the 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.

Persist the transactions (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 eventually 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 4 txs checksum

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

Returns: Hash - Address txs

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(bunlde => {
     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:14700
[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:14700" Uri of a helix node node
[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.

http-client~createHttpClient([settings])

Param Type Default Description
[settings] object {}
[settings.provider] string "http://localhost:14700" Uri of a helix node node
[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.

Create an http client to access a helix node http API.

Returns: Object

multisig

multisig.Address

multisig.Multisig

signing

signing~subseed(seed, index)

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

Returns: Int8Array - subseed txBits

signing~key(subseed, length)

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

Returns: Int8Array - Private key txBits

signing~digests(key)

Param Type Description
key Int8Array Private key txBits

signing~address(digests)

Param Type Description
digests Int8Array Digests txBits

Returns: Int8Array - Address txBits

signing~digest(normalizedBundleFragment, signatureFragment)

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

Returns: Int8Array - Digest txBits

signing~signatureFragment(normalizeBundleFragment, keyFragment)

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

Returns: Int8Array - Signature Fragment txBits

signing~validateSignatures(expectedAddress, signatureFragments, bundleHash)

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

signing~normalizedBundleHash(bundlehash)

Param Type Description
bundlehash Hash Bundle hash txs

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

Returns: Int8Array - Normalized bundle hash

transaction-converter

transaction-converter~asTransactionStrings(transactions)

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

Converts a transaction object or a list of those into transaction hex strings.

Returns: txs | Array.<TxHex> - Transaction hex strings

transaction-converter~asTransactionObject(txs)

Param Type Description
txs TxHex Transaction txs

Converts transaction txs of 768 txs 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 txs 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(txs)

Param Type Description
txs Array.<TxHex> List of transactions (txs) 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(txBytes)

Param Type Description
txBits Int8Array Int8Array of 6144
transaction txBits

Calculates the transaction hash out of 6144 transaction txBits.

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 (32 txs)

transaction~isTransactionTxHex(txs, minWeightMagnitude)

Param Type
txs string
minWeightMagnitude number

Checks if input is correct transaction txs (768 txs)

transaction~isAttachedTxHex(txs)

Param Type
txs string

Checks if input is valid attached transaction txs. For attached transactions last 48 txs 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 HLX units. Valid unit names are: h, Kh, Mh, Gh, Th, Ph

validators

validators~isAddress(address)

Param Type Description
address string Address txs, 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 a helix node 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