docs
API
Generated with
docs/scalus/scalus.cardano/scalus.cardano.node/Emulator

Emulator

scalus.cardano.node.Emulator
See theEmulator companion object
class Emulator(initialUtxos: Utxos = ..., initialContext: Context = ..., val validators: Iterable[Validator] = ..., val mutators: Iterable[Mutator] = ..., initialCertState: CertState = ..., initialDatums: Map[DataHash, Data] = ..., initialAppliedTxLog: Vector[AppliedTx] = ...) extends EmulatorBase

An in-memory bare-bones node implementation (JVM version with thread-safe state).

Allows submitting transaction and querying UTxO state. Runs validators and mutators against all submitted transactions. The default validator and mutator lists reflect the Cardano Node UTxO related ledger rules.

The rules themselves live in EmulatorBase, shared with the JavaScript emulator; all this class adds is the state cell and the compare-and-set retry that makes concurrent submission safe.

Attributes

See also

scalus.cardano.ledger.rules for the ledger rules

Companion
object
Graph
Supertypes
trait InteropApi
trait EmulatorBase
trait BlockchainProviderTF[Future]
trait BlockchainReaderTF[Future]
class Object
trait Matchable
class Any
Show all

Members list

Value members

Concrete methods

override def appliedTxLog: Vector[AppliedTx]

Narrowed to Vector — the type this class has always returned.

Narrowed to Vector — the type this class has always returned.

Attributes

Definition Classes

Inherited methods

def addUtxo(input: TransactionInput, output: TransactionOutput): Unit

Adds a UTxO to the ledger directly, bypassing transaction validation. Overwrites any UTxO already sitting at the same input.

Adds a UTxO to the ledger directly, bypassing transaction validation. Overwrites any UTxO already sitting at the same input.

An inline datum on output joins the datum store, so getDatum answers for a script UTxO seeded this way exactly as it does for one produced by a transaction.

Attributes

Inherited from:
EmulatorBase
def appliedTxIndex: Map[TransactionHash, AppliedTx]

Index of applied transactions by hash, for O(1) lookup.

Index of applied transactions by hash, for O(1) lookup.

Attributes

Inherited from:
EmulatorBase
def appliedTxs: Set[TransactionHash]

Hashes of all applied transactions. Held as a materialized set (derived from appliedTxLog by EmulatorState, so it cannot drift) rather than a per-call key-set view, so access is a plain O(1) field read.

Hashes of all applied transactions. Held as a materialized set (derived from appliedTxLog by EmulatorState, so it cannot drift) rather than a per-call key-set view, so access is a plain O(1) field read.

Attributes

Inherited from:
EmulatorBase
override def cardanoInfo: CardanoInfo

Returns CardanoInfo for this reader.

Returns CardanoInfo for this reader.

This is always available synchronously after the reader is constructed. For emulators, this returns the current context. For remote providers like BlockfrostProvider, the CardanoInfo is fetched during async construction.

Attributes

Definition Classes
Inherited from:
EmulatorBase
def certState: CertState

Attributes

Inherited from:
EmulatorBase
override def checkTransaction(txHash: TransactionHash): Future[TransactionStatus]

Whether this emulator has applied the transaction.

Whether this emulator has applied the transaction.

Authoritative, unlike the inherited default, which infers status from the UTxOs a transaction produced: findUtxos here answers Right(empty) for a transaction it has never seen, and an emulator that has applied a transaction whose outputs are all since spent produces none either. The applied-transaction index knows the answer outright.

Attributes

Definition Classes
Inherited from:
EmulatorBase
def clearAppliedTxs(): Unit

Clear the applied-transaction bookkeeping (appliedTxLog and appliedTxIndex), leaving the ledger state (utxos, certState, datums) untouched.

Clear the applied-transaction bookkeeping (appliedTxLog and appliedTxIndex), leaving the ledger state (utxos, certState, datums) untouched.

Attributes

Inherited from:
EmulatorBase
def currentSlot: Future[SlotNo]

Returns the current slot number.

Returns the current slot number.

Attributes

Inherited from:
EmulatorBase
def currentSlotSync: SlotNo

The current slot, without the Future wrapper.

The current slot, without the Future wrapper.

An emulator's slot is in-memory state, so the effectful accessor above is a formality imposed by the BlockchainReader interface. Streaming needs the value synchronously while building a chain point, where handing back an already-completed Future and unwrapping it would be pure ceremony.

Attributes

Inherited from:
EmulatorBase
def datums: Map[DataHash, Data]

Attributes

Inherited from:
EmulatorBase
def evaluatorMode: EvaluatorMode

Evaluator mode the emulator runs Plutus scripts in (e.g. Validate vs EvaluateAndComputeCost). Exposed so snapshots such as ImmutableEmulator.fromEmulator can preserve it rather than silently reverting to the Context default.

Evaluator mode the emulator runs Plutus scripts in (e.g. Validate vs EvaluateAndComputeCost). Exposed so snapshots such as ImmutableEmulator.fromEmulator can preserve it rather than silently reverting to the Context default.

Attributes

Inherited from:
EmulatorBase
override def executionContext: ExecutionContext

Emulator uses parasitic EC since all operations are synchronous.

Emulator uses parasitic EC since all operations are synchronous.

Attributes

Definition Classes
Inherited from:
EmulatorBase
def fetchLatestParams: Future[ProtocolParams]

Fetches the latest protocol parameters from the network.

Fetches the latest protocol parameters from the network.

Attributes

Inherited from:
EmulatorBase
def findUtxo(input: TransactionInput): Future[Either[UtxoQueryError, Utxo]]

Find a single UTxO by its transaction input.

Find a single UTxO by its transaction input.

Attributes

Returns

Right(utxo) if found, Left(NotFound) otherwise

Inherited from:
BlockchainReaderTF
override def findUtxos(query: UtxoQuery): Future[Either[UtxoQueryError, Utxos]]

Find UTxOs using a type-safe query.

Find UTxOs using a type-safe query.

Value parameters

query

The query specifying source, filters, and pagination

Attributes

Returns

Either a UtxoQueryError or the matching UTxOs

Definition Classes
Inherited from:
EmulatorBase
def findUtxos(address: Address): Future[Either[UtxoQueryError, Utxos]]

Find all UTxOs at the given address.

Find all UTxOs at the given address.

Attributes

Inherited from:
BlockchainReaderTF
def findUtxos(inputs: Set[TransactionInput]): Future[Either[UtxoQueryError, Utxos]]

Find UTxOs by a set of transaction inputs (fails with NotFound if not all are found).

Find UTxOs by a set of transaction inputs (fails with NotFound if not all are found).

Attributes

Inherited from:
BlockchainReaderTF
final def findUtxosForAddress(address: Address): List[Utxo]

All UTxOs at the given address as a Java list.

All UTxOs at the given address as a Java list.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
final def findUtxosForAddressAsync(address: Address): CompletableFuture[List[Utxo]]

CompletableFuture variant of findUtxosForAddress.

CompletableFuture variant of findUtxosForAddress.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
final def findUtxosForInputs(inputs: Set[TransactionInput]): List[Utxo]

The UTxOs among inputs that are unspent, as a Java list.

The UTxOs among inputs that are unspent, as a Java list.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
def findUtxosSync(query: UtxoQuery): Utxos

findUtxos without the Future. The emulator's state is in memory and its query evaluation is pure, so the effect wrapper is an interface formality — JavaScript and Java callers both want the value.

findUtxos without the Future. The emulator's state is in memory and its query evaluation is pure, so the effect wrapper is an interface formality — JavaScript and Java callers both want the value.

Attributes

Inherited from:
EmulatorBase
def getAppliedTx(txHash: TransactionHash): Option[AppliedTx]

Look up the full applied-tx record (transaction + slot + spent inputs) by hash.

Look up the full applied-tx record (transaction + slot + spent inputs) by hash.

Attributes

Inherited from:
EmulatorBase
final def getAppliedTxHashes: Set[TransactionHash]

Hashes of all applied transactions as a Java set.

Hashes of all applied transactions as a Java set.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
final def getAppliedTxLog: List[AppliedTx]

The applied-transaction log as a Java list (oldest first).

The applied-transaction log as a Java list (oldest first).

Attributes

Inherited from:
EmulatorJavaApi (hidden)
final def getAppliedTxOrNull(txHash: TransactionHash): AppliedTx

The applied-transaction record with the given hash, or null if unknown.

The applied-transaction record with the given hash, or null if unknown.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
final def getCurrentSlot: Long

The current slot number.

The current slot number.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
def getDatum(datumHash: DataHash): Future[Option[Data]]

Look up a datum by its hash. Returns None if unknown.

Look up a datum by its hash. Returns None if unknown.

Attributes

Inherited from:
EmulatorBase
final def getDatumOrNull(datumHash: DataHash): Data

The datum with the given hash, or null if unknown.

The datum with the given hash, or null if unknown.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
final def getDatums: Map[DataHash, Data]

All known datums by hash as a Java map.

All known datums by hash as a Java map.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
def getDelegation(credential: Credential): DelegationInfo

Attributes

Inherited from:
EmulatorBase
final def getProtocolParams: ProtocolParams

The protocol parameters the emulator validates against.

The protocol parameters the emulator validates against.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
def getTransaction(txHash: TransactionHash): Option[Transaction]

Look up a previously applied transaction by hash, or None if it was never applied.

Look up a previously applied transaction by hash, or None if it was never applied.

Attributes

Inherited from:
EmulatorBase
final def getTransactionOrNull(txHash: TransactionHash): Transaction

The applied transaction with the given hash, or null if unknown.

The applied transaction with the given hash, or null if unknown.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
final def getUtxos: Map[TransactionInput, TransactionOutput]

The current UTxO set as a Java map.

The current UTxO set as a Java map.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
def hasTx(txHash: TransactionHash): Boolean

Attributes

Inherited from:
EmulatorBase
override protected def mapF[A, B](fa: Future[A])(f: A => B): Future[B]

Map over the Future effect using this reader's captured ExecutionContext.

Map over the Future effect using this reader's captured ExecutionContext.

Attributes

Definition Classes
Inherited from:
BlockchainReader
def pollForConfirmation(txHash: TransactionHash, maxAttempts: Int = ..., delayMs: Long = ...): Future[TransactionStatus]

Poll for transaction confirmation.

Poll for transaction confirmation.

Default implementation for emulators: a single check is sufficient since confirmation is instant.

Attributes

Inherited from:
BlockchainProvider
inline def queryUtxos(inline f: Utxo => Boolean): UtxoQueryWithReaderTF[Future]

Query UTxOs using a lambda DSL.

Query UTxOs using a lambda DSL.

Translates the lambda to a UtxoQuery at compile time and returns a builder that can be further configured before execution. Effect-polymorphic — the resulting .execute() returns the reader's own F[Either[UtxoQueryError, Utxos]], so the same call shape works on Future-typed providers (Blockfrost, JS) and direct-style providers (ox Id).

Example:

// Simple query — execute immediately
reader.queryUtxos { u =>
 u.output.address == myAddress
}.execute()

// With pagination and minimum total
reader.queryUtxos { u =>
 u.output.address == myAddress && u.output.value.hasAsset(policyId, assetName)
}.minTotal(Coin.ada(100)).limit(10).execute()

Supported expressions:

  • u.output.address == addr — query by address
  • u.input.transactionId == txId — query by transaction
  • u.output.value.hasAsset(policyId, assetName) — query/filter by asset
  • u.output.value.coin >= amount — filter by minimum lovelace
  • u.output.hasDatumHash(hash) — filter by datum hash
  • && — AND combination
  • || — OR combination

Value parameters

f

Lambda expression from Utxo to Boolean

Attributes

Returns

A UtxoQueryWithReaderTF builder over this reader's effect type

Inherited from:
BlockchainReaderTF
def removeUtxo(input: TransactionInput): Unit

Removes a UTxO from the ledger directly, bypassing transaction validation. A no-op if no UTxO sits at that input.

Removes a UTxO from the ledger directly, bypassing transaction validation. A no-op if no UTxO sits at that input.

A datum the removed UTxO carried inline stays in the datum store: a node keeps answering for a datum it has seen after the output holding it is spent, and so does this.

Attributes

Inherited from:
EmulatorBase
def setSlot(slot: SlotNo): Unit

Attributes

Inherited from:
EmulatorBase
def snapshot(): Emulator

An independent emulator starting from this one's state, taken as a single read — the copy and the original share no mutable cell and evolve separately from here on.

An independent emulator starting from this one's state, taken as a single read — the copy and the original share no mutable cell and evolve separately from here on.

Attributes

Inherited from:
EmulatorBase
def stakeDistribution: Seq[StakeDistributionEntry]

Live stake per registered stake credential: the lovelace sitting at addresses delegating to it, plus its reward balance, and the pool it delegates to.

Live stake per registered stake credential: the lovelace sitting at addresses delegating to it, plus its reward balance, and the pool it delegates to.

This is the emulator's answer to "who controls how much stake", the query a governance or delegation test needs. It is not a reward calculation: nothing is paid out.

Pointer addresses are ignored — they are deprecated and carry no stake here.

Reads the state cell once, the way snapshot does. Two reads would let a submission land between them on the JVM, producing a row whose stake came from the post-transaction UTxO set and whose rewards came from the pre-transaction certificate state.

Attributes

Inherited from:
EmulatorBase
def submit(transaction: Transaction, debugScripts: Map[ScriptHash, DebugScript]): Future[Either[SubmitError, TransactionHash]]

Submit a transaction with debug scripts for diagnostic replay.

Submit a transaction with debug scripts for diagnostic replay.

When a release script fails with empty logs, the evaluator replays it using the debug script to produce diagnostic output.

Value parameters

debugScripts

map from release script hash to debug script for diagnostic replay

transaction

the transaction to submit

Attributes

Inherited from:
EmulatorBase
def submit(transaction: Transaction): Future[Either[SubmitError, TransactionHash]]

Submits a transaction to the network.

Submits a transaction to the network.

Attributes

Inherited from:
EmulatorBase
def submitAndPoll(transaction: Transaction, maxAttempts: Int = ..., delayMs: Long = ...): Future[Either[SubmitError, TransactionHash]]

Submit a transaction and poll until confirmed.

Submit a transaction and poll until confirmed.

Default implementation composes submit and pollForConfirmation.

Attributes

Inherited from:
BlockchainProvider
final def submitAsync(transaction: Transaction): CompletableFuture[SubmitResult]

CompletableFuture variant of trySubmit, for API-shape parity with asynchronous BlockchainProvider implementations.

CompletableFuture variant of trySubmit, for API-shape parity with asynchronous BlockchainProvider implementations.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
def submitSync(transaction: Transaction, debugScripts: Map[ScriptHash, DebugScript]): Either[SubmitError, TransactionHash]

Synchronously submit a transaction with debug scripts for diagnostic replay.

Synchronously submit a transaction with debug scripts for diagnostic replay.

Attributes

Inherited from:
EmulatorBase
def submitSync(transaction: Transaction): Either[SubmitError, TransactionHash]

Attributes

Inherited from:
EmulatorBase
def tick(n: Long): Unit

Attributes

Inherited from:
EmulatorBase
final def trySubmit(transaction: Transaction, debugScripts: Map[ScriptHash, DebugScript]): SubmitResult

Like trySubmit, evaluating failing scripts against the given debug scripts for diagnostics.

Like trySubmit, evaluating failing scripts against the given debug scripts for diagnostics.

Attributes

Inherited from:
EmulatorJavaApi (hidden)
final def trySubmit(transaction: Transaction): SubmitResult

Submits a transaction and reports the outcome as a SubmitResult (never throws for a rejected transaction).

Submits a transaction and reports the outcome as a SubmitResult (never throws for a rejected transaction).

Attributes

Inherited from:
EmulatorJavaApi (hidden)
def utxos: Utxos

Attributes

Inherited from:
EmulatorBase

Concrete fields

val mutators: Iterable[Mutator]
val validators: Iterable[Validator]
Generated with