Skip to content

Latest commit

 

History

History
216 lines (140 loc) · 9.65 KB

README.md

File metadata and controls

216 lines (140 loc) · 9.65 KB
Raw

SYNOPSIS

NPM Package Build Status Coverage Status Gitter or #ethereumjs on freenode

js-standard-style

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

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

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}'

Running tests with a reporter/formatter

npm run formatTest -t [npm script name OR node command] will pipe to tap-spec by default.

To pipe the results of the API tests through tap-spec:

npm run formatTest -- -t testAPI

To pipe the results of tests run with a node command through tap-spec:

npm run formatTest -- -t "./tests/tester -b --dir='bcBlockGasLimitTest'"

The -with flag allows the specification of a formatter of your choosing:

npm install -g tap-mocha-reporter npm run formatTest -- -t testAPI -with 'tap-mocha-reporter json'

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

CI Test Integration

Tests are run on CircleCI on every PR, configuration can be found in .circleci/config.yml.

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.

LICENSE

MPL-2.0