cannon: merge into monorepo, preserve git history

cannon/.gitignore

+node_modules
+artifacts
+cache
+.*.swp
+venv
+.idea
+*.log
+example/bin
+contracts/out
+state.json
+*.json
+*.pprof
+*.out

cannon/LICENSE

+MIT License
+
+Copyright (c) 2021 Optimism
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cannon/Makefile

+SHELL := /bin/bash
+
+build: contracts
+.PHONY: build
+
+contracts:
+	cd contracts && forge build
+.PHONY: contracts
+
+test:
+	cd mipsevm && go test -v ./...
+.PHONY: test

cannon/README.md

+<!--![cannon](https://upload.wikimedia.org/wikipedia/commons/8/80/Cannon%2C_Château_du_Haut-Koenigsbourg%2C_France.jpg)-->
+<!--![cannon](https://cdn1.epicgames.com/ue/product/Featured/SCIFIWEAPONBUNDLE_featured-894x488-83fbc936b6d86edcbbe892b1a6780224.png)-->
+<!--![cannon](https://static.wikia.nocookie.net/ageofempires/images/8/80/Bombard_cannon_aoe2DE.png/revision/latest/top-crop/width/360/height/360?cb=20200331021834)-->
+![cannon](https://paradacreativa.es/wp-content/uploads/2021/05/Canon-orbital-GTA-01.jpg)
+
+---
+
+Cannon *(cannon cannon cannon)* is an onchain MIPS instruction emulator.
+Cannon supports EVM-equivalent fault proofs by enabling Geth to run onchain,
+one instruction at a time, as part of an interactive dispute game.
+
+* It's Go code
+* ...that runs an EVM
+* ...emulating a MIPS machine
+* ...running compiled Go code
+* ...that runs an EVM
+
+For more information, see [Docs](./docs/README.md).
+
+## Directory Layout
+
+```
+contracts -- A MIPS emulator implementation, using merkleized state and a pre-image oracle.
+example   -- Example programs that can be run and proven with Cannon.
+extra     -- Extra scripts and legacy contracts, deprecated.
+mipsevm   -- Go tooling to test the onchain MIPS implementation, and generate proof data.
+diffmips  -- MIPS diff testing, to ensure correctness of the main Cannon implementation, with isolated dependencies. 
+```
+
+## Building
+
+### `contracts`
+
+The contracts are compiled with [`forge`](https://github.com/foundry-rs/foundry).
+```
+make contracts
+```
+
+## License
+
+MIT, see [`LICENSE`](./LICENSE) file.
+
+**Note: This code is unaudited.**
+In NO WAY should it be used to secure any monetary value before testing and auditing.
+This is experimental software, and should be treated as such.
+The authors of this project make no guarantees of security of ANY KIND.

cannon/cmd/json.go

+package cmd
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+)
+
+func loadJSON[X any](inputPath string) (*X, error) {
+	if inputPath == "" {
+		return nil, errors.New("no path specified")
+	}
+	f, err := os.OpenFile(inputPath, os.O_RDONLY, 0)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open file %q: %w", inputPath, err)
+	}
+	defer f.Close()
+	var state X
+	if err := json.NewDecoder(f).Decode(&state); err != nil {
+		return nil, fmt.Errorf("failed to decode file %q: %w", inputPath, err)
+	}
+	return &state, nil
+}
+
+func writeJSON[X any](outputPath string, value X, outIfEmpty bool) error {
+	var out io.Writer
+	if outputPath != "" {
+		f, err := os.OpenFile(outputPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0755)
+		if err != nil {
+			return fmt.Errorf("failed to open output file: %w", err)
+		}
+		defer f.Close()
+		out = f
+	} else if outIfEmpty {
+		out = os.Stdout
+	} else {
+		return nil
+	}
+	enc := json.NewEncoder(out)
+	if err := enc.Encode(value); err != nil {
+		return fmt.Errorf("failed to encode to JSON: %w", err)
+	}
+	_, err := out.Write([]byte{'\n'})
+	if err != nil {
+		return fmt.Errorf("failed to append new-line: %w", err)
+	}
+	return nil
+}

cannon/cmd/load_elf.go

+package cmd
+
+import (
+	"debug/elf"
+	"fmt"
+
+	"github.com/urfave/cli/v2"
+
+	"github.com/ethereum-optimism/cannon/mipsevm"
+)
+
+var (
+	LoadELFPathFlag = &cli.PathFlag{
+		Name:      "path",
+		Usage:     "Path to 32-bit big-endian MIPS ELF file",
+		TakesFile: true,
+		Required:  true,
+	}
+	LoadELFPatchFlag = &cli.StringSliceFlag{
+		Name:     "patch",
+		Usage:    "Type of patching to do",
+		Value:    cli.NewStringSlice("go", "stack"),
+		Required: false,
+	}
+	LoadELFOutFlag = &cli.PathFlag{
+		Name:     "out",
+		Usage:    "Output path to write JSON state to. State is dumped to stdout if set to empty string.",
+		Value:    "state.json",
+		Required: false,
+	}
+	LoadELFMetaFlag = &cli.PathFlag{
+		Name:     "meta",
+		Usage:    "Write metadata file, for symbol lookup during program execution. None if empty.",
+		Value:    "meta.json",
+		Required: false,
+	}
+)
+
+func LoadELF(ctx *cli.Context) error {
+	elfPath := ctx.Path(LoadELFPathFlag.Name)
+	elfProgram, err := elf.Open(elfPath)
+	if err != nil {
+		return fmt.Errorf("failed to open ELF file %q: %w", elfPath, err)
+	}
+	if elfProgram.Machine != elf.EM_MIPS {
+		return fmt.Errorf("ELF is not big-endian MIPS R3000, but got %q", elfProgram.Machine.String())
+	}
+	state, err := mipsevm.LoadELF(elfProgram)
+	if err != nil {
+		return fmt.Errorf("failed to load ELF data into VM state: %w", err)
+	}
+	for _, typ := range ctx.StringSlice(LoadELFPatchFlag.Name) {
+		switch typ {
+		case "stack":
+			err = mipsevm.PatchStack(state)
+		case "go":
+			err = mipsevm.PatchGo(elfProgram, state)
+		default:
+			return fmt.Errorf("unrecognized form of patching: %q", typ)
+		}
+		if err != nil {
+			return fmt.Errorf("failed to apply patch %s: %w", typ, err)
+		}
+	}
+	meta, err := mipsevm.MakeMetadata(elfProgram)
+	if err != nil {
+		return fmt.Errorf("failed to compute program metadata: %w", err)
+	}
+	if err := writeJSON[*mipsevm.Metadata](ctx.Path(LoadELFMetaFlag.Name), meta, false); err != nil {
+		return fmt.Errorf("failed to output metadata: %w", err)
+	}
+	return writeJSON[*mipsevm.State](ctx.Path(LoadELFOutFlag.Name), state, true)
+}
+
+var LoadELFCommand = &cli.Command{
+	Name:        "load-elf",
+	Usage:       "Load ELF file into Cannon JSON state",
+	Description: "Load ELF file into Cannon JSON state, optionally patch out functions",
+	Action:      LoadELF,
+	Flags: []cli.Flag{
+		LoadELFPathFlag,
+		LoadELFPatchFlag,
+		LoadELFOutFlag,
+		LoadELFMetaFlag,
+	},
+}

cannon/cmd/log.go

+package cmd
+
+import (
+	"io"
+
+	"github.com/ethereum/go-ethereum/log"
+)
+
+func Logger(w io.Writer, lvl log.Lvl) log.Logger {
+	h := log.StreamHandler(w, log.LogfmtFormat())
+	h = log.SyncHandler(h)
+	h = log.LvlFilterHandler(lvl, h)
+	l := log.New()
+	l.SetHandler(h)
+	return l
+}

cannon/cmd/matcher.go

+package cmd
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/ethereum-optimism/cannon/mipsevm"
+)
+
+type StepMatcher func(st *mipsevm.State) bool
+
+type StepMatcherFlag struct {
+	repr    string
+	matcher StepMatcher
+}
+
+func MustStepMatcherFlag(pattern string) *StepMatcherFlag {
+	out := new(StepMatcherFlag)
+	if err := out.Set(pattern); err != nil {
+		panic(err)
+	}
+	return out
+}
+
+func (m *StepMatcherFlag) Set(value string) error {
+	m.repr = value
+	if value == "" || value == "never" {
+		m.matcher = func(st *mipsevm.State) bool {
+			return false
+		}
+	} else if value == "always" {
+		m.matcher = func(st *mipsevm.State) bool {
+			return true
+		}
+	} else if strings.HasPrefix(value, "=") {
+		when, err := strconv.ParseUint(value[1:], 0, 64)
+		if err != nil {
+			return fmt.Errorf("failed to parse step number: %w", err)
+		}
+		m.matcher = func(st *mipsevm.State) bool {
+			return st.Step == when
+		}
+	} else if strings.HasPrefix(value, "%") {
+		when, err := strconv.ParseUint(value[1:], 0, 64)
+		if err != nil {
+			return fmt.Errorf("failed to parse step interval number: %w", err)
+		}
+		m.matcher = func(st *mipsevm.State) bool {
+			return st.Step%when == 0
+		}
+	} else {
+		return fmt.Errorf("unrecognized step matcher: %q", value)
+	}
+	return nil
+}
+
+func (m *StepMatcherFlag) String() string {
+	return m.repr
+}
+
+func (m *StepMatcherFlag) Matcher() StepMatcher {
+	if m.matcher == nil { // Set(value) is not called for omitted inputs, default to never matching.
+		return func(st *mipsevm.State) bool {
+			return false
+		}
+	}
+	return m.matcher
+}

cannon/cmd/run.go

+package cmd
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"time"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/ethereum/go-ethereum/log"
+	"github.com/urfave/cli/v2"
+
+	"github.com/pkg/profile"
+
+	"github.com/ethereum-optimism/cannon/mipsevm"
+	"github.com/ethereum-optimism/cannon/preimage"
+)
+
+var (
+	RunInputFlag = &cli.PathFlag{
+		Name:      "input",
+		Usage:     "path of input JSON state. Stdin if left empty.",
+		TakesFile: true,
+		Value:     "state.json",
+		Required:  true,
+	}
+	RunOutputFlag = &cli.PathFlag{
+		Name:      "output",
+		Usage:     "path of output JSON state. Stdout if left empty.",
+		TakesFile: true,
+		Value:     "out.json",
+		Required:  false,
+	}
+	patternHelp    = "'never' (default), 'always', '=123' at exactly step 123, '%123' for every 123 steps"
+	RunProofAtFlag = &cli.GenericFlag{
+		Name:     "proof-at",
+		Usage:    "step pattern to output proof at: " + patternHelp,
+		Value:    new(StepMatcherFlag),
+		Required: false,
+	}
+	RunProofFmtFlag = &cli.StringFlag{
+		Name:     "proof-fmt",
+		Usage:    "format for proof data output file names. Proof data is written to stdout if empty.",
+		Value:    "proof-%d.json",
+		Required: false,
+	}
+	RunSnapshotAtFlag = &cli.GenericFlag{
+		Name:     "snapshot-at",
+		Usage:    "step pattern to output snapshots at: " + patternHelp,
+		Value:    new(StepMatcherFlag),
+		Required: false,
+	}
+	RunSnapshotFmtFlag = &cli.StringFlag{
+		Name:     "snapshot-fmt",
+		Usage:    "format for snapshot output file names.",
+		Value:    "state-%d.json",
+		Required: false,
+	}
+	RunStopAtFlag = &cli.GenericFlag{
+		Name:     "stop-at",
+		Usage:    "step pattern to stop at: " + patternHelp,
+		Value:    new(StepMatcherFlag),
+		Required: false,
+	}
+	RunMetaFlag = &cli.PathFlag{
+		Name:     "meta",
+		Usage:    "path to metadata file for symbol lookup for enhanced debugging info durign execution.",
+		Value:    "meta.json",
+		Required: false,
+	}
+	RunInfoAtFlag = &cli.GenericFlag{
+		Name:     "info-at",
+		Usage:    "step pattern to print info at: " + patternHelp,
+		Value:    MustStepMatcherFlag("%100000"),
+		Required: false,
+	}
+	RunPProfCPU = &cli.BoolFlag{
+		Name:  "pprof.cpu",
+		Usage: "enable pprof cpu profiling",
+	}
+)
+
+type Proof struct {
+	Step uint64 `json:"step"`
+
+	Pre  common.Hash `json:"pre"`
+	Post common.Hash `json:"post"`
+
+	StepInput   hexutil.Bytes `json:"step-input"`
+	OracleInput hexutil.Bytes `json:"oracle-input"`
+}
+
+type rawHint string
+
+func (rh rawHint) Hint() string {
+	return string(rh)
+}
+
+type rawKey [32]byte
+
+func (rk rawKey) PreimageKey() [32]byte {
+	return rk
+}
+
+type ProcessPreimageOracle struct {
+	pCl *preimage.OracleClient
+	hCl *preimage.HintWriter
+	cmd *exec.Cmd
+}
+
+func NewProcessPreimageOracle(name string, args []string) (*ProcessPreimageOracle, error) {
+	if name == "" {
+		return &ProcessPreimageOracle{}, nil
+	}
+
+	pClientRW, pOracleRW, err := preimage.CreateBidirectionalChannel()
+	if err != nil {
+		return nil, err
+	}
+	hClientRW, hOracleRW, err := preimage.CreateBidirectionalChannel()
+	if err != nil {
+		return nil, err
+	}
+
+	cmd := exec.Command(name, args...)
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	cmd.ExtraFiles = []*os.File{
+		hOracleRW.Reader(),
+		hOracleRW.Writer(),
+		pOracleRW.Reader(),
+		pOracleRW.Writer(),
+	}
+	out := &ProcessPreimageOracle{
+		pCl: preimage.NewOracleClient(pClientRW),
+		hCl: preimage.NewHintWriter(hClientRW),
+		cmd: cmd,
+	}
+	return out, nil
+}
+
+func (p *ProcessPreimageOracle) Hint(v []byte) {
+	if p.hCl == nil { // no hint processor
+		return
+	}
+	p.hCl.Hint(rawHint(v))
+}
+
+func (p *ProcessPreimageOracle) GetPreimage(k [32]byte) []byte {
+	if p.pCl == nil {
+		panic("no pre-image retriever available")
+	}
+	return p.pCl.Get(rawKey(k))
+}
+
+func (p *ProcessPreimageOracle) Start() error {
+	if p.cmd == nil {
+		return nil
+	}
+	return p.cmd.Start()
+}
+
+func (p *ProcessPreimageOracle) Close() error {
+	if p.cmd == nil {
+		return nil
+	}
+	_ = p.cmd.Process.Signal(os.Interrupt)
+	p.cmd.WaitDelay = time.Second * 10
+	err := p.cmd.Wait()
+	if err, ok := err.(*exec.ExitError); ok {
+		if err.Success() {
+			return nil
+		}
+	}
+	return err
+}
+
+type StepFn func(proof bool) (*mipsevm.StepWitness, error)
+
+func Guard(proc *os.ProcessState, fn StepFn) StepFn {
+	return func(proof bool) (*mipsevm.StepWitness, error) {
+		wit, err := fn(proof)
+		if err != nil {
+			if proc.Exited() {
+				return nil, fmt.Errorf("pre-image server exited with code %d, resulting in err %v", proc.ExitCode(), err)
+			} else {
+				return nil, err
+			}
+		}
+		return wit, nil
+	}
+}
+
+var _ mipsevm.PreimageOracle = (*ProcessPreimageOracle)(nil)
+
+func Run(ctx *cli.Context) error {
+	if ctx.Bool(RunPProfCPU.Name) {
+		defer profile.Start(profile.NoShutdownHook, profile.ProfilePath("."), profile.CPUProfile).Stop()
+	}
+
+	state, err := loadJSON[mipsevm.State](ctx.Path(RunInputFlag.Name))
+	if err != nil {
+		return err
+	}
+
+	l := Logger(os.Stderr, log.LvlInfo)
+	outLog := &mipsevm.LoggingWriter{Name: "program std-out", Log: l}
+	errLog := &mipsevm.LoggingWriter{Name: "program std-err", Log: l}
+
+	// split CLI args after first '--'
+	args := ctx.Args().Slice()
+	for i, arg := range args {
+		if arg == "--" {
+			args = args[i+1:]
+			break
+		}
+	}
+	if len(args) == 0 {
+		args = []string{""}
+	}
+
+	po, err := NewProcessPreimageOracle(args[0], args[1:])
+	if err != nil {
+		return fmt.Errorf("failed to create pre-image oracle process: %w", err)
+	}
+	if err := po.Start(); err != nil {
+		return fmt.Errorf("failed to start pre-image oracle server: %w", err)
+	}
+	defer func() {
+		if err := po.Close(); err != nil {
+			l.Error("failed to close pre-image server", "err", err)
+		}
+	}()
+
+	stopAt := ctx.Generic(RunStopAtFlag.Name).(*StepMatcherFlag).Matcher()
+	proofAt := ctx.Generic(RunProofAtFlag.Name).(*StepMatcherFlag).Matcher()
+	snapshotAt := ctx.Generic(RunSnapshotAtFlag.Name).(*StepMatcherFlag).Matcher()
+	infoAt := ctx.Generic(RunInfoAtFlag.Name).(*StepMatcherFlag).Matcher()
+
+	var meta *mipsevm.Metadata
+	if metaPath := ctx.Path(RunMetaFlag.Name); metaPath == "" {
+		l.Info("no metadata file specified, defaulting to empty metadata")
+		meta = &mipsevm.Metadata{Symbols: nil} // provide empty metadata by default
+	} else {
+		if m, err := loadJSON[mipsevm.Metadata](metaPath); err != nil {
+			return fmt.Errorf("failed to load metadata: %w", err)
+		} else {
+			meta = m
+		}
+	}
+
+	us := mipsevm.NewInstrumentedState(state, po, outLog, errLog)
+	proofFmt := ctx.String(RunProofFmtFlag.Name)
+	snapshotFmt := ctx.String(RunSnapshotFmtFlag.Name)
+
+	stepFn := us.Step
+	if po.cmd != nil {
+		stepFn = Guard(po.cmd.ProcessState, stepFn)
+	}
+
+	start := time.Now()
+	startStep := state.Step
+
+	// avoid symbol lookups every instruction by preparing a matcher func
+	sleepCheck := meta.SymbolMatcher("runtime.notesleep")
+
+	for !state.Exited {
+		if state.Step%100 == 0 { // don't do the ctx err check (includes lock) too often
+			if err := ctx.Context.Err(); err != nil {
+				return err
+			}
+		}
+
+		step := state.Step
+
+		if infoAt(state) {
+			delta := time.Since(start)
+			l.Info("processing",
+				"step", step,
+				"pc", mipsevm.HexU32(state.PC),
+				"insn", mipsevm.HexU32(state.Memory.GetMemory(state.PC)),
+				"ips", float64(step-startStep)/(float64(delta)/float64(time.Second)),
+				"pages", state.Memory.PageCount(),
+				"mem", state.Memory.Usage(),
+				"name", meta.LookupSymbol(state.PC),
+			)
+		}
+
+		if sleepCheck(state.PC) { // don't loop forever when we get stuck because of an unexpected bad program
+			return fmt.Errorf("got stuck in Go sleep at step %d", step)
+		}
+
+		if stopAt(state) {
+			break
+		}
+
+		if snapshotAt(state) {
+			if err := writeJSON[*mipsevm.State](fmt.Sprintf(snapshotFmt, step), state, false); err != nil {
+				return fmt.Errorf("failed to write state snapshot: %w", err)
+			}
+		}
+
+		if proofAt(state) {
+			preStateHash := crypto.Keccak256Hash(state.EncodeWitness())
+			witness, err := stepFn(true)
+			if err != nil {
+				return fmt.Errorf("failed at proof-gen step %d (PC: %08x): %w", step, state.PC, err)
+			}
+			postStateHash := crypto.Keccak256Hash(state.EncodeWitness())
+			proof := &Proof{
+				Step:      step,
+				Pre:       preStateHash,
+				Post:      postStateHash,
+				StepInput: witness.EncodeStepInput(),
+			}
+			if witness.HasPreimage() {
+				proof.OracleInput, err = witness.EncodePreimageOracleInput()
+				if err != nil {
+					return fmt.Errorf("failed to encode pre-image oracle input: %w", err)
+				}
+			}
+			if err := writeJSON[*Proof](fmt.Sprintf(proofFmt, step), proof, true); err != nil {
+				return fmt.Errorf("failed to write proof data: %w", err)
+			}
+		} else {
+			_, err = stepFn(false)
+			if err != nil {
+				return fmt.Errorf("failed at step %d (PC: %08x): %w", step, state.PC, err)
+			}
+		}
+	}
+
+	if err := writeJSON[*mipsevm.State](ctx.Path(RunOutputFlag.Name), state, true); err != nil {
+		return fmt.Errorf("failed to write state output: %w", err)
+	}
+	return nil
+}
+
+var RunCommand = &cli.Command{
+	Name:        "run",
+	Usage:       "Run VM step(s) and generate proof data to replicate onchain.",
+	Description: "Run VM step(s) and generate proof data to replicate onchain. See flags to match when to output a proof, a snapshot, or to stop early.",
+	Action:      Run,
+	Flags: []cli.Flag{
+		RunInputFlag,
+		RunOutputFlag,
+		RunProofAtFlag,
+		RunProofFmtFlag,
+		RunSnapshotAtFlag,
+		RunSnapshotFmtFlag,
+		RunStopAtFlag,
+		RunMetaFlag,
+		RunInfoAtFlag,
+		RunPProfCPU,
+	},
+}

cannon/contracts/foundry.toml

+# Config Reference: https://github.com/foundry-rs/foundry/tree/master/config
+
+[profile.default]
+src = 'src'
+out = 'out'
+libs = []
+ffi = false
+fs_permissions = []
+
+[fmt]
+bracket_spacing = true

cannon/contracts/src/MIPS.sol

+// SPDX-License-Identifier: MIT
+pragma solidity ^0.7.6;
+
+interface IOracle {
+  function readPreimage(bytes32 key, uint256 offset) external view returns (bytes32 dat, uint256 datLen);
+}
+
+// https://inst.eecs.berkeley.edu/~cs61c/resources/MIPS_Green_Sheet.pdf
+// https://uweb.engr.arizona.edu/~ece369/Resources/spim/MIPSReference.pdf
+// https://en.wikibooks.org/wiki/MIPS_Assembly/Instruction_Formats
+
+// https://www.cs.cmu.edu/afs/cs/academic/class/15740-f97/public/doc/mips-isa.pdf
+// page A-177
+
+// MIPS linux kernel errors used by Go runtime:
+// https://github.com/golang/go/blob/master/src/syscall/zerrors_linux_mips.go
+
+// This MIPS contract emulates a single MIPS instruction.
+//
+// Note that delay slots are isolated instructions:
+// the nextPC in the state pre-schedules where the VM jumps next.
+//
+// The Step input is a packed VM state, with binary-merkle-tree witness data for memory reads/writes.
+// The Step outputs a keccak256 hash of the packed VM State, and logs the resulting state for offchain usage.
+contract MIPS {
+
+  struct State {
+    bytes32 memRoot;
+    bytes32 preimageKey;
+    uint32 preimageOffset;
+    uint32 pc;
+    uint32 nextPC;  // State is executing a branch/jump delay slot if nextPC != pc+4
+    uint32 lo;
+    uint32 hi;
+    uint32 heap;
+    uint8 exitCode;
+    bool exited;
+    uint64 step;
+    uint32[32] registers;
+  }
+
+  // total State size: 32+32+6*4+1+1+8+32*4 = 226 bytes
+
+  uint32 constant public BRK_START = 0x40000000;
+
+  uint32 constant FD_STDIN = 0;
+  uint32 constant FD_STDOUT = 1;
+  uint32 constant FD_STDERR = 2;
+  uint32 constant FD_HINT_READ = 3;
+  uint32 constant FD_HINT_WRITE = 4;
+  uint32 constant FD_PREIMAGE_READ = 5;
+  uint32 constant FD_PREIMAGE_WRITE = 6;
+
+  uint32 constant EBADF = 0x9;
+  uint32 constant EINVAL = 0x16;
+
+  IOracle public oracle;
+
+  function SE(uint32 dat, uint32 idx) internal pure returns (uint32) {
+    bool isSigned = (dat >> (idx-1)) != 0;
+    uint256 signed = ((1 << (32-idx)) - 1) << idx;
+    uint256 mask = (1 << idx) - 1;
+    return uint32(dat&mask | (isSigned ? signed : 0));
+  }
+
+  function outputState() internal returns (bytes32 out) {
+    assembly {
+      // copies 'size' bytes, right-aligned in word at 'from', to 'to', incl. trailing data
+      function copyMem(from, to, size) -> fromOut, toOut {
+        mstore(to, mload(add(from, sub(32, size))))
+        fromOut := add(from, 32)
+        toOut := add(to, size)
+      }
+      let from := 0x80 // state
+      let start := mload(0x40) // free mem ptr
+      let to := start
+      from, to := copyMem(from, to, 32) // memRoot
+      from, to := copyMem(from, to, 32) // preimageKey
+      from, to := copyMem(from, to, 4) // preimageOffset
+      from, to := copyMem(from, to, 4) // pc
+      from, to := copyMem(from, to, 4) // nextPC
+      from, to := copyMem(from, to, 4) // lo
+      from, to := copyMem(from, to, 4) // hi
+      from, to := copyMem(from, to, 4) // heap
+      from, to := copyMem(from, to, 1) // exitCode
+      from, to := copyMem(from, to, 1) // exited
+      from, to := copyMem(from, to, 8) // step
+      from := add(from, 32) // offset to registers
+      for { let i := 0 } lt(i, 32) { i := add(i, 1) } { from, to := copyMem(from, to, 4) } // registers
+      mstore(to, 0) // clean up end
+      log0(start, sub(to, start)) // log the resulting MIPS state, for debugging
+      out := keccak256(start, sub(to, start))
+    }
+    return out;
+  }
+
+  function handleSyscall() internal returns (bytes32) {
+    State memory state;
+    assembly {
+      state := 0x80
+    }
+    uint32 syscall_no = state.registers[2];
+    uint32 v0 = 0;
+    uint32 v1 = 0;
+
+    uint32 a0 = state.registers[4];
+    uint32 a1 = state.registers[5];
+    uint32 a2 = state.registers[6];
+
+    if (syscall_no == 4090) {
+      // mmap
+      uint32 sz = a1;
+      if (sz&4095 != 0) { // adjust size to align with page size
+        sz += 4096 - (sz&4095);
+      }
+      if (a0 == 0) {
+        v0 = state.heap;
+        state.heap += sz;
+      } else {
+        v0 = a0;
+      }
+    } else if (syscall_no == 4045) {
+      // brk
+      v0 = BRK_START;
+    } else if (syscall_no == 4120) {
+      // clone (not supported)
+      v0 = 1;
+    } else if (syscall_no == 4246) {
+      // exit group
+      state.exited = true;
+      state.exitCode = uint8(a0);
+      return outputState();
+    } else if (syscall_no == 4003) { // read
+      // args: a0 = fd, a1 = addr, a2 = count
+      // returns: v0 = read, v1 = err code
+      if (a0 == FD_STDIN) {
+        // leave v0 and v1 zero: read nothing, no error
+      } else if (a0 == FD_PREIMAGE_READ) { // pre-image oracle
+        // verify proof 1 is correct, and get the existing memory.
+        uint32 mem = readMem(a1 & 0xFFffFFfc, 1); // mask the addr to align it to 4 bytes
+        (bytes32 dat, uint256 datLen) = oracle.readPreimage(state.preimageKey, state.preimageOffset);
+        assembly { // assembly for more precise ops, and no var count limit
+          let alignment := and(a1, 3) // the read might not start at an aligned address
+          let space := sub(4, alignment) // remaining space in memory word
+          if lt(space, datLen) { datLen := space } // if less space than data, shorten data
+          if lt(a2, datLen) { datLen := a2 } // if requested to read less, read less
+          dat := shr(sub(256, mul(datLen, 8)), dat) // right-align data
+          dat := shl(mul(alignment, 8), dat) // position data to insert into memory word
+          let mask := sub(shl(mul(sub(4, alignment), 8), 1), 1) // mask all bytes after start
+          let suffixMask := sub(shl(mul(add(sub(4, alignment), datLen), 8), 1), 1) // mask of all bytes starting from end, maybe none
+          mask := and(mask, not(suffixMask)) // reduce mask to just cover the data we insert
+          mem := or(and(mem, not(mask)), dat) // clear masked part of original memory, and insert data
+        }
+        writeMem(a1 & 0xFFffFFfc, 1, mem);
+        state.preimageOffset += uint32(datLen);
+        v0 = uint32(datLen);
+      } else if (a0 == FD_HINT_READ) { // hint response
+        // don't actually read into memory, just say we read it all, we ignore the result anyway
+        v0 = a2;
+      } else {
+        v0 = 0xFFffFFff;
+        v1 = EBADF;
+      }
+    } else if (syscall_no == 4004) { // write
+      // args: a0 = fd, a1 = addr, a2 = count
+      // returns: v0 = written, v1 = err code
+      if (a0 == FD_STDOUT || a0 == FD_STDERR || a0 == FD_HINT_WRITE) {
+        v0 = a2; // tell program we have written everything
+      } else if (a0 == FD_PREIMAGE_WRITE) { // pre-image oracle
+        uint32 mem = readMem(a1 & 0xFFffFFfc, 1); // mask the addr to align it to 4 bytes
+        bytes32 key = state.preimageKey;
+        assembly { // assembly for more precise ops, and no var count limit
+          let alignment := and(a1, 3) // the read might not start at an aligned address
+          let space := sub(4, alignment) // remaining space in memory word
+          if lt(space, a2) { a2 := space } // if less space than data, shorten data
+          key := shl(mul(a2, 8), key) // shift key, make space for new info
+          let mask := sub(shl(mul(a2, 8), 1), 1) // mask for extracting value from memory
+          mem := and(shr(mul(sub(space, a2), 8), mem), mask) // align value to right, mask it
+          key := or(key, mem) // insert into key
+        }
+        state.preimageKey = key;
+        state.preimageOffset = 0; // reset offset, to read new pre-image data from the start
+        v0 = a2;
+      } else {
+        v0 = 0xFFffFFff;
+        v1 = EBADF;
+      }
+    } else if (syscall_no == 4055) { // fcntl
+      // args: a0 = fd, a1 = cmd
+      if (a1 == 3) { // F_GETFL: get file descriptor flags
+        if (a0 == FD_STDIN || a0 == FD_PREIMAGE_READ || a0 == FD_HINT_READ) {
+          v0 = 0; // O_RDONLY
+        } else if (a0 == FD_STDOUT || a0 == FD_STDERR || a0 == FD_PREIMAGE_WRITE || a0 == FD_HINT_WRITE) {
+          v0 = 1; // O_WRONLY
+        } else {
+          v0 = 0xFFffFFff;
+          v1 = EBADF;
+        }
+      } else {
+        v0 = 0xFFffFFff;
+        v1 = EINVAL; // cmd not recognized by this kernel
+      }
+    }
+
+    state.registers[2] = v0;
+    state.registers[7] = v1;
+
+    state.pc = state.nextPC;
+    state.nextPC = state.nextPC + 4;
+
+    return outputState();
+  }
+
+  function handleBranch(uint32 opcode, uint32 insn, uint32 rtReg, uint32 rs) internal returns (bytes32) {
+    State memory state;
+    assembly {
+      state := 0x80
+    }
+    bool shouldBranch = false;
+
+    if (opcode == 4 || opcode == 5) {   // beq/bne
+      uint32 rt = state.registers[rtReg];
+      shouldBranch = (rs == rt && opcode == 4) || (rs != rt && opcode == 5);
+    } else if (opcode == 6) { shouldBranch = int32(rs) <= 0; // blez
+    } else if (opcode == 7) { shouldBranch = int32(rs) > 0; // bgtz
+    } else if (opcode == 1) {
+      // regimm
+      uint32 rtv = ((insn >> 16) & 0x1F);
+      if (rtv == 0) shouldBranch = int32(rs) < 0;  // bltz
+      if (rtv == 1) shouldBranch = int32(rs) >= 0; // bgez
+    }
+
+    uint32 prevPC = state.pc;
+    state.pc = state.nextPC; // execute the delay slot first
+    if (shouldBranch) {
+      state.nextPC = prevPC + 4 + (SE(insn&0xFFFF, 16)<<2); // then continue with the instruction the branch jumps to.
+    } else {
+      state.nextPC = state.nextPC + 4; // branch not taken
+    }
+
+    return outputState();
+  }
+
+  function handleHiLo(uint32 func, uint32 rs, uint32 rt, uint32 storeReg) internal returns (bytes32) {
+    State memory state;
+    assembly {
+      state := 0x80
+    }
+    uint32 val;
+    if (func == 0x10) val = state.hi; // mfhi
+    else if (func == 0x11) state.hi = rs; // mthi
+    else if (func == 0x12) val = state.lo; // mflo
+    else if (func == 0x13) state.lo = rs; // mtlo
+    else if (func == 0x18) { // mult
+      uint64 acc = uint64(int64(int32(rs))*int64(int32(rt)));
+      state.hi = uint32(acc>>32);
+      state.lo = uint32(acc);
+    } else if (func == 0x19) { // multu
+      uint64 acc = uint64(uint64(rs)*uint64(rt));
+      state.hi = uint32(acc>>32);
+      state.lo = uint32(acc);
+    } else if (func == 0x1a) { // div
+      state.hi = uint32(int32(rs)%int32(rt));
+      state.lo = uint32(int32(rs)/int32(rt));
+    } else if (func == 0x1b) { // divu
+      state.hi = rs%rt;
+      state.lo = rs/rt;
+    }
+
+    if (storeReg != 0) {
+      state.registers[storeReg] = val;
+    }
+
+    state.pc = state.nextPC;
+    state.nextPC = state.nextPC + 4;
+
+    return outputState();
+  }
+
+  function handleJump(uint32 linkReg, uint32 dest) internal returns (bytes32) {
+    State memory state;
+    assembly {
+      state := 0x80
+    }
+    uint32 prevPC = state.pc;
+    state.pc = state.nextPC;
+    state.nextPC = dest;
+    if (linkReg != 0) {
+      state.registers[linkReg] = prevPC+8; // set the link-register to the instr after the delay slot instruction.
+    }
+    return outputState();
+  }
+
+  function handleRd(uint32 storeReg, uint32 val, bool conditional) internal returns (bytes32) {
+    State memory state;
+    assembly {
+      state := 0x80
+    }
+    require(storeReg < 32, "valid register");
+    // never write to reg 0, and it can be conditional (movz, movn)
+    if (storeReg != 0 && conditional) {
+      state.registers[storeReg] = val;
+    }
+
+    state.pc = state.nextPC;
+    state.nextPC = state.nextPC + 4;
+
+    return outputState();
+  }
+
+  function proofOffset(uint8 proofIndex) internal pure returns (uint256 offset) {
+    // A proof of 32 bit memory, with 32-byte leaf values, is (32-5)=27 bytes32 entries.
+    // And the leaf value itself needs to be encoded as well. And proof.offset == 358
+    offset = 358 + (uint256(proofIndex) * (28*32));
+    uint256 s = 0;
+    assembly { s := calldatasize() }
+    require(s >= (offset + 28*32), "check that there is enough calldata");
+    return offset;
+  }
+
+  function readMem(uint32 addr, uint8 proofIndex) internal pure returns (uint32 out) {
+    uint256 offset = proofOffset(proofIndex);
+    assembly {
+      if and(addr, 3) { revert(0, 0) } // quick addr alignment check
+      let leaf := calldataload(offset)
+      offset := add(offset, 32)
+      function hashPair(a, b) -> h {
+        mstore(0, a) // use scratch space slots to hash the two nodes together
+        mstore(32, b)
+        h := keccak256(0, 64)
+      }
+      let path := shr(5, addr)
+      let node := leaf // starting from the leaf node, work back up by combining with siblings, to reconstruct the root
+      for { let i := 0 } lt(i, 27) { i := add(i, 1) } {
+        let sibling := calldataload(offset)
+        offset := add(offset, 32)
+        switch and(shr(i, path), 1)
+        case 0 { node := hashPair(node, sibling) }
+        case 1 { node := hashPair(sibling, node) }
+      }
+      let memRoot := mload(0x80) // load memRoot, first field of state
+      if iszero(eq(node, memRoot)) { // verify the root matches
+        mstore(0, 0x0badf00d)
+        revert(0, 32)
+      }
+      // bits to shift = (32 - 4 - (addr % 32)) * 8
+      let shamt := shl(3, sub(sub(32, 4), and(addr, 31)))
+      out := and(shr(shamt, leaf), 0xFFffFFff)
+    }
+    return out;
+  }
+
+  // writeMem writes the value by first overwriting the part of the leaf, and then recomputing the memory merkle root.
+  function writeMem(uint32 addr, uint8 proofIndex, uint32 value) internal pure {
+    uint256 offset = proofOffset(proofIndex);
+    assembly {
+      if and(addr, 3) { revert(0, 0) } // quick addr alignment check
+      let leaf := calldataload(offset)
+      let shamt := shl(3, sub(sub(32, 4), and(addr, 31)))
+      // mask out 4 bytes, and OR in the value
+      leaf := or(and(leaf, not(shl(shamt, 0xFFffFFff))), shl(shamt, value))
+      offset := add(offset, 32)
+      function hashPair(a, b) -> h {
+        mstore(0, a) // use scratch space slots to hash the two nodes together
+        mstore(32, b)
+        h := keccak256(0, 64)
+      }
+      let path := shr(5, addr)
+      let node := leaf // starting from the leaf node, work back up by combining with siblings, to reconstruct the root
+      for { let i := 0 } lt(i, 27) { i := add(i, 1) } {
+        let sibling := calldataload(offset)
+        offset := add(offset, 32)
+        switch and(shr(i, path), 1)
+        case 0 { node := hashPair(node, sibling) }
+        case 1 { node := hashPair(sibling, node) }
+      }
+      mstore(0x80, node) // store new memRoot, first field of state
+    }
+  }
+
+  // will revert if any required input state is missing
+  function Step(bytes calldata stateData, bytes calldata proof) public returns (bytes32) {
+    State memory state;
+    // packed data is ~6 times smaller
+    assembly {
+      if iszero(eq(state, 0x80)) { // expected state mem offset check
+        revert(0,0)
+      }
+      if iszero(eq(mload(0x40), mul(32, 48))) { // expected memory check
+        revert(0,0)
+      }
+      if iszero(eq(stateData.offset, 100)) { // 32*3+4=100 expected state data offset
+        revert(0,0)
+      }
+      if iszero(eq(proof.offset, 358)) { // 100+32+226=358 expected proof offset
+        revert(0,0)
+      }
+      function putField(callOffset, memOffset, size) -> callOffsetOut, memOffsetOut {
+        // calldata is packed, thus starting left-aligned, shift-right to pad and right-align
+        let w := shr(shl(3, sub(32, size)), calldataload(callOffset))
+        mstore(memOffset, w)
+        callOffsetOut := add(callOffset, size)
+        memOffsetOut := add(memOffset, 32)
+      }
+      let c := stateData.offset // calldata offset
+      let m := 0x80 // mem offset
+      c, m := putField(c, m, 32) // memRoot
+      c, m := putField(c, m, 32) // preimageKey
+      c, m := putField(c, m, 4) // preimageOffset
+      c, m := putField(c, m, 4) // pc
+      c, m := putField(c, m, 4) // nextPC
+      c, m := putField(c, m, 4) // lo
+      c, m := putField(c, m, 4) // hi
+      c, m := putField(c, m, 4) // heap
+      c, m := putField(c, m, 1) // exitCode
+      c, m := putField(c, m, 1) // exited
+      c, m := putField(c, m, 8) // step
+      mstore(m, add(m, 32)) // offset to registers
+      m := add(m, 32)
+      for { let i := 0 } lt(i, 32) { i := add(i, 1) } { c, m := putField(c, m, 4) } // registers
+    }
+    if(state.exited) { // don't change state once exited
+      return outputState();
+    }
+    state.step += 1;
+
+    // instruction fetch
+    uint32 insn = readMem(state.pc, 0);
+
+    uint32 opcode = insn >> 26; // 6-bits
+
+    // j-type j/jal
+    if (opcode == 2 || opcode == 3) {
+      // TODO likely bug in original code: MIPS spec says this should be in the "current" region;
+      // a 256 MB aligned region (i.e. use top 4 bits of branch delay slot (pc+4))
+      return handleJump(opcode == 2 ? 0 : 31, SE(insn&0x03FFFFFF, 26) << 2);
+    }
+
+    // register fetch
+    uint32 rs; // source register 1 value
+    uint32 rt; // source register 2 / temp value
+    uint32 rtReg = (insn >> 16) & 0x1F;
+
+    // R-type or I-type (stores rt)
+    rs = state.registers[(insn >> 21) & 0x1F];
+    uint32 rdReg = rtReg;
+    if (opcode == 0 || opcode == 0x1c) {
+      // R-type (stores rd)
+      rt = state.registers[rtReg];
+      rdReg = (insn >> 11) & 0x1F;
+    } else if (opcode < 0x20) {
+      // rt is SignExtImm
+      // don't sign extend for andi, ori, xori
+      if (opcode == 0xC || opcode == 0xD || opcode == 0xe) {
+        // ZeroExtImm
+        rt = insn&0xFFFF;
+      } else {
+        // SignExtImm
+        rt = SE(insn&0xFFFF, 16);
+      }
+    } else if (opcode >= 0x28 || opcode == 0x22 || opcode == 0x26) {
+      // store rt value with store
+      rt = state.registers[rtReg];
+
+      // store actual rt with lwl and lwr
+      rdReg = rtReg;
+    }
+
+    if ((opcode >= 4 && opcode < 8) || opcode == 1) {
+      return handleBranch(opcode, insn, rtReg, rs);
+    }
+
+    uint32 storeAddr = 0xFF_FF_FF_FF;
+    // memory fetch (all I-type)
+    // we do the load for stores also
+    uint32 mem;
+    if (opcode >= 0x20) {
+      // M[R[rs]+SignExtImm]
+      rs += SE(insn&0xFFFF, 16);
+      uint32 addr = rs & 0xFFFFFFFC;
+      mem = readMem(addr, 1);
+      if (opcode >= 0x28 && opcode != 0x30) {
+        // store
+        storeAddr = addr;
+        // store opcodes don't write back to a register
+        rdReg = 0;
+      }
+    }
+
+    // ALU
+    uint32 val = execute(insn, rs, rt, mem) & 0xffFFffFF; // swr outputs more than 4 bytes without the mask
+
+    uint32 func = insn & 0x3f; // 6-bits
+    if (opcode == 0 && func >= 8 && func < 0x1c) {
+      if (func == 8 || func == 9) { // jr/jalr
+        return handleJump(func == 8 ? 0 : rdReg, rs);
+      }
+
+      if (func == 0xa) { // movz
+        return handleRd(rdReg, rs, rt == 0);
+      }
+      if (func == 0xb) { // movn
+        return handleRd(rdReg, rs, rt != 0);
+      }
+
+      // syscall (can read and write)
+      if (func == 0xC) {
+        return handleSyscall();
+      }
+
+      // lo and hi registers
+      // can write back
+      if (func >= 0x10 && func < 0x1c) {
+        return handleHiLo(func, rs, rt, rdReg);
+      }
+    }
+
+    // stupid sc, write a 1 to rt
+    if (opcode == 0x38 && rtReg != 0) {
+      state.registers[rtReg] = 1;
+    }
+
+    // write memory
+    if (storeAddr != 0xFF_FF_FF_FF) {
+      writeMem(storeAddr, 1, val);
+    }
+
+    // write back the value to destination register
+    return handleRd(rdReg, val, true);
+  }
+
+  function execute(uint32 insn, uint32 rs, uint32 rt, uint32 mem) internal pure returns (uint32) {
+    uint32 opcode = insn >> 26;    // 6-bits
+    uint32 func = insn & 0x3f; // 6-bits
+    // TODO: deref the immed into a register
+
+    if (opcode < 0x20) {
+      // transform ArithLogI
+      // TODO: replace with table
+      if (opcode >= 8 && opcode < 0xF) {
+        if (opcode == 8) { func = 0x20; }        // addi
+        else if (opcode == 9) { func = 0x21; }   // addiu
+        else if (opcode == 0xa) { func = 0x2a; } // slti
+        else if (opcode == 0xb) { func = 0x2B; } // sltiu
+        else if (opcode == 0xc) { func = 0x24; } // andi
+        else if (opcode == 0xd) { func = 0x25; } // ori
+        else if (opcode == 0xe) { func = 0x26; } // xori
+        opcode = 0;
+      }
+
+      // 0 is opcode SPECIAL
+      if (opcode == 0) {
+        uint32 shamt = (insn >> 6) & 0x1f;
+        if (func < 0x20) {
+          if (func >= 0x08) { return rs;  // jr/jalr/div + others
+          // Shift and ShiftV
+          } else if (func == 0x00) { return rt << shamt;      // sll
+          } else if (func == 0x02) { return rt >> shamt;      // srl
+          } else if (func == 0x03) { return SE(rt >> shamt, 32-shamt);      // sra
+          } else if (func == 0x04) { return rt << (rs&0x1F);         // sllv
+          } else if (func == 0x06) { return rt >> (rs&0x1F);         // srlv
+          } else if (func == 0x07) { return SE(rt >> rs, 32-rs);     // srav
+          }
+        }
+        // 0x10-0x13 = mfhi, mthi, mflo, mtlo
+        // R-type (ArithLog)
+        if (func == 0x20 || func == 0x21) { return rs+rt;   // add or addu
+        } else if (func == 0x22 || func == 0x23) { return rs-rt;   // sub or subu
+        } else if (func == 0x24) { return rs&rt;            // and
+        } else if (func == 0x25) { return (rs|rt);          // or
+        } else if (func == 0x26) { return (rs^rt);          // xor
+        } else if (func == 0x27) { return ~(rs|rt);         // nor
+        } else if (func == 0x2a) {
+          return int32(rs)<int32(rt) ? 1 : 0; // slt
+        } else if (func == 0x2B) {
+          return rs<rt ? 1 : 0;               // sltu
+        }
+      } else if (opcode == 0xf) { return rt<<16; // lui
+      } else if (opcode == 0x1c) {  // SPECIAL2
+        if (func == 2) return uint32(int32(rs)*int32(rt)); // mul
+        if (func == 0x20 || func == 0x21) { // clo
+          if (func == 0x20) rs = ~rs;
+          uint32 i = 0; while (rs&0x80000000 != 0) { i++; rs <<= 1; } return i;
+        }
+      }
+    } else if (opcode < 0x28) {
+      if (opcode == 0x20) {  // lb
+        return SE((mem >> (24-(rs&3)*8)) & 0xFF, 8);
+      } else if (opcode == 0x21) {  // lh
+        return SE((mem >> (16-(rs&2)*8)) & 0xFFFF, 16);
+      } else if (opcode == 0x22) {  // lwl
+        uint32 val = mem << ((rs&3)*8);
+        uint32 mask = uint32(0xFFFFFFFF) << ((rs&3)*8);
+        return (rt & ~mask) | val;
+      } else if (opcode == 0x23) { return mem;   // lw
+      } else if (opcode == 0x24) {  // lbu
+        return (mem >> (24-(rs&3)*8)) & 0xFF;
+      } else if (opcode == 0x25) {  // lhu
+        return (mem >> (16-(rs&2)*8)) & 0xFFFF;
+      } else if (opcode == 0x26) {  // lwr
+        uint32 val = mem >> (24-(rs&3)*8);
+        uint32 mask = uint32(0xFFFFFFFF) >> (24-(rs&3)*8);
+        return (rt & ~mask) | val;
+      }
+    } else if (opcode == 0x28) { // sb
+      uint32 val = (rt&0xFF) << (24-(rs&3)*8);
+      uint32 mask = 0xFFFFFFFF ^ uint32(0xFF << (24-(rs&3)*8));
+      return (mem & mask) | val;
+    } else if (opcode == 0x29) { // sh
+      uint32 val = (rt&0xFFFF) << (16-(rs&2)*8);
+      uint32 mask = 0xFFFFFFFF ^ uint32(0xFFFF << (16-(rs&2)*8));
+      return (mem & mask) | val;
+    } else if (opcode == 0x2a) {  // swl
+      uint32 val = rt >> ((rs&3)*8);
+      uint32 mask = uint32(0xFFFFFFFF) >> ((rs&3)*8);
+      return (mem & ~mask) | val;
+    } else if (opcode == 0x2b) { // sw
+      return rt;
+    } else if (opcode == 0x2e) {  // swr
+      uint32 val = rt << (24-(rs&3)*8);
+      uint32 mask = uint32(0xFFFFFFFF) << (24-(rs&3)*8);
+      return (mem & ~mask) | val;
+    } else if (opcode == 0x30) { return mem; // ll
+    } else if (opcode == 0x38) { return rt; // sc
+    }
+
+    revert("invalid instruction");
+  }
+}

cannon/contracts/src/Oracle.sol

+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+
+contract Oracle {
+
+    mapping (bytes32 => uint256) public preimageLengths;
+    mapping (bytes32 => mapping(uint256 => bytes32)) preimageParts;
+    mapping (bytes32 => mapping(uint256 => bool)) preimagePartOk;
+
+    function readPreimage(bytes32 key, uint256 offset) external view returns (bytes32 dat, uint256 datLen) {
+        require(preimagePartOk[key][offset], "preimage must exist");
+        datLen = 32;
+        uint256 length = preimageLengths[key];
+        if(offset + 32 >= length + 8) { // add 8 for the length-prefix part
+            datLen = length + 8 - offset;
+        }
+        dat = preimageParts[key][offset];
+    }
+
+    // TODO: we need to mix-in the ID of the dispute for local-type keys to avoid collisions,
+    // and restrict local pre-image insertion to the dispute-managing contract.
+    // For now we permit anyone to write any pre-image unchecked, to make testing easy.
+    // This method is DANGEROUS. And NOT FOR PRODUCTION.
+    function cheat(uint256 partOffset, bytes32 key, bytes32 part, uint256 size) external {
+        preimagePartOk[key][partOffset] = true;
+        preimageParts[key][partOffset] = part;
+        preimageLengths[key] = size;
+    }
+
+    // loadKeccak256PreimagePart prepares the pre-image to be read by keccak256 key,
+    // starting at the given offset, up to 32 bytes (clipped at preimage length, if out of data).
+    function loadKeccak256PreimagePart(uint256 partOffset, bytes calldata preimage) external {
+        uint256 size;
+        bytes32 key;
+        bytes32 part;
+        assembly {
+            size := calldataload(0x44) // len(sig) + len(partOffset) + len(preimage offset) = 4 + 32 + 32 = 0x44
+            if iszero(lt(partOffset, add(size, 8))) { // revert if part offset >= size+8 (i.e. parts must be within bounds)
+                revert(0, 0)
+            }
+            let ptr := 0x80 // we leave solidity slots 0x40 and 0x60 untouched, and everything after as scratch-memory.
+            mstore(ptr, shl(192, size)) // put size as big-endian uint64 at start of pre-image
+            ptr := add(ptr, 8)
+            calldatacopy(ptr, preimage.offset, size) // copy preimage payload into memory so we can hash and read it.
+            // Note that it includes the 8-byte big-endian uint64 length prefix.
+            // this will be zero-padded at the end, since memory at end is clean.
+            part := mload(add(sub(ptr, 8), partOffset))
+            let h := keccak256(ptr, size) // compute preimage keccak256 hash
+            key := or(and(h, not(shl(248, 0xFF))), shl(248, 2)) // mask out prefix byte, replace with type 2 byte
+        }
+        preimagePartOk[key][partOffset] = true;
+        preimageParts[key][partOffset] = part;
+        preimageLengths[key] = size;
+    }
+}

cannon/docs/README.md

+# Cannon Overview
+
+Cannon has two main components:
+- Onchain `MIPS.sol`: EVM implementation to verify execution of a single MIPS instruction.
+- Offchain `mipsevm`: Go implementation to produce a proof for any MIPS instruction to verify onchain.
+
+Between these two modes of operation, the [witness data](#witness-data) is essential,
+to reproduce the same instruction onchain as offchain.
+
+## Onchain `MIPS.sol`
+
+This is an onchain implementation of big-endian 32-bit MIPS instruction execution.
+This covers MIPS III, R3000, as required by the `mips` Go compiler/runtime target.
+
+The systemcall instruction is implemented to simulate a minimal subset of the Linux kernel,
+just enough to serve the needs of a basic Go program:
+allocate memory, read/write to certain file-descriptors, and exit.
+
+Note that this does not include concurrency related system calls: when running Go programs,
+the GC has to be disabled, since it runs concurrently.
+This is done by patching out specific runtime functions that start the GC,
+by simply inserting jumps to the return-address, before the functions spin up any additional threads.
+
+
+## Offchain `mipsevm`
+
+This is an instrumented emulator, also running big-endian 32-bit MIPS, that executes one step at a time,
+and maintains the same state as used for onchain execution.
+The difference is that it has access to the full memory, and pre-image oracle.
+And as it executes each step, it can optionally produce the witness data for the step, to repeat it onchain.
+
+The Cannon CLI is used to load a program into an initial state,
+transition it N steps quickly without witness generation, and 1 step while producing a witness.
+
+`mipsevm` is backed by the Unicorn emulator, but instrumented for proof generation,
+and handles delay-slots by isolating each individual instruction and tracking `nextPC`
+to emulate the delayed `PC` changes after delay-slot execution.
+
+## Witness Data
+
+There are 3 types of witness data involved in onchain execution:
+- [Packed State](#packed-state)
+- [Memory proofs](#memory-proofs) 
+- [Pre-image data](#pre-image-data)
+
+### Packed State
+
+The following state is packed together, and provided in every executed onchain instruction:
+```solidity
+struct State {
+  bytes32 memRoot;
+  bytes32 preimageKey;
+  uint32 preimageOffset;
+  uint32 pc;
+  uint32 nextPC;
+  uint32 lo;
+  uint32 hi;
+  uint32 heap;
+  uint8 exitCode;
+  bool exited;
+  uint64 step;
+  uint32[32] registers;
+}
+```
+
+The packed state is small! The `State` data can be packed in such a small amount of EVM words,
+that it is more efficient to fully provide it, than to create a proof for each individual part involved in execution.
+
+The memory is represented as a merkle-tree root, committing to a binary merkle tree of all memory data,
+see [memory proofs](#memory-proofs).
+
+The `State` covers all general purpose registers, as well as the `lo`, `hi` and `pc` values.
+
+`nextPC` helps pre-schedule the program counter change, to emulate delay-slot behavior of MIPS
+after branch and jump instructions.
+
+The program stops changing the state when `exited` is set to true. The exit-code is remembered,
+to determine if the program is successful, or panicked/exited in some unexpected way.
+This outcome can be used to determine truthiness of claims that are verified as part of the program execution.
+
+The `heap` value is a special value, used to emulate a growing heap, to map new memory upon `mmap` calls by the program.
+No memory reads/writes are actually illegal however, mmap-ing is purely to satisfy program runtimes that
+need the memory-pointer result of the syscall to locate free memory.
+
+The `preimageKey` and `preimageOffset` are backing the in-flight communication of [pre-image data](#pre-image-data).
+
+The VM `stateHash` is computed as `keccak256(encoded_packed_state)`,
+where `encoded_packed_state` is the concatenation of all state-values (all `uint` values are big-endian).
+
+
+### Memory proofs
+
+Simplicity is key here. Previous versions of Cannon used to overlap memory and register state,
+and represent it with a Merkle Patricia Trie.
+This added a lot of complexity, as there would be multiple dynamically-sized MPT proofs,
+with read and write operations, during a single instruction.
+
+Instead, memory in Cannon is now represented as a binary merkle tree:
+The tree has a fixed-depth of 27 levels, with leaf values of 32 bytes each.
+This spans the full 32-bit address space: `2**27 * 32 = 2**32`.
+Each leaf contains the memory at that part of the tree.
+
+The tree is efficiently allocated, since the root of fully zeroed sub-trees
+can be computed without actually creating the full-subtree: `zero_hash[d] = hash(zero_hash[d-1], zero_hash[d-1])`,
+until the base-case of `zero_hash[0] == bytes32(0)`.
+
+Nodes in this memory tree are combined as: `out = keccak256(left ++ right)`, where `++` is concatenation,
+and `left` and `right` are the 32-byte outputs of the respective sub-trees or the leaf values themselves.
+Individual leaf nodes are not hashed.
+
+The proof format is a concatenated byte array of 28 `bytes32`. The first `bytes32` is the leaf value,
+and the remaining 27 `bytes32` are the sibling nodes up till the root of the tree,
+along the branch of the leaf value, starting from the bottom.
+
+To verify the proof, start with the leaf value as `node`, and combine it with respective sibling values:
+`node = keccak256(node ++ sibling)` or `node = keccak256(sibling ++ node)`,
+depending the position of `node` at that level of the tree.
+
+During the onchain execution, each instruction only executes 1 or 2 memory reads, followed by 0 or 1 writes,
+where the write is over the same memory as was last read.
+
+The memory access is specifically:
+- instruction (4 byte) read at `PC`
+- load or syscall mem read, always aligned 4 bytes, read at any `addr`
+- store or syscall mem write, always aligned 4 bytes, at ths same `addr`
+
+Writing only once, at the last read leaf, also means that the leaf can be safely updated and the same proof-data
+that was used to verify the read, can be used to reconstruct the new `memRoot` of the memory tree,
+since all sibling data that is combined with the new leaf value was already authenticated during the read part.
+
+### Pre-image data
+
+Pre-image data is accessed through syscalls exclusively.
+The OP-stack fault-proof [Pre-image Oracle specs](https://github.com/ethereum-optimism/optimism/blob/develop/specs/fault-proof.md#pre-image-oracle)
+define the ABI for communicating pre-images.
+
+This ABI is implemented by the VM by intercepting the `read`/`write` syscalls to specific file descriptors:
+- `hint client read = 3`: used by the client to send hint data to the host. Optional, implemented as blocking.
+- `hint client write = 4`: used by the client to wait for the host. Always instant, since the above is implemented as blocking.
+- `preimage client read = 5`: used by the client to read pre-image data, starting from the latest pre-image reading offset.
+- `preimage client write = 6`: used by the client to change the pre-image key. The key may change a little bit at a time. The last 32 written bytes count as key for retrieval when reading the pre-image. Changing the key also resets the read offset to 0.
+
+The data is loaded into `Oracle.sol` using the respective loading function based on the pre-image type.
+And then retrieved during execution of the `read` syscall.
+
+Note that although the oracle provides up to 32 bytes of the pre-image,
+Cannon only supports reading at most 4 bytes at a time, to unify the memory operations with regular load/stores.
+
+
+## Usage in Dispute Game
+
+The onchain MIPS execution functions as base-case of an interactive dispute game.
+The dispute game narrows down a sequence of disputed instructions to a single disputed instruction.
+This instruction can then be executed onchain to determine objective truth.
+
+The Dispute Game itself is out of scope for Cannon: Cannon is just one example of a fault-proof VM that
+can be used to resolve disputes.

cannon/example/Makefile

+all: elf dump
+
+.PHONY: elf
+elf: $(patsubst %/go.mod,bin/%.elf,$(wildcard */go.mod))
+
+.PHONY: dump
+dump: $(patsubst %/go.mod,bin/%.dump,$(wildcard */go.mod))
+
+bin:
+	mkdir bin
+
+# take any directory with a go mod, and build an ELF
+# verify output with: readelf -h bin/<name>.elf
+# result is mips32, big endian, R3000
+bin/%.elf: bin
+	cd $(@:bin/%.elf=%) && GOOS=linux GOARCH=mips GOMIPS=softfloat go build -o ../$@ .
+
+# take any ELF and dump it
+# TODO: currently have the little-endian toolchain, but should use the big-endian one. The -EB compat flag works though.
+bin/%.dump: bin/%.elf
+	mipsel-linux-gnu-objdump -D --disassembler-options=no-aliases --wide --source -m mips:3000 -EB $(@:%.dump=%.elf) > $@

cannon/example/claim/go.mod

+module claim
+
+go 1.20
+
+require github.com/ethereum-optimism/cannon/preimage v0.0.0
+
+require (
+	golang.org/x/crypto v0.8.0 // indirect
+	golang.org/x/sys v0.7.0 // indirect
+)
+
+replace github.com/ethereum-optimism/cannon/preimage v0.0.0 => ../../preimage

cannon/example/claim/go.sum

+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/stretchr/testify v1.8.2 h1:+h33VjcLVPDHtOdpUCuF+7gSuG3yGIftsP1YvFihtJ8=
+golang.org/x/crypto v0.8.0 h1:pd9TJtTueMTVQXzk8E2XESSMQDj/U7OUu0PqJqPXQjQ=
+golang.org/x/crypto v0.8.0/go.mod h1:mRqEX+O9/h5TFCrQhkgjo2yKi0yYA+9ecGkdQoHrywE=
+golang.org/x/sys v0.7.0 h1:3jlCCIQZPdOYu1h8BkNvLz8Kgwtae2cagcG/VamtZRU=
+golang.org/x/sys v0.7.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

cannon/example/claim/main.go

+package main
+
+import (
+	"encoding/binary"
+	"fmt"
+	"os"
+
+	"github.com/ethereum-optimism/cannon/preimage"
+)
+
+type rawHint string
+
+func (rh rawHint) Hint() string {
+	return string(rh)
+}
+
+func main() {
+	_, _ = os.Stderr.Write([]byte("started!"))
+
+	po := preimage.NewOracleClient(preimage.ClientPreimageChannel())
+	hinter := preimage.NewHintWriter(preimage.ClientHinterChannel())
+
+	preHash := *(*[32]byte)(po.Get(preimage.LocalIndexKey(0)))
+	diffHash := *(*[32]byte)(po.Get(preimage.LocalIndexKey(1)))
+	claimData := *(*[8]byte)(po.Get(preimage.LocalIndexKey(2)))
+
+	// Hints are used to indicate which things the program will access,
+	// so the server can be prepared to serve the corresponding pre-images.
+	hinter.Hint(rawHint(fmt.Sprintf("fetch-state %x", preHash)))
+	pre := po.Get(preimage.Keccak256Key(preHash))
+
+	// Multiple pre-images may be fetched based on a hint.
+	// E.g. when we need all values of a merkle-tree.
+	hinter.Hint(rawHint(fmt.Sprintf("fetch-diff %x", diffHash)))
+	diff := po.Get(preimage.Keccak256Key(diffHash))
+	diffPartA := po.Get(preimage.Keccak256Key(*(*[32]byte)(diff[:32])))
+	diffPartB := po.Get(preimage.Keccak256Key(*(*[32]byte)(diff[32:])))
+
+	// Example state-transition function: s' = s*a + b
+	s := binary.BigEndian.Uint64(pre)
+	a := binary.BigEndian.Uint64(diffPartA)
+	b := binary.BigEndian.Uint64(diffPartB)
+	fmt.Printf("computing %d * %d + %d\n", s, a, b)
+	sOut := s*a + b
+
+	sClaim := binary.BigEndian.Uint64(claimData[:])
+	if sOut != sClaim {
+		fmt.Printf("claim %d is bad! Correct result is %d\n", sOut, sClaim)
+		os.Exit(1)
+	} else {
+		fmt.Printf("claim %d is good!\n", sOut)
+		os.Exit(0)
+	}
+}

cannon/example/hello/go.mod

+module hello
+

cannon/example/hello/main.go

+package main
+
+import "os"
+
+func main() {
+	_, _ = os.Stdout.Write([]byte("hello world!"))
+}

cannon/go.mod

+module github.com/ethereum-optimism/cannon
+
+go 1.20
+
+require (
+	github.com/ethereum-optimism/cannon/preimage v0.0.0
+	github.com/ethereum/go-ethereum v1.11.5
+	github.com/pkg/profile v1.7.0
+	github.com/stretchr/testify v1.8.2
+	github.com/urfave/cli/v2 v2.25.3
+)
+
+require (
+	github.com/DataDog/zstd v1.5.2 // indirect
+	github.com/StackExchange/wmi v0.0.0-20180116203802-5d049714c4a6 // indirect
+	github.com/VictoriaMetrics/fastcache v1.6.0 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/btcsuite/btcd/btcec/v2 v2.2.0 // indirect
+	github.com/cespare/xxhash/v2 v2.2.0 // indirect
+	github.com/cockroachdb/errors v1.9.1 // indirect
+	github.com/cockroachdb/logtags v0.0.0-20230118201751-21c54148d20b // indirect
+	github.com/cockroachdb/pebble v0.0.0-20230209160836-829675f94811 // indirect
+	github.com/cockroachdb/redact v1.1.3 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/deckarep/golang-set/v2 v2.1.0 // indirect
+	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.0.1 // indirect
+	github.com/edsrzf/mmap-go v1.0.0 // indirect
+	github.com/felixge/fgprof v0.9.3 // indirect
+	github.com/getsentry/sentry-go v0.18.0 // indirect
+	github.com/go-ole/go-ole v1.2.1 // indirect
+	github.com/go-stack/stack v1.8.1 // indirect
+	github.com/gofrs/flock v0.8.1 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/protobuf v1.5.2 // indirect
+	github.com/golang/snappy v0.0.4 // indirect
+	github.com/google/pprof v0.0.0-20211214055906-6f57359322fd // indirect
+	github.com/gorilla/websocket v1.4.2 // indirect
+	github.com/holiman/bloomfilter/v2 v2.0.3 // indirect
+	github.com/holiman/uint256 v1.2.0 // indirect
+	github.com/klauspost/compress v1.15.15 // indirect
+	github.com/kr/pretty v0.3.1 // indirect
+	github.com/kr/text v0.2.0 // indirect
+	github.com/mattn/go-runewidth v0.0.9 // indirect
+	github.com/matttproud/golang_protobuf_extensions v1.0.4 // indirect
+	github.com/olekukonko/tablewriter v0.0.5 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/prometheus/client_golang v1.14.0 // indirect
+	github.com/prometheus/client_model v0.3.0 // indirect
+	github.com/prometheus/common v0.39.0 // indirect
+	github.com/prometheus/procfs v0.9.0 // indirect
+	github.com/rogpeppe/go-internal v1.9.0 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
+	github.com/shirou/gopsutil v3.21.4-0.20210419000835-c7a38de76ee5+incompatible // indirect
+	github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7 // indirect
+	github.com/tklauser/go-sysconf v0.3.5 // indirect
+	github.com/tklauser/numcpus v0.2.2 // indirect
+	github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673 // indirect
+	golang.org/x/crypto v0.8.0 // indirect
+	golang.org/x/exp v0.0.0-20230206171751-46f607a40771 // indirect
+	golang.org/x/sys v0.7.0 // indirect
+	golang.org/x/text v0.9.0 // indirect
+	google.golang.org/protobuf v1.28.1 // indirect
+	gopkg.in/natefinch/npipe.v2 v2.0.0-20160621034901-c1b8fa8bdcce // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+replace github.com/ethereum-optimism/cannon/preimage v0.0.0 => ./preimage

cannon/go.sum

+cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
+github.com/AndreasBriese/bbloom v0.0.0-20190306092124-e2d15f34fcf9/go.mod h1:bOvUY6CB00SOBii9/FifXqc0awNKxLFCL/+pkDPuyl8=
+github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
+github.com/CloudyKit/fastprinter v0.0.0-20200109182630-33d98a066a53/go.mod h1:+3IMCy2vIlbG1XG/0ggNQv0SvxCAIpPM5b1nCz56Xno=
+github.com/CloudyKit/jet/v3 v3.0.0/go.mod h1:HKQPgSJmdK8hdoAbKUUWajkHyHo4RaU5rMdUywE7VMo=
+github.com/DataDog/zstd v1.5.2 h1:vUG4lAyuPCXO0TLbXvPv7EB7cNK1QV/luu55UHLrrn8=
+github.com/DataDog/zstd v1.5.2/go.mod h1:g4AWEaM3yOg3HYfnJ3YIawPnVdXJh9QME85blwSAmyw=
+github.com/Joker/hpp v1.0.0/go.mod h1:8x5n+M1Hp5hC0g8okX3sR3vFQwynaX/UgSOM9MeBKzY=
+github.com/Shopify/goreferrer v0.0.0-20181106222321-ec9c9a553398/go.mod h1:a1uqRtAwp2Xwc6WNPJEufxJ7fx3npB4UV/JOLmbu5I0=
+github.com/StackExchange/wmi v0.0.0-20180116203802-5d049714c4a6 h1:fLjPD/aNc3UIOA6tDi6QXUemppXK3P9BI7mr2hd6gx8=
+github.com/StackExchange/wmi v0.0.0-20180116203802-5d049714c4a6/go.mod h1:3eOhrUMpNV+6aFIbp5/iudMxNCF27Vw2OZgy4xEx0Fg=
+github.com/VictoriaMetrics/fastcache v1.6.0 h1:C/3Oi3EiBCqufydp1neRZkqcwmEiuRT9c3fqvvgKm5o=
+github.com/VictoriaMetrics/fastcache v1.6.0/go.mod h1:0qHz5QP0GMX4pfmMA/zt5RgfNuXJrTP0zS7DqpHGGTw=
+github.com/ajg/form v1.5.1/go.mod h1:uL1WgH+h2mgNtvBq0339dVnzXdBETtL2LeUXaIv25UY=
+github.com/allegro/bigcache v1.2.1-0.20190218064605-e24eb225f156 h1:eMwmnE/GDgah4HI848JfFxHt+iPb26b4zyfspmqY0/8=
+github.com/allegro/bigcache v1.2.1-0.20190218064605-e24eb225f156/go.mod h1:Cb/ax3seSYIx7SuZdm2G2xzfwmv3TPSk2ucNfQESPXM=
+github.com/armon/consul-api v0.0.0-20180202201655-eb2c6b5be1b6/go.mod h1:grANhF5doyWs3UAsr3K4I6qtAmlQcZDesFNEHPZAzj8=
+github.com/aymerick/raymond v2.0.3-0.20180322193309-b565731e1464+incompatible/go.mod h1:osfaiScAUVup+UC9Nfq76eWqDhXlp+4UYaA8uhTBO6g=
+github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
+github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/btcsuite/btcd/btcec/v2 v2.2.0 h1:fzn1qaOt32TuLjFlkzYSsBC35Q3KUjT1SwPxiMSCF5k=
+github.com/btcsuite/btcd/btcec/v2 v2.2.0/go.mod h1:U7MHm051Al6XmscBQ0BoNydpOTsFAn707034b5nY8zU=
+github.com/btcsuite/btcd/chaincfg/chainhash v1.0.1 h1:q0rUy8C/TYNBQS1+CGKw68tLOFYSNEs0TFnxxnS9+4U=
+github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
+github.com/cespare/xxhash/v2 v2.1.1/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44=
+github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWRnGsAI=
+github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI=
+github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
+github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
+github.com/cncf/udpa/go v0.0.0-20201120205902-5459f2c99403/go.mod h1:WmhPx2Nbnhtbo57+VJT5O0JRkEi1Wbu0z5j0R8u5Hbk=
+github.com/cockroachdb/datadriven v1.0.2 h1:H9MtNqVoVhvd9nCBwOyDjUEdZCREqbIdCJD93PBm/jA=
+github.com/cockroachdb/datadriven v1.0.2/go.mod h1:a9RdTaap04u637JoCzcUoIcDmvwSUtcUFtT/C3kJlTU=
+github.com/cockroachdb/errors v1.9.1 h1:yFVvsI0VxmRShfawbt/laCIDy/mtTqqnvoNgiy5bEV8=
+github.com/cockroachdb/errors v1.9.1/go.mod h1:2sxOtL2WIc096WSZqZ5h8fa17rdDq9HZOZLBCor4mBk=
+github.com/cockroachdb/logtags v0.0.0-20211118104740-dabe8e521a4f/go.mod h1:Vz9DsVWQQhf3vs21MhPMZpMGSht7O/2vFW2xusFUVOs=
+github.com/cockroachdb/logtags v0.0.0-20230118201751-21c54148d20b h1:r6VH0faHjZeQy818SGhaone5OnYfxFR/+AzdY3sf5aE=
+github.com/cockroachdb/logtags v0.0.0-20230118201751-21c54148d20b/go.mod h1:Vz9DsVWQQhf3vs21MhPMZpMGSht7O/2vFW2xusFUVOs=
+github.com/cockroachdb/pebble v0.0.0-20230209160836-829675f94811 h1:ytcWPaNPhNoGMWEhDvS3zToKcDpRsLuRolQJBVGdozk=
+github.com/cockroachdb/pebble v0.0.0-20230209160836-829675f94811/go.mod h1:Nb5lgvnQ2+oGlE/EyZy4+2/CxRh9KfvCXnag1vtpxVM=
+github.com/cockroachdb/redact v1.1.3 h1:AKZds10rFSIj7qADf0g46UixK8NNLwWTNdCIGS5wfSQ=
+github.com/cockroachdb/redact v1.1.3/go.mod h1:BVNblN9mBWFyMyqK1k3AAiSxhvhfK2oOZZ2lK+dpvRg=
+github.com/codegangsta/inject v0.0.0-20150114235600-33e0aa1cb7c0/go.mod h1:4Zcjuz89kmFXt9morQgcfYZAYZ5n8WHjt81YYWIwtTM=
+github.com/coreos/etcd v3.3.10+incompatible/go.mod h1:uF7uidLiAD3TWHmW31ZFd/JWoc32PjwdhPthX9715RE=
+github.com/coreos/go-etcd v2.0.0+incompatible/go.mod h1:Jez6KQU2B/sWsbdaef3ED8NzMklzPG4d5KIOhIy30Tk=
+github.com/coreos/go-semver v0.2.0/go.mod h1:nnelYz7RCh+5ahJtPPxZlU+153eP4D4r3EedlOD2RNk=
+github.com/cpuguy83/go-md2man v1.0.10/go.mod h1:SmD6nW6nTyfqj6ABTjUi3V3JVMnlJmwcJI5acqYI6dE=
+github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
+github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/deckarep/golang-set/v2 v2.1.0 h1:g47V4Or+DUdzbs8FxCCmgb6VYd+ptPAngjM6dtGktsI=
+github.com/deckarep/golang-set/v2 v2.1.0/go.mod h1:VAky9rY/yGXJOLEDv3OMci+7wtDpOF4IN+y82NBOac4=
+github.com/decred/dcrd/crypto/blake256 v1.0.0 h1:/8DMNYp9SGi5f0w7uCm6d6M4OU2rGFK09Y2A4Xv7EE0=
+github.com/decred/dcrd/crypto/blake256 v1.0.0/go.mod h1:sQl2p6Y26YV+ZOcSTP6thNdn47hh8kt6rqSlvmrXFAc=
+github.com/decred/dcrd/dcrec/secp256k1/v4 v4.0.1 h1:YLtO71vCjJRCBcrPMtQ9nqBsqpA1m5sE92cU+pd5Mcc=
+github.com/decred/dcrd/dcrec/secp256k1/v4 v4.0.1/go.mod h1:hyedUtir6IdtD/7lIxGeCxkaw7y45JueMRL4DIyJDKs=
+github.com/dgraph-io/badger v1.6.0/go.mod h1:zwt7syl517jmP8s94KqSxTlM6IMsdhYy6psNgSztDR4=
+github.com/dgryski/go-farm v0.0.0-20190423205320-6a90982ecee2/go.mod h1:SqUrOPUnsFjfmXRMNPybcSiG0BgUW2AuFH8PAnS2iTw=
+github.com/dustin/go-humanize v1.0.0/go.mod h1:HtrtbFcZ19U5GC7JDqmcUSB87Iq5E25KnS6fMYU6eOk=
+github.com/edsrzf/mmap-go v1.0.0 h1:CEBF7HpRnUCSJgGUb5h1Gm7e3VkmVDrR8lvWVLtrOFw=
+github.com/edsrzf/mmap-go v1.0.0/go.mod h1:YO35OhQPt3KJa3ryjFM5Bs14WD66h8eGKpfaBNrHW5M=
+github.com/eknkc/amber v0.0.0-20171010120322-cdade1c07385/go.mod h1:0vRUJqYpeSZifjYj7uP3BG/gKcuzL9xWVV/Y+cK33KM=
+github.com/envoyproxy/go-control-plane v0.9.0/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
+github.com/envoyproxy/go-control-plane v0.9.1-0.20191026205805-5f8ba28d4473/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
+github.com/envoyproxy/go-control-plane v0.9.9-0.20210217033140-668b12f5399d/go.mod h1:cXg6YxExXjJnVBQHBLXeUAgxn2UodCpnH306RInaBQk=
+github.com/envoyproxy/protoc-gen-validate v0.1.0/go.mod h1:iSmxcyjqTsJpI2R4NaDN7+kN2VEUnK/pcBlmesArF7c=
+github.com/etcd-io/bbolt v1.3.3/go.mod h1:ZF2nL25h33cCyBtcyWeZ2/I3HQOfTP+0PIEvHjkjCrw=
+github.com/ethereum/go-ethereum v1.11.5 h1:3M1uan+LAUvdn+7wCEFrcMM4LJTeuxDrPTg/f31a5QQ=
+github.com/ethereum/go-ethereum v1.11.5/go.mod h1:it7x0DWnTDMfVFdXcU6Ti4KEFQynLHVRarcSlPr0HBo=
+github.com/fasthttp-contrib/websocket v0.0.0-20160511215533-1f3b11f56072/go.mod h1:duJ4Jxv5lDcvg4QuQr0oowTf7dz4/CR8NtyCooz9HL8=
+github.com/fatih/structs v1.1.0/go.mod h1:9NiDSp5zOcgEDl+j00MP/WkGVPOlPRLejGD8Ga6PJ7M=
+github.com/felixge/fgprof v0.9.3 h1:VvyZxILNuCiUCSXtPtYmmtGvb65nqXh2QFWc0Wpf2/g=
+github.com/felixge/fgprof v0.9.3/go.mod h1:RdbpDgzqYVh/T9fPELJyV7EYJuHB55UTEULNun8eiPw=
+github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
+github.com/fsnotify/fsnotify v1.4.9/go.mod h1:znqG4EE+3YCdAaPaxE2ZRY/06pZUdp0tY4IgpuI1SZQ=
+github.com/fsnotify/fsnotify v1.6.0 h1:n+5WquG0fcWoWp6xPWfHdbskMCQaFnG6PfBrh1Ky4HY=
+github.com/gavv/httpexpect v2.0.0+incompatible/go.mod h1:x+9tiU1YnrOvnB725RkpoLv1M62hOWzwo5OXotisrKc=
+github.com/getsentry/sentry-go v0.12.0/go.mod h1:NSap0JBYWzHND8oMbyi0+XZhUalc1TBdRL1M71JZW2c=
+github.com/getsentry/sentry-go v0.18.0 h1:MtBW5H9QgdcJabtZcuJG80BMOwaBpkRDZkxRkNC1sN0=
+github.com/getsentry/sentry-go v0.18.0/go.mod h1:Kgon4Mby+FJ7ZWHFUAZgVaIa8sxHtnRJRLTXZr51aKQ=
+github.com/gin-contrib/sse v0.0.0-20190301062529-5545eab6dad3/go.mod h1:VJ0WA2NBN22VlZ2dKZQPAPnyWw5XTlK1KymzLKsr59s=
+github.com/gin-gonic/gin v1.4.0/go.mod h1:OW2EZn3DO8Ln9oIKOvM++LBO+5UPHJJDH72/q/3rZdM=
+github.com/go-check/check v0.0.0-20180628173108-788fd7840127/go.mod h1:9ES+weclKsC9YodN5RgxqK/VD9HM9JsCSh7rNhMZE98=
+github.com/go-errors/errors v1.0.1/go.mod h1:f4zRHt4oKfwPJE5k8C9vpYG+aDHdBFUsgrm6/TyX73Q=
+github.com/go-errors/errors v1.4.2 h1:J6MZopCL4uSllY1OfXM374weqZFFItUbrImctkmUxIA=
+github.com/go-martini/martini v0.0.0-20170121215854-22fa46961aab/go.mod h1:/P9AEU963A2AYjv4d1V5eVL1CQbEJq6aCNHDDjibzu8=
+github.com/go-ole/go-ole v1.2.1 h1:2lOsA72HgjxAuMlKpFiCbHTvu44PIVkZ5hqm3RSdI/E=
+github.com/go-ole/go-ole v1.2.1/go.mod h1:7FAglXiTm7HKlQRDeOQ6ZNUHidzCWXuZWq/1dTyBNF8=
+github.com/go-stack/stack v1.8.1 h1:ntEHSVwIt7PNXNpgPmVfMrNhLtgjlmnZha2kOpuRiDw=
+github.com/go-stack/stack v1.8.1/go.mod h1:dcoOX6HbPZSZptuspn9bctJ+N/CnF5gGygcUP3XYfe4=
+github.com/gobwas/httphead v0.0.0-20180130184737-2c6c146eadee/go.mod h1:L0fX3K22YWvt/FAX9NnzrNzcI4wNYi9Yku4O0LKYflo=
+github.com/gobwas/pool v0.2.0/go.mod h1:q8bcK0KcYlCgd9e7WYLm9LpyS+YeLd8JVDW6WezmKEw=
+github.com/gobwas/ws v1.0.2/go.mod h1:szmBTxLgaFppYjEmNtny/v3w89xOydFnnZMcgRRu/EM=
+github.com/gofrs/flock v0.8.1 h1:+gYjHKf32LDeiEEFhQaotPbLuUXjY5ZqxKgXy7n59aw=
+github.com/gofrs/flock v0.8.1/go.mod h1:F1TvTiK9OcQqauNUHlbJvyl9Qa1QvF/gOUDKA14jxHU=
+github.com/gogo/googleapis v0.0.0-20180223154316-0cd9801be74a/go.mod h1:gf4bu3Q80BeJ6H1S1vYPm8/ELATdvryBaNFGgqEef3s=
+github.com/gogo/googleapis v1.4.1/go.mod h1:2lpHqI5OcWCtVElxXnPt+s8oJvMpySlOyM6xDCrzib4=
+github.com/gogo/protobuf v1.2.0/go.mod h1:r8qH/GZQm5c6nD/R0oafs1akxWv10x8SbQlK7atdtwQ=
+github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
+github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
+github.com/gogo/status v1.1.0/go.mod h1:BFv9nrluPLmrS0EmGVvLaPNmRosr9KapBYd5/hpY1WM=
+github.com/golang-jwt/jwt v3.2.2+incompatible/go.mod h1:8pz2t5EyA70fFQQSrl6XZXzqecmYZeUEB8OUGHkxJ+I=
+github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q=
+github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A=
+github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.5/go.mod h1:6O5/vntMXwX2lRkT1hjjk0nAC1IDOTvTlVgjlRvqsdk=
+github.com/golang/protobuf v1.4.0-rc.1/go.mod h1:ceaxUfeHdC40wWswd/P6IGgMaK3YpKi5j83Wpe3EHw8=
+github.com/golang/protobuf v1.4.0-rc.1.0.20200221234624-67d41d38c208/go.mod h1:xKAWHe0F5eneWXFV3EuXVDTCmh+JuBKY0li0aMyXATA=
+github.com/golang/protobuf v1.4.0-rc.2/go.mod h1:LlEzMj4AhA7rCAGe4KMBDvJI+AwstrUpVNzEA03Pprs=
+github.com/golang/protobuf v1.4.0-rc.4.0.20200313231945-b860323f09d0/go.mod h1:WU3c8KckQ9AFe+yFwt9sWVRKCVIyN9cPHBJSNnbL67w=
+github.com/golang/protobuf v1.4.0/go.mod h1:jodUvKwWbYaEsadDk5Fwe5c77LiNKVO9IDvqG2KuDX0=
+github.com/golang/protobuf v1.4.1/go.mod h1:U8fpvMrcmy5pZrNK1lt4xCsGvpyWQ/VVv6QDs8UjoX8=
+github.com/golang/protobuf v1.4.2/go.mod h1:oDoupMAO8OvCJWAcko0GGGIgR6R6ocIYbsSw735rRwI=
+github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
+github.com/golang/protobuf v1.5.2 h1:ROPKBNFfQgOUMifHyP+KYbvpjbdoFNs+aK7DXlji0Tw=
+github.com/golang/protobuf v1.5.2/go.mod h1:XVQd3VNwM+JqD3oG2Ue2ip4fOMUkwXdXDdiuN0vRsmY=
+github.com/golang/snappy v0.0.3/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q=
+github.com/golang/snappy v0.0.4 h1:yAGX7huGHXlcLOEtBnF4w7FQwA26wojNCwOYAEhLjQM=
+github.com/golang/snappy v0.0.4/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q=
+github.com/gomodule/redigo v1.7.1-0.20190724094224-574c33c3df38/go.mod h1:B4C85qUVwatsJoIUNIfCRsp7qO0iAmpGFZ4EELWSbC4=
+github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M=
+github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
+github.com/google/go-cmp v0.3.1/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
+github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
+github.com/google/go-querystring v1.0.0/go.mod h1:odCYkC5MyYFN7vkCjXpyrEuKhc/BUO6wN/zVPAxq5ck=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/pprof v0.0.0-20211214055906-6f57359322fd h1:1FjCyPC+syAzJ5/2S8fqdZK1R22vvA0J7JZKcuOIQ7Y=
+github.com/google/pprof v0.0.0-20211214055906-6f57359322fd/go.mod h1:KgnwoLYCZ8IQu3XUZ8Nc/bM9CCZFOyjUNOSygVozoDg=
+github.com/google/uuid v1.1.2/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gopherjs/gopherjs v0.0.0-20181017120253-0766667cb4d1/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
+github.com/gorilla/websocket v1.4.1/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/gorilla/websocket v1.4.2 h1:+/TMaTYc4QFitKJxsQ7Yye35DkWvkdLcvGKqM+x0Ufc=
+github.com/gorilla/websocket v1.4.2/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/hashicorp/go-version v1.2.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
+github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
+github.com/holiman/bloomfilter/v2 v2.0.3 h1:73e0e/V0tCydx14a0SCYS/EWCxgwLZ18CZcZKVu0fao=
+github.com/holiman/bloomfilter/v2 v2.0.3/go.mod h1:zpoh+gs7qcpqrHr3dB55AMiJwo0iURXE7ZOP9L9hSkA=
+github.com/holiman/uint256 v1.2.0 h1:gpSYcPLWGv4sG43I2mVLiDZCNDh/EpGjSk8tmtxitHM=
+github.com/holiman/uint256 v1.2.0/go.mod h1:y4ga/t+u+Xwd7CpDgZESaRcWy0I7XMlTMA25ApIH5Jw=
+github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
+github.com/hydrogen18/memlistener v0.0.0-20200120041712-dcc25e7acd91/go.mod h1:qEIFzExnS6016fRpRfxrExeVn2gbClQA99gQhnIcdhE=
+github.com/ianlancetaylor/demangle v0.0.0-20210905161508-09a460cdf81d/go.mod h1:aYm2/VgdVmcIU8iMfdMvDMsRAQjcfZSKFby6HOFvi/w=
+github.com/imkira/go-interpol v1.1.0/go.mod h1:z0h2/2T3XF8kyEPpRgJ3kmNv+C43p+I/CoI+jC3w2iA=
+github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8=
+github.com/iris-contrib/blackfriday v2.0.0+incompatible/go.mod h1:UzZ2bDEoaSGPbkg6SAB4att1aAwTmVIx/5gCVqeyUdI=
+github.com/iris-contrib/go.uuid v2.0.0+incompatible/go.mod h1:iz2lgM/1UnEf1kP0L/+fafWORmlnuysV2EMP8MW+qe0=
+github.com/iris-contrib/jade v1.1.3/go.mod h1:H/geBymxJhShH5kecoiOCSssPX7QWYH7UaeZTSWddIk=
+github.com/iris-contrib/pongo2 v0.0.1/go.mod h1:Ssh+00+3GAZqSQb30AvBRNxBx7rf0GqwkjqxNd0u65g=
+github.com/iris-contrib/schema v0.0.1/go.mod h1:urYA3uvUNG1TIIjOSCzHr9/LmbQo8LrOcOqfqxa4hXw=
+github.com/json-iterator/go v1.1.6/go.mod h1:+SdeFBvtyEkXs7REEP0seUULqWtbJapLOCVDaaPEHmU=
+github.com/json-iterator/go v1.1.9/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/uOdHXbAo4=
+github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU=
+github.com/k0kubun/colorstring v0.0.0-20150214042306-9440f1994b88/go.mod h1:3w7q1U84EfirKl04SVQ/s7nPm1ZPhiXd34z40TNz36k=
+github.com/kataras/golog v0.0.10/go.mod h1:yJ8YKCmyL+nWjERB90Qwn+bdyBZsaQwU3bTVFgkFIp8=
+github.com/kataras/iris/v12 v12.1.8/go.mod h1:LMYy4VlP67TQ3Zgriz8RE2h2kMZV2SgMYbq3UhfoFmE=
+github.com/kataras/neffos v0.0.14/go.mod h1:8lqADm8PnbeFfL7CLXh1WHw53dG27MC3pgi2R1rmoTE=
+github.com/kataras/pio v0.0.2/go.mod h1:hAoW0t9UmXi4R5Oyq5Z4irTbaTsOemSrDGUtaTl7Dro=
+github.com/kataras/sitemap v0.0.5/go.mod h1:KY2eugMKiPwsJgx7+U103YZehfvNGOXURubcGyk0Bz8=
+github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
+github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
+github.com/klauspost/compress v1.8.2/go.mod h1:RyIbtBH6LamlWaDj8nUwkbUhJ87Yi3uG0guNDohfE1A=
+github.com/klauspost/compress v1.9.7/go.mod h1:RyIbtBH6LamlWaDj8nUwkbUhJ87Yi3uG0guNDohfE1A=
+github.com/klauspost/compress v1.15.15 h1:EF27CXIuDsYJ6mmvtBRlEuB2UVOqHG1tAXgZ7yIO+lw=
+github.com/klauspost/compress v1.15.15/go.mod h1:ZcK2JAFqKOpnBlxcLsJzYfrS9X1akm9fHZNnD9+Vo/4=
+github.com/klauspost/cpuid v1.2.1/go.mod h1:Pj4uuM528wm8OyEC2QMXAi2YiTZ96dNQPGgoMS4s3ek=
+github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/labstack/echo/v4 v4.5.0/go.mod h1:czIriw4a0C1dFun+ObrXp7ok03xON0N1awStJ6ArI7Y=
+github.com/labstack/gommon v0.3.0/go.mod h1:MULnywXg0yavhxWKc+lOruYdAhDwPK9wf0OL7NoOu+k=
+github.com/magiconair/properties v1.8.0/go.mod h1:PppfXfuXeibc/6YijjN8zIbojt8czPbwD3XqdrwzmxQ=
+github.com/mattn/go-colorable v0.1.2/go.mod h1:U0ppj6V5qS13XJ6of8GYAs25YV2eR4EVcfRqFIhoBtE=
+github.com/mattn/go-colorable v0.1.8/go.mod h1:u6P/XSegPjTcexA+o6vUJrdnUu04hMope9wVRipJSqc=
+github.com/mattn/go-colorable v0.1.11/go.mod h1:u5H1YNBxpqRaxsYJYSkiCWKzEfiAb1Gb520KVy5xxl4=
+github.com/mattn/go-isatty v0.0.7/go.mod h1:Iq45c/XA43vh69/j3iqttzPXn0bhXyGjM0Hdxcsrc5s=
+github.com/mattn/go-isatty v0.0.8/go.mod h1:Iq45c/XA43vh69/j3iqttzPXn0bhXyGjM0Hdxcsrc5s=
+github.com/mattn/go-isatty v0.0.9/go.mod h1:YNRxwqDuOph6SZLI9vUUz6OYw3QyUt7WiY2yME+cCiQ=
+github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU=
+github.com/mattn/go-isatty v0.0.14/go.mod h1:7GGIvUiUoEMVVmxf/4nioHXj79iQHKdU27kJ6hsGG94=
+github.com/mattn/go-runewidth v0.0.9 h1:Lm995f3rfxdpd6TSmuVCHVb/QhupuXlYr8sCI/QdE+0=
+github.com/mattn/go-runewidth v0.0.9/go.mod h1:H031xJmbD/WCDINGzjvQ9THkh0rPKHF+m2gUSrubnMI=
+github.com/mattn/goveralls v0.0.2/go.mod h1:8d1ZMHsd7fW6IRPKQh46F2WRpyib5/X4FOpevwGNQEw=
+github.com/matttproud/golang_protobuf_extensions v1.0.4 h1:mmDVorXM7PCGKw94cs5zkfA9PSy5pEvNWRP0ET0TIVo=
+github.com/matttproud/golang_protobuf_extensions v1.0.4/go.mod h1:BSXmuO+STAnVfrANrmjBb36TMTDstsz7MSK+HVaYKv4=
+github.com/mediocregopher/radix/v3 v3.4.2/go.mod h1:8FL3F6UQRXHXIBSPUs5h0RybMF8i4n7wVopoX3x7Bv8=
+github.com/microcosm-cc/bluemonday v1.0.2/go.mod h1:iVP4YcDBq+n/5fb23BhYFvIMq/leAFZyRl6bYmGDlGc=
+github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
+github.com/mitchellh/mapstructure v1.1.2/go.mod h1:FVVH3fgwuzCH5S8UJGiWEs2h04kUh9fWfEaFds41c1Y=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v0.0.0-20180701023420-4b7aa43c6742/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
+github.com/modern-go/reflect2 v1.0.1/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
+github.com/moul/http2curl v1.0.0/go.mod h1:8UbvGypXm98wA/IqH45anm5Y2Z6ep6O31QGOAZ3H0fQ=
+github.com/nats-io/jwt v0.3.0/go.mod h1:fRYCDE99xlTsqUzISS1Bi75UBJ6ljOJQOAAu5VglpSg=
+github.com/nats-io/nats.go v1.9.1/go.mod h1:ZjDU1L/7fJ09jvUSRVBR2e7+RnLiiIQyqyzEE/Zbp4w=
+github.com/nats-io/nkeys v0.1.0/go.mod h1:xpnFELMwJABBLVhffcfd1MZx6VsNRFpEugbxziKVo7w=
+github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OSON2c=
+github.com/nxadm/tail v1.4.4 h1:DQuhQpB1tVlglWS2hLQ5OV6B5r8aGxSrPc5Qo6uTN78=
+github.com/nxadm/tail v1.4.4/go.mod h1:kenIhsEOeOJmVchQTgglprH7qJGnHDVpk1VPCcaMI8A=
+github.com/olekukonko/tablewriter v0.0.5 h1:P2Ga83D34wi1o9J6Wh1mRuqd4mF/x/lgBS7N7AbDhec=
+github.com/olekukonko/tablewriter v0.0.5/go.mod h1:hPp6KlRPjbx+hW8ykQs1w3UBbZlj6HuIJcUGPhkA7kY=
+github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
+github.com/onsi/ginkgo v1.10.3/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
+github.com/onsi/ginkgo v1.12.1/go.mod h1:zj2OWP4+oCPe1qIXoGWkgMRwljMUYCdkwsT2108oapk=
+github.com/onsi/ginkgo v1.14.0 h1:2mOpI4JVVPBN+WQRa0WKH2eXR+Ey+uK4n7Zj0aYpIQA=
+github.com/onsi/ginkgo v1.14.0/go.mod h1:iSB4RoI2tjJc9BBv4NKIKWKya62Rps+oPG/Lv9klQyY=
+github.com/onsi/gomega v1.7.1/go.mod h1:XdKZgCCFLUoM/7CFJVPcG8C1xQ1AJ0vpAezJrB7JYyY=
+github.com/onsi/gomega v1.10.1 h1:o0+MgICZLuZ7xjH7Vx6zS/zcu93/BEp1VwkIW1mEXCE=
+github.com/onsi/gomega v1.10.1/go.mod h1:iN09h71vgCQne3DLsj+A5owkum+a2tYe+TOCB1ybHNo=
+github.com/pelletier/go-toml v1.2.0/go.mod h1:5z9KED0ma1S8pY6P1sdut58dfprrGBbd/94hg7ilaic=
+github.com/pingcap/errors v0.11.4 h1:lFuQV/oaUMGcD2tqt+01ROSmJs75VG1ToEOkZIZ4nE4=
+github.com/pingcap/errors v0.11.4/go.mod h1:Oi8TUi2kEtXXLMJk9l1cGmz20kV3TaQ0usTwv5KuLY8=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
+github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/profile v1.7.0 h1:hnbDkaNWPCLMO9wGLdBFTIZvzDrDfBM2072E1S9gJkA=
+github.com/pkg/profile v1.7.0/go.mod h1:8Uer0jas47ZQMJ7VD+OHknK4YDY07LPUC6dEvqDjvNo=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/prometheus/client_golang v1.14.0 h1:nJdhIvne2eSX/XRAFV9PcvFFRbrjbcTUj0VP62TMhnw=
+github.com/prometheus/client_golang v1.14.0/go.mod h1:8vpkKitgIVNcqrRBWh1C4TIUQgYNtG/XQE4E/Zae36Y=
+github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
+github.com/prometheus/client_model v0.3.0 h1:UBgGFHqYdG/TPFD1B1ogZywDqEkwp3fBMvqdiQ7Xew4=
+github.com/prometheus/client_model v0.3.0/go.mod h1:LDGWKZIo7rky3hgvBe+caln+Dr3dPggB5dvjtD7w9+w=
+github.com/prometheus/common v0.39.0 h1:oOyhkDq05hPZKItWVBkJ6g6AtGxi+fy7F4JvUV8uhsI=
+github.com/prometheus/common v0.39.0/go.mod h1:6XBZ7lYdLCbkAVhwRsWTZn+IN5AB9F/NXd5w0BbEX0Y=
+github.com/prometheus/procfs v0.9.0 h1:wzCHvIvM5SxWqYvwgVL7yJY8Lz3PKn49KQtpgMYJfhI=
+github.com/prometheus/procfs v0.9.0/go.mod h1:+pB4zwohETzFnmlpe6yd2lSc+0/46IYZRB/chUwxUZY=
+github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTEfhy4qGm1nDQc=
+github.com/rogpeppe/go-internal v1.8.1/go.mod h1:JeRgkft04UBgHMgCIwADu4Pn6Mtm5d4nPKWu0nJ5d+o=
+github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/russross/blackfriday v1.5.2/go.mod h1:JO/DiYxRf+HjHt06OyowR9PTA263kcR/rfWxYHBV53g=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/ryanuber/columnize v2.1.0+incompatible/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=
+github.com/schollz/closestmatch v2.1.0+incompatible/go.mod h1:RtP1ddjLong6gTkbtmuhtR2uUrrJOpYzYRvbcPAid+g=
+github.com/sergi/go-diff v1.0.0/go.mod h1:0CfEIISq7TuYL3j771MWULgwwjU+GofnZX9QAmXWZgo=
+github.com/shirou/gopsutil v3.21.4-0.20210419000835-c7a38de76ee5+incompatible h1:Bn1aCHHRnjv4Bl16T8rcaFjYSrGrIZvpiGO6P3Q4GpU=
+github.com/shirou/gopsutil v3.21.4-0.20210419000835-c7a38de76ee5+incompatible/go.mod h1:5b4v6he4MtMOwMlS0TUMTu2PcXUg8+E1lC7eC3UO/RA=
+github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc=
+github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
+github.com/smartystreets/goconvey v1.6.4/go.mod h1:syvi0/a8iFYH4r/RixwvyeAJjdLS9QV7WQ/tjFTllLA=
+github.com/spf13/afero v1.1.2/go.mod h1:j4pytiNVoe2o6bmDsKpLACNPDBIoEAkihy7loJ1B0CQ=
+github.com/spf13/cast v1.3.0/go.mod h1:Qx5cxh0v+4UWYiBimWS+eyWzqEqokIECu5etghLkUJE=
+github.com/spf13/cobra v0.0.5/go.mod h1:3K3wKZymM7VvHMDS9+Akkh4K60UwM26emMESw8tLCHU=
+github.com/spf13/jwalterweatherman v1.0.0/go.mod h1:cQK4TGJAtQXfYWX+Ddv3mKDzgVb68N+wFjFa4jdeBTo=
+github.com/spf13/pflag v1.0.3/go.mod h1:DYY7MBk1bdzusC3SYhjObp+wFpr4gzcvqqNjLnInEg4=
+github.com/spf13/viper v1.3.2/go.mod h1:ZiWeW+zYFKm7srdB9IoDzzZXaJaI5eL9QjNiN/DMA2s=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
+github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.2 h1:+h33VjcLVPDHtOdpUCuF+7gSuG3yGIftsP1YvFihtJ8=
+github.com/stretchr/testify v1.8.2/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7 h1:epCh84lMvA70Z7CTTCmYQn2CKbY8j86K7/FAIr141uY=
+github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7/go.mod h1:q4W45IWZaF22tdD+VEXcAWRA037jwmWEB5VWYORlTpc=
+github.com/tklauser/go-sysconf v0.3.5 h1:uu3Xl4nkLzQfXNsWn15rPc/HQCJKObbt1dKJeWp3vU4=
+github.com/tklauser/go-sysconf v0.3.5/go.mod h1:MkWzOF4RMCshBAMXuhXJs64Rte09mITnppBXY/rYEFI=
+github.com/tklauser/numcpus v0.2.2 h1:oyhllyrScuYI6g+h/zUvNXNp1wy7x8qQy3t/piefldA=
+github.com/tklauser/numcpus v0.2.2/go.mod h1:x3qojaO3uyYt0i56EW/VUYs7uBvdl2fkfZFu0T9wgjM=
+github.com/ugorji/go v1.1.4/go.mod h1:uQMGLiO92mf5W77hV/PUCpI3pbzQx3CRekS0kk+RGrc=
+github.com/ugorji/go v1.1.7/go.mod h1:kZn38zHttfInRq0xu/PH0az30d+z6vm202qpg1oXVMw=
+github.com/ugorji/go/codec v0.0.0-20181204163529-d75b2dcb6bc8/go.mod h1:VFNgLljTbGfSG7qAOspJ7OScBnGdDN/yBr0sguwnwf0=
+github.com/ugorji/go/codec v1.1.7/go.mod h1:Ax+UKWsSmolVDwsd+7N3ZtXu+yMGCf907BLYF3GoBXY=
+github.com/urfave/cli/v2 v2.25.3 h1:VJkt6wvEBOoSjPFQvOkv6iWIrsJyCrKGtCtxXWwmGeY=
+github.com/urfave/cli/v2 v2.25.3/go.mod h1:GHupkWPMM0M/sj1a2b4wUrWBPzazNrIjouW6fmdJLxc=
+github.com/urfave/negroni v1.0.0/go.mod h1:Meg73S6kFm/4PpbYdq35yYWoCZ9mS/YSx+lKnmiohz4=
+github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
+github.com/valyala/fasthttp v1.6.0/go.mod h1:FstJa9V+Pj9vQ7OJie2qMHdwemEDaDiSdBnvPM1Su9w=
+github.com/valyala/fasttemplate v1.0.1/go.mod h1:UQGH1tvbgY+Nz5t2n7tXsz52dQxojPUpymEIMZ47gx8=
+github.com/valyala/fasttemplate v1.2.1/go.mod h1:KHLXt3tVN2HBp8eijSv/kGJopbvo7S+qRAEEKiv+SiQ=
+github.com/valyala/tcplisten v0.0.0-20161114210144-ceec8f93295a/go.mod h1:v3UYOV9WzVtRmSR+PDvWpU/qWl4Wa5LApYYX4ZtKbio=
+github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f/go.mod h1:N2zxlSyiKSe5eX1tZViRH5QA0qijqEDrYZiPEAiq3wU=
+github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415/go.mod h1:GwrjFmJcFw6At/Gs6z4yjiIwzuJ1/+UwLxMQDVQXShQ=
+github.com/xeipuuv/gojsonschema v1.2.0/go.mod h1:anYRn/JVcOK2ZgGU+IjEV4nwlhoK5sQluxsYJ78Id3Y=
+github.com/xordataexchange/crypt v0.0.3-0.20170626215501-b2862e3d0a77/go.mod h1:aYKd//L2LvnjZzWKhF00oedf4jCCReLcmhLdhm1A27Q=
+github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673 h1:bAn7/zixMGCfxrRTfdpNzjtPYqr8smhKouy9mxVdGPU=
+github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673/go.mod h1:N3UwUGtsrSj3ccvlPHLoLsHnpR27oXr4ZE984MbSER8=
+github.com/yalp/jsonpath v0.0.0-20180802001716-5cc68e5049a0/go.mod h1:/LWChgwKmvncFJFHJ7Gvn9wZArjbV5/FppcK2fKk/tI=
+github.com/yudai/gojsondiff v1.0.0/go.mod h1:AY32+k2cwILAkW1fbgxQ5mUmMiZFgLIV+FBNExI05xg=
+github.com/yudai/golcs v0.0.0-20170316035057-ecda9a501e82/go.mod h1:lgjkn3NuSvDfVJdfcVVdX+jpBxNmX4rDAzaS45IcYoM=
+github.com/yudai/pp v2.0.1+incompatible/go.mod h1:PuxR/8QJ7cyCkFp/aUDS+JY727OFEZkTdatxwunjIkc=
+github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+github.com/yuin/goldmark v1.3.5/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
+golang.org/x/crypto v0.0.0-20181203042331-505ab145d0a9/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20190701094942-4def268fd1a4/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
+golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
+golang.org/x/crypto v0.0.0-20191227163750-53104e6ec876/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/crypto v0.0.0-20210322153248-0c34fe9e7dc2/go.mod h1:T9bdIzuCu7OtxOm1hfPfRQxPLYneinmdGuTeoZ9dtd4=
+golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
+golang.org/x/crypto v0.8.0 h1:pd9TJtTueMTVQXzk8E2XESSMQDj/U7OUu0PqJqPXQjQ=
+golang.org/x/crypto v0.8.0/go.mod h1:mRqEX+O9/h5TFCrQhkgjo2yKi0yYA+9ecGkdQoHrywE=
+golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
+golang.org/x/exp v0.0.0-20230206171751-46f607a40771 h1:xP7rWLUr1e1n2xkK5YB4LI0hPEy3LJC6Wk+D4pGlOJg=
+golang.org/x/exp v0.0.0-20230206171751-46f607a40771/go.mod h1:CxIveKay+FTh1D0yPZemJVgC/95VzuuOLq5Qi4xnoYc=
+golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
+golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvxsM5YxQ5yQlVC4a0KAMCusXpPoU=
+golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
+golang.org/x/lint v0.0.0-20210508222113-6edffad5e616/go.mod h1:3xt1FjdF8hUf6vQPIChWIBhFzV8gjjsPE/fR3IyQdNY=
+golang.org/x/mod v0.1.1-0.20191105210325-c90efee705ee/go.mod h1:QqPTAvyqsEbceGzBzNggFXnrqF1CaUcvgkdR5Ot7KZg=
+golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/mod v0.4.2/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20181220203305-927f97764cc3/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20190213061140-3a22650c66bd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190327091125-710a502c58a2/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190503192946-f4e77d36d62c/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20190827160401-ba9fcec4b297/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20191209160850-c0dbc17a3553/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20200520004742-59133d7f0dd7/go.mod h1:qpuaurCH72eLCgpAm/N6yyVIVM9cpaDIP3A8BGJEC5A=
+golang.org/x/net v0.0.0-20200813134508-3edf25e44fcc/go.mod h1:/O7V0waA8r7cgGh81Ro3o1hOxt32SMVPicZroKQ2sZA=
+golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4/go.mod h1:p54w0d4576C0XHj96bSt6lcn1PtDYWL6XObtHCRCNQM=
+golang.org/x/net v0.0.0-20211008194852-3b03d305991f/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
+golang.org/x/net v0.9.0 h1:aWJ/m6xSmxWBx+V0XRHTlrYrPG56jKsLdTFmsSsCzOM=
+golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
+golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20181221193216-37e7f081c4d4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190227155943-e225da77a7e6/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.1.0 h1:wsuoTGHzEhffawBOhz5CYhcrV4IdKZbEyZjBMuTp12o=
+golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20181205085412-a5c9d58dba9a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190222072716-a9d3bda3a223/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190626221950-04f50cda93cb/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190813064441-fde4db37ae7a/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190904154756-749cb33beabd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20191005200804-aed5e4c7ecf9/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20191120155948-bd437916bb0e/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200223170610-d5e6a3e2c0ae/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200323222414-85ca7c5b95cd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200519105757-fe76b779f299/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200814200057-3d37ad5750ed/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210316164454-77fc1eacc6aa/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210324051608-47abb6519492/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210330210617-4fbd30eecc44/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210403161142-5e06dd20ab57/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210510120138-977fb7262007/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20210927094055-39ccf1dd6fa6/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20211007075335-d3039528d8ac/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220209214540-3681064d5158/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.7.0 h1:3jlCCIQZPdOYu1h8BkNvLz8Kgwtae2cagcG/VamtZRU=
+golang.org/x/sys v0.7.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.5/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
+golang.org/x/text v0.9.0 h1:2sjJmO8cDvYveuX97RDLsxlyUxLl+GHoLxBiRdHllBE=
+golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
+golang.org/x/time v0.0.0-20201208040808-7e3f01d25324/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20181221001348-537d06c36207/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20190114222345-bf090417da8b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20190226205152-f727befe758c/go.mod h1:9Yl7xja0Znq3iFh3HoIrodX9oNMXvdceNzlUR8zjMvY=
+golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
+golang.org/x/tools v0.0.0-20190327201419-c70d86f8b7cf/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
+golang.org/x/tools v0.0.0-20190328211700-ab21143f2384/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
+golang.org/x/tools v0.0.0-20190524140312-2c0ae7006135/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.0.0-20200130002326-2f3ba24bd6e7/go.mod h1:TB2adYChydJhpapKDTa4BR/hXlZSLoq2Wpct/0txZ28=
+golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
+golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
+golang.org/x/tools v0.1.3/go.mod h1:o0xws9oXOQQZyjljx8fwUC0k7L1pTE6eaCbjGeHmOkk=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20220517211312-f3a8303e98df h1:5Pf6pFKu98ODmgnpvkJ3kFUOQGGLIzLIkbzUHp47618=
+google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM=
+google.golang.org/appengine v1.4.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=
+google.golang.org/genproto v0.0.0-20180518175338-11a468237815/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc=
+google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc=
+google.golang.org/genproto v0.0.0-20190819201941-24fa4b261c55/go.mod h1:DMBHOl98Agz4BDEuKkezgsaosCRResVns1a3J2ZsMNc=
+google.golang.org/genproto v0.0.0-20200526211855-cb27e3aa2013/go.mod h1:NbSheEEYHJ7i3ixzK3sjbqSGDJWnxyFXZblF3eUsNvo=
+google.golang.org/genproto v0.0.0-20210624195500-8bfb893ecb84/go.mod h1:SzzZ/N+nwJDaO1kznhnlzqS8ocJICar6hYhVyhi++24=
+google.golang.org/grpc v1.12.0/go.mod h1:yo6s7OP7yaDglbqo1J04qKzAhqBH6lvTonzMVmEdcZw=
+google.golang.org/grpc v1.19.0/go.mod h1:mqu4LbDTu4XGKhr4mRzUsmM4RtVoemTSY81AxZiDr8c=
+google.golang.org/grpc v1.23.0/go.mod h1:Y5yQAOtifL1yxbo5wqy6BxZv8vAUGQwXBOALyacEbxg=
+google.golang.org/grpc v1.25.1/go.mod h1:c3i+UQWmh7LiEpx4sFZnkU36qjEYZ0imhYfXVyQciAY=
+google.golang.org/grpc v1.27.0/go.mod h1:qbnxyOmOxrQa7FizSgH+ReBfzJrCY1pSN7KXBS8abTk=
+google.golang.org/grpc v1.38.0/go.mod h1:NREThFqKR1f3iQ6oBuvc5LadQuXVGo9rkm5ZGrQdJfM=
+google.golang.org/protobuf v0.0.0-20200109180630-ec00e32a8dfd/go.mod h1:DFci5gLYBciE7Vtevhsrf46CRTquxDuWsQurQQe4oz8=
+google.golang.org/protobuf v0.0.0-20200221191635-4d8936d0db64/go.mod h1:kwYJMbMJ01Woi6D6+Kah6886xMZcty6N08ah7+eCXa0=
+google.golang.org/protobuf v0.0.0-20200228230310-ab0ca4ff8a60/go.mod h1:cfTl7dwQJ+fmap5saPgwCLgHXTUD7jkjRqWcaiX5VyM=
+google.golang.org/protobuf v1.20.1-0.20200309200217-e05f789c0967/go.mod h1:A+miEFZTKqfCUM6K7xSMQL9OKL/b6hQv+e19PK+JZNE=
+google.golang.org/protobuf v1.21.0/go.mod h1:47Nbq4nVaFHyn7ilMalzfO3qCViNmqZ2kzikPIcrTAo=
+google.golang.org/protobuf v1.22.0/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2l/sGQquU=
+google.golang.org/protobuf v1.23.0/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2l/sGQquU=
+google.golang.org/protobuf v1.23.1-0.20200526195155-81db48ad09cc/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2l/sGQquU=
+google.golang.org/protobuf v1.25.0/go.mod h1:9JNX74DMeImyA3h4bdi1ymwjUzf21/xIlbajtzgsN7c=
+google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
+google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
+google.golang.org/protobuf v1.28.1 h1:d0NfwRgPtno5B1Wa6L2DAG+KivqkdutMf1UhdNx175w=
+google.golang.org/protobuf v1.28.1/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=
+gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMys=
+gopkg.in/go-playground/assert.v1 v1.2.1/go.mod h1:9RXL0bg/zibRAgZUYszZSwO/z8Y/a8bDuhia5mkpMnE=
+gopkg.in/go-playground/validator.v8 v8.18.2/go.mod h1:RX2a/7Ha8BgOhfk7j780h4/u/RRjR0eouCJSH80/M2Y=
+gopkg.in/ini.v1 v1.51.1/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
+gopkg.in/mgo.v2 v2.0.0-20180705113604-9856a29383ce/go.mod h1:yeKp02qBN3iKW1OzL3MGk2IdtZzaj7SFntXj72NppTA=
+gopkg.in/natefinch/npipe.v2 v2.0.0-20160621034901-c1b8fa8bdcce h1:+JknDZhAj8YMt7GC73Ei8pv4MzjDUNPHgQWJdtMAaDU=
+gopkg.in/natefinch/npipe.v2 v2.0.0-20160621034901-c1b8fa8bdcce/go.mod h1:5AcXVHNjg+BDxry382+8OKon8SEWiKktQR07RKPsv1c=
+gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 h1:uRGJdciOHaEIrze2W8Q3AKkepLTh2hOroT7a+7czfdQ=
+gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v3 v3.0.0-20191120175047-4206685974f2/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
+honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

cannon/main.go

+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/urfave/cli/v2"
+
+	"github.com/ethereum-optimism/cannon/cmd"
+)
+
+func main() {
+	app := cli.NewApp()
+	app.Name = "cannon"
+	app.Usage = "MIPS Fault Proof tool"
+	app.Description = "MIPS Fault Proof tool"
+	app.Commands = []*cli.Command{
+		cmd.LoadELFCommand,
+		cmd.RunCommand,
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+
+	c := make(chan os.Signal, 1)
+	signal.Notify(c, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		for {
+			<-c
+			cancel()
+			fmt.Println("\r\nExiting...")
+		}
+	}()
+
+	err := app.RunContext(ctx, os.Args)
+	if err != nil {
+		if errors.Is(err, ctx.Err()) {
+			_, _ = fmt.Fprintf(os.Stderr, "command interrupted")
+			os.Exit(130)
+		} else {
+			_, _ = fmt.Fprintf(os.Stderr, "error: %v", err)
+			os.Exit(1)
+		}
+	}
+}

cannon/mipsevm/.gitignore

+mipsevm
+mipsevm.test
+*.prof

cannon/mipsevm/README.md

+# `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.
+4. Implement the `PreimageOracle` interface
+5. Instrument the emulator with the state, and pre-image oracle, using `NewInstrumentedState`
+6. Step through the instrumented state with `Step(proof)`,
+   where `proof==true` if witness data should be generated. Steps are faster with `proof==false`.
+7. Optionally repeat the step on-chain by calling `MIPS.sol` and `Oracle.sol`, using the above witness data.

cannon/mipsevm/evm.go

+package mipsevm
+
+import (
+	"encoding/binary"
+	"encoding/json"
+	"fmt"
+	"math/big"
+	"os"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/consensus"
+	"github.com/ethereum/go-ethereum/consensus/ethash"
+	"github.com/ethereum/go-ethereum/core"
+	"github.com/ethereum/go-ethereum/core/rawdb"
+	"github.com/ethereum/go-ethereum/core/state"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/core/vm"
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/ethereum/go-ethereum/params"
+)
+
+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]
+)
+
+func LoadContracts() (*Contracts, error) {
+	mips, err := LoadContract("MIPS")
+	if err != nil {
+		return nil, err
+	}
+	oracle, err := LoadContract("Oracle")
+	if err != nil {
+		return nil, err
+	}
+	return &Contracts{
+		MIPS:   mips,
+		Oracle: oracle,
+	}, nil
+}
+
+func LoadContract(name string) (*Contract, error) {
+	// TODO change to forge build output
+	dat, err := os.ReadFile(fmt.Sprintf("../contracts/out/%s.sol/%s.json", name, name))
+	if err != nil {
+		return nil, fmt.Errorf("failed to read contract JSON definition of %q: %w", name, err)
+	}
+	var out Contract
+	if err := json.Unmarshal(dat, &out); err != nil {
+		return nil, fmt.Errorf("failed to parse contract JSON definition of %q: %w", name, err)
+	}
+	return &out, nil
+}
+
+type Contract struct {
+	DeployedBytecode struct {
+		Object    hexutil.Bytes `json:"object"`
+		SourceMap string        `json:"sourceMap"`
+	} `json:"deployedBytecode"`
+
+	// ignore abi,bytecode,etc.
+}
+
+func (c *Contract) SourceMap(sourcePaths []string) (*SourceMap, error) {
+	return ParseSourceMap(sourcePaths, c.DeployedBytecode.Object, c.DeployedBytecode.SourceMap)
+}
+
+type Contracts struct {
+	MIPS   *Contract
+	Oracle *Contract
+}
+
+type Addresses struct {
+	MIPS         common.Address
+	Oracle       common.Address
+	Sender       common.Address
+	FeeRecipient common.Address
+}
+
+func NewEVMEnv(contracts *Contracts, addrs *Addresses) (*vm.EVM, *state.StateDB) {
+	chainCfg := params.MainnetChainConfig
+	offsetBlocks := uint64(1000) // blocks after shanghai fork
+	bc := &testChain{startTime: *chainCfg.ShanghaiTime + offsetBlocks*12}
+	header := bc.GetHeader(common.Hash{}, 17034870+offsetBlocks)
+	db := rawdb.NewMemoryDatabase()
+	statedb := state.NewDatabase(db)
+	state, err := state.New(types.EmptyRootHash, statedb, nil)
+	if err != nil {
+		panic(fmt.Errorf("failed to create memory state db: %w", err))
+	}
+	blockContext := core.NewEVMBlockContext(header, bc, nil)
+	vmCfg := vm.Config{}
+
+	env := vm.NewEVM(blockContext, vm.TxContext{}, state, chainCfg, vmCfg)
+	// pre-deploy the contracts
+	env.StateDB.SetCode(addrs.MIPS, contracts.MIPS.DeployedBytecode.Object)
+	env.StateDB.SetCode(addrs.Oracle, contracts.Oracle.DeployedBytecode.Object)
+	env.StateDB.SetState(addrs.MIPS, common.Hash{}, addrs.Oracle.Hash())
+
+	rules := env.ChainConfig().Rules(header.Number, true, header.Time)
+	env.StateDB.Prepare(rules, addrs.Sender, addrs.FeeRecipient, &addrs.MIPS, vm.ActivePrecompiles(rules), nil)
+	return env, state
+}
+
+type testChain struct {
+	startTime uint64
+}
+
+func (d *testChain) Engine() consensus.Engine {
+	return ethash.NewFullFaker()
+}
+
+func (d *testChain) GetHeader(h common.Hash, n uint64) *types.Header {
+	parentHash := common.Hash{0: 0xff}
+	binary.BigEndian.PutUint64(parentHash[1:], n-1)
+	return &types.Header{
+		ParentHash:      parentHash,
+		UncleHash:       types.EmptyUncleHash,
+		Coinbase:        common.Address{},
+		Root:            common.Hash{},
+		TxHash:          types.EmptyTxsHash,
+		ReceiptHash:     types.EmptyReceiptsHash,
+		Bloom:           types.Bloom{},
+		Difficulty:      big.NewInt(0),
+		Number:          new(big.Int).SetUint64(n),
+		GasLimit:        30_000_000,
+		GasUsed:         0,
+		Time:            d.startTime + n*12,
+		Extra:           nil,
+		MixDigest:       common.Hash{},
+		Nonce:           types.BlockNonce{},
+		BaseFee:         big.NewInt(7),
+		WithdrawalsHash: &types.EmptyWithdrawalsHash,
+	}
+}

cannon/mipsevm/evm_test.go

+package mipsevm
+
+import (
+	"bytes"
+	"debug/elf"
+	"io"
+	"math/big"
+	"os"
+	"path"
+	"testing"
+	"time"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/core/vm"
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/stretchr/testify/require"
+)
+
+func testContractsSetup(t *testing.T) (*Contracts, *Addresses, *SourceMapTracer) {
+	contracts, err := LoadContracts()
+	require.NoError(t, err)
+
+	mipsSrcMap, err := contracts.MIPS.SourceMap([]string{"../contracts/src/MIPS.sol"})
+	require.NoError(t, err)
+	oracleSrcMap, err := contracts.Oracle.SourceMap([]string{"../contracts/src/Oracle.sol"})
+	require.NoError(t, err)
+
+	addrs := &Addresses{
+		MIPS:         common.Address{0: 0xff, 19: 1},
+		Oracle:       common.Address{0: 0xff, 19: 2},
+		Sender:       common.Address{0x13, 0x37},
+		FeeRecipient: common.Address{0xaa},
+	}
+	tracer := NewSourceMapTracer(map[common.Address]*SourceMap{addrs.MIPS: mipsSrcMap, addrs.Oracle: oracleSrcMap}, os.Stdout)
+	return contracts, addrs, tracer
+}
+
+func TestEVM(t *testing.T) {
+	testFiles, err := os.ReadDir("open_mips_tests/test/bin")
+	require.NoError(t, err)
+
+	contracts, addrs, tracer := testContractsSetup(t)
+	sender := common.Address{0x13, 0x37}
+	//tracer = logger.NewMarkdownLogger(&logger.Config{}, os.Stdout)
+
+	for _, f := range testFiles {
+		t.Run(f.Name(), func(t *testing.T) {
+			if f.Name() == "oracle.bin" {
+				t.Skip("oracle test needs to be updated to use syscall pre-image oracle")
+			}
+
+			env, evmState := NewEVMEnv(contracts, addrs)
+			env.Config.Debug = false
+			env.Config.Tracer = tracer
+
+			fn := path.Join("open_mips_tests/test/bin", f.Name())
+			programMem, err := os.ReadFile(fn)
+			require.NoError(t, err)
+			state := &State{PC: 0, NextPC: 4, Memory: NewMemory()}
+			err = state.Memory.SetMemoryRange(0, bytes.NewReader(programMem))
+			require.NoError(t, err, "load program into state")
+
+			// set the return address ($ra) to jump into when test completes
+			state.Registers[31] = endAddr
+
+			us := NewInstrumentedState(state, nil, os.Stdout, os.Stderr)
+
+			for i := 0; i < 1000; i++ {
+				if us.state.PC == endAddr {
+					break
+				}
+				insn := state.Memory.GetMemory(state.PC)
+				t.Logf("step: %4d pc: 0x%08x insn: 0x%08x", state.Step, state.PC, insn)
+
+				stepWitness, err := us.Step(true)
+				require.NoError(t, err)
+				input := stepWitness.EncodeStepInput()
+				startingGas := uint64(30_000_000)
+
+				// we take a snapshot so we can clean up the state, and isolate the logs of this instruction run.
+				snap := env.StateDB.Snapshot()
+				ret, leftOverGas, err := env.Call(vm.AccountRef(sender), addrs.MIPS, input, startingGas, big.NewInt(0))
+				require.NoError(t, err, "evm should not fail")
+				require.Len(t, ret, 32, "expecting 32-byte state hash")
+				// remember state hash, to check it against state
+				postHash := common.Hash(*(*[32]byte)(ret))
+				logs := evmState.Logs()
+				require.Equal(t, 1, len(logs), "expecting a log with post-state")
+				evmPost := logs[0].Data
+				require.Equal(t, crypto.Keccak256Hash(evmPost), postHash, "logged state must be accurate")
+				env.StateDB.RevertToSnapshot(snap)
+
+				t.Logf("EVM step took %d gas, and returned stateHash %s", startingGas-leftOverGas, postHash)
+
+				// verify the post-state matches.
+				// TODO: maybe more readable to decode the evmPost state, and do attribute-wise comparison.
+				uniPost := us.state.EncodeWitness()
+				require.Equal(t, hexutil.Bytes(uniPost).String(), hexutil.Bytes(evmPost).String(),
+					"unicorn produced different state than EVM")
+			}
+			require.Equal(t, uint32(endAddr), state.PC, "must reach end")
+			// inspect test result
+			done, result := state.Memory.GetMemory(baseAddrEnd+4), state.Memory.GetMemory(baseAddrEnd+8)
+			require.Equal(t, done, uint32(1), "must be done")
+			require.Equal(t, result, uint32(1), "must have success result")
+		})
+	}
+}
+
+func TestHelloEVM(t *testing.T) {
+	contracts, addrs, tracer := testContractsSetup(t)
+	sender := common.Address{0x13, 0x37}
+
+	elfProgram, err := elf.Open("../example/bin/hello.elf")
+	require.NoError(t, err, "open ELF file")
+
+	state, err := LoadELF(elfProgram)
+	require.NoError(t, err, "load ELF into state")
+
+	err = PatchGo(elfProgram, state)
+	require.NoError(t, err, "apply Go runtime patches")
+	require.NoError(t, PatchStack(state), "add initial stack")
+
+	var stdOutBuf, stdErrBuf bytes.Buffer
+	us := NewInstrumentedState(state, nil, io.MultiWriter(&stdOutBuf, os.Stdout), io.MultiWriter(&stdErrBuf, os.Stderr))
+
+	env, evmState := NewEVMEnv(contracts, addrs)
+	env.Config.Debug = false
+	env.Config.Tracer = tracer
+
+	start := time.Now()
+	for i := 0; i < 400_000; i++ {
+		if us.state.Exited {
+			break
+		}
+		insn := state.Memory.GetMemory(state.PC)
+		if i%1000 == 0 { // avoid spamming test logs, we are executing many steps
+			t.Logf("step: %4d pc: 0x%08x insn: 0x%08x", state.Step, state.PC, insn)
+		}
+
+		stepWitness, err := us.Step(true)
+		require.NoError(t, err)
+		input := stepWitness.EncodeStepInput()
+		startingGas := uint64(30_000_000)
+
+		// we take a snapshot so we can clean up the state, and isolate the logs of this instruction run.
+		snap := env.StateDB.Snapshot()
+		ret, leftOverGas, err := env.Call(vm.AccountRef(sender), addrs.MIPS, input, startingGas, big.NewInt(0))
+		require.NoErrorf(t, err, "evm should not fail, took %d gas", startingGas-leftOverGas)
+		require.Len(t, ret, 32, "expecting 32-byte state hash")
+		// remember state hash, to check it against state
+		postHash := common.Hash(*(*[32]byte)(ret))
+		logs := evmState.Logs()
+		require.Equal(t, 1, len(logs), "expecting a log with post-state")
+		evmPost := logs[0].Data
+		require.Equal(t, crypto.Keccak256Hash(evmPost), postHash, "logged state must be accurate")
+		env.StateDB.RevertToSnapshot(snap)
+
+		//t.Logf("EVM step took %d gas, and returned stateHash %s", startingGas-leftOverGas, postHash)
+
+		// verify the post-state matches.
+		// TODO: maybe more readable to decode the evmPost state, and do attribute-wise comparison.
+		uniPost := us.state.EncodeWitness()
+		require.Equal(t, hexutil.Bytes(uniPost).String(), hexutil.Bytes(evmPost).String(),
+			"unicorn produced different state than EVM")
+	}
+	end := time.Now()
+	delta := end.Sub(start)
+	t.Logf("test took %s, %d instructions, %s per instruction", delta, state.Step, delta/time.Duration(state.Step))
+
+	require.True(t, state.Exited, "must complete program")
+	require.Equal(t, uint8(0), state.ExitCode, "exit with 0")
+
+	require.Equal(t, "hello world!", stdOutBuf.String(), "stdout says hello")
+	require.Equal(t, "", stdErrBuf.String(), "stderr silent")
+}
+
+func TestClaimEVM(t *testing.T) {
+	contracts, addrs, tracer := testContractsSetup(t)
+
+	elfProgram, err := elf.Open("../example/bin/claim.elf")
+	require.NoError(t, err, "open ELF file")
+
+	state, err := LoadELF(elfProgram)
+	require.NoError(t, err, "load ELF into state")
+
+	err = PatchGo(elfProgram, state)
+	require.NoError(t, err, "apply Go runtime patches")
+	require.NoError(t, PatchStack(state), "add initial stack")
+
+	oracle, expectedStdOut, expectedStdErr := claimTestOracle(t)
+
+	var stdOutBuf, stdErrBuf bytes.Buffer
+	us := NewInstrumentedState(state, oracle, io.MultiWriter(&stdOutBuf, os.Stdout), io.MultiWriter(&stdErrBuf, os.Stderr))
+
+	env, evmState := NewEVMEnv(contracts, addrs)
+	env.Config.Debug = false
+	env.Config.Tracer = tracer
+
+	for i := 0; i < 2000_000; i++ {
+		if us.state.Exited {
+			break
+		}
+
+		insn := state.Memory.GetMemory(state.PC)
+		if i%1000 == 0 { // avoid spamming test logs, we are executing many steps
+			t.Logf("step: %4d pc: 0x%08x insn: 0x%08x", state.Step, state.PC, insn)
+		}
+
+		stepWitness, err := us.Step(true)
+		require.NoError(t, err)
+		input := stepWitness.EncodeStepInput()
+		startingGas := uint64(30_000_000)
+
+		// we take a snapshot so we can clean up the state, and isolate the logs of this instruction run.
+		snap := env.StateDB.Snapshot()
+
+		// prepare pre-image oracle data, if any
+		if stepWitness.HasPreimage() {
+			poInput, err := stepWitness.EncodePreimageOracleInput()
+			require.NoError(t, err, "encode preimage oracle input")
+			_, leftOverGas, err := env.Call(vm.AccountRef(addrs.Sender), addrs.Oracle, poInput, startingGas, big.NewInt(0))
+			require.NoErrorf(t, err, "evm should not fail, took %d gas", startingGas-leftOverGas)
+		}
+
+		ret, leftOverGas, err := env.Call(vm.AccountRef(addrs.Sender), addrs.MIPS, input, startingGas, big.NewInt(0))
+		require.NoErrorf(t, err, "evm should not fail, took %d gas", startingGas-leftOverGas)
+		require.Len(t, ret, 32, "expecting 32-byte state hash")
+		// remember state hash, to check it against state
+		postHash := common.Hash(*(*[32]byte)(ret))
+		logs := evmState.Logs()
+		require.Equal(t, 1, len(logs), "expecting a log with post-state")
+		evmPost := logs[0].Data
+		require.Equal(t, crypto.Keccak256Hash(evmPost), postHash, "logged state must be accurate")
+		env.StateDB.RevertToSnapshot(snap)
+	}
+
+	require.True(t, state.Exited, "must complete program")
+	require.Equal(t, uint8(0), state.ExitCode, "exit with 0")
+
+	require.Equal(t, expectedStdOut, stdOutBuf.String(), "stdout")
+	require.Equal(t, expectedStdErr, stdErrBuf.String(), "stderr")
+}

cannon/mipsevm/instrumented.go

+package mipsevm
+
+import (
+	"io"
+)
+
+type PreimageOracle interface {
+	Hint(v []byte)
+	GetPreimage(k [32]byte) []byte
+}
+
+type InstrumentedState struct {
+	state *State
+
+	stdOut io.Writer
+	stdErr io.Writer
+
+	lastMemAccess   uint32
+	memProofEnabled bool
+	memProof        [28 * 32]byte
+
+	preimageOracle PreimageOracle
+
+	// cached pre-image data, including 8 byte length prefix
+	lastPreimage []byte
+	// key for above preimage
+	lastPreimageKey [32]byte
+	// offset we last read from, or max uint32 if nothing is read this step
+	lastPreimageOffset uint32
+}
+
+const (
+	fdStdin         = 0
+	fdStdout        = 1
+	fdStderr        = 2
+	fdHintRead      = 3
+	fdHintWrite     = 4
+	fdPreimageRead  = 5
+	fdPreimageWrite = 6
+)
+
+const (
+	MipsEBADF  = 0x9
+	MipsEINVAL = 0x16
+)
+
+func NewInstrumentedState(state *State, po PreimageOracle, stdOut, stdErr io.Writer) *InstrumentedState {
+	return &InstrumentedState{
+		state:          state,
+		stdOut:         stdOut,
+		stdErr:         stdErr,
+		preimageOracle: po,
+	}
+}
+
+func (m *InstrumentedState) Step(proof bool) (wit *StepWitness, err error) {
+	m.memProofEnabled = proof
+	m.lastMemAccess = ^uint32(0)
+	m.lastPreimageOffset = ^uint32(0)
+
+	if proof {
+		insnProof := m.state.Memory.MerkleProof(m.state.PC)
+		wit = &StepWitness{
+			State:    m.state.EncodeWitness(),
+			MemProof: insnProof[:],
+		}
+	}
+	err = m.mipsStep()
+	if err != nil {
+		return nil, err
+	}
+
+	if proof {
+		wit.MemProof = append(wit.MemProof, m.memProof[:]...)
+		if m.lastPreimageOffset != ^uint32(0) {
+			wit.PreimageOffset = m.lastPreimageOffset
+			wit.PreimageKey = m.lastPreimageKey
+			wit.PreimageValue = m.lastPreimage
+		}
+	}
+	return
+}

cannon/mipsevm/logw.go

+package mipsevm
+
+import (
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/log"
+)
+
+// 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.
+type LoggingWriter struct {
+	Name string
+	Log  log.Logger
+}
+
+func logAsText(b string) bool {
+	for _, c := range b {
+		if (c < 0x20 || c >= 0x7F) && (c != '\n' && c != '\t') {
+			return false
+		}
+	}
+	return true
+}
+
+func (lw *LoggingWriter) Write(b []byte) (int, error) {
+	t := string(b)
+	if logAsText(t) {
+		lw.Log.Info("", "text", t)
+	} else {
+		lw.Log.Info("", "data", hexutil.Bytes(b))
+	}
+	return len(b), nil
+}

cannon/mipsevm/memory.go

+package mipsevm
+
+import (
+	"encoding/binary"
+	"encoding/json"
+	"fmt"
+	"io"
+	"math/bits"
+	"sort"
+
+	"github.com/ethereum/go-ethereum/crypto"
+)
+
+// Note: 2**12 = 4 KiB, the minimum page-size in Unicorn for mmap
+// as well as the Go runtime min phys page size.
+const (
+	PageAddrSize = 12
+	PageKeySize  = 32 - PageAddrSize
+	PageSize     = 1 << PageAddrSize
+	PageAddrMask = PageSize - 1
+	MaxPageCount = 1 << PageKeySize
+	PageKeyMask  = MaxPageCount - 1
+)
+
+func HashPair(left, right [32]byte) [32]byte {
+	out := crypto.Keccak256Hash(left[:], right[:])
+	//fmt.Printf("0x%x 0x%x -> 0x%x\n", left, right, out)
+	return out
+}
+
+var zeroHashes = func() [256][32]byte {
+	// empty parts of the tree are all zero. Precompute the hash of each full-zero range sub-tree level.
+	var out [256][32]byte
+	for i := 1; i < 256; i++ {
+		out[i] = HashPair(out[i-1], out[i-1])
+	}
+	return out
+}()
+
+type Memory struct {
+	// generalized index -> merkle root or nil if invalidated
+	nodes map[uint64]*[32]byte
+
+	// pageIndex -> cached page
+	pages map[uint32]*CachedPage
+
+	// Note: since we don't de-alloc pages, we don't do ref-counting.
+	// Once a page exists, it doesn't leave memory
+
+	// two caches: we often read instructions from one page, and do memory things with another page.
+	// this prevents map lookups each instruction
+	lastPageKeys [2]uint32
+	lastPage     [2]*CachedPage
+}
+
+func NewMemory() *Memory {
+	return &Memory{
+		nodes:        make(map[uint64]*[32]byte),
+		pages:        make(map[uint32]*CachedPage),
+		lastPageKeys: [2]uint32{^uint32(0), ^uint32(0)}, // default to invalid keys, to not match any pages
+	}
+}
+
+func (m *Memory) PageCount() int {
+	return len(m.pages)
+}
+
+func (m *Memory) ForEachPage(fn func(pageIndex uint32, page *Page) error) error {
+	for pageIndex, cachedPage := range m.pages {
+		if err := fn(pageIndex, cachedPage.Data); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (m *Memory) Invalidate(addr uint32) {
+	// addr must be aligned to 4 bytes
+	if addr&0x3 != 0 {
+		panic(fmt.Errorf("unaligned memory access: %x", addr))
+	}
+
+	// find page, and invalidate addr within it
+	if p, ok := m.pageLookup(addr >> PageAddrSize); ok {
+		prevValid := p.Ok[1]
+		p.Invalidate(addr & PageAddrMask)
+		if !prevValid { // if the page was already invalid before, then nodes to mem-root will also still be.
+			return
+		}
+	} else { // no page? nothing to invalidate
+		return
+	}
+
+	// find the gindex of the first page covering the address
+	gindex := ((uint64(1) << 32) | uint64(addr)) >> PageAddrSize
+
+	for gindex > 0 {
+		m.nodes[gindex] = nil
+		gindex >>= 1
+	}
+}
+
+func (m *Memory) MerkleizeSubtree(gindex uint64) [32]byte {
+	l := uint64(bits.Len64(gindex))
+	if l > 28 {
+		panic("gindex too deep")
+	}
+	if l > PageKeySize {
+		depthIntoPage := l - 1 - PageKeySize
+		pageIndex := (gindex >> depthIntoPage) & PageKeyMask
+		if p, ok := m.pages[uint32(pageIndex)]; ok {
+			pageGindex := (1 << depthIntoPage) | (gindex & ((1 << depthIntoPage) - 1))
+			return p.MerkleizeSubtree(pageGindex)
+		} else {
+			return zeroHashes[28-l] // page does not exist
+		}
+	}
+	if l > PageKeySize+1 {
+		panic("cannot jump into intermediate node of page")
+	}
+	n, ok := m.nodes[gindex]
+	if !ok {
+		// if the node doesn't exist, the whole sub-tree is zeroed
+		return zeroHashes[28-l]
+	}
+	if n != nil {
+		return *n
+	}
+	left := m.MerkleizeSubtree(gindex << 1)
+	right := m.MerkleizeSubtree((gindex << 1) | 1)
+	r := HashPair(left, right)
+	m.nodes[gindex] = &r
+	return r
+}
+
+func (m *Memory) MerkleProof(addr uint32) (out [28 * 32]byte) {
+	proof := m.traverseBranch(1, addr, 0)
+	// encode the proof
+	for i := 0; i < 28; i++ {
+		copy(out[i*32:(i+1)*32], proof[i][:])
+	}
+	return out
+}
+
+func (m *Memory) traverseBranch(parent uint64, addr uint32, depth uint8) (proof [][32]byte) {
+	if depth == 32-5 {
+		proof = make([][32]byte, 0, 32-5+1)
+		proof = append(proof, m.MerkleizeSubtree(parent))
+		return
+	}
+	if depth > 32-5 {
+		panic("traversed too deep")
+	}
+	self := parent << 1
+	sibling := self | 1
+	if addr&(1<<(31-depth)) != 0 {
+		self, sibling = sibling, self
+	}
+	proof = m.traverseBranch(self, addr, depth+1)
+	siblingNode := m.MerkleizeSubtree(sibling)
+	proof = append(proof, siblingNode)
+	return
+}
+
+func (m *Memory) MerkleRoot() [32]byte {
+	return m.MerkleizeSubtree(1)
+}
+
+func (m *Memory) pageLookup(pageIndex uint32) (*CachedPage, bool) {
+	// hit caches
+	if pageIndex == m.lastPageKeys[0] {
+		return m.lastPage[0], true
+	}
+	if pageIndex == m.lastPageKeys[1] {
+		return m.lastPage[1], true
+	}
+	p, ok := m.pages[pageIndex]
+
+	// only cache existing pages.
+	if ok {
+		m.lastPageKeys[1] = m.lastPageKeys[0]
+		m.lastPage[1] = m.lastPage[0]
+		m.lastPageKeys[0] = pageIndex
+		m.lastPage[0] = p
+	}
+
+	return p, ok
+}
+
+func (m *Memory) SetMemory(addr uint32, v uint32) {
+	// addr must be aligned to 4 bytes
+	if addr&0x3 != 0 {
+		panic(fmt.Errorf("unaligned memory access: %x", addr))
+	}
+
+	pageIndex := addr >> PageAddrSize
+	pageAddr := addr & PageAddrMask
+	p, ok := m.pageLookup(pageIndex)
+	if !ok {
+		// allocate the page if we have not already.
+		// Go may mmap relatively large ranges, but we only allocate the pages just in time.
+		p = m.AllocPage(pageIndex)
+	} else {
+		m.Invalidate(addr) // invalidate this branch of memory, now that the value changed
+	}
+	binary.BigEndian.PutUint32(p.Data[pageAddr:pageAddr+4], v)
+}
+
+func (m *Memory) GetMemory(addr uint32) uint32 {
+	// addr must be aligned to 4 bytes
+	if addr&0x3 != 0 {
+		panic(fmt.Errorf("unaligned memory access: %x", addr))
+	}
+	p, ok := m.pageLookup(addr >> PageAddrSize)
+	if !ok {
+		return 0
+	}
+	pageAddr := addr & PageAddrMask
+	return binary.BigEndian.Uint32(p.Data[pageAddr : pageAddr+4])
+}
+
+func (m *Memory) AllocPage(pageIndex uint32) *CachedPage {
+	p := &CachedPage{Data: new(Page)}
+	m.pages[pageIndex] = p
+	// make nodes to root
+	k := (1 << PageKeySize) | uint64(pageIndex)
+	for k > 0 {
+		m.nodes[k] = nil
+		k >>= 1
+	}
+	return p
+}
+
+type pageEntry struct {
+	Index uint32 `json:"index"`
+	Data  *Page  `json:"data"`
+}
+
+func (m *Memory) MarshalJSON() ([]byte, error) {
+	pages := make([]pageEntry, 0, len(m.pages))
+	for k, p := range m.pages {
+		pages = append(pages, pageEntry{
+			Index: k,
+			Data:  p.Data,
+		})
+	}
+	sort.Slice(pages, func(i, j int) bool {
+		return pages[i].Index < pages[j].Index
+	})
+	return json.Marshal(pages)
+}
+
+func (m *Memory) UnmarshalJSON(data []byte) error {
+	var pages []pageEntry
+	if err := json.Unmarshal(data, &pages); err != nil {
+		return err
+	}
+	m.nodes = make(map[uint64]*[32]byte)
+	m.pages = make(map[uint32]*CachedPage)
+	m.lastPageKeys = [2]uint32{^uint32(0), ^uint32(0)}
+	m.lastPage = [2]*CachedPage{nil, nil}
+	for i, p := range pages {
+		if _, ok := m.pages[p.Index]; ok {
+			return fmt.Errorf("cannot load duplicate page, entry %d, page index %d", i, p.Index)
+		}
+		m.AllocPage(p.Index).Data = p.Data
+	}
+	return nil
+}
+
+func (m *Memory) SetMemoryRange(addr uint32, r io.Reader) error {
+	for {
+		pageIndex := addr >> PageAddrSize
+		pageAddr := addr & PageAddrMask
+		p, ok := m.pageLookup(pageIndex)
+		if !ok {
+			p = m.AllocPage(pageIndex)
+		}
+		p.InvalidateFull()
+		n, err := r.Read(p.Data[pageAddr:])
+		if err != nil {
+			if err == io.EOF {
+				return nil
+			}
+			return err
+		}
+		addr += uint32(n)
+	}
+}
+
+type memReader struct {
+	m     *Memory
+	addr  uint32
+	count uint32
+}
+
+func (r *memReader) Read(dest []byte) (n int, err error) {
+	if r.count == 0 {
+		return 0, io.EOF
+	}
+
+	// Keep iterating over memory until we have all our data.
+	// It may wrap around the address range, and may not be aligned
+	endAddr := r.addr + r.count
+
+	pageIndex := r.addr >> PageAddrSize
+	start := r.addr & PageAddrMask
+	end := uint32(PageSize)
+
+	if pageIndex == (endAddr >> PageAddrSize) {
+		end = endAddr & PageAddrMask
+	}
+	p, ok := r.m.pageLookup(pageIndex)
+	if ok {
+		n = copy(dest, p.Data[start:end])
+	} else {
+		n = copy(dest, make([]byte, end-start)) // default to zeroes
+	}
+	r.addr += uint32(n)
+	r.count -= uint32(n)
+	return n, nil
+}
+
+func (m *Memory) ReadMemoryRange(addr uint32, count uint32) io.Reader {
+	return &memReader{m: m, addr: addr, count: count}
+}
+
+func (m *Memory) Usage() string {
+	total := uint64(len(m.pages)) * PageSize
+	const unit = 1024
+	if total < unit {
+		return fmt.Sprintf("%d B", total)
+	}
+	div, exp := uint64(unit), 0
+	for n := total / unit; n >= unit; n /= unit {
+		div *= unit
+		exp++
+	}
+	// KiB, MiB, GiB, TiB, ...
+	return fmt.Sprintf("%.1f %ciB", float64(total)/float64(div), "KMGTPE"[exp])
+}

cannon/mipsevm/memory_test.go

+package mipsevm
+
+import (
+	"bytes"
+	"crypto/rand"
+	"encoding/binary"
+	"encoding/json"
+	"io"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestMemoryMerkleProof(t *testing.T) {
+	t.Run("nearly empty tree", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(0x10000, 0xaabbccdd)
+		proof := m.MerkleProof(0x10000)
+		require.Equal(t, uint32(0xaabbccdd), binary.BigEndian.Uint32(proof[:4]))
+		for i := 0; i < 32-5; i++ {
+			require.Equal(t, zeroHashes[i][:], proof[32+i*32:32+i*32+32], "empty siblings")
+		}
+	})
+	t.Run("fuller tree", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(0x10000, 0xaabbccdd)
+		m.SetMemory(0x80004, 42)
+		m.SetMemory(0x13370000, 123)
+		root := m.MerkleRoot()
+		proof := m.MerkleProof(0x80004)
+		require.Equal(t, uint32(42), binary.BigEndian.Uint32(proof[4:8]))
+		node := *(*[32]byte)(proof[:32])
+		path := uint32(0x80004) >> 5
+		for i := 32; i < len(proof); i += 32 {
+			sib := *(*[32]byte)(proof[i : i+32])
+			if path&1 != 0 {
+				node = HashPair(sib, node)
+			} else {
+				node = HashPair(node, sib)
+			}
+			path >>= 1
+		}
+		require.Equal(t, root, node, "proof must verify")
+	})
+}
+
+func TestMemoryMerkleRoot(t *testing.T) {
+	t.Run("empty", func(t *testing.T) {
+		m := NewMemory()
+		root := m.MerkleRoot()
+		require.Equal(t, zeroHashes[32-5], root, "fully zeroed memory should have expected zero hash")
+	})
+	t.Run("empty page", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(0xF000, 0)
+		root := m.MerkleRoot()
+		require.Equal(t, zeroHashes[32-5], root, "fully zeroed memory should have expected zero hash")
+	})
+	t.Run("single page", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(0xF000, 1)
+		root := m.MerkleRoot()
+		require.NotEqual(t, zeroHashes[32-5], root, "non-zero memory")
+	})
+	t.Run("repeat zero", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(0xF000, 0)
+		m.SetMemory(0xF004, 0)
+		root := m.MerkleRoot()
+		require.Equal(t, zeroHashes[32-5], root, "zero still")
+	})
+	t.Run("two empty pages", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(PageSize*3, 0)
+		m.SetMemory(PageSize*10, 0)
+		root := m.MerkleRoot()
+		require.Equal(t, zeroHashes[32-5], root, "zero still")
+	})
+	t.Run("random few pages", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(PageSize*3, 1)
+		m.SetMemory(PageSize*5, 42)
+		m.SetMemory(PageSize*6, 123)
+		p3 := m.MerkleizeSubtree((1 << PageKeySize) | 3)
+		p5 := m.MerkleizeSubtree((1 << PageKeySize) | 5)
+		p6 := m.MerkleizeSubtree((1 << PageKeySize) | 6)
+		z := zeroHashes[PageAddrSize-5]
+		r1 := HashPair(
+			HashPair(
+				HashPair(z, z),  // 0,1
+				HashPair(z, p3), // 2,3
+			),
+			HashPair(
+				HashPair(z, p5), // 4,5
+				HashPair(p6, z), // 6,7
+			),
+		)
+		r2 := m.MerkleizeSubtree(1 << (PageKeySize - 3))
+		require.Equal(t, r1, r2, "expecting manual page combination to match subtree merkle func")
+	})
+	t.Run("invalidate page", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(0xF000, 0)
+		require.Equal(t, zeroHashes[32-5], m.MerkleRoot(), "zero at first")
+		m.SetMemory(0xF004, 1)
+		require.NotEqual(t, zeroHashes[32-5], m.MerkleRoot(), "non-zero")
+		m.SetMemory(0xF004, 0)
+		require.Equal(t, zeroHashes[32-5], m.MerkleRoot(), "zero again")
+	})
+}
+
+func TestMemoryReadWrite(t *testing.T) {
+
+	t.Run("large random", func(t *testing.T) {
+		m := NewMemory()
+		data := make([]byte, 20_000)
+		_, err := rand.Read(data[:])
+		require.NoError(t, err)
+		require.NoError(t, m.SetMemoryRange(0, bytes.NewReader(data)))
+		for _, i := range []uint32{0, 4, 1000, 20_000 - 4} {
+			v := m.GetMemory(i)
+			expected := binary.BigEndian.Uint32(data[i : i+4])
+			require.Equalf(t, expected, v, "read at %d", i)
+		}
+	})
+
+	t.Run("repeat range", func(t *testing.T) {
+		m := NewMemory()
+		data := []byte(strings.Repeat("under the big bright yellow sun ", 40))
+		require.NoError(t, m.SetMemoryRange(0x1337, bytes.NewReader(data)))
+		res, err := io.ReadAll(m.ReadMemoryRange(0x1337-10, uint32(len(data)+20)))
+		require.NoError(t, err)
+		require.Equal(t, make([]byte, 10), res[:10], "empty start")
+		require.Equal(t, data, res[10:len(res)-10], "result")
+		require.Equal(t, make([]byte, 10), res[len(res)-10:], "empty end")
+	})
+
+	t.Run("read-write", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(12, 0xAABBCCDD)
+		require.Equal(t, uint32(0xAABBCCDD), m.GetMemory(12))
+		m.SetMemory(12, 0xAABB1CDD)
+		require.Equal(t, uint32(0xAABB1CDD), m.GetMemory(12))
+	})
+
+	t.Run("unaligned read", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(12, 0xAABBCCDD)
+		m.SetMemory(16, 0x11223344)
+		require.Panics(t, func() {
+			m.GetMemory(13)
+		})
+		require.Panics(t, func() {
+			m.GetMemory(14)
+		})
+		require.Panics(t, func() {
+			m.GetMemory(15)
+		})
+		require.Equal(t, uint32(0x11223344), m.GetMemory(16))
+		require.Equal(t, uint32(0), m.GetMemory(20))
+		require.Equal(t, uint32(0xAABBCCDD), m.GetMemory(12))
+	})
+
+	t.Run("unaligned write", func(t *testing.T) {
+		m := NewMemory()
+		m.SetMemory(12, 0xAABBCCDD)
+		require.Panics(t, func() {
+			m.SetMemory(13, 0x11223344)
+		})
+		require.Panics(t, func() {
+			m.SetMemory(14, 0x11223344)
+		})
+		require.Panics(t, func() {
+			m.SetMemory(15, 0x11223344)
+		})
+		require.Equal(t, uint32(0xAABBCCDD), m.GetMemory(12))
+	})
+}
+
+func TestMemoryJSON(t *testing.T) {
+	m := NewMemory()
+	m.SetMemory(8, 123)
+	dat, err := json.Marshal(m)
+	require.NoError(t, err)
+	var res Memory
+	require.NoError(t, json.Unmarshal(dat, &res))
+	require.Equal(t, uint32(123), res.GetMemory(8))
+}

cannon/mipsevm/metadata.go

+package mipsevm
+
+import (
+	"debug/elf"
+	"fmt"
+	"sort"
+)
+
+type Symbol struct {
+	Name  string `json:"name"`
+	Start uint32 `json:"start"`
+	Size  uint32 `json:"size"`
+}
+
+type Metadata struct {
+	Symbols []Symbol `json:"symbols"`
+}
+
+func MakeMetadata(elfProgram *elf.File) (*Metadata, error) {
+	syms, err := elfProgram.Symbols()
+	if err != nil {
+		return nil, fmt.Errorf("failed to load symbols table: %w", err)
+	}
+	// Make sure the table is sorted, Go outputs mostly sorted data, except some internal functions
+	sort.Slice(syms, func(i, j int) bool {
+		return syms[i].Value < syms[j].Value
+	})
+	out := &Metadata{Symbols: make([]Symbol, len(syms))}
+	for i, s := range syms {
+		out.Symbols[i] = Symbol{Name: s.Name, Start: uint32(s.Value), Size: uint32(s.Size)}
+	}
+	return out, nil
+}
+
+func (m *Metadata) LookupSymbol(addr uint32) string {
+	if len(m.Symbols) == 0 {
+		return "!unknown"
+	}
+	// find first symbol with higher start. Or n if no such symbol exists
+	i := sort.Search(len(m.Symbols), func(i int) bool {
+		return m.Symbols[i].Start > addr
+	})
+	if i == 0 {
+		return "!start"
+	}
+	out := &m.Symbols[i-1]
+	if out.Start+out.Size < addr { // addr may be pointing to a gap between symbols
+		return "!gap"
+	}
+	return out.Name
+}
+
+func (m *Metadata) SymbolMatcher(name string) func(addr uint32) bool {
+	for _, s := range m.Symbols {
+		if s.Name == name {
+			start := s.Start
+			end := s.Start + s.Size
+			return func(addr uint32) bool {
+				return addr >= start && addr < end
+			}
+		}
+	}
+	return func(addr uint32) bool {
+		return false
+	}
+}
+
+// HexU32 to lazy-format integer attributes for logging
+type HexU32 uint32
+
+func (v HexU32) String() string {
+	return fmt.Sprintf("%08x", uint32(v))
+}
+
+func (v HexU32) MarshalText() ([]byte, error) {
+	return []byte(v.String()), nil
+}

cannon/mipsevm/mips.go

+package mipsevm
+
+import (
+	"encoding/binary"
+	"fmt"
+	"io"
+)
+
+func (m *InstrumentedState) readPreimage(key [32]byte, offset uint32) (dat [32]byte, datLen uint32) {
+	preimage := m.lastPreimage
+	if key != m.lastPreimageKey {
+		m.lastPreimageKey = key
+		data := m.preimageOracle.GetPreimage(key)
+		// add the length prefix
+		preimage = make([]byte, 0, 8+len(data))
+		preimage = binary.BigEndian.AppendUint64(preimage, uint64(len(data)))
+		preimage = append(preimage, data...)
+		m.lastPreimage = preimage
+	}
+	m.lastPreimageOffset = offset
+	datLen = uint32(copy(dat[:], preimage[offset:]))
+	return
+}
+
+func (m *InstrumentedState) trackMemAccess(effAddr uint32) {
+	if m.memProofEnabled && m.lastMemAccess != effAddr {
+		if m.lastMemAccess != ^uint32(0) {
+			panic(fmt.Errorf("unexpected different mem access at %08x, already have access at %08x buffered", effAddr, m.lastMemAccess))
+		}
+		m.lastMemAccess = effAddr
+		m.memProof = m.state.Memory.MerkleProof(effAddr)
+	}
+}
+
+func (m *InstrumentedState) handleSyscall() error {
+	syscallNum := m.state.Registers[2] // v0
+	v0 := uint32(0)
+	v1 := uint32(0)
+
+	a0 := m.state.Registers[4]
+	a1 := m.state.Registers[5]
+	a2 := m.state.Registers[6]
+
+	//fmt.Printf("syscall: %d\n", syscallNum)
+	switch syscallNum {
+	case 4090: // mmap
+		sz := a1
+		if sz&PageAddrMask != 0 { // adjust size to align with page size
+			sz += PageSize - (sz & PageAddrMask)
+		}
+		if a0 == 0 {
+			v0 = m.state.Heap
+			//fmt.Printf("mmap heap 0x%x size 0x%x\n", v0, sz)
+			m.state.Heap += sz
+		} else {
+			v0 = a0
+			//fmt.Printf("mmap hint 0x%x size 0x%x\n", v0, sz)
+		}
+		// Go does this thing where it first gets memory with PROT_NONE,
+		// and then mmaps with a hint with prot=3 (PROT_READ|WRITE).
+		// We can ignore the NONE case, to avoid duplicate/overlapping mmap calls to unicorn.
+		//prot := a2
+		//if prot != 0 {
+		//	if err := mu.MemMap(uint64(v0), uint64(sz)); err != nil {
+		//		log.Fatalf("mmap fail: %v", err)
+		//	}
+		//}
+	case 4045: // brk
+		v0 = 0x40000000
+	case 4120: // clone (not supported)
+		v0 = 1
+	case 4246: // exit_group
+		m.state.Exited = true
+		m.state.ExitCode = uint8(a0)
+		return nil
+	case 4003: // read
+		// args: a0 = fd, a1 = addr, a2 = count
+		// returns: v0 = read, v1 = err code
+		switch a0 {
+		case fdStdin:
+			// leave v0 and v1 zero: read nothing, no error
+		case fdPreimageRead: // pre-image oracle
+			effAddr := a1 & 0xFFffFFfc
+			m.trackMemAccess(effAddr)
+			mem := m.state.Memory.GetMemory(effAddr)
+			dat, datLen := m.readPreimage(m.state.PreimageKey, m.state.PreimageOffset)
+			//fmt.Printf("reading pre-image data: addr: %08x, offset: %d, datLen: %d, data: %x, key: %s  count: %d\n", a1, m.state.PreimageOffset, datLen, dat[:datLen], m.state.PreimageKey, a2)
+			alignment := a1 & 3
+			space := 4 - alignment
+			if space < datLen {
+				datLen = space
+			}
+			if a2 < datLen {
+				datLen = a2
+			}
+			var outMem [4]byte
+			binary.BigEndian.PutUint32(outMem[:], mem)
+			copy(outMem[alignment:], dat[:datLen])
+			m.state.Memory.SetMemory(effAddr, binary.BigEndian.Uint32(outMem[:]))
+			m.state.PreimageOffset += datLen
+			v0 = datLen
+			//fmt.Printf("read %d pre-image bytes, new offset: %d, eff addr: %08x mem: %08x\n", datLen, m.state.PreimageOffset, effAddr, outMem)
+		case fdHintRead: // hint response
+			// don't actually read into memory, just say we read it all, we ignore the result anyway
+			v0 = a2
+		default:
+			v0 = 0xFFffFFff
+			v1 = MipsEBADF
+		}
+	case 4004: // write
+		// args: a0 = fd, a1 = addr, a2 = count
+		// returns: v0 = written, v1 = err code
+		switch a0 {
+		case fdStdout:
+			_, _ = io.Copy(m.stdOut, m.state.Memory.ReadMemoryRange(a1, a2))
+			v0 = a2
+		case fdStderr:
+			_, _ = io.Copy(m.stdErr, m.state.Memory.ReadMemoryRange(a1, a2))
+			v0 = a2
+		case fdHintWrite:
+			hintData, _ := io.ReadAll(m.state.Memory.ReadMemoryRange(a1, a2))
+			m.state.LastHint = append(m.state.LastHint, hintData...)
+			for len(m.state.LastHint) >= 4 { // process while there is enough data to check if there are any hints
+				hintLen := binary.BigEndian.Uint32(m.state.LastHint[:4])
+				if hintLen >= uint32(len(m.state.LastHint[4:])) {
+					hint := m.state.LastHint[4 : 4+hintLen] // without the length prefix
+					m.state.LastHint = m.state.LastHint[4+hintLen:]
+					m.preimageOracle.Hint(hint)
+				} else {
+					break // stop processing hints if there is incomplete data buffered
+				}
+			}
+			v0 = a2
+		case fdPreimageWrite:
+			effAddr := a1 & 0xFFffFFfc
+			m.trackMemAccess(effAddr)
+			mem := m.state.Memory.GetMemory(effAddr)
+			key := m.state.PreimageKey
+			alignment := a1 & 3
+			space := 4 - alignment
+			if space < a2 {
+				a2 = space
+			}
+			copy(key[:], key[a2:])
+			var tmp [4]byte
+			binary.BigEndian.PutUint32(tmp[:], mem)
+			copy(key[32-a2:], tmp[:])
+			m.state.PreimageKey = key
+			m.state.PreimageOffset = 0
+			//fmt.Printf("updating pre-image key: %s\n", m.state.PreimageKey)
+			v0 = a2
+		default:
+			v0 = 0xFFffFFff
+			v1 = MipsEBADF
+		}
+	case 4055: // fcntl
+		// args: a0 = fd, a1 = cmd
+		if a1 == 3 { // F_GETFL: get file descriptor flags
+			switch a0 {
+			case fdStdin, fdPreimageRead, fdHintRead:
+				v0 = 0 // O_RDONLY
+			case fdStdout, fdStderr, fdPreimageWrite, fdHintWrite:
+				v0 = 1 // O_WRONLY
+			default:
+				v0 = 0xFFffFFff
+				v1 = MipsEBADF
+			}
+		} else {
+			v0 = 0xFFffFFff
+			v1 = MipsEINVAL // cmd not recognized by this kernel
+		}
+	}
+	m.state.Registers[2] = v0
+	m.state.Registers[7] = v1
+
+	m.state.PC = m.state.NextPC
+	m.state.NextPC = m.state.NextPC + 4
+	return nil
+}
+
+func (m *InstrumentedState) handleBranch(opcode uint32, insn uint32, rtReg uint32, rs uint32) error {
+	shouldBranch := false
+	if opcode == 4 || opcode == 5 { // beq/bne
+		rt := m.state.Registers[rtReg]
+		shouldBranch = (rs == rt && opcode == 4) || (rs != rt && opcode == 5)
+	} else if opcode == 6 {
+		shouldBranch = int32(rs) <= 0 // blez
+	} else if opcode == 7 {
+		shouldBranch = int32(rs) > 0 // bgtz
+	} else if opcode == 1 {
+		// regimm
+		rtv := (insn >> 16) & 0x1F
+		if rtv == 0 { // bltz
+			shouldBranch = int32(rs) < 0
+		}
+		if rtv == 1 { // bgez
+			shouldBranch = int32(rs) >= 0
+		}
+	}
+
+	prevPC := m.state.PC
+	m.state.PC = m.state.NextPC // execute the delay slot first
+	if shouldBranch {
+		m.state.NextPC = prevPC + 4 + (SE(insn&0xFFFF, 16) << 2) // then continue with the instruction the branch jumps to.
+	} else {
+		m.state.NextPC = m.state.NextPC + 4 // branch not taken
+	}
+	return nil
+}
+
+func (m *InstrumentedState) handleHiLo(fun uint32, rs uint32, rt uint32, storeReg uint32) error {
+	val := uint32(0)
+	switch fun {
+	case 0x10: // mfhi
+		val = m.state.HI
+	case 0x11: // mthi
+		m.state.HI = rs
+	case 0x12: // mflo
+		val = m.state.LO
+	case 0x13: // mtlo
+		m.state.LO = rs
+	case 0x18: // mult
+		acc := uint64(int64(int32(rs)) * int64(int32(rt)))
+		m.state.HI = uint32(acc >> 32)
+		m.state.LO = uint32(acc)
+	case 0x19: // multu
+		acc := uint64(uint64(rs) * uint64(rt))
+		m.state.HI = uint32(acc >> 32)
+		m.state.LO = uint32(acc)
+	case 0x1a: // div
+		m.state.HI = uint32(int32(rs) % int32(rt))
+		m.state.LO = uint32(int32(rs) / int32(rt))
+	case 0x1b: // divu
+		m.state.HI = rs % rt
+		m.state.LO = rs / rt
+	}
+
+	if storeReg != 0 {
+		m.state.Registers[storeReg] = val
+	}
+
+	m.state.PC = m.state.NextPC
+	m.state.NextPC = m.state.NextPC + 4
+	return nil
+}
+
+func (m *InstrumentedState) handleJump(linkReg uint32, dest uint32) error {
+	prevPC := m.state.PC
+	m.state.PC = m.state.NextPC
+	m.state.NextPC = dest
+	if linkReg != 0 {
+		m.state.Registers[linkReg] = prevPC + 8 // set the link-register to the instr after the delay slot instruction.
+	}
+	return nil
+}
+
+func (m *InstrumentedState) handleRd(storeReg uint32, val uint32, conditional bool) error {
+	if storeReg >= 32 {
+		panic("invalid register")
+	}
+	if storeReg != 0 && conditional {
+		m.state.Registers[storeReg] = val
+	}
+	m.state.PC = m.state.NextPC
+	m.state.NextPC = m.state.NextPC + 4
+	return nil
+}
+
+func (m *InstrumentedState) mipsStep() error {
+	if m.state.Exited {
+		return nil
+	}
+	m.state.Step += 1
+	// instruction fetch
+	insn := m.state.Memory.GetMemory(m.state.PC)
+	opcode := insn >> 26 // 6-bits
+
+	// j-type j/jal
+	if opcode == 2 || opcode == 3 {
+		// TODO likely bug in original code: MIPS spec says this should be in the "current" region;
+		// a 256 MB aligned region (i.e. use top 4 bits of branch delay slot (pc+4))
+		linkReg := uint32(0)
+		if opcode == 3 {
+			linkReg = 31
+		}
+		return m.handleJump(linkReg, SE(insn&0x03FFFFFF, 26)<<2)
+	}
+
+	// register fetch
+	rs := uint32(0) // source register 1 value
+	rt := uint32(0) // source register 2 / temp value
+	rtReg := (insn >> 16) & 0x1F
+
+	// R-type or I-type (stores rt)
+	rs = m.state.Registers[(insn>>21)&0x1F]
+	rdReg := rtReg
+	if opcode == 0 || opcode == 0x1c {
+		// R-type (stores rd)
+		rt = m.state.Registers[rtReg]
+		rdReg = (insn >> 11) & 0x1F
+	} else if opcode < 0x20 {
+		// rt is SignExtImm
+		// don't sign extend for andi, ori, xori
+		if opcode == 0xC || opcode == 0xD || opcode == 0xe {
+			// ZeroExtImm
+			rt = insn & 0xFFFF
+		} else {
+			// SignExtImm
+			rt = SE(insn&0xFFFF, 16)
+		}
+	} else if opcode >= 0x28 || opcode == 0x22 || opcode == 0x26 {
+		// store rt value with store
+		rt = m.state.Registers[rtReg]
+
+		// store actual rt with lwl and lwr
+		rdReg = rtReg
+	}
+
+	if (opcode >= 4 && opcode < 8) || opcode == 1 {
+		return m.handleBranch(opcode, insn, rtReg, rs)
+	}
+
+	storeAddr := uint32(0xFF_FF_FF_FF)
+	// memory fetch (all I-type)
+	// we do the load for stores also
+	mem := uint32(0)
+	if opcode >= 0x20 {
+		// M[R[rs]+SignExtImm]
+		rs += SE(insn&0xFFFF, 16)
+		addr := rs & 0xFFFFFFFC
+		m.trackMemAccess(addr)
+		mem = m.state.Memory.GetMemory(addr)
+		if opcode >= 0x28 && opcode != 0x30 {
+			// store
+			storeAddr = addr
+			// store opcodes don't write back to a register
+			rdReg = 0
+		}
+	}
+
+	// ALU
+	val := execute(insn, rs, rt, mem)
+
+	fun := insn & 0x3f // 6-bits
+	if opcode == 0 && fun >= 8 && fun < 0x1c {
+		if fun == 8 || fun == 9 { // jr/jalr
+			linkReg := uint32(0)
+			if fun == 9 {
+				linkReg = rdReg
+			}
+			return m.handleJump(linkReg, rs)
+		}
+
+		if fun == 0xa { // movz
+			return m.handleRd(rdReg, rs, rt == 0)
+		}
+		if fun == 0xb { // movn
+			return m.handleRd(rdReg, rs, rt != 0)
+		}
+
+		// syscall (can read and write)
+		if fun == 0xC {
+			return m.handleSyscall()
+		}
+
+		// lo and hi registers
+		// can write back
+		if fun >= 0x10 && fun < 0x1c {
+			return m.handleHiLo(fun, rs, rt, rdReg)
+		}
+	}
+
+	// stupid sc, write a 1 to rt
+	if opcode == 0x38 && rtReg != 0 {
+		m.state.Registers[rtReg] = 1
+	}
+
+	// write memory
+	if storeAddr != 0xFF_FF_FF_FF {
+		m.trackMemAccess(storeAddr)
+		m.state.Memory.SetMemory(storeAddr, val)
+	}
+
+	// write back the value to destination register
+	return m.handleRd(rdReg, val, true)
+}
+
+func execute(insn uint32, rs uint32, rt uint32, mem uint32) uint32 {
+	opcode := insn >> 26 // 6-bits
+	fun := insn & 0x3f   // 6-bits
+	// TODO: deref the immed into a register
+
+	if opcode < 0x20 {
+		// transform ArithLogI
+		// TODO: replace with table
+		if opcode >= 8 && opcode < 0xF {
+			switch opcode {
+			case 8:
+				fun = 0x20 // addi
+			case 9:
+				fun = 0x21 // addiu
+			case 0xA:
+				fun = 0x2A // slti
+			case 0xB:
+				fun = 0x2B // sltiu
+			case 0xC:
+				fun = 0x24 // andi
+			case 0xD:
+				fun = 0x25 // ori
+			case 0xE:
+				fun = 0x26 // xori
+			}
+			opcode = 0
+		}
+
+		// 0 is opcode SPECIAL
+		if opcode == 0 {
+			shamt := (insn >> 6) & 0x1F
+			if fun < 0x20 {
+				switch {
+				case fun >= 0x08:
+					return rs // jr/jalr/div + others
+				case fun == 0x00:
+					return rt << shamt // sll
+				case fun == 0x02:
+					return rt >> shamt // srl
+				case fun == 0x03:
+					return SE(rt>>shamt, 32-shamt) // sra
+				case fun == 0x04:
+					return rt << (rs & 0x1F) // sllv
+				case fun == 0x06:
+					return rt >> (rs & 0x1F) // srlv
+				case fun == 0x07:
+					return SE(rt>>rs, 32-rs) // srav
+				}
+			}
+			// 0x10-0x13 = mfhi, mthi, mflo, mtlo
+			// R-type (ArithLog)
+			switch fun {
+			case 0x20, 0x21:
+				return rs + rt // add or addu
+			case 0x22, 0x23:
+				return rs - rt // sub or subu
+			case 0x24:
+				return rs & rt // and
+			case 0x25:
+				return rs | rt // or
+			case 0x26:
+				return rs ^ rt // xor
+			case 0x27:
+				return ^(rs | rt) // nor
+			case 0x2A:
+				if int32(rs) < int32(rt) {
+					return 1 // slt
+				} else {
+					return 0
+				}
+			case 0x2B:
+				if rs < rt {
+					return 1 // sltu
+				} else {
+					return 0
+				}
+			}
+		} else if opcode == 0xF {
+			return rt << 16 // lui
+		} else if opcode == 0x1C { // SPECIAL2
+			if fun == 2 { // mul
+				return uint32(int32(rs) * int32(rt))
+			}
+			if fun == 0x20 || fun == 0x21 { // clo
+				if fun == 0x20 {
+					rs = ^rs
+				}
+				i := uint32(0)
+				for ; rs&0x80000000 != 0; i++ {
+					rs <<= 1
+				}
+				return i
+			}
+		}
+	} else if opcode < 0x28 {
+		switch opcode {
+		case 0x20: // lb
+			return SE((mem>>(24-(rs&3)*8))&0xFF, 8)
+		case 0x21: // lh
+			return SE((mem>>(16-(rs&2)*8))&0xFFFF, 16)
+		case 0x22: // lwl
+			val := mem << ((rs & 3) * 8)
+			mask := uint32(0xFFFFFFFF) << ((rs & 3) * 8)
+			return (rt & ^mask) | val
+		case 0x23: // lw
+			return mem
+		case 0x24: // lbu
+			return (mem >> (24 - (rs&3)*8)) & 0xFF
+		case 0x25: // lhu
+			return (mem >> (16 - (rs&2)*8)) & 0xFFFF
+		case 0x26: // lwr
+			val := mem >> (24 - (rs&3)*8)
+			mask := uint32(0xFFFFFFFF) >> (24 - (rs&3)*8)
+			return (rt & ^mask) | val
+		}
+	} else if opcode == 0x28 { // sb
+		val := (rt & 0xFF) << (24 - (rs&3)*8)
+		mask := 0xFFFFFFFF ^ uint32(0xFF<<(24-(rs&3)*8))
+		return (mem & mask) | val
+	} else if opcode == 0x29 { // sh
+		val := (rt & 0xFFFF) << (16 - (rs&2)*8)
+		mask := 0xFFFFFFFF ^ uint32(0xFFFF<<(16-(rs&2)*8))
+		return (mem & mask) | val
+	} else if opcode == 0x2a { // swl
+		val := rt >> ((rs & 3) * 8)
+		mask := uint32(0xFFFFFFFF) >> ((rs & 3) * 8)
+		return (mem & ^mask) | val
+	} else if opcode == 0x2b { // sw
+		return rt
+	} else if opcode == 0x2e { // swr
+		val := rt << (24 - (rs&3)*8)
+		mask := uint32(0xFFFFFFFF) << (24 - (rs&3)*8)
+		return (mem & ^mask) | val
+	} else if opcode == 0x30 {
+		return mem // ll
+	} else if opcode == 0x38 {
+		return rt // sc
+	}
+
+	panic("invalid instruction")
+}
+
+func SE(dat uint32, idx uint32) uint32 {
+	isSigned := (dat >> (idx - 1)) != 0
+	signed := ((uint32(1) << (32 - idx)) - 1) << idx
+	mask := (uint32(1) << idx) - 1
+	if isSigned {
+		return dat&mask | signed
+	} else {
+		return dat & mask
+	}
+}

cannon/mipsevm/open_mips_tests/LICENSE

+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

cannon/mipsevm/open_mips_tests/README.md

+# OpenMIPS test vectors
+
+Tests from https://github.com/grantae/OpenMIPS/tree/d606b35e9d5260aef20de2a58660c8303a681e9c/software/test/macro/tests
+
+OpenMIPS is licensed LGPLv3 (as seen in the root of the repository), see [`LICENSE`](./LICENSE) file.
+Note that some build-system files from 2014/2015 in that repository by the same author are marked as BSD licensed,
+but the build-system is not used here.
+
+Requires https://github.com/sergev/LiteBSD/releases/download/tools/gcc-4.8.1-mips-macosx.tgz to build
+

cannon/mipsevm/open_mips_tests/maketests.py

+#!/usr/bin/env python3
+import os
+import sys
+import tempfile
+from capstone import *
+from elftools.elf.elffile import ELFFile
+md = Cs(CS_ARCH_MIPS, CS_MODE_32 + CS_MODE_BIG_ENDIAN)
+
+def maketest(d, out):
+  with tempfile.NamedTemporaryFile() as nf:
+    path = "/Users/kafka/fun/mips/mips-gcc-4.8.1/bin/"
+    print("building", d, "->", out)
+    # which mips is go
+    ret = os.system("%s/mips-elf-as -defsym big_endian=1 -march=mips32r2 -o %s %s" % (path, nf.name, d))
+    assert(ret == 0)
+    nf.seek(0)
+    elffile = ELFFile(nf)
+    #print(elffile)
+    for sec in elffile.iter_sections():
+      #print(sec, sec.name, sec.data())
+      if sec.name == ".test":
+        with open(out, "wb") as f:
+          # jump to 0xdead0000 when done
+          #data = b"\x24\x1f\xde\xad\x00\x1f\xfc\x00" + sec.data()
+          data = sec.data()
+          for dd in md.disasm(data, 0):
+            print(dd)
+          f.write(data)
+
+if __name__ == "__main__":
+  os.makedirs("/tmp/mips", exist_ok=True)
+  if len(sys.argv) > 2:
+    maketest(sys.argv[1], sys.argv[2])
+  else:
+    for d in os.listdir("test/"):
+      if not d.endswith(".asm"):
+        continue
+      maketest("test/"+d, "test/bin/"+(d.replace(".asm", ".bin")))
\ No newline at end of file

cannon/mipsevm/open_mips_tests/test/add.asm

+###############################################################################
+# File         : add.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'add' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff         # A = 0xfffffffd (-3)
+    ori     $t0, 0xfffd
+    ori     $t1, $0, 0x3        # B = 0x3
+    add     $t2, $t0, $t1       # C = A + B = 0
+    sltiu   $v0, $t2, 1         # D = 1 if C == 0
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/addi.asm

+###############################################################################
+# File         : addi.asm
+# Project      : MIPS32 MUX
+# Author       : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'addi' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff         # A = 0xfffffffd (-3)
+    ori     $t0, 0xfffd
+    addi    $t1, $t0, 5         # B = A + 5 = 2
+    addi    $t2, $t1, 0xfffe    # C = B + -2 = 0
+    sltiu   $v0, $t2, 1         # D = 1 if C == 0
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/addiu.asm

+###############################################################################
+# File         : addiu.asm
+# Project      : MIPS32 MUX
+# Author       : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'addiu' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff         # A = 0xfffffffd (-3)
+    ori     $t0, 0xfffd
+    addiu   $t1, $t0, 5         # B = A + 5 = 2
+    addiu   $t2, $t1, 0xfffe    # C = B + -2 = 0
+    sltiu   $v0, $t2, 1         # D = 1 if C == 0
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/addu.asm

+###############################################################################
+# File         : addu.asm
+# Project      : MIPS32 MUX
+# Author       : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'addu' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff         # A = 0xfffffffd (-3)
+    ori     $t0, 0xfffd
+    ori     $t1, $0, 0x3        # B = 0x3
+    addu    $t2, $t0, $t1       # C = A + B = 0
+    sltiu   $v0, $t2, 1         # D = 1 if C == 0
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/and.asm

+###############################################################################
+# File         : and.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'and' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf         # A = 0xdeafbeef
+    lui     $t1, 0xaaaa         # B = 0xaaaaaaaa
+    lui     $t2, 0x5555         # C = 0x55555555
+    ori     $t0, 0xbeef
+    ori     $t1, 0xaaaa
+    ori     $t2, 0x5555
+    and     $t3, $t0, $t1       # D = A & B = 0x8aaaaaaa
+    and     $t4, $t2, $t3       # E = B & D = 0
+    sltiu   $v0, $t4, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/andi.asm

+###############################################################################
+# File         : andi.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'andi' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $t0, $0,  0xcafe    # A = 0xcafe
+    andi    $t1, $t0, 0xaaaa    # B = A & 0xaaaa = 0x8aaa
+    andi    $t2, $t1, 0x5555    # C = B & 0x5555 = 0
+    sltiu   $v0, $t2, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/beq.asm

+###############################################################################
+# File         : beq.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'beq' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $t0, $0,  0xcafe
+    ori     $t1, $0,  0xcafe
+    ori     $v0, $0,  0         # The test result starts as a failure
+    beq     $t0, $v0, $finish   # No branch
+    nop
+    beq     $t0, $t1, $target
+    nop
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+
+$done:
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 branch detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    beq     $0, $0, $finish     # Late-by-1 branch detection (result not stored)
+    nop
+    j       $finish
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/bgez.asm

+###############################################################################
+# File         : bgez.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'bgez' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff
+    bgez    $t0, $finish        # No branch
+    nop
+    bgez    $s1, $target
+    nop
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+
+$done:
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 branch detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    bgez    $0, $finish         # Late-by-1 branch detection (result not stored)
+    nop
+    j       $finish             # Broken branch recovery
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/bgtz.asm

+###############################################################################
+# File         : bgtz.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'bgtz' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $v0, $0, 0          # The test result starts as a failure
+    lui     $t0, 0xffff
+    bgtz    $t0, $finish        # No branch
+    nop
+    bgtz    $s1, $target
+    nop
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+
+$done:
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 branch detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    bgtz    $s1, $finish        # Late-by-1 branch detection (result not stored)
+    nop
+    j       $finish             # Broken branch recovery
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/blez.asm

+###############################################################################
+# File         : blez.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'blez' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $v0, $0, 0          # The test result starts as a failure
+    blez    $s1, $finish        # No branch
+    lui     $t0, 0xffff
+    blez    $t0, $target
+    nop
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+
+$done:
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 branch detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    blez    $0, $finish         # Late-by-1 branch detection (result not stored)
+    nop
+    j       $finish
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/bltz.asm

+###############################################################################
+# File         : bltz.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'bltz' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $v0, $0, 0          # The test result starts as a failure
+    bltz    $0, $finish         # No branch
+    nop
+    bltz    $s1, $finish        # No branch
+    lui     $t0, 0xffff
+    bltz    $t0, $target
+    nop
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+
+$done:
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 branch detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    bltz    $t0, $finish        # Late-by-1 branch detection (result not stored)
+    nop
+    j       $finish             # Broken branch recovery
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/bne.asm

+###############################################################################
+# File         : bne.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'bne' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $t0, $0,  0xcafe
+    ori     $t1, $0,  0xcafe
+    ori     $v0, $0,  0         # The test result starts as a failure
+    bne     $t0, $t1, $finish   # No branch
+    nop
+    bne     $t0, $v0, $target
+    nop
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+
+$done:
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 branch detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    bne     $t0, $0, $finish    # Late-by-1 branch detection (result not stored)
+    nop
+    j       $finish
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/clo.asm

+###############################################################################
+# File         : clo.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'clo' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t2, 0xffff         # 32
+    ori     $t2, 0xffff
+    lui     $t3, 0xffff         # 18
+    ori     $t3, 0xc000
+    lui     $t4, 0xf800         # 5
+    lui     $t5, 0xf000         # 4
+    lui     $t6, 0x7fff         # 0
+    ori     $t7, $0, 0          # 0
+    clo     $s2, $t2
+    clo     $s3, $t3
+    clo     $s4, $t4
+    clo     $s5, $t5
+    clo     $s6, $t6
+    clo     $s7, $t7
+    addiu   $s2, -32
+    addiu   $s3, -18
+    addiu   $s4, -5
+    addiu   $s5, -4
+    addiu   $s6, 0
+    addiu   $s7, 0
+    or      $v1, $s2, $s3
+    or      $v1, $v1, $s4
+    or      $v1, $v1, $s5
+    or      $v1, $v1, $s6
+    or      $v1, $v1, $s7
+    sltiu   $v0, $v1, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/clz.asm

+###############################################################################
+# File         : clz.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'clz' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t2, 0xffff         # 0
+    ori     $t2, 0xffff
+    ori     $t3, $0, 0x0100     # 23
+    lui     $t4, 0x0700         # 5
+    lui     $t5, 0x0f00         # 4
+    lui     $t6, 0x7fff         # 1
+    ori     $t7, $0, 0          # 32
+    clz     $s2, $t2
+    clz     $s3, $t3
+    clz     $s4, $t4
+    clz     $s5, $t5
+    clz     $s6, $t6
+    clz     $s7, $t7
+    addiu   $s2, 0
+    addiu   $s3, -23
+    addiu   $s4, -5
+    addiu   $s5, -4
+    addiu   $s6, -1
+    addiu   $s7, -32
+    or      $v1, $s2, $s3
+    or      $v1, $v1, $s4
+    or      $v1, $v1, $s5
+    or      $v1, $v1, $s6
+    or      $v1, $v1, $s7
+    sltiu   $v0, $v1, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/div.asm

+###############################################################################
+# File         : div.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'div' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0x1234
+    ori     $t0, 0x5678
+    lui     $t1, 0xc001
+    ori     $t1, 0xcafe
+    div     $t1, $t0            # 0xfffffffd (q), 0xf69ece66 (r)
+    mfhi    $t2
+    mflo    $t3
+    lui     $t4, 0xf69e
+    ori     $t4, 0xce66
+    lui     $t5, 0xffff
+    ori     $t5, 0xfffd
+    subu    $t6, $t2, $t4
+    subu    $t7, $t3, $t5
+    sltiu   $v0, $t6, 1
+    sltiu   $v1, $t7, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/divu.asm

+###############################################################################
+# File         : divu.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'divu' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0x1234
+    ori     $t0, 0x5678
+    lui     $t1, 0xc001
+    ori     $t1, 0xcafe
+    divu    $t1, $t0            # 0xa (q), 0x09f66a4e (r)
+    mfhi    $t2
+    mflo    $t3
+    lui     $t4, 0x09f6
+    ori     $t4, 0x6a4e
+    lui     $t5, 0x0000
+    ori     $t5, 0x000a
+    subu    $t6, $t2, $t4
+    subu    $t7, $t3, $t5
+    sltiu   $v0, $t6, 1
+    sltiu   $v1, $t7, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/j.asm

+###############################################################################
+# File         : j.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'j' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    j       $target
+    ori     $v0, $0, 0          # The test result starts as a failure
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    j       $finish             # Late-by 1 detection (result not written)
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/jal.asm

+###############################################################################
+# File         : jal.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'jal' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $v1, $ra, 0         # Save $ra
+    jal     $target
+    ori     $v0, $0, 0          # The test result starts as a failure
+
+$finish:
+    sw      $v0, 8($s0)
+    ori     $ra, $v1, 0         # Restore $ra
+    sw      $s1, 4($s0)
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    jr      $ra
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/jalr.asm

+###############################################################################
+# File         : jalr.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'jalr' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $v1, $ra, 0         # Save $ra
+    la      $t0, $target
+    jalr    $t0
+    ori     $v0, $0, 0          # The test result starts as a failure
+
+$finish:
+    sw      $v0, 8($s0)
+    ori     $ra, $v1, 0         # Restore $ra
+    sw      $s1, 4($s0)
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    jr      $ra
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/jr.asm

+###############################################################################
+# File         : jr.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'jr' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    la      $t0, $target
+    jr      $t0
+    ori     $v0, $0, 0          # The test result starts as a failure
+
+$finish:
+    sw      $v0, 8($s0)
+    sw      $s1, 4($s0)
+    jr      $ra
+    nop
+    j       $finish             # Early-by-1 detection
+
+$target:
+    nop
+    ori     $v0, $0, 1          # Set the result to pass
+    j       $finish
+    nop
+
+    #### Test code end ####
+
+    .end test

cannon/mipsevm/open_mips_tests/test/lb.asm

+###############################################################################
+# File         : lb.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'lb' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xbfc0         # Load address 0xbfc007fc (last word in 2KB starting
+    ori     $t0, 0x07fc         #  from 0xbfc00000)
+    lui     $t1, 0xc001
+    ori     $t1, 0x7afe
+    sw      $t1, 0($t0)
+    lb      $t2, 0($t0)
+    lb      $t3, 1($t0)
+    lb      $t4, 2($t0)
+    lb      $t5, 3($t0)
+    .ifdef big_endian
+    lui     $t6, 0xffff
+    ori     $t6, 0xffc0
+    lui     $t7, 0x0000
+    ori     $t7, 0x0001
+    lui     $t8, 0x0000
+    ori     $t8, 0x007a
+    lui     $t9, 0xffff
+    ori     $t9, 0xfffe
+    .else
+    lui     $t6, 0xffff
+    ori     $t6, 0xfffe
+    lui     $t7, 0x0000
+    ori     $t7, 0x007a
+    lui     $t8, 0x0000
+    ori     $t8, 0x0001
+    lui     $t9, 0xffff
+    ori     $t9, 0xffc0
+    .endif
+    subu    $v1, $t2, $t6
+    sltiu   $v0, $v1, 1
+    subu    $v1, $t3, $t7
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+    subu    $v1, $t4, $t8
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+    subu    $v1, $t5, $t9
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+
+    # Repeat with halves swapped (sign extension corner cases)
+    lui     $t1, 0x7afe
+    ori     $t1, 0xc001
+    sw      $t1, 0($t0)
+    lb      $t2, 0($t0)
+    lb      $t3, 1($t0)
+    lb      $t4, 2($t0)
+    lb      $t5, 3($t0)
+    .ifdef big_endian
+    lui     $t6, 0x0000
+    ori     $t6, 0x007a
+    lui     $t7, 0xffff
+    ori     $t7, 0xfffe
+    lui     $t8, 0xffff
+    ori     $t8, 0xffc0
+    lui     $t9, 0x0000
+    ori     $t9, 0x0001
+    .else
+    lui     $t6, 0x0000
+    ori     $t6, 0x0001
+    lui     $t7, 0xffff
+    ori     $t7, 0xffc0
+    lui     $t8, 0xffff
+    ori     $t8, 0xfffe
+    lui     $t9, 0x0000
+    ori     $t9, 0x007a
+    .endif
+    subu    $v1, $t2, $t6
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+    subu    $v1, $t3, $t7
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+    subu    $v1, $t4, $t8
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+    subu    $v1, $t5, $t9
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/lbu.asm

+###############################################################################
+# File         : lbu.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'lbu' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xbfc0         # Load address 0xbfc007fc (last word in 2KB starting
+    ori     $t0, 0x07fc         #  from 0xbfc00000)
+    lui     $t1, 0xc001
+    ori     $t1, 0x7afe
+    sw      $t1, 0($t0)
+    lbu     $t2, 0($t0)
+    lbu     $t3, 1($t0)
+    lbu     $t4, 2($t0)
+    lbu     $t5, 3($t0)
+    .ifdef big_endian
+    ori     $t6, $0, 0x00c0
+    ori     $t7, $0, 0x0001
+    ori     $t8, $0, 0x007a
+    ori     $t9, $0, 0x00fe
+    .else
+    ori     $t6, $0, 0x00fe
+    ori     $t7, $0, 0x007a
+    ori     $t8, $0, 0x0001
+    ori     $t9, $0, 0x00c0
+    .endif
+    subu    $v1, $t2, $t6
+    sltiu   $v0, $v1, 1
+    subu    $v1, $t3, $t7
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+    subu    $v1, $t4, $t8
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+    subu    $v1, $t5, $t9
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/lh.asm

+###############################################################################
+# File         : lh.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'lh' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xbfc0         # Load address 0xbfc007fc (last word in 2KB starting
+    ori     $t0, 0x07fc         #  from 0xbfc00000)
+    lui     $t1, 0x7001
+    ori     $t1, 0xcafe
+    sw      $t1, 0($t0)
+    lh      $t2, 0($t0)
+    lh      $t3, 2($t0)
+    .ifdef big_endian
+    lui     $t4, 0x0000
+    ori     $t4, 0x7001
+    lui     $t5, 0xffff
+    ori     $t5, 0xcafe
+    .else
+    lui     $t4, 0xffff
+    ori     $t4, 0xcafe
+    lui     $t5, 0x0000
+    ori     $t5, 0x7001
+    .endif
+    subu    $v1, $t2, $t4
+    sltiu   $v0, $v1, 1
+    subu    $v1, $t3, $t5
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+
+    # Repeat with halves swapped (sign extension corner cases)
+    lui     $t1, 0xcafe
+    ori     $t1, 0x7001
+    sw      $t1, 0($t0)
+    lh      $t2, 0($t0)
+    lh      $t3, 2($t0)
+    .ifdef big_endian
+    lui     $t4, 0xffff
+    ori     $t4, 0xcafe
+    lui     $t5, 0x0000
+    ori     $t5, 0x7001
+    .else
+    lui     $t4, 0x0000
+    ori     $t4, 0x7001
+    lui     $t5, 0xffff
+    ori     $t5, 0xcafe
+    .endif
+    subu    $v1, $t2, $t4
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+    subu    $v1, $t3, $t5
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/lhu.asm

+###############################################################################
+# File         : lhu.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'lhu' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xbfc0         # Load address 0xbfc007fc (last word in 2KB starting
+    ori     $t0, 0x07fc         #  from 0xbfc00000)
+    lui     $t1, 0x7001
+    ori     $t1, 0xcafe
+    sw      $t1, 0($t0)
+    lhu     $t2, 0($t0)
+    lhu     $t3, 2($t0)
+    .ifdef big_endian
+    ori     $t4, $0, 0x7001
+    ori     $t5, $0, 0xcafe
+    .else
+    ori     $t4, $0, 0xcafe
+    ori     $t5, $0, 0x7001
+    .endif
+    subu    $v1, $t2, $t4
+    sltiu   $v0, $v1, 1
+    subu    $v1, $t3, $t5
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+
+    # Repeat with halves swapped (sign extension corner cases)
+    lui     $t1, 0xcafe
+    ori     $t1, 0x7001
+    sw      $t1, 0($t0)
+    lhu     $t2, 0($t0)
+    lhu     $t3, 2($t0)
+    .ifdef big_endian
+    ori     $t4, $0, 0xcafe
+    ori     $t5, $0, 0x7001
+    .else
+    ori     $t4, $0, 0x7001
+    ori     $t5, $0, 0xcafe
+    .endif
+    subu    $v1, $t2, $t4
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+    subu    $v1, $t3, $t5
+    sltiu   $v1, $v1, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/lui.asm

+###############################################################################
+# File         : lui.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'lui' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $v0, $0, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/lw.asm

+###############################################################################
+# File         : lw.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'lw' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xbfc0         # Load a valid address (last word in 2KB starting
+    ori     $t0, 0x07fc         #  from 0xbfc00000)
+    sw      $0,  0($t0)
+    ori     $t1, $0, 1
+    sw      $t1, 0($t0)
+    lw      $v0, 0($t0)
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/lwl.asm

+###############################################################################
+# File         : lwl.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'lwl' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xbfc0         # Load address 0xbfc007fc (last word in 2KB starting
+    ori     $t0, 0x07fc         # from 0xbfc00000)
+    lui     $t1, 0xc001         # Memory word is 0xc001cafe
+    ori     $t1, 0xcafe
+    sw      $t1, 0($t0)
+    lui     $t2, 0xdeaf         # Register word is 0xdeafbeef
+    ori     $t2, 0xbeef
+    or      $t3, $0, $t2
+    or      $t4, $0, $t2
+    or      $t5, $0, $t2
+    or      $t6, $0, $t2
+    lwl     $t3, 0($t0)
+    lwl     $t4, 1($t0)
+    lwl     $t5, 2($t0)
+    lwl     $t6, 3($t0)
+    .ifdef big_endian
+    lui     $s3, 0xc001         # 0xc001cafe
+    ori     $s3, 0xcafe
+    lui     $s4, 0x01ca         # 0x01cafeef
+    ori     $s4, 0xfeef
+    lui     $s5, 0xcafe         # 0xcafebeef
+    ori     $s5, 0xbeef
+    lui     $s6, 0xfeaf         # 0xfeafbeef
+    ori     $s6, 0xbeef
+    .else
+    lui     $s3, 0xfeaf         # 0xfeafbeef
+    ori     $s3, 0xbeef
+    lui     $s4, 0xcafe         # 0xcafebeef
+    ori     $s4, 0xbeef
+    lui     $s5, 0x01ca         # 0x01cafeef
+    ori     $s5, 0xfeef
+    lui     $s6, 0xc001         # 0xc001cafe
+    ori     $s6, 0xcafe
+    .endif
+    subu    $s2, $t3, $s3
+    sltiu   $v0, $s2, 1
+    subu    $s2, $t4, $s4
+    sltiu   $v1, $s2, 1
+    and     $v0, $v0, $v1
+    subu    $s2, $t5, $s5
+    sltiu   $v1, $s2, 1
+    and     $v0, $v0, $v1
+    subu    $s2, $t6, $s6
+    sltiu   $v1, $s2, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/lwr.asm

+###############################################################################
+# File         : lwr.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'lwr' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xbfc0         # Load address 0xbfc007fc (last word in 2KB starting
+    ori     $t0, 0x07fc         # from 0xbfc00000)
+    lui     $t1, 0xc001         # Memory word is 0xc001cafe
+    ori     $t1, 0xcafe
+    sw      $t1, 0($t0)
+    lui     $t2, 0xdeaf         # Register word is 0xdeafbeef
+    ori     $t2, 0xbeef
+    or      $t3, $0, $t2
+    or      $t4, $0, $t2
+    or      $t5, $0, $t2
+    or      $t6, $0, $t2
+    lwr     $t3, 0($t0)
+    lwr     $t4, 1($t0)
+    lwr     $t5, 2($t0)
+    lwr     $t6, 3($t0)
+    .ifdef big_endian
+    lui     $s3, 0xdeaf         # 0xdeafbec0
+    ori     $s3, 0xbec0
+    lui     $s4, 0xdeaf         # 0xdeafc001
+    ori     $s4, 0xc001
+    lui     $s5, 0xdec0         # 0xdec001ca
+    ori     $s5, 0x01ca
+    lui     $s6, 0xc001         # 0xc001cafe
+    ori     $s6, 0xcafe
+    .else
+    lui     $s3, 0xc001         # 0xc001cafe
+    ori     $s3, 0xcafe
+    lui     $s4, 0xdec0         # 0xdec001ca
+    ori     $s4, 0x01ca
+    lui     $s5, 0xdeaf         # 0xdeafc001
+    ori     $s5, 0xc001
+    lui     $s6, 0xdeaf         # 0xdeafbec0
+    ori     $s6, 0xbec0
+    .endif
+    subu    $s2, $t3, $s3
+    sltiu   $v0, $s2, 1
+    subu    $s2, $t4, $s4
+    sltiu   $v1, $s2, 1
+    and     $v0, $v0, $v1
+    subu    $s2, $t5, $s5
+    sltiu   $v1, $s2, 1
+    and     $v0, $v0, $v1
+    subu    $s2, $t6, $s6
+    sltiu   $v1, $s2, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/mfthi.asm

+###############################################################################
+# File         : mfthi.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'mthi' and 'mfhi' instructions.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf
+    ori     $t0, 0xbeef
+    mthi    $t0
+    mfhi    $t1
+    subu    $v1, $t0, $t1
+    sltiu   $v0, $v1, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/mftlo.asm

+###############################################################################
+# File         : mftlo.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'mtlo' and 'mflo' instructions.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf
+    ori     $t0, 0xbeef
+    mtlo    $t0
+    mflo    $t1
+    subu    $v1, $t0, $t1
+    sltiu   $v0, $v1, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/movn.asm

+###############################################################################
+# File         : movn.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'movn' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf
+    ori     $t0, $t0, 0xbeef
+    ori     $t1, $0, 0
+    movn    $t2, $t0, $s1       # $t2 gets 0xdeafbeef
+    movn    $t1, $t0, $0        # $t1 remains 0
+    subu    $t3, $t2, $t0
+    sltiu   $v0, $t3, 1
+    sltiu   $v1, $t1, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/movz.asm

+###############################################################################
+# File         : movz.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'movz' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf
+    ori     $t0, $t0, 0xbeef
+    ori     $t2, $0, 0
+    movz    $t2, $t0, $s0       # $t2 remains 0
+    movz    $t1, $t0, $0        # $t1 gets 0xdeafbeef
+    subu    $t3, $t1, $t0
+    sltiu   $v0, $t3, 1
+    sltiu   $v1, $t2, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/mul.asm

+###############################################################################
+# File         : mul.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'mul' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0x1234
+    ori     $t0, 0x5678
+    lui     $t1, 0xc001
+    ori     $t1, 0xcafe
+    mul     $t2, $t0, $t1       # 0xb2a07b10
+    lui     $t3, 0xb2a0
+    ori     $t3, 0x7b10
+    subu    $t4, $t2, $t3
+    sltiu   $v0, $t4, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/mult.asm

+###############################################################################
+# File         : mult.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'mult' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0x1234
+    ori     $t0, 0x5678
+    lui     $t1, 0xc001
+    ori     $t1, 0xcafe
+    mult    $t0, $t1            # 0xfb730b05b2a07b10
+    mfhi    $t2
+    mflo    $t3
+    lui     $t4, 0xfb73
+    ori     $t4, 0x0b05
+    lui     $t5, 0xb2a0
+    ori     $t5, 0x7b10
+    subu    $t6, $t2, $t4
+    subu    $t7, $t3, $t5
+    sltiu   $v0, $t6, 1
+    sltiu   $v1, $t7, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/multu.asm

+###############################################################################
+# File         : multu.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'multu' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0x1234
+    ori     $t0, 0x5678
+    lui     $t1, 0xc001
+    ori     $t1, 0xcafe
+    multu   $t0, $t1            # 0x0da7617db2a07b10
+    mfhi    $t2
+    mflo    $t3
+    lui     $t4, 0x0da7
+    ori     $t4, 0x617d
+    lui     $t5, 0xb2a0
+    ori     $t5, 0x7b10
+    subu    $t6, $t2, $t4
+    subu    $t7, $t3, $t5
+    sltiu   $v0, $t6, 1
+    sltiu   $v1, $t7, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/nor.asm

+###############################################################################
+# File         : nor.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'nor' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf         # A = 0xdeafbeef
+    ori     $t0, $t0, 0xbeef
+    lui     $t1, 0x3141         # B = 0x31415926
+    ori     $t1, $t1, 0x5926
+    lui     $t2, 0xffff         # C = 0xfffffffe
+    ori     $t2, $t2, 0xfffe
+    nor     $t3, $t0, $t1       # D = nor(A,B) = 0x00100010
+    nor     $v0, $t2, $t3       # E = nor(C,D) = 0x1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/oracle.asm

+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+
+# load hash at 0x30001000
+# 0x47173285 a8d7341e 5e972fc6 77286384 f802f8ef 42a5ec5f 03bbfa25 4cb01fad = "hello world"
+test:
+  lui $s0, 0x3000
+  ori $s0, 0x1000
+
+  lui $t0, 0x4717
+  ori $t0, 0x3285
+  sw $t0, 0($s0)
+  lui $t0, 0xa8d7
+  ori $t0, 0x341e
+  sw $t0, 4($s0)
+  lui $t0, 0x5e97
+  ori $t0, 0x2fc6
+  sw $t0, 8($s0)
+  lui $t0, 0x7728
+  ori $t0, 0x6384
+  sw $t0, 0xc($s0)
+  lui $t0, 0xf802
+  ori $t0, 0xf8ef
+  sw $t0, 0x10($s0)
+  lui $t0, 0x42a5
+  ori $t0, 0xec5f
+  sw $t0, 0x14($s0)
+  lui $t0, 0x03bb
+  ori $t0, 0xfa25
+  sw $t0, 0x18($s0)
+  lui $t0, 0x4cb0
+  ori $t0, 0x1fad
+  sw $t0, 0x1c($s0)
+
+# syscall 4020 to trigger
+  li $v0, 4020
+  syscall
+
+# length at 0x31000000
+  lui $s1, 0x3100
+  lw $t0, 0($s1)
+
+# should be len("hello world") == 11
+  li $t4, 11
+  subu $t5, $t0, $t4
+  sltiu $v0, $t5, 1 
+
+# data at 0x31000004
+  lw $t0, 4($s1)
+  lui $t4, 0x6865
+  ori $t4, 0x6c6c
+  subu $t5, $t0, $t4
+  sltiu $v1, $t5, 1
+
+  and $v0, $v0, $v1
+
+# save results
+  lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+  ori     $s0, 0xfff0
+  ori     $s1, $0, 1          # Prepare the 'done' status
+
+  sw      $v0, 8($s0)         # Set the test result
+  sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+  jr      $ra
+  nop
+
+  .end test

cannon/mipsevm/open_mips_tests/test/ori.asm

+###############################################################################
+# File         : ori.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'ori' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $v0, $s1, 0
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/sb.asm

+###############################################################################
+# File         : sb.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'sb' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xbfc0         # Load address 0xbfc007fc (last word in 2KB starting
+    ori     $t0, 0x07fc         #  from 0xbfc00000)
+    sw      $0,  0($t0)
+    ori     $t1, $0, 0xc0
+    ori     $t2, $0, 0x01
+    ori     $t3, $0, 0xca
+    ori     $t4, $0, 0xfe
+    sb      $t1, 0($t0)
+    sb      $t2, 1($t0)
+    sb      $t3, 2($t0)
+    sb      $t4, 3($t0)
+    lw      $t5, 0($t0)
+    .ifdef big_endian
+    lui     $t6, 0xc001
+    ori     $t6, 0xcafe
+    .else
+    lui     $t6, 0xfeca
+    ori     $t6, 0x01c0
+    .endif
+    subu    $t7, $t5, $t6
+    sltiu   $v0, $t7, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/sh.asm

+###############################################################################
+# File         : sh.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'sh' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xbfc0         # Load address 0xbfc007fc (last word in 2KB starting
+    ori     $t0, 0x07fc         #  from 0xbfc00000)
+    sw      $0,  0($t0)
+    ori     $t1, $0, 0xc001
+    ori     $t2, $0, 0xcafe
+    sh      $t1, 0($t0)
+    sh      $t2, 2($t0)
+    lw      $t3, 0($t0)
+    .ifdef big_endian
+    lui     $t4, 0xc001
+    ori     $t4, 0xcafe
+    .else
+    lui     $t4, 0xcafe
+    ori     $t4, 0xc001
+    .endif
+    subu    $t5, $t3, $t4
+    sltiu   $v0, $t5, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/sll.asm

+###############################################################################
+# File         : sll.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'sll' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf         # A = 0xdeafbeef
+    ori     $t0, 0xbeef
+    sll     $t1, $t0, 4         # B = 0xdeafbeef << 4 = 0xeafbeef0
+    lui     $t2, 0xeafb         # C = 0xeafbeef0
+    ori     $t2, 0xeef0
+    subu    $t3, $t1, $t2
+    sltiu   $v0, $t3, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/sllv.asm

+###############################################################################
+# File         : sllv.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'sllv' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf         # A = 0xdeafbeef
+    ori     $t0, 0xbeef
+    ori     $t1, $0, 12
+    sllv    $t2, $t0, $t1       # B = 0xdeafbeef << 12 = 0xfbeef000
+    lui     $t3, 0xfbee
+    ori     $t3, 0xf000
+    subu    $t4, $t2, $t3
+    sltiu   $v0, $t4, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/slt.asm

+###############################################################################
+# File         : slt.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'slt' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff
+    ori     $t0, 0xffff
+    slt     $v0, $t0, $s1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/slti.asm

+###############################################################################
+# File         : slti.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'slti' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0x8000
+    slti    $v0, $t0, 0xffff
+    slti    $v1, $t0, 0
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/sltiu.asm

+###############################################################################
+# File         : sltiu.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'sltiu' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0x8000
+    sltiu   $v0, $t0, 0xffff
+    sltiu   $v1, $0, 0xffff
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/sltu.asm

+###############################################################################
+# File         : sltu.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'sltu' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff
+    ori     $t0, 0xffff
+    sltu    $v0, $s1, $t0
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/sra.asm

+###############################################################################
+# File         : sra.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'sra' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf         # A = 0xdeafbeef
+    ori     $t0, 0xbeef
+    sra     $t1, $t0, 4         # B = 0xdeafbeef >> 4 = 0xfdeafbee
+    lui     $t2, 0xfdea         # C = 0xfdeafbee
+    ori     $t2, 0xfbee
+    subu    $t3, $t1, $t2       # D = B - C = 0
+    sltiu   $v0, $t3, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/srav.asm

+###############################################################################
+# File         : srav.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'srav' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf         # A = 0xdeafbeef
+    ori     $t0, 0xbeef
+    ori     $t1, $0, 12
+    srav    $t2, $t0, $t1       # B = 0xdeafbeef >> 12 = 0xfffdeafb
+    lui     $t3, 0xfffd
+    ori     $t3, 0xeafb
+    subu    $t4, $t2, $t3
+    sltiu   $v0, $t4, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/srl.asm

+###############################################################################
+# File         : srl.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'srl' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf         # A = 0xdeafbeef
+    ori     $t0, 0xbeef
+    srl     $t1, $t0, 4         # B = 0xdeafbeef >> 4 = 0x0deafbee
+    lui     $t2, 0x0dea
+    ori     $t2, 0xfbee
+    subu    $t3, $t1, $t2       # D = B - C = 0
+    sltiu   $v0, $t3, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/srlv.asm

+###############################################################################
+# File         : srlv.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'srlv' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf         # A = 0xdeafbeef
+    ori     $t0, 0xbeef
+    ori     $t1, $0, 12
+    srlv    $t2, $t0, $t1       # B = 0xdeafbeef >> 12 = 0x000deafb
+    lui     $t3, 0x000d
+    ori     $t3, 0xeafb
+    subu    $t4, $t2, $t3
+    sltiu   $v0, $t4, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/sub.asm

+###############################################################################
+# File         : sub.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'sub' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff         # A = 0xfffffffd (-3)
+    ori     $t0, 0xfffd
+    sub     $t1, $t0, $t0       # B = A - A = 0
+    sub     $t2, $t1, $t0       # C = B - A = 0 - A = 3
+    ori     $t3, $0, 3          # D = 2
+    sub     $t4, $t2, $t3       # E = C - D = C - 2 = 0
+    sltiu   $v0, $t4, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/subu.asm

+###############################################################################
+# File         : subu.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'subu' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xffff         # A = 0xfffffffd (-3)
+    ori     $t0, 0xfffd
+    ori     $t1, $0, 4          # B = 4
+    subu    $t2, $t0, $t1       # C = A - B = 0xfffffff9 (-7)
+    lui     $t3, 0xffff         # D = 0xfffffff8 (like -8 mod 2^32)
+    ori     $t3, 0xfff8
+    subu    $t4, $t2, $t3       # F = C - D = 1
+    subu    $t5, $t4, $s1       # G = F - 1 = 0
+    sltiu   $v0, $t5, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/swl.asm

+###############################################################################
+# File         : swl.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'swl' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xbfc0         # Load address 0xbfc007ec (last four words in 2KB starting
+    ori     $t0, 0x07ec         # from 0xbfc00000)
+    lui     $t1, 0xc001         # Memory word is 0xc001cafe
+    ori     $t1, 0xcafe
+    sw      $t1, 0($t0)
+    sw      $t1, 4($t0)
+    sw      $t1, 8($t0)
+    sw      $t1, 12($t0)
+    lui     $t2, 0xdeaf         # Register word is 0xdeafbeef
+    ori     $t2, 0xbeef
+    swl     $t2, 0($t0)
+    swl     $t2, 5($t0)
+    swl     $t2, 10($t0)
+    swl     $t2, 15($t0)
+    lw      $s2, 0($t0)
+    lw      $s3, 4($t0)
+    lw      $s4, 8($t0)
+    lw      $s5, 12($t0)
+    .ifdef big_endian
+    lui     $t3, 0xdeaf         # 0xdeafbeef
+    ori     $t3, 0xbeef
+    lui     $t4, 0xc0de         # 0xc0deafbe
+    ori     $t4, 0xafbe
+    lui     $t5, 0xc001         # 0xc001deaf
+    ori     $t5, 0xdeaf
+    lui     $t6, 0xc001         # 0xc001cade
+    ori     $t6, 0xcade
+    .else
+    lui     $t3, 0xc001         # 0xc001cade
+    ori     $t3, 0xcade
+    lui     $t4, 0xc001         # 0xc001deaf
+    ori     $t4, 0xdeaf
+    lui     $t5, 0xc0de         # 0xc0deafbe
+    ori     $t5, 0xafbe
+    lui     $t6, 0xdeaf         # 0xdeafbeef
+    ori     $t6, 0xbeef
+    .endif
+    subu    $t7, $s2, $t3
+    sltiu   $v0, $t7, 1
+    subu    $t7, $s3, $t4
+    sltiu   $v1, $t7, 1
+    and     $v0, $v0, $v1
+    subu    $t7, $s4, $t5
+    sltiu   $v1, $t7, 1
+    and     $v0, $v0, $v1
+    subu    $t7, $s5, $t6
+    sltiu   $v1, $t7, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/swr.asm

+###############################################################################
+# File         : swr.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'swr' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xbfc0         # Load address 0xbfc007ec (last four words in 2KB starting
+    ori     $t0, 0x07ec         # from 0xbfc00000)
+    lui     $t1, 0xc001         # Memory words are 0xc001cafe
+    ori     $t1, 0xcafe
+    sw      $t1, 0($t0)
+    sw      $t1, 4($t0)
+    sw      $t1, 8($t0)
+    sw      $t1, 12($t0)
+    lui     $t2, 0xdeaf         # Register word is 0xdeafbeef
+    ori     $t2, 0xbeef
+    swr     $t2, 0($t0)
+    swr     $t2, 5($t0)
+    swr     $t2, 10($t0)
+    swr     $t2, 15($t0)
+    lw      $s2, 0($t0)
+    lw      $s3, 4($t0)
+    lw      $s4, 8($t0)
+    lw      $s5, 12($t0)
+    .ifdef big_endian
+    lui     $t3, 0xef01         # 0xef01cafe
+    ori     $t3, 0xcafe
+    lui     $t4, 0xbeef         # 0xbeefcafe
+    ori     $t4, 0xcafe
+    lui     $t5, 0xafbe         # 0xafbeeffe
+    ori     $t5, 0xeffe
+    lui     $t6, 0xdeaf         # 0xdeafbeef
+    ori     $t6, 0xbeef
+    .else
+    lui     $t3, 0xdeaf         # 0xdeafbeef
+    ori     $t3, 0xbeef
+    lui     $t4, 0xafbe         # 0xafbeeffe
+    ori     $t4, 0xeffe
+    lui     $t5, 0xbeef         # 0xbeefcafe
+    ori     $t5, 0xcafe
+    lui     $t6, 0xef01         # 0xef01cafe
+    ori     $t6, 0xcafe
+    .endif
+    subu    $t7, $s2, $t3
+    sltiu   $v0, $t7, 1
+    subu    $t7, $s3, $t4
+    sltiu   $v1, $t7, 1
+    and     $v0, $v0, $v1
+    subu    $t7, $s4, $t5
+    sltiu   $v1, $t7, 1
+    and     $v0, $v0, $v1
+    subu    $t7, $s5, $t6
+    sltiu   $v1, $t7, 1
+    and     $v0, $v0, $v1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/xor.asm

+###############################################################################
+# File         : xor.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'xor' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    lui     $t0, 0xdeaf         # A = 0xdeafbeef
+    ori     $t0, 0xbeef
+    lui     $t1, 0x3141         # B = 0x31415926
+    ori     $t1, 0x5926
+    lui     $t2, 0xefee         # C = 0xefeee7c8
+    ori     $t2, 0xe7c8
+    xor     $t3, $t0, $t1       # D = xor(A,B) = 0xefeee7c8
+    xor     $t4, $t2, $t3       # E = xor(C,D) = 0x1
+    xor     $t5, $t4, $s1       # F = xor(E,1) = 0
+    sltiu   $v0, $t5, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/open_mips_tests/test/xori.asm

+###############################################################################
+# File         : xori.asm
+# Project      : MIPS32 MUX
+# Author:      : Grant Ayers (ayers@cs.stanford.edu)
+#
+# Standards/Formatting:
+#   MIPS gas, soft tab, 80 column
+#
+# Description:
+#   Test the functionality of the 'xori' instruction.
+#
+###############################################################################
+
+
+    .section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+test:
+    lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+    ori     $s0, 0xfff0
+    ori     $s1, $0, 1          # Prepare the 'done' status
+
+    #### Test code start ####
+
+    ori     $t0, $0, 0xdeaf     # A = 0xdeaf
+    xori    $t1, $t0, 0x3141    # B = xor(A, 0x3141) = 0xefee
+    xori    $t2, $t1, 0xefef    # C = xor(B, 0xefef) = 0x1
+    xori    $t3, $t2, 1         # D = xor(C, 1) = 0
+    sltiu   $v0, $t3, 1
+
+    #### Test code end ####
+
+    sw      $v0, 8($s0)         # Set the test result
+    sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+    jr      $ra
+    nop
+
+    .end test

cannon/mipsevm/page.go

+package mipsevm
+
+import (
+	"encoding/hex"
+	"fmt"
+
+	"github.com/ethereum/go-ethereum/crypto"
+)
+
+type Page [PageSize]byte
+
+func (p *Page) MarshalText() ([]byte, error) {
+	dst := make([]byte, hex.EncodedLen(len(p)))
+	hex.Encode(dst, p[:])
+	return dst, nil
+}
+
+func (p *Page) UnmarshalText(dat []byte) error {
+	if len(dat) != PageSize*2 {
+		return fmt.Errorf("expected %d hex chars, but got %d", PageSize*2, len(dat))
+	}
+	_, err := hex.Decode(p[:], dat)
+	return err
+}
+
+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 (p *CachedPage) Invalidate(pageAddr uint32) {
+	if pageAddr >= PageSize {
+		panic("invalid page addr")
+	}
+	k := (1 << PageAddrSize) | pageAddr
+	// first cache layer caches nodes that has two 32 byte leaf nodes.
+	k >>= 5 + 1
+	for k > 0 {
+		p.Ok[k] = false
+		k >>= 1
+	}
+}
+
+func (p *CachedPage) InvalidateFull() {
+	p.Ok = [PageSize / 32]bool{} // reset everything to false
+}
+
+func (p *CachedPage) MerkleRoot() [32]byte {
+	// hash the bottom layer
+	for i := uint64(0); i < PageSize; i += 64 {
+		j := PageSize/32/2 + i/64
+		if p.Ok[j] {
+			continue
+		}
+		p.Cache[j] = crypto.Keccak256Hash(p.Data[i : i+64])
+		//fmt.Printf("0x%x 0x%x -> 0x%x\n", p.Data[i:i+32], p.Data[i+32:i+64], p.Cache[j])
+		p.Ok[j] = true
+	}
+
+	// hash the cache layers
+	for i := PageSize/32 - 2; i > 0; i -= 2 {
+		j := i >> 1
+		if p.Ok[j] {
+			continue
+		}
+		p.Cache[j] = HashPair(p.Cache[i], p.Cache[i+1])
+		p.Ok[j] = true
+	}
+
+	return p.Cache[1]
+}
+
+func (p *CachedPage) MerkleizeSubtree(gindex uint64) [32]byte {
+	_ = p.MerkleRoot() // fill cache
+	if gindex >= PageSize/32 {
+		if gindex >= PageSize/32*2 {
+			panic("gindex too deep")
+		}
+		// it's pointing to a bottom node
+		nodeIndex := gindex & (PageAddrMask >> 5)
+		return *(*[32]byte)(p.Data[nodeIndex*32 : nodeIndex*32+32])
+	}
+	return p.Cache[gindex]
+}

cannon/mipsevm/page_test.go

+package mipsevm
+
+import (
+	"testing"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCachedPage(t *testing.T) {
+	p := &CachedPage{Data: new(Page)}
+	p.Data[42] = 0xab
+
+	gindex := ((uint64(1) << PageAddrSize) | 42) >> 5
+	node := common.Hash(p.MerkleizeSubtree(gindex))
+	expectedLeaf := common.Hash{10: 0xab}
+	require.Equal(t, expectedLeaf, node, "leaf nodes should not be hashed")
+
+	node = p.MerkleizeSubtree(gindex >> 1)
+	expectedParent := common.Hash(HashPair(zeroHashes[0], expectedLeaf))
+	require.Equal(t, expectedParent, node, "can get the parent node")
+
+	node = p.MerkleizeSubtree(gindex >> 2)
+	expectedParentParent := common.Hash(HashPair(expectedParent, zeroHashes[1]))
+	require.Equal(t, expectedParentParent, node, "and the parent of the parent")
+
+	pre := p.MerkleRoot()
+	p.Data[42] = 0xcd
+	post := p.MerkleRoot()
+	require.Equal(t, pre, post, "no change expected until cache is invalidated")
+
+	p.Invalidate(42)
+	post2 := p.MerkleRoot()
+	require.NotEqual(t, post, post2, "change after cache invalidation")
+
+	p.Data[2000] = 0xef
+	p.Invalidate(42)
+	post3 := p.MerkleRoot()
+	require.Equal(t, post2, post3, "local invalidation is not global invalidation")
+
+	p.Invalidate(2000)
+	post4 := p.MerkleRoot()
+	require.NotEqual(t, post3, post4, "can see the change now")
+
+	p.Data[1000] = 0xff
+	p.InvalidateFull()
+	post5 := p.MerkleRoot()
+	require.NotEqual(t, post4, post5, "and global invalidation works regardless of changed data")
+}

cannon/mipsevm/patch.go

+package mipsevm
+
+import (
+	"bytes"
+	"debug/elf"
+	"encoding/binary"
+	"fmt"
+	"io"
+)
+
+func LoadELF(f *elf.File) (*State, error) {
+	s := &State{
+		PC:        uint32(f.Entry),
+		NextPC:    uint32(f.Entry + 4),
+		HI:        0,
+		LO:        0,
+		Heap:      0x20000000,
+		Registers: [32]uint32{},
+		Memory:    NewMemory(),
+		ExitCode:  0,
+		Exited:    false,
+		Step:      0,
+	}
+
+	for i, prog := range f.Progs {
+		if prog.Type == 0x70000003 { // MIPS_ABIFLAGS
+			continue
+		}
+
+		r := io.Reader(io.NewSectionReader(prog, 0, int64(prog.Filesz)))
+		if prog.Filesz != prog.Memsz {
+			if prog.Type == elf.PT_LOAD {
+				if prog.Filesz < prog.Memsz {
+					r = io.MultiReader(r, bytes.NewReader(make([]byte, prog.Memsz-prog.Filesz)))
+				} else {
+					return nil, fmt.Errorf("invalid PT_LOAD program segment %d, file size (%d) > mem size (%d)", i, prog.Filesz, prog.Memsz)
+				}
+			} else {
+				return nil, fmt.Errorf("program segment %d has different file size (%d) than mem size (%d): filling for non PT_LOAD segments is not supported", i, prog.Filesz, prog.Memsz)
+			}
+		}
+
+		if prog.Vaddr+prog.Memsz >= uint64(1<<32) {
+			return nil, fmt.Errorf("program %d out of 32-bit mem range: %x - %x (size: %x)", i, prog.Vaddr, prog.Vaddr+prog.Memsz, prog.Memsz)
+		}
+		if err := s.Memory.SetMemoryRange(uint32(prog.Vaddr), r); err != nil {
+			return nil, fmt.Errorf("failed to read program segment %d: %w", i, err)
+		}
+	}
+
+	return s, nil
+}
+
+func PatchGo(f *elf.File, st *State) error {
+	symbols, err := f.Symbols()
+	if err != nil {
+		return fmt.Errorf("failed to read symbols data, cannot patch program: %w", err)
+	}
+
+	for _, s := range symbols {
+		// Disable Golang GC by patching the functions that enable the GC to a no-op function.
+		switch s.Name {
+		case "runtime.gcenable",
+			"runtime.init.5",            // patch out: init() { go forcegchelper() }
+			"runtime.main.func1",        // patch out: main.func() { newm(sysmon, ....) }
+			"runtime.deductSweepCredit", // uses floating point nums and interacts with gc we disabled
+			"runtime.(*gcControllerState).commit",
+			// these prometheus packages rely on concurrent background things. We cannot run those.
+			"github.com/prometheus/client_golang/prometheus.init",
+			"github.com/prometheus/client_golang/prometheus.init.0",
+			"github.com/prometheus/procfs.init",
+			"github.com/prometheus/common/model.init",
+			"github.com/prometheus/client_model/go.init",
+			"github.com/prometheus/client_model/go.init.0",
+			"github.com/prometheus/client_model/go.init.1",
+			// skip flag pkg init, we need to debug arg-processing more to see why this fails
+			"flag.init",
+			// We need to patch this out, we don't pass float64nan because we don't support floats
+			"runtime.check":
+			// MIPS32 patch: ret (pseudo instruction)
+			// 03e00008 = jr $ra = ret (pseudo instruction)
+			// 00000000 = nop (executes with delay-slot, but does nothing)
+			if err := st.Memory.SetMemoryRange(uint32(s.Value), bytes.NewReader([]byte{
+				0x03, 0xe0, 0x00, 0x08,
+				0, 0, 0, 0,
+			})); err != nil {
+				return fmt.Errorf("failed to patch Go runtime.gcenable: %w", err)
+			}
+		case "runtime.MemProfileRate":
+			if err := st.Memory.SetMemoryRange(uint32(s.Value), bytes.NewReader(make([]byte, 4))); err != nil { // disable mem profiling, to avoid a lot of unnecessary floating point ops
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+func PatchStack(st *State) error {
+	// setup stack pointer
+	sp := uint32(0x7f_ff_d0_00)
+	// allocate 1 page for the initial stack data, and 16KB = 4 pages for the stack to grow
+	if err := st.Memory.SetMemoryRange(sp-4*PageSize, bytes.NewReader(make([]byte, 5*PageSize))); err != nil {
+		return fmt.Errorf("failed to allocate page for stack content")
+	}
+	st.Registers[29] = sp
+
+	storeMem := func(addr uint32, v uint32) {
+		var dat [4]byte
+		binary.BigEndian.PutUint32(dat[:], v)
+		_ = st.Memory.SetMemoryRange(addr, bytes.NewReader(dat[:]))
+	}
+
+	// init argc, argv, aux on stack
+	storeMem(sp+4*1, 0x42)   // argc = 0 (argument count)
+	storeMem(sp+4*2, 0x35)   // argv[n] = 0 (terminating argv)
+	storeMem(sp+4*3, 0)      // envp[term] = 0 (no env vars)
+	storeMem(sp+4*4, 6)      // auxv[0] = _AT_PAGESZ = 6 (key)
+	storeMem(sp+4*5, 4096)   // auxv[1] = page size of 4 KiB (value) - (== minPhysPageSize)
+	storeMem(sp+4*6, 25)     // auxv[2] = AT_RANDOM
+	storeMem(sp+4*7, sp+4*9) // auxv[3] = address of 16 bytes containing random value
+	storeMem(sp+4*8, 0)      // auxv[term] = 0
+
+	_ = st.Memory.SetMemoryRange(sp+4*9, bytes.NewReader([]byte("4;byfairdiceroll"))) // 16 bytes of "randomness"
+
+	return nil
+}

cannon/mipsevm/solutil.go

+package mipsevm
+
+import (
+	"fmt"
+	"io"
+	"math/big"
+	"os"
+	"strconv"
+	"strings"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/core/vm"
+)
+
+type LineCol struct {
+	Line uint32
+	Col  uint32
+}
+
+type InstrMapping struct {
+	S int32 // start offset in bytes within source (negative when non-existent!)
+	L int32 // length in bytes within source (negative when non-existent!)
+	F int32 // file index of source (negative when non-existent!)
+	J byte  // jump type (i=into, o=out, -=regular)
+	M int32 // modifier depth
+}
+
+func parseInstrMapping(last InstrMapping, v string) (InstrMapping, error) {
+	data := strings.Split(v, ":")
+	out := last
+	if len(data) < 1 {
+		return out, nil
+	}
+	if len(data) > 5 {
+		return out, fmt.Errorf("unexpected length: %d", len(data))
+	}
+	var err error
+	parse := func(x string) int32 {
+		p, e := strconv.ParseInt(x, 10, 32)
+		err = e
+		return int32(p)
+	}
+	if data[0] != "" {
+		out.S = parse(data[0])
+	}
+	if len(data) < 2 || err != nil {
+		return out, err
+	}
+	if data[1] != "" {
+		out.L = parse(data[1])
+	}
+	if len(data) < 3 || err != nil {
+		return out, err
+	}
+	if data[2] != "" {
+		out.F = parse(data[2])
+	}
+	if len(data) < 4 || err != nil {
+		return out, err
+	}
+	if data[3] != "" {
+		out.J = data[3][0]
+	}
+	if len(data) < 5 || err != nil {
+		return out, err
+	}
+	if data[4] != "" {
+		out.M = parse(data[4])
+	}
+	return out, err
+}
+
+type SourceMap struct {
+	// source names
+	Sources []string
+	// per source, source offset -> line/col
+	PosData [][]LineCol
+	// per bytecode byte, byte index -> instr
+	Instr []InstrMapping
+}
+
+func (s *SourceMap) Info(pc uint64) (source string, line uint32, col uint32) {
+	instr := s.Instr[pc]
+	if instr.F < 0 {
+		return "generated", 0, 0
+	}
+	if instr.F >= int32(len(s.Sources)) {
+		source = "unknown"
+		return
+	}
+	source = s.Sources[instr.F]
+	if instr.S < 0 {
+		return
+	}
+	if s.PosData[instr.F] == nil { // when the source file is known to be unavailable
+		return
+	}
+	lc := s.PosData[instr.F][instr.S]
+	line = lc.Line
+	col = lc.Col
+	return
+}
+
+func (s *SourceMap) FormattedInfo(pc uint64) string {
+	f, l, c := s.Info(pc)
+	return fmt.Sprintf("%s:%d:%d", f, l, c)
+}
+
+// ParseSourceMap parses a solidity sourcemap: mapping bytecode indices to source references.
+// See https://docs.soliditylang.org/en/latest/internals/source_mappings.html
+func ParseSourceMap(sources []string, bytecode []byte, sourceMap string) (*SourceMap, error) {
+	instructions := strings.Split(sourceMap, ";")
+
+	srcMap := &SourceMap{
+		Sources: sources,
+		PosData: make([][]LineCol, 0, len(sources)),
+		Instr:   make([]InstrMapping, 0, len(bytecode)),
+	}
+	// map source code position byte offsets to line/column pairs
+	for i, s := range sources {
+		if strings.HasPrefix(s, "~") {
+			srcMap.PosData = append(srcMap.PosData, nil)
+			continue
+		}
+		dat, err := os.ReadFile(s)
+		if err != nil {
+			return nil, fmt.Errorf("failed to read source %d %q: %w", i, s, err)
+		}
+		datStr := string(dat)
+
+		out := make([]LineCol, len(datStr))
+		line := uint32(1)
+		lastLinePos := uint32(0)
+		for i, b := range datStr { // iterate the utf8 or the bytes?
+			col := uint32(i) - lastLinePos
+			out[i] = LineCol{Line: line, Col: col}
+			if b == '\n' {
+				lastLinePos = uint32(i)
+				line += 1
+			}
+		}
+		srcMap.PosData = append(srcMap.PosData, out)
+	}
+
+	instIndex := 0
+
+	// bytecode offset to instruction
+	lastInstr := InstrMapping{}
+	for i := 0; i < len(bytecode); {
+		inst := bytecode[i]
+		instLen := 1
+		if inst >= 0x60 && inst <= 0x7f { // push instructions
+			pushDataLen := inst - 0x60 + 1
+			instLen += int(pushDataLen)
+		}
+
+		var instMapping string
+		if instIndex >= len(instructions) {
+			// truncated source-map? Or some instruction that's longer than we accounted for?
+			// probably the contract-metadata bytes that are not accounted for in source map
+		} else {
+			instMapping = instructions[instIndex]
+		}
+		m, err := parseInstrMapping(lastInstr, instMapping)
+		if err != nil {
+			return nil, fmt.Errorf("failed to parse instr element in source map: %w", err)
+		}
+
+		for j := 0; j < instLen; j++ {
+			srcMap.Instr = append(srcMap.Instr, m)
+		}
+		i += instLen
+		instIndex += 1
+	}
+	return srcMap, nil
+}
+
+func NewSourceMapTracer(srcMaps map[common.Address]*SourceMap, out io.Writer) *SourceMapTracer {
+	return &SourceMapTracer{srcMaps, out}
+}
+
+type SourceMapTracer struct {
+	srcMaps map[common.Address]*SourceMap
+	out     io.Writer
+}
+
+func (s *SourceMapTracer) CaptureTxStart(gasLimit uint64) {}
+
+func (s *SourceMapTracer) CaptureTxEnd(restGas uint64) {}
+
+func (s *SourceMapTracer) CaptureStart(env *vm.EVM, from common.Address, to common.Address, create bool, input []byte, gas uint64, value *big.Int) {
+}
+
+func (s *SourceMapTracer) CaptureEnd(output []byte, gasUsed uint64, err error) {}
+
+func (s *SourceMapTracer) CaptureEnter(typ vm.OpCode, from common.Address, to common.Address, input []byte, gas uint64, value *big.Int) {
+}
+
+func (s *SourceMapTracer) CaptureExit(output []byte, gasUsed uint64, err error) {}
+
+func (s *SourceMapTracer) info(codeAddr *common.Address, pc uint64) string {
+	info := "non-contract"
+	if codeAddr != nil {
+		srcMap, ok := s.srcMaps[*codeAddr]
+		if ok {
+			info = srcMap.FormattedInfo(pc)
+		} else {
+			info = "unknown-contract"
+		}
+	}
+	return info
+}
+
+func (s *SourceMapTracer) CaptureState(pc uint64, op vm.OpCode, gas, cost uint64, scope *vm.ScopeContext, rData []byte, depth int, err error) {
+	fmt.Fprintf(s.out, "%-40s : pc %x opcode %s\n", s.info(scope.Contract.CodeAddr, pc), pc, op.String())
+}
+
+func (s *SourceMapTracer) CaptureFault(pc uint64, op vm.OpCode, gas, cost uint64, scope *vm.ScopeContext, depth int, err error) {
+	fmt.Fprintf(s.out, "%-40s: pc %x opcode %s FAULT %v\n", s.info(scope.Contract.CodeAddr, pc), pc, op.String(), err)
+	fmt.Println("----")
+	fmt.Fprintf(s.out, "calldata: %x\n", scope.Contract.Input)
+	fmt.Println("----")
+	fmt.Fprintf(s.out, "memory: %x\n", scope.Memory.Data())
+	fmt.Println("----")
+	fmt.Fprintf(s.out, "stack:\n")
+	stack := scope.Stack.Data()
+	for i := range stack {
+		fmt.Fprintf(s.out, "%3d: %x\n", -i, stack[len(stack)-1-i].Bytes32())
+	}
+}
+
+var _ vm.EVMLogger = (*SourceMapTracer)(nil)

cannon/mipsevm/solutil_test.go

+package mipsevm
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestSourcemap(t *testing.T) {
+	contract, err := LoadContract("MIPS")
+	require.NoError(t, err)
+	srcMap, err := contract.SourceMap([]string{"../contracts/src/MIPS.sol"})
+	require.NoError(t, err)
+	for i := 0; i < len(contract.DeployedBytecode.Object); i++ {
+		info := srcMap.FormattedInfo(uint64(i))
+		if !strings.HasPrefix(info, "generated:") && !strings.HasPrefix(info, "../contracts/src/MIPS.sol") {
+			t.Fatalf("unexpected info: %q", info)
+		}
+	}
+}

cannon/mipsevm/state.go

+package mipsevm
+
+import (
+	"encoding/binary"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+)
+
+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 (s *State) EncodeWitness() []byte {
+	out := make([]byte, 0)
+	memRoot := s.Memory.MerkleRoot()
+	out = append(out, memRoot[:]...)
+	out = append(out, s.PreimageKey[:]...)
+	out = binary.BigEndian.AppendUint32(out, s.PreimageOffset)
+	out = binary.BigEndian.AppendUint32(out, s.PC)
+	out = binary.BigEndian.AppendUint32(out, s.NextPC)
+	out = binary.BigEndian.AppendUint32(out, s.LO)
+	out = binary.BigEndian.AppendUint32(out, s.HI)
+	out = binary.BigEndian.AppendUint32(out, s.Heap)
+	out = append(out, s.ExitCode)
+	if s.Exited {
+		out = append(out, 1)
+	} else {
+		out = append(out, 0)
+	}
+	out = binary.BigEndian.AppendUint64(out, s.Step)
+	for _, r := range s.Registers {
+		out = binary.BigEndian.AppendUint32(out, r)
+	}
+	return out
+}

cannon/mipsevm/state_test.go

+package mipsevm
+
+import (
+	"bytes"
+	"debug/elf"
+	"encoding/binary"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"os"
+	"path"
+	"strings"
+	"testing"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/stretchr/testify/require"
+
+	"github.com/ethereum-optimism/cannon/preimage"
+)
+
+// 0xbf_c0_00_00 ... baseAddrEnd is used in tests to write the results to
+const baseAddrEnd = 0xbf_ff_ff_f0
+
+// endAddr is used as return-address for tests
+const endAddr = 0xa7ef00d0
+
+func TestState(t *testing.T) {
+	testFiles, err := os.ReadDir("open_mips_tests/test/bin")
+	require.NoError(t, err)
+
+	for _, f := range testFiles {
+		t.Run(f.Name(), func(t *testing.T) {
+			if f.Name() == "oracle.bin" {
+				t.Skip("oracle test needs to be updated to use syscall pre-image oracle")
+			}
+			// TODO: currently tests are compiled as flat binary objects
+			// We can use more standard tooling to compile them to ELF files and get remove maketests.py
+			fn := path.Join("open_mips_tests/test/bin", f.Name())
+			//elfProgram, err := elf.Open()
+			//require.NoError(t, err, "must load test ELF binary")
+			//state, err := LoadELF(elfProgram)
+			//require.NoError(t, err, "must load ELF into state")
+			programMem, err := os.ReadFile(fn)
+			require.NoError(t, err)
+			state := &State{PC: 0, NextPC: 4, Memory: NewMemory()}
+			err = state.Memory.SetMemoryRange(0, bytes.NewReader(programMem))
+			require.NoError(t, err, "load program into state")
+
+			// set the return address ($ra) to jump into when test completes
+			state.Registers[31] = endAddr
+
+			us := NewInstrumentedState(state, nil, os.Stdout, os.Stderr)
+
+			for i := 0; i < 1000; i++ {
+				if us.state.PC == endAddr {
+					break
+				}
+				_, err := us.Step(false)
+				require.NoError(t, err)
+			}
+			require.Equal(t, uint32(endAddr), us.state.PC, "must reach end")
+			// inspect test result
+			done, result := state.Memory.GetMemory(baseAddrEnd+4), state.Memory.GetMemory(baseAddrEnd+8)
+			require.Equal(t, done, uint32(1), "must be done")
+			require.Equal(t, result, uint32(1), "must have success result")
+		})
+	}
+}
+
+func TestHello(t *testing.T) {
+	elfProgram, err := elf.Open("../example/bin/hello.elf")
+	require.NoError(t, err, "open ELF file")
+
+	state, err := LoadELF(elfProgram)
+	require.NoError(t, err, "load ELF into state")
+
+	err = PatchGo(elfProgram, state)
+	require.NoError(t, err, "apply Go runtime patches")
+	require.NoError(t, PatchStack(state), "add initial stack")
+
+	var stdOutBuf, stdErrBuf bytes.Buffer
+	us := NewInstrumentedState(state, nil, io.MultiWriter(&stdOutBuf, os.Stdout), io.MultiWriter(&stdErrBuf, os.Stderr))
+
+	for i := 0; i < 400_000; i++ {
+		if us.state.Exited {
+			break
+		}
+		_, err := us.Step(false)
+		require.NoError(t, err)
+	}
+
+	require.True(t, state.Exited, "must complete program")
+	require.Equal(t, uint8(0), state.ExitCode, "exit with 0")
+
+	require.Equal(t, "hello world!", stdOutBuf.String(), "stdout says hello")
+	require.Equal(t, "", stdErrBuf.String(), "stderr silent")
+}
+
+type testOracle struct {
+	hint        func(v []byte)
+	getPreimage func(k [32]byte) []byte
+}
+
+func (t *testOracle) Hint(v []byte) {
+	t.hint(v)
+}
+
+func (t *testOracle) GetPreimage(k [32]byte) []byte {
+	return t.getPreimage(k)
+}
+
+var _ PreimageOracle = (*testOracle)(nil)
+
+func claimTestOracle(t *testing.T) (po PreimageOracle, stdOut string, stdErr string) {
+	s := uint64(1000)
+	a := uint64(3)
+	b := uint64(4)
+
+	encodeU64 := func(x uint64) []byte {
+		return binary.BigEndian.AppendUint64(nil, x)
+	}
+
+	var diff []byte
+	diff = append(diff, crypto.Keccak256(encodeU64(a))...)
+	diff = append(diff, crypto.Keccak256(encodeU64(b))...)
+
+	preHash := crypto.Keccak256Hash(encodeU64(s))
+	diffHash := crypto.Keccak256Hash(diff)
+
+	images := make(map[[32]byte][]byte)
+	images[preimage.LocalIndexKey(0).PreimageKey()] = preHash[:]
+	images[preimage.LocalIndexKey(1).PreimageKey()] = diffHash[:]
+	images[preimage.LocalIndexKey(2).PreimageKey()] = encodeU64(s*a + b)
+
+	oracle := &testOracle{
+		hint: func(v []byte) {
+			parts := strings.Split(string(v), " ")
+			require.Len(t, parts, 2)
+			p, err := hex.DecodeString(parts[1])
+			require.NoError(t, err)
+			require.Len(t, p, 32)
+			h := common.Hash(*(*[32]byte)(p))
+			switch parts[0] {
+			case "fetch-state":
+				require.Equal(t, h, preHash, "expecting request for pre-state pre-image")
+				images[preimage.Keccak256Key(preHash).PreimageKey()] = encodeU64(s)
+			case "fetch-diff":
+				require.Equal(t, h, diffHash, "expecting request for diff pre-images")
+				images[preimage.Keccak256Key(diffHash).PreimageKey()] = diff
+				images[preimage.Keccak256Key(crypto.Keccak256Hash(encodeU64(a))).PreimageKey()] = encodeU64(a)
+				images[preimage.Keccak256Key(crypto.Keccak256Hash(encodeU64(b))).PreimageKey()] = encodeU64(b)
+			default:
+				t.Fatalf("unexpected hint: %q", parts[0])
+			}
+		},
+		getPreimage: func(k [32]byte) []byte {
+			p, ok := images[k]
+			if !ok {
+				t.Fatalf("missing pre-image %s", k)
+			}
+			return p
+		},
+	}
+
+	return oracle, fmt.Sprintf("computing %d * %d + %d\nclaim %d is good!\n", s, a, b, s*a+b), "started!"
+}
+
+func TestClaim(t *testing.T) {
+	elfProgram, err := elf.Open("../example/bin/claim.elf")
+	require.NoError(t, err, "open ELF file")
+
+	state, err := LoadELF(elfProgram)
+	require.NoError(t, err, "load ELF into state")
+
+	err = PatchGo(elfProgram, state)
+	require.NoError(t, err, "apply Go runtime patches")
+	require.NoError(t, PatchStack(state), "add initial stack")
+
+	oracle, expectedStdOut, expectedStdErr := claimTestOracle(t)
+
+	var stdOutBuf, stdErrBuf bytes.Buffer
+	us := NewInstrumentedState(state, oracle, io.MultiWriter(&stdOutBuf, os.Stdout), io.MultiWriter(&stdErrBuf, os.Stderr))
+
+	for i := 0; i < 2000_000; i++ {
+		if us.state.Exited {
+			break
+		}
+		_, err := us.Step(false)
+		require.NoError(t, err)
+	}
+
+	require.True(t, state.Exited, "must complete program")
+	require.Equal(t, uint8(0), state.ExitCode, "exit with 0")
+
+	require.Equal(t, expectedStdOut, stdOutBuf.String(), "stdout")
+	require.Equal(t, expectedStdErr, stdErrBuf.String(), "stderr")
+}

cannon/mipsevm/witness.go

+package mipsevm
+
+import (
+	"encoding/binary"
+	"errors"
+	"fmt"
+
+	"github.com/ethereum-optimism/cannon/preimage"
+)
+
+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 uint32ToBytes32(v uint32) []byte {
+	var out [32]byte
+	binary.BigEndian.PutUint32(out[32-4:], v)
+	return out[:]
+}
+
+func (wit *StepWitness) EncodeStepInput() []byte {
+	var input []byte
+	input = append(input, StepBytes4...)
+	input = append(input, uint32ToBytes32(32*2)...)                           // state data offset in bytes
+	input = append(input, uint32ToBytes32(32*2+32+uint32(len(wit.State)))...) // proof data offset in bytes
+
+	input = append(input, uint32ToBytes32(uint32(len(wit.State)))...) // state data length in bytes
+	input = append(input, wit.State[:]...)
+	input = append(input, uint32ToBytes32(uint32(len(wit.MemProof)))...) // proof data length in bytes
+	input = append(input, wit.MemProof[:]...)
+	return input
+}
+
+func (wit *StepWitness) HasPreimage() bool {
+	return wit.PreimageKey != ([32]byte{})
+}
+
+func (wit *StepWitness) EncodePreimageOracleInput() ([]byte, error) {
+	if wit.PreimageKey == ([32]byte{}) {
+		return nil, errors.New("cannot encode pre-image oracle input, witness has no pre-image to proof")
+	}
+
+	switch preimage.KeyType(wit.PreimageKey[0]) {
+	case preimage.LocalKeyType:
+		// We have no on-chain form of preparing the bootstrap pre-images onchain yet.
+		// So instead we cheat them in.
+		// In production usage there should be an on-chain contract that exposes this,
+		// rather than going through the global keccak256 oracle.
+		var input []byte
+		input = append(input, CheatBytes4...)
+		input = append(input, uint32ToBytes32(wit.PreimageOffset)...)
+		input = append(input, wit.PreimageKey[:]...)
+		var tmp [32]byte
+		copy(tmp[:], wit.PreimageValue[wit.PreimageOffset:])
+		input = append(input, tmp[:]...)
+		input = append(input, uint32ToBytes32(uint32(len(wit.PreimageValue))-8)...)
+		// TODO: do we want to pad the end to a multiple of 32 bytes?
+		return input, nil
+	case preimage.Keccak256KeyType:
+		var input []byte
+		input = append(input, LoadKeccak256PreimagePartBytes4...)
+		input = append(input, uint32ToBytes32(wit.PreimageOffset)...)
+		input = append(input, uint32ToBytes32(32+32)...) // partOffset, calldata offset
+		input = append(input, uint32ToBytes32(uint32(len(wit.PreimageValue))-8)...)
+		input = append(input, wit.PreimageValue[8:]...)
+		// TODO: do we want to pad the end to a multiple of 32 bytes?
+		return input, nil
+	default:
+		return nil, fmt.Errorf("unsupported pre-image type %d, cannot prepare preimage with key %x offset %d for oracle",
+			wit.PreimageKey[0], wit.PreimageKey, wit.PreimageOffset)
+	}
+}

cannon/preimage/filechan.go

+package preimage
+
+import (
+	"io"
+	"os"
+)
+
+// FileChannel is a unidirectional channel for file I/O
+type FileChannel interface {
+	io.ReadWriteCloser
+	// Reader returns the file that is used for reading.
+	Reader() *os.File
+	// Writer returns the file that is used for writing.
+	Writer() *os.File
+}
+
+type ReadWritePair struct {
+	r *os.File
+	w *os.File
+}
+
+// NewReadWritePair creates a new FileChannel that uses the given files
+func NewReadWritePair(r *os.File, w *os.File) *ReadWritePair {
+	return &ReadWritePair{r: r, w: w}
+}
+
+func (rw *ReadWritePair) Read(p []byte) (int, error) {
+	return rw.r.Read(p)
+}
+
+func (rw *ReadWritePair) Write(p []byte) (int, error) {
+	return rw.w.Write(p)
+}
+
+func (rw *ReadWritePair) Reader() *os.File {
+	return rw.r
+}
+
+func (rw *ReadWritePair) Writer() *os.File {
+	return rw.w
+}
+
+func (rw *ReadWritePair) Close() error {
+	if err := rw.r.Close(); err != nil {
+		return err
+	}
+	return rw.w.Close()
+}
+
+// CreateBidirectionalChannel creates a pair of FileChannels that are connected to each other.
+func CreateBidirectionalChannel() (FileChannel, FileChannel, error) {
+	ar, bw, err := os.Pipe()
+	if err != nil {
+		return nil, nil, err
+	}
+	br, aw, err := os.Pipe()
+	if err != nil {
+		return nil, nil, err
+	}
+	return NewReadWritePair(ar, aw), NewReadWritePair(br, bw), nil
+}
+
+const (
+	HClientRFd = 3
+	HClientWFd = 4
+	PClientRFd = 5
+	PClientWFd = 6
+)
+
+func ClientHinterChannel() *ReadWritePair {
+	r := os.NewFile(HClientRFd, "preimage-hint-read")
+	w := os.NewFile(HClientWFd, "preimage-hint-write")
+	return NewReadWritePair(r, w)
+}
+
+// ClientPreimageChannel returns a FileChannel for the preimage oracle in a detached context
+func ClientPreimageChannel() *ReadWritePair {
+	r := os.NewFile(PClientRFd, "preimage-oracle-read")
+	w := os.NewFile(PClientWFd, "preimage-oracle-write")
+	return NewReadWritePair(r, w)
+}

cannon/preimage/go.mod

+module github.com/ethereum-optimism/cannon/preimage
+
+go 1.20
+
+require (
+	github.com/stretchr/testify v1.8.2
+	golang.org/x/crypto v0.8.0
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	golang.org/x/sys v0.7.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

cannon/preimage/go.sum

+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.2 h1:+h33VjcLVPDHtOdpUCuF+7gSuG3yGIftsP1YvFihtJ8=
+github.com/stretchr/testify v1.8.2/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+golang.org/x/crypto v0.8.0 h1:pd9TJtTueMTVQXzk8E2XESSMQDj/U7OUu0PqJqPXQjQ=
+golang.org/x/crypto v0.8.0/go.mod h1:mRqEX+O9/h5TFCrQhkgjo2yKi0yYA+9ecGkdQoHrywE=
+golang.org/x/sys v0.7.0 h1:3jlCCIQZPdOYu1h8BkNvLz8Kgwtae2cagcG/VamtZRU=
+golang.org/x/sys v0.7.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

cannon/preimage/hash.go

+package preimage
+
+import "golang.org/x/crypto/sha3"
+
+func Keccak256(v []byte) (out [32]byte) {
+	s := sha3.NewLegacyKeccak256()
+	s.Write(v)
+	s.Sum(out[:0])
+	return
+}

cannon/preimage/hints.go

+package preimage
+
+import (
+	"encoding/binary"
+	"fmt"
+	"io"
+)
+
+// HintWriter writes hints to an io.Writer (e.g. a special file descriptor, or a debug log),
+// for a pre-image oracle service to prepare specific pre-images.
+type HintWriter struct {
+	rw io.ReadWriter
+}
+
+var _ Hinter = (*HintWriter)(nil)
+
+func NewHintWriter(rw io.ReadWriter) *HintWriter {
+	return &HintWriter{rw: rw}
+}
+
+func (hw *HintWriter) Hint(v Hint) {
+	hint := v.Hint()
+	var hintBytes []byte
+	hintBytes = binary.BigEndian.AppendUint32(hintBytes, uint32(len(hint)))
+	hintBytes = append(hintBytes, []byte(hint)...)
+	_, err := hw.rw.Write(hintBytes)
+	if err != nil {
+		panic(fmt.Errorf("failed to write pre-image hint: %w", err))
+	}
+	_, err = hw.rw.Read([]byte{0})
+	if err != nil {
+		panic(fmt.Errorf("failed to read pre-image hint ack: %w", err))
+	}
+}
+
+// HintReader reads the hints of HintWriter and passes them to a router for preparation of the requested pre-images.
+// Onchain the written hints are no-op.
+type HintReader struct {
+	rw io.ReadWriter
+}
+
+func NewHintReader(rw io.ReadWriter) *HintReader {
+	return &HintReader{rw: rw}
+}
+
+func (hr *HintReader) NextHint(router func(hint string) error) error {
+	var length uint32
+	if err := binary.Read(hr.rw, binary.BigEndian, &length); err != nil {
+		if err == io.EOF {
+			return io.EOF
+		}
+		return fmt.Errorf("failed to read hint length prefix: %w", err)
+	}
+	payload := make([]byte, length)
+	if length > 0 {
+		if _, err := io.ReadFull(hr.rw, payload); err != nil {
+			return fmt.Errorf("failed to read hint payload (length %d): %w", length, err)
+		}
+	}
+	if err := router(string(payload)); err != nil {
+		// write back on error to unblock the HintWriter
+		_, _ = hr.rw.Write([]byte{0})
+		return fmt.Errorf("failed to handle hint: %w", err)
+	}
+	if _, err := hr.rw.Write([]byte{0}); err != nil {
+		return fmt.Errorf("failed to write trailing no-op byte to unblock hint writer: %w", err)
+	}
+	return nil
+}

cannon/preimage/hints_test.go

+package preimage
+
+import (
+	"bytes"
+	"crypto/rand"
+	"errors"
+	"io"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+type rawHint string
+
+func (rh rawHint) Hint() string {
+	return string(rh)
+}
+
+func TestHints(t *testing.T) {
+	// Note: pretty much every string is valid communication:
+	// length, payload, 0. Worst case you run out of data, or allocate too much.
+	testHint := func(hints ...string) {
+		a, b := bidirectionalPipe()
+		var wg sync.WaitGroup
+		wg.Add(2)
+
+		go func() {
+			hw := NewHintWriter(a)
+			for _, h := range hints {
+				hw.Hint(rawHint(h))
+			}
+			wg.Done()
+		}()
+
+		got := make(chan string, len(hints))
+		go func() {
+			defer wg.Done()
+			hr := NewHintReader(b)
+			for i := 0; i < len(hints); i++ {
+				err := hr.NextHint(func(hint string) error {
+					got <- hint
+					return nil
+				})
+				if err == io.EOF {
+					break
+				}
+				require.NoError(t, err)
+			}
+		}()
+		if waitTimeout(&wg) {
+			t.Error("hint read/write stuck")
+		}
+
+		require.Equal(t, len(hints), len(got), "got all hints")
+		for _, h := range hints {
+			require.Equal(t, h, <-got, "hints match")
+		}
+	}
+
+	t.Run("empty hint", func(t *testing.T) {
+		testHint("")
+	})
+	t.Run("hello world", func(t *testing.T) {
+		testHint("hello world")
+	})
+	t.Run("zero byte", func(t *testing.T) {
+		testHint(string([]byte{0}))
+	})
+	t.Run("many zeroes", func(t *testing.T) {
+		testHint(string(make([]byte, 1000)))
+	})
+	t.Run("random data", func(t *testing.T) {
+		dat := make([]byte, 1000)
+		_, _ = rand.Read(dat[:])
+		testHint(string(dat))
+	})
+	t.Run("multiple hints", func(t *testing.T) {
+		testHint("give me header a", "also header b", "foo bar")
+	})
+	t.Run("unexpected EOF", func(t *testing.T) {
+		var buf bytes.Buffer
+		hw := NewHintWriter(&buf)
+		hw.Hint(rawHint("hello"))
+		_, _ = buf.Read(make([]byte, 1)) // read one byte so it falls short, see if it's detected
+		hr := NewHintReader(&buf)
+		err := hr.NextHint(func(hint string) error { return nil })
+		require.ErrorIs(t, err, io.ErrUnexpectedEOF)
+	})
+	t.Run("cb error", func(t *testing.T) {
+		a, b := bidirectionalPipe()
+		var wg sync.WaitGroup
+		wg.Add(2)
+
+		go func() {
+			hw := NewHintWriter(a)
+			hw.Hint(rawHint("one"))
+			hw.Hint(rawHint("two"))
+			wg.Done()
+		}()
+		go func() {
+			defer wg.Done()
+			hr := NewHintReader(b)
+			cbErr := errors.New("fail")
+			err := hr.NextHint(func(hint string) error { return cbErr })
+			require.ErrorIs(t, err, cbErr)
+			var readHint string
+			err = hr.NextHint(func(hint string) error {
+				readHint = hint
+				return nil
+			})
+			require.NoError(t, err)
+			require.Equal(t, readHint, "two")
+		}()
+		if waitTimeout(&wg) {
+			t.Error("read/write hint stuck")
+		}
+	})
+}
+
+// waitTimeout returns true iff wg.Wait timed out
+func waitTimeout(wg *sync.WaitGroup) bool {
+	done := make(chan struct{})
+	go func() {
+		wg.Wait()
+		close(done)
+	}()
+	select {
+	case <-time.After(time.Second * 30):
+		return true
+	case <-done:
+		return false
+	}
+}

cannon/preimage/iface.go

+package preimage
+
+import (
+	"encoding/binary"
+	"encoding/hex"
+)
+
+type Key interface {
+	// PreimageKey changes the Key commitment into a
+	// 32-byte type-prefixed preimage key.
+	PreimageKey() [32]byte
+}
+
+type Oracle interface {
+	// Get the full pre-image of a given pre-image key.
+	// This returns no error: the client state-transition
+	// is invalid if there is any missing pre-image data.
+	Get(key Key) []byte
+}
+
+type OracleFn func(key Key) []byte
+
+func (fn OracleFn) Get(key Key) []byte {
+	return fn(key)
+}
+
+// KeyType is the key-type of a pre-image, used to prefix the pre-image key with.
+type KeyType byte
+
+const (
+	// The zero key type is illegal to use, ensuring all keys are non-zero.
+	_ KeyType = 0
+	// LocalKeyType is for input-type pre-images, specific to the local program instance.
+	LocalKeyType KeyType = 1
+	// Keccak256KeyType is for keccak256 pre-images, for any global shared pre-images.
+	Keccak256KeyType KeyType = 2
+)
+
+// LocalIndexKey is a key local to the program, indexing a special program input.
+type LocalIndexKey uint64
+
+func (k LocalIndexKey) PreimageKey() (out [32]byte) {
+	out[0] = byte(LocalKeyType)
+	binary.BigEndian.PutUint64(out[24:], uint64(k))
+	return
+}
+
+// Keccak256Key wraps a keccak256 hash to use it as a typed pre-image key.
+type Keccak256Key [32]byte
+
+func (k Keccak256Key) PreimageKey() (out [32]byte) {
+	out = k                         // copy the keccak hash
+	out[0] = byte(Keccak256KeyType) // apply prefix
+	return
+}
+
+func (k Keccak256Key) String() string {
+	return "0x" + hex.EncodeToString(k[:])
+}
+
+func (k Keccak256Key) TerminalString() string {
+	return "0x" + hex.EncodeToString(k[:])
+}
+
+// Hint is an interface to enable any program type to function as a hint,
+// when passed to the Hinter interface, returning a string representation
+// of what data the host should prepare pre-images for.
+type Hint interface {
+	Hint() string
+}
+
+// Hinter is an interface to write hints to the host.
+// This may be implemented as a no-op or logging hinter
+// if the program is executing in a read-only environment
+// where the host is expected to have all pre-images ready.
+type Hinter interface {
+	Hint(v Hint)
+}
+
+type HinterFn func(v Hint)
+
+func (fn HinterFn) Hint(v Hint) {
+	fn(v)
+}

cannon/preimage/oracle.go

+package preimage
+
+import (
+	"encoding/binary"
+	"fmt"
+	"io"
+)
+
+// OracleClient implements the Oracle by writing the pre-image key to the given stream,
+// and reading back a length-prefixed value.
+type OracleClient struct {
+	rw io.ReadWriter
+}
+
+func NewOracleClient(rw io.ReadWriter) *OracleClient {
+	return &OracleClient{rw: rw}
+}
+
+var _ Oracle = (*OracleClient)(nil)
+
+func (o *OracleClient) Get(key Key) []byte {
+	h := key.PreimageKey()
+	if _, err := o.rw.Write(h[:]); err != nil {
+		panic(fmt.Errorf("failed to write key %s (%T) to pre-image oracle: %w", key, key, err))
+	}
+
+	var length uint64
+	if err := binary.Read(o.rw, binary.BigEndian, &length); err != nil {
+		panic(fmt.Errorf("failed to read pre-image length of key %s (%T) from pre-image oracle: %w", key, key, err))
+	}
+	payload := make([]byte, length)
+	if _, err := io.ReadFull(o.rw, payload); err != nil {
+		panic(fmt.Errorf("failed to read pre-image payload (length %d) of key %s (%T) from pre-image oracle: %w", length, key, key, err))
+	}
+
+	return payload
+}
+
+// OracleServer serves the pre-image requests of the OracleClient, implementing the same protocol as the onchain VM.
+type OracleServer struct {
+	rw io.ReadWriter
+}
+
+func NewOracleServer(rw io.ReadWriter) *OracleServer {
+	return &OracleServer{rw: rw}
+}
+
+func (o *OracleServer) NextPreimageRequest(getPreimage func(key [32]byte) ([]byte, error)) error {
+	var key [32]byte
+	if _, err := io.ReadFull(o.rw, key[:]); err != nil {
+		if err == io.EOF {
+			return io.EOF
+		}
+		return fmt.Errorf("failed to read requested pre-image key: %w", err)
+	}
+	value, err := getPreimage(key)
+	if err != nil {
+		return fmt.Errorf("failed to serve pre-image %s request: %w", key, err)
+	}
+
+	if err := binary.Write(o.rw, binary.BigEndian, uint64(len(value))); err != nil {
+		return fmt.Errorf("failed to write length-prefix %d: %w", len(value), err)
+	}
+	if len(value) == 0 {
+		return nil
+	}
+	if _, err := o.rw.Write(value); err != nil {
+		return fmt.Errorf("failed to write pre-image value (%d long): %w", len(value), err)
+	}
+	return nil
+}

cannon/preimage/oracle_test.go

+package preimage
+
+import (
+	"bytes"
+	"crypto/rand"
+	"fmt"
+	"io"
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+type readWritePair struct {
+	io.Reader
+	io.Writer
+}
+
+func bidirectionalPipe() (a, b io.ReadWriter) {
+	ar, bw := io.Pipe()
+	br, aw := io.Pipe()
+	return readWritePair{Reader: ar, Writer: aw}, readWritePair{Reader: br, Writer: bw}
+}
+
+func TestOracle(t *testing.T) {
+	testPreimage := func(preimages ...[]byte) {
+		a, b := bidirectionalPipe()
+		cl := NewOracleClient(a)
+		srv := NewOracleServer(b)
+
+		preimageByHash := make(map[[32]byte][]byte)
+		for _, p := range preimages {
+			k := Keccak256Key(Keccak256(p))
+			preimageByHash[k.PreimageKey()] = p
+		}
+		for _, p := range preimages {
+			k := Keccak256Key(Keccak256(p))
+
+			var wg sync.WaitGroup
+			wg.Add(2)
+
+			go func(k Key, p []byte) {
+				result := cl.Get(k)
+				wg.Done()
+				expected := preimageByHash[k.PreimageKey()]
+				require.True(t, bytes.Equal(expected, result), "need correct preimage %x, got %x", expected, result)
+			}(k, p)
+
+			go func() {
+				err := srv.NextPreimageRequest(func(key [32]byte) ([]byte, error) {
+					dat, ok := preimageByHash[key]
+					if !ok {
+						return nil, fmt.Errorf("cannot find %s", key)
+					}
+					return dat, nil
+				})
+				wg.Done()
+				require.NoError(t, err)
+			}()
+			wg.Wait()
+		}
+	}
+	t.Run("empty preimage", func(t *testing.T) {
+		testPreimage([]byte{})
+	})
+	t.Run("nil preimage", func(t *testing.T) {
+		testPreimage(nil)
+	})
+	t.Run("zero", func(t *testing.T) {
+		testPreimage([]byte{0})
+	})
+	t.Run("multiple", func(t *testing.T) {
+		testPreimage([]byte("tx from alice"), []byte{0x13, 0x37}, []byte("tx from bob"))
+	})
+	t.Run("zeroes", func(t *testing.T) {
+		testPreimage(make([]byte, 1000))
+	})
+	t.Run("random", func(t *testing.T) {
+		dat := make([]byte, 1000)
+		_, _ = rand.Read(dat[:])
+		testPreimage(dat)
+	})
+}