SYNOPSIS
Implements Vapory's VM in JS
INSTALL
npm install vaporyjs-vm
USAGE
var VM = require('vaporyjs-vm')
//create a new VM instance
var vm = new VM()
var code = '7f4e616d65526567000000000000000000000000000000000000000000000000003055307f4e616d6552656700000000000000000000000000000000000000000000000000557f436f6e666967000000000000000000000000000000000000000000000000000073661005d2720d855f1d9976f88bb10c1a3398c77f5573661005d2720d855f1d9976f88bb10c1a3398c77f7f436f6e6669670000000000000000000000000000000000000000000000000000553360455560df806100c56000396000f3007f726567697374657200000000000000000000000000000000000000000000000060003514156053576020355415603257005b335415603e5760003354555b6020353360006000a233602035556020353355005b60007f756e72656769737465720000000000000000000000000000000000000000000060003514156082575033545b1560995733335460006000a2600033545560003355005b60007f6b696c6c00000000000000000000000000000000000000000000000000000000600035141560cb575060455433145b1560d25733ff5b6000355460005260206000f3'
//code needs to be a buffer
code = Buffer.from(code, 'hex')
vm.runCode({
code: code,
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 run npm run build
. This will give you a global variable VapVM
to use. The standalone file will be at ./dist/vaporyjs-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 theVM
will create an in memory trie. -
blockchain
- an instance of theBlockchain
If no blockchain is given a fake blockchain will be used. -
opts
-
enableHomestead
- a boolean that overrides the homestead settings based on blocknumber -
activatePrecompiles
- create entries in the state tree for the precompiled contracts
-
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
- TheBlock
to process -
opts.generate
- aBoolean
; whether to generate the stateRoot. If falserunBlock
will check the stateRoot of the block against the Trie -
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:-
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
- 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 vapor used by this transaction as abignum
-
gasUsed
- the amount of gas used by the transaction -
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 vapor 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 used -
opts.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 properties-
gas
- 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 values -
suicides
- anArray
of accounts that have suicided. -
suicideTo
- the account that the suicide refund should go to. -
logs
- anArray
of logs that the contract emitted. -
exception
- aboolean
, whether or not the contract encountered an exception -
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 vapor. -
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
- aNumber
representing the program counter -
opcode
- the next opcode to be ran -
gas
- abignum
standing for the amount of gasLeft -
stack
- anArray
ofBuffers
containing the stack. -
storageTrie
- the storage trie for the account -
account
- theAccount
which owns the code running. -
address
- the address of theaccount
-
depth
- the current number of calls deep the contract is -
memory
- 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
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
.