or #ethereumjs on freenode

Implements Ethereum's VM in JS

npm install ethereumjs-vm

var VM = require('ethereumjs-vm')

//create a new VM instance
var vm = new VM()
var code = '7f4e616d65526567000000000000000000000000000000000000000000000000003055307f4e616d6552656700000000000000000000000000000000000000000000000000557f436f6e666967000000000000000000000000000000000000000000000000000073661005d2720d855f1d9976f88bb10c1a3398c77f5573661005d2720d855f1d9976f88bb10c1a3398c77f7f436f6e6669670000000000000000000000000000000000000000000000000000553360455560df806100c56000396000f3007f726567697374657200000000000000000000000000000000000000000000000060003514156053576020355415603257005b335415603e5760003354555b6020353360006000a233602035556020353355005b60007f756e72656769737465720000000000000000000000000000000000000000000060003514156082575033545b1560995733335460006000a2600033545560003355005b60007f6b696c6c00000000000000000000000000000000000000000000000000000000600035141560cb575060455433145b1560d25733ff5b6000355460005260206000f3'
//code needs tobe 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 exmaples can be found here

• examples
• old blog post

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

• 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.createTraceReadStream()
  • vm.loadCompiled(address, src, cb)
• VM debugging hooks
  • vm.onStep

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.

Process a transaction.

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

Processes the block running all of the transaction 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

Process a transaction.

• opts.tx - A Transaction to run.
• opts.block - The block to which the tx belongs. If omited 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 propieties:
  • amountSpent - the amount of ether used by this transaction as a bignum
  • vm - contains the results from running the code, if any, as described in vm.runCode(params, 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 omited a blank block will be used.
• opts.gasLimit - The gas limit for the code given as an Buffer
• opts.account - The Account that the executing code belongs to. If omited 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, a error string containing an error that may have happen or null and a results object with the following propieties
  • gasUsed - the amount of gas as a bignum the code used to run.
  • gasRefund - a Bignum containting the amount of gas to refund from deleting storage values
  • suicide - a boolean, whether the contract commited suicide
  • account - account of the code that ran
  • expcetion - a boolean, whethere or not the contract encoutered an exception
  • exceptionError - a String describing the exception if there was one.
  • return - a Buffer containing the value that was returned by the contract

Generates the Canonical genesis state.

Generate the genesis state.

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

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

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

Creates a vm trace stream. The steam is an Object stream. The object contains

• step - how many steps the current VM has taken
• pc - a Number repersenting the program counter
• depth - the current number of calls deep the contract is
• opcode - the next opcode to be ran
• gas - a bignum standing for the amount of gasLeft
• memory - the memory of the VM as a buffer
• storage - an map of key/values that are in storages
• address - the address of the account
• stack - an Array of Buffers containing the stack

NOTE: using this function defines the onStep hook. So you can't use both at the same time.

Loads a contract defined as a stingified JS function

• address - a Buffer containing the address of the contract
• src - a String of a function to be run when the address is called

The step event is give an Object and done. TheObject` has the following propieties.

• pc - a Number repersenting 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

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

The VM processes state changes at many levels.

• runBlockchain
  • for every block, runBlock
• runBlock
  • for every tx, runTx
  • pay miner and uncles
• runTx
  • checkpoint state
  • runCall
  • revert or commit checkpoint
• runCall
  • transfer value
  • load code
  • runCode
  • materialize created contracts
• runCode
  • iterrate 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.

MPL-2.0