@dexon-foundation/ethereumjs-vm
v2.4.3
Published
An Ethereum VM implementation
Downloads
30
Readme
SYNOPSIS
Implements Ethereum's VM in Javascript.
Fork Support
With the 2.4.x
release series we now start to gradually add Constantinople
features with the
bitwise shifting instructions from EIP 145
making the start being introduced in the v2.4.0
release.
Since both the scope of the Constantinople
hardfork as well as the state of at least some of the EIPs
to be included are not yet finalized, this is only meant for EXPERIMENTAL
purposes, e.g. for developer
tools to give users early access and make themself familiar with dedicated features.
Once scope and EIPs from Constantinople
are final we will target a v2.5.0
release which will officially
introduce Constantinople
support with all the changes bundled together.
Note that from this release on we also introduce new chain
(default: mainnet
) and hardfork
(default: byzantium
) parameters, which make use of our new ethereumjs-common library and in the future will allow
for parallel hardfork support from Byzantium
onwards.
Since hardfork
default might be changed or dropped in future releases, you might want to explicitly
set this to byzantium
on your next update to avoid future unexpected behavior.
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).
INSTALL
npm install ethereumjs-vm
USAGE
var VM = require('ethereumjs-vm')
//create a new VM instance
var vm = new VM()
var code = '7f4e616d65526567000000000000000000000000000000000000000000000000003055307f4e616d6552656700000000000000000000000000000000000000000000000000557f436f6e666967000000000000000000000000000000000000000000000000000073661005d2720d855f1d9976f88bb10c1a3398c77f5573661005d2720d855f1d9976f88bb10c1a3398c77f7f436f6e6669670000000000000000000000000000000000000000000000000000553360455560df806100c56000396000f3007f726567697374657200000000000000000000000000000000000000000000000060003514156053576020355415603257005b335415603e5760003354555b6020353360006000a233602035556020353355005b60007f756e72656769737465720000000000000000000000000000000000000000000060003514156082575033545b1560995733335460006000a2600033545560003355005b60007f6b696c6c00000000000000000000000000000000000000000000000000000000600035141560cb575060455433145b1560d25733ff5b6000355460005260206000f3'
vm.runCode({
code: Buffer.from(code, 'hex'), // code needs to be a Buffer
gasLimit: Buffer.from('ffffffff', 'hex')
}, function(err, results){
console.log('returned: ' + results.return.toString('hex'));
})
Also more examples can be found here
BROWSER
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
.
API
new VM([opts])
Creates a new VM object
opts
stateManager
- A state manager instance (EXPERIMENTAL - unstable API)state
- A merkle-patricia-tree instance for the state tree (ignored ifstateManager
is passed)blockchain
- A blockchain object for storing/retrieving blocks (ignored ifstateManager
is passed)chain
- The chain the VM operates on [default: 'mainnet']hardfork
- Hardfork rules to be used [default: 'byzantium', supported: 'byzantium' (will throw on unsupported)]activatePrecompiles
- Create entries in the state tree for the precompiled contractsallowUnlimitedContractSize
- Allows unlimited contract sizes while debugging. By setting this totrue
, the check for contract size limit of 2KB (see EIP-170) is bypassed. (default:false
; ONLY set totrue
during debugging).
VM
methods
vm.runBlockchain(blockchain, cb)
Process blocks and adds them to the blockchain.
blockchain
- A blockchain that to processcb
- 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
- TheBlock
to processopts.generate
- aBoolean
; whether to generate the stateRoot. If falserunBlock
will check the stateRoot of the block against the Triecb
- The callback. It is given two arguments, anerror
string containing an error that may have happened ornull
, and aresults
object with the following properties:receipts
- the receipts from the transactions in the blockresults
- an Array for results from the transactions in the block
vm.runTx(opts, cb)
Process a transaction.
opts.tx
- ATransaction
to run.opts.block
- The block to which thetx
belongs. If omitted a blank block will be used.cb
- The callback. It is given two arguments, anerror
string containing an error that may have happened ornull
, and aresults
object with the following properties:amountSpent
- the amount of ether used by this transaction as abignum
gasUsed
- the amount of gas as abignum
used by the transactiongasRefund
- the amount of gas as abignum
that was refunded during the transaction (i.e.gasUsed = totalGasConsumed - gasRefund
)vm
- contains the results from running the code, if any, as described invm.runCode(params, cb)
vm.runCode(opts, cb)
Runs EVM code
opts.code
- The EVM code to run given as aBuffer
opts.data
- The input data given as aBuffer
opts.value
- The value in ether that is being sent toopt.address
. Defaults to0
opts.block
- TheBlock
thetx
belongs to. If omitted a blank block will be used.opts.gasLimit
- The gas limit for the code given as aBuffer
opts.account
- TheAccount
that the executing code belongs to. If omitted an empty account will be usedopts.address
- The address of the account that is executing this code. The address should be aBuffer
of bytes. Defaults to0
opts.origin
- The address where the call originated from. The address should be aBuffer
of 20bits. Defaults to0
opts.caller
- The address that ran this code. The address should be aBuffer
of 20bits. Defaults to0
cb
- The callback. It is given two arguments, anerror
string containing an error that may have happened ornull
and aresults
object with the following propertiesgas
- the amount of gas left as abignum
gasUsed
- the amount of gas as abignum
the code used to run.gasRefund
- abignum
containing the amount of gas to refund from deleting storage valuesselfdestruct
- anObject
with keys for accounts that have selfdestructed and values for balance transfer recipient accounts.logs
- anArray
of logs that the contract emitted.exception
-0
if the contract encountered an exception,1
otherwise.exceptionError
- aString
describing the exception if there was one.return
- aBuffer
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
- anObject
whose keys are addresses and values arestring
s 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, otherwise the VM will treat the event handler as a synchronous function.
step
The step
event is given an Object
and callback. The Object
has the following properties.
pc
- aNumber
representing the program counteropcode
- the next opcode to be rangasLeft
- abignum
standing for the amount of gasLeftstack
- anArray
ofBuffers
containing the stack.storageTrie
- the storage trie for the accountaccount
- theAccount
which owns the code running.address
- the address of theaccount
depth
- the current number of calls deep the contract ismemory
- the memory of the VM as abuffer
cache
- The account cache. Contains all the accounts loaded from the trie. It is an instance of functional red black tree
newContract
The newContract
event is given an Object
and callback. The Object
has the following properties.
address
: The created address for the new contract (typeBuffer | Uint8Array
)code
: The deployment bytecode for reference (typeBuffer | Uint8Array
)
beforeBlock
Emits the block that is about to be processed.
afterBlock
Emits the results of the processing a block.
beforeTx
Emits the Transaction that is about to be processed.
afterTx
Emits the result of the transaction.
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
.
TESTING
Running Tests
Tests can be found in the tests
directory, with FORK_CONFIG
set in tests/tester.js
. There are test runners for State tests and Blockchain tests. VM tests are disabled since Frontier gas costs are not supported any more. Tests are then executed by the ethereumjs-testing utility library using the official client-independent Ethereum tests.
For a wider picture about how to use tests to implement EIPs you can have a look at this reddit post or the associated YouTube video introduction to core development with Ethereumjs-vm.
Running different Test Types
Running all the tests:
npm test
Running the State tests:
node ./tests/tester -s
Running the Blockchain tests:
node ./tests/tester -b
State tests and Blockchain tests can also be run against the dist
folder (default: lib
):
node ./tests/tester -b --dist
State tests run significantly faster than Blockchain tests, so it is often a good choice to start fixing State tests.
Running Specific Tests
Running all the blockchain tests in a file:
node ./tests/tester -b --file='randomStatetest303'
Running tests from a specific directory:
node ./tests/tester -b --dir='bcBlockGasLimitTest'
Running a specific state test case:
node ./tests/tester -s --test='stackOverflow'
Only run test cases with selected data
, gas
and/or value
values (see
attribute description in
test docs), provided by the index of the array element in the test transaction
section:
node tests/tester -s --test='CreateCollisionToEmpty' --data=0 --gas=1 --value=0
Run a state test from a specified source file not under the tests
directory:
node ./tests/tester -s --customStateTest='{path_to_file}'
Skipping Tests
There are three types of skip lists (BROKEN
, PERMANENT
and SLOW
) which
can be found in tests/tester.js
. By default tests from all skip lists are omitted.
You can change this behaviour with:
node tests/tester -s --skip=BROKEN,PERMANENT
to skip only the BROKEN
and PERMANENT
tests and include the SLOW
tests.
There are also the keywords NONE
or ALL
for convenience.
It is also possible to only run the tests from the skip lists:
node tests/tester -s --runSkipped=SLOW
Debugging
Local Debugging
For state tests you can use the --jsontrace
flag to output opcode trace information.
Blockchain tests support --debug
to verify the postState:
node ./tests/tester -b --debug --test='ZeroValue_SELFDESTRUCT_ToOneStorageKey_OOGRevert_d0g0v0_EIP158'
All/most State tests are replicated as Blockchain tests in a GeneralStateTests
sub directory in the Ethereum tests repo, so for debugging single test cases the Blockchain test version of the State test can be used.
Debugging Tools
For comparing EVM
traces here are some instructions for setting up pyethereum
to generate corresponding traces for state tests.
Compare TAP output from blockchain/state tests and produces concise diff of the differences between them (example):
curl https://gist.githubusercontent.com/jwasinger/6cef66711b5e0787667ceb3db6bea0dc/raw/0740f03b4ce90d0955d5aba1e0c30ce698c7145a/gistfile1.txt > output-wip-byzantium.txt
curl https://gist.githubusercontent.com/jwasinger/e7004e82426ff0a7137a88d273f11819/raw/66fbd58722747ebe4f7006cee59bbe22461df8eb/gistfile1.txt > output-master.txt
python utils/diffTestOutput.py output-wip-byzantium.txt output-master.txt
An extremely rich and powerful toolbox is the evmlab from holiman
, both for debugging and creating new test cases or example data.