vaporyjs-vm
v1.4.0
Published
an vapory VM implementation
Downloads
21
Readme
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 blocknumberactivatePrecompiles
- create entries in the state tree for the precompiled contracts
VM
methods
vm.runBlockchain(blockchain, cb)
Process a transaction.
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 vapor used by this transaction as abignum
gasUsed
- the amount of gas used by the transactionvm
- 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 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 valuessuicides
- 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 exceptionexceptionError
- 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 counteropcode
- the next opcode to be rangas
- 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
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
.