Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/op-rs/cannon-rs
An alternative implementation of the OP Stack's Cannon, a MIPS emulator for the EVM.
https://github.com/op-rs/cannon-rs
Last synced: 5 days ago
JSON representation
An alternative implementation of the OP Stack's Cannon, a MIPS emulator for the EVM.
- Host: GitHub
- URL: https://github.com/op-rs/cannon-rs
- Owner: op-rs
- License: mit
- Created: 2023-09-13T02:58:59.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-07-27T16:13:45.000Z (6 months ago)
- Last Synced: 2025-01-06T17:53:45.600Z (15 days ago)
- Language: Rust
- Size: 13.1 MB
- Stars: 59
- Watchers: 5
- Forks: 10
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
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`][op-program]
(also known as the fault-proof program) for the [OP Stack][monorepo]'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][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][cannon]
* ...that runs an EVM
* ...emulating a MIPS machine
* ...running [compiled Go code][op-program]
* ...that runs an EVM
## Overview
* [`cannon-mipsevm`](./crates/mipsevm) - Contains the native implementation of the MIPS thread context emulator.
* [`preimage-oracle`](./crates/preimage) - Rust bindings for interacting as client or sever over the Pre-image Oracle ABI.
* [`cannon-contracts`](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock/src/cannon) - [*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][cannon], built by [George Hotz][geohot] and members of the [OP Labs][op-labs] team. The original implementation is written in Go, and can be found [in the Optimism monorepo][cannon]. 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`](https://github.com/anton-rs/cannon-rs/pull/17/commits/71b68d52fb858cfc544c1430b482aeaef460552e).
| 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][rustup]
* Recommended: [`cargo-nextest`][nextest]
* [Go toolchain][golang]
* [binutils][binutils]
### Testing
```sh
# With `cargo-nextest`
cargo +nightly nextest run --release --all --all-features
# Without `cargo-nextest`
cargo +nightly t --release --all --all-features
```
### Linting and Formatting
```sh
cargo +nightly fmt --all -- && cargo +nightly clippy --all --all-features -- -D warnings
```
### Running Benchmarks
```sh
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][monorepo].
* [Cannon specification][cannon-specs]
* [Preimage oracle specification][fpp-specs]
## Docker
The docker image for `cannon-rs` is located in the [docker](./docker) directory, and can be built using the
script provided.
[geohot]: https://github.com/geohot
[op-labs]: https://oplabs.co
[monorepo]: https://github.com/ethereum-optimism/optimism
[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon
[op-program]: https://github.com/ethereum-optimism/optimism/tree/develop/op-program
[op-challenger]: https://github.com/ethereum-optimism/optimism/tree/develop/op-challenger
[rustup]: https://rustup.rs/
[golang]: https://go.dev/doc/install
[binutils]: https://www.gnu.org/software/binutils/
[nextest]: https://nexte.st/
[fpp-specs]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/fault-proof.md
[cannon-specs]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/cannon-fault-proof-vm.md