docs
API
Generated with
docs/scalus/scalus.cardano/scalus.cardano.txbuilder

scalus.cardano.txbuilder

package scalus.cardano.txbuilder

Members list

Type members

Classlikes

object Change

Utilities for handling change outputs in transaction balancing.

Utilities for handling change outputs in transaction balancing.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
Change.type
sealed trait Datum

Datums in UTxOs can be stored in two forms: inline datums or datum hashes. When there's a hash, we need to provide a datum corresponding to this hash, which can be done by either providing the value literally, or using a reference input where it is stored inline. The latter is not supported, since we haven't seen it in the wild - you can work with the datum of a reference/other input directly. Please open an issue if you need it.

Datums in UTxOs can be stored in two forms: inline datums or datum hashes. When there's a hash, we need to provide a datum corresponding to this hash, which can be done by either providing the value literally, or using a reference input where it is stored inline. The latter is not supported, since we haven't seen it in the wild - you can work with the datum of a reference/other input directly. Please open an issue if you need it.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object DatumInlined
class DatumValue
object Datum

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
Datum.type
case class DelayedDatumSpec(outputIndex: Int, datumBuilder: Transaction => Data, step: TransactionBuilderStep)

Inline datum whose value is computed from the final transaction.

Inline datum whose value is computed from the final transaction.

Registered when TransactionBuilderStep.SendWithDatumBuilder is processed. After all steps are processed, replaceDelayedDatums invokes the builder and patches the placeholder output at outputIndex.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class DelayedRedeemerSpec(purpose: RedeemerPurpose, redeemerBuilder: Transaction => Data, step: TransactionBuilderStep)

Redeemer whose value is computed from the final transaction.

Redeemer whose value is computed from the final transaction.

Registered when a spend/mint step receives a Transaction => Data builder. After all steps are processed, replaceDelayedRedeemers invokes the builder with the sorted Transaction and patches the placeholder.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class DetachedRedeemer(datum: Data, purpose: RedeemerPurpose)

Redeemer that was detached from a transaction. Contains just enough info for it to be re-attached again, if a transaction needs a redeemer for some action.

Redeemer that was detached from a transaction. Contains just enough info for it to be re-attached again, if a transaction needs a redeemer for some action.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class EditableTransaction(transaction: Transaction, redeemers: Vector[DetachedRedeemer])

A transaction with redeemers detached.

A transaction with redeemers detached.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class NativeScriptWitness(scriptSource: ScriptSource[Native]) extends SpendWitness

Witnesses for native scripts.

Witnesses for native scripts.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait SpendWitness
trait Witness
class Object
trait Matchable
class Any
Show all
object NativeScriptWitness

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
case object PubKeyWitness extends SpendWitness

Use this value to indicate there will be a signature. The corresponding verification key hash will be tracked automatically in the context.

Use this value to indicate there will be a signature. The corresponding verification key hash will be tracked automatically in the context.

Attributes

Supertypes
trait Singleton
trait Product
trait Mirror
trait Serializable
trait Product
trait Equals
trait SpendWitness
trait Witness
class Object
trait Matchable
class Any
Show all
Self type
case class RedeemerIndexingInternalError(detachedRedeemer: DetachedRedeemer, steps: Seq[TransactionBuilderStep])

Internal error indicating a redeemer could not be attached to any transaction component.

Internal error indicating a redeemer could not be attached to any transaction component.

This error occurs when a detached redeemer's purpose does not match any input, mint, withdrawal, certificate, vote, or proposal in the transaction. This typically indicates an internal inconsistency in the transaction builder - a redeemer was tracked but its corresponding transaction component was removed or never added.

Value parameters

detachedRedeemer

the redeemer that could not be attached, containing its data and purpose

steps

the sequence of transaction builder steps that were processed

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object RedeemerManagement

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
sealed trait RedeemerPurpose

Contains a value that a redeemer corresponds to. Allows finding a redeemer index, given a transaction contains the value.

Contains a value that a redeemer corresponds to. Allows finding a redeemer index, given a transaction contains the value.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class ForCert
class ForMint
class ForPropose
class ForReward
class ForSpend
class ForVote
Show all
object RedeemerPurpose

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
enum ResolvedTxInput

Attributes

Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
sealed trait ScriptSource[+A <: Script]

Specifies how the transaction should find the source code for the script.

Specifies how the transaction should find the source code for the script.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object ScriptSource

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
enum SomeBuildError

These are the sum type for any errors that may occur during different phases and that can be returned thrown by a higher-level TxBuilder

These are the sum type for any errors that may occur during different phases and that can be returned thrown by a higher-level TxBuilder

Attributes

Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
trait SpendWitness extends Witness

Attributes

Supertypes
trait Witness
class Object
trait Matchable
class Any
Known subtypes
object PubKeyWitness
sealed trait StepError

Base trait for errors that occur during transaction building step processing.

Base trait for errors that occur during transaction building step processing.

Each error captures the specific TransactionBuilderStep that caused the failure, allowing users to identify which operation in their transaction building sequence failed. The explain method provides a human-readable description of the error.

Attributes

See also

TransactionBuilder.build for the main entry point that may return these errors

SomeBuildError.SomeStepError for how step errors are wrapped in the build result

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
Show all
object StepError

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
StepError.type
case class ThreeArgumentPlutusScriptWitness(scriptSource: ScriptSource[PlutusScript], redeemerBuilder: Transaction => Data, datum: Datum) extends SpendWitness

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait SpendWitness
trait Witness
class Object
trait Matchable
class Any
Show all
object ThreeArgumentPlutusScriptWitness

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
object TransactionBuilder

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
sealed trait TransactionBuilderStep

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Fee
class Mint
class Send
class Spend
Show all
object TransactionBuilderStep

Steps to build the transaction:

Steps to build the transaction:

  • generally non-commutative, so the order matters
  • some are additive (e.g. Mint), some are not, e.g., (Spend)

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
object TransactionConversion

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
object TransactionEditor

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
class TransactionSigner(keys: Set[KeyPair])

JVM TransactionSigner that uses JvmEd25519Signer directly.

JVM TransactionSigner that uses JvmEd25519Signer directly.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
object TransactionSigner

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
case class TwoArgumentPlutusScriptWitness(scriptSource: ScriptSource[PlutusScript], redeemerBuilder: Transaction => Data) extends Witness

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait Witness
class Object
trait Matchable
class Any
Show all
object TwoArgumentPlutusScriptWitness

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
enum TxBalancingError

Transaction balancing error types.

Transaction balancing error types.

These errors can occur during the transaction balancing process, which iteratively adjusts fees and change outputs until the transaction is balanced (consumed == produced).

Attributes

Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class TxBuilder(env: CardanoInfo, context: Context, evaluator: PlutusScriptEvaluator, steps: Seq[TransactionBuilderStep] = ..., attachedData: Map[DataHash, Data] = ..., changeOutputIndex: Option[Int] = ..., debugScripts: Map[ScriptHash, DebugScript] = ...)

A high-level, fluent API for building Cardano transactions.

A high-level, fluent API for building Cardano transactions.

TxBuilder provides a convenient way to construct transactions by chaining method calls. It handles input selection, output creation, script attachment, minting, and transaction finalization including fee calculation and change handling.

TxBuilder is purely functional; each method returns a new instance with the updated state. The complete method is the only one that performs effects (querying UTXOs from a provider).

==Platform Support==

TxBuilder supports both JVM and JavaScript platforms:

  • complete(provider, sponsor): Returns Future[TxBuilder]. Available on all platforms.
  • complete(provider, sponsor, timeout): JVM-only blocking version with timeout parameter.

On JVM, you can also use the await extension method on Future:

import scalus.cardano.txbuilder.await
builder.complete(provider, sponsor).await()

==Usage==

// Cross-platform - async (returns Future)
val txFuture = TxBuilder(env)
 .payTo(recipientAddress, Value.ada(10))
 .complete(provider, sponsorAddress)
 .map(_.sign(signer).transaction)

// JVM-only - blocking with timeout
import scala.concurrent.duration.*
val tx = TxBuilder(env)
 .payTo(recipientAddress, Value.ada(10))
 .complete(provider, sponsorAddress, 30.seconds)
 .sign(signer)
 .transaction

Value parameters

attachedData

datum values to be included in the transaction witness set

changeOutputIndex

index of the explicit change output (set by changeTo), or None for implicit change

context

the current transaction builder context

env

the environment containing protocol parameters, network info, and slot configuration

evaluator

the Plutus script evaluator used for script validation

steps

accumulated transaction building steps

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object TxBuilder

Factory methods for creating TxBuilder instances.

Factory methods for creating TxBuilder instances.

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
TxBuilder.type
sealed abstract class TxBuilderException(message: String, cause: Throwable = ...) extends RuntimeException

Base exception for all TxBuilder errors.

Base exception for all TxBuilder errors.

This sealed hierarchy provides typed exceptions for different failure modes in TxBuilder, enabling programmatic error handling while remaining backwards compatible with RuntimeException.

Attributes

Companion
object
Supertypes
class RuntimeException
class Exception
class Throwable
trait Serializable
class Object
trait Matchable
class Any
Show all
Known subtypes
Show all
object TxBuilderException

Attributes

Companion
class
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
sealed trait Witness

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
trait SpendWitness
object PubKeyWitness
enum WitnessKind

A witness to conduct an authorized operation on-chain. This could be spending an input, minting, rewarding, governance ops, certificate ops, etc.

A witness to conduct an authorized operation on-chain. This could be spending an input, minting, rewarding, governance ops, certificate ops, etc.

The only ways to do this as of writing (2025-10-03) are

  • PubKey
  • Native Script
  • Plutus Script

The types include all additional data required to authorize the operation.

Attributes

Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all

Deprecated classlikes

case class ExpectedSigner(hash: AddrKeyHash)

Tracks a pubkey hash expected to sign the transaction, used for fee estimation.

Tracks a pubkey hash expected to sign the transaction, used for fee estimation.

To add on-chain required signers, use TransactionBuilderStep.RequireSignature instead.

Attributes

Deprecated
[Since version 0.15.1] Use TxBuilder.requireSignature() instead
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all

Types

type ScriptWitness = NativeScriptWitness | TwoArgumentPlutusScriptWitness

Witness type for minting, certificates, withdrawals, and voting operations.

Witness type for minting, certificates, withdrawals, and voting operations.

Supports both native scripts and Plutus scripts. Use the factory methods on the companion objects to create witnesses:

import TwoArgumentPlutusScriptWitness.*
val plutusWitness = attached(script, redeemer)
val refWitness = reference(redeemer)

import NativeScriptWitness.*
val nativeWitness = attached(nativeScript)

Attributes

Value members

Concrete methods

def addDummySignatures(numberOfKeys: Int, tx: Transaction): Transaction

add at most 256 keys

add at most 256 keys

Attributes

def appendDistinct[A](elem: A, seq: Seq[A]): Seq[A]

Append an element to a sequence, returning distinct values only and preserving the order of elements.

Append an element to a sequence, returning distinct values only and preserving the order of elements.

Attributes

def keepRawL[A : Encoder](): Lens[KeepRaw[A], A]
def removeDummySignatures(numberOfKeys: Int, tx: Transaction): Transaction

remove at most 256 keys, must be used in conjunction with addDummyVKeys

remove at most 256 keys, must be used in conjunction with addDummyVKeys

Attributes

def txBuilder(using env: CardanoInfo): TxBuilder

Creates a TxBuilder using a context CardanoInfo.

Creates a TxBuilder using a context CardanoInfo.

Example:

given CardanoInfo = CardanoInfo.mainnet
val builder = txBuilder  // Uses the given CardanoInfo

Attributes

def txOutputsL: Lens[Transaction, IndexedSeq[Sized[TransactionOutput]]]
def txRedeemersL: Lens[Transaction, Option[KeepRaw[Redeemers]]]

Extensions

Extensions

extension [S, A, B](lens: Lens[S, A])
def >>>[C](other: Lens[A, C]): Lens[S, C]
Generated with