@harmoniclabs/pluts-emulator/dist/Emulator.d.ts

Cardano emulator for offchian testing

import { Address, AddressStr, IUTxO, ProtocolParameters, Tx, ITxRunnerProvider, TxOutRefStr, UTxO, Hash32 } from "@harmoniclabs/plu-ts";
import { EmulatorBlockInfos } from "./types/EmulatorBlockInfos.js";
import { CanResolveToUTxO, CanBeData, GenesisInfos, IGetGenesisInfos, IGetProtocolParameters, IResolveUTxOs, ISubmitTx, TxBuilder } from "@harmoniclabs/buildooor";
export declare class Emulator implements ITxRunnerProvider, IGetGenesisInfos, IGetProtocolParameters, IResolveUTxOs, ISubmitTx {
    private readonly utxos;
    private readonly stakeAddresses;
    private readonly addresses;
    private debugLevel;
    private readonly mempool;
    private time;
    private slot;
    private blockHeight;
    private readonly genesisInfos;
    private readonly protocolParameters;
    private lastBlock;
    private readonly datumTable;
    readonly txBuilder: TxBuilder;
    /**
     * Create a new Emulator
     * @param initialUtxoSet Initial UTxOs to populate the ledger
     * @param genesisInfos Chain genesis information
     * @param protocolParameters Protocol parameters
     * @param debugLevel Debug level (0: no debug, 1: basic debug, 2: detailed debug)
     */
    constructor(initialUtxoSet?: Iterable<IUTxO>, genesisInfos?: GenesisInfos, protocolParameters?: ProtocolParameters, debugLevel?: number);
    /** Add a UTxO to the ledger
      * @param utxo UTxO to add
      * @returns void
    */
    private addUtxoToLedger;
    /** Remove a UTxO from the ledger
      * @param utxoRef UTxO reference to remove
      * @returns void
    */
    private removeUtxoFromLedger;
    /** Pretty printers */
    /** Pretty print a UTxO
      * @param utxo UTxO to pretty print
      * @param detailed Whether to show detailed information (default: false)
      * @returns Pretty printed string
    */
    prettyPrintUtxo(utxo: UTxO, detailed?: boolean): string;
    /** Pretty print a set of UTxOs
      * @param utxos UTxOs to pretty print
      * @param detailed Whether to show detailed information (default: false)
      * @returns Pretty printed string
    */
    prettyPrintUtxos(utxos: Map<TxOutRefStr, UTxO>, detailed?: boolean): string;
    /** Pretty print the ledger state
     * @param detailed Whether to show detailed information (default: false)
     * @return Pretty printed string of the entire ledger state
     */
    prettyPrintLedgerState(detailed?: boolean): string;
    /** Pretty print the mempool
     * @param detailed Whether to show detailed information (default: false)
     * @return Pretty printed string
     * */
    prettyPrintMempool(detailed?: boolean): string;
    /** Getters */
    /** Get genesis information */
    getGenesisInfos(): Promise<GenesisInfos>;
    /** Get protocol parameters */
    getProtocolParameters(): Promise<ProtocolParameters>;
    /** Get the maximal size for a transaction */
    getTxMaxSize(): number;
    /** Get the current time */
    getCurrentTime(): number;
    /** Get the current block height */
    getCurrentSlot(): number;
    /** Get the current block height */
    getCurrentBlockHeight(): number;
    /** Get the current block information */
    getChainTip(): EmulatorBlockInfos;
    /** Returns the set of UTxOs */
    getUtxos(): UTxO[];
    /**
     * Get all transactions in the mempool
     */
    getMempool(): Tx[];
    /** Helper */
    /** Get the size of a transaction */
    getTxSize(tx: Tx | undefined): number;
    fromSlotToPosix(slot: number): bigint;
    /**
     * Calculate the minimum required fee for a transaction
     * @param tx The transaction
     * @returns The minimum required fee in lovelace
     */
    private calculateMinFee;
    /** Debug */
    /** Set the debug level */
    setDebugLevel(level: number): void;
    /** Get the debug level */
    /** Debug log amethod
      * @param level Debug level (0: no debug, 1: basic debug, 2: detailed debug)
      * @param message Debug message
      * @returns void
    */
    private debug;
    /**
     * Resolves the utxos that are present on the current ledger state
     *
     * Note: if some of the specified utxos are not present (have been spent already)
     * they will be filtered out
     * @param utxos UTxOs to resolve
     * @returns Promise<UTxO[]> Resolved UTxOs
    */
    resolveUtxos(utxos: CanResolveToUTxO[]): Promise<UTxO[]>;
    /**
     * Resolves UTxOs for a specific address
     * @param address Address to find UTxOs for
     * @returns Array of UTxOs belonging to the address, or undefined if none found
     */
    resolveUtxosbyAddress(address: Address | AddressStr): UTxO[] | undefined;
    /**
     * Retrieves UTxOs for a specific address (Blockfrost API compatible method)
     * @param address Address to find UTxOs for
     * @returns Promise with array of UTxOs belonging to the address
     */
    addressUtxos(address: AddressStr | Address): Promise<UTxO[]>;
    /**
     * Resolves datum hashes to their corresponding datum values
     * @param hashes Array of Hash32 objects representing datum hashes to resolve
     * @returns Promise with an array of resolved datums with their hashes
     */
    resolveDatumHashes(hashes: Hash32[]): Promise<{
        hash: string;
        datum: CanBeData;
    }[]>;
    /**
     * Advance to a future block
     * @param blocks Number of blocks to advance
     */
    awaitBlock(blocks?: number): void;
    /** Advance to a future slot
     * @param slots Number of slots to advance
     * @returns void
     * */
    awaitSlot(slots?: number): void;
    /** Update the ledger by processing the mempool, respecting the block size limit */
    private updateLedger;
    /** Process a transaction into the ledger state
      * @param tx Transaction to process
      * @returns void
     */
    private processTx;
    /** Submit a transaction to the mempool
      * @param txCBOR Transaction to submit (CBOR or Tx object)
      * @returns Transaction hash
      * Note: [RS] I think we should allow users to transactions that will fail script validation
     */
    submitTx(txCBOR: string | Tx): Promise<string>;
    /**
     * Validate a transaction against the current state
     * @param tx Transaction to validate
     */
    private validateTx;
    /**
     * Validate tx inputs to ensure sufficient collateral is provided in it
     * @param tx Transaction to validate collateral for
     * @returns
     */
    private validateCollateral;
    /**
     * Slash collateral for a failed transaction
     * @param tx The transaction that failed phase-2 validation
     */
    private slashCollateral;
}
/**
 * Initialize an emulator with UTxOs for testing
 * @param addresses Map of addresses and their initial balances in lovelaces
 * @returns Configured Emulator instance
 */
export declare function initializeEmulator(addresses?: Map<Address, bigint>): Emulator;
/**
* Initialize an emulator when handling a single wallet address.
* If the address already has a UTxO with 15 ADA, reuse it; otherwise, throw error expecting wallet to be populated manually.
* @param utxos The UTxOs contained in the browser wallet to initialize the emulator with.
* @returns Configured Emulator instances
*/
export declare function initializeEmulatorWithWalletUtxOs(utxos: UTxO[]): Emulator;