@ethereumjs/vm

ethereumjs-vm

Implements Ethereum's VM in TypeScript.

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 preceeding release.

INSTALL

npm install @ethereumjs/vm

USAGE

import { BN } from 'ethereumjs-util'
import Common from '@ethereumjs/common'
import VM from '@ethereumjs/vm'

const common = new Common({ chain: 'mainnet' })
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)

Example

This projects contain the following examples:

1. ./examples/run-blockchain: Loads tests data, including accounts and blocks, and runs all of them in the VM.
2. ./examples/run-code-browser: Show how to use this library in a browser.
3. ./examples/run-solidity-contract: Compiles a Solidity contract, and calls constant and non-constant functions.
4. ./examples/run-transactions-complete: Runs a contract-deployment transaction and then calls one of its functions.
5. ./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.

API

VM

For documentation on VM instantiation, exposed API and emitted events see generated API docs.

StateManager

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.

BROWSER

To build the VM for standalone use in the browser, see: Running the VM in a browser.

SETUP

Hardfork Support

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+)
• byzantium
• constantinople
• petersburg
• istanbul (v4.1.1+)
• muirGlacier (only mainnet and ropsten) (v4.1.3+)
• berlin (DRAFT, only EIP-2315)

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 from '@ethereumjs/common'
import VM from '@ethereumjs/vm'

const common = new Common({ chain: 'mainnet', hardfork: 'byzantium' })
const vm = new VM({ common })

EIP Support

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 from '@ethereumjs/common'
import VM from '@ethereumjs/vm'

const common = new Common({ chain: 'mainnet', eips: [2537] })
const vm = new VM({ common })

Currently supported EIPs:

• EIP-2537: BLS precompiles
• EIP-2929: gas cost increases for state access opcodes

Tracing Events

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 RunBlockResult right after running a block.
• beforeTx: Emits a Transaction right before running it.
• afterTx: Emits a RunTxResult 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.

Asynchronous event handlers

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.

Synchronous event handlers

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.

Internal Structure

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.

DEVELOPMENT

Developer documentation - currently mainly with information on testing and debugging - can be found here.

EthereumJS

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.

LICENSE

MPL-2.0