TxBuilder

Appends transaction building steps to this builder.

This is the low-level method for adding steps. Prefer using the high-level methods like spend, payTo, mint, etc. unless you need direct step control.

Value parameters

s: the steps to append

Attributes

Attaches a datum to the transaction witness set.

Use this method when spending UTXOs that have datum hashes instead of inline datums. The datum hash is computed automatically and the datum is stored for inclusion in the witness set.

Value parameters

datum: the datum data to attach

Attributes

Builds and finalizes the transaction.

This method assembles the transaction from all the accumulated steps, calculates fees, handles change, validates and runs all Plutus scripts, and produces a ready-to-sign transaction.

Value parameters

diffHandler: the handler for managing transaction balance differences (change)

Attributes

Returns: a new TxBuilder with the finalized transaction
Throws: RuntimeException
if script execution fails or if the transaction cannot be balanced

Builds and finalizes the transaction, sending any remaining value to the specified change address.

This is a convenience method that uses the default change handling strategy. Any difference between inputs and outputs (minus fees) will be sent to the provided address as a new output.

Note: If changeTo was called, that output will receive the change instead of creating a new output at this address.

Value parameters

changeTo: the address to receive any remaining value (change)

Attributes

Returns: a new TxBuilder with the finalized transaction
Throws: RuntimeException
if script execution fails or if the transaction cannot be balanced

Specifies an output that will receive change during transaction balancing.

The output specifies the MINIMUM amount it must contain. During balancing, any excess ADA and tokens will be added to this output. The final output will always have at least the specified value, plus any change from the transaction.

This method can only be called once per transaction. If not called, a new change output will be created at the sponsor address during complete.

The change output must meet the minimum ADA requirement (minUTxO). If the transaction doesn't have enough excess to cover this minimum, additional UTXOs will be selected automatically.

Value parameters

output: the output that will receive change (specifies minimum amounts)

Attributes

Throws: IllegalArgumentException
if called more than once

Adds the specified utxos to the list of collateral inputs.

Collateral inputs are used to cover transaction fees if script execution fails. They are only consumed if a script fails validation.

Attributes

Adds the specified utxos to the list of collateral inputs.

Collateral inputs are used to cover transaction fees if script execution fails. They are only consumed if a script fails validation.

Attributes

Completes the transaction by selecting UTXOs, adding collateral, and balancing.

This method queries the reader for available UTXOs at the sponsor address, selects inputs to cover all outputs and fees, selects collateral if needed (for script transactions), and sets up change handling to the sponsor address.

This is the primary cross-platform method available on both JVM and JavaScript platforms.

On JVM, you can use the blocking overload with a timeout parameter, or use the await extension method:

import scalus.cardano.txbuilder.await
builder.complete(reader, sponsor).await(30.seconds)

Value parameters

reader: the async reader to query for UTXOs
sponsor: the address to use for input selection, collateral, and change

Attributes

Returns: a Future containing a new TxBuilder with the transaction completed

Completes the transaction using pre-fetched UTXOs.

This synchronous variant is useful when UTXOs are already available in memory, avoiding the need for async provider queries. Otherwise identical to the provider-based variant.

Value parameters

availableUtxos: the UTXOs available at the sponsor address for input/collateral selection
sponsor: the address to use for input selection, collateral, and change

Attributes

Returns: a new TxBuilder with the transaction completed

Delegates a stake key to the specified stake pool.

Attributes

Delegates a script-based stake key to the specified stake pool.

Use the factory methods to create the witness:

import TwoArgumentPlutusScriptWitness.*
builder.delegateTo(scriptStakeAddr, poolId, attached(script, redeemer))

Value parameters

poolId: the pool key hash to delegate to
stakeAddress: the script-based stake address to delegate
witness: the script witness authorizing the delegation

Attributes

Note: The stake address must have a script credential. Using a key-based credential with a script witness will cause validation errors.

Delegates to both a stake pool and a DRep.

Attributes

Delegates a script-based stake address to both a stake pool and a DRep.

Value parameters

drep: the DRep to delegate voting power to
poolId: the pool key hash to delegate to
stakeAddress: the script-based stake address
witness: the script witness authorizing the delegation

Attributes

Note: The stake address must have a script credential. Using a key-based credential with a script witness will cause validation errors.

Delegates voting power to a DRep.

Attributes

Delegates voting power from a script-based stake address to a DRep.

Value parameters

drep: the DRep to delegate voting power to
stakeAddress: the script-based stake address
witness: the script witness authorizing the delegation

Attributes

Note: The stake address must have a script credential. Using a key-based credential with a script witness will cause validation errors.

Deregisters a stake key from the network.

The refund amount is taken from protocol parameters (stakeAddressDeposit).

Attributes

Deregisters a stake key with an explicit refund amount.

Value parameters

refund: the amount originally deposited during registration (must match ledger state)

Attributes

Deregisters a script-based stake key from the network.

Use the factory methods to create the witness:

import TwoArgumentPlutusScriptWitness.*

// With attached Plutus script
builder.deregisterStake(scriptStakeAddr, attached(script, redeemer))

// With explicit refund amount
builder.deregisterStake(scriptStakeAddr, Some(Coin.ada(2)), attached(script, redeemer))

Value parameters

stakeAddress: the script-based stake address to deregister
witness: the script witness authorizing the deregistration

Attributes

Note: The stake address must have a script credential. Using a key-based credential with a script witness will cause validation errors.

Deregisters a script-based stake key from the network with explicit refund.

Value parameters

refund: optional refund amount (must match ledger state for explicit refund)
stakeAddress: the script-based stake address to deregister
witness: the script witness authorizing the deregistration

Attributes

Note: The stake address must have a script credential. Using a key-based credential with a script witness will cause validation errors.

Assembles the transaction without balancing or fee calculation.

This method builds a transaction from the accumulated steps but skips the finalization phase (fee calculation, change handling, script evaluation). Useful for:

Testing: Creating transactions for ScriptContext derivation
Inspection: Previewing transaction structure before committing to balancing
Advanced use cases: When manual control over balancing is needed

Attributes

Returns: the unbalanced transaction
Throws: TxBuilderException
if step processing fails

Adds transaction metadata (auxiliary data).

Metadata is optional data attached to a transaction that does not affect validation but can be used for off-chain purposes.

Value parameters

auxiliaryData: the auxiliary data to attach

Attributes

Sets a minimum fee for the transaction.

This overrides the automatically calculated fee. Use with caution; the actual fee may need to be higher to cover script execution costs.

Value parameters

minFee: the minimum fee in lovelace

Attributes

Mints or burns native tokens under a minting policy (reference script).

Use positive amounts to mint tokens and negative amounts to burn tokens. The minting policy script must be present as a reference input (via references) for this to work.

Type parameters

T: type of the redeemer (must have a ToData instance)

Value parameters

assets: map of asset names to amounts (positive for minting, negative for burning); zero amounts are silently ignored
policyId: the policy ID (script hash) of the minting policy
redeemer: redeemer to pass to the minting policy script

Attributes

Mints or burns native tokens with the script provided inline.

Use positive amounts to mint tokens and negative amounts to burn tokens.

Type parameters

T: type of the redeemer (must have a ToData instance)

Value parameters

assets: map of asset names to amounts (positive for minting, negative for burning); zero amounts are silently ignored
redeemer: redeemer to pass to the minting policy script
script: the minting policy script

Attributes

Mints or burns native tokens using a CompiledPlutus script.

The compiled script is used both for the on-chain script and registered as a debug script for diagnostic replay.

Value parameters

assets: map of asset names to amounts (positive for minting, negative for burning); zero amounts are silently ignored
compiled: compiled Plutus script (carries SIR for diagnostic replay)
redeemer: redeemer to pass to the minting policy script

Attributes

Mints or burns native tokens with a delayed redeemer using a CompiledPlutus script.

Value parameters

assets: map of asset names to amounts (positive for minting, negative for burning); zero amounts are silently ignored
compiled: compiled Plutus script (carries SIR for diagnostic replay)
redeemerBuilder: function that computes the redeemer from the assembled transaction

Attributes

Mints or burns native tokens with a delayed redeemer and attached script.

Use this method when the redeemer depends on the final transaction structure (e.g., for self-referential scripts). The redeemer is computed after the transaction is assembled but before script evaluation.

Value parameters

assets: map of asset names to amounts (positive for minting, negative for burning); zero amounts are silently ignored
redeemerBuilder: function that computes the redeemer from the assembled transaction
script: the minting policy script

Attributes

Mints or burns native tokens with a delayed redeemer computed from the built transaction.

Use this method when the redeemer depends on the final transaction structure (e.g., for self-referential scripts). The redeemer is computed after the transaction is assembled but before script evaluation.

The minting policy script must be present as a reference input (via references).

Value parameters

assets: map of asset names to amounts (positive for minting, negative for burning); zero amounts are silently ignored
policyId: the policy ID (script hash) of the minting policy
redeemerBuilder: function that computes the redeemer from the assembled transaction

Attributes

Mints or burns native tokens using a script witness.

This is the unified API for minting operations. Use the factory methods to create the witness:

// Plutus script with attached script (included in transaction)
import TwoArgumentPlutusScriptWitness.*
builder.mint(policyId, assets, attached(script, redeemer))

// Plutus script with reference script (must be in a reference input)
builder.references(scriptRefUtxo)
      .mint(policyId, assets, reference(redeemer))

// Plutus script with delayed redeemer (computed from final transaction)
builder.mint(policyId, assets, attached(script, tx => computeRedeemer(tx)))

// Native script
import NativeScriptWitness.*
builder.mint(policyId, assets, attached(nativeScript))

Value parameters

assets: map of asset names to amounts (positive to mint, negative to burn); zero amounts are silently ignored
policyId: the minting policy ID (script hash)
witness: the script witness authorizing the mint (NativeScriptWitness or TwoArgumentPlutusScriptWitness)

Attributes

Adds the specified output to the list of transaction outputs.

Use this method for fine-grained control over output construction. For simpler cases, use payTo.

Value parameters

output: the transaction output to add

Attributes

Sends the specified value to the given address without a datum.

Value parameters

address: recipient address
value: amount to send

Attributes

Sends the specified value to the given address with an inline datum.

Value parameters

address: recipient address
datum: inline datum to attach to the output
value: amount to send

Attributes

Sends the specified value to the given address with a datum hash.

Make sure to call attach with the corresponding datum data before calling build.

Value parameters

address: recipient address
datumHash: hash of the datum (the actual datum must be attached via attach)
value: amount to send

Attributes

Sends the specified value to the compiled script's address without a datum.

The address is derived from the compiled script's hash. The debug script is registered automatically, enabling diagnostic replay if a script at this address fails.

Value parameters

compiled: the compiled Plutus script
value: amount to send

Attributes

Sends the specified value to the compiled script's address with an inline datum.

The address is derived from the compiled script's hash. The debug script is registered automatically, enabling diagnostic replay if a script at this address fails.

Value parameters

compiled: the compiled Plutus script
datum: inline datum to attach to the output
value: amount to send

Attributes

Sends the specified value to the compiled script's address with a datum hash.

The address is derived from the compiled script's hash. The debug script is registered automatically, enabling diagnostic replay if a script at this address fails.

Make sure to call attach with the corresponding datum data before calling build.

Value parameters

compiled: the compiled Plutus script
datumHash: hash of the datum (the actual datum must be attached via attach)
value: amount to send

Attributes

Sends the specified value to an address with an inline datum based on the transaction.

Use this method when the datum depends on the final transaction structure. The datum is computed after the transaction is assembled but before script evaluation.

Value parameters

address: recipient address
datumBuilder: function from the final transaction to the inline datum
value: amount to send

Attributes

Sends the specified value to a compiled script's address with an inline datum based on the transaction.

Use this method when the datum depends on the final transaction structure. The datum is computed after the transaction is assembled but before script evaluation.

The address is derived from the compiled script's hash. The debug script is registered automatically, enabling diagnostic replay if a script at this address fails.

Value parameters

compiled: the compiled Plutus script
datumBuilder: function from the final transaction to the inline datum
value: amount to send

Attributes

Adds the specified utxos to the list of reference inputs.

Reference inputs allow scripts to read UTXOs without consuming them.

Attributes

Adds the specified utxo to the list of reference inputs and registers the compiled script for diagnostic replay.

Use this overload when the reference UTXO contains a script and you want diagnostic replay support. The compiled script is registered so that if the release script fails with empty logs, the evaluator can recompile from SIR with error traces.

Value parameters

compiled: the compiled Plutus script for diagnostic replay
utxo: the reference UTXO

Attributes

Registers stake address and delegates to both stake pool and DRep in one transaction.

The deposit amount is taken from protocol parameters (stakeAddressDeposit).

Attributes

Registers a script-based stake address and delegates to both stake pool and DRep.

The deposit amount is taken from protocol parameters (stakeAddressDeposit).

Value parameters

drep: the DRep to delegate voting power to
poolId: the pool key hash to delegate to
stakeAddress: the script-based stake address to register
witness: the script witness authorizing the registration and delegation

Attributes

Note: The stake address must have a script credential. Using a key-based credential with a script witness will cause validation errors.

Registers stake address and delegates voting power to a DRep in one transaction.

The deposit amount is taken from protocol parameters (stakeAddressDeposit).

Attributes

Registers a script-based stake address and delegates voting power to a DRep.

The deposit amount is taken from protocol parameters (stakeAddressDeposit).

Value parameters

drep: the DRep to delegate voting power to
stakeAddress: the script-based stake address to register
witness: the script witness authorizing the registration and delegation

Attributes

Note: The stake address must have a script credential. Using a key-based credential with a script witness will cause validation errors.

Registers as a DRep.

The deposit amount is taken from protocol parameters (dRepDeposit).

Attributes

Registers a script-based DRep.

The deposit amount is taken from protocol parameters (dRepDeposit). Post-Conway, script-based DRep registrations require authorization.

import TwoArgumentPlutusScriptWitness.*
builder.registerDRep(scriptCredential, Some(anchor), attached(script, redeemer))

Value parameters

anchor: optional metadata anchor for the DRep
drepCredential: the script-based DRep credential
witness: the script witness authorizing the registration

Attributes

Note: The credential must be a script credential (Credential.ScriptHash). Using a key-based credential with a script witness will cause validation errors.

Registers a stake key with the network.

The deposit amount is taken from protocol parameters (stakeAddressDeposit).

Attributes

Registers a script-based stake key with the network.

Post-Conway, script-based registrations require authorization. Use the factory methods to create the witness:

import TwoArgumentPlutusScriptWitness.*

// With attached Plutus script
builder.registerStake(scriptStakeAddr, attached(script, redeemer))

// With reference Plutus script
builder.references(scriptRefUtxo)
      .registerStake(scriptStakeAddr, reference(redeemer))

// With native script
import NativeScriptWitness.*
builder.registerStake(scriptStakeAddr, attached(nativeScript))

Value parameters

stakeAddress: the script-based stake address to register
witness: the script witness authorizing the registration

Attributes

Note: The stake address must have a script credential. Using a key-based credential with a script witness will cause validation errors.

Requires the given public key hash to sign the transaction.

Attributes

Requires multiple public key hashes to sign the transaction.

Attributes

Signs the transaction with the provided signer.

This method should be called after build to add signatures to the transaction. Multiple signers can be applied by chaining sign calls.

Value parameters

signer: the transaction signer

Attributes

Returns: a new TxBuilder with the signed transaction

Spends a UTXO with an explicit witness.

This is the most flexible spend method, allowing full control over the witness configuration. Use this when you need custom witness settings not covered by the convenience overloads.

Value parameters

utxo: the UTXO to spend
witness: the witness specifying how to authorize the spend (PubKeyWitness, NativeScriptWitness, or ThreeArgumentPlutusScriptWitness)

Attributes

Adds the specified pubkey utxo to the list of inputs, thus spending it.

If the sum of outputs exceeds the sum of spent inputs, the change is going to be handled according to the changeTo or diffHandler parameter of build.

Value parameters

utxo: utxo to spend

Attributes

Note: use spend with utxo and redeemer to spend script-protected utxos. Otherwise, build throws.

Adds the specified pubkey utxos to the list of inputs, thus spending them.

If the sum of outputs exceeds the sum of spent inputs, the change is going to be handled according to the changeTo or diffHandler parameter of build.

Value parameters

utxos: utxos to spend

Attributes

Note: use spend with utxo and redeemer to spend script-protected utxos. Otherwise, build throws.

Adds the specified script-protected utxo to the list of inputs and the specified redeemer to the witness set.

The script must be present as a reference input (via references) for this to work. If the script that protects the utxo fails with the specified redeemer, build is going to throw.

If the sum of outputs exceeds the sum of spent inputs, the change is going to be handled according to the changeTo or diffHandler parameter of build.

Value parameters

redeemer: redeemer to pass to the script to unlock the inputs
utxo: utxo to spend

Attributes

Adds the specified script-protected utxo with a delayed redeemer that is computed from the built transaction.

Use this method when the redeemer depends on the final transaction structure (e.g., for self-referential scripts). The redeemer is computed after the transaction is assembled but before script evaluation.

The script must be present as a reference input (via references) for this to work.

Value parameters

redeemerBuilder: function that computes the redeemer from the assembled transaction
utxo: utxo to spend

Attributes

Spends a script-protected UTXO with a delayed redeemer computed from the built transaction.

Use this method when the redeemer depends on the final transaction structure (e.g., for self-referential scripts that need to know input/output indices). The redeemer is computed after the transaction is assembled but before script evaluation.

Value parameters

redeemerBuilder: function that computes the redeemer from the assembled transaction
script: the Plutus script that protects the UTXO
utxo: the UTXO to spend

Attributes

Adds the specified script-protected utxo to the list of inputs and the specified redeemer to the witness set.

If the specified script fails with the specified redeemer, build is going to throw.

If the sum of outputs exceeds the sum of spent inputs, the change is going to be handled according to the changeTo or diffHandler parameter of build.

Value parameters

redeemer: redeemer to pass to the script to unlock the inputs
script: script that protects the utxo
utxo: utxo to spend

Attributes

Spends a script-protected UTXO using a CompiledPlutus script.

The compiled script is used both for the on-chain script (via .script) and registered as a debug script for diagnostic replay. If the script was compiled with Options.release (no traces) and fails, the evaluator will automatically recompile from SIR with error traces and replay to produce diagnostic logs.

Value parameters

compiled: compiled Plutus script (carries SIR for diagnostic replay)
redeemer: redeemer to pass to the script
utxo: the UTXO to spend

Attributes

Spends a script-protected UTXO with a delayed redeemer using a CompiledPlutus script.

Value parameters

compiled: compiled Plutus script (carries SIR for diagnostic replay)
redeemerBuilder: function that computes the redeemer from the assembled transaction
utxo: the UTXO to spend

Attributes

Registers a stake key and delegates to a stake pool in a single transaction.

The deposit amount is taken from protocol parameters (stakeAddressDeposit).

Attributes

Registers a script-based stake key and delegates to a stake pool.

The deposit amount is taken from protocol parameters (stakeAddressDeposit).

Value parameters

poolId: the pool key hash to delegate to
stakeAddress: the script-based stake address to register and delegate
witness: the script witness authorizing the registration and delegation

Attributes

Note: The stake address must have a script credential. Using a key-based credential with a script witness will cause validation errors.

Returns the current transaction.

Call this after build and optionally sign to get the final transaction ready for submission.

Attributes

Unregisters as a DRep.

Value parameters

refund: the amount originally deposited during registration (must match ledger state)

Attributes

Unregisters a script-based DRep.

Value parameters

drepCredential: the script-based DRep credential
refund: the amount originally deposited during registration (must match ledger state)
witness: the script witness authorizing the unregistration

Attributes

Note: The credential must be a script credential (Credential.ScriptHash). Using a key-based credential with a script witness will cause validation errors.

Updates DRep metadata anchor.

Attributes

Updates a script-based DRep metadata anchor.

Value parameters

anchor: optional new metadata anchor
drepCredential: the script-based DRep credential
witness: the script witness authorizing the update

Attributes

Note: The credential must be a script credential (Credential.ScriptHash). Using a key-based credential with a script witness will cause validation errors.

Sets the transaction validity interval using slot numbers.

The transaction is only valid for inclusion in a block within the specified slot range. This is important for time-sensitive contracts.

Value parameters

interval: the validity interval specifying the valid slot range

Attributes

Sets the earliest time from which the transaction is valid.

The timestamp is converted to a slot number using the environment's slot configuration.

Value parameters

from: the earliest valid time for the transaction

Attributes

Sets the latest time until which the transaction is valid.

The timestamp is converted to a slot number using the environment's slot configuration. The transaction becomes invalid after this time.

Value parameters

to: the latest valid time for the transaction (exclusive)

Attributes

Registers a debug script for diagnostic replay.

When a release script (compiled without error traces) fails during evaluation with empty logs, the evaluator will use the registered debug script to replay the failing evaluation, producing diagnostic logs.

This overload accepts a DebugScript directly, which can wrap either a pre-compiled debug scalus.cardano.ledger.PlutusScript (for external builders) or a lazy recompilation from CompiledPlutus.

Value parameters

debugScript: the debug script to use for replay
scriptHash: the script hash of the release script (used for lookup)

Attributes

Registers a compiled script for diagnostic replay.

When a release script (compiled without error traces) fails during evaluation with empty logs, the evaluator will use the registered compiled script to recompile from SIR with error traces and replay the failing evaluation, producing diagnostic logs.

This is automatically called by the spend, mint, payTo, and references overloads that accept CompiledPlutus. Use this method directly for other use cases where you want diagnostic replay.

'''Migration note:''' If you previously used validator.script (a PlutusScript) with spend or mint, pass validator (a CompiledPlutus) directly instead to enable automatic diagnostic replay.

Value parameters

compiled: the compiled Plutus script to register for diagnostic replay

Attributes

Withdraws staking rewards.

Attributes

Withdraws staking rewards from a script-based stake address.

Use the factory methods to create the witness:

import TwoArgumentPlutusScriptWitness.*
builder.withdrawRewards(scriptAddr, amount, attached(script, redeemer))
builder.withdrawRewards(scriptAddr, amount, reference(redeemer))

Value parameters

amount: withdrawal amount
stakeAddress: stake address to withdraw from (must have script credential)
witness: the script witness authorizing the withdrawal

TxBuilder

Value parameters

Attributes

Members list

Value members

Concrete methods

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Attributes

Attributes

Value parameters

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Value parameters

Attributes

Type parameters

Value parameters

Attributes

Type parameters

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes