Documentation ¶
Index ¶
- Constants
- Variables
- type Environment
- type Frame
- type FunctionImport
- type ImportResolver
- type NopResolver
- type Resolver
- type State
- type StateDatabase
- func (stateDB *StateDatabase) AddStateEntry(state *StateEntry, rootState *StateEntry) error
- func (stateDB *StateDatabase) Bytes() []byte
- func (stateDB *StateDatabase) FindMax() (*StateEntry, error)
- func (stateDB *StateDatabase) QueryState(id []byte) (*StateEntry, error)
- func (stateDB *StateDatabase) SetWorkingRoot(rootState *StateEntry)
- func (stateDB *StateDatabase) String() string
- func (stateDB *StateDatabase) WriteToMemory() error
- type StateEntry
- type VirtualMachine
- func (vm *VirtualMachine) AddAndCheckGas(delta uint64) bool
- func (vm *VirtualMachine) Execute()
- func (vm *VirtualMachine) GetCurrentFrame() *Frame
- func (vm *VirtualMachine) GetFunctionExport(key string) (int, bool)
- func (vm *VirtualMachine) GetGlobalExport(key string) (int, bool)
- func (vm *VirtualMachine) Ignite(functionID int, params ...int64)
- func (vm *VirtualMachine) LoadStateDB(id string) error
- func (vm *VirtualMachine) LoadWorkingRoot() error
- func (vm *VirtualMachine) PrintStackTrace()
- func (vm *VirtualMachine) ResetToState(id []byte) error
- func (vm *VirtualMachine) Run(entryID int, params ...int64) (int64, error)
- func (vm *VirtualMachine) RunWithGasLimit(entryID, limit int, params ...int64) (int64, error)
- func (vm *VirtualMachine) SaveState() error
Constants ¶
const ( // DefaultCallStackSize - default call stack size. DefaultCallStackSize = 512 // DefaultPageSize - linear memory page size DefaultPageSize = 65536 )
Variables ¶
var ( // ErrStateAlreadyExists - describes an error regarding a state addition in a state database already containing the given state ErrStateAlreadyExists = errors.New("state already exists in given state DB") // ErrInvalidStateNonce - describes an error regarding a state addition with a nonce less than the last provided in the given state db ErrInvalidStateNonce = errors.New("invalid state nonce") )
var ( // ErrNilStateEntry - describes an error regarding a stateDB of 0 entry length ErrNilStateEntry = errors.New("no state entries found") )
Functions ¶
This section is empty.
Types ¶
type Environment ¶
type Environment struct { EnableJIT bool `json:"JIT"` // Should enable JIT MaxMemoryPages int `json:"maxMemPages"` // Max memory pages at given time MaxTableSize int `json:"maxTableSize"` // Max mem table size at given time MaxValueSlots int `json:"maxValueSlots"` // Max value slots at given time MaxCallStackDepth int `json:"maxCallStackDepth"` // Max call stack length/depth at given time DefaultMemoryPages int `json:"defaultMemPages"` // Default num mem pages at given time DefaultTableSize int `json:"defaultTableSize"` // Preset table size GasLimit uint64 `json:"gasLimit"` // Gas limit DisableFloatingPoint bool `json:"disableFloat"` // Remove float capacity ReturnOnGasLimitExceeded bool `json:"returnOnGasExceed"` // Panic on exceed specified gas limit }
Environment - VM config, vars
func EnvironmentFromBytes ¶
func EnvironmentFromBytes(b []byte) (*Environment, error)
EnvironmentFromBytes - marshal byte array into environment struct
func NewEnvironment ¶
func NewEnvironment(maxMemoryPages int, maxTableSize int, maxValueSlots int, maxCallStackDepth int, defaultMemoryPages int, defaultTableSize int, gasLimit uint64, disableFloatingPoint bool, returnOnGasLimitExceeded bool) *Environment
NewEnvironment - initialize virtual machine config with given params
func ReadEnvironmentFromMemory ¶
func ReadEnvironmentFromMemory() (*Environment, error)
ReadEnvironmentFromMemory - read env from memory
func (*Environment) Bytes ¶
func (environment *Environment) Bytes() []byte
Bytes - get byte array representation of given env
func (*Environment) String ¶
func (environment *Environment) String() string
String - get string representation of given env
func (*Environment) WriteToMemory ¶
func (environment *Environment) WriteToMemory() error
WriteToMemory - write env to memory
type Frame ¶
type Frame struct { FunctionID int // Module function identifier Code []byte // Frame bytecode Regs []int64 // Regs Locals []int64 // Local vrs IP int // IP ReturnReg int // Returning reg Continuation int32 // Continuation }
Frame - call stack frame
func (*Frame) Destroy ¶
func (f *Frame) Destroy(vm *VirtualMachine)
Destroy - destroy a frame; must be called on return
func (*Frame) Init ¶
func (f *Frame) Init(vm *VirtualMachine, functionID int, code compiler.InterpreterCode)
Init - initializes a frame; must be called on `call` and `call_indirect`
type FunctionImport ¶
type FunctionImport func(vm *VirtualMachine) int64
FunctionImport represents the function import type. If len(sig.ReturnTypes) == 0, the return value will be ignored.
type ImportResolver ¶
type ImportResolver interface { ResolveFunc(module, field string) FunctionImport // Func resolver method ResolveGlobal(module, field string) int64 // Global resolver method }
ImportResolver - interface for allowing one to define imports to WebAssembly modules
type NopResolver ¶
type NopResolver struct{}
NopResolver - nil WebAssembly module import resolver.
func (*NopResolver) ResolveFunc ¶
func (r *NopResolver) ResolveFunc(module, field string) FunctionImport
ResolveFunc - panic
func (*NopResolver) ResolveGlobal ¶
func (r *NopResolver) ResolveGlobal(module, field string) int64
ResolveGlobal - panic
type Resolver ¶
type Resolver struct {
// contains filtered or unexported fields
}
Resolver - define imports for WebAssembly modules
func (*Resolver) ResolveFunc ¶
func (r *Resolver) ResolveFunc(module, field string) FunctionImport
ResolveFunc - define a set of import functions that may be called within a WebAssembly module
func (*Resolver) ResolveGlobal ¶
ResolveGlobal - define a set of global variables for use within a WebAssembly module
type State ¶
type State struct { CallStack []Frame `json:"call_stack"` // VM call stack CurrentFrame int `json:"current_frame"` // Current callstack frame Table []uint32 `json:"table"` // VM mem/runtime table Globals []int64 `json:"globals"` // Global vrs Memory []byte `json:"memory"` // Virtual machine memory NumValueSlots int `json:"num_val_slots"` // Num of used value slots Yielded int64 `json:"yielded"` // Did yield InsideExecute bool `json:"inside_execute"` // Inside execute Exited bool `json:"has_exited"` // Did exit ExitError interface{} `json:"exit_err"` // Error on exit ReturnValue int64 `json:"return"` // Return value Gas uint64 `json:"gas"` // Gas usage GasLimitExceeded bool `json:"gas_limit_exceeded"` // Has exceeded given gas limit StateChildren []*StateEntry `json:"children"` // State children ID []byte `json:"ID"` // State ID }
State - state node
type StateDatabase ¶
type StateDatabase struct { States []*StateEntry `json:"states"` // All states (not in tree) StateRoot *StateEntry `json:"root"` // VM state root WorkingRoot *StateEntry `json:"working_root"` // Working VM state root MerkleRoot []byte `json:"merkle_root"` // State merkle root ID []byte `json:"ID"` // State DB ID }
StateDatabase - database holding vm states
func NewStateDatabase ¶
func NewStateDatabase(rootState *StateEntry) *StateDatabase
NewStateDatabase - initialize state DB with given root
func ReadStateDBFromMemory ¶
func ReadStateDBFromMemory(id string) (*StateDatabase, error)
ReadStateDBFromMemory - read state database from persistent memory
func StateDatabaseFromBytes ¶
func StateDatabaseFromBytes(b []byte) (*StateDatabase, error)
StateDatabaseFromBytes - marshal given byte array into state database
func (*StateDatabase) AddStateEntry ¶
func (stateDB *StateDatabase) AddStateEntry(state *StateEntry, rootState *StateEntry) error
AddStateEntry - add state entry to given state database at given root state
func (*StateDatabase) Bytes ¶
func (stateDB *StateDatabase) Bytes() []byte
Bytes - get byte representation of db
func (*StateDatabase) FindMax ¶
func (stateDB *StateDatabase) FindMax() (*StateEntry, error)
FindMax - find state entry with max nonce value
func (*StateDatabase) QueryState ¶
func (stateDB *StateDatabase) QueryState(id []byte) (*StateEntry, error)
QueryState - query state in db by identifier
func (*StateDatabase) SetWorkingRoot ¶
func (stateDB *StateDatabase) SetWorkingRoot(rootState *StateEntry)
SetWorkingRoot - set current working root (similar to a "git checkout COMMIT_HASH")
func (*StateDatabase) String ¶
func (stateDB *StateDatabase) String() string
String - get string representation of db
func (*StateDatabase) WriteToMemory ¶
func (stateDB *StateDatabase) WriteToMemory() error
WriteToMemory - write state database to persistent storage with given data path
type StateEntry ¶
type StateEntry struct { State *State `json:"state"` // State Nonce uint64 `json:"nonce"` // Entry nonce ID []byte `json:"ID"` // Entry ID }
StateEntry - state entry header
func NewStateEntry ¶
func NewStateEntry(callStack []Frame, currentFrame int, table []uint32, globals []int64, memory []byte, numValueSlots int, yielded int64, insideExecute bool, exited bool, exitError interface{}, returnValue int64, gas uint64, gasLimitExceeded bool, nonce uint64) *StateEntry
NewStateEntry - initialize new state entry
func (*StateEntry) Bytes ¶
func (stateEntry *StateEntry) Bytes() []byte
Bytes - get byte representation of entry
func (*StateEntry) FindMax ¶
func (stateEntry *StateEntry) FindMax() (*StateEntry, error)
FindMax - find state child of greatest nonce value
func (*StateEntry) String ¶
func (stateEntry *StateEntry) String() string
String - get string representation of entry
type VirtualMachine ¶
type VirtualMachine struct { Environment Environment `json:"environment"` // VM config Module *compiler.Module // Loaded web-assembly module FunctionCode []compiler.InterpreterCode // Func bytecode FunctionImports []FunctionImport // Import funcs CallStack []Frame // VM call stack CurrentFrame int // Current callstack frame Table []uint32 // VM mem/runtime table Globals []int64 // Global vrs Memory []byte // Virtual machine memory NumValueSlots int // Num of used value slots Yielded int64 // Did yield InsideExecute bool // Inside execute Delegate func() // Delegate call Exited bool // Did exit ExitError interface{} // Error on exit ReturnValue int64 // Return value Gas uint64 // Gas usage GasLimitExceeded bool // Has exceeded given gas limit StateDB *StateDatabase // State database }
VirtualMachine - container holding VM config, metadata
func NewVirtualMachine ¶
func NewVirtualMachine(code []byte, config Environment, impResolver ImportResolver, gasPolicy compiler.GasPolicy) (_retVM *VirtualMachine, retErr error)
NewVirtualMachine - instantiate a virtual machine for a given WebAssembly module, with specific execution options specified under a VMConfig, and a WebAssembly module import resolver
func (*VirtualMachine) AddAndCheckGas ¶
func (vm *VirtualMachine) AddAndCheckGas(delta uint64) bool
AddAndCheckGas - add and check gas
func (*VirtualMachine) Execute ¶
func (vm *VirtualMachine) Execute()
Execute - start the virtual machines main instruction processing loop. May return at any point and is guaranteed to return at least once every 10000 instructions. Caller is responsible for detecting VM status in a loop
func (*VirtualMachine) GetCurrentFrame ¶
func (vm *VirtualMachine) GetCurrentFrame() *Frame
GetCurrentFrame - return the current frame
func (*VirtualMachine) GetFunctionExport ¶
func (vm *VirtualMachine) GetFunctionExport(key string) (int, bool)
GetFunctionExport - return the function export with the given name
func (*VirtualMachine) GetGlobalExport ¶
func (vm *VirtualMachine) GetGlobalExport(key string) (int, bool)
GetGlobalExport - return the global export with the given name
func (*VirtualMachine) Ignite ¶
func (vm *VirtualMachine) Ignite(functionID int, params ...int64)
Ignite - initialize the first call frame
func (*VirtualMachine) LoadStateDB ¶
func (vm *VirtualMachine) LoadStateDB(id string) error
LoadStateDB - load state database
func (*VirtualMachine) LoadWorkingRoot ¶
func (vm *VirtualMachine) LoadWorkingRoot() error
LoadWorkingRoot - load last saved state
func (*VirtualMachine) PrintStackTrace ¶
func (vm *VirtualMachine) PrintStackTrace()
PrintStackTrace - print the entire VM stack trace for debugging
func (*VirtualMachine) ResetToState ¶
func (vm *VirtualMachine) ResetToState(id []byte) error
ResetToState - revert vm state to given state with ID
func (*VirtualMachine) Run ¶
func (vm *VirtualMachine) Run(entryID int, params ...int64) (int64, error)
Run runs a WebAssembly modules function denoted by its ID with a specified set of parameters. Panics on logical errors.
func (*VirtualMachine) RunWithGasLimit ¶
func (vm *VirtualMachine) RunWithGasLimit(entryID, limit int, params ...int64) (int64, error)
RunWithGasLimit - run a WebAssembly modules function denoted by its ID with a specified set of parameters for a specified amount of instructions (also known as gas) denoted by `limit`
func (*VirtualMachine) SaveState ¶
func (vm *VirtualMachine) SaveState() error
SaveState - save state