@feelyourprotocol/evm 8141.0.0

package/dist/esm/evm.d.ts

@@ -0,0 +1,181 @@
+import type { BlockLevelAccessList, PrefixedHexString } from '@feelyourprotocol/util';
+import { Account, Address } from '@feelyourprotocol/util';
+import { EventEmitter } from 'eventemitter3';
+import { EVMError } from './errors.ts';
+import type { FrameExecutionContext } from './frameContext.ts';
+import { Journal } from './journal.ts';
+import { EVMPerformanceLogger } from './logger.ts';
+import { Message } from './message.ts';
+import { TransientStorage } from './transientStorage.ts';
+import { type Block, type CustomOpcode, type EVMBLSInterface, type EVMEvent, type EVMInterface, type EVMMockBlockchainInterface, type EVMOpts, type EVMResult, type EVMRunCallOpts, type EVMRunCodeOpts, type ExecResult } from './types.ts';
+import type { Common, StateManagerInterface } from '@feelyourprotocol/common';
+import type { BinaryTreeAccessWitness } from './binaryTreeAccessWitness.ts';
+import type { InterpreterOpts } from './interpreter.ts';
+import type { MessageWithTo } from './message.ts';
+import type { AsyncDynamicGasHandler, SyncDynamicGasHandler } from './opcodes/gas.ts';
+import type { OpHandler, OpcodeList, OpcodeMap } from './opcodes/index.ts';
+import type { CustomPrecompile, PrecompileFunc } from './precompiles/index.ts';
+/**
+ * Creates a standardized ExecResult for out-of-gas errors.
+ * @param gasLimit - Gas limit consumed by the failing frame
+ * @returns Execution result describing the OOG failure
+ */
+export declare function OOGResult(gasLimit: bigint): ExecResult;
+/**
+ * Creates an ExecResult for code-deposit out-of-gas errors (EIP-3541).
+ * @param gasUsedCreateCode - Gas consumed while attempting to store code
+ */
+export declare function COOGResult(gasUsedCreateCode: bigint): ExecResult;
+/**
+ * Returns an ExecResult signalling invalid bytecode input.
+ * @param gasLimit - Gas consumed up to the point of failure
+ */
+export declare function INVALID_BYTECODE_RESULT(gasLimit: bigint): ExecResult;
+/**
+ * Returns an ExecResult signalling invalid EOF formatting.
+ * @param gasLimit - Gas consumed up to the point of failure
+ */
+export declare function INVALID_EOF_RESULT(gasLimit: bigint): ExecResult;
+/**
+ * Returns an ExecResult for code size violations.
+ * @param gasUsed - Gas consumed before the violation was detected
+ */
+export declare function CodesizeExceedsMaximumError(gasUsed: bigint): ExecResult;
+/**
+ * Wraps an {@link EVMError} in an ExecResult.
+ * @param error - Error encountered during execution
+ * @param gasUsed - Gas consumed up to the error
+ */
+export declare function EVMErrorResult(error: EVMError, gasUsed: bigint): ExecResult;
+/**
+ * Creates a default block header used by stand-alone executions.
+ * @returns Block-like object with zeroed header fields
+ */
+export declare function defaultBlock(): Block;
+/**
+ * The EVM (Ethereum Virtual Machine) is responsible for executing EVM bytecode, processing transactions, and managing state changes. It handles both contract calls and contract creation operations.
+ *
+ * An EVM instance can be created with the constructor method:
+ *
+ * - {@link createEVM}
+ */
+export declare class EVM implements EVMInterface {
+    protected static supportedHardforks: ("chainstart" | "byzantium" | "istanbul" | "homestead" | "dao" | "tangerineWhistle" | "spuriousDragon" | "constantinople" | "petersburg" | "muirGlacier" | "berlin" | "london" | "arrowGlacier" | "grayGlacier" | "mergeNetsplitBlock" | "paris" | "shanghai" | "cancun" | "prague" | "osaka" | "bpo1" | "bpo2" | "bpo3" | "bpo4" | "bpo5" | "amsterdam")[];
+    protected _tx?: {
+        gasPrice: bigint;
+        origin: Address;
+    };
+    protected _block?: Block;
+    /** EIP-8141 frame execution context, set by the VM during frame tx execution */
+    frameExecutionContext?: FrameExecutionContext;
+    readonly common: Common;
+    readonly events: EventEmitter<EVMEvent>;
+    stateManager: StateManagerInterface;
+    blockchain: EVMMockBlockchainInterface;
+    journal: Journal;
+    binaryAccessWitness?: BinaryTreeAccessWitness;
+    systemBinaryAccessWitness?: BinaryTreeAccessWitness;
+    readonly transientStorage: TransientStorage;
+    protected _opcodes: OpcodeList;
+    readonly allowUnlimitedContractSize: boolean;
+    readonly allowUnlimitedInitCodeSize: boolean;
+    readonly blockLevelAccessList?: BlockLevelAccessList;
+    protected readonly _customOpcodes?: CustomOpcode[];
+    protected readonly _customPrecompiles?: CustomPrecompile[];
+    protected _handlers: Map<number, OpHandler>;
+    protected _dynamicGasHandlers: Map<number, AsyncDynamicGasHandler | SyncDynamicGasHandler>;
+    protected _opcodeMap: OpcodeMap;
+    protected _precompiles: Map<string, PrecompileFunc>;
+    protected readonly _optsCached: EVMOpts;
+    protected performanceLogger: EVMPerformanceLogger;
+    get precompiles(): Map<string, PrecompileFunc>;
+    get opcodes(): OpcodeList;
+    protected readonly _bls?: EVMBLSInterface;
+    /**
+     * EVM is run in DEBUG mode (default: false)
+     * Taken from DEBUG environment variable
+     *
+     * Safeguards on debug() calls are added for
+     * performance reasons to avoid string literal evaluation
+     * @hidden
+     */
+    readonly DEBUG: boolean;
+    protected readonly _emit: (topic: string, data: any) => Promise<void>;
+    private _bn254;
+    /**
+     *
+     * Creates new EVM object
+     *
+     * @deprecated The direct usage of this constructor is replaced since
+     * non-finalized async initialization lead to side effects. Please
+     * use the async {@link createEVM} constructor instead (same API).
+     *
+     * @param opts The EVM options
+     * @param bn128 Initialized bn128 WASM object for precompile usage (internal)
+     */
+    constructor(opts: EVMOpts);
+    /**
+     * Returns a list with the currently activated opcodes
+     * available for EVM execution
+     */
+    getActiveOpcodes(): OpcodeList;
+    protected _executeCall(message: MessageWithTo): Promise<EVMResult>;
+    protected _executeCreate(message: Message): Promise<EVMResult>;
+    /**
+     * Starts the actual bytecode processing for a CALL or CREATE
+     */
+    protected runInterpreter(message: Message, opts?: InterpreterOpts): Promise<ExecResult>;
+    /**
+     * Executes an EVM message, determining whether it's a call or create
+     * based on the `to` address. It checkpoints the state and reverts changes
+     * if an exception happens during the message execution.
+     */
+    runCall(opts: EVMRunCallOpts): Promise<EVMResult>;
+    /**
+     * Bound to the global VM and therefore
+     * shouldn't be used directly from the evm class
+     */
+    runCode(opts: EVMRunCodeOpts): Promise<ExecResult>;
+    /**
+     * Returns the precompile function registered at the given address,
+     * or `undefined` if no precompile is active there.
+     *
+     * Accepts either an `Address` instance or a `0x`-prefixed hex string.
+     *
+     * ```ts
+     * const evm = await createEVM({
+     *   customPrecompiles: [{ address: '0x000000000000000000000000000000000000ff01', function: myFn }],
+     * })
+     * const fn = evm.getPrecompile('0x000000000000000000000000000000000000ff01')
+     * ```
+     */
+    getPrecompile(address: Address | PrefixedHexString): PrecompileFunc | undefined;
+    /**
+     * Executes a precompiled contract with given data and gas limit.
+     */
+    protected runPrecompile(code: PrecompileFunc, data: Uint8Array, gasLimit: bigint): Promise<ExecResult> | ExecResult;
+    protected _loadCode(message: Message): Promise<void>;
+    protected _generateAddress(message: Message): Promise<Address>;
+    protected _reduceSenderBalance(account: Account, message: Message): Promise<void>;
+    protected _addToBalance(toAccount: Account, message: MessageWithTo): Promise<void>;
+    /**
+     * Once the interpreter has finished depth 0, a post-message cleanup should be done
+     */
+    private postMessageCleanup;
+    /**
+     * This method copies the EVM, current HF and EIP settings
+     * and returns a new EVM instance.
+     *
+     * Note: this is only a shallow copy and both EVM instances
+     * will point to the same underlying state DB.
+     *
+     * @returns EVM
+     */
+    shallowCopy(): EVM;
+    getPerformanceLogs(): {
+        opcodes: import("./logger.ts").EVMPerformanceLogOutput[];
+        precompiles: import("./logger.ts").EVMPerformanceLogOutput[];
+    };
+    clearPerformanceLogs(): void;
+}
+//# sourceMappingURL=evm.d.ts.map

package/dist/esm/evm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm.d.ts","sourceRoot":"","sources":["../../src/evm.ts"],"names":[],"mappings":"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"}