SealEVM

README

SealEVM

SealEVM is an independent EVM implementation that decouples from the storage system through interfaces and caching, and can be easily ported to any blockchain system implemented in golang, adding EVM support for it.

---

• 中文

Example

In the example directory, a simple usage reference example of SealEVM is provided. This example uses memory as external storage and shows simple functions such as contract deployment, invocation, variable reading, etc.

⚠️Note: The codes under example directory is only for a simple demonstration of code usage, please do not use it in any actual commercial and production environment

Main structures and interfaces

⚠️Note, the namespace in the source code is an alias for address, which has the same meaning as address in Ethereum.

Parameters for creating EVM instances

type EVMParam struct {
    MaxStackDepth  int //Maximum stack depth
    ExternalStore  storage.IExternalStorage //External storage interface, which will be explained in detail in later chapters
    ResultCallback EVMResultCallback //Callback function after EVM execution
    Context        *environment.Context //Environment context for EVM execution, please read the source code for the meaning of internal fields
    GasSetting     *instructions.GasSetting //Custom gas cost setting for OpCode
}

External storage interface

SealEVM will interact with external storage through this interface to implement necessary functions such as state reading, address creation, new contract storage, etc.

type IExternalStorage interface {
    //Get the account balance of the specified address from external storage
    GetBalance(address *evmInt256.Int) (*evmInt256.Int, error)

    //Get the contract of the specified address from external storage
    GetContract(address *evmInt256.Int) (*Contract, error)

    //Get the hash of the specified block from external storage
    GetBlockHash(block *evmInt256.Int) (*evmInt256.Int, error)

    //Calculates and returns the hash value of the given Code, which will be used as CodeHash
	HashOfCode(code []byte) *evmInt256.Int
    
	//When executing opcode CREAT(0xF0), this method will be called to get the address of the created contract
    CreateAddress(caller *evmInt256.Int, tx environment.Transaction) *evmInt256.Int
    
    //When executing opcode CREAT2(0xF5), this method will be called to get the address of the created contract
    CreateFixedAddress(caller *evmInt256.Int, salt *evmInt256.Int, tx environment.Transaction) *evmInt256.Int
    
    //Get from external storage whether account balance transfer can be performed
    CanTransfer(from *evmInt256.Int, to *evmInt256.Int, amount *evmInt256.Int) bool
    
    //When executing opcode SLOAD(0x54), get 256-bit data from external storage at the specified location
    //Note: The parameter n is the address of the current executing contract, and the parameter k is the key of the storage location given when executing opcode SLOAD(0x54)
    Load(n *evmInt256.Int, k *evmInt256.Int) (*evmInt256.Int, error)
}

Execution result

SealEVM will put all data that has changed during contract execution, except for new contract deployment, into cache and will 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
}

Cache of execution results

The following is a description of the functions of these cache variables. Please refer to the source code for detailed structures.

type ResultCache struct {
    OriginalData CacheUnderNamespace //Cache information read from external storage during execution
    CachedData   CacheUnderNamespace //Cache all state updates at the end of execution

    TOriginalData CacheUnderNamespace //Cache information read from external transient storage during execution
    TCachedData   CacheUnderNamespace //Cache all transient state updates at the end of execution

    Balance   BalanceCache //Cache all account balance changes during execution
    Logs      LogCache //Cache all logs generated by contracts during execution
    Destructs Cache //Cache addresses of contracts that executed opcode SELFDESTRUCT(0xff)
}

---

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     *instructions.GasSetting
}

type EVMResultCallback

type EVMResultCallback func(result ExecuteResult, err error)

type ExecuteResult

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