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

Upgrade

To perform an upgrade, execute the following command:

npm update @liskhq/lisk-transactions

Usage

Example of creating a transfer transaction
const transactions = require('@liskhq/lisk-transactions');

// 1. Create the transaction object
const tx = new transactions.TransferTransaction({
    asset:{
        amount: '15000000',
        recipientId: '123L',
        data: 'Hello Lisk!'
    }
});

// 2. Sign the transaction
tx.sign(
    '7158c297294a540bc9ac6e474529c3da38d03ece056e3fa2d98141e6ec54132d',
    'account reform outdoor curtain animal zoo best gain super glue bacon endless'
);

Constants

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

transactions.constants.BYTESIZES;
transactions.constants.DAPP_FEE;
transactions.constants.DELEGATE_NAME_FEE;
transactions.constants.EPOCH_TIME;
transactions.constants.EPOCH_TIME_MILLISECONDS;
transactions.constants.EPOCH_TIME_SECONDS;
transactions.constants.FIXED_POINT;
transactions.constants.MAX_ADDRESS_NUMBER;
transactions.constants.MAX_INT64;
transactions.constants.MAX_MULTISIG_SIGNATURES;
transactions.constants.MAX_NUMBER_OF_KEYS;
transactions.constants.MAX_NUMBER_OF_SIGNATURES;
transactions.constants.MAX_POM_HEIGHTS;
transactions.constants.MAX_PUBLIC_KEY_LENGTH;
transactions.constants.MAX_PUNISHABLE_BLOCK_HEIGHT_DIFFERENCE;
transactions.constants.MAX_TRANSACTION_AMOUNT;
transactions.constants.MAX_TRANSACTION_ID;
transactions.constants.MAX_TRANSFER_ASSET_DATA_LENGTH;
transactions.constants.MIN_FEE_PER_BYTE;
transactions.constants.MIN_NUMBER_OF_KEYS;
transactions.constants.MIN_NUMBER_OF_SIGNATURES;
transactions.constants.NETWORK_IDENTIFIER_LENGTH;
transactions.constants.USERNAME_MAX_LENGTH;

Creating transactions

Type 8: Transfer

This creates a transfer (type 8) transaction.

Syntax

TransferTransaction(options)

Parameters

options: Options to be used when creating the transaction:

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

  • recipientId (required): The address of the recipient.

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

Return value

object: The created transaction object.

Example

const tx = new transactions.TransferTransaction({
    asset:{
        amount: '15000000',
        recipientId: '123L',
        data: 'Hello Lisk!'
    }
});
/*
TransferTransaction {
  senderPublicKey: '',
  signatures: [],
  nonce: 0n,
  fee: 0n,
  type: 8,
  _id: undefined,
  confirmations: undefined,
  blockId: undefined,
  height: undefined,
  receivedAt: undefined,
  asset: { data: 'Hello Lisk!', recipientId: '123L', amount: 15000000n }
}
*/

Type 10: Delegate

This creates a register delegate (type 10) transaction.

Syntax

DelegateTransaction(options)

Parameters

options: Options to be used when creating the transaction:

  • asset.username: The delegate username to register.

Return value

object: The created transaction object.

Example

const tx =  new transactions.DelegateTransaction({ asset:{ username: 'myDelegate'}});
/*
DelegateTransaction {
  senderPublicKey: '',
  signatures: [],
  nonce: 0n,
  fee: 0n,
  type: 10,
  _id: undefined,
  confirmations: undefined,
  blockId: undefined,
  height: undefined,
  receivedAt: undefined,
  asset: { username: 'myDelegate' }
}
*/

Type 12: Multisignature

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

Syntax

MultisignatureTransaction(options)

Parameters

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

  • asset.mandatoryKeys: An array of public keys which are required for the multisignature group.

  • asset.optionalKeys: An array of public keys which are optionally part of the multisignature group.

  • asset.numberOfSignatures: The minimum number of signatures required to authorise a transaction. Needs to be a value between 1 and 64.

  • nonce: Nonce of the account that will sign this transaction.

  • fee: The transaction fee. Has to be equal or greater than the minimum fee for this transaction.

Return value

object: The created transaction object.

Example

const tx = new transactions.MultisignatureTransaction({
    asset: {
        mandatoryKeys: [
            '9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
            '141b16ac8d5bd150f16b1caa08f689057ca4c4434445e56661831f4e671b7c0a',
            '3ff32442bb6da7d60c1b7752b24e6467813c9b698e0f278d48c43580da972135',
        ],
        optionalKeys: [],
        numberOfSignatures: 3,
    },
    nonce: '2',
    fee: '250000',
});
console.log(tx);
/*
MultisignatureTransaction {
  senderPublicKey: '',
  signatures: [],
  nonce: 2n,
  fee: 250000n,
  type: 12,
  _id: undefined,
  confirmations: undefined,
  blockId: undefined,
  height: undefined,
  receivedAt: undefined,
  asset: {
    mandatoryKeys: [
      '9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f',
      '141b16ac8d5bd150f16b1caa08f689057ca4c4434445e56661831f4e671b7c0a',
      '3ff32442bb6da7d60c1b7752b24e6467813c9b698e0f278d48c43580da972135',
    ],
    optionalKeys: [],
    numberOfSignatures: 3,
    networkIdentifier: '7158c297294a540bc9ac6e474529c3da38d03ece056e3fa2d98141e6ec54132d'
  },
  MAX_KEYS_COUNT: 64
}
*/

Type 13: Vote

This creates a cast votes (type 13) transaction.

Syntax

castVotes(options)

Parameters

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

  • asset.votes: An array of objects with a delegateAddress and the amount of tokens that will be locked for this delegate.

Return value

object: The created transaction object.

Example

const tx = new transactions.VoteTransaction({
    asset:{
        votes:[
            { delegateAddress:'11750255083444888021L', amount: '-1000000000'},
            { delegateAddress:'64373847834494888026L', amount: '3000000000'}
        ]
    }
});

/*
VoteTransaction {
  senderPublicKey: '',
  signatures: [],
  nonce: 0n,
  fee: 0n,
  type: 13,
  _id: undefined,
  confirmations: undefined,
  blockId: undefined,
  height: undefined,
  receivedAt: undefined,
  asset: { votes: [
  { delegateAddress: '11750255083444888021L', amount: -1000000000n },
  { delegateAddress: '64373847834494888026L', amount: 3000000000n }
  ]}
}
  */

Type 14: Unlock

This creates a unlock (type 14) transaction, to unlock tokens that have been locked with the VoteTransaction.

Syntax

UnlockTransaction(options)

Parameters

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

  • asset.unlockingObjects: An array of objects with a delegateAddress, the unvoteHeight and the amount of tokens that will be unlocked for this delegate.

Return value

object: The created transaction object.

Example

const tx = new transactions.UnlockTransaction({
    asset:{
        unlockingObjects:[
            { delegateAddress:'11750255083444888021L', amount: '-1000000000', unvoteHeight: '1234'},
            { delegateAddress:'64373847834494888026L', amount: '3000000000', unvoteHeight: '1234' }
        ]
    }
});
/*
UnlockTransaction {
  senderPublicKey: '',
  signatures: [],
  nonce: 0n,
  fee: 0n,
  type: 14,
  _id: undefined,
  confirmations: undefined,
  blockId: undefined,
  height: undefined,
  receivedAt: undefined,
  asset: { unlockingObjects: [
  {
    delegateAddress: '11750255083444888021L',
    amount: -1000000000n,
    unvoteHeight: '1234'
  },
  {
    delegateAddress: '64373847834494888026L',
    amount: 3000000000n,
    unvoteHeight: '1234'
  }
 ]}
}
  */

Type 15: ProofOfMisbehavior

This creates a proof of misbehavior (type 15) transaction.

Syntax

transactions.ProofOfMisbehaviorTransaction(options)

Parameters

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

  • asset.header1 (required): The blockheader that is contradicting with asset.header2 as per BFT violation rules.

  • asset.header2 (required): The blockheader that is contradicting with asset.header1 as per BFT violation rules.

Return value

object: The created transaction object.

Example

const tx = new transactions.ProofOfMisbehaviorTransaction({
    asset:{
        header1: {
            blockSignature: 'e8b4768a7805bdcef097458e52b4acc5aed9816032504a57a0ae14ede0054bd916ddc0ff93a4baac91048930afde72f0e89a9fd5b07bd98620e3d5558b34b005',
            generatorPublicKey: '7a7f24c061db6a92320ba14323f814c20dbcc811a931ead3ca63c75a4de1b643',
            height: 8938,
            maxHeightPreviouslyForged: 8788,
            maxHeightPrevoted: 8868,
            numberOfTransactions: 0,
            payloadHash: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
            payloadLength: 0,
            previousBlockId: '9326981395427095175',
            reward: '500000000',
            seedReveal: 'abe2a66d7a35fd7b580e977d9f7911ae',
            timestamp: 122329567,
            totalAmount: '0',
            totalFee: '0',
            version: 2
        },
        header2: {
            blockSignature: '31ccf4ce1a3a224a2a32c3f4bdc6fad0ddb8feb45b05b7d411eee1a608f9d91284d09c727bba173c882d5dc90cb951c5affc10462d650031a627e00d919cbf08',
            generatorPublicKey: '7a7f24c061db6a92320ba14323f814c20dbcc811a931ead3ca63c75a4de1b643',
            height: 8933,
            maxHeightPreviouslyForged: 8788,
            maxHeightPrevoted: 8868,
            numberOfTransactions: 0,
            payloadHash: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
            payloadLength: 0,
            previousBlockId: '9326981395427095175',
            reward: '500000000',
            seedReveal: 'abe2a66d7a35fd7b580e977d9f7911ae',
            timestamp: 122329567,
            totalAmount: '0',
            totalFee: '0',
            version: 2
        }
    }
});
/*
ProofOfMisbehaviorTransaction {
  senderPublicKey: '',
  signatures: [],
  nonce: 0n,
  fee: 0n,
  type: 15,
  _id: undefined,
  confirmations: undefined,
  blockId: undefined,
  height: undefined,
  receivedAt: undefined,
  asset: {
    header1: {
      blockSignature: 'e8b4768a7805bdcef097458e52b4acc5aed9816032504a57a0ae14ede0054bd916ddc0ff93a4baac91048930afde72f0e89a9fd5b07bd98620e3d5558b34b005',
      generatorPublicKey: '7a7f24c061db6a92320ba14323f814c20dbcc811a931ead3ca63c75a4de1b643',
      height: 8938,
      maxHeightPreviouslyForged: 8788,
      maxHeightPrevoted: 8868,
      numberOfTransactions: 0,
      payloadHash: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
      payloadLength: 0,
      previousBlockId: '9326981395427095175',
      reward: '500000000',
      seedReveal: 'abe2a66d7a35fd7b580e977d9f7911ae',
      timestamp: 122329567,
      totalAmount: '0',
      totalFee: '0',
      version: 2
    },
    header2: {
      blockSignature: '31ccf4ce1a3a224a2a32c3f4bdc6fad0ddb8feb45b05b7d411eee1a608f9d91284d09c727bba173c882d5dc90cb951c5affc10462d650031a627e00d919cbf08',
      generatorPublicKey: '7a7f24c061db6a92320ba14323f814c20dbcc811a931ead3ca63c75a4de1b643',
      height: 8933,
      maxHeightPreviouslyForged: 8788,
      maxHeightPrevoted: 8868,
      numberOfTransactions: 0,
      payloadHash: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
      payloadLength: 0,
      previousBlockId: '9326981395427095175',
      reward: '500000000',
      seedReveal: 'abe2a66d7a35fd7b580e977d9f7911ae',
      timestamp: 122329567,
      totalAmount: '0',
      totalFee: '0',
      version: 2
    },
    reward: 0n
  }
}

  */

Signing transactions

After the transaction object was created like described in the section Creating transactions, it is needed to sign the transaction before it can be broadcasted to a node.

tx.sign(
    '7158c297294a540bc9ac6e474529c3da38d03ece056e3fa2d98141e6ec54132d', (1)
    'account reform outdoor curtain animal zoo best gain super glue bacon endless' (2)
    );
/*
TransferTransaction {
  senderPublicKey: 'f7425ba1b192e07639a0304531e21117ccc1852279b6ec7c296b18bd95bcc4c3',
  signatures: [
    'f6635a1f53f1e97443771c2b31b9f8cdfb1a5afb875f5d2bae8fec71c861fc8f3c9c312ac4fbc8a404a7b906b1bc7d62ca0851568ee30425452a497ab37caa0b'
  ],
  nonce: 0n,
  fee: 0n,
  type: 8,
  _id: '10457170653864555613',
  confirmations: undefined,
  blockId: undefined,
  height: undefined,
  receivedAt: undefined,
  asset: { data: 'Hello Lisk!', recipientId: '123L', amount: 15000000n }
}
 */
1 The network identifier of the network, where you wish to post the transaction.
2 Enter here the 12 word mnemonic passphrase for an account

After the transaction is signed, the signatures, senderPublicKey and networkIdentifier are added to the transaction object.

It is also possible to get the minimum fee for this particular transaction, to be accepted by the network:

tx.minFee
/*
141000n
 */

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.

verifyMinRemainingBalance

Verifies if the remaining balance in the account is sufficient.

Syntax

verifyMinRemainingBalance(id, account, minRemainingBalance)

Parameters

  • id: The id of the transaction.

  • account: The sender account of the transaction.

  • minRemainingBalance: The minimum account balance.

Return value

undefined: if the accounts has enough balance to pay the amount and fee of 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.