refactor: Remove legacy code and unnecessary pickle support (v0.2.0)

Major cleanup and simplification:
- Remove all pickle support from PyO3 classes (unused complexity)
- Delete serialization.rs (was only for pickle support)
- Remove legacy compatibility methods:
  - journal_bytes() (use journal property instead)
  - image_id property (use id property instead)
  - ed25519_input_vecs() (use ed25519_input() instead)
- Clean up serialization helpers:
  - Remove incompatible merkle_proof_input() for env::read() style
  - Keep merkle_commitment_input() for 2LA-style demo
- Update demos to use serialization helpers properly

Benefits:
- Smaller codebase with less maintenance burden
- Clearer separation between Rust and Python code
- No confusing duplicate methods or unused features
- Demos now properly test the serialization helpers

Breaking changes from v0.1.0:
- Removed pickle support (use standard serialization if needed)
- Removed deprecated method aliases

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: nyc432

Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "pyr0"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 
 [lib]

README.md

@@ -1,11 +1,11 @@
 # PyR0 - Python Interface for RISC Zero zkVM
 
-[![Version](https://img.shields.io/badge/version-0.1.0-orange)](https://github.com/garyrob/PyR0/releases)
+[![Version](https://img.shields.io/badge/version-0.2.0-orange)](https://github.com/garyrob/PyR0/releases)
 **⚠️ Experimental Alpha - Apple Silicon Only**
 
 Python bindings for [RISC Zero](https://www.risczero.com/) zkVM, enabling zero-knowledge proof generation and verification from Python.
 
-> **Note**: This is an experimental alpha release (v0.1.0) currently targeting Apple Silicon (M1/M2/M3) Macs only.
+> **Note**: This is an experimental alpha release (v0.2.0) currently targeting Apple Silicon (M1/M2/M3) Macs only.
 
 ## Overview
 
@@ -15,6 +15,20 @@ PyR0 provides a Python interface to RISC Zero's zero-knowledge virtual machine,
 - Build Merkle trees with Poseidon hash for ZK circuits
 - Serialize data for guest program inputs
 
+### Architecture
+
+PyR0 bridges Python and RISC Zero zkVM:
+
+1. **Host (Python)**: Prepares input data, loads guest programs, generates proofs
+2. **Guest (Rust)**: Executes in zkVM, reads input, writes output to journal
+3. **Proof**: Cryptographic evidence that the guest executed correctly
+
+The typical workflow:
+1. Write a Rust guest program that performs your computation
+2. Compile it to RISC-V ELF binary
+3. Use PyR0 to load the ELF, provide input, and generate a proof
+4. Share the proof and journal (public outputs) for verification
+
 ## Installation
 
 ### System Requirements
@@ -94,23 +108,100 @@ hash_result = merkle_py.poseidon_hash([input1, input2])
 
 ### Data Serialization
 
-Prepare data for RISC Zero guest programs:
+PyR0 provides serialization helpers for sending data to RISC Zero guest programs. The choice of serialization method depends on how your guest reads the data:
+
+#### For Guests Using `env::read()`
+
+These helpers add length prefixes and are designed for serde deserialization:
 
 ```python
 from pyr0 import serialization
 
-# Optional serialization helpers for guest programs
+# These work with env::read() in the guest
 data = serialization.to_vec_u8(bytes_data)  # Vec<u8> with length prefix
-data = serialization.to_u32(value)          # 32-bit unsigned integer
-data = serialization.to_u64(value)          # 64-bit unsigned integer
-data = serialization.to_string(text)        # String with length prefix
-data = serialization.to_bool(value)         # Boolean value
-data = serialization.to_bytes32(data)       # Fixed [u8; 32] array
-data = serialization.to_bytes64(data)       # Fixed [u8; 64] array
-
-# Convenience functions for common patterns
+data = serialization.to_u32(value)          # u32 (4 bytes, little-endian)
+data = serialization.to_u64(value)          # u64 (8 bytes, little-endian)
+data = serialization.to_string(text)        # String with 8-byte length prefix
+data = serialization.to_bool(value)         # bool (single byte: 0 or 1)
+
+# Guest code would use:
+# let data: Vec<u8> = env::read();
+# let value: u32 = env::read();
+# let text: String = env::read();
+```
+
+#### For Guests Using `env::read_slice()`
+
+These helpers provide raw bytes without length prefixes:
+
+```python
+# Fixed-size arrays (no length prefix)
+data = serialization.to_bytes32(data)       # [u8; 32] - exactly 32 bytes
+data = serialization.to_bytes64(data)       # [u8; 64] - exactly 64 bytes
+data = serialization.raw_bytes(data)        # Raw bytes, no transformation
+
+# Guest code would use:
+# let mut buffer = [0u8; 32];
+# env::read_slice(&mut buffer);
+```
+
+#### Convenience Functions
+
+Pre-built serializers for common cryptographic operations:
+
+```python
+# For Ed25519 signature verification (uses env::read() format)
 input_data = serialization.ed25519_input(public_key, signature, message)
-input_data = serialization.merkle_proof_input(leaf, siblings, indices)
+
+# For Merkle proofs with 2LA-style commitments (uses env::read_slice() format)
+# Note: Expects exactly 16 siblings for a 16-level tree
+input_data = serialization.merkle_commitment_input(k_pub, r, e, siblings, indices)
+```
+
+#### Choosing Between `env::read()` and `env::read_slice()`
+
+**Use `env::read()` when:**
+- Data sizes are variable
+- You want automatic deserialization
+- You're using standard Rust types (Vec, String, etc.)
+- You don't know the exact size in advance
+
+**Use `env::read_slice()` when:**
+- Data size is fixed and known
+- You want maximum efficiency (no overhead)
+- You're working with raw bytes
+- You want to avoid serde overhead
+
+**Example: Sending mixed data types**
+
+```python
+# Python host code
+from pyr0 import serialization
+
+# Combine different serialization methods
+input_data = b""
+input_data += serialization.to_u32(42)           # 4 bytes (for env::read)
+input_data += serialization.to_bytes32(key)      # 32 bytes (for env::read_slice)
+input_data += serialization.to_string("hello")   # Variable (for env::read)
+
+receipt = pyr0.prove(image, input_data)
+```
+
+```rust
+// Rust guest code
+use risc0_zkvm::guest::env;
+
+fn main() {
+    // Read the u32 with serde
+    let number: u32 = env::read();
+    
+    // Read the fixed array with read_slice
+    let mut key = [0u8; 32];
+    env::read_slice(&mut key);
+    
+    // Read the string with serde
+    let text: String = env::read();
+}
 ```
 
 ### Journal Deserialization
@@ -166,6 +257,60 @@ PyR0/
 └── CLAUDE.md         # Development notes
 ```
 
+## Common Pitfalls
+
+### Serialization Mismatches
+
+The most common error is mismatched serialization between host and guest:
+
+```python
+# WRONG: Host uses to_vec_u8 (adds length prefix)
+input_data = serialization.to_vec_u8(my_bytes)
+```
+
+```rust
+// WRONG: Guest uses read_slice (expects raw bytes)
+let mut buffer = [0u8; 32];
+env::read_slice(&mut buffer);  // Will read length prefix as data!
+```
+
+**Solution**: Match serialization methods:
+- `to_vec_u8()` ↔ `env::read::<Vec<u8>>()`
+- `to_bytes32()` or `raw_bytes()` ↔ `env::read_slice()`
+
+### Size Mismatches
+
+When using `env::read_slice()`, the buffer size must match exactly:
+
+```rust
+// Guest expects exactly 100 bytes
+let mut buffer = [0u8; 100];
+env::read_slice(&mut buffer);
+```
+
+```python
+# Host must send exactly 100 bytes
+input_data = serialization.raw_bytes(b"x" * 100)  # Correct
+input_data = serialization.raw_bytes(b"x" * 99)   # Wrong - too short!
+```
+
+### Journal Format
+
+The journal (public output) should use a consistent serialization format. We recommend Borsh for cross-language compatibility:
+
+```rust
+// Guest: Write with Borsh
+use borsh::BorshSerialize;
+let output = MyOutput { ... };
+env::commit_slice(&borsh::to_vec(&output)?);
+```
+
+```python
+# Host: Read with Borsh
+from borsh_construct import CStruct
+output = OutputSchema.parse(receipt.journal)
+```
+
 ## Development
 
 This project uses [maturin](https://www.maturin.rs/) for building Python extensions from Rust. Key commands:
@@ -174,12 +319,23 @@ This project uses [maturin](https://www.maturin.rs/) for building Python extensi
 # Build release wheel
 uv tool run maturin build --release
 
+# Install the built wheel (force reinstall to avoid cache issues)
+uv pip install --force-reinstall target/wheels/PyR0-0.2.0-*.whl
+
 # Run tests/demos
 uv run demo/ed25519_demo.py
 uv run demo/merkle_zkp_demo.py
 uv run test/test_merkle_zkp.py
 ```
 
+### Important Build Notes
+
+After making changes to ANY file (Rust or Python), you must rebuild and reinstall:
+1. Build: `uv tool run maturin build --release`
+2. Install: `uv pip install --force-reinstall target/wheels/PyR0-*.whl`
+
+The `--force-reinstall` flag is crucial to ensure you're using the latest version.
+
 ## Acknowledgments
 
 This project is based on the original [PyR0](https://github.com/l2iterative/pyr0prover-python) by L2 Iterative, which focused on distributed proof generation using Dask/Ray. The current fork extends PyR0 with additional features for zero-knowledge proof development, including Merkle tree support and improved guest program interfaces.

demo/merkle_zkp_demo.py

@@ -144,22 +144,18 @@ def run_zkp_proof(selected_user, merkle_siblings, merkle_bits, tree_root):
         print(f"  e:     0x{selected_user['e'].hex()[:16]}... (secret!)")
         print(f"  Merkle path: {len(merkle_siblings)} siblings (secret!)")
 
-        # Prepare input for the guest program - now using raw bytes
-        # Guest uses env::read_slice() for efficient reading
-        input_data = b""
+        # Use the serialization helper to prepare input
+        # This creates the exact format expected by the guest program
+        from pyr0 import serialization
 
-        # k_pub, r, e - raw 32 bytes each
-        input_data += selected_user['k_pub']
-        input_data += selected_user['r']
-        input_data += selected_user['e']
-        
-        # Path siblings - 16 * 32 bytes
-        for sibling in merkle_siblings:
-            input_data += sibling
-        
-        # Indices - 16 bytes (one byte per bit)
-        for bit in merkle_bits:
-            input_data += bytes([1 if bit else 0])
+        # Use the merkle commitment helper for guests using env::read_slice()
+        input_data = serialization.merkle_commitment_input(
+            selected_user['k_pub'],
+            selected_user['r'],
+            selected_user['e'],
+            merkle_siblings,
+            merkle_bits
+        )
 
         # Debug: Check the data
         print(f"\nDebug - Input data size: {len(input_data)} bytes")

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "PyR0"
-version = "0.1.0"
+version = "0.2.0"
 authors = [
     { name = "Weikeng Chen", email = "weikeng.chen@l2iterative.com" }
 ]

src/image.rs

@@ -1,4 +1,3 @@
-use crate::serialization::Pickleable;
 use anyhow::Result;
 use pyo3::prelude::*;
 use risc0_binfmt::{MemoryImage, Program};
@@ -29,7 +28,6 @@ impl Image {
     }
 }
 
-impl Pickleable for Image {}
 
 #[pymethods]
 impl Image {
@@ -51,19 +49,5 @@ impl Image {
             ))
         }
     }
-    
-    /// Legacy alias for compatibility
-    #[getter]
-    fn image_id(&self) -> PyResult<Vec<u8>> {
-        self.id()
-    }
 
-    fn __getstate__(&self, py: Python<'_>) -> PyResult<PyObject> {
-        self.to_bytes(py)
-    }
-
-    fn __setstate__(&mut self, py: Python<'_>, state: PyObject) -> PyResult<()> {
-        *self = Self::from_bytes(state, py)?;
-        Ok(())
-    }
 }

src/lib.rs

@@ -1,7 +1,6 @@
 mod image;
 mod receipt;
 mod segment;
-mod serialization;
 mod session;
 mod succinct;