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.

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

def appliedTxIndex: Map[TransactionHash, AppliedTx]

Index of applied transactions by hash, for O(1) lookup. Platform-specific state.

Index of applied transactions by hash, for O(1) lookup. Platform-specific state.

Attributes

def appliedTxLog: Vector[AppliedTx]

Ordered log of transactions applied to this emulator, in submission order (oldest first).

Ordered log of transactions applied to this emulator, in submission order (oldest first).

Unlike appliedTxs (hashes only), each entry retains the full transaction together with the slot it was applied at and the inputs it consumed (resolved against the pre-application UTxO set). This lets callers reconstruct chain history — e.g. walk the continuing outputs of an asset — without keeping their own submitted-transaction bookkeeping.

Ordering reflects submission order; under concurrent submission it is best-effort — the underlying ledger state transition is serialized, but the log append that follows it is not.

Attributes

def appliedTxs: Set[TransactionHash]

Hashes of all applied transactions. Held as a materialized set (kept in sync with appliedTxIndex by the platform implementations) so access is a plain O(1) field read rather than a per-call key-set view.

Hashes of all applied transactions. Held as a materialized set (kept in sync with appliedTxIndex by the platform implementations) so access is a plain O(1) field read rather than a per-call key-set view.

Attributes

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

def datums: Map[DataHash, Data]
final def setSlot(slot: SlotNo): Unit
final def submitSync(transaction: Transaction): Either[SubmitError, TransactionHash]
final 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

def utxos: Utxos

Inherited methods

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 checkTransaction(txHash: TransactionHash): Future[TransactionStatus]

Check the status of a transaction on the blockchain.

Check the status of a transaction on the blockchain.

Default implementation checks for UTxOs from the transaction. For emulators without a mempool concept, this returns either Confirmed or NotFound.

Attributes

Inherited from:
BlockchainReader
def currentSlot: Future[SlotNo]

Returns the current slot number.

Returns the current slot number.

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

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 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 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 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)

Concrete fields

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