tx.txbuilder

Home > @blaze-cardano/tx > TxBuilder

TxBuilder class

A builder class for constructing Cardano transactions with various components like inputs, outputs, and scripts.

Signature:

export declare class TxBuilder 

Constructors

Constructor	Modifiers	Description
(constructor)(params, tracing)		Constructs a new instance of the TxBuilder class. Initializes a new transaction body with an empty set of inputs, outputs, and no fee.

Properties

Property	Modifiers	Type	Description
burnAddress	readonly	Address	Returns the burn address.
outputsCount	readonly	number	Returns the number of transaction outputs in the current transaction body.
params	readonly	ProtocolParameters

Methods

Method	Modifiers	Description
addAdditionalSigners(amount)		The additional signers field is used to add additional signing counts for fee calculation. These will be included in the signing phase at a later stage. This is needed due to native scripts signees being non-deterministic.
addDelegation(delegator, poolId, redeemer)		Adds a certificate to delegate a staker to a pool
addDeregisterStake(credential, redeemer)		Adds a certificate to deregister a stake account.
addInput(utxo, redeemer, unhashDatum)		Adds an input to the transaction. This method is responsible for including a new input, which represents a reference to an unspent transaction output (UTxO) that will be consumed by the transaction. Optionally, a redeemer and an unhashed datum can be provided for script validation purposes.
addMint(policy, assets, redeemer)		Adds minting information to the transaction. This includes specifying the policy under which assets are minted, the assets to be minted, and an optional redeemer for Plutus scripts.
addOutput(output)		Adds a transaction output to the current transaction body. This method also ensures that the minimum ada requirements are met for the output. After adding the output, it updates the transaction body's outputs. It also checks if the output value exceeds the maximum value size.
addPreCompleteHook(hook)		Adds a pre-complete hook to the transaction builder. This hook will be executed before the transaction is finalized. Pre-complete hooks are useful for performing last-minute modifications or validations on the transaction before it's completed. Multiple hooks can be added, and they will be executed in the order they were added.
addReferenceInput(utxo)		Adds a reference input to the transaction. Reference inputs are used to refer to outputs from previous transactions without spending them, allowing scripts to read their data. This can be useful for various contract logic, such as checking the state of a datum without consuming the UTxO that holds it.
addRegisterPool()		Adds a certificate to register a pool.
addRegisterStake(credential)		Adds a certificate to register a staker.
addRequiredSigner(signer)		Adds a required signer to the transaction. This is necessary for transactions that must be explicitly signed by a particular key.
addRetirePool()		Adds a certificate to retire a pool.
addUnspentOutputs(utxos)		Adds unspent transaction outputs (UTxOs) to the set of UTxOs available for this transaction. These UTxOs can then be used for balancing the transaction, ensuring that inputs and outputs are equal.
addWithdrawal(address, amount, redeemer)		Adds a withdrawal to the transaction. This method allows for the withdrawal of funds from a staking reward account. Optionally, a redeemer can be provided for script validation purposes.
buildFinalWitnessSet(signatures)	protected	Builds a full witness set with the provided signatures This includes collecting all necessary scripts (native, Plutus V1, V2, V3), vkey signatures, redeemers, and Plutus data required for script validation. It organizes these components into a structured format that can be serialized and included in the transaction.
buildPlaceholderWitnessSet()	protected	Builds a placeholder transaction witness set required for the transaction. This includes collecting all necessary scripts (native, Plutus V1, V2, V3), redeemers, and Plutus data required for script validation. Includes placeholder signatures for the known required signers, so we estimate the transaction size accurately It organizes these components into a structured format that can be serialized and included in the transaction.
calculateFees()	protected	Calculates the transaction fees based on the transaction size and parameters. It updates the transaction body with the calculated fee.
complete({ useCoinSelection })		Completes the transaction by performing several key operations: - Verifies the presence of a change address. - Gathers inputs and performs coin selection if necessary. - Balances the change output. - Builds the transaction witness set. - Calculates the script data hash. - Estimates and sets the transaction fee. - Merges the fee value with the excess value and rebalances the change.
delegate(poolId, redeemer)		This method delegates the selected reward address to a pool. It first checks if the reward address is set and if it has a stake component. If both conditions are met, it adds a delegation to the transaction.
deployScript(script, address)		Deploys a script by creating a new UTxO with the script as its reference.
enableTracing(enabled)		Hook to allow an existing instance to turn on tracing.
getScriptData(tw)	protected	Generates a script data hash for the transaction if there are any datums or redeemers present. This hash is crucial for the validation of Plutus scripts in the transaction.
lockAssets(address, value, datum, scriptReference)		Locks a specified amount of assets to a script. The difference between 'pay' and 'lock' is that you pay to a public key/user, and you lock at a script. This method ensures that the address is valid and the assets are locked to the script.
lockLovelace(address, lovelace, datum, scriptReference)		Locks a specified amount of lovelace to a script. The difference between 'pay' and 'lock' is that you pay to a public key/user, and you lock at a script. This method ensures that the address is valid and the lovelace is locked to the script.
payAssets(address, value, datum)		Adds a payment in assets to the transaction output. This method ensures that the address is valid and the payment is added to the transaction output.
payLovelace(address, lovelace, datum)		Adds a payment in lovelace to the transaction output. This method ensures that the address is valid and the payment is added to the transaction output.
prepareCollateral({ useCoinSelection })	protected	Prepares the collateral for the transaction by selecting suitable UTXOs. Throws an error if suitable collateral cannot be found or if some inputs cannot be resolved.{boolean}
provideCollateral(utxos)		Adds unspent transaction outputs (UTxOs) to the set of collateral UTxOs available for this transaction. These UTxOs can then be used to provide collateral for the transaction, if necessary. If provided, they will b If there are specific, valid collateral UTxOs provided, Blaze will use them before using any other UTxO.
provideDatum(datum)		Adds a Plutus datum to the transaction. This datum is not directly associated with any particular output but may be used by scripts during transaction validation. This method is useful for including additional information that scripts may need to validate the transaction without requiring it to be attached to a specific output.
provideScript(script)		Adds a script to the transaction's script scope. If the script is already provided via a reference script, it will not be explicitly used again. This method ensures that each script is only included once in the transaction, either directly or by reference, to optimize the transaction size and processing.
setAuxiliaryData(auxiliaryData)		Sets the auxiliary data for the transaction and updates the transaction's auxiliary data hash.
setChangeAddress(address, override)		Sets the change address for the transaction. This address will receive any remaining funds not allocated to outputs or fees.
setCollateralChangeAddress(address)		Sets the collateral change address for the transaction. This address will receive the collateral change if there is any.
setDonation(donation)		Sets the donation to the treasury in lovelace
setFeePadding(pad)		Sets an additional padding to add onto the transactions. Use this only in emergencies, and please open a ticket at https://github.com/butaneprotocol/blaze-cardano so we can correct the fee calculation!
setMetadata(metadata)		Sets the transaction metadata and updates the transaction's auxiliary data hash.
setMinimumFee(fee)		Sets the minimum fee for the transaction. This fee will be used during the transaction building process.
setNetworkId(networkId)		Sets the network ID for the transaction builder. The network ID is used to determine which network the transaction is intended for.
setRewardAddress(address)		Sets the reward address for the transaction. This address will be used for delegation purposes and also stake key component of the transaction.
setValidFrom(validFrom)		Specifies the exact time when the transaction becomes valid.
setValidUntil(validUntil)		Specifies the exact time when the transaction expires.
toCbor()		Prints the transaction cbor in its current state without trying to complete it
useCoinSelector(selector)		Sets a custom coin selector function for the transaction builder. This function will be used to select inputs during the transaction building process.
useEvaluator(evaluator, override)		Sets the evaluator for the transaction builder. The evaluator is used to execute Plutus scripts during transaction building.