malik672/cannon-rs

An alternative implementation of the OP Stack's Cannon, a MIPS emulator for the EVM.

An alternative implementation of the OP Stack's Cannon in Rust.

What's a Cannon? • Overview • Credits • Benchmarks • Contributing • Documentation • Docker

What's a Cannon?

Cannon is an emulator designed to simulate a single MIPS thread context on the EVM. Its primary use is to execute the op-program (also known as the fault-proof program) for the OP Stack's interactive dispute protocol. The op-program consists of a stripped down version of op-geth's state transition code in addition to the derivation pipeline, and produces deterministic results. Subsequently, it is compiled to MIPS to be ran on top of Cannon on-chain to prove fault in claims about the state of L2 on L1. Cannon also has a native implementation of the MIPS thread context that mirrors the on-chain version, which enables the op-challenger to generate state commitments for an op-program execution trace and participate in dispute games.

TL;DR:

• It's Rust code
• ...that was originally Go code
• ...that runs an EVM
• ...emulating a MIPS machine
• ...running compiled Go code
• ...that runs an EVM

Overview

• cannon-mipsevm - Contains the native implementation of the MIPS thread context emulator.
• preimage-oracle - Rust bindings for interacting as client or sever over the Pre-image Oracle ABI.
• cannon-contracts - [in OP monorepo] Contains the Solidity implementation of the MIPS thread context and the Preimage Oracle.

Credits

This repository is heavily inspired by the original Cannon, built by George Hotz and members of the OP Labs team. The original implementation is written in Go, and can be found in the Optimism monorepo. All credits for the original idea and reference implementation of this concept go to these folks.

Benchmarks

cannon-mipsevm benchmarks

The below benchmark was ran on a 2021 Macbook Pro with an M1 Max and 32 GB of unified memory on commit 71b68d5.

Benchmark Name	cannon mean (Reference)	cannon-rs mean
Memory Merkle Root (25MB)	736.94 ms	29.58 µs (-99%)
Memory Merkle Root (50MB)	1.54s	7.25 ms (-99%)
Memory Merkle Root (100MB)	3.34s	273.76 ms (-91.8%)
Memory Merkle Root (200MB)	6.30s	1.65s (-73.81%)

todo - execution benchmarks

Contributing

To get started, a few dependencies are required:

• Rust toolchain
  • Recommended: cargo-nextest
• Go toolchain
• binutils

Testing

# With `cargo-nextest`
cargo +nightly nextest run --release --all --all-features
# Without `cargo-nextest`
cargo +nightly t --release --all --all-features

Linting and Formatting

cargo +nightly fmt --all -- && cargo +nightly clippy --all --all-features -- -D warnings

Running Benchmarks

cargo +nightly bench --all --all-features

Documentation

Rustdocs are available by running cargo doc --open after cloning the repo.

Specification

The specification for both Cannon and the preimage oracle can be found in the Optimism monorepo.

• Cannon specification
• Preimage oracle specification

Docker

The docker image for cannon-rs is located in the docker directory, and can be built using the script provided.