Transactions

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

Installation

How to perform the installation:

$ npm install @liskhq/lisk-transactions

Upgrade

How to perform an upgrade:

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: The options required when creating the transaction are shown below:

  • 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: The options required when creating the transaction are shown below:

  • 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: The options required when creating the transaction are shown 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. This needs to be a value between 1 and 64.

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

  • fee: The transaction fee. This 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: The options required when creating the transaction are shown 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 in order to unlock tokens that have been locked with the VoteTransaction.

Syntax

UnlockTransaction(options)

Parameters

options: The options required when creating the transaction are shown 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: The options required when creating the transaction are shown 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 as described in the section Creating transactions, it is necessary to sign the transaction before it can be broadcast 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 the 12 word mnemonic passphrase here 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, by executing the following command:

tx.minFee
/*
141000n
 */

Utility methods

convertBeddowsToLSK

This converts the amounts in Beddows (the smallest denomination), to the corresponding 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 corresponding 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 a 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.

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 have 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.