Transactions

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

Installation

$ npm install @liskhq/lisk-transactions@3.0.2

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 registered 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 broadcast to.

  • recipientId: The address of the recipient.

  • recipientPublicKey: The address of the recipient. Required only 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 in order 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 broadcast 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 are displayed below:

  • username: The delegate username to register.

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

  • passphrase: Optional passphrase to use in order 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 can be found below:

  • 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 broadcast 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 12: registerMultisignature

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

Syntax

registerMultisignature(options)

Parameters

options: Options to be used when creating the transaction can be found below:

  • 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 broadcast 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, networkIdentifier)

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 broadcast 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 public 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 public 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. Chooses the 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 from a sender of a 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. A TransactionError is thrown, if the verification fails.

verifyAmountBalance

Verifies if an account has enough balance to pay the amount and the 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 account has enough balance to pay the amount and fee of the transaction. A 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 account has enough balance to send the transaction. A 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 the following:

  • status Contains 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 the following:

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

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