refactor: Complete API refinement for cleaner, more Pythonic interface (v0.1.0)

Major API improvements:
- Add unified prove() function combining execution and proof generation
- Remove prepare_input() - prove() now accepts bytes directly
- Switch guests to env::read_slice() for efficient byte reading
- Make journal and other data accessible as properties (not methods)
- Clean up naming: image.id instead of image.image_id
- Remove redundant verify_proof() in favor of receipt.verify()
- Move serialization helpers to optional pyr0.serialization module

Benefits:
- Simpler one-step proof generation: prove(image, input_bytes)
- More Pythonic property-based access: receipt.journal, image.id
- Direct byte handling without wrapper functions
- Optional serialization helpers for common patterns
- Reduced API surface area while maintaining full functionality

Both Merkle ZKP and Ed25519 demos updated and working with new API.

This release marks the transition from pre-alpha to alpha status.

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

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

Author: nyc432

CLAUDE.md

@@ -1,5 +1,27 @@
 # Claude Development Notes
 
+## Essential Development Workflow
+
+**After ANY changes to Rust code (src/*.rs):**
+
+```bash
+# 1. Build the wheel
+uv tool run maturin build --release
+# Maturin will output: "📦 Built wheel for CPython 3.12 to /path/to/PyR0-X.X.X-cp312-cp312-platform.whl"
+
+# 2. Force reinstall (CRITICAL - must use --force-reinstall)
+# Option A: Use the * wildcard to match the latest built wheel
+uv pip install --force-reinstall target/wheels/PyR0-*.whl
+
+# Option B: Copy the exact filename from maturin's output
+# Example: uv pip install --force-reinstall target/wheels/PyR0-0.1.0-cp312-cp312-macosx_11_0_arm64.whl
+```
+
+**Why --force-reinstall is required:**
+- Without it, uv uses cached versions even after rebuilding
+- Changes won't take effect without forcing reinstallation
+- This is the #1 cause of "changes not working" issues
+
 ## Using PyO3 with uv - Key Steps
 
 ### Setup
@@ -84,7 +106,7 @@ uv tool run maturin develop
 uv tool run maturin build --release
 
 # Step 2: Force reinstall (IMPORTANT: use --force-reinstall to override cache)
-uv pip install --force-reinstall target/wheels/PyR0-0.2.0-cp312-cp312-macosx_11_0_arm64.whl
+uv pip install --force-reinstall target/wheels/PyR0-*.whl
 
 # Alternative (slower but automatic):
 uv sync --no-editable
@@ -137,7 +159,7 @@ print(dir(pyr0))  # Should show 'serialization' if properly installed
    - `pyproject.toml` - the `version = "x.x.x"` line
    - `Cargo.toml` - the `version = "x.x.x"` line  
    - `README.md` - the version badge and any version references
-3. Include version in commit message (e.g., "Add feature X (v0.0.4)")
+3. Include version in commit message (e.g., "Add feature X (v0.1.0)")
 4. Create and push a git tag:
    ```bash
    git tag -a vX.X.X -m "Description of changes"

Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "pyr0"
-version = "0.0.4"
+version = "0.1.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.0.4-orange)](https://github.com/garyrob/PyR0/releases)
-**⚠️ Experimental Pre-Alpha - Apple Silicon Only**
+[![Version](https://img.shields.io/badge/version-0.1.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 pre-alpha release (v0.0.4) currently targeting Apple Silicon (M1/M2/M3) Macs only.
+> **Note**: This is an experimental alpha release (v0.1.0) currently targeting Apple Silicon (M1/M2/M3) Macs only.
 
 ## Overview
 
@@ -52,20 +52,20 @@ import pyr0
 # Load a RISC Zero guest program
 with open("guest_program.elf", "rb") as f:
     elf_data = f.read()
-image = pyr0.load_image(elf_data)  # Simplified name
+image = pyr0.load_image(elf_data)
 
-# Execute with input
-input_data = pyr0.prepare_input(b"your input data")
-segments, info = pyr0.execute_with_input(image, input_data)
+# One-step proof generation (execution + proof)
+input_data = b"your input data"  # Direct bytes, no wrapper needed
+receipt = pyr0.prove(image, input_data)
 
-# Generate a proof
-receipt = pyr0.generate_proof(segments[0])  # Clearer name
-
-# Get the journal (public outputs) from the receipt
-journal = receipt.journal_bytes()
+# Get the journal (public outputs) as a property
+journal = receipt.journal
 
 # Verify the proof
-pyr0.verify_proof(receipt)  # Consistent naming
+receipt.verify()
+
+# Access the image ID
+image_id = image.id
 ```
 
 ### Merkle Trees with Poseidon Hash
@@ -99,7 +99,7 @@ Prepare data for RISC Zero guest programs:
 ```python
 from pyr0 import serialization
 
-# Serialize various data types for guest programs
+# Optional serialization helpers for guest programs
 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
@@ -108,8 +108,9 @@ 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
 
-# Prepare Ed25519 signature verification input
-input_data = serialization.ed25519_input_vecs(public_key, signature, message)
+# Convenience functions for common patterns
+input_data = serialization.ed25519_input(public_key, signature, message)
+input_data = serialization.merkle_proof_input(leaf, siblings, indices)
 ```
 
 ### Journal Deserialization
@@ -126,7 +127,7 @@ OutputSchema = CStruct(
 )
 
 # Parse journal from receipt
-journal = receipt.journal_bytes()
+journal = receipt.journal  # Access as property
 output = OutputSchema.parse(journal)
 ```
 

demo/ed25519_demo.py

@@ -15,19 +15,7 @@
 
 # Debug: check what we actually imported
 print(f"Imported pyr0 from: {pyr0.__file__}")
-print(f"Using new API: {hasattr(pyr0, 'load_image')}")
-if not hasattr(pyr0.Image, 'image_id'):
-    print("\n❌ ERROR: Using outdated pyr0 version without image_id support")
-    print(f"   Currently importing from: {pyr0.__file__}")
-    if "/src/pyr0/" in pyr0.__file__:
-        print("\n   PROBLEM: You're importing from the source directory (editable install)")
-        print("   This happens because uv installs projects in editable mode by default.")
-        print("\n   TO FIX: Run 'uv sync --no-editable' to build and install the compiled package")
-        print("   This will build the Rust extension with the latest features.\n")
-    else:
-        print("\n   The installed package appears to be outdated.")
-        print("   TO FIX: Rebuild with 'uv sync --no-editable'\n")
-    sys.exit(1)
+print(f"Using new API: {hasattr(pyr0, 'prove')}")
 
 # Constants
 GUEST_DIR = Path(__file__).parent / "ed25519_demo_guest"
@@ -74,7 +62,7 @@
 print("✓ ELF loaded into image")
 
 # Get and display the program's unique ID
-PROGRAM_ID = image.image_id.hex()
+PROGRAM_ID = image.id.hex()
 print(f"✓ Program ID: {PROGRAM_ID[:16]}...{PROGRAM_ID[-16:]}")
 print(f"  (Full ID: {PROGRAM_ID})")
 
@@ -84,17 +72,18 @@
 sig_bytes = bytes.fromhex(VALID_SIG)
 msg_bytes = MESSAGE.encode('utf-8')
 
-# Use the new serialization approach - Python handles the format
-# This creates three Vec<u8> values as expected by the guest
-input_data = pyr0.prepare_input(
-    serialization.ed25519_input_vecs(pk_bytes, sig_bytes, msg_bytes)
-)
+# Use the new API - prove() accepts bytes directly
+# The serialization helper creates the proper format for the guest
+input_data = serialization.ed25519_input(pk_bytes, sig_bytes, msg_bytes)
 
 print(f"Input size: {len(input_data)} bytes")
-print("Executing...")
+print("Executing and generating proof...")
 
-segments, info = pyr0.execute_with_input(image, input_data)
-journal = info.get_journal()
+# Use the new unified prove() function
+start = time.time()
+receipt = pyr0.prove(image, input_data)
+proof_time = time.time() - start
+journal = receipt.journal
 
 print(f"Journal: {len(journal)} bytes")
 print(f"First 10 bytes: {journal[:10]}")
@@ -140,15 +129,11 @@
 else:
     print(f"Unexpected result: {result}")
 
-# Generate proof
-print("\nGenerating proof...")
-start = time.time()
-receipt = pyr0.generate_proof(segments[0])  # Use new consistent name
-proof_time = time.time() - start
-print(f"Proof generated in {proof_time:.2f}s")
+# Proof was already generated by prove()
+print(f"\nProof generated in {proof_time:.2f}s")
 
 # Verify the receipt's program ID matches our expected program
-receipt_program_id = receipt.program_id().hex()
+receipt_program_id = receipt.program_id.hex()
 if receipt_program_id != PROGRAM_ID:
     print(f"❌ ERROR: Program ID mismatch!")
     print(f"  Expected: {PROGRAM_ID}")
@@ -157,19 +142,18 @@
 print(f"✓ Program ID verified: {receipt_program_id[:16]}...{receipt_program_id[-16:]}")
 
 # Verify the cryptographic proof
-pyr0.verify_proof(receipt)  # Use new consistent name
+receipt.verify()
 print("✓ Proof verified")
 
 # Test with invalid signature
 print("\n=== Test 2: Invalid Signature ===")
 sig_bytes = bytes.fromhex(INVALID_SIG)
 
-input_data = pyr0.prepare_input(
-    serialization.ed25519_input_vecs(pk_bytes, sig_bytes, msg_bytes)
-)
+input_data = serialization.ed25519_input(pk_bytes, sig_bytes, msg_bytes)
 
+# For the second test, we just execute, no need for proof
 segments, info = pyr0.execute_with_input(image, input_data)
-journal = info.get_journal()
+journal = info.journal
 
 print(f"Journal: {len(journal)} bytes")
 

demo/merkle_proof_guest/src/main.rs

@@ -5,6 +5,7 @@
 #![no_std]
 
 extern crate alloc;
+use alloc::vec;
 use alloc::vec::Vec;
 
 use risc0_zkvm::guest::env;
@@ -69,50 +70,50 @@ fn verify_merkle_path(
 risc0_zkvm::guest::entry!(main);
 
 fn main() {
-    // RISC Zero serializes everything through env::read()
-    // Each byte becomes a u32 in the input stream
+    // Use env::read_slice() for efficient byte reading
+    // Python sends raw bytes, no u32 expansion
 
-    // Read k_pub (32 bytes, each as u32)
+    // Read all input at once into a buffer
+    // We know the exact size: 32*3 + 32*16 + 16 = 96 + 512 + 16 = 624 bytes
+    let mut input_buffer = vec![0u8; 624];
+    env::read_slice(&mut input_buffer);
+    
+    // Create a cursor to read from the buffer
+    let mut offset = 0;
+    
+    // Read k_pub (32 bytes)
     let mut k_pub = [0u8; 32];
-    for i in 0..32 {
-        k_pub[i] = env::read::<u32>() as u8;
-    }
+    k_pub.copy_from_slice(&input_buffer[offset..offset+32]);
+    offset += 32;
 
-    // Read r (32 bytes, each as u32)
+    // Read r (32 bytes)
     let mut r = [0u8; 32];
-    for i in 0..32 {
-        r[i] = env::read::<u32>() as u8;
-    }
+    r.copy_from_slice(&input_buffer[offset..offset+32]);
+    offset += 32;
 
-    // Read e (32 bytes, each as u32)
+    // Read e (32 bytes)
     let mut e = [0u8; 32];
-    for i in 0..32 {
-        e[i] = env::read::<u32>() as u8;
-    }
+    e.copy_from_slice(&input_buffer[offset..offset+32]);
+    offset += 32;
 
-    // Read path length
-    let path_len: u32 = env::read();
-    assert_eq!(path_len, 16, "Merkle path must have 16 levels");
+    // Read path length (16 for our fixed-depth tree)
+    // For simplicity, we'll hardcode 16 levels since that's what we always use
+    let path_len = 16usize;
 
-    // Read path siblings (each is 32 bytes)
+    // Read path siblings (16 * 32 bytes)
     let mut path = Vec::new();
     for _ in 0..path_len {
         let mut sibling = [0u8; 32];
-        for j in 0..32 {
-            sibling[j] = env::read::<u32>() as u8;
-        }
+        sibling.copy_from_slice(&input_buffer[offset..offset+32]);
+        offset += 32;
         path.push(sibling);
     }
 
-    // Read indices length
-    let indices_len: u32 = env::read();
-    assert_eq!(indices_len, 16, "Must have 16 index bits");
-    
-    // Read indices (each byte as u32)
+    // Read indices (16 bytes, one per level)
     let mut indices = Vec::new();
-    for _ in 0..indices_len {
-        let bit_val: u32 = env::read();
-        indices.push(bit_val != 0);
+    for _ in 0..path_len {
+        indices.push(input_buffer[offset] != 0);
+        offset += 1;
     }
 
     // Step 1: Compute the leaf commitment C = Hash(k_pub || r || e)