ethereumjs-vm

What is ethereumjs-vm?

The ethereumjs-vm package is a JavaScript implementation of the Ethereum Virtual Machine (EVM). It allows developers to execute smart contracts, run Ethereum transactions, and simulate the Ethereum blockchain environment. This package is useful for testing, development, and research purposes.

What are ethereumjs-vm's main functionalities?

Execute Smart Contracts

This feature allows you to execute smart contracts within the Ethereum Virtual Machine. The code sample demonstrates how to set up the VM, create an account, and run a simple contract code.

const { VM } = require('ethereumjs-vm');
const { Account, Address } = require('ethereumjs-util');
const { default: Common } = require('@ethereumjs/common');

const common = new Common({ chain: 'mainnet' });
const vm = new VM({ common });

const runCode = async () => {
  const code = '0x6001600101600055'; // Simple contract code
  const address = Address.fromString('0x1234567890123456789012345678901234567890');
  const account = new Account({ balance: '0x10000000000000' });

  await vm.stateManager.putAccount(address, account);

  const result = await vm.runCode({
    code: Buffer.from(code, 'hex'),
    gasLimit: Buffer.from('ffffffff', 'hex'),
    address,
  });

  console.log(result);
};

runCode();

Run Ethereum Transactions

This feature allows you to run Ethereum transactions within the VM. The code sample demonstrates how to create a transaction and execute it using the VM.

const { VM } = require('ethereumjs-vm');
const { Transaction } = require('ethereumjs-tx');
const { default: Common } = require('@ethereumjs/common');

const common = new Common({ chain: 'mainnet' });
const vm = new VM({ common });

const runTransaction = async () => {
  const txData = {
    nonce: '0x00',
    gasPrice: '0x09184e72a000',
    gasLimit: '0x2710',
    to: '0x0000000000000000000000000000000000000000',
    value: '0x00',
    data: '0x',
  };

  const tx = new Transaction(txData, { common });

  const result = await vm.runTx({ tx });

  console.log(result);
};

runTransaction();

Simulate Blockchain Environment

This feature allows you to simulate a blockchain environment by running blocks within the VM. The code sample demonstrates how to create a block and execute it using the VM.

const { VM } = require('ethereumjs-vm');
const { Block } = require('@ethereumjs/block');
const { default: Common } = require('@ethereumjs/common');

const common = new Common({ chain: 'mainnet' });
const vm = new VM({ common });

const simulateBlockchain = async () => {
  const block = Block.fromBlockData({}, { common });

  const result = await vm.runBlock({ block, generate: true, skipBlockValidation: true });

  console.log(result);
};

simulateBlockchain();

Other packages similar to ethereumjs-vm

ganache-cli

Ganache CLI is a fast and customizable blockchain emulator that allows you to run a personal Ethereum blockchain. It is often used for development and testing purposes. Compared to ethereumjs-vm, Ganache CLI provides a more user-friendly interface and additional features like snapshotting and forking.

truffle

Truffle is a development framework for Ethereum that includes a suite of tools for smart contract development, testing, and deployment. It integrates with Ganache for local blockchain simulation. While ethereumjs-vm focuses on the EVM execution, Truffle provides a more comprehensive development environment.

hardhat

Hardhat is a development environment for Ethereum that helps developers manage and automate the recurring tasks inherent to building smart contracts and DApps. It includes a local Ethereum network for testing. Hardhat offers more advanced features like debugging and stack traces compared to ethereumjs-vm.

README

SYNOPSIS

or #ethereumjs on freenode

Implements Ethereum's VM in JS

INSTALL

npm install ethereumjs-vm

USAGE

var VM = require('ethereumjs-vm')

//create a new VM instance
var vm = new VM()
var code = '7f4e616d65526567000000000000000000000000000000000000000000000000003055307f4e616d6552656700000000000000000000000000000000000000000000000000557f436f6e666967000000000000000000000000000000000000000000000000000073661005d2720d855f1d9976f88bb10c1a3398c77f5573661005d2720d855f1d9976f88bb10c1a3398c77f7f436f6e6669670000000000000000000000000000000000000000000000000000553360455560df806100c56000396000f3007f726567697374657200000000000000000000000000000000000000000000000060003514156053576020355415603257005b335415603e5760003354555b6020353360006000a233602035556020353355005b60007f756e72656769737465720000000000000000000000000000000000000000000060003514156082575033545b1560995733335460006000a2600033545560003355005b60007f6b696c6c00000000000000000000000000000000000000000000000000000000600035141560cb575060455433145b1560d25733ff5b6000355460005260206000f3'
//code needs to be a buffer
code = new Buffer(code, 'hex')

vm.runCode({
  code: code,
  gasLimit: new Buffer('ffffffff', 'hex') 
}, function(err, results){
  console.log('returned: ' + results.return.toString('hex'));
})

Also more examples can be found here

• examples
• old blog post

BROWSER

To build for standalone use in the browser install browserify and run npm run build. This will give you a global variable EthVM to use. The standalone file will be at ./dist/ethereumjs-vm.js

API

• new VM([StateTrie], [blockchain])
• VM methods
  • vm.runBlockchain([blockchain], [cb])
  • vm.runBlock(opts, cb)
  • vm.runTx(opts, cb)
  • vm.runCode(opts, cb)
  • vm.generateCanonicalGenesis(cb)
  • vm.generateGenesis(cb)
• VM debugging hooks
  • vm.onStep

new VM([StateTrie], [blockchain])

Creates a new VM object

• StateTrie - The Patricia Merkle Tree that contains the state. If no trie is given the VM will create an in memory trie.
• blockchain - an instance of the Blockchain If no blockchain is given a fake blockchain will be used.

VM methods

vm.runBlockchain(blockchain, cb)

Process a transaction.

• blockchain - A blockchain that to process
• cb - The callback. It is given an err parameter if it fails

vm.runBlock(opts, cb)

Processes the block running all of the transactions it contains and updating the miner's account.

• opts.block - The Block to process
• opts.generate - a Boolean; whether to generate the stateRoot. If false runBlock will check the stateRoot of the block against the Trie
• cb - The callback. It is given two arguments, an error string containing an error that may have happened or null, and a results object with the following properties:
  • receipts - the receipts from the transactions in the block
  • results - an Array for results from the transactions in the block

vm.runTx(opts, cb)

Process a transaction.

• opts.tx - A Transaction to run.
• opts.block - The block to which the tx belongs. If omitted a blank block will be used.
• cb - The callback. It is given two arguments, an error string containing an error that may have happened or null, and a results object with the following properties:
  • amountSpent - the amount of ether used by this transaction as a bignum
  • gasUsed - the amount of gas used by the transaction
  • vm - contains the results from running the code, if any, as described in vm.runCode(params, cb)

vm.runCode(opts, cb)

Runs EVM code

• opts.code - The EVM code to run given as a Buffer
• opts.data - The input data given as a Buffer
• opts.value - The value in ether that is being sent to opt.address. Defaults to 0
• opts.block - The Block the tx belongs to. If omitted a blank block will be used.
• opts.gasLimit - The gas limit for the code given as a Buffer
• opts.account - The Account that the executing code belongs to. If omitted an empty account will be used
• opts.address - The address of the account that is executing this code. The address should be a Buffer of bytes. Defaults to 0
• opts.origin - The address where the call originated from. The address should be a Buffer of 20bits. Defaults to 0
• opts.caller - The address that ran this code. The address should be a Buffer of 20bits. Defaults to 0
• cb - The callback. It is given two arguments, an error string containing an error that may have happened or null and a results object with the following properties
  • gas - the amount of gas left as a bignum
  • gasUsed - the amount of gas as a bignum the code used to run.
  • gasRefund - a Bignum containing the amount of gas to refund from deleting storage values
  • suicides - an Array of accounts that have suicided.
  • suicideTo - the account that the suicide refund should go to.
  • logs - an Array of logs that the contract emitted.
  • exception - a boolean, whether or not the contract encountered an exception
  • exceptionError - a String describing the exception if there was one.
  • return - a Buffer containing the value that was returned by the contract

vm.stateManager.generateCanonicalGenesis(cb)

Generates the Canonical genesis state.

vm.stateManager.generateGenesis(genesisData, cb)

Generate the genesis state.

• genesisData - an Object whose keys are addresses and values are strings representing initial allocation of ether.
• cb - The callback

var genesisData = {
  "51ba59315b3a95761d0863b05ccc7a7f54703d99": "1606938044258990275541962092341162602522202993782792835301376",
  "e4157b34ea9615cfbde6b4fda419828124b70c78": "1606938044258990275541962092341162602522202993782792835301376"
}

vm.generateGenesis(genesisData, function(){
  console.log('generation done');
})

events

All events are instances of async-eventemmiter. If an event handler has an arity of 2 the VM will pause until the callback is called

step

The step event is given an Object and callback. The Object has the following properties.

• pc - a Number representing the program counter
• opcode - the next opcode to be ran
• gas - a bignum standing for the amount of gasLeft
• stack - an Array of Buffers containing the stack.
• storageTrie - the storage trie for the account
• account - the Account which owns the code running.
• address - the address of the account
• depth - the current number of calls deep the contract is
• memory - the memory of the VM as a buffer
• cache - The account cache. Contains all the accounts loaded from the trie. It is an instance of functional red black tree

beforeBlock

Emits the block that is about to be processed.

afterBlock

Emits the results of the processing a block.

beforeTx

Emits the Transaction that I about to be processed.

afterTx

Emits the result of the transaction.

TESTING

npm test
if you want to just run the Blockchain tests run ./bin/tester -b if you want to just run the VM tests run ./bin/tester -v if you want to just run the State tests run ./bin/tester -s

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.

LICENSE

MPL-2.0