emulator.emulator

Home > @blaze-cardano/emulator > Emulator

Emulator class

The Emulator class is used to simulate the behavior of a ledger. It maintains a ledger of unspent transaction outputs, reward accounts, protocol parameters, and a clock. It also provides methods to start and stop an event loop for the ledger.

Signature:

export declare class Emulator 

Constructors

Constructor	Modifiers	Description
(constructor)(genesisOutputs, { evaluator, slotConfig, trace: traceGovernance, slotsPerEpoch, params, treasury, cc, ccHotCredentials, })		Constructs a new emulator instance seeded with the provided genesis outputs.

Properties

Property	Modifiers	Type	Description
accounts		Map<RewardAccount, RegisteredAccount>	The map of reward accounts and their balances.
activePools		Record<PoolId, PoolParameters>
bootstrapMode		boolean
cc		Committee
clock		LedgerTimer	The clock of the ledger.
constitution		ConstitutionCore
datumHashes		Record<DatumHash, PlutusData>	A lookup table of hashes to datums.
depositPot		bigint
dreps		Record<Hash28ByteBase16, DRepState>
enactQueue		EnactQueueItem[]
evaluator		Evaluator	The script evaluator for the emulator
eventLoop?		ReturnType<typeof setInterval>	(Optional) The event loop for the ledger.
feePot		bigint
mockedWallets		Map<string, Wallet>	A map from label to blaze instance for that wallet
params		ProtocolParameters	The protocol parameters of the ledger.
snapshots		Record<number, StakeSnapshot>
treasury		bigint

Methods

Method	Modifiers	Description
addressOf(label)		Returns the current change address for a labelled wallet, creating the wallet if it has not been initialised yet.
addUtxo(utxo)		Adds a given UTxO to the Emulator's ledger. Overwrites any existing UTxO with the same input.
as(label, callback)		Executes the supplied callback in the context of a labelled wallet and Blaze client, simplifying multi-party test flows.
awaitTransactionConfirmation(txId)		Forces block production until the referenced transaction leaves the mempool.
expectScriptFailure(tx, pattern)		Asserts that completing the provided transaction fails with an optional matching error message. Helps validate negative Plutus scenarios.
expectValidMultisignedTransaction(signers, tx)		Submits a transaction requiring multiple labelled wallets to co-sign. Each signer is resolved via getOrAddWallet before submission.
expectValidTransaction(blaze, tx)		Completes, signs, and submits a transaction, throwing if validation fails. Retains the CBOR for debugging in line with emulator troubleshooting flow.
fund(label, value, datum)		Mints a synthetic genesis UTxO to the labelled wallet to seed it with funds.
getCommitteeHotCredential(coldCredentialHash)		Retrieves the cached hot credential for the provided committee cold hash.
getCurrentTreasuryFeeShare()		Calculates the treasury's share of accumulated fees based on the current parameters.
getGovernanceProposalStatus(actionId)		Returns the lifecycle status for a governance action, if the emulator is tracking it.
getOutput(inp)		Retrieves an output from the ledger by input.
getTallies(actionId)		Computes the latest ratification tallies for an action using the most recent stake snapshot.
isKnownStakePool(keyHash)
lookupScript(script)		Locates the synthetic script reference UTxO for the provided script.
publishScript(script)		Attaches the provided script to a genesis-style UTxO so tests can reference it via lookupScript without building an on-chain transaction.
register(label, value, datum)		Funds and registers a labelled wallet, returning its default change address.
removeUtxo(inp)		Removes a given UTxO from the Emulator's ledger by input.
setCommitteeHotCredential(coldCredentialHash, credential)		Assigns or clears the active hot credential for a committee member. Throws when the supplied cold credential hash is not part of the committee.
setCommitteeState(committee, { hotCredentials, })		Replaces the current constitutional committee and resets cached hot credentials. Clearing the committee also clears the last enacted constitution per Conway §5.5.
slotToUnix(slot)		Converts a slot index back into a unix timestamp (ms).
startEventLoop()		Starts the event loop for the ledger. If the event loop is already running, it is cleared and restarted. The event loop calls the stepForwardBlock method every 20 slots.
stepForwardBlock()		Advances exactly one block (20 slots) according to the emulator clock.
stepForwardToNextEpoch()		Advances the emulator to the first slot of the next epoch. Mirrors the epoch boundary workflow defined in the Conway ledger spec.
stepForwardToSlot(slot)		Advances the emulator forward to the provided slot, triggering epoch transitions and materialising the mempool as needed.
stepForwardToUnix(unix)		Advances time to the slot corresponding to the provided unix timestamp.
stopEventLoop()		Stops the event loop for the ledger. If the event loop is running, it is cleared.
submitTransaction(tx)		Submits a transaction to the ledger.
unixToSlot(unixMillis)		Converts a unix timestamp (ms) into a slot using the current slot configuration.
utxos()		Retrieves the Emulator's ledger as an array of UTxOs.