vm

package
v0.4.1 Latest Latest
Warning

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

 Go to latest Published: Aug 22, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

op_arithmetic.go

op_control.go

op_env.go

op_jump.go

op_memory.go

op_sha3.go

op_stack.go

Index

Constants

This section is empty.

Variables

View Source 
var (
	PrecompileECRecover = common.BytesToAddress([]byte{0x01})
	PrecompileSHA256    = common.BytesToAddress([]byte{0x02})
	PrecompileRIPEMD160 = common.BytesToAddress([]byte{0x03})
	PrecompileIdentity  = common.BytesToAddress([]byte{0x04})
	PrecompileModExp    = common.BytesToAddress([]byte{0x05})
	PrecompileBN256Add  = common.BytesToAddress([]byte{0x06})
	PrecompileBN256Mul  = common.BytesToAddress([]byte{0x07})
	PrecompileBN256Pair = common.BytesToAddress([]byte{0x08})
	PrecompileBlake2F   = common.BytesToAddress([]byte{0x09})
	PrecompileKZG       = common.BytesToAddress([]byte{0x0a})
	PrecompileBLSG1Add  = common.BytesToAddress([]byte{0x0b})
	PrecompileBLSG1MSM  = common.BytesToAddress([]byte{0x0c})
	PrecompileBLSG2Add  = common.BytesToAddress([]byte{0x0d})
	PrecompileBLSG2MSM  = common.BytesToAddress([]byte{0x0e})
	PrecompileBLSPair   = common.BytesToAddress([]byte{0x0f})
	PrecompileBLSMapG1  = common.BytesToAddress([]byte{0x10})
	PrecompileBLSMapG2  = common.BytesToAddress([]byte{0x11})
	PrecompileP256      = common.BytesToAddress([]byte{0x01, 0x00})
)

Precompiled contract addresses

View Source 
var ErrReturnDataOutOfBounds = errors.New("return data out of bounds")

ErrReturnDataOutOfBounds is raised when RETURNDATACOPY reads outside the return-data buffer. EIP-211 defines this as an exceptional halt rather than a zero-padded copy.

View Source 
var ErrWriteProtection = errors.New("write protection")

ErrWriteProtection is raised when a read-only call frame attempts to mutate state.

View Source 
var PrecompiledContracts = map[common.Address]PrecompiledContract{
	PrecompileECRecover: &ecrecover{},
	PrecompileSHA256:    &sha256hash{},
	PrecompileRIPEMD160: &ripemd160hash{},
	PrecompileIdentity:  &dataCopy{},
	PrecompileModExp:    &modExp{},
	PrecompileBN256Add:  &bn256Add{gas: 150},
	PrecompileBN256Mul:  &bn256ScalarMul{gas: 6000},
	PrecompileBN256Pair: &bn256Pairing{baseGas: 45000, perPairGas: 34000},
	PrecompileBlake2F:   &blake2F{},
}

PrecompiledContracts maps addresses to their precompiled contract implementations.

Functions

func ActivePrecompilesForRules added in v0.1.0 

func ActivePrecompilesForRules(rules core.Rules) []common.Address

func ApplyTransaction 

func ApplyTransaction(
	statedb core.StateDB,
	tx *types.Transaction,
	sender common.Address,
	blockNumber *big.Int,
	timestamp uint64,
	coinbase common.Address,
	gasLimit uint64,
) ([]byte, uint64, bool, error)

ApplyTransaction attempts to apply a transaction to the given state database. It handles gas deduction, nonce increment, value transfer, and VM execution.

func ApplyTransactionWithContext 

func ApplyTransactionWithContext(
	statedb core.StateDB,
	tx *types.Transaction,
	sender common.Address,
	ctx *BlockContext,
) ([]byte, uint64, bool, error)

ApplyTransactionWithContext applies a transaction with full block context.

func ApplyTransactionWithContextAndDetailedHook added in v0.0.45 

func ApplyTransactionWithContextAndDetailedHook(
	statedb core.StateDB,
	tx *types.Transaction,
	sender common.Address,
	ctx *BlockContext,
	hook func(TraceStep) bool,
) ([]byte, uint64, bool, error)

ApplyTransactionWithContextAndDetailedHook applies a full transaction while capturing memory and storage context for explainable traces. Callers that only need lightweight opcode identity should use ApplyTransactionWithContextAndHook instead.

func ApplyTransactionWithContextAndHook added in v0.0.22 

func ApplyTransactionWithContextAndHook(
	statedb core.StateDB,
	tx *types.Transaction,
	sender common.Address,
	ctx *BlockContext,
	hook func(TraceStep) bool,
) ([]byte, uint64, bool, error)

ApplyTransactionWithContextAndHook applies a full transaction and emits a transaction-wide opcode trace, including nested CALL and CREATE frames.

func IsPrecompiled 

func IsPrecompiled(addr common.Address) bool

IsPrecompiled returns true if the address is a precompiled contract.

func IsPrecompiledForRules added in v0.1.0 

func IsPrecompiledForRules(addr common.Address, rules core.Rules) bool

func RunPrecompiled 

func RunPrecompiled(addr common.Address, input []byte, suppliedGas uint64) ([]byte, uint64, error)

RunPrecompiled executes a precompiled contract and returns the output and remaining gas.

func RunPrecompiledForRules added in v0.1.0 

func RunPrecompiledForRules(addr common.Address, input []byte, suppliedGas uint64, rules core.Rules) ([]byte, uint64, error)

func SetLogger 

func SetLogger(l zerolog.Logger)

SetLogger allows overriding the package level logger.

Types

type BlockContext 

type BlockContext struct {
	BlockNumber *big.Int
	Timestamp   uint64
	Coinbase    common.Address
	GasLimit    uint64
	BaseFee     *big.Int
	Difficulty  *big.Int
	Random      *big.Int // PREVRANDAO for post-merge
	ChainID     *big.Int
	BlobBaseFee *big.Int
	ChainConfig *core.ChainConfig
	BlockHashes map[uint64]common.Hash
}

BlockContext contains block-level context for transaction execution.

type Interpreter 

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

func New 

func New(code []byte, statedb core.StateDB, address common.Address) *Interpreter

func NewWithCallData 

func NewWithCallData(code []byte, data []byte, statedb core.StateDB, address common.Address) *Interpreter

NewWithCallData creates an interpreter with the provided code and calldata.

func (*Interpreter) Err 

func (i *Interpreter) Err() error

func (*Interpreter) Gas 

func (i *Interpreter) Gas() uint64

Gas returns the remaining gas.

func (*Interpreter) IsReverted 

func (i *Interpreter) IsReverted() bool

func (*Interpreter) Logs 

func (i *Interpreter) Logs() []LogEntry

Logs returns the collected LOG entries emitted during execution.

func (*Interpreter) Memory 

func (i *Interpreter) Memory() *core.Memory

func (*Interpreter) ReturnedCode 

func (i *Interpreter) ReturnedCode() []byte

ReturnedCode returns the byte slice produced by a RETURN opcode. It is primarily used to obtain the runtime bytecode generated during contract creation.

func (*Interpreter) Run 

func (i *Interpreter) Run()

func (*Interpreter) RunWithHook 

func (i *Interpreter) RunWithHook(hook func(step TraceStep) bool)

RunWithHook executes bytecode using the same execution loop as Run and emits a TraceStep before and after each opcode. Returning false from the hook stops execution without executing another opcode.

func (*Interpreter) SetBaseFee 

func (i *Interpreter) SetBaseFee(fee *big.Int)

func (*Interpreter) SetBlobBaseFee 

func (i *Interpreter) SetBlobBaseFee(fee *big.Int)

SetBlobBaseFee sets the blob base fee for the current block (EIP-4844).

func (*Interpreter) SetBlobHashes 

func (i *Interpreter) SetBlobHashes(hashes []common.Hash)

SetBlobHashes sets the versioned blob hashes for EIP-4844 transactions.

func (*Interpreter) SetBlockGasLimit 

func (i *Interpreter) SetBlockGasLimit(limit uint64)

func (*Interpreter) SetBlockHashes added in v0.2.0 

func (i *Interpreter) SetBlockHashes(hashes map[uint64]common.Hash)

SetBlockHashes installs the canonical ancestor hashes available to BLOCKHASH. Entries outside the EVM's 256-block lookup window are ignored by the opcode.

func (*Interpreter) SetBlockNumber 

func (i *Interpreter) SetBlockNumber(num uint64)

SetBlockNumber sets the block number used by environment opcodes like NUMBER.

func (*Interpreter) SetCallData 

func (i *Interpreter) SetCallData(data []byte)

SetCallData sets the calldata that opcodes like CALLDATALOAD operate on.

func (*Interpreter) SetCallValue 

func (i *Interpreter) SetCallValue(val *big.Int)

func (*Interpreter) SetCaller 

func (i *Interpreter) SetCaller(addr common.Address)

func (*Interpreter) SetChainConfig 

func (i *Interpreter) SetChainConfig(cfg *core.ChainConfig)

SetChainConfig sets the chain configuration.

func (*Interpreter) SetChainID 

func (i *Interpreter) SetChainID(id *big.Int)

func (*Interpreter) SetCoinbase 

func (i *Interpreter) SetCoinbase(addr common.Address)

func (*Interpreter) SetDifficulty 

func (i *Interpreter) SetDifficulty(diff *big.Int)

func (*Interpreter) SetGas 

func (i *Interpreter) SetGas(gas uint64)

func (*Interpreter) SetGasPrice 

func (i *Interpreter) SetGasPrice(price *big.Int)

func (*Interpreter) SetMemory 

func (i *Interpreter) SetMemory(m *core.Memory)

func (*Interpreter) SetOrigin 

func (i *Interpreter) SetOrigin(addr common.Address)

func (*Interpreter) SetRandom 

func (i *Interpreter) SetRandom(random *big.Int)

SetRandom sets the PREVRANDAO value for post-merge blocks. The DIFFICULTY opcode returns this value after The Merge.

func (*Interpreter) SetReadOnly added in v0.0.31 

func (i *Interpreter) SetReadOnly(readOnly bool)

SetReadOnly marks the current call frame as static. Child frames inherit the flag so CALL, CALLCODE, and DELEGATECALL cannot escape STATICCALL protection.

func (*Interpreter) SetStack 

func (i *Interpreter) SetStack(s *core.Stack)

func (*Interpreter) SetTimestamp 

func (i *Interpreter) SetTimestamp(ts uint64)

func (*Interpreter) SetTraceContext added in v0.0.22 

func (i *Interpreter) SetTraceContext(hook func(step TraceStep) bool, depth int)

SetTraceContext installs a transaction-wide trace hook. Child interpreters inherit it with an incremented depth so nested calls remain observable.

func (*Interpreter) SetTraceDetails added in v0.0.39 

func (i *Interpreter) SetTraceDetails(enabled bool)

SetTraceDetails enables memory snapshots and storage access context for explainable traces. Lightweight conformance hooks can leave it disabled.

func (*Interpreter) Stack 

func (i *Interpreter) Stack() *core.Stack

type LogEntry 

type LogEntry struct {
	Address string   `json:"address"`
	Topics  []string `json:"topics"`
	Data    string   `json:"data"` // hex encoded 0x prefix
	Index   int      `json:"index"`
}

LogEntry represents a single LOGn emission captured during execution. This is a simplified representation: address is always zero in the current interpreter (no account model yet).

type OpcodeHandler 

type OpcodeHandler func(i *Interpreter, op byte)

OpcodeHandler defines a function that executes a specific opcode

type PrecompiledContract 

type PrecompiledContract interface {
	// RequiredGas calculates the gas cost for running the precompile with the given input.
	RequiredGas(input []byte) uint64
	// Run executes the precompiled contract and returns the output or an error.
	Run(input []byte) ([]byte, error)
}

PrecompiledContract is the interface for native precompiled contract implementations.

type TraceStep 

type TraceStep struct {
	PC         uint64               `json:"pc"`
	Opcode     byte                 `json:"opcode"`
	OpcodeName string               `json:"opcode_name"`
	Stack      []string             `json:"stack"`
	StackSize  int                  `json:"stack_size"`
	Gas        uint64               `json:"gas"`
	Reverted   bool                 `json:"reverted"`
	Halt       bool                 `json:"halt"`
	IsPost     bool                 `json:"is_post"`
	Depth      int                  `json:"depth"`
	Address    string               `json:"address"`
	Error      string               `json:"error,omitempty"`
	Memory     []byte               `json:"-"`
	Storage    []TraceStorageAccess `json:"-"`
}

TraceStep captures a single execution step for external tracing.

type TraceStorageAccess added in v0.0.39 

type TraceStorageAccess struct {
	Kind      string
	Address   string
	Slot      string
	Before    string
	After     string
	Original  string
	Warm      bool
	Transient bool
}

TraceStorageAccess captures the storage context visible before an opcode. It is intentionally part of the internal trace hook rather than StateDB so normal execution does not pay for a separate state-observer abstraction.

Source Files

View all Source files

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.