TransactionBuilder

This package houses the TransactionBuilder, which lets you build a transaction to then send into the network.

Installation

Install through your package manager of choice:

pnpm install @pokt-foundation/pocketjs-transaction-builder

Usage

import { TransactionBuilder } from '@pokt-foundation/pocketjs-transaction-builder'

// Initializing the TransactionBuilder is simple:
// 1. Instanciate a provider
export const provider = new JsonRpcProvider({
  rpcUrl: MAINNET_RPC_URL,
})

// 2. Instanciate a signer
export const signer = await KeyManager.fromPrivateKey(process.env.PRIVATE_KEY)

// 3. Instanciate the TransactionBuilder
export const builder = new TransactionBuilder({
  signer,
  provider,
})

// Create a new `Send` Message which is used to send funds over the network.
const sendMsg = transactionBuilder.send(
  signer.getAddress(),
  '07a6fca4dea9f01e4c19f301df0d0afac128561b',
  // Amount in uPOKT (1 POKT = 1*10^6 uPOKT)
  '1000000'
)
// Send it over the network!
const txresponse = await transactionBuilder.submit({
  memo: 'POKT Payment',
  txMsg: sendMsg,
})

TransactionBuilder API

Constructor

signer

• type: KeyManager The KeyManager instance that holds the staked app in the blockchain.

provider

• type: JsonRpcProvider | IsomorphicProvider The provider instance with available dispatchers to talk to the network.

chainID (optional)

• type: mainnet | localnet | testnet ChainID to send the transactions to. The provider endpoint must be connected to that chain ID.

Methods

getChainID(): ChainID

Gets the current chain ID this transaction builder has been initialized for.

Returns ChainID: 'mainnet', 'localnet', or 'testnet'.

setChainID(id): void

Sets the chainID to one of the supported networks.

| Param | Type | Description | | ----- | -------- | ------------------------------------------------------------------------------- | | id | string | The chain to send transactions to. The provider must be connected to that chain |

createTransaction({ fee, memo, txMsg }): Promise

Signs and creates a transaction object that can be submitted to the network given the parameters and called upon Msgs.

Returns Promise<RawTxRequest>: The raw transaction request which can be sent over the network.

| Param | Type | Description | | ----- | -------- | -------------------------------------------------------------------------------------------- | | fee | string | The amount to pay as a fee for executing this transaction, in uPOKT (1 POKT = 1*10^6 uPOKT) | | memo | string | Memo field for this transaction. | | txMsg | TxMsg | Transaction message generated with one of the available methods. |

submit({ fee, memo, txMsg }): Promise

Submit receives a valid transaction message, creates a Raw Transaction Request and sends it over the network.

Returns Promise<TransactionResponse: The transaction response from the network, containing the transaction hash.

| Param | Type | Description | | ----- | -------- | -------------------------------------------------------------------------------------------- | | fee | string | The amount to pay as a fee for executing this transaction, in uPOKT (1 POKT = 1*10^6 uPOKT) | | memo | string | Memo field for this transaction. | | txMsg | TxMsg | Transaction message generated with one of the available methods. |

submitRawTransaction(tx): Promise

Submit receives an already made Raw Transaction Request and sends it over the network.

Returns Promise<TransactionResponse: The transaction response from the network, containing the transaction hash.

| Param | Type | Description | | ----- | -------------- | -------------------------------------------------------------- | | tx | RawTxRequest | The raw transaction request, created with createTransaction. |

send({ fromAddress, toAddress, amount }): MsgProtoSend

Adds a MsgSend TxMsg for this transaction.

Returns a MsgProtoSend: An unsigned Send transaction message.

| Param | Type | Description | | ----------- | -------- | ----------------------------------------------------------- | | fromAddress | string | Origin address, which is the address that the signer holds. | | toAddress | string | Destination address | | amount | string | Amount of uPOKT to send. |

appStake({ appPubKey, chains, amount }): MsgProtoAppStake

Adds a MsgAppStake TxMsg for this transaction.

Returns a MsgProtoAppStake: The unsigned App Stake message.

| Param | Type | Description | | --------- | ---------- | ------------------------------------------------------------------------------------------------------------ | | appPubKey | string | Application Public Key | | chains | string[] | Chains that the apps wants access to by staking POKT. Throughput will be equally divided through all chains. | | amount | string | Amount of uPOKT to stake. |

appTransfer({ appPubKey }): MsgProtoAppStake

Builds a transaction message to transfer the slot of a staked app. Signer must be an existing staked app to transfer the slot from.

Returns a MsgProtoAppTransfer: The unsigned AppTransfer message

|Param|Type|Description| |--|--|--| |appPubKey|string|Application public key to be transferred to|

appUnstake(address): MsgProtoAppUnstake

Adds a MsgProtoAppUnstake TxMsg for this transaction.

Returns MsgProtoAppUnstake: The unsigned app unstake message.

| Param | Type | Description | | ------- | -------- | ----------------------- | | address | string | Address of the account. |

nodeStake({ nodePubKey, chains, amount, serviceURL }): MsgProtoNodeStakeTx

Adds a NodeStake TxMsg for this transaction.

Returns a MsgProtoNodeStakeTx: The unsigned node stake message.

| Param | Type | Description | | ---------- | ---------- | ------------------------------------------------------------ | | nodePubKey | string | Node Public Key | | chains | string[] | Chains that the node wants to service to by staking POKT. | | amount | string | Amount of uPOKT to stake. | | serviceURL | URL | Node service URL that will be used to send requests through. |

nodeUnstake(address): MsgProtoNodeUnstake

Adds a MsgProtoNodeUnstake for this transaction.

Returns MsgProtoNodeUnstake: The unsigned node unstake message.

| Param | Type | Description | | ------- | -------- | ----------------------- | | address | string | Address of the account. |

nodeUnjail(address): MsgAProtoNodeUnjail

Adds a MsgUnjail for this transaction.

Returns a MsgProtoNodeUnstake: The unsigned node unjail message.

| Param | Type | Description | | ------- | -------- | ----------------------- | | address | string | Address of the account. |

govDAOTransfer({ toAddress, amount, action }): MsgProtoGovUpgrade

Adds a MsgProtoGovDAOTransferTxMsg for this transaction.

Returns a MsgProtoGovDAOTransfer: The unsigned upgrade message

| Param | Type | Description | | --------- | ----------- | -------------------------------------------------------------------------------------- | | action | DAOAction | the action the dao transfer represent (i.e transfer or burn) | | amount | string | the Amount of uPOKT to perform with specified action | | toAddress | string | the recipient of the dao action once executed for transfers. Not required for burning. |

govChangeParam({ paramKey, paramValue, overrideGovParamsWhitelistValidation }): MsgProtoGovUpgrade

Adds a MsgProtoGovChangeParamTxMsg for this transaction.

Returns a MsgProtoGovChangeParam: The unsigned upgrade message

| Param | Type | Description | | ------------------------------------ | ------------------------ | ----------------------------------------------------------------------------------------------- | | paramKey | GovParameter, string | the governance parameter key | | paramValue | string | the new governance parameter value in ASCII (plain text) format. | | overrideGovParamsWhitelistValidation | boolean (optional) | used to override the validation check for a governance parameter not found in GovParameter enum |

govUpgradeHeight({ height, version }): MsgProtoGovUpgrade

Adds a MsgProtoGovUpgradeTxMsg for this transaction.

The GovUpgradeTxMsg is multipurpose. This function acts as an opinionated way of applying the protocol's upgrade height

Returns a MsgProtoGovUpgrade: The unsigned upgrade message

| Param | Type | Description | | ------- | -------- | ---------------------------------------- | | height | int | height to upgrade the protocol's version | | version | string | the new protocol's version |

govUpgradeFeatures({ features }): MsgProtoGovUpgrade

Adds a MsgProtoGovUpgradeTxMsg for this transaction.

The GovUpgradeTxMsg is multipurpose. This function acts as an opinionated way of applying the protocol's upgrade features.

Returns a MsgProtoGovUpgrade: The unsigned upgrade message

| Param | Type | Description | |----------|------------|-------------------------------------------------------------------| | features | string[] | array of features [ "RSCAL:30000", "{featureName2}:{height2}" ] |

govUpgrade({ features, height, version }): MsgProtoGovUpgrade

The GovUpgradeTxMsg is multipurpose, use this only if you are familiar with the tx msg, otherwise rely on govUpgradeHeight and govUpgradeFeatures

Returns a MsgProtoGovUpgrade: The unsigned upgrade message

| Param | Type | Description | |----------|------------|---------------------------------------------------------------------------------------------------------------| | height | int | height to upgrade the protocol's version | | version | string | the new protocol's version | | features | string[] | array of features to deactivate / activate with the notation: [ "RSCAL:30000", "{featureName2}:{height2}" ] |