mipsevm

package
v0.0.0-...-eb934a0 Latest Latest
Warning

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

Go to latest
Published: Aug 3, 2023 License: MIT, MIT Imports: 27 Imported by: 0

README

mipsevm

Supported 55 instructions:

'addi', 'addiu', 'addu', 'and', 'andi',
'b', 'beq', 'beqz', 'bgez', 'bgtz', 'blez', 'bltz', 'bne', 'bnez',
'clz', 'divu',
'j', 'jal', 'jalr', 'jr',
'lb', 'lbu', 'lui', 'lw', 'lwr',
'mfhi', 'mflo', 'move', 'movn', 'movz', 'mtlo', 'mul', 'multu',
'negu', 'nop', 'not', 'or', 'ori',
'sb', 'sll', 'sllv', 'slt', 'slti', 'sltiu', 'sltu', 'sra', 'srl', 'srlv', 'subu', 'sw', 'swr', 'sync', 'syscall',
'xor', 'xori'

To run:

  1. Load a program into a state, e.g. using LoadELF.
  2. Patch the program if necessary: e.g. using PatchGo for Go programs, PatchStack for empty initial stack, etc.
  3. Implement the PreimageOracle interface
  4. Instrument the emulator with the state, and pre-image oracle, using NewInstrumentedState
  5. Step through the instrumented state with Step(proof), where proof==true if witness data should be generated. Steps are faster with proof==false.
  6. Optionally repeat the step on-chain by calling MIPS.sol and PreimageOracle.sol, using the above witness data.

Documentation

Index

Constants

View Source
const (
	MipsEBADF  = 0x9
	MipsEINVAL = 0x16
)
View Source
const (
	PageAddrSize = 12
	PageKeySize  = 32 - PageAddrSize
	PageSize     = 1 << PageAddrSize
	PageAddrMask = PageSize - 1
	MaxPageCount = 1 << PageKeySize
	PageKeyMask  = MaxPageCount - 1
)

Note: 2**12 = 4 KiB, the min phys page size in the Go runtime.

Variables

View Source
var (
	StepBytes4                      = crypto.Keccak256([]byte("Step(bytes,bytes)"))[:4]
	CheatBytes4                     = crypto.Keccak256([]byte("cheat(uint256,bytes32,bytes32,uint256)"))[:4]
	LoadKeccak256PreimagePartBytes4 = crypto.Keccak256([]byte("loadKeccak256PreimagePart(uint256,bytes)"))[:4]
)

Functions

func HashPair

func HashPair(left, right [32]byte) [32]byte

func NewEVMEnv

func NewEVMEnv(contracts *Contracts, addrs *Addresses) (*vm.EVM, *state.StateDB)

func PatchGo

func PatchGo(f *elf.File, st *State) error

func PatchStack

func PatchStack(st *State) error

func SE

func SE(dat uint32, idx uint32) uint32

Types

type Addresses

type Addresses struct {
	MIPS         common.Address
	Oracle       common.Address
	Sender       common.Address
	FeeRecipient common.Address
}

type CachedPage

type CachedPage struct {
	Data *Page
	// intermediate nodes only
	Cache [PageSize / 32][32]byte
	// true if the intermediate node is valid
	Ok [PageSize / 32]bool
}

func (*CachedPage) Invalidate

func (p *CachedPage) Invalidate(pageAddr uint32)

func (*CachedPage) InvalidateFull

func (p *CachedPage) InvalidateFull()

func (*CachedPage) MerkleRoot

func (p *CachedPage) MerkleRoot() [32]byte

func (*CachedPage) MerkleizeSubtree

func (p *CachedPage) MerkleizeSubtree(gindex uint64) [32]byte

type Contract

type Contract struct {
	DeployedBytecode struct {
		Object    hexutil.Bytes `json:"object"`
		SourceMap string        `json:"sourceMap"`
	} `json:"deployedBytecode"`
}

func LoadContract

func LoadContract(name string) (*Contract, error)

func (*Contract) SourceMap

func (c *Contract) SourceMap(sourcePaths []string) (*srcmap.SourceMap, error)

type Contracts

type Contracts struct {
	MIPS   *Contract
	Oracle *Contract
}

func LoadContracts

func LoadContracts() (*Contracts, error)

LoadContracts loads the Cannon contracts, from op-bindings package

func LoadContractsFromFiles

func LoadContractsFromFiles() (*Contracts, error)

LoadContractsFromFiles loads the Cannon contracts, from local filesystem

type HexU32

type HexU32 uint32

HexU32 to lazy-format integer attributes for logging

func (HexU32) MarshalText

func (v HexU32) MarshalText() ([]byte, error)

func (HexU32) String

func (v HexU32) String() string

type InstrumentedState

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

func NewInstrumentedState

func NewInstrumentedState(state *State, po PreimageOracle, stdOut, stdErr io.Writer) *InstrumentedState

func (*InstrumentedState) Step

func (m *InstrumentedState) Step(proof bool) (wit *StepWitness, err error)

type LoggingWriter

type LoggingWriter struct {
	Name string
	Log  log.Logger
}

LoggingWriter is a simple util to wrap a logger, and expose an io Writer interface, for the program running within the VM to write to.

func (*LoggingWriter) Write

func (lw *LoggingWriter) Write(b []byte) (int, error)

type Memory

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

func NewMemory

func NewMemory() *Memory

func (*Memory) AllocPage

func (m *Memory) AllocPage(pageIndex uint32) *CachedPage

func (*Memory) ForEachPage

func (m *Memory) ForEachPage(fn func(pageIndex uint32, page *Page) error) error

func (*Memory) GetMemory

func (m *Memory) GetMemory(addr uint32) uint32

func (*Memory) Invalidate

func (m *Memory) Invalidate(addr uint32)

func (*Memory) MarshalJSON

func (m *Memory) MarshalJSON() ([]byte, error)

func (*Memory) MerkleProof

func (m *Memory) MerkleProof(addr uint32) (out [28 * 32]byte)

func (*Memory) MerkleRoot

func (m *Memory) MerkleRoot() [32]byte

func (*Memory) MerkleizeSubtree

func (m *Memory) MerkleizeSubtree(gindex uint64) [32]byte

func (*Memory) PageCount

func (m *Memory) PageCount() int

func (*Memory) ReadMemoryRange

func (m *Memory) ReadMemoryRange(addr uint32, count uint32) io.Reader

func (*Memory) SetMemory

func (m *Memory) SetMemory(addr uint32, v uint32)

func (*Memory) SetMemoryRange

func (m *Memory) SetMemoryRange(addr uint32, r io.Reader) error

func (*Memory) UnmarshalJSON

func (m *Memory) UnmarshalJSON(data []byte) error

func (*Memory) Usage

func (m *Memory) Usage() string

type Metadata

type Metadata struct {
	Symbols []Symbol `json:"symbols"`
}

func MakeMetadata

func MakeMetadata(elfProgram *elf.File) (*Metadata, error)

func (*Metadata) LookupSymbol

func (m *Metadata) LookupSymbol(addr uint32) string

func (*Metadata) SymbolMatcher

func (m *Metadata) SymbolMatcher(name string) func(addr uint32) bool

type Page

type Page [PageSize]byte

func (*Page) MarshalText

func (p *Page) MarshalText() ([]byte, error)

func (*Page) UnmarshalText

func (p *Page) UnmarshalText(dat []byte) error

type PreimageOracle

type PreimageOracle interface {
	Hint(v []byte)
	GetPreimage(k [32]byte) []byte
}

type State

type State struct {
	Memory *Memory `json:"memory"`

	PreimageKey    common.Hash `json:"preimageKey"`
	PreimageOffset uint32      `json:"preimageOffset"` // note that the offset includes the 8-byte length prefix

	PC     uint32 `json:"pc"`
	NextPC uint32 `json:"nextPC"`
	LO     uint32 `json:"lo"`
	HI     uint32 `json:"hi"`
	Heap   uint32 `json:"heap"` // to handle mmap growth

	ExitCode uint8 `json:"exit"`
	Exited   bool  `json:"exited"`

	Step uint64 `json:"step"`

	Registers [32]uint32 `json:"registers"`

	// LastHint is optional metadata, and not part of the VM state itself.
	// It is used to remember the last pre-image hint,
	// so a VM can start from any state without fetching prior pre-images,
	// and instead just repeat the last hint on setup,
	// to make sure pre-image requests can be served.
	// The first 4 bytes are a uin32 length prefix.
	// Warning: the hint MAY NOT BE COMPLETE. I.e. this is buffered,
	// and should only be read when len(LastHint) > 4 && uint32(LastHint[:4]) >= len(LastHint[4:])
	LastHint hexutil.Bytes `json:"lastHint,omitempty"`
}

func LoadELF

func LoadELF(f *elf.File) (*State, error)

func (*State) EncodeWitness

func (s *State) EncodeWitness() []byte

type StepWitness

type StepWitness struct {
	// encoded state witness
	State []byte

	MemProof []byte

	PreimageKey    [32]byte // zeroed when no pre-image is accessed
	PreimageValue  []byte   // including the 8-byte length prefix
	PreimageOffset uint32
}

func (*StepWitness) EncodePreimageOracleInput

func (wit *StepWitness) EncodePreimageOracleInput() ([]byte, error)

func (*StepWitness) EncodeStepInput

func (wit *StepWitness) EncodeStepInput() []byte

func (*StepWitness) HasPreimage

func (wit *StepWitness) HasPreimage() bool

type Symbol

type Symbol struct {
	Name  string `json:"name"`
	Start uint32 `json:"start"`
	Size  uint32 `json:"size"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL