Implements Ethereum's VM in Javascript.
The VM currently supports the following hardfork rules:
Byzantium
Constantinople
Petersburg
(default)Istanbul
(beta
)
If you are still looking for a Spurious Dragon compatible version of this library install the latest of the 2.2.x
series (see Changelog).
A feature-complete Istanbul
HF implementation is available since the v4.1.0
VM release. You can activate an Istanbul
VM by using the istanbul
hardfork
option flag.
Supported Istanbul
EIPs:
- EIP-152: Blake 2b
F
precompile, PR #584 - EIP-1108: Reduce
alt_bn128
precompile gas costs,
PR #540 (already released inv4.0.0
) - EIP-1344: Add ChainID Opcode, PR #572
- EIP-1884: Trie-size-dependent Opcode Repricing, PR #581
- EIP-2200: Rebalance net-metered SSTORE gas costs, PR #590
Note that Istanbul
support is still labeled as beta
. All implementations
have only basic test coverage since the official Ethereum consensus tests are
not yet merged. There might be also last minute changes to EIPs during the
testing period.
npm install ethereumjs-vm
const BN = require('bn.js')
var VM = require('ethereumjs-vm').default
// Create a new VM instance
// For explicity setting the HF use e.g. `new VM({ hardfork: 'petersburg' })`
const vm = new VM()
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(err => console.log('Error : ' + err))
This projects contain the following examples:
- ./examples/run-blockchain: Loads tests data, including accounts and blocks, and runs all of them in the VM.
- ./examples/run-code-browser: Show how to use this library in a browser.
- ./examples/run-solidity-contract: Compiles a Solidity contract, and calls constant and non-constant functions.
- ./examples/run-transactions-complete: Runs a contract-deployment transaction and then calls one of its functions.
- ./examples/decode-opcodes: Decodes a binary EVM program into its opcodes.
All of the examples have their own README.md
explaining how to run them.
To build for standalone use in the browser, install browserify
and check run-transactions-simple example. This will give you a global variable EthVM
to use. The generated file will be at ./examples/run-transactions-simple/build.js
.
For documentation on VM
instantiation, exposed API and emitted events
see generated API docs.
The API for the StateManager
is currently in Beta
, separate documentation can be found here, see also release notes from the v2.5.0
VM release for details on the StateManager
rewrite.
The VM processes state changes at many levels.
- runBlockchain
- for every block, runBlock
- runBlock
- for every tx, runTx
- pay miner and uncles
- runTx
- check sender balance
- check sender nonce
- runCall
- transfer gas charges
- runCall
- checkpoint state
- transfer value
- load code
- runCode
- materialize created contracts
- revert or commit checkpoint
- runCode
- iterate over code
- run op codes
- track gas usage
- OpFns
- run individual op code
- modify stack
- modify memory
- calculate fee
The opFns for CREATE
, CALL
, and CALLCODE
call back up to runCall
.
You can subscribe to the following events of the VM:
beforeBlock
: Emits aBlock
right before running it.afterBlock
: EmitsRunBlockResult
right after running a block.beforeTx
: Emits aTransaction
right before running it.afterTx
: Emits aRunTxResult
right after running a transaction.beforeMessage
: Emits aMessage
right after running it.afterMessage
: Emits anEVMResult
right after running a message.step
: Emits anInterpreterStep
right before running an EVM step.newContract
: Emits aNewContractEvent
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.
If an async
function is used as an event handler, the VM will wait for it to resolve before continuing executing.
If an exception is thrown from within an event handler, it will bubble into the VM and interrupt it, possibly corrupting its state. It's strongly recommended not to throw from event handlers.
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.