emulator

package
v2.0.3-0...-45cb04b Latest Latest
Warning

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

 Go to latest Published: Sep 18, 2025 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package emulator contains the implementation of the EVMEmulator and subcomponents.

The main components in this package are:

  • EVMEmulator, which is responsible for executing the Ethereum transactions.

    The EVMEmulator relies on the `go-ethereum` implementation of the Ethereum Virtual Machine (EVM). We use a fork that adds support for ISC's magic contract.

  • StateDB, which adapts go-ethereum's vm.StateDB interface to ISC's kv.KVStore interface. In other words, it keeps track of the EVM state (the key-value store, account balances, contract codes, etc), storing it in a subpartition of the `evm` core contract's state.

  • BlockchainDB, which keeps track of the Ethereum blocks and their transactions and receipts.

The emulator package is mostly agnostic about ISC. It depends only on the ethereum and kv packages.

Index

Constants

View Source 
const (
	BlockKeepAll = -1
)

Variables

This section is empty.

Functions

func BlockchainDBSubrealm 

func BlockchainDBSubrealm(store kv.KVStore) kv.KVStore

func BlockchainDBSubrealmR 

func BlockchainDBSubrealmR(store kv.KVStoreReader) kv.KVStoreReader

func CreateAccount 

func CreateAccount(kv kv.KVStore, addr common.Address)

func Exist 

func Exist(addr common.Address, s kv.KVStoreReader) bool

Exist reports whether the given account exists in state. expects s to be the stateDB state partition

func GetChainIDFromBlockChainDBState 

func GetChainIDFromBlockChainDBState(kv kv.KVStoreReader) uint16

func GetCode 

func GetCode(s kv.KVStoreReader, addr common.Address) []byte

func GetNonce 

func GetNonce(s kv.KVStoreReader, addr common.Address) uint64

func GetState 

func GetState(s kv.KVStoreReader, addr common.Address, key common.Hash) common.Hash

func IncNonce 

func IncNonce(kv kv.KVStore, addr common.Address)

func Init 

func Init(
	emulatorState kv.KVStore,
	chainID uint16,
	gasLimits GasLimits,
	timestamp uint64,
	alloc types.GenesisAlloc,
)

Init initializes the EVM state with the provided genesis allocation parameters

func NewHookedState 

func NewHookedState(stateDB *StateDB, hooks *tracing.Hooks) *hookedStateDB

NewHookedState wraps the given stateDb with the given hooks

func SetCode 

func SetCode(kv kv.KVStore, addr common.Address, code []byte)

func SetNonce 

func SetNonce(kv kv.KVStore, addr common.Address, n uint64)

func SetState 

func SetState(kv kv.KVStore, addr common.Address, key, value common.Hash)

func StateDBSubrealm 

func StateDBSubrealm(store kv.KVStore) kv.KVStore

func StateDBSubrealmR 

func StateDBSubrealmR(store kv.KVStoreReader) kv.KVStoreReader

Types

type BlockchainDB 

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

BlockchainDB contains logic for storing a fake blockchain (more like a list of blocks), intended for satisfying EVM tools that depend on the concept of a block.

func NewBlockchainDB 

func NewBlockchainDB(store kv.KVStore, blockGasLimit uint64, blockKeepAmount int32) *BlockchainDB

func (*BlockchainDB) AddTransaction 

func (bc *BlockchainDB) AddTransaction(tx *types.Transaction, receipt *types.Receipt)

func (*BlockchainDB) GetBlockByHash 

func (bc *BlockchainDB) GetBlockByHash(hash common.Hash) *types.Block

func (*BlockchainDB) GetBlockByNumber 

func (bc *BlockchainDB) GetBlockByNumber(blockNumber uint64) *types.Block

func (*BlockchainDB) GetBlockHashByBlockNumber 

func (bc *BlockchainDB) GetBlockHashByBlockNumber(blockNumber uint64) common.Hash

func (*BlockchainDB) GetBlockNumberByBlockHash 

func (bc *BlockchainDB) GetBlockNumberByBlockHash(hash common.Hash) (uint64, bool)

func (*BlockchainDB) GetBlockNumberByTxHash 

func (bc *BlockchainDB) GetBlockNumberByTxHash(txHash common.Hash) (uint64, bool)

func (*BlockchainDB) GetChainID 

func (bc *BlockchainDB) GetChainID() uint16

func (*BlockchainDB) GetCurrentBlock 

func (bc *BlockchainDB) GetCurrentBlock() *types.Block

func (*BlockchainDB) GetHeaderByBlockNumber 

func (bc *BlockchainDB) GetHeaderByBlockNumber(blockNumber uint64) *types.Header

func (*BlockchainDB) GetHeaderByHash 

func (bc *BlockchainDB) GetHeaderByHash(hash common.Hash) *types.Header

func (*BlockchainDB) GetNumber 

func (bc *BlockchainDB) GetNumber() uint64

func (*BlockchainDB) GetPendingBlockNumber 

func (bc *BlockchainDB) GetPendingBlockNumber() uint64

func (*BlockchainDB) GetPendingCumulativeGasUsed 

func (bc *BlockchainDB) GetPendingCumulativeGasUsed() uint64

func (*BlockchainDB) GetPendingHeader 

func (bc *BlockchainDB) GetPendingHeader(timestamp uint64) *types.Header

func (*BlockchainDB) GetReceiptByTxHash 

func (bc *BlockchainDB) GetReceiptByTxHash(txHash common.Hash) *types.Receipt

func (*BlockchainDB) GetReceiptsByBlockNumber 

func (bc *BlockchainDB) GetReceiptsByBlockNumber(blockNumber uint64) []*types.Receipt

func (*BlockchainDB) GetTimestampByBlockNumber 

func (bc *BlockchainDB) GetTimestampByBlockNumber(blockNumber uint64) uint64

func (*BlockchainDB) GetTransactionByBlockNumberAndIndex 

func (bc *BlockchainDB) GetTransactionByBlockNumberAndIndex(blockNumber uint64, i uint32) *types.Transaction

func (*BlockchainDB) GetTransactionByHash 

func (bc *BlockchainDB) GetTransactionByHash(txHash common.Hash) (tx *types.Transaction, blockHash common.Hash, blockNumber, index uint64, err error)

func (*BlockchainDB) GetTransactionsByBlockNumber 

func (bc *BlockchainDB) GetTransactionsByBlockNumber(blockNumber uint64) []*types.Transaction

func (*BlockchainDB) GetTxIndexInBlockByTxHash 

func (bc *BlockchainDB) GetTxIndexInBlockByTxHash(txHash common.Hash) uint32

func (*BlockchainDB) Init 

func (bc *BlockchainDB) Init(chainID uint16, timestamp uint64)

func (*BlockchainDB) Initialized 

func (bc *BlockchainDB) Initialized() bool

func (*BlockchainDB) MintBlock 

func (bc *BlockchainDB) MintBlock(timestamp uint64)

func (*BlockchainDB) SetChainID 

func (bc *BlockchainDB) SetChainID(chainID uint16)

type Context 

type Context interface {
	State() kv.KVStore
	Timestamp() uint64
	GasLimits() GasLimits
	BlockKeepAmount() int32
	MagicContracts() map[common.Address]vm.ISCMagicContract

	TakeSnapshot() int
	RevertToSnapshot(int)

	BaseTokensDecimals() uint8
	GetBaseTokensBalance(addr common.Address) *big.Int
	AddBaseTokensBalance(addr common.Address, amount *big.Int)
	SubBaseTokensBalance(addr common.Address, amount *big.Int)

	WithoutGasBurn(f func())
}

type EVMEmulator 

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

func NewEVMEmulator 

func NewEVMEmulator(ctx Context) *EVMEmulator

func (*EVMEmulator) BlockGasLimit 

func (e *EVMEmulator) BlockGasLimit() uint64

func (*EVMEmulator) BlockchainDB 

func (e *EVMEmulator) BlockchainDB() *BlockchainDB

func (*EVMEmulator) CallContract 

func (e *EVMEmulator) CallContract(call ethereum.CallMsg, gasEstimateMode bool) (*core.ExecutionResult, error)

CallContract executes a contract call, without committing changes to the state

func (*EVMEmulator) CallGasLimit 

func (e *EVMEmulator) CallGasLimit() uint64

func (*EVMEmulator) ChainContext 

func (e *EVMEmulator) ChainContext() core.ChainContext

func (*EVMEmulator) MintBlock 

func (e *EVMEmulator) MintBlock()

func (*EVMEmulator) SendTransaction 

func (e *EVMEmulator) SendTransaction(
	tx *types.Transaction,
	tracer *tracing.Hooks,
	addToBlockchain ...bool,
) (receipt *types.Receipt, result *core.ExecutionResult, err error)

func (*EVMEmulator) Signer 

func (e *EVMEmulator) Signer() types.Signer

func (*EVMEmulator) StateDB 

func (e *EVMEmulator) StateDB() *StateDB

type GasLimits 

type GasLimits struct {
	Block uint64
	Call  uint64
}

type StateDB 

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

StateDB implements vm.StateDB with a kv.KVStore as backend. The Ethereum account balance is tied to the L1 balance.

func NewStateDB 

func NewStateDB(ctx Context) *StateDB

func (*StateDB) AccessEvents 

func (s *StateDB) AccessEvents() *state.AccessEvents

func (*StateDB) AddAddressToAccessList 

func (s *StateDB) AddAddressToAccessList(addr common.Address)

AddAddressToAccessList adds the given address to the access list. This operation is safe to perform even if the feature/fork is not active yet

func (*StateDB) AddBalance 

func (s *StateDB) AddBalance(addr common.Address, amount *uint256.Int, _ tracing.BalanceChangeReason) uint256.Int

func (*StateDB) AddLog 

func (s *StateDB) AddLog(log *types.Log)

func (*StateDB) AddPreimage 

func (s *StateDB) AddPreimage(common.Hash, []byte)

func (*StateDB) AddRefund 

func (s *StateDB) AddRefund(n uint64)

func (*StateDB) AddSlotToAccessList 

func (s *StateDB) AddSlotToAccessList(addr common.Address, slot common.Hash)

AddSlotToAccessList adds the given (address,slot) to the access list. This operation is safe to perform even if the feature/fork is not active yet

func (*StateDB) AddressInAccessList 

func (s *StateDB) AddressInAccessList(addr common.Address) bool

func (*StateDB) CreateAccount 

func (s *StateDB) CreateAccount(addr common.Address)

func (*StateDB) CreateContract 

func (s *StateDB) CreateContract(addr common.Address)

CreateContract is used whenever a contract is created. This may be preceded by CreateAccount, but that is not required if it already existed in the state due to funds sent beforehand. This operation sets the 'newContract'-flag, which is required in order to correctly handle EIP-6780 'delete-in-same-transaction' logic.

func (*StateDB) Empty 

func (s *StateDB) Empty(addr common.Address) bool

Empty returns whether the given account is empty. Empty is defined according to EIP161 (balance = nonce = code = 0).

func (*StateDB) Exist 

func (s *StateDB) Exist(addr common.Address) bool

Exist reports whether the given account exists in state. Notably this should also return true for self-destructed accounts.

func (*StateDB) Finalise 

func (s *StateDB) Finalise(deleteEmptyObjects bool)

func (*StateDB) GetBalance 

func (s *StateDB) GetBalance(addr common.Address) *uint256.Int

func (*StateDB) GetCode 

func (s *StateDB) GetCode(addr common.Address) []byte

func (*StateDB) GetCodeHash 

func (s *StateDB) GetCodeHash(addr common.Address) common.Hash

func (*StateDB) GetCodeSize 

func (s *StateDB) GetCodeSize(addr common.Address) int

func (*StateDB) GetCommittedState 

func (s *StateDB) GetCommittedState(addr common.Address, key common.Hash) common.Hash

func (*StateDB) GetLogs 

func (s *StateDB) GetLogs() []*types.Log

func (*StateDB) GetNonce 

func (s *StateDB) GetNonce(addr common.Address) uint64

func (*StateDB) GetRefund 

func (s *StateDB) GetRefund() uint64

func (*StateDB) GetState 

func (s *StateDB) GetState(addr common.Address, key common.Hash) common.Hash

func (*StateDB) GetStateAndCommittedState 

func (s *StateDB) GetStateAndCommittedState(addr common.Address, hash common.Hash) (common.Hash, common.Hash)

GetStateAndCommittedState We can’t implement the “proper” geth-style GetStateAndCommittedState here. In go-ethereum, “current” is the live (dirty) value after in-tx writes, while “committed” is the original value from the backing trie at tx start. Our emulator doesn’t track per-tx “original” values as EIP‑2200/3529 asks for. As a result, current and committed collapse to the same value, so GetCommittedState is effectively GetState. Implementing this properly would require an origin map and journaling integrated with the tx lifecycle.

func (*StateDB) GetStorageRoot 

func (s *StateDB) GetStorageRoot(addr common.Address) common.Hash

GetStorageRoot implements vm.StateDB.

func (*StateDB) GetTransientState 

func (s *StateDB) GetTransientState(addr common.Address, key common.Hash) common.Hash

GetTransientState implements vm.StateDB

func (*StateDB) HasSelfDestructed 

func (s *StateDB) HasSelfDestructed(addr common.Address) bool

func (*StateDB) IncNonce 

func (s *StateDB) IncNonce(addr common.Address)

func (*StateDB) PointCache 

func (s *StateDB) PointCache() *utils.PointCache

PointCache implements vm.StateDB.

func (*StateDB) Prepare 

func (s *StateDB) Prepare(rules params.Rules, sender common.Address, coinbase common.Address, dest *common.Address, precompiles []common.Address, txAccesses types.AccessList)

Prepare implements vm.StateDB cleans up refunds, transient storage and "newContract" flags

func (*StateDB) PrepareAccessList 

func (s *StateDB) PrepareAccessList(sender common.Address, dest *common.Address, precompiles []common.Address, txAccesses types.AccessList)

func (*StateDB) RevertToSnapshot 

func (s *StateDB) RevertToSnapshot(i int)

func (*StateDB) SelfDestruct 

func (s *StateDB) SelfDestruct(addr common.Address) uint256.Int

func (*StateDB) SelfDestruct6780 

func (s *StateDB) SelfDestruct6780(addr common.Address) (uint256.Int, bool)

func (*StateDB) SetCode 

func (s *StateDB) SetCode(addr common.Address, code []byte) []byte

func (*StateDB) SetNonce 

func (s *StateDB) SetNonce(addr common.Address, n uint64, r tracing.NonceChangeReason)

func (*StateDB) SetState 

func (s *StateDB) SetState(addr common.Address, key, value common.Hash) common.Hash

func (*StateDB) SetTransientState 

func (s *StateDB) SetTransientState(addr common.Address, key common.Hash, value common.Hash)

SetTransientState implements vm.StateDB

func (*StateDB) SlotInAccessList 

func (s *StateDB) SlotInAccessList(addr common.Address, slot common.Hash) (addressOk, slotOk bool)

func (*StateDB) Snapshot 

func (s *StateDB) Snapshot() int

func (*StateDB) SubBalance 

func (s *StateDB) SubBalance(addr common.Address, amount *uint256.Int, _ tracing.BalanceChangeReason) uint256.Int

func (*StateDB) SubRefund 

func (s *StateDB) SubRefund(n uint64)

func (*StateDB) Witness 

func (s *StateDB) Witness() *stateless.Witness

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.