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 DelayedRedeemerSpec(purpose: RedeemerPurpose, redeemerBuilder: Transaction => Data, step: TransactionBuilderStep)

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 ExpectedSigner(hash: AddrKeyHash)

An scalus.cardano.ledger.AddrKeyHash that is expected to sign some scalus.cardano.ledger.Transaction.

An scalus.cardano.ledger.AddrKeyHash that is expected to sign some scalus.cardano.ledger.Transaction.

The purpose for signing is not presently tracked. For a sketch, see commit https://github.com/cardano-hydrozoa/hydrozoa/commit/1a8c9c73fbfb33e79456a0a8b9f08688ef39b749

Attributes

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

Witnesses for native scripts. Can appear several times, but with the same additionalSigners.

Witnesses for native scripts. Can appear several times, but with the same additionalSigners.

Attributes

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

Attributes

Supertypes
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
object RedeemersContext

Attributes

Companion
class
Supertypes
trait Product
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, additionalSigners: Set[ExpectedSigner]) 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, additionalSigners: Set[ExpectedSigner]) 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] = ..., validators: Seq[Validator] = ...)

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

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

validators

ledger rules to run against the built transaction for additional validations

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 BuilderContext(env: CardanoInfo, wallet: Wallet, evaluator: PlutusScriptEvaluator)

Attributes

Companion
object
Deprecated
[Since version 0.13.0] Will be removed
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object BuilderContext

Attributes

Companion
class
Deprecated
[Since version 0.13.0] Will be removed
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
class ChangeOutputDiffHandler(protocolParams: ProtocolParams, changeOutputIdx: Int)

Helper class that creates a diff handler function for an existing change output.

Helper class that creates a diff handler function for an existing change output.

Attributes

Deprecated
[Since version 0.13.0] Use Change.changeOutputDiffHandler instead

Use Change.changeOutputDiffHandler instead

Supertypes
class Object
trait Matchable
class Any
Known subtypes
object Environment

Attributes

Deprecated
[Since version 0.13.0] Use CardanoInfo directly instead
Supertypes
class Object
trait Matchable
class Any
Self type
object LowLevelTxBuilder

Attributes

Deprecated
[Since version scalus 0.13.0] Use TransactionBuilder methods instead

This object is deprecated. Use the functions and types from their new locations:

  • balanceFeeAndChange and balanceFeeAndChangeWithTokens are now in TransactionBuilder object
  • TxBalancingError is now in its own file scalus.cardano.txbuilder.TxBalancingError
  • modifyBody, modifyWs, setFee, calculateChangeValue are now in TransactionBuilder object
  • withValue extension is now in TransactionOutput companion object in scalus.cardano.ledger
Supertypes
class Object
trait Matchable
class Any
Self type
object RedeemerPurposeUtils

Attributes

Deprecated
[Since version 0.13.0] use RedeemerPurpose instead
Supertypes
class Object
trait Matchable
class Any
Self type
case class RedeemersContext(inputs: Vector[TransactionInput] = ..., mintingPolicyHashes: Vector[ScriptHash] = ..., rewardAddresses: Vector[RewardAccount] = ..., certs: Vector[Certificate] = ..., proposals: Vector[ProposalProcedure] = ..., voters: Vector[Voter] = ...)

Contains parts of a transaction that are needed for redeemer processing.

Contains parts of a transaction that are needed for redeemer processing.

Attributes

Companion
object
Deprecated
[Since version 0.13.0] Use Transaction-based methods directly
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class StakeCredential(credential: Credential)

Attributes

Deprecated
[Since version 0.13.0] Use Credential instead
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
trait Wallet

Owns a set of pubkey-controlled UTXOs.

Owns a set of pubkey-controlled UTXOs.

Attributes

Companion
object
Deprecated
[Since version 0.13.0] Will be removed
Supertypes
class Object
trait Matchable
class Any
object Wallet

Attributes

Companion
trait
Deprecated
[Since version 0.13.0] Will be removed
Supertypes
class Object
trait Matchable
class Any
Self type
Wallet.type

Types

Deprecated types

type Environment = CardanoInfo

Attributes

Deprecated
[Since version 0.13.0] Use CardanoInfo directly instead
type TransactionUnspentOutput = Utxo

Attributes

Deprecated
[Since version 0.13.0] Use scalus.cardano.ledger.Utxo instead

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 txOutputsL: Lens[Transaction, IndexedSeq[Sized[TransactionOutput]]]
def txRedeemersL: Lens[Transaction, Option[KeepRaw[Redeemers]]]

Deprecated methods

def calculateChangeValue(tx: Transaction, utxo: Utxos, params: ProtocolParams): Value

Attributes

Deprecated
[Since version scalus 0.13.0] Use TransactionBuilder.calculateChangeValue instead
def modifyBody(tx: Transaction, f: TransactionBody => TransactionBody): Transaction

Attributes

Deprecated
[Since version scalus 0.13.0] Use TransactionBuilder.modifyBody instead
def modifyWs(tx: Transaction, f: TransactionWitnessSet => TransactionWitnessSet): Transaction

Attributes

Deprecated
[Since version scalus 0.13.0] Use TransactionBuilder.modifyWs instead
def setFee(amount: Coin)(tx: Transaction): Transaction

Attributes

Deprecated
[Since version scalus 0.13.0] Use TransactionBuilder.setFee instead

Deprecated fields

val TransactionUnspentOutput: Utxo.type

Attributes

Deprecated
[Since version 0.13.0] Use scalus.cardano.ledger.Utxo instead

Extensions

Extensions

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

Deprecated extensions

extension (network: Network)
def toNetworkId: Int

Attributes

Deprecated
[Since version 0.13.0] Use Network.networkId instead
Generated with