badboilabs / cannon-rs

Tooling to develop and emulate verifyable programs compatible with Optimism Cannon and the OP Stack 🦀🎆

Cannon-rs

A comprehensive collection of crates and tools to support development of Cannon programs in Rust

Thinking about contributing? There are bounties available for meaningful contributions via our OnlyDust page!

About The Project

Cannon-rs aims to support the emerging number of projects using Rust to develop provable programs for Optimism Cannon. This is the evolution of the rust-cannon-template supported by the Optimism RetroPGF round 2.

Advantages of using Rust are:

• Code Reuse - Take advantage of existing, trusted crates in the crypto ecosystem
• Compact Binaries - Cannon programs built using Rust are much smaller than their Golang equivalents
• Proving Speed - Generating proofs through emulation for large programs can be slow. Effective use of Rust can reduce the length of the program trace required speeding up the proving process

The project itself provides a number of tools to enable this:

Build system using Docker

Although MIPS is a standard Rust target the specific configuration needed to support the Cannon ISA is quite different. Cannon-rs provides a custom Rust target and a Docker image configured to build elf files which can be patched to run within Cannon.

Guest<->Host Communication

Cannon uses syscalls for communication between the guest program and the host. The cannon-io crate exposes a simple and safe wrapper around the low level syscalls to allow printing to stdout, retrieving data via the pre-image oracle and safely terminating a program with an exit code.

Preimage Server

The Optimism Cannon emulator uses custom IO streams to communicate with a child process responsible for retrieving preimage data given its key. The Cannon preimage server implementation is geared toward providing access to the Ethereum data required for rollup execution.

Cannon-rs provides a simple CLI tool for serving preimages stored in a JSON file. This can be extended with new implementations of the PreimageProvider trait in order to provide a tool suited to your application.

Cargo Cannon tool (WIP)

Makes generating and building new Cannon projects as easy as:

cargo cannon new
cargo cannon build

Prerequisites

Cross compiling for Cannon requires:

• Docker
• Just (cargo install just)

Getting Started

1. Copy the project-template from this repo to get started
2. Build something awesome in Rust 🦀
3. Build for Cannon using just build

Roadmap

• Rust build system for Cannon MIPS target (no_std)
• Heap implementation
• Guest<->Host Communication
  • stdout
  • Request data via Preimage Oracle
  • Hints
• Template for bootstrapping own projects
• Preimage Server
  • Server compatible with Optimism Cannon emulator
  • Serve preimages from JSON file
• cargo cannon tooling
  • cargo cannon build to wrap docker cross-compilation
  • cargo cannon new to create new Cannon projects

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are very welcome! To contribute please

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

A huge thanks to all existing contributors from the community!!

Used By

License

Distributed under the LGPL-3 License. See LICENSE for more information.

Contact

Willem Olding - @willemolding1 - [email protected]

Project Link: https://github.com/BadBoiLabs/Cannon-rs

cannon-rs's Issues

`cargo cannon new` command

Add a command to the cargo-cannon CLI tool that bootstraps a new cannon-rs project.

This should use a template taken from this repo and fill it with user-defined info

A great example that this could basically copy is cargo-risc0 new.

Write `cargo cannon new` command to generate new projects from template

Currently the cargo cannon new command is stubbed. Ideally we want this to grab the template from this repo and populate it in a similar way to cargo template.

Add support for hints

The Cannon-vm supports hints as an optional way for the guest program to communicate with the host. It has no effect in the on-chain VM.

This is used in Optimism for example to allow the guest to advise the host to pre-fetch certain pieces of chain data early in execution rather than when it is needed via the pre-image oracle.

Cannon-rs currently does not support the hint syscalls and these should be added for full support.

Write `cargo cannon build` command

Currently the cargo cannon build command is stubbed.

This command should build the project as defined by the cargo arguments (e.g. package, workspace) using the cannon-rs/builder docker image. This image should be retrieved if needed.

See cargo cross for examples of cross-compiling using docker as a cargo extension