Class TxBuilder

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

Constructors

constructor

Properties

params

Accessors

burnAddress outputsCount

Methods

addAdditionalSigners addDelegation addDeregisterStake addInput addMint addOutput addPreCompleteHook addReferenceInput addRegisterPool addRegisterStake addRequiredSigner addRetirePool addUnspentOutputs addWithdrawal complete delegate deployScript enableTracing lockAssets lockLovelace payAssets payLovelace provideCollateral provideDatum provideScript setAuxiliaryData setChangeAddress setCollateralChangeAddress setDonation setFeePadding setMetadata setMinimumFee setNetworkId setRewardAddress setValidFrom setValidUntil toCbor useCoinSelector useEvaluator

Constructors

constructor

  • new TxBuilder(params, tracing?): TxBuilder

  • Constructs a new instance of the TxBuilder class. Initializes a new transaction body with an empty set of inputs, outputs, and no fee.

    Parameters

    Returns TxBuilder

Properties

Readonlyparams

params: Core.ProtocolParameters

Accessors

burnAddress

  • get burnAddress(): Address

  • Returns the burn address.

    Returns Address

outputsCount

  • get outputsCount(): number

  • Returns the number of transaction outputs in the current transaction body.

    Returns number

    The number of transaction outputs.

Methods

addAdditionalSigners

  • addAdditionalSigners(amount): TxBuilder

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

    Parameters

    • amount: number

      The amount of additional signers

    Returns TxBuilder

    The same transaction builder

addDelegation

  • addDelegation(delegator, poolId, redeemer?): TxBuilder

  • Adds a certificate to delegate a staker to a pool

    Parameters

    • delegator: Credential

      The credential of the staker to delegate.

    • poolId: Core.PoolId

      The ID of the pool to delegate to.

    • Optionalredeemer: PlutusData

      Optional. A redeemer to be used if the delegation requires Plutus script validation.

    Returns TxBuilder

    The updated transaction builder.

addDeregisterStake

  • addDeregisterStake(credential, redeemer?): TxBuilder

  • Adds a certificate to deregister a stake account.

    Parameters

    • credential: Credential

      The credential to deregister.

    • Optionalredeemer: PlutusData

    Returns TxBuilder

    The updated transaction builder.

addInput

  • addInput(utxo, redeemer?, unhashDatum?): TxBuilder

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

    Parameters

    • utxo: TransactionUnspentOutput

      The UTxO to be consumed as an input.

    • Optionalredeemer: PlutusData

      Optional. The redeemer data for script validation, required for spending Plutus script-locked UTxOs.

    • OptionalunhashDatum: PlutusData

      Optional. The unhashed datum, required if the UTxO being spent includes a datum hash instead of inline datum.

    Returns TxBuilder

    The same transaction builder

    Throws

    If attempting to add a duplicate input, if the UTxO payment key is missing, if attempting to spend with a redeemer for a KeyHash credential, if attempting to spend without a datum when required, or if providing both an inline datum and an unhashed datum.

addMint

  • addMint(policy, assets, redeemer?): this

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

    Parameters

    • policy: PolicyId

      The policy ID under which the assets are minted.

    • assets: Map<AssetName, bigint>

      A map of asset names to the amounts being minted.

    • Optionalredeemer: PlutusData

      Optional. A redeemer to be used if the minting policy requires Plutus script validation.

    Returns this

addOutput

  • addOutput(output): TxBuilder

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

    Parameters

    • output: TransactionOutput

      The transaction output to be added.

    Returns TxBuilder

    The same transaction builder

addPreCompleteHook

  • addPreCompleteHook(hook): TxBuilder

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

    Parameters

    • hook: ((tx: TxBuilder) => Promise<void>)

      A function that takes the TxBuilder instance as an argument and performs some operation. The hook should be asynchronous.

        • (tx): Promise<void>

        • Parameters

          Returns Promise<void>

    Returns TxBuilder

    The same transaction builder instance for method chaining.

addReferenceInput

  • addReferenceInput(utxo): TxBuilder

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

    Parameters

    • utxo: TransactionUnspentOutput

      The unspent transaction output to add as a reference input.

    Returns TxBuilder

    The same transaction builder

    Throws

    If the input to be added is already present in the list of reference inputs, to prevent duplicates.

addRegisterPool

  • addRegisterPool(): void

  • Adds a certificate to register a pool.

    Returns void

    Throws

    Method not implemented.

addRegisterStake

  • addRegisterStake(credential): this

  • Adds a certificate to register a staker.

    Parameters

    • credential: Credential

      The credential to register.

    Returns this

    Throws

    Method not implemented.

addRequiredSigner

  • addRequiredSigner(signer): TxBuilder

  • Adds a required signer to the transaction. This is necessary for transactions that must be explicitly signed by a particular key.

    Parameters

    • signer: Ed25519KeyHashHex

      The hash of the Ed25519 public key that is required to sign the transaction.

    Returns TxBuilder

    The same transaction builder

addRetirePool

  • addRetirePool(): void

  • Adds a certificate to retire a pool.

    Returns void

    Throws

    Method not implemented.

addUnspentOutputs

  • addUnspentOutputs(utxos): TxBuilder

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

    Parameters

    • utxos: TransactionUnspentOutput[]

      The unspent transaction outputs to add.

    Returns TxBuilder

    The same transaction builder

addWithdrawal

  • addWithdrawal(address, amount, redeemer?): TxBuilder

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

    Parameters

    • address: Core.RewardAccount

      The reward account from which to withdraw.

    • amount: bigint

      The amount of ADA to withdraw.

    • Optionalredeemer: PlutusData

      Optional. The redeemer data for script validation.

    Returns TxBuilder

    The same transaction builder

    Throws

    If the reward account does not have a stake credential or if any other error occurs.

complete

  • complete(__namedParameters?): Promise<Transaction>

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

    Parameters

    • Optional__namedParameters: UseCoinSelectionArgs

    Returns Promise<Transaction>

    A new Transaction object with all components set and ready for submission.

    Throws

    If the change address is not set, or if the coin selection fails to eliminate negative values, or if balancing the change output fails.

delegate

  • delegate(poolId, redeemer?): this

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

    Parameters

    • poolId: Core.PoolId

      The ID of the pool to delegate the reward address to.

    • Optionalredeemer: PlutusData

    Returns this

    Throws

    If the reward address is not set or if the method is unimplemented.

deployScript

  • deployScript(script, address?): TxBuilder

  • Deploys a script by creating a new UTxO with the script as its reference.

    Parameters

    • script: Script

      The script to be deployed.

    • Optionaladdress: Address

      The address to lock the script to. Defaults to a burn address where the UTxO will be unspendable.

    Returns TxBuilder

    The same transaction builder.

    Example

    const myScript = Script.newPlutusV2Script(new PlutusV2Script("..."));
    txBuilder.deployScript(myScript);
    // or
    txBuilder.deployScript(myScript, someAddress);

enableTracing

  • enableTracing(enabled): TxBuilder

  • Hook to allow an existing instance to turn on tracing.

    Parameters

    • enabled: boolean

      Whether to enable tracing.

    Returns TxBuilder

lockAssets

  • lockAssets(address, value, datum, scriptReference?): TxBuilder

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

    Parameters

    • address: Address

      The address to lock the assets to.

    • value: Value

      The value of the assets to lock.

    • datum: Core.Datum

      The datum to be associated with the locked assets.

    • OptionalscriptReference: Script

      The reference to the script to lock the assets to.

    Returns TxBuilder

    The same transaction builder

lockLovelace

  • lockLovelace(address, lovelace, datum, scriptReference?): TxBuilder

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

    Parameters

    • address: Address

      The address to lock the lovelace to.

    • lovelace: bigint

      The amount of lovelace to lock.

    • datum: Core.Datum

      The datum to be associated with the locked lovelace.

    • OptionalscriptReference: Script

      The reference to the script to lock the lovelace to.

    Returns TxBuilder

    The same transaction builder

payAssets

  • payAssets(address, value, datum?): TxBuilder

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

    Parameters

    • address: Address

      The address to send the payment to.

    • value: Value

      The value of the assets to send.

    • Optionaldatum: Core.Datum

      Optional datum to be associated with the paid assets.

    Returns TxBuilder

    The same transaction builder

payLovelace

  • payLovelace(address, lovelace, datum?): TxBuilder

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

    Parameters

    • address: Address

      The address to send the payment to.

    • lovelace: bigint

      The amount of lovelace to send.

    • Optionaldatum: Core.Datum

      Optional datum to be associated with the paid assets.

    Returns TxBuilder

    The same transaction builder

provideCollateral

  • provideCollateral(utxos): TxBuilder

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

    Parameters

    • utxos: TransactionUnspentOutput[]

      the UTxOs to add as collateral

    Returns TxBuilder

    The same transaction builder

provideDatum

  • provideDatum(datum): TxBuilder

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

    Parameters

    • datum: PlutusData

      The Plutus datum to be added to the transaction.

    Returns TxBuilder

    The same transaction builder

provideScript

  • provideScript(script): TxBuilder

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

    Parameters

    • script: Script

      The script to be added to the transaction's script scope.

    Returns TxBuilder

    The same transaction builder

setAuxiliaryData

  • setAuxiliaryData(auxiliaryData): TxBuilder

  • Sets the auxiliary data for the transaction and updates the transaction's auxiliary data hash.

    Parameters

    • auxiliaryData: AuxiliaryData

      The auxiliary data to set.

    Returns TxBuilder

    The same transaction builder

setChangeAddress

  • setChangeAddress(address, override?): TxBuilder

  • Sets the change address for the transaction. This address will receive any remaining funds not allocated to outputs or fees.

    Parameters

    • address: Address

      The address to receive the change.

    • Optionaloverride: boolean

      Whether to override the change address if one is already set.

    Returns TxBuilder

    The same transaction builder

setCollateralChangeAddress

  • setCollateralChangeAddress(address): TxBuilder

  • Sets the collateral change address for the transaction. This address will receive the collateral change if there is any.

    Parameters

    • address: Address

      The address to receive the collateral change.

    Returns TxBuilder

    The same transaction builder

setDonation

  • setDonation(donation): TxBuilder

  • Sets the donation to the treasury in lovelace

    Parameters

    • donation: bigint

      The amount of lovelace to donate back to the treasury

    Returns TxBuilder

    The same transaction builder

setFeePadding

  • setFeePadding(pad): TxBuilder

  • 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!

    Parameters

    • pad: bigint

      The padding to add onto the transaction fee

    Returns TxBuilder

    the same transaction builder

setMetadata

  • setMetadata(metadata): TxBuilder

  • Sets the transaction metadata and updates the transaction's auxiliary data hash.

    Parameters

    • metadata: GeneralTransactionMetadata

      the metadata to set

    Returns TxBuilder

    The same transaction builder

setMinimumFee

  • setMinimumFee(fee): TxBuilder

  • Sets the minimum fee for the transaction. This fee will be used during the transaction building process.

    Parameters

    • fee: bigint

      The minimum fee to be set.

    Returns TxBuilder

    The same transaction builder

setNetworkId

  • setNetworkId(networkId): TxBuilder

  • Sets the network ID for the transaction builder. The network ID is used to determine which network the transaction is intended for.

    Parameters

    • networkId: NetworkId

      The network ID to set.

    Returns TxBuilder

    The same transaction builder

setRewardAddress

  • setRewardAddress(address): TxBuilder

  • Sets the reward address for the transaction. This address will be used for delegation purposes and also stake key component of the transaction.

    Parameters

    • address: Address

      The reward address

    Returns TxBuilder

    The same transaction builder

setValidFrom

  • setValidFrom(validFrom): TxBuilder

  • Specifies the exact time when the transaction becomes valid.

    Parameters

    • validFrom: Slot

      The slot from which the transaction becomes valid.

    Returns TxBuilder

    The instance of this TxBuilder for chaining.

    Throws

    If the validity start interval is already set.

setValidUntil

  • setValidUntil(validUntil): TxBuilder

  • Specifies the exact time when the transaction expires.

    Parameters

    • validUntil: Slot

      The slot until which the transaction is valid.

    Returns TxBuilder

    The instance of this TxBuilder for chaining.

    Throws

    If the time to live is already set.

toCbor

  • toCbor(): string

  • Prints the transaction cbor in its current state without trying to complete it

    Returns string

    The CBOR representation of the transaction

useCoinSelector

  • useCoinSelector(selector): TxBuilder

  • Sets a custom coin selector function for the transaction builder. This function will be used to select inputs during the transaction building process.

    Parameters

    • selector: ((inputs: TransactionUnspentOutput[], dearth: Value) => SelectionResult)

      The coin selector function to use.

        • (inputs, dearth): SelectionResult

        • Parameters

          • inputs: TransactionUnspentOutput[]
          • dearth: Value

          Returns SelectionResult

    Returns TxBuilder

    The same transaction builder

useEvaluator

  • useEvaluator(evaluator, override?): TxBuilder

  • Sets the evaluator for the transaction builder. The evaluator is used to execute Plutus scripts during transaction building.

    Parameters

    • evaluator: Core.Evaluator

      The evaluator to be used for script execution.

    • Optionaloverride: boolean

      Whether to override the evaluator if one is already set.

    Returns TxBuilder

    The same transaction builder

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods