Class Emulator

constructor

• new Emulator(genesisOutputs, params?, __namedParameters?): Emulator

• Constructs a new instance of the Emulator class. Initializes the ledger with the provided genesis outputs and parameters.

  Parameters

  • genesisOutputs: TransactionOutput[]

    The genesis outputs to initialize the ledger with.
  • Optionalparams: Core.ProtocolParameters = hardCodedProtocolParams

    The parameters to initialize the emulator with.
  • __namedParameters: EmulatorOptions = {}

  Returns Emulator

accounts

clock

datumHashes

evaluator

OptionaleventLoop

mockedWallets

params

addUtxo

• addUtxo(utxo): void

• Adds a given UTxO to the Emulator's ledger. Overwrites any existing UTxO with the same input.

  Parameters

  • utxo: TransactionUnspentOutput

    The UTxO to add to the ledger.

  Returns void

addressOf

• addressOf(label): Promise<Address>

• Parameters

  • label: string

  Returns Promise<Address>

as

• as<T>(label, callback): Promise<T>

• Type Parameters

  • T = void

  Parameters

  • label: string
  • callback: ((blaze: Blaze<Provider, Wallet>, address: Address) => Promise<T>)
    • • (blaze, address): Promise<T>

      • Parameters

        • blaze: Blaze<Provider, Wallet>
        • address: Address

        Returns Promise<T>

  Returns Promise<T>

awaitTransactionConfirmation

• awaitTransactionConfirmation(txId): void

• Parameters

  • txId: TransactionId

  Returns void

expectScriptFailure

• expectScriptFailure(tx, pattern?): Promise<void>

• Parameters

  • tx: TxBuilder
  • Optionalpattern: RegExp

  Returns Promise<void>

expectValidMultisignedTransaction

• expectValidMultisignedTransaction(signers, tx): Promise<void>

• Parameters

  • signers: string[]
  • tx: TxBuilder

  Returns Promise<void>

expectValidTransaction

• expectValidTransaction(blaze, tx): Promise<void>

• Parameters

  • blaze: Blaze<Provider, Wallet>
  • tx: TxBuilder

  Returns Promise<void>

fund

• fund(label, value?, datum?): Promise<void>

• Parameters

  • label: string
  • Optionalvalue: Value
  • Optionaldatum: PlutusData

  Returns Promise<void>

getOutput

• getOutput(inp): TransactionOutput

• Retrieves an output from the ledger by input.

  Parameters

  • inp: TransactionInput

    The input to retrieve the output for.

  Returns TransactionOutput

  The output corresponding to the input, or undefined if the input is not found.

lookupScript

• lookupScript(script): TransactionUnspentOutput

• Parameters

  • script: Script

  Returns TransactionUnspentOutput

publishScript

• publishScript(script): Promise<void>

• Parameters

  • script: Script

  Returns Promise<void>

register

• register(label, value?, datum?): Promise<Address>

• Parameters

  • label: string
  • Optionalvalue: Value
  • Optionaldatum: PlutusData

  Returns Promise<Address>

removeUtxo

• removeUtxo(inp): void

• Removes a given UTxO from the Emulator's ledger by input.

  Parameters

  • inp: TransactionInput

    The input to remove from the ledger.

  Returns void

slotToUnix

• slotToUnix(slot): number

• Parameters

  • slot: number | bigint | Slot

  Returns number

startEventLoop

• startEventLoop(): void

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

  Returns void

stepForwardBlock

• stepForwardBlock(): void

• Returns void

stepForwardToSlot

• stepForwardToSlot(slot): void

• Parameters

  • slot: number | bigint

  Returns void

stepForwardToUnix

• stepForwardToUnix(unix): void

• Parameters

  • unix: number | bigint

  Returns void

stopEventLoop

• stopEventLoop(): void

• Stops the event loop for the ledger. If the event loop is running, it is cleared.

  Returns void

submitTransaction

• submitTransaction(tx): Promise<TransactionId>

• Submits a transaction to the ledger.

  Parameters

  • tx: Transaction

    The transaction to submit.

  Returns Promise<TransactionId>

  A promise that resolves to the transaction hash.

  Throws

  • If any of the following checks fail:
    • Invalid witnesses
    • Incorrect count of scripts and vkeys
    • Stake key registration
    • Withdrawals
    • Validity interval
    • Input existence
    • Script refs
    • Collateral inputs
    • Required signers
    • Mint witnesses
    • Cert witnesses
    • Input witnesses
    • Consumed witnesses

  Remarks

  This function performs the following checks and validations:

  • Balance Inputs/Outputs: Ensure that inputs/outputs are accurately balanced.
  • Verify Witnesses: Ensure that all witnesses in the transaction are valid.
  • Correct Count of Scripts and Vkeys: Check that the transaction has the correct number of scripts and vkeys.
  • Stake Key Registration: If the transaction involves a stake key registration, ensure that the stake key is not already registered.
  • Withdrawals: If the transaction involves withdrawals, ensure that the withdrawal amount matches the actual reward balance (in babbage, zero should be valid).
  • Validity Interval: Check that the transaction's validity interval is within the slot range.
  • Input Existence: Check that all inputs in the transaction exist and have not been spent.
  • Script Refs: For each input, check if it has a script ref and handle it accordingly.
  • Collateral Inputs: Check that all collateral inputs only contain vkeys.
  • Required Signers: Check that all required signers are included in the transaction.
  • Mint Witnesses: Check that all mint witnesses are included in the transaction.
  • Cert Witnesses: Check that all cert witnesses are included in the transaction.
  • Input Witnesses: Check that all input witnesses are included in the transaction.
  • Check Consumed Witnesses: Check that all witnesses have been consumed.
  • Apply Transitions: Apply the necessary transitions to the ledger, mempool, withdrawal requests, cert requests, and outputs, create outputs and consume datum hashes: For each output, create a new unspent output and consume the datum hash.
  • UTXO: Check that the transaction's outputs are valid. Fee checking, minSize, ada /= 0, Alonzo.validateOutputTooBigUTxO,
  • Fee Checking: Ensure that the transaction fee is not too small. See the fee calculator in tx builder.
  • Collateral Checking: Check that the collateral inputs are valid. Collateral should be UTxOs where all are held by pubkeys such that the sum of the collateral minus the collateral return is greater than the minimum collateral fee for the transaction.
    • Understanding collateral balancing: if the tx fails, instead of consuming inputs and producing outputs, you consume collateral inputs and produce 1 output (the collateral return), this is
  • Disjoint RefInputs: Ensure that there is no intersection between the input set of a transaction and the reference input set of a transaction. I.e no reference inputs may be spent.
  • Outputs Too Small: Check that all outputs of the transaction are not too small. See size calculation in tx builder, use the min size parameter from protocol params.
  • Other UTxO Transition Rules: Check other transition rules for the UTXO.
  • PPUP: Run the PPUP rule before script evaluation. Note from micah: not fully understood.
  • Expect Scripts To Pass: Ensure that all scripts pass. Simple enough, requires an 'Evaluator' to be attached to the emulator (see tx class).
  • Valid field matters for scripts/collateral: Check that the valid field is true for scripts and collateral.
    • The valid field tells you whether the tx should be passed as a collateral forfeit or if the tx should succeed.
    • I believe when the valid field is true, even if the tx fails, the node will reject it, but a malicious node could accept and propagate it.
  • Babbage Missing Scripts: Check for missing scripts according to the Babbage rules. Reference scripts get counted for free, in conway the constitution script is given for free, others need to be included in witnesses.
  • Scripts Well Formed: Ensure that all scripts are well-formed.
  • Check scripts needed: Check that all needed scripts are provided.
  • Missing Script Witnesses: Check for missing script witnesses.
  • Extraneous Script Witness: No unnecessary scripts may be attached to the transaction.
  • Failed Babbage Scripts: Validate failed Babbage scripts.
  • Outside Forecast: Validate that the transaction is bounded within the forecast (start <-> ttl).
  • Inputs Is Not Empty Set: Validate that the inputs are not an empty set.
  • Value Conserved: Validate that the value is conserved (inputs + withdrawals = outputs + fee + mint && collateral inputs = collateral outputs + collateral fee). See getPitch() from tx builder.
  • ADA is not minted: Ensure that ADA is not minted.
  • Output Too Big: Validate that the output is not too big.
  • Output Boot AddrAttrs Too Big: Validate that the output boot address attributes are not too big.
  • Correct Network Id: Validate that the correct network ID is used.
  • Network for Withdrawals: Validate the network for withdrawals.
  • Size of Tx: Validate the size of the transaction.
  • Consumed Exunits: Validate the consumed exunits.
  • Number of Collateral Inputs: Validate the number of collateral inputs.

unixToSlot

• unixToSlot(unix_millis): Slot

• Parameters

  • unix_millis: number | bigint

  Returns Slot

utxos

• utxos(): TransactionUnspentOutput[]

• Retrieves the Emulator's ledger as an array of UTxOs.

  Returns TransactionUnspentOutput[]

  The full list of UTxOs in the Emulator's ledger.