vm

package
v0.0.0-...-886a677 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 8, 2024 License: MIT Imports: 26 Imported by: 3

Documentation

Index

Constants

View Source 
const (
	// MaxInvocationStackSize is the maximum size of an invocation stack.
	MaxInvocationStackSize = 1024

	// MaxTryNestingDepth is the maximum level of TRY nesting allowed,
	// that is you can't have more exception handling contexts than this.
	MaxTryNestingDepth = 16

	// MaxStackSize is the maximum number of items allowed to be
	// on all stacks at once.
	MaxStackSize = 2 * 1024
)
View Source 
const MaxMultisigKeys = 1024

MaxMultisigKeys is the maximum number of keys allowed for correct multisig contract.

Variables

View Source 
var ErrMultiRet = errors.New("multiple return values in a cross-contract call")

ErrMultiRet is returned when caller does not expect multiple return values from callee.

Functions

func CheckMultisigPar 

func CheckMultisigPar(v *VM, curve elliptic.Curve, h []byte, pkeys [][]byte, sigs [][]byte) bool

CheckMultisigPar checks if the sigs contains sufficient valid signatures.

func DynamicOnUnload 

func DynamicOnUnload(v *VM, ctx *Context, commit bool) error

DynamicOnUnload implements OnUnload script for dynamic calls, if no exception has occurred it checks that the context has exactly 0 (in which case a `Null` is pushed) or 1 returned value.

func GetInteropID 

func GetInteropID(parameter []byte) uint32

GetInteropID converts instruction parameter to an interop ID.

func IsMultiSigContract 

func IsMultiSigContract(script []byte) bool

IsMultiSigContract checks whether the passed script is a multi-signature contract.

func IsScriptCorrect 

func IsScriptCorrect(script []byte, methods bitfield.Field) error

IsScriptCorrect checks the script for errors and mask provided for correctness wrt instruction boundaries. Normally, it returns nil, but it can return some specific error if there is any.

func IsSignatureContract 

func IsSignatureContract(script []byte) bool

IsSignatureContract checks whether the passed script is a signature check contract.

func IsStandardContract 

func IsStandardContract(script []byte) bool

IsStandardContract checks whether the passed script is a signature or multi-signature contract.

func ParseMultiSigContract 

func ParseMultiSigContract(script []byte) (int, [][]byte, bool)

ParseMultiSigContract returns the number of signatures and a list of public keys from the verification script of the contract.

func ParseSignatureContract 

func ParseSignatureContract(script []byte) ([]byte, bool)

ParseSignatureContract parses a simple signature contract and returns a public key.

Types

type Context 

type Context struct {
	// contains filtered or unexported fields
}

Context represents the current execution context of the VM.

func NewContext 

func NewContext(b []byte) *Context

NewContext returns a new Context object.

func NewContextWithParams 

func NewContextWithParams(b []byte, rvcount int, pos int) *Context

NewContextWithParams creates new Context objects using script, parameter count, return value count and initial position in script.

func (*Context) BreakPoints 

func (c *Context) BreakPoints() []int

BreakPoints returns the current set of Context's breakpoints.

func (*Context) CurrInstr 

func (c *Context) CurrInstr() (int, opcode.Opcode)

CurrInstr returns the current instruction and opcode.

func (*Context) DumpArgumentsSlot 

func (c *Context) DumpArgumentsSlot() string

DumpArgumentsSlot returns json formatted representation of the given slot.

func (*Context) DumpLocalSlot 

func (c *Context) DumpLocalSlot() string

DumpLocalSlot returns json formatted representation of the given slot.

func (*Context) DumpStaticSlot 

func (c *Context) DumpStaticSlot() string

DumpStaticSlot returns json formatted representation of the given slot.

func (*Context) Estack 

func (c *Context) Estack() *Stack

Estack returns the evaluation stack of c.

func (*Context) GetCallFlags 

func (c *Context) GetCallFlags() callflag.CallFlag

GetCallFlags returns the calling flags which the context was created with.

func (*Context) GetNEF 

func (c *Context) GetNEF() *nef.File

GetNEF returns NEF structure used by this context if it's present.

func (*Context) IP 

func (c *Context) IP() int

IP returns the current instruction offset in the context script.

func (*Context) IsCalledByEntry 

func (c *Context) IsCalledByEntry() bool

IsCalledByEntry checks parent script contexts and return true if the current one is an entry script (the first loaded into the VM) or one called by it.

func (*Context) IsDeployed 

func (c *Context) IsDeployed() bool

IsDeployed returns whether this context contains a deployed contract.

func (*Context) Jump 

func (c *Context) Jump(pos int)

Jump unconditionally moves the next instruction pointer to the specified location.

func (*Context) LenInstr 

func (c *Context) LenInstr() int

LenInstr returns the number of instructions loaded.

func (*Context) MarshalJSON 

func (c *Context) MarshalJSON() ([]byte, error)

MarshalJSON implements the JSON marshalling interface.

func (*Context) Next 

func (c *Context) Next() (opcode.Opcode, []byte, error)

Next returns the next instruction to execute with its parameter if any. The parameter is not copied and shouldn't be written to. After its invocation, the instruction pointer points to the instruction returned.

func (*Context) NextIP 

func (c *Context) NextIP() int

NextIP returns the next instruction pointer.

func (*Context) NextInstr 

func (c *Context) NextInstr() (int, opcode.Opcode)

NextInstr returns the next instruction and opcode.

func (*Context) NumOfReturnVals 

func (c *Context) NumOfReturnVals() int

NumOfReturnVals returns the number of return values expected from this context.

func (*Context) Program 

func (c *Context) Program() []byte

Program returns the loaded program.

func (*Context) ScriptHash 

func (c *Context) ScriptHash() util.Uint160

ScriptHash returns a hash of the script in the current context.

type ContextUnloadCallback 

type ContextUnloadCallback func(v *VM, ctx *Context, commit bool) error

ContextUnloadCallback is a callback method used on context unloading from istack.

type Element 

type Element struct {
	// contains filtered or unexported fields
}

Element represents an element on the stack. Technically, it's a wrapper around stackitem.Item interface to provide some API simplification for the VM.

func NewElement 

func NewElement(v any) Element

NewElement returns a new Element object, with its underlying value inferred to the corresponding type.

func (Element) Array 

func (e Element) Array() []stackitem.Item

Array attempts to get the underlying value of the element as an array of other items. It will panic if the item type is different, which will be caught by the VM.

func (Element) BigInt 

func (e Element) BigInt() *big.Int

BigInt attempts to get the underlying value of the element as a big integer. It will panic if the assertion has failed, which will be caught by the VM.

func (Element) Bool 

func (e Element) Bool() bool

Bool converts the underlying value of the element to a boolean if it's possible to do so. Otherwise, it will panic.

func (Element) Bytes 

func (e Element) Bytes() []byte

Bytes attempts to get the underlying value of the element as a byte array. It will panic if the assertion has failed, which will be caught by the VM.

func (Element) BytesOrNil 

func (e Element) BytesOrNil() []byte

BytesOrNil attempts to get the underlying value of the element as a byte array or nil. It will panic if the assertion has failed, which will be caught by the VM.

func (Element) Interop 

func (e Element) Interop() *stackitem.Interop

Interop attempts to get the underlying value of the element as an interop item.

func (Element) Item 

func (e Element) Item() stackitem.Item

Item returns the Item contained in the element.

func (Element) String 

func (e Element) String() string

String attempts to get a string from the element value. It is assumed to be used in interops and panics if the string is not a valid UTF-8 byte sequence.

func (Element) Value 

func (e Element) Value() any

Value returns the value of the Item contained in the element.

type Stack 

type Stack struct {
	// contains filtered or unexported fields
}

Stack represents a Stack backed by a slice of Elements.

func NewStack 

func NewStack(n string) *Stack

NewStack returns a new stack name by the given name.

func (*Stack) Back 

func (s *Stack) Back() Element

Back returns the element at the end of the stack. Nil if the stack is empty.

func (*Stack) Clear 

func (s *Stack) Clear()

Clear clears all elements on the stack and set its length to 0.

func (*Stack) Dup 

func (s *Stack) Dup(n int) Element

Dup duplicates and returns the element at position n. Dup is used for copying elements on the top of its own stack. 

s.Push(s.Peek(0)) // will result in unexpected behavior.
s.Push(s.Dup(0)) // is the correct approach.

func (*Stack) InsertAt 

func (s *Stack) InsertAt(e Element, n int)

InsertAt inserts the given item (n) deep on the stack. Be very careful using it and _always_ check n before invocation as it will panic otherwise.

func (*Stack) Iter 

func (s *Stack) Iter(f func(Element))

Iter iterates over all elements int the stack, starting from the top of the stack. 

s.Iter(func(elem *Element) {
	// do something with the element.
})

func (*Stack) IterBack 

func (s *Stack) IterBack(f func(Element))

IterBack iterates over all elements of the stack, starting from the bottom of the stack. 

s.IterBack(func(elem *Element) {
	// do something with the element.
})

func (*Stack) Len 

func (s *Stack) Len() int

Len returns the number of elements that are on the stack.

func (*Stack) MarshalJSON 

func (s *Stack) MarshalJSON() ([]byte, error)

MarshalJSON implements the JSON marshalling interface.

func (*Stack) Peek 

func (s *Stack) Peek(n int) Element

Peek returns the element (n) far in the stack beginning from the top of the stack. For n == 0 it's, effectively, the same as Top, but it'll panic if the stack is empty.

func (*Stack) Pop 

func (s *Stack) Pop() Element

Pop removes and returns the element on top of the stack. It panics if the stack is empty.

func (*Stack) PopSigElements 

func (s *Stack) PopSigElements() ([][]byte, error)

PopSigElements pops keys or signatures from the stack as needed for CHECKMULTISIG.

func (*Stack) Push 

func (s *Stack) Push(e Element)

Push pushes the given element on the stack.

func (*Stack) PushItem 

func (s *Stack) PushItem(i stackitem.Item)

PushItem pushes an Item to the stack.

func (*Stack) PushVal 

func (s *Stack) PushVal(v any)

PushVal pushes the given value on the stack. It will infer the underlying Item to its corresponding type.

func (*Stack) RemoveAt 

func (s *Stack) RemoveAt(n int) Element

RemoveAt removes the element (n) deep on the stack beginning from the top of the stack. It panics if called with out of bounds n.

func (*Stack) ReverseTop 

func (s *Stack) ReverseTop(n int) error

ReverseTop reverses top n items of the stack.

func (*Stack) Roll 

func (s *Stack) Roll(n int) error

Roll brings an item with the given index to the top of the stack moving all other elements down accordingly. It does all of that without popping and pushing elements.

func (*Stack) Swap 

func (s *Stack) Swap(n1, n2 int) error

Swap swaps two elements on the stack without popping and pushing them.

func (*Stack) ToArray 

func (s *Stack) ToArray() []stackitem.Item

ToArray converts the stack to an array of stackitems with the top item being the last.

func (*Stack) Top 

func (s *Stack) Top() Element

Top returns the element on top of the stack. Nil if the stack is empty.

type StateMessage 

type StateMessage string

StateMessage is a vm state message which could be used as an additional info, for example by cli.

type SyscallHandler 

type SyscallHandler = func(*VM, uint32) error

SyscallHandler is a type for syscall handler.

type VM 

type VM struct {
	GasLimit int64

	// SyscallHandler handles SYSCALL opcode.
	SyscallHandler func(v *VM, id uint32) error

	// LoadToken handles CALLT opcode.
	LoadToken func(id int32) error
	// contains filtered or unexported fields
}

VM represents the virtual machine.

func New 

func New() *VM

New returns a new VM object ready to load AVM bytecode scripts.

func NewWithTrigger 

func NewWithTrigger(t trigger.Type) *VM

NewWithTrigger returns a new VM for executions triggered by t.

func (*VM) AddBreakPoint 

func (v *VM) AddBreakPoint(n int)

AddBreakPoint adds a breakpoint to the current context.

func (*VM) AddBreakPointRel 

func (v *VM) AddBreakPointRel(n int)

AddBreakPointRel adds a breakpoint relative to the current instruction pointer.

func (*VM) AddGas 

func (v *VM) AddGas(gas int64) bool

AddGas consumes the specified amount of gas. It returns true if gas limit wasn't exceeded.

func (*VM) AtBreakpoint 

func (v *VM) AtBreakpoint() bool

AtBreakpoint returns whether the VM is at breakpoint.

func (*VM) Call 

func (v *VM) Call(offset int)

Call calls a method by offset using the new execution context.

func (*VM) Context 

func (v *VM) Context() *Context

Context returns the current executed context. Nil if there is no context, which implies no program is loaded.

func (*VM) ContractHasTryBlock 

func (v *VM) ContractHasTryBlock() bool

ContractHasTryBlock checks if the currently executing contract has a TRY block in one of its contexts.

func (*VM) DumpEStack 

func (v *VM) DumpEStack() string

DumpEStack returns json formatted representation of the execution stack.

func (*VM) DumpIStack 

func (v *VM) DumpIStack() string

DumpIStack returns json formatted representation of the invocation stack.

func (*VM) EnableInvocationTree 

func (v *VM) EnableInvocationTree()

CollectInvocationTree enables collecting invocation tree data.

func (*VM) Estack 

func (v *VM) Estack() *Stack

Estack returns the evaluation stack, so interop hooks can utilize this.

func (*VM) GasConsumed 

func (v *VM) GasConsumed() int64

GasConsumed returns the amount of GAS consumed during execution.

func (*VM) GetCallingScriptHash 

func (v *VM) GetCallingScriptHash() util.Uint160

GetCallingScriptHash implements the ScriptHashGetter interface.

func (*VM) GetCurrentScriptHash 

func (v *VM) GetCurrentScriptHash() util.Uint160

GetCurrentScriptHash implements the ScriptHashGetter interface.

func (*VM) GetEntryScriptHash 

func (v *VM) GetEntryScriptHash() util.Uint160

GetEntryScriptHash implements the ScriptHashGetter interface.

func (*VM) GetInvocationTree 

func (v *VM) GetInvocationTree() *invocations.Tree

GetInvocationTree returns the current invocation tree structure.

func (*VM) HasFailed 

func (v *VM) HasFailed() bool

HasFailed returns whether the VM is in the failed state now. Usually, it's used to check status after Run.

func (*VM) HasHalted 

func (v *VM) HasHalted() bool

HasHalted returns whether the VM is in the Halt state.

func (*VM) HasStopped 

func (v *VM) HasStopped() bool

HasStopped returns whether the VM is in the Halt or Failed state.

func (*VM) Istack 

func (v *VM) Istack() []*Context

Istack returns the invocation stack, so interop hooks can utilize this.

func (*VM) Load 

func (v *VM) Load(prog []byte)

Load initializes the VM with the program given.

func (*VM) LoadDynamicScript 

func (v *VM) LoadDynamicScript(b []byte, f callflag.CallFlag)

LoadDynamicScript loads the given script with the given flags. This script is considered to be dynamic, it can either return no value at all or return exactly one value.

func (*VM) LoadFileWithFlags 

func (v *VM) LoadFileWithFlags(path string, f callflag.CallFlag) error

LoadFileWithFlags loads a program in NEF format from the given path, ready to execute it.

func (*VM) LoadNEFMethod 

func (v *VM) LoadNEFMethod(exe *nef.File, caller util.Uint160, hash util.Uint160, f callflag.CallFlag,
	hasReturn bool, methodOff int, initOff int, onContextUnload ContextUnloadCallback)

LoadNEFMethod allows to create a context to execute a method from the NEF file with the specified caller and executing hash, call flags, return value, method and _initialize offsets.

func (*VM) LoadScript 

func (v *VM) LoadScript(b []byte)

LoadScript loads a script from the internal script table. It will immediately push a new context created from this script to the invocation stack and starts executing it.

func (*VM) LoadScriptWithFlags 

func (v *VM) LoadScriptWithFlags(b []byte, f callflag.CallFlag)

LoadScriptWithFlags loads script and sets call flag to f.

func (*VM) LoadScriptWithHash 

func (v *VM) LoadScriptWithHash(b []byte, hash util.Uint160, f callflag.CallFlag)

LoadScriptWithHash is similar to the LoadScriptWithFlags method, but it also loads the given script hash directly into the Context to avoid its recalculations and to make it possible to override it for deployed contracts with special hashes (the function assumes that it is used for deployed contracts setting context's parameters accordingly). It's up to the user of this function to make sure the script and hash match each other.

func (*VM) LoadWithFlags 

func (v *VM) LoadWithFlags(prog []byte, f callflag.CallFlag)

LoadWithFlags initializes the VM with the program and flags given.

func (*VM) PopResult 

func (v *VM) PopResult() any

PopResult is used to pop the first item of the evaluation stack. This allows us to test the compiler and the vm in a bi-directional way.

func (*VM) PrintOps 

func (v *VM) PrintOps(out io.Writer)

PrintOps prints the opcodes of the current loaded program to stdout.

func (*VM) PushContextScriptHash 

func (v *VM) PushContextScriptHash(n int) error

PushContextScriptHash pushes the script hash of the invocation stack element number n to the evaluation stack.

func (*VM) Ready 

func (v *VM) Ready() bool

Ready returns true if the VM is ready to execute the loaded program. It will return false if no program is loaded.

func (*VM) Reset 

func (v *VM) Reset(t trigger.Type)

Reset allows to reuse existing VM for subsequent executions making them somewhat more efficient. It reuses invocation and evaluation stacks as well as VM structure itself.

func (*VM) Run 

func (v *VM) Run() error

Run starts execution of the loaded program.

func (*VM) SetPriceGetter 

func (v *VM) SetPriceGetter(f func(opcode.Opcode, []byte) int64)

SetPriceGetter registers the given PriceGetterFunc in v. f accepts vm's Context, current instruction and instruction parameter.

func (*VM) State 

func (v *VM) State() vmstate.State

State returns the state for the VM.

func (*VM) Step 

func (v *VM) Step() error

Step 1 instruction in the program.

func (*VM) StepInto 

func (v *VM) StepInto() error

StepInto behaves the same as “step over” in case the line does not contain a function. Otherwise, the debugger will enter the called function and continue line-by-line debugging there.

func (*VM) StepOut 

func (v *VM) StepOut() error

StepOut takes the debugger to the line where the current function was called.

func (*VM) StepOver 

func (v *VM) StepOver() error

StepOver takes the debugger to the line that will step over the given line. If the line contains a function, the function will be executed and the result is returned without debugging each line.

Source Files

View all Source files

Directories

Path Synopsis
Package vmstate contains a set of VM state flags along with appropriate type.
 Package vmstate contains a set of VM state flags along with appropriate type.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.