SealEVM

README

SealEVM

SealEVM is a standalone EVM executor, aiming to create a completely decoupled EVM execution environment from the storage system, to add EVM support for any blockchain system.

The current version has achieved decoupling from the storage system through interfaces and caching, supporting the addition of EVM support to any blockchain system implemented in Golang.

⚠️ Note: Because SealEVM pursues decoupled and independent operation, it only ensures that the calculation and execution process behavior of opcodes are consistent with EVM, but other characteristics of Ethereum, such as GAS consumption and precompiled contracts, are not completely consistent with Ethereum.

• 中文

---

Example Code

The example directory provides a simple reference example of SealEVM usage. This example uses memory as external storage, demonstrating simple functions like contract deployment, invocation, and variable reading.

⚠️ Note: The example in the example directory is only a simple demonstration of code usage and should not be used in any actual commercial or production environment.

Main Structures and Interfaces

EVM Instance Configuration Parameters

type EVMParam struct {
    MaxStackDepth  int // Maximum stack depth
    ExternalStore  storage.IExternalStorage // External storage interface, see the following sections for details
    ResultCallback EVMResultCallback // Callback function after EVM execution is completed
    Context        *environment.Context // Context for EVM execution, read the source code for internal field meaning
    GasSetting     *gasSetting.Setting // Gas fee settings, use default settings if nil
}

External Storage Interface

SealEVM interacts with external storage through this interface to achieve necessary contract reading, state reading, address creation, and other functions.

type IExternalStorage interface {
    // Retrieve stored contracts
    GetContract(address types.Address) (*environment.Contract, error)
    
    // Get block hash at a specified height
    GetBlockHash(block *evmInt256.Int) (*evmInt256.Int, error)
    
    // Check if a contract exists
    ContractExist(address types.Address) bool
    
    // Check if an address is empty (see EIP161 for the definition of empty)
    ContractEmpty(address types.Address) bool
    
    // Return the hash value of the given contract code
    HashOfCode(code []byte) types.Hash
    
    // Return the created contract address based on parameters, used by opcode CREATE (0xF0)
    CreateAddress(caller types.Address, tx environment.Transaction) types.Address
    
    // Return the created contract address based on parameters, used by opcode CREATE2 (0xF5)
    CreateFixedAddress(caller types.Address, salt types.Hash, code []byte, tx environment.Transaction) types.Address
    
    // Retrieve 256-bit data from external storage at a specified slot during the execution of opcode SLOAD (0x54)
    Load(address types.Address, slot types.Slot) (*evmInt256.Int, error)
}

Execution Results

When executing contracts, SealEVM places all data changes, except for new contract deployments, into a cache and does not notify external storage.

type ExecuteResult struct {
    ResultData   []byte //Data returned by contract execution
    GasLeft      uint64 //Remaining gas
    StorageCache storage.ResultCache //Cache of external state changes. External data needs to be updated according to this cache. This will be explained in detail below.
    ExitOpCode   opcodes.OpCode //The last executed opcode when execution is completed
}

Execution Results Cache

Below is a description of the function of these cache variables, refer to the source code for detailed structure.

type ResultCache struct {
    OriginalData SlotCache // Original data loaded from external storage through SLOAD
    CachedData   SlotCache // Data stored after contract execution through SSTORE
    
    // TOriginalData and TCachedData are caches for transient storage, 
    // introduced by EIP-1153 as a temporary storage space during contract execution
    TOriginalData SlotCache
    TCachedData   SlotCache
    
    Logs         *LogCache // Log cache generated by opcodes LOG0 (0xA0) ~ LOG4 (0xA4)
    Destructs    DestructCache // Cache for contracts that executed SELFDESTRUCT (0xFF)
    NewContracts ContractCache // Cache for contracts created by internal transactions during execution
}

---

License

Apache License 2.0

Documentation

Index

• func Load()
• type EVM
  • func New(param EVMParam) *EVM
  • func NewWithCache(param EVMParam, s *storage.Storage) *EVM
  • func (e *EVM) ExecuteContract(doTransfer bool) (ExecuteResult, error)
• type EVMParam
• type EVMResultCallback
• type ExecuteResult

Functions

func Load

func Load()

Types

type EVM

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

func New

func New(param EVMParam) *EVM

func NewWithCache

func NewWithCache(param EVMParam, s *storage.Storage) *EVM

func (*EVM) ExecuteContract

func (e *EVM) ExecuteContract(doTransfer bool) (ExecuteResult, error)

type EVMParam

type EVMParam struct {
	MaxStackDepth  int
	ExternalStore  storage.IExternalStorage
	ResultCallback EVMResultCallback
	Context        *environment.Context
	GasSetting     *gasSetting.Setting
}

type EVMResultCallback

type EVMResultCallback func(result ExecuteResult, err error)

type ExecuteResult

type ExecuteResult struct {
	ResultData   []byte
	GasLeft      uint64
	StorageCache storage.ResultCache
	ExitOpCode   opcodes.OpCode
}