{"id":24075005,"url":"https://github.com/op-rs/cannon-rs","last_synced_at":"2025-05-01T09:16:53.692Z","repository":{"id":196399228,"uuid":"690858446","full_name":"op-rs/cannon-rs","owner":"op-rs","description":"An alternative implementation of the OP Stack's Cannon, a MIPS emulator for the EVM.","archived":false,"fork":false,"pushed_at":"2024-07-27T16:13:45.000Z","size":13741,"stargazers_count":63,"open_issues_count":8,"forks_count":11,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-01T09:16:47.963Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/op-rs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-13T02:58:59.000Z","updated_at":"2025-02-15T01:05:35.000Z","dependencies_parsed_at":"2024-07-20T19:43:17.785Z","dependency_job_id":"ca578f61-1287-4e1f-8e6b-45f1317d0d6a","html_url":"https://github.com/op-rs/cannon-rs","commit_stats":null,"previous_names":["anton-rs/cannon-rs","op-rs/cannon-rs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/op-rs%2Fcannon-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/op-rs%2Fcannon-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/op-rs%2Fcannon-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/op-rs%2Fcannon-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/op-rs","download_url":"https://codeload.github.com/op-rs/cannon-rs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251850182,"owners_count":21653978,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-09T18:34:29.584Z","updated_at":"2025-05-01T09:16:53.652Z","avatar_url":"https://github.com/op-rs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n\u003cimg src=\"./assets/banner.png\" alt=\"Cannon\" width=\"100%\" align=\"center\"\u003e\n\u003c/h1\u003e\n\n\u003ch4 align=\"center\"\u003e\n    An alternative implementation of the OP Stack's \u003ca href=\"https://github.com/ethereum-optimism/optimism/tree/develop/cannon\"\u003eCannon\u003c/a\u003e in Rust.\n\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/clabby/cannon-rs/actions/workflows/ci.yaml\"\u003e\n    \u003cimg src=\"https://github.com/clabby/cannon-rs/actions/workflows/ci.yaml/badge.svg?label=ci\" alt=\"Ci\"\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-green.svg?label=license\" alt=\"License\"\u003e\n  \u003ca href=\"https://github.com/ethereum-optimism/monorepo\"\u003e\u003cimg src=\"https://img.shields.io/badge/OP%20Stack-monorepo-red\" alt=\"OP Stack\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://t.me/+2yfSX0YikWMxNTRh\"\u003e\u003cimg src=\"https://img.shields.io/badge/Telegram-x?logo=telegram\u0026label=anton-rs%20contributors\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#whats-a-cannon\"\u003eWhat's a Cannon?\u003c/a\u003e •\n  \u003ca href=\"#overview\"\u003eOverview\u003c/a\u003e •\n  \u003ca href=\"#credits\"\u003eCredits\u003c/a\u003e •\n  \u003ca href=\"#benchmarks\"\u003eBenchmarks\u003c/a\u003e •\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e •\n  \u003ca href=\"#documentation\"\u003eDocumentation\u003c/a\u003e •\n  \u003ca href=\"#docker\"\u003eDocker\u003c/a\u003e\n\u003c/p\u003e\n\n## What's a Cannon?\n\nCannon 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]\n(also known as the fault-proof program) for the [OP Stack][monorepo]'s interactive dispute protocol. The `op-program` consists\nof a stripped down version of `op-geth`'s state transition code in addition to the derivation pipeline, and produces deterministic results.\nSubsequently, 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\nnative implementation of the MIPS thread context that mirrors the on-chain version, which enables the [op-challenger][op-challenger] to generate\nstate commitments for an `op-program` execution trace and participate in dispute games.\n\n*TL;DR:*\n* It's Rust code\n* ...that was [originally Go code][cannon]\n* ...that runs an EVM\n* ...emulating a MIPS machine\n* ...running [compiled Go code][op-program]\n* ...that runs an EVM\n\n## Overview\n* [`cannon-mipsevm`](./crates/mipsevm) - Contains the native implementation of the MIPS thread context emulator.\n* [`preimage-oracle`](./crates/preimage) - Rust bindings for interacting as client or sever over the Pre-image Oracle ABI.\n* [`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.\n\n## Credits\n\nThis 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\ncredits for the original idea and reference implementation of this concept go to these folks.\n\n## Benchmarks\n\n### `cannon-mipsevm` benchmarks\n\nThe below benchmark was ran on a 2021 Macbook Pro with an M1 Max and 32 GB of unified memory\non commit [`71b68d5`](https://github.com/anton-rs/cannon-rs/pull/17/commits/71b68d52fb858cfc544c1430b482aeaef460552e).\n\n| Benchmark Name             | `cannon` mean (Reference) | `cannon-rs` mean    |\n|----------------------------|---------------------------|---------------------|\n| Memory Merkle Root (25MB)  | 736.94 ms                 | 29.58 µs (-99%)     |\n| Memory Merkle Root (50MB)  | 1.54s                     | 7.25 ms (-99%)      |\n| Memory Merkle Root (100MB) | 3.34s                     | 273.76 ms (-91.8%)  |\n| Memory Merkle Root (200MB) | 6.30s                     | 1.65s (-73.81%)     |\n\n*todo - execution benchmarks*\n\n## Contributing\n\nTo get started, a few dependencies are required:\n* [Rust toolchain][rustup]\n    * Recommended: [`cargo-nextest`][nextest]\n* [Go toolchain][golang]\n* [binutils][binutils]\n\n### Testing\n\n```sh\n# With `cargo-nextest`\ncargo +nightly nextest run --release --all --all-features\n# Without `cargo-nextest`\ncargo +nightly t --release --all --all-features\n```\n\n### Linting and Formatting\n\n```sh\ncargo +nightly fmt --all -- \u0026\u0026 cargo +nightly clippy --all --all-features -- -D warnings\n```\n\n### Running Benchmarks\n\n```sh\ncargo +nightly bench --all --all-features\n```\n\n## Documentation\n\nRustdocs are available by running `cargo doc --open` after cloning the repo.\n\n### Specification\n\nThe specification for both Cannon and the preimage oracle can be found in the [Optimism monorepo][monorepo].\n* [Cannon specification][cannon-specs]\n* [Preimage oracle specification][fpp-specs]\n\n## Docker\n\nThe docker image for `cannon-rs` is located in the [docker](./docker) directory, and can be built using the\nscript provided.\n\n[geohot]: https://github.com/geohot\n[op-labs]: https://oplabs.co\n[monorepo]: https://github.com/ethereum-optimism/optimism\n[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon\n[op-program]: https://github.com/ethereum-optimism/optimism/tree/develop/op-program\n[op-challenger]: https://github.com/ethereum-optimism/optimism/tree/develop/op-challenger\n[rustup]: https://rustup.rs/\n[golang]: https://go.dev/doc/install\n[binutils]: https://www.gnu.org/software/binutils/\n[nextest]: https://nexte.st/\n[fpp-specs]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/fault-proof.md\n[cannon-specs]: https://github.com/ethereum-optimism/optimism/blob/develop/specs/cannon-fault-proof-vm.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fop-rs%2Fcannon-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fop-rs%2Fcannon-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fop-rs%2Fcannon-rs/lists"}