@nomicfoundation/ethereumjs-evm
Advanced tools
JavaScript Ethereum Virtual Machine (EVM) implementation
| TypeScript implementation of the Ethereum EVM. |
|---|
To obtain the latest version, simply require the project using npm:
npm install @ethereumjs/evm
This package provides the core Ethereum Virtual Machine (EVM) implementation which is capable of executing EVM-compatible bytecode. The package has been extracted from the @ethereumjs/vm package along the VM v6 release.
Note that this package atm cannot be run in a standalone mode but needs to be executed via the VM package which provides an outer Ethereum mainnet compatible execution context. Standalone functionality will be added along a future non-breaking release.
import { Chain, Common, Hardfork } from '@ethereumjs/common'
import { Blockchain } from '@ethereumjs/blockchain'
import { EEI } from '@ethereumjs/vm'
import { EVM } from '@ethereumjs/evm'
import { DefaultStateManager } from '@ethereumjs/statemanager'
// Note: in a future release there will be an EEI default implementation
// which will ease standalone initialization
const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London })
const blockchain = await Blockchain.create({ common })
const stateManager = new DefaultStateManager({ common })
const eei = new EEI(stateManager, common, blockchain)
const evm = new EVM({
common,
blockchain,
eei,
})
const STOP = '00'
const ADD = '01'
const PUSH1 = '60'
// Note that numbers added are hex values, so '20' would be '32' as decimal e.g.
const code = [PUSH1, '03', PUSH1, '05', ADD, STOP]
evm.on('step', function (data) {
// Note that data.stack is not immutable, i.e. it is a reference to the vm's internal stack object
console.log(`Opcode: ${data.opcode.name}\tStack: ${data.stack}`)
})
evm
.runCode({
code: Buffer.from(code.join(''), 'hex'),
gasLimit: BigInt(0xffff),
})
.then((results) => {
console.log(`Returned: ${results.returnValue.toString('hex')}`)
console.log(`gasUsed : ${results.gasUsed.toString()}`)
})
.catch(console.error)
This projects contain the following examples:
All of the examples have their own README.md explaining how to run them.
For documentation on EVM instantiation, exposed API and emitted events see generated API docs.
Starting with v1 the usage of BN.js for big numbers has been removed from the library and replaced with the usage of the native JS BigInt data type (introduced in ES2020).
Please note that number-related API signatures have changed along with this version update and the minimal build target has been updated to ES2020.
This package contains the inner Ethereum Virtual Machine core functionality which was included in the @ethereumjs/vm package up till v5 and has been extracted along the v6 release.
This will make it easier to customize the inner EVM, which can now be passed as an optional argument to the outer VM instance.
At the moment the EVM package can not be run standalone and it is therefore recommended for most use cases to rather use the VM package and access EVM functionality through the vm.evm property.
For the EVM to properly work it needs access to a respective execution environment (to e.g. request on information like block hashes) as well as the connection to an outer account and contract state.
To ensure a unified interface the EVM provides a TypeScript EEI interface providing which includes the necessary function signatures for access to environmental parameters as well as the VM state.
The @ethereumjs/vm provides a concrete implementation of this interface which can be used to instantiate the EVM within an Ethereum mainnet compatible execution context.
To build the EVM for standalone use in the browser, see: Running the EVM in a browser.
The EthereumJS EVM implements all hardforks from Frontier (chainstart) up to the latest active mainnet hardfork.
Currently the following hardfork rules are supported:
chainstart (a.k.a. Frontier)homesteadtangerineWhistlespuriousDragonbyzantiumconstantinoplepetersburgistanbulmuirGlacier (only mainnet and ropsten)berlin (v5.2.0+)london (v5.4.0+)arrowGlacier (only mainnet) (v5.6.0+)merge (only goerli, ropsten and soon mainnet)Default: merge (taken from Common.DEFAULT_HARDFORK)
A specific hardfork EVM ruleset can be activated by passing in the hardfork
along the Common instance to the outer @ethereumjs/vm instance.
It is possible to individually activate EIP support in the EVM by instantiate the Common instance passed to the outer VM with the respective EIPs, e.g.:
import { Chain, Common } from '@ethereumjs/common'
import { VM } from '@ethereumjs/vm'
const common = new Common({ chain: Chain.Mainnet, eips: [2537] })
const vm = new VM({ common })
Currently supported EIPs:
london EIP)experimental)experimental)berlin EIP)berlin EIP)berlin EIP)berlin EIP)london EIP)london EIP)experimental)london EIP)experimental)experimental)experimental)experimental)Our TypeScript EVM is implemented as an AsyncEventEmitter and events are submitted along major execution steps which you can listen to.
You can subscribe to the following events:
beforeMessage: Emits a Message right after running it.afterMessage: Emits an EVMResult right after running a message.step: Emits an InterpreterStep right before running an EVM step.newContract: Emits a NewContractEvent right before creating a contract. This event contains the deployment code, not the deployed code, as the creation message may not return such a code.An example for the step event can be found in the initial usage example in this README.
You can perform asynchronous operations from within an event handler and prevent the EVM to keep running until they finish.
In order to do that, your event handler has to accept two arguments. The first one will be the event object, and the second one a function. The EVM won't continue until you call this function.
If an exception is passed to that function, or thrown from within the handler or a function called by it, the exception will bubble into the EVM and interrupt it, possibly corrupting its state. It's strongly recommended not to do that.
If you want to perform synchronous operations, you don't need to receive a function as the handler's second argument, nor call it.
Note that if your event handler receives multiple arguments, the second one will be the continuation function, and it must be called.
If an exception is thrown from withing the handler or a function called by it, the exception will bubble into the EVM and interrupt it, possibly corrupting its state. It's strongly recommended not to throw from withing event handlers.
If you want to understand your EVM runs we have added a hierarchically structured list of debug loggers for your convenience which can be activated in arbitrary combinations. We also use these loggers internally for development and testing. These loggers use the debug library and can be activated on the CL with DEBUG=[Logger Selection] node [Your Script to Run].js and produce output like the following:
The following loggers are currently available:
| Logger | Description |
|---|---|
evm | EVM control flow, CALL or CREATE message execution |
evm:gas | EVM gas logger |
evm:eei:gas | EEI gas logger |
evm:ops | Opcode traces |
evm:ops:[Lower-case opcode name] | Traces on a specific opcode |
Here are some examples for useful logger combinations.
Run one specific logger:
DEBUG=evm ts-node test.ts
Run all loggers currently available:
DEBUG=evm:*,evm:*:* ts-node test.ts
Run only the gas loggers:
DEBUG=evm:*:gas ts-node test.ts
Excluding the ops logger:
DEBUG=evm:*,evm:*:*,-evm:ops ts-node test.ts
Run some specific loggers including a logger specifically logging the SSTORE executions from the EVM (this is from the screenshot above):
DEBUG=evm,evm:ops:sstore,evm:*:gas ts-node test.ts
The EVM processes state changes at many levels.
The opFns for CREATE, CALL, and CALLCODE call back up to runCall.
TODO: this section likely needs an update.
See @ethereumjs/vm README.
See our organizational documentation for an introduction to EthereumJS as well as information on current standards and best practices. If you want to join for work or carry out improvements on the libraries, please review our contribution guidelines first.
FAQs
JavaScript Ethereum Virtual Machine (EVM) implementation
The npm package @nomicfoundation/ethereumjs-evm receives a total of 30,626 weekly downloads. As such, @nomicfoundation/ethereumjs-evm popularity was classified as popular.
We found that @nomicfoundation/ethereumjs-evm demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.