@ethereumjs/vm
Advanced tools
| TypeScript implementation of the Ethereum VM. |
|---|
Note: this README reflects the state of the library from v5.0.0 onwards. See README from the standalone repository for an introduction on the last preceding release.
npm install @ethereumjs/vm
import { BN } from 'ethereumjs-util'
import Common, { Chain, Hardfork } from '@ethereumjs/common'
import VM from '@ethereumjs/vm'
const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Berlin })
const vm = new VM({ common })
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]
vm.on('step', function (data) {
console.log(`Opcode: ${data.opcode.name}\tStack: ${data.stack}`)
})
vm.runCode({
code: Buffer.from(code.join(''), 'hex'),
gasLimit: new BN(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 VM instantiation, exposed API and emitted events see generated API docs.
Documentation on the StateManager can be found here. If you want to provide your own StateManager you can implement the dedicated interface to ensure that your implementation conforms with the current API.
Note: along the EIP-2929 (Gas cost increases for state access opcodes) implementation released in v5.2.0 a new EIP2929StateManager interface has been introduced inheriting from the base StateManager interface. The methods introduced there will be merged into the base state manager on the next breaking release.
To build the VM for standalone use in the browser, see: Running the VM in a browser.
Starting with v5.1.0 the VM supports running both Ethash/PoW and Clique/PoA blocks and transactions. Clique support has been added along the work on PR #1032 and follow-up PRs and (block) validation checks and the switch of the execution context now happens correctly.
@ethereumjs/blockchain validates the PoW algorithm with @ethereumjs/ethash and validates blocks' difficulty to match their canonical difficulty.
For the VM to work correctly in a Clique/PoA context you need to use the library with the following library versions or higher:
v3.1.0v5.1.0v2.1.0The following is a simple example for a block run on Goerli:
import VM from '@ethereumjs/vm'
import Common, { Chain } from '@ethereumjs/common'
const common = new Common({ chain: Chain.Goerli })
const hardforkByBlockNumber = true
const vm = new VM({ common, hardforkByBlockNumber })
const serialized = Buffer.from('f901f7a06bfee7294bf4457...', 'hex')
const block = Block.fromRLPSerializedBlock(serialized, { hardforkByBlockNumber })
const result = await vm.runBlock(block)
Starting with the v5 release series all hardforks from Frontier (chainstart) up to the latest active mainnet hardfork are supported.
The VM currently supports the following hardfork rules:
chainstart (a.k.a. Frontier) (v5.0.0+)homestead (v5.0.0+)tangerineWhistle (v5.0.0+)spuriousDragon (v5.0.0+)byzantiumconstantinoplepetersburgistanbul (v4.1.1+)muirGlacier (only mainnet and ropsten) (v4.1.3+)berlin (v5.2.0+)london (v5.4.0+)Default: istanbul (taken from Common.DEFAULT_HARDFORK)
A specific hardfork VM ruleset can be activated by passing in the hardfork
along the Common instance:
import Common, { Chain, Hardfork } from '@ethereumjs/common'
import VM from '@ethereumjs/vm'
const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Berlin })
const vm = new VM({ common })
It is possible to individually activate EIP support in the VM by instantiate the Common instance passed
with the respective EIPs, e.g.:
import Common, { Chain } 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)berlin EIP)berlin EIP)berlin EIP)berlin EIP)london EIP)london EIP)london EIP)Our TypeScript VM 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:
beforeBlock: Emits a Block right before running it.afterBlock: Emits AfterBlockEvent right after running a block.beforeTx: Emits a Transaction right before running it.afterTx: Emits a AfterTxEvent right after running a transaction.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 VM 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 VM 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 VM 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 VM and interrupt it, possibly corrupting its state. It's strongly recommended not to throw from withing event handlers.
If you want to understand your VM 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 |
|---|---|
vm:block | Block operations (run txs, generating receipts, block rewards,...) |
vm:tx | Transaction operations (account updates, checkpointing,...) |
vm:tx:gas | Transaction gas logger |
vm:evm | EVM control flow, CALL or CREATE message execution |
vm:evm:gas | EVM gas logger |
vm:eei:gas | EEI gas logger |
vm:state | StateManager logger |
vm:ops | Opcode traces |
vm:ops:[Lower-case opcode name] | Traces on a specific opcode |
Here are some examples for useful logger combinations.
Run one specific logger:
DEBUG=vm:tx ts-node test.ts
Run all loggers currently available:
DEBUG=vm:*,vm:*:* ts-node test.ts
Run only the gas loggers:
DEBUG=vm:*:gas ts-node test.ts
Excluding the state logger:
DEBUG=vm:*,vm:*:*,-vm:state ts-node test.ts
Run some specific loggers including a logger specifically logging the SSTORE executions from the VM (this is from the screenshot above):
DEBUG=vm:tx,vm:evm,vm:ops:sstore,vm:*:gas ts-node test.ts
The VM processes state changes at many levels.
The opFns for CREATE, CALL, and CALLCODE call back up to runCall.
Developer documentation - currently mainly with information on testing and debugging - can be found here.
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 do improvements on the libraries have a look at our contribution guidelines.
FAQs
An Ethereum VM implementation
The npm package @ethereumjs/vm receives a total of 68,611 weekly downloads. As such, @ethereumjs/vm popularity was classified as popular.
We found that @ethereumjs/vm 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
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.