feat:zk core systems guest/host

Author: zacksfF

zkvm/guest/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "shadow-evm-guest"
+version = "0.1.0"
+edition = "2021"
+description = "RISC Zero guest program for Shadow-EVM ZK Coprocessor"
+
+[dependencies]
+# Core Shadow-EVM library with no_std
+shadow-evm-core = { path = "../../core", default-features = false }
+
+# RISC Zero guest SDK
+risc0-zkvm = { version = "1.2", default-features = false }
+
+[profile.release]
+opt-level = 3
+lto = true

zkvm/guest/src/evm/executor.rs

@@ -0,0 +1,29 @@
+//! ZK Executor for guest execution
+//!
+//! Wraps the core ShadowExecutor for use inside the ZK-VM guest.
+
+use shadow_evm_core::prelude::*;
+
+/// ZK Executor wrapper
+///
+/// Provides a streamlined interface for executing EVM transactions
+/// inside the ZK-VM and generating commitments.
+pub struct ZkExecutor;
+
+impl ZkExecutor {
+    /// Execute a transaction and return the commitment
+    ///
+    /// This is the main entry point for ZK execution.
+    /// It takes an ExecutionInput and returns either:
+    /// - Ok((output, commitment)) on success
+    /// - Err(error) on failure
+    ///
+    /// # ZK Properties
+    /// - Execution is deterministic
+    /// - Same input always produces same output
+    /// - Commitment binds input to output cryptographically
+    pub fn execute(input: ExecutionInput) -> Result<(ExecutionOutput, ExecutionCommitment)> {
+        // Use the core executor
+        ShadowExecutor::execute(input)
+    }
+}

zkvm/guest/src/evm/host_io.rs

@@ -0,0 +1,33 @@
+//! Host I/O helpers for RISC Zero guest
+//!
+//! Provides functions for reading inputs from the host and
+//! committing outputs to the journal.
+
+use risc0_zkvm::guest::env;
+use shadow_evm_core::prelude::*;
+
+/// Read ExecutionInput from the host
+///
+/// Deserializes the execution input that was provided by the host.
+/// This input contains:
+/// - Block environment (number, timestamp, gas limit, etc.)
+/// - Transaction input (caller, to, value, data, etc.)
+/// - Pre-execution state
+pub fn read_input() -> ExecutionInput {
+    env::read()
+}
+
+/// Commit the execution commitment to the journal
+///
+/// The journal is the public output of the ZK proof.
+/// Anyone can read the journal after verification.
+///
+/// We commit the ExecutionCommitment which contains:
+/// - Input hash
+/// - Output hash  
+/// - Pre-state root
+/// - Post-state root
+/// - Combined commitment
+pub fn commit_output(commitment: &ExecutionCommitment) {
+    env::commit(commitment);
+}

zkvm/guest/src/evm/mod.rs

@@ -0,0 +1,11 @@
+//! EVM execution module for ZKVM guest
+//!
+//! This module provides the EVM execution logic that runs inside the RISC-V ZK-VM.
+
+pub mod executor;
+pub mod host_io;
+pub mod state;
+
+// Re-exports
+pub use executor::ZkExecutor;
+pub use host_io::{commit_output, read_input};

zkvm/guest/src/evm/state.rs

@@ -0,0 +1,59 @@
+//! ZK-compatible state wrapper
+//!
+//! Provides a wrapper around the core InMemoryDB that ensures
+//! all state operations are deterministic and ZK-friendly.
+
+use shadow_evm_core::prelude::*;
+
+/// ZK-compatible state wrapper
+///
+/// This wrapper ensures all state operations are deterministic
+/// and suitable for execution inside a ZK-VM.
+pub struct ZkState {
+    /// The underlying in-memory database
+    db: InMemoryDB,
+}
+
+impl ZkState {
+    /// Create a new ZK state from an InMemoryDB
+    pub fn new(db: InMemoryDB) -> Self {
+        Self { db }
+    }
+
+    /// Get the underlying database
+    pub fn into_db(self) -> InMemoryDB {
+        self.db
+    }
+
+    /// Get a reference to the underlying database
+    pub fn db(&self) -> &InMemoryDB {
+        &self.db
+    }
+
+    /// Get a mutable reference to the underlying database
+    pub fn db_mut(&mut self) -> &mut InMemoryDB {
+        &mut self.db
+    }
+
+    /// Compute the state root
+    pub fn state_root(&self) -> Hash {
+        self.db.compute_state_root()
+    }
+
+    /// Verify the state root matches expected value
+    pub fn verify_root(&self, expected: &Hash) -> bool {
+        self.state_root() == *expected
+    }
+}
+
+impl From<InMemoryDB> for ZkState {
+    fn from(db: InMemoryDB) -> Self {
+        Self::new(db)
+    }
+}
+
+impl From<ZkState> for InMemoryDB {
+    fn from(state: ZkState) -> Self {
+        state.into_db()
+    }
+}

zkvm/guest/src/main.rs

@@ -0,0 +1,59 @@
+//! Shadow-EVM ZKVM Guest Entry Point
+//!
+//! This is the main program that runs inside the RISC-V ZK-VM.
+//! It reads an ExecutionInput from the host, executes the EVM transaction,
+//! and commits the ExecutionCommitment to the journal.
+//!
+//! # Flow
+//! 1. Host serializes ExecutionInput and passes it to the guest
+//! 2. Guest deserializes and executes using ShadowExecutor
+//! 3. Guest computes ExecutionCommitment
+//! 4. Guest commits the commitment to the journal
+//! 5. Prover generates a proof of correct execution
+//!
+//! # Public Output (Journal)
+//! The journal contains the ExecutionCommitment which includes:
+//! - input_hash: Hash of the execution input
+//! - output_hash: Hash of the execution output
+//! - pre_state_root: Merkle root of pre-execution state
+//! - post_state_root: Merkle root of post-execution state
+//! - commitment: Combined cryptographic commitment
+
+#![no_main]
+#![no_std]
+
+extern crate alloc;
+
+mod evm;
+mod types;
+
+use evm::{commit_output, read_input, ZkExecutor};
+
+risc0_zkvm::guest::entry!(main);
+
+/// Guest main entry point
+///
+/// This function is called when the ZK-VM starts executing.
+/// Any panic will cause the proof generation to fail.
+fn main() {
+    // Step 1: Read the execution input from the host
+    let input = read_input();
+
+    // Step 2: Execute the EVM transaction
+    // This uses the core ShadowExecutor which wraps revm
+    let result = ZkExecutor::execute(input);
+
+    // Step 3: Handle the result and commit to journal
+    match result {
+        Ok((_output, commitment)) => {
+            // Commit the execution commitment to the journal
+            // This becomes the public output of the ZK proof
+            commit_output(&commitment);
+        }
+        Err(_err) => {
+            // Execution failed - panic to abort proof generation
+            // The host should validate inputs before proving
+            panic!("EVM execution failed");
+        }
+    }
+}

zkvm/guest/src/types.rs

@@ -0,0 +1,11 @@
+//! Type re-exports for ZKVM guest
+//!
+//! Re-exports all types from shadow-evm-core for convenient use in the guest.
+
+#![allow(unused_imports)]
+
+// Re-export all core types
+pub use shadow_evm_core::prelude::*;
+
+// Re-export additional types that might be needed
+pub use shadow_evm_core::{compute_commitment, hash_struct, keccak256, VERSION};

zkvm/host/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "shadow-evm-host"
+version = "0.1.0"
+edition = "2021"
+description = "RISC Zero host program for Shadow-EVM ZK Coprocessor"
+
+[dependencies]
+# Core Shadow-EVM library
+shadow-evm-core = { path = "../../core" }
+
+# RISC Zero host SDK
+risc0-zkvm = { version = "1.2" }
+
+# Serialization
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+bincode = "1.3"
+
+# CLI
+clap = { version = "4.0", features = ["derive"] }
+
+# Async runtime
+tokio = { version = "1", features = ["full"] }
+
+# Error handling
+anyhow = "1.0"
+
+# Hex encoding for display
+hex = "0.4"
+
+[build-dependencies]
+risc0-build = { version = "1.2" }

zkvm/host/build.rs

@@ -0,0 +1,13 @@
+//! Build script for Shadow-EVM host
+//!
+//! Compiles the guest program and generates the methods.rs file
+//! containing the ELF binary and image ID.
+
+fn main() {
+    // Tell Cargo to rerun if guest code changes
+    println!("cargo:rerun-if-changed=../guest/src");
+    println!("cargo:rerun-if-changed=../guest/Cargo.toml");
+
+    // Build the guest program
+    risc0_build::embed_methods();
+}

zkvm/host/src/io.rs

@@ -0,0 +1,93 @@
+//! I/O utilities for the host
+//!
+//! Handles serialization/deserialization of inputs and outputs
+//! for communication with the guest and external systems.
+
+use anyhow::{Context, Result};
+use shadow_evm_core::prelude::*;
+use std::fs;
+use std::path::Path;
+
+/// Serialize ExecutionInput to bytes
+pub fn serialize_input(input: &ExecutionInput) -> Result<Vec<u8>> {
+    bincode::serialize(input).context("Failed to serialize ExecutionInput")
+}
+
+/// Deserialize ExecutionInput from bytes
+pub fn deserialize_input(data: &[u8]) -> Result<ExecutionInput> {
+    bincode::deserialize(data).context("Failed to deserialize ExecutionInput")
+}
+
+/// Serialize ExecutionCommitment to bytes
+pub fn serialize_commitment(commitment: &ExecutionCommitment) -> Result<Vec<u8>> {
+    bincode::serialize(commitment).context("Failed to serialize ExecutionCommitment")
+}
+
+/// Deserialize ExecutionCommitment from bytes
+pub fn deserialize_commitment(data: &[u8]) -> Result<ExecutionCommitment> {
+    bincode::deserialize(data).context("Failed to deserialize ExecutionCommitment")
+}
+
+/// Save ExecutionInput to a JSON file
+pub fn save_input_json<P: AsRef<Path>>(input: &ExecutionInput, path: P) -> Result<()> {
+    let json = serde_json::to_string_pretty(input)?;
+    fs::write(path, json)?;
+    Ok(())
+}
+
+/// Load ExecutionInput from a JSON file
+pub fn load_input_json<P: AsRef<Path>>(path: P) -> Result<ExecutionInput> {
+    let json = fs::read_to_string(path)?;
+    let input: ExecutionInput = serde_json::from_str(&json)?;
+    Ok(input)
+}
+
+/// Save binary data to a file
+pub fn save_bytes<P: AsRef<Path>>(data: &[u8], path: P) -> Result<()> {
+    fs::write(path, data)?;
+    Ok(())
+}
+
+/// Load binary data from a file
+pub fn load_bytes<P: AsRef<Path>>(path: P) -> Result<Vec<u8>> {
+    let data = fs::read(path)?;
+    Ok(data)
+}
+
+/// Format a hash as a hex string
+pub fn format_hash(hash: &Hash) -> String {
+    format!("0x{}", hex::encode(hash.as_slice()))
+}
+
+/// Format commitment for display
+pub fn format_commitment(commitment: &ExecutionCommitment) -> String {
+    format!(
+        "ExecutionCommitment {{\n  \
+         input_hash: {},\n  \
+         output_hash: {},\n  \
+         pre_state_root: {},\n  \
+         post_state_root: {},\n  \
+         commitment: {}\n\
+         }}",
+        format_hash(&commitment.input_hash),
+        format_hash(&commitment.output_hash),
+        format_hash(&commitment.pre_state_root),
+        format_hash(&commitment.post_state_root),
+        format_hash(&commitment.commitment),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_serialize_roundtrip() {
+        let input = ExecutionInput::new(BlockEnv::default(), TxInput::default(), InMemoryDB::new());
+
+        let bytes = serialize_input(&input).unwrap();
+        let decoded = deserialize_input(&bytes).unwrap();
+
+        assert_eq!(input.hash(), decoded.hash());
+    }
+}