Transactions

The Lisk Elements transactions module provides functions for creating transactions of every type, including a set of utility functions.

Installation

$ npm install @liskhq/lisk-transactions

Upgrade

To perform an upgrade, execute the following command:

npm update @liskhq/lisk-transactions

Constants

Transactions-specific constants are available via the transaction key, and include relevant fees and byte allocations for transaction components.

Usage

import * as transactions from '@liskhq/lisk-transactions';

transactions.constants.FIXED_POINT; (1)

transactions.constants.TRANSFER_FEE; (2)
transactions.constants.SIGNATURE_FEE; (3)
transactions.constants.DELEGATE_FEE; (4)
transactions.constants.VOTE_FEE; (5)
transactions.constants.MULTISIGNATURE_FEE; (6)

transactions.constants.MULTISIGNATURE_MAX_LIFETIME; (7)
transactions.constants.MULTISIGNATURE_MIN_LIFETIME; (8)
transactions.constants.MULTISIGNATURE_MAX_KEYSGROUP; (9)
transactions.constants.MULTISIGNATURE_MIN_KEYSGROUP; (10)

transactions.constants.USERNAME_MAX_LENGTH; (11)
transactions.constants.BYTESIZES; (12)

transactions.constants.EPOCH_TIME; (13)
transactions.constants.EPOCH_TIME_MILLISECONDS; (14)
transactions.constants.EPOCH_TIME_SECONDS; (15)

transactions.constants.MAX_ADDRESS_NUMBER; (16)
transactions.constants.MAX_TRANSACTION_AMOUNT; (17)
transactions.constants.MAX_TRANSACTION_ID; (18)
1 Number to use when converting between the smallest possible denomination and 1 LSK.
2 Fee required for a transfer (type 0) transaction.
3 Fee required for a register second passphrase (type 1) transaction.
4 Fee required for a register delegate (type 2) transaction.
5 Fee required for a cast votes (type 3) transaction.
6 Fee required per group member (plus one) for a register multisignature account (type 4) transaction.
7 Maximum lifetime in transaction pool of a multi-signature transaction in hours.
8 Minimum lifetime in transaction pool of a multi-signature transaction in hours.
9 Maximum number of public keys that can be part of a multi-signature group.
10 Minimum number of public keys that can be part of a multi-signature group.
11 Maximum number of characters allowed for a username.
12 Object containing the number of bytes to allocate for each component of a transaction.
13 Date from which timestamps are calculated.
14 EPOCH_TIME in milliseconds since Unix Epoch.
15 EPOCH_TIME in seconds since Unix Epoch.
16 Maximum valid number which can form an address when suffixed with an 'L'.
17 Maximum valid amount for a transaction. Maximum value for PostgreSQL bigint.
18 Maximum valid number for transaction IDs.

Methods for creating transactions

Type 8: transfer

This creates a transfer (type 0) transaction.

Syntax

transfer(options)

Parameters

options: Options to be used when creating the transaction:

  • amount(required): The amount to transfer, (as a string in Beddows, the lowest denomination possible).

  • networkIdentifier(required): The ID of the network where the transaction will be broadcasted to.

  • recipientId: The address of the recipient.

  • recipientPublicKey: The address of the recipient. Only needed, if no recipientId is provided and vice versa.

  • data: Optional data to include in the transaction asset. (Must be a UTF8-encoded string of maximum 64 characters.)

  • passphrase: Optional passphrase to use to sign the transaction. If not provided at creation the transaction can be signed later.

  • secondPassphrase: Optional second passphrase to use to sign the transaction if the account has registered a second passphrase. If not provided at the creation, the transaction can be signed with the second passphrase later.

Return value

object: The created transaction object.

Example

transactions.transfer({
    networkIdentifier: '7158c297294a540bc9ac6e474529c3da38d03ece056e3fa2d98141e6ec54132d',
    amount: '1230000',
    recipientId: '12668885769632475474L'
    });
/*
{
  senderPublicKey: undefined,
  timestamp: 117410306,
  type: 8,
  asset: {
    amount: '1230000',
    recipientId: '12668885769632475474L',
    data: undefined
  }
}*/

Type 9: registerSecondPassphrase

This creates a register second passphrase, (type 1) transaction.

Syntax

registerSecondPassphrase(options)

Parameters

options: Options to be used when creating the transaction: * secondPassphrase: The second passphrase to register. * passphrase: Optional passphrase used to sign the transaction. * networkIdentifier: The ID of the network where the transaction will be broadcasted to. If not provided at the creation, the transaction can be signed later.

Return value

object: The created transaction object.

Example

transactions.registerSecondPassphrase({
    networkIdentifier: '7158c297294a540bc9ac6e474529c3da38d03ece056e3fa2d98141e6ec54132d',
    passphrase:'one two three',
    secondPassphrase:'four five six'
});
/*
{
    id: '13923958554840193683',
    blockId: undefined,
    height: undefined,
    confirmations: undefined,
    type: 9,
    timestamp: 117411517,
    senderPublicKey: 'ff61f0c5e5e48d8b043962b8f3a80fda41679f3fa0a1c79f8a294876fab242ed',
    senderId: '2367716785579772625L',
    fee: '500000000',
    signature: '774de652a6af47a8c0b5655f3b91677ebf67309e200462756fb6c55bc125f63903493798a4c962372b589a6fbbbadc28df86f6cbd25486eb271b78320fe76a0d',
    signSignature: undefined,
    signatures: [],
    asset: {
      publicKey: '92b5fc01eb39ed4edddac518aa6d58b15a48ae767f7ab2cfb6605966edacadf5'
    },
    receivedAt: undefined
  }
  */

Type 10: registerDelegate

This creates a register delegate (type 2) transaction.

Syntax

registerDelegate(options)

Parameters

options: Options to be used when creating the transaction:

  • username: The delegate username to register.

  • networkIdentifier: The ID of the network where the transaction will be broadcasted to.

  • passphrase: Optional passphrase to use to sign the transaction. If not provided at the creation, the transaction can be signed later.

  • secondPassphrase: Optional second passphrase used to sign the transaction if the account has registered a second passphrase. If not provided at the creation, the transaction can be signed with the second passphrase later.

Return value

object: The created transaction object.

Example

transactions.registerDelegate({
    networkIdentifier: '7158c297294a540bc9ac6e474529c3da38d03ece056e3fa2d98141e6ec54132d',
    passphrase:'one two three',
    username:'foo'
});
/*
{
  id: '16884232508060487400',
  blockId: undefined,
  height: undefined,
  confirmations: undefined,
  type: 10,
  timestamp: 117411841,
  senderPublicKey: 'ff61f0c5e5e48d8b043962b8f3a80fda41679f3fa0a1c79f8a294876fab242ed',
  senderId: '2367716785579772625L',
  fee: '2500000000',
  signature: '668264a8c6a769faa7a2c48dda08b33228d9775354d70312ecdfacbbde929693b27bb795d78abcbc1ab9e63552c086fa29da6a758a621c623f617dcf4e273208',
  signSignature: undefined,
  signatures: [],
  asset: { username: 'foo' },
  receivedAt: undefined
}
  */

Type 11: castVotes

This creates a cast votes (type 3) transaction.

Syntax

castVotes(options)

Parameters

options: Options to be used when creating the transaction:

  • votes: The public keys of the delegates to vote for.

  • unvotes: The public keys of the delegates from whom you want to remove your vote.

  • networkIdentifier: The ID of the network where the transaction will be broadcasted to.

  • passphrase: Optional passphrase used to sign the transaction. If not provided at the creation, the transaction can be signed later.

  • secondPassphrase: Optional second passphrase used to sign the transaction if the account has registered a second passphrase. If not provided at the creation, the transaction can be signed with the second passphrase later.

Return value

object: The created transaction object.

Example

transactions.castVotes({
    networkIdentifier: '7158c297294a540bc9ac6e474529c3da38d03ece056e3fa2d98141e6ec54132d',
    passphrase:'one two three',
    votes: ['9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f'],
    unvotes: [
        '141b16ac8d5bd150f16b1caa08f689057ca4c4434445e56661831f4e671b7c0a',
        '3ff32442bb6da7d60c1b7752b24e6467813c9b698e0f278d48c43580da972135',
        ]
});

/*
{
  id: '12115346598732700133',
  blockId: undefined,
  height: undefined,
  confirmations: undefined,
  type: 11,
  timestamp: 117412612,
  senderPublicKey: 'ff61f0c5e5e48d8b043962b8f3a80fda41679f3fa0a1c79f8a294876fab242ed',
  senderId: '2367716785579772625L',
  fee: '100000000',
  signature: 'da54f85ee512ac67ff9cd278cd751a9243f5977530315d5e3fddc954fefd6f3351ad8f86e035ee86d99d14db228fdea98664d6ef724baef662f8f866ed7fda09',
  signSignature: undefined,
  signatures: [],
  asset: {
    votes: [
      '+9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
      '-141b16ac8d5bd150f16b1caa08f689057ca4c4434445e56661831f4e671b7c0a',
      '-3ff32442bb6da7d60c1b7752b24e6467813c9b698e0f278d48c43580da972135'
    ]
  },
  receivedAt: undefined
}
  */

Type 11: registerMultisignature

This creates a register multisignature account (type 4) transaction.

Syntax

registerMultisignature(options)

Parameters

options: Options to be used when creating the transaction:

  • keysgroup: An array of public keys which should form part of the multisignature group.

  • lifetime: The time to wait for enough signatures before a transaction becomes invalid.

  • minimum: The minimum number of signatures required to authorise a transaction.

  • networkIdentifier: The ID of the network where the transaction will be broadcasted to.

  • passphrase: Optional passphrase used to sign the transaction. If not provided at the creation, the transaction can be signed later.

  • secondPassphrase: Optional second passphrase used to sign the transaction if the account has registered a second passphrase. If not provided at the creation, the transaction can be signed with the second passphrase later.

Return value

object: The created transaction object.

Example

transactions.registerMultisignature({
    keysgroup: [
        '9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
        '141b16ac8d5bd150f16b1caa08f689057ca4c4434445e56661831f4e671b7c0a',
        '3ff32442bb6da7d60c1b7752b24e6467813c9b698e0f278d48c43580da972135',
    ],
    lifetime: 34,
    minimum: 2,
    networkIdentifier: '7158c297294a540bc9ac6e474529c3da38d03ece056e3fa2d98141e6ec54132d'
});
/*
{
  senderPublicKey: undefined,
  timestamp: 117413270,
  type: 12,
  fee: '2000000000',
  asset: {
    min: 2,
    lifetime: 34,
    keysgroup: [
      '+9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
      '+141b16ac8d5bd150f16b1caa08f689057ca4c4434445e56661831f4e671b7c0a',
      '+3ff32442bb6da7d60c1b7752b24e6467813c9b698e0f278d48c43580da972135'
    ]
  },
  networkIdentifier: '7158c297294a540bc9ac6e474529c3da38d03ece056e3fa2d98141e6ec54132d'
}
*/

Methods for creating signature objects

createSignatureObject

This creates a signature object for a transaction from a multisignature account.

Syntax

createSignatureObject(transaction, passphrase)

Parameters

  • transaction: The multisignature transaction to sign.

  • passphrase: Passphrase used to sign the transaction.

  • networkIdentifier: The ID of the network where the transaction will be broadcasted to.

Return value

object: The signature object which can be broadcast to the network. Contains transactionId, publicKey and signature hex strings.

Example

transactions.createSignatureObject({
    transaction: {
        id: '14133632879168695498',
        blockId: undefined,
        height: undefined,
        confirmations: undefined,
        type: 11,
        timestamp: 117414657,
        senderPublicKey: 'ff61f0c5e5e48d8b043962b8f3a80fda41679f3fa0a1c79f8a294876fab242ed',
        senderId: '2367716785579772625L',
        fee: '100000000',
        signature: 'adc74c9e8521cded1559fb73cdee1e16e698d9e5a8f30998e953b74daf999ffe1d7993b5faf8ffbc72fa981187baeab2afa5f44c97ca743f6bf4208cf7f6a90f',
        signSignature: undefined,
        signatures: [],
        asset: {
            votes: [
                '+9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
                '-141b16ac8d5bd150f16b1caa08f689057ca4c4434445e56661831f4e671b7c0a',
                '-3ff32442bb6da7d60c1b7752b24e6467813c9b698e0f278d48c43580da972135'
            ]
        },
        receivedAt: undefined
                 },
    passphrase: 'one two three',
    networkIdentifier: '7158c297294a540bc9ac6e474529c3da38d03ece056e3fa2d98141e6ec54132d'
});
/*
{
  transactionId: '14133632879168695498',
  publicKey: 'ff61f0c5e5e48d8b043962b8f3a80fda41679f3fa0a1c79f8a294876fab242ed',
  signature: 'adc74c9e8521cded1559fb73cdee1e16e698d9e5a8f30998e953b74daf999ffe1d7993b5faf8ffbc72fa981187baeab2afa5f44c97ca743f6bf4208cf7f6a90f'
}
*/

Utility methods

convertBeddowsToLSK

This converts amounts in Beddows, (the smallest denomination) to the amounts in one LSK.

Syntax

convertBeddowsToLSK(amount)

Parameters

amount: string decimal representation of amount to be converted.

Return value

string: Amount in LSK.

Examples

transactions.utils.convertBeddowsToLSK('100000'); // '0.001'

convertLSKToBeddows

This converts the amounts in LSK to the amounts in Beddows, (the smallest denomination).

Syntax

convertLSKToBeddows(amount)

Parameters

amount: string decimal representation of amount to be converted.

Return value

string: Amount in Beddows.

Examples

transactions.utils.convertLSKToBeddows('0.001'); // '100000'

getId

Returns a transaction ID for a transaction.

Syntax

getId(transactionBytes)

Parameters

transactionBytes: The buffer representation of the transaction whose ID is required.

Return value

string: The transaction ID.

validateSenderIdAndPublicKey

Validates if the senderId matches the public key of a transaction.

Syntax

validateSenderIdAndPublicKey(id, senderId, publicKey)

Parameters

  • id: The transaction id.

  • senderId: The address to validate as string.

  • senderPublicKey: The public key to validate as string.

Return value

boolean: true if the public key matches the senderId, otherwise an error will be thrown.

validateMultisignatures

Validates multisignatures.

Syntax

validateMultisignatures(publicKeys, signatures, minimumValidations, transactionBytes(,id))

Parameters

  • publicKeys: The public key to validate as list of strings.

  • signatures: The signature to validate as string.

  • minimumValidations: The public key to validate as number.

  • transactionBytes: The buffer representation of the transaction.

  • id: Optional transaction id.

Return value

boolean: true if the signature is valid for the provided transaction and public key, otherwise an error will be thrown.

validateSignature

Validates a signature.

Syntax

validateSignature(publicKey, signature, transactionBytes(,id))

Parameters

  • publicKey: The public key to validate as string.

  • signature: The signature to validate as string.

  • transactionBytes: The buffer representation of the transaction.

  • id: Optional transaction id.

Return value

boolean: true if the signature is valid for the provided transaction and public key, otherwise an error will be thrown.

prependMinusToPublicKeys

Prepends a - to a list of public keys.

Syntax

prependMinusToPublicKeys([publicKeys])

Parameters

publicKeys: List of pulbic keys.

Return value

publicKeys: A list of public keys with a - prepended.

prependPlusToPublicKeys

Prepends a + to a list of public keys.

Syntax

prependPlusToPublicKeys([publicKeys])

Parameters

publicKeys: List of pulbic keys.

Return value

publicKeys: A list of public keys with a + prepended.

getTimeFromBlockchainEpoch

Calculates the number of seconds that elapsed since the network Epoch time. Picks current time, if no time is provided. ==== Syntax

getTimeFromBlockchainEpoch(timestamp)

Parameters

timestamp: Optional timestamp in seconds as number.

Return value

timestamp: The time that has been elapsed between the network Epoch time and the provided timestamp.

verifySenderPublicKey

Verifies a public key of a sender of an transaction.

Syntax

verifySenderPublicKey(id, sender, publicKey)

Parameters

  • id: The id of the transaction.

  • sender: The sender account of the transaction.

  • publicKey: The public key to verify.

Return value

undefined: if the public key is verified. An TransactionError is thrown, if the verification fails.

verifyAmountBalance

Verifies if an account has enough balance to pay amount and fee of a transaction.

Syntax

verifyAmountBalance(id, account, amount, fee)

Parameters

  • id: The id of the transaction.

  • account: The sender account of the transaction.

  • amount: The amount of the transaction.

  • fee: The fee of the transaction.

Return value

undefined: if the accounts has enough balance to pay the amount and fee of the transaction. An TransactionError is thrown, if the verification fails.

verifyBalance

Verifies if an account has enough balance to send a transaction.

Syntax

verifyBalance(id, account, amount)

Parameters

  • id: The id of the transaction.

  • account: The sender account of the transaction.

  • amount: The amount of the transaction.

Return value

undefined: if the accounts has enough balance to send the transaction. An TransactionError is thrown, if the verification fails.

verifyMultiSignatures

Verifies signatures of a multisignature account for a transaction.

Syntax

verifyMultiSignatures(id, sender, signatures, transactionBytes)

Parameters

  • id: The id of the transaction.

  • sender: The sender account of the transaction.

  • signatures: The signatures to verify.

  • transactionBytes: The buffer representation of the transaction.

Return value

object: An object with

  • status containing the result of the validation of the signatures.

  • errors A list of TransactionErrors, empty if none have been thrown.

verifySecondSignature

Verifies the second signature of an account for a transaction.

Syntax

verifySecondSignature(id, sender, signSignature, transactionBytes)

Parameters

  • id: The id of the transaction.

  • sender: The sender account of the transaction.

  • signSignature: The signature to verify.

  • transactionBytes: The buffer representation of the transaction.

Return value

object: An object with

  • status containing the result of the validation of the second signature.

  • errors A list of TransactionErrors, empty if none have been thrown.