🚧 Add cannon lib crate

bin/Cargo.toml

@@ -14,12 +14,13 @@ tracing-subscriber = "0.3.17"
 anyhow = "1.0.75"
 serde = { version = "1.0.188", features = ["derive"] }
 serde_json = "1.0.107"
-alloy-primitives = "0.3.3"
+alloy-primitives = "0.4.0"
 tokio = { version = "1.32.0", features = ["macros"] }
 flate2 = "1.0.27"
 async-trait = "0.1.73"
 
 # Local
+cannon = { path = "../crates/cannon" }
 cannon-mipsevm = { path = "../crates/mipsevm" }
 preimage-oracle = { path = "../crates/preimage" }
 

bin/src/cannon.rs

@@ -3,7 +3,6 @@ use anyhow::{anyhow, Result};
 use clap::{ArgAction, Parser};
 use tracing::Level;
 
-mod compressor;
 mod subcommands;
 
 /// Comand line arguments for `cannon` binary

bin/src/subcommands/load_elf.rs

@@ -1,10 +1,9 @@
 //! The `load-elf` subcommand for the cannon binary
 
-use crate::compressor::compress_bytes;
-
 use super::CannonSubcommandDispatcher;
 use anyhow::Result;
 use async_trait::async_trait;
+use cannon::compressor::compress_bytes;
 use cannon_mipsevm::{load_elf, patch_go, patch_stack};
 use clap::{builder::PossibleValue, Args, ValueEnum};
 use std::{fs, path::PathBuf};

bin/src/subcommands/mod.rs

@@ -24,7 +24,6 @@ pub(crate) enum CannonSubcommand {
 
 #[async_trait]
 impl CannonSubcommandDispatcher for CannonSubcommand {
-    /// TODO(clabby): Dynamic dispatch on Box<dyn CannonSubcommandDispatcher>
     async fn dispatch(&self) -> Result<()> {
         match self {
             CannonSubcommand::Run(args) => args.dispatch().await,

bin/src/subcommands/witness.rs

@@ -1,10 +1,10 @@
 //! The `witness` subcommand for the cannon binary
 
 use super::CannonSubcommandDispatcher;
-use crate::compressor::decompress_bytes;
 use alloy_primitives::B256;
 use anyhow::Result;
 use async_trait::async_trait;
+use cannon::compressor::decompress_bytes;
 use cannon_mipsevm::{State, StateWitnessHasher};
 use clap::Args;
 use std::{fs, path::PathBuf};

crates/cannon/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "cannon"
+description = "An implementation of the OP Stack's native BE MIPS32 VM in Rust"
+edition = "2021"
+
+version.workspace = true
+authors.workspace = true
+
+[dependencies]
+# External
+tracing = "0.1.37"
+anyhow = "1.0.75"
+serde = { version = "1.0.188", features = ["derive"] }
+serde_json = "1.0.107"
+alloy-primitives = "0.4.0"
+tokio = { version = "1.32.0", features = ["macros"] }
+flate2 = "1.0.27"
+
+# Local
+cannon-mipsevm = { path = "../mipsevm" }
+preimage-oracle = { path = "../preimage" }
+
+[dev-dependencies]
+proptest = "1.2.0"

crates/cannon/src/builder.rs

@@ -0,0 +1,94 @@
+use crate::Kernel;
+
+/// The [KernelBuilder] struct is a helper for building a [Kernel] struct.
+pub struct KernelBuilder {
+    /// The path to the input JSON state.
+    input: String,
+    /// The path to the output JSON state.
+    output: Option<String>,
+    /// The step to generate an output proof at.
+    proof_at: Option<u64>,
+    /// Format for proof data output file names. Proof data is written to stdout
+    /// if this is not specified.
+    proof_format: Option<String>,
+    /// The step pattern to generate state snapshots at.
+    snapshot_at: Option<String>,
+    /// Format for snapshot data output file names.
+    snapshot_format: Option<String>,
+    /// The instruction step to stop running at.
+    stop_at: Option<u64>,
+    /// The pattern to print information at.
+    info_at: Option<String>,
+    /// An L1 RPC endpoint
+    l1_endpoint: String,
+    /// An L2 RPC endpoint
+    l2_endpoint: String,
+}
+
+impl KernelBuilder {
+    /// Builds the [Kernel] struct from the information contained within the [KernelBuilder].
+    pub fn build(self) -> Kernel {
+        Kernel::new(
+            self.input,
+            self.output,
+            self.proof_at,
+            self.proof_format,
+            self.snapshot_at,
+            self.snapshot_format,
+            self.stop_at,
+            self.info_at,
+            self.l1_endpoint,
+            self.l2_endpoint,
+        )
+    }
+
+    pub fn with_input(mut self, input: String) -> Self {
+        self.input = input;
+        self
+    }
+
+    pub fn with_output(mut self, output: String) -> Self {
+        self.output = Some(output);
+        self
+    }
+
+    pub fn with_proof_at(mut self, proof_at: u64) -> Self {
+        self.proof_at = Some(proof_at);
+        self
+    }
+
+    pub fn with_proof_format(mut self, proof_format: String) -> Self {
+        self.proof_format = Some(proof_format);
+        self
+    }
+
+    pub fn with_snapshot_at(mut self, snapshot_at: String) -> Self {
+        self.snapshot_at = Some(snapshot_at);
+        self
+    }
+
+    pub fn with_snapshot_format(mut self, snapshot_format: String) -> Self {
+        self.snapshot_format = Some(snapshot_format);
+        self
+    }
+
+    pub fn with_stop_at(mut self, stop_at: u64) -> Self {
+        self.stop_at = Some(stop_at);
+        self
+    }
+
+    pub fn with_info_at(mut self, info_at: String) -> Self {
+        self.info_at = Some(info_at);
+        self
+    }
+
+    pub fn with_l1_endpoint(mut self, l1_endpoint: String) -> Self {
+        self.l1_endpoint = l1_endpoint;
+        self
+    }
+
+    pub fn with_l2_endpoint(mut self, l2_endpoint: String) -> Self {
+        self.l2_endpoint = l2_endpoint;
+        self
+    }
+}

bin/src/compressor.rs → crates/cannon/src/compressor.rs

@@ -1,18 +1,18 @@
-//! This module contains utilities for compressing and decompressing serialized bytes.
+//! This module contains utilities for compressing and decompressing serialized bytes using gzip.
 
 use anyhow::Result;
 use flate2::{bufread::GzDecoder, write::GzEncoder, Compression};
 use std::io::{Read, Write};
 
 /// Compresses a byte slice using gzip.
-pub(crate) fn compress_bytes(bytes: &[u8]) -> Result<Vec<u8>> {
+pub fn compress_bytes(bytes: &[u8]) -> Result<Vec<u8>> {
     let mut encoder = GzEncoder::new(Vec::new(), Compression::best());
     encoder.write_all(bytes)?;
     Ok(encoder.finish()?)
 }
 
 /// Decompresses a byte slice using gzip.
-pub(crate) fn decompress_bytes(compressed_bytes: &[u8]) -> Result<Vec<u8>> {
+pub fn decompress_bytes(compressed_bytes: &[u8]) -> Result<Vec<u8>> {
     let mut decoder = GzDecoder::new(compressed_bytes);
 
     // Give our decompressed buffer the same capacity as the compressed buffer to reduce

crates/cannon/src/kernel.rs

@@ -0,0 +1,59 @@
+//! This module contains the [Kernel] struct and its associated methods.
+
+/// The [Kernel] struct contains the configuration for a Cannon kernel as well as
+/// the [PreimageOracle] and [InstrumentedState] instances that form it.
+#[allow(dead_code)]
+pub struct Kernel {
+    // ins_state: InstrumentedState,
+    // preimage_oracle: PreimageOracle,
+    /// The path to the input JSON state.
+    input: String,
+    /// The path to the output JSON state.
+    output: Option<String>,
+    /// The step to generate an output proof at.
+    proof_at: Option<u64>,
+    /// Format for proof data output file names. Proof data is written to stdout
+    /// if this is not specified.
+    proof_format: Option<String>,
+    /// The step pattern to generate state snapshots at.
+    snapshot_at: Option<String>,
+    /// Format for snapshot data output file names.
+    snapshot_format: Option<String>,
+    /// The instruction step to stop running at.
+    stop_at: Option<u64>,
+    /// The pattern to print information at.
+    info_at: Option<String>,
+    /// An L1 RPC endpoint
+    l1_endpoint: String,
+    /// An L2 RPC endpoint
+    l2_endpoint: String,
+}
+
+impl Kernel {
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        input: String,
+        output: Option<String>,
+        proof_at: Option<u64>,
+        proof_format: Option<String>,
+        snapshot_at: Option<String>,
+        snapshot_format: Option<String>,
+        stop_at: Option<u64>,
+        info_at: Option<String>,
+        l1_endpoint: String,
+        l2_endpoint: String,
+    ) -> Self {
+        Self {
+            input,
+            output,
+            proof_at,
+            proof_format,
+            snapshot_at,
+            snapshot_format,
+            stop_at,
+            info_at,
+            l1_endpoint,
+            l2_endpoint,
+        }
+    }
+}

crates/cannon/src/lib.rs

@@ -0,0 +1,9 @@
+#![doc = include_str!("../README.md")]
+
+mod builder;
+pub use builder::KernelBuilder;
+
+mod kernel;
+pub use kernel::Kernel;
+
+pub mod compressor;

crates/preimage/Cargo.toml

@@ -7,7 +7,7 @@ version.workspace = true
 authors.workspace = true
 
 [dependencies]
-alloy-primitives = "0.3.3"
+alloy-primitives = "0.4.0"
 once_cell = "1.18.0"
 serde = { version = "1.0.188", features = ["derive"] }
 serde_json = "1.0.106"