SYNOPSIS
Implements Ethereum's VM in JS
CONTACT
Scrollback or #ethereumjs on freenode
INSTALL
npm install ethereumjs-vm
USAGE
var VM = require('ethereumjs-vm')
var vm = new VM()
var code = '7f4e616d65526567000000000000000000000000000000000000000000000000003055307f4e616d6552656700000000000000000000000000000000000000000000000000557f436f6e666967000000000000000000000000000000000000000000000000000073661005d2720d855f1d9976f88bb10c1a3398c77f5573661005d2720d855f1d9976f88bb10c1a3398c77f7f436f6e6669670000000000000000000000000000000000000000000000000000553360455560df806100c56000396000f3007f726567697374657200000000000000000000000000000000000000000000000060003514156053576020355415603257005b335415603e5760003354555b6020353360006000a233602035556020353355005b60007f756e72656769737465720000000000000000000000000000000000000000000060003514156082575033545b1560995733335460006000a2600033545560003355005b60007f6b696c6c00000000000000000000000000000000000000000000000000000000600035141560cb575060455433145b1560d25733ff5b6000355460005260206000f3'
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
BOWSER
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
API
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 trieblockchain
- an instance of the Blockchain
If no blockchain is given a fake blockchain will be used.
VM
methods
vm.runBlock(opts, cb)
Processes the block
running all of the transaction it contains and updating the miner's account.
opts.block
- The Block
to processcb
- The callback
vm.runTx(opts, cb)
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)
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 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 usedopts.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 valuessuicide
- a boolean
, whether the contract commited suicideaccount
- account of the code that ranexpcetion
- a boolean
, whethere or not the contract encoutered an exceptionexceptionError
- a String
describing the exception if there was one.return
- a Buffer
containing the value that was returned by the contract
vm.loadPrecompiled(address, src, cb)
Loads a contract defined as a stingified JS function
address
- a Buffer
containing the address of the contractsrc
- a String
of a function to be run when the address
is called
vm.loadAllPrecompiled(cb)
Loads all the precompile contracts are in the precompiled dir
vm.generateCanonicalGenesis(cb)
Generates the Canonical genesis state.
vm.generateGenesis(genesisData, cb)
Generate the genesis state.
genesisData
- an Object
whose keys are addresses and values are a string
s representing initail allocation of ether.cb
- The callback
var genesisData = {
"51ba59315b3a95761d0863b05ccc7a7f54703d99": "1606938044258990275541962092341162602522202993782792835301376",
"e4157b34ea9615cfbde6b4fda419828124b70c78": "1606938044258990275541962092341162602522202993782792835301376"
}
vm.generateGenesis(genesisData, function(){
conosle.log('generation done');
})
vm.createTraceReadStream()
Creates a vm trace stream. The steam is an Object
stream. The object contains
step
- how many steps the current VM has takenpc
- a Number
repersenting the program counterdepth
- the current number of calls deep the contract isopcode
- the next opcode to be rangas
- a bignum
standing for the amount of gasLeftmemory
- the memory of the VM as a buffer
storage
- an map of key/values that are in storagesaddress
- 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.
VM
debugging hook
vm.onStep
When onStep
is assigned a function the VM will run that function at the begining of each opcode. The onStep
function is give an Object
and done
. done
must be called before the VM contunies. The Object
has the following propieties.
pc
- a Number
repersenting the program counteropcode
- the next opcode to be rangas
- a bignum
standing for the amount of gasLeftstack
- an Array
of Buffers
containing the stack.storageTrie
- the storage trie for the accountaccount
- the Account
which owns the code running.address
- the address of the account
depth
- the current number of calls deep the contract ismemory
- the memory of the VM as a buffer
TESTING
npm test
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