Emulator

An emulator in the preset of chainConfig, spec [CF-1]. It has no default arguments: Scala allows them on one overload only, and Java and JavaScript cannot use them.

The 1.4 constructor, in the Instant preset, spec [CF-4]. It keeps its default arguments, so Scala callers can name only the fields they set.

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

addDatum for a datum without its original bytes: the store keeps its canonical CBOR.

Adds a datum to the datum store getDatum reads, with the bytes it is given, so a UTxO added with addUtxo that holds only the hash of its datum can have the datum found too. Adding a datum the store already holds changes nothing.

Pays amount into the reward balance of a registered account, as the epoch boundary pays rewards in the Haskell ledger. Nothing else changes: no deposit, no pot, no slot.

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.

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

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.

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.

Where the transaction stands, from txStatus: Pending and Confirmed map to themselves, every other status to NotFound, spec [TS-3], [TS-4]. A tx known only from the applied-tx log the emulator was built with has no block, so it is NotFound, as on a node.

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 epoch of the current slot, ledger-rules spec [ES-9].

Returns the current slot number.

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.

Every datum this emulator has seen, by hash, decoded. binaryDatums keeps the bytes.

The ChainSync events that take a follower from from to to, two tips of the block tree, spec section 12.1: one RollBackward to their common ancestor when from is not an ancestor of to, then one RollForward per block up to to, in height order. ChainTip.origin is genesis.

Experimental: ChainEvent, AppliedBlock and AppliedTransaction live in scalus.cardano.node.stream.internal, outside the binary-compatibility check, and may change in a minor release.

The donations of this epoch. The next epoch boundary moves them into treasury.

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.

Emulator uses parasitic EC since all operations are synchronous.

The fee pot: the fees of the applied transactions since the last epoch boundary, plus those of the epoch before it, which the next boundary takes out (deltaF, ledger-rules spec [RW-12]).

Fetches the latest protocol parameters from the network.

Find a single UTxO by its transaction input.

Find UTxOs using a type-safe query.

findUtxosSync with a view, in a Future, spec [VW-3].

Find all UTxOs at the given address.

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

All UTxOs at the given address in the ledger state view reads, spec [VW-3].

All UTxOs at the given address as a Java list.

CompletableFuture variant of findUtxosForAddress.

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

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.

The UTxOs that match query in the ledger state view reads, spec [VW-3].

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

Hashes of all applied transactions as a Java set.

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

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

The epoch of the current slot, ledger-rules spec [ES-9].

The current slot number.

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

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

All known datums by hash as a Java map.

diff as a Java list, spec section 12.1. Experimental, as diff is: the event types live in scalus.cardano.node.stream.internal and may change in a minor release.

The gov state: proposals in submission order with their votes, the committee and the constitution, spec [ES-9]. One proposal is getGovState.proposal(id), D35.

The cardano-ledger names of every ledger failure of transaction, in the ledger's order, for example ["BadInputsUTxO", "OutsideValidityIntervalUTxO"]; empty when the ledger rules accept it. A dry run: the state does not change. Ledger-rules spec [FL-8]; see ledgerFailures.

The whole ledger state in the shape of the node's NewEpochState, read from one state, ledger-rules spec D122; its Java getters are those of NewEpochStatePlatform, D128.

The pending txs, oldest first, as a Java list.

The ratify result the last epoch boundary computed, which the next boundary enacts, ledger-rules spec [ES-9b].

The reward update the next epoch boundary pays, or null before the first boundary, ledger-rules spec [ES-9a].

The protocol parameters the emulator validates against.

The reserves, ledger-rules spec [ES-9].

The stake snapshots and the fee snapshot of the last epoch boundary, ledger-rules spec [ES-9a].

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

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

The current UTxO set as a Java map.

The gov state: the proposals in the order they were submitted, with their votes, the enacted roots, the committee and the constitution, spec [ES-9]. One proposal is govState.proposal(id); one DRep state is certState.vstate.dreps(credential), D35.

Whether the tx is in appliedTxLog: in a block of the selected chain above the clearAppliedTxs cursor, or in the log the emulator was built with. A pending tx, in the Manual preset, reads false. txStatus reads the blocks only, so a tx of the imported log is NotFound there.

Every failure of transaction under the ledger rules of this emulator, as the ledger collects them, in the order of the ledger's interpreter, ledger-rules spec [FL-1], [FL-8]. Empty when the rules accept it. A dry run on the state that submitSync validates against: the state does not change.

submitSync reports one failure, which need not be the first of this list. TransactionException.ledgerNames names each failure with its cardano-ledger constructors.

It runs validators and mutators, not processTransaction: a subclass that overrides processTransaction to check other rules does not change this list.

The whole ledger state in the shape of the node's NewEpochState, read from one state, ledger-rules spec D122: the UTxO and cert state, the gov state, the account state, the stake snapshots, the reward update, the ratify result, the pparams and the pool distribution. Its fields equal the getters above; its treasury is treasury, spec [DM-13].

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

The pending txs, oldest first.

The ratify result the last epoch boundary computed, which the next boundary enacts, ledger-rules spec [ES-9b], [EB-10a], D94: the enacted ids in order, the expired ids, and the enact state after the run. At genesis it enacts nothing, spec [DM-9c]. What a boundary enacted shows after it in govState, the pparams and the balances.

RATIFY never accepts a HardForkInitiation to protocol version 12 or more, spec [EN-4a], D91: such an action delays nothing, and it expires with its deposit refunded.

The reward update the last epoch boundary computed from go, which the next boundary pays, ledger-rules spec [ES-9a], [RW-21]. None before the first boundary, spec [ES-8a].

Wait for the transaction to leave the mempool, without sleeping, spec [SF-2]: with AwaitTxPolicy.ProduceBlock, forge a block while it is Pending, at most maxAttempts blocks, spec [SF-3]; with AwaitTxPolicy.WaitOnly, report the status as it is, spec [SF-4]. delayMs is ignored: the emulator has virtual time.

Forge a block of txs at slot on on, a block anywhere in the block tree, or ChainPoint.origin for genesis, and return its point, spec section 8.2. It models a block from another pool: the txs come from the caller, not from the mempool, spec [FG-20].

The txs are applied in order to the ledger after on, spec [FG-15]. Then chain selection runs, spec [FG-19]: a branch longer than the selected chain becomes the selected chain, and the txs of the blocks it replaces follow the orphanTxs policy, spec section 11. On an error nothing changes, spec [FG-17].

Forge a block of txs on on, at slot on.slot + 1, spec [FG-11]. See the overload with a slot.

Forge a block from the mempool, and return its point, spec section 8.1.

In the Manual preset this is the only way a block appears: at slot max(current slot, tip slot + 1), with the longest prefix of the mempool that fits the block limits, after the current slot moves there and the mempool is revalidated, spec [FG-1], [FG-3], [FG-4]. An empty mempool forges an empty block, spec [FG-8].

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

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.

The reserves, ledger-rules spec [ES-9]. They start as EmulatorInitialState.reserves, the mainnet reserves by default, spec [ES-7].

Remove the last n blocks of the selected chain, and every block that descends from them, and return the tip after chain selection, spec section 11.3. The txs of the removed blocks follow the orphanTxs policy, and the current slot stays, spec [RB-6], [RB-7].

Move the current slot to slot, then revalidate the mempool, spec section 10. Each epoch boundary crossed costs one epoch transition, so a move across millions of epochs is slow.

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. The copy starts from the whole state, so it keeps the fees, the donations and the treasury, spec [SC-7c].

The stake snapshots mark, set and go and the fee snapshot, as of the last epoch boundary, ledger-rules spec [ES-9a]. The genesis fills all three from the initial state, spec [ES-8a].

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 the stake now, not a stake snapshot: snapshots holds the stake of the last epoch boundaries, which the rewards read. A row here may be for a credential that is not registered or delegates to no pool; a snapshot has no such row.

The coin is the ledger's instant stake, the one SNAP reads: pointer, enterprise and Byron addresses carry none.

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.

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.

Submits a transaction to the network.

Submit a transaction and poll until confirmed.

Default implementation composes submit and pollForConfirmation.

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

Synchronously submit a transaction with debug scripts for diagnostic replay.

The tip of the selected chain, or ChainTip.origin before the first block.

The treasury as of the last epoch boundary, the value a tx must state as its currentTreasuryValue. It lives in the env, spec [SC-6], so it starts as initialContext.env.treasury.

produceBlock on a branch at slot with a Java list, spec section 8.2.

produceBlock on a branch with a Java list: forge txs on on, at slot on.slot + 1, spec [FG-11].

rollback, with the result as an EmulatorResult, spec section 11.3.

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

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

The status of the tx txHash, spec [TS-1]. It reads the mempool and the blocks, not the applied-tx log: a tx known only from the log the emulator was built with is NotFound.

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

The blocks stay: the log drops the imported log and then starts above the tip, spec [DE-4].