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

• [x] Rust build system for Cannon MIPS target (no_std)
• [x] Heap implementation
• [x] Guest<->Host Communication
  • [x] stdout
  • [x] Request data via Preimage Oracle
  • [x] Hints
• [x] Template for bootstrapping own projects
• [x] Preimage Server
  • [x] Server compatible with Optimism Cannon emulator
  • [x] 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 - willemolding@gmail.com

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