Documentation
¶
Overview ¶
Package evm is a minimal, read-only EVM interpreter for executing view/pure contract calls against locally-verified Filecoin FEVM state (lantern#43 Part B, Stage 3).
Scope: read-only `eth_call`. It implements the opcode subset that Solidity view/pure functions emit (arithmetic, comparison, bitwise, SHA3, environment/calldata, memory, storage SLOAD, control flow, and CALL/STATICCALL to other contracts for cross-contract reads). State mutation opcodes (SSTORE, CREATE/CREATE2, SELFDESTRUCT, LOG*) are not reachable on a read-only call and cause a revert if hit, exactly as a staticcall would.
It deliberately avoids vendoring go-ethereum's full core/vm (which drags in core/types, params, and the CGo secp256k1 crypto) to keep Lantern pure-Go and lean. Word math is holiman/uint256; hashing is keccak from golang.org/x/crypto/sha3.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrExecutionReverted = errors.New("execution reverted")
ErrExecutionReverted signals the call reverted; Result.Return carries the revert payload (ABI-encoded Error(string) etc.). Maps to eth JSON-RPC error code 3.
Functions ¶
This section is empty.
Types ¶
type Address ¶
type Address [20]byte
Address is a 20-byte EVM address.
func BytesToAddress ¶
BytesToAddress packs the rightmost 20 bytes of b into an Address.
type Backend ¶
type Backend interface {
// GetCode returns the EVM bytecode for the given 20-byte address.
// Empty (len 0) for accounts with no code.
GetCode(addr Address) ([]byte, error)
// GetStorage returns the 32-byte storage value at slot `key` for the
// contract at `addr`. Absent slots return the zero word.
GetStorage(addr Address, key uint256.Int) (uint256.Int, error)
// GetBalance returns the attoFIL/wei balance of addr as a 256-bit word.
GetBalance(addr Address) (uint256.Int, error)
// BlockNumber / Timestamp / ChainID expose the environment a view call
// observes. These can be the head tipset's epoch/time and the network
// chain id (314 / 314159).
BlockNumber() uint64
Timestamp() uint64
ChainID() uint64
}
Backend supplies the contract/world state the interpreter reads. All methods are read-only. Implementations back these with Lantern's verified state accessor (Stage 1 bytecode loader + Stage 2 KAMT storage reader).
type OpCode ¶
type OpCode byte
OpCode is a single EVM instruction byte.
const ( STOP OpCode = 0x00 ADD OpCode = 0x01 MUL OpCode = 0x02 SUB OpCode = 0x03 DIV OpCode = 0x04 SDIV OpCode = 0x05 MOD OpCode = 0x06 SMOD OpCode = 0x07 ADDMOD OpCode = 0x08 MULMOD OpCode = 0x09 EXP OpCode = 0x0a SIGNEXTEND OpCode = 0x0b LT OpCode = 0x10 GT OpCode = 0x11 SLT OpCode = 0x12 SGT OpCode = 0x13 EQ OpCode = 0x14 ISZERO OpCode = 0x15 AND OpCode = 0x16 OR OpCode = 0x17 XOR OpCode = 0x18 NOT OpCode = 0x19 BYTE OpCode = 0x1a SHL OpCode = 0x1b SHR OpCode = 0x1c SAR OpCode = 0x1d SHA3 OpCode = 0x20 ADDRESS OpCode = 0x30 BALANCE OpCode = 0x31 ORIGIN OpCode = 0x32 CALLER OpCode = 0x33 CALLVALUE OpCode = 0x34 CALLDATALOAD OpCode = 0x35 CALLDATASIZE OpCode = 0x36 CALLDATACOPY OpCode = 0x37 CODESIZE OpCode = 0x38 CODECOPY OpCode = 0x39 GASPRICE OpCode = 0x3a EXTCODESIZE OpCode = 0x3b EXTCODECOPY OpCode = 0x3c RETURNDATASIZE OpCode = 0x3d RETURNDATACOPY OpCode = 0x3e EXTCODEHASH OpCode = 0x3f BLOCKHASH OpCode = 0x40 COINBASE OpCode = 0x41 TIMESTAMP OpCode = 0x42 NUMBER OpCode = 0x43 DIFFICULTY OpCode = 0x44 GASLIMIT OpCode = 0x45 CHAINID OpCode = 0x46 SELFBALANCE OpCode = 0x47 BASEFEE OpCode = 0x48 POP OpCode = 0x50 MLOAD OpCode = 0x51 MSTORE OpCode = 0x52 MSTORE8 OpCode = 0x53 SLOAD OpCode = 0x54 SSTORE OpCode = 0x55 JUMP OpCode = 0x56 JUMPI OpCode = 0x57 PC OpCode = 0x58 MSIZE OpCode = 0x59 GAS OpCode = 0x5a JUMPDEST OpCode = 0x5b PUSH0 OpCode = 0x5f PUSH1 OpCode = 0x60 PUSH32 OpCode = 0x7f DUP1 OpCode = 0x80 DUP16 OpCode = 0x8f SWAP1 OpCode = 0x90 SWAP16 OpCode = 0x9f LOG0 OpCode = 0xa0 LOG1 OpCode = 0xa1 LOG2 OpCode = 0xa2 LOG3 OpCode = 0xa3 LOG4 OpCode = 0xa4 CREATE OpCode = 0xf0 CALL OpCode = 0xf1 CALLCODE OpCode = 0xf2 RETURN OpCode = 0xf3 DELEGATECALL OpCode = 0xf4 CREATE2 OpCode = 0xf5 STATICCALL OpCode = 0xfa REVERT OpCode = 0xfd INVALID OpCode = 0xfe SELFDESTRUCT OpCode = 0xff )
The opcode subset this interpreter recognises. Values are the canonical EVM opcode bytes.
type Result ¶
type Result struct {
// Return is the RETURN data (for a successful call) or the REVERT
// data (when Reverted is true).
Return []byte
// Reverted is true if the call ended in REVERT or a fault that maps to
// a revert (e.g. an unsupported state-mutation opcode on a read call).
Reverted bool
// GasUsed is a coarse gas counter (read calls are not gas-billed on
// chain; this is informational / for an estimate ceiling).
GasUsed uint64
}
Result is the outcome of a read-only EVM execution.
func Call ¶
Call executes `input` against the code at `to` and returns the result.
eth_call semantics: state mutations (SSTORE / value moves) and LOGs that happen during the call are applied to an ephemeral overlay that is discarded when the call returns -- chain state is never touched. This is what lets write-shaped calls (ERC-20 transferFrom inside a DEX swap, router reentrancy) execute correctly instead of falsely reverting.
Source Files