PyR0 v0.8.0: Production-ready API with safety improvements

🚀 PyR0 v0.8.0

This release removes all experimental scaffolding and provides a clean, production-ready API for RISC Zero proof generation from Python.

⚠️ Breaking Changes

• Removed VerifierContext - Was a non-functional placeholder
• Removed merkle functionality - Moved to separate PySMT project
• Removed release parameter from build_guest() - Always uses release mode now
• Removed dry_run from public API - Was insecure for production use

✨ New Features

• InputBuilder API - Safe, chainable API for serializing guest input data
• Framing support - Mix CBOR and raw data safely with write_cbor_frame() and write_frame()
• Typed helpers - write_bytes32() and write_image_id() for common 32-byte values

🔧 Improvements

• Enforced release-only builds - 100-1000x performance improvement, no debug mode
• Consolidated test organization - All tests now in test/ directory
• Fixed all placeholder implementations - No more mock code
• Honest documentation - Clear about what each API actually does
• Production-safe defaults - No dev mode, no mocking, no shortcuts

📝 API Highlights

Safe Input Serialization

# New InputBuilder API with three safe patterns
builder = pyr0.InputBuilder()

# Pattern A: CBOR-only
builder.write_cbor(cbor_bytes)

# Pattern B: Raw-only  
builder.write_u32(42).write_bytes32(key)

# Pattern C: Framed (safe mixing)
builder.write_cbor_frame(cbor_bytes).write_u32(42)

input_data = builder.build()

Simplified Build API

# Always builds in release mode for optimal performance
elf_path = pyr0.build_guest("path/to/guest")

🔒 Safety & Security

• No debug/dev mode support
• No mock implementations
• Clear API boundaries between serialization patterns
• Cryptographically secure proof generation only

📦 Installation

# From PyPI (when available)
pip install PyR0==0.8.0

# From source
git clone https://github.com/garyrob/PyR0.git
cd PyR0
uv tool run maturin build --release
uv pip install target/wheels/PyR0-0.8.0-*.whl

⚠️ Important Notes

• Still in alpha - API may change
• Currently supports Apple Silicon (M1/M2/M3) only
• Requires RISC Zero toolchain installed

🙏 Acknowledgments

This release represents a major cleanup and hardening of the PyR0 API. Special thanks to the RISC Zero team for their excellent zkVM platform.

---

Full Changelog: v0.7.0...v0.8.0

v0.6.0: Proof Composition Support

🎉 Release v0.6.0: Proof Composition Support

Major Features

🔗 Full Proof Composition

• ExecutorEnv class: Build execution environments with assumptions for proof composition
• prove_with_env() function: Generate proofs with custom environments containing assumptions
• Assumption-based recursion: One zkVM guest can now verify proofs from another efficiently
• Lazy verification: Assumptions are verified when the final proof is generated

📚 Documentation

• Comprehensive Proof Composition Guide: Added detailed section to README explaining:
  • How composition works conceptually
  • Complete working examples with full code
  • Critical implementation details
  • Advanced patterns and use cases
  • Performance and security considerations
  • Troubleshooting guide

🧹 Code Quality Improvements

• Production-ready demos: Removed all debug markers and placeholder code
• Clean test suite: Added composition test to comprehensive test runner
• No shortcuts: All test and demo code now production-quality with no misleading fallbacks

📝 Example Usage

# Create environment with inner proof as assumption
env = pyr0.ExecutorEnv()
env.add_assumption(inner_receipt)

# Add input data for outer guest
env.write(expected_data)
env.write(inner_image_id)

# Generate composed proof
outer_receipt = pyr0.prove_with_env(outer_image, env)

# Single verification proves both computations!
outer_receipt.verify_hex(outer_image_id)

🚀 Use Cases Enabled

• Multi-step computations: Break complex algorithms into verifiable steps
• Privacy-preserving pipelines: Different parties prove different parts
• Modular verification: Build libraries of verified components
• Proof aggregation: Combine multiple proofs into one

⚠️ Note

This is an experimental alpha release (v0.6.0) currently targeting Apple Silicon (M1/M2/M3) Macs only.

🙏 Acknowledgments

Built on RISC Zero's powerful zkVM and assumption-based recursion model.

---

🤖 Generated with Claude Code

v0.4.0: Python-friendly Receipt API

What's Changed

🎉 Major Receipt API Improvements

Python-friendly properties and methods for better ergonomics and security.

New Features

• Journal Properties: journal_bytes, journal_hex, journal_text, journal_len for easy journal access
• Structured Exit Status: ExitStatus with kind, user_code, and ok properties
• ExitKind Enum: Clear exit types (HALTED, PAUSED, SYSTEM_SPLIT, SESSION_LIMIT)
• Image ID Properties: claimed_image_id_hex/claimed_image_id_bytes (clearly marked as untrusted)
• New Verification Methods:
  • verify_hex(image_id) - accepts hex strings with optional 0x prefix
  • verify_bytes(image_id) - accepts 32-byte values
  • verify_integrity() - safe inspection of failed proofs
• Receipt Serialization: to_bytes()/from_bytes() for storage/transport
• Helper Function: compute_image_id_hex(elf_bytes) to derive trusted image IDs
• Better Debugging: Improved __repr__() with journal preview and image ID

Security Improvements

• Clear separation between "claimed" (from receipt) and "trusted" (from verifier) image IDs
• Verification methods require explicit trusted image ID parameter
• Better error messages and validation

Removed

• decode_journal() - Not implemented as RISC Zero 1.2 doesn't expose needed APIs (requires 2.x+)

Backward Compatibility

• Legacy properties (journal, program_id, exit_code) still work
• verify() method continues to work with image_id parameter

Installation

# For development
uv tool run maturin build --release
uv pip install --force-reinstall target/wheels/PyR0-*.whl

Full Changelog: v0.3.0...v0.4.0

v0.3.0: Secure Image ID Verification

Breaking Changes

• Security: Receipt.verify() now requires image_id parameter to prevent deriving image ID from untrusted receipt data

What's Changed

Security Improvements

• Enforced external image ID verification in verify() method
• Follows security best practice: never trust data from unverified sources
• Prevents potential security vulnerabilities from trusting receipt-provided image IDs

Test Suite Enhancements

• Added comprehensive test suite with zero-tolerance policy
• Created run_all_tests.sh master test runner
• All tests and demos now return proper exit codes (0 for success, 1 for failure)
• Test runner aborts immediately on first failure
• Added security verification tests

API Refinements

• Simplified API with consistent naming conventions
• Removed legacy code and unnecessary complexity
• Better error messages and validation
• Cleaner module structure

Files Changed

• Modified receipt verification to require external image ID
• Updated all demos and tests to pass image ID to verify()
• Added new security tests
• Created unified test runner

Installation

# For development
uv tool run maturin build --release
uv pip install --force-reinstall target/wheels/PyR0-*.whl

Full Changelog: v0.2.0...v0.3.0

PyR0 v0.2.0 - Clean Architecture

🧹 PyR0 v0.2.0 - Clean Architecture Release

This release focuses on removing unnecessary complexity and legacy code, plus comprehensive documentation improvements.

🗑️ Major Cleanup

Removed Unused Features

• Eliminated all pickle support - Removed unnecessary PyO3 pickle implementation that wasn't being used
• Deleted serialization.rs - This file only provided unused pickle support
• Removed unused imports - Cleaned up test files

Removed Legacy Methods

• journal_bytes() → Use journal property
• image_id → Use id property
• ed25519_input_vecs() → Use ed25519_input()

✨ Improvements

Better Documentation

• Comprehensive serialization guide explaining env::read() vs env::read_slice()
• Architecture overview showing how PyR0 bridges Python and RISC Zero
• Common pitfalls section with solutions for serialization mismatches
• Clear examples of matching host and guest serialization methods

Better Serialization Helpers

• Demos now properly use serialization helpers for testing
• merkle_zkp_demo.py uses merkle_commitment_input()
• ed25519_demo.py uses ed25519_input()
• Clear documentation on when to use each helper

Cleaner Codebase

• Smaller binary size without pickle support
• Clearer separation between Rust and Python code
• No confusing duplicate methods
• Better alignment between host serialization and guest deserialization

📖 Key Documentation Additions

The README now includes:

• When to use env::read() vs env::read_slice() in guests
• How to mix serialization methods in a single input
• Common pitfalls and their solutions
• Build notes about --force-reinstall requirement

💔 Breaking Changes from v0.1.0

• Pickle support removed - If you were pickling PyR0 objects, use standard serialization methods instead
• Legacy method aliases removed - Update to use the new property-based API

📦 Installation

git clone https://github.com/garyrob/PyR0.git
cd PyR0
uv tool run maturin build --release
uv pip install --force-reinstall target/wheels/PyR0-0.2.0-*.whl

🧪 Testing

Both demos continue to work perfectly:

uv run demo/ed25519_demo.py      # Ed25519 signature verification
uv run demo/merkle_zkp_demo.py   # Privacy-preserving membership proofs

📝 Notes

• Still in alpha - API may continue to evolve
• Currently Apple Silicon only (M1/M2/M3)
• Requires Python 3.8.3+ and Rust toolchain

---

This release makes PyR0 leaner, more focused, and better documented for developers working with RISC Zero zkVM.

PyR0 v0.1.0 - Alpha Release

🎉 PyR0 v0.1.0 - First Alpha Release

This release marks PyR0's transition from pre-alpha to alpha status with a completely refined API that's cleaner, more Pythonic, and easier to use.

🚀 Major API Improvements

Simplified Proof Generation

# Before: Multiple steps
input_data = pyr0.prepare_input(data)
segments, info = pyr0.execute_with_input(image, input_data)
receipt = pyr0.generate_proof(segments[0])

# Now: One simple call
receipt = pyr0.prove(image, data)

Property-Based Access

# Before: Method calls
journal = receipt.journal_bytes()
image_id = image.image_id()

# Now: Properties
journal = receipt.journal
image_id = image.id

✨ Key Features

• Unified prove() function - Combines execution and proof generation in one call
• Direct byte handling - No more prepare_input() wrapper, just pass bytes directly
• Efficient guest I/O - Guests now use env::read_slice() for better performance
• Cleaner API - Properties instead of methods for data access
• Optional serialization - Helper functions in pyr0.serialization module
• Borsh support - Built-in support for cross-language serialization

📦 What's Included

• Full RISC Zero zkVM integration
• Merkle tree implementation with Poseidon hash
• Zero-knowledge proof generation and verification
• Ed25519 signature verification in zkVM
• Complete demo applications

🔧 System Requirements

⚠️ Currently Apple Silicon Only

• Apple Silicon Mac (M1/M2/M3)
• macOS 11.0+
• Python 3.8.3+
• Rust toolchain
• uv package manager

📚 Examples

Two complete demonstration applications are included:

• Merkle ZKP Demo - Privacy-preserving membership proofs
• Ed25519 Demo - Zero-knowledge signature verification

🛠️ Installation

# Clone and build
git clone https://github.com/garyrob/PyR0.git
cd PyR0
uv tool run maturin build --release
uv pip install --force-reinstall target/wheels/PyR0-0.1.0-*.whl

# Run demos
uv run demo/merkle_zkp_demo.py
uv run demo/ed25519_demo.py

📝 Breaking Changes from v0.0.x

This is a major API overhaul. Code using v0.0.x will need updates:

• Replace prepare_input() calls with direct byte passing
• Replace generate_proof() with prove()
• Update property access (remove parentheses)
• Update guest code to use env::read_slice()

🙏 Acknowledgments

Based on the original PyR0 by L2 Iterative, extended with Merkle trees and improved APIs.

---

Note: This is an alpha release for testing and development. Production use is not recommended yet.

v0.0.4 - Journal Extraction & Borsh Serialization

🚀 Release v0.0.4

✨ Major Improvements

Fixed Journal Extraction from SegmentReceipt

• Properly implemented journal_bytes() method for SegmentReceipt
• Now correctly extracts journal data from receipt.claim.output.journal structure in RISC Zero 1.2
• Handles MaybePruned wrapper types appropriately

Added Borsh Serialization Support

• Guest programs now use Borsh serialization with env::commit_slice() for cross-language compatibility
• Added borsh-construct Python dependency for deserializing journal data
• Eliminated the 4x size expansion issue from u32-word encoding
• Journal data is now compact and portable between Rust and Python

📝 Demo & Documentation Updates

• Updated Merkle ZKP demo to use Borsh serialization
• Fixed demo to get journal from receipt (not SessionInfo)
• Added journal deserialization examples to README
• Updated Python version requirement to 3.8.3+ for borsh-construct
• Improved documentation of project structure and demo scripts

🔧 Other Changes

• Removed non-functional examples/ directory
• Updated all version references to 0.0.4
• Fixed demo paths in README

📦 Dependencies

• Added borsh v1.5 to guest Cargo.toml
• Added borsh-construct to Python dependencies

🎯 What This Means

Developers can now:

• Reliably extract journal data from both SegmentReceipt and SuccinctReceipt
• Use standard Borsh serialization for guest program outputs
• Parse journal data in Python with proper schema definitions
• Build zero-knowledge proofs with properly formatted public outputs

⚠️ Note

This is still an experimental pre-alpha release for Apple Silicon (M1/M2/M3) Macs only.

🙏 Acknowledgments

Thanks to the RISC Zero team for guidance on the journal extraction API in v1.2.2.

v0.0.3 - Merkle ZKP Demo (Pre-Alpha)

v0.0.3 - Merkle ZKP Demo (Pre-Alpha)

⚠️ Experimental Pre-Alpha Release - Apple Silicon Only

🎉 What's New

Zero-Knowledge Merkle Proofs

• Complete Merkle ZKP implementation equivalent to Noir 2LA circuits
• Prove membership in a Merkle tree WITHOUT revealing which leaf you are
• Full demo showing privacy-preserving authentication
• RISC Zero guest program for proof generation and verification

Improved Serialization

• Added raw_bytes() function for cleaner data passing to guest programs
• Better integration between Python and RISC Zero zkVM

Documentation & Testing

• Comprehensive demo: merkle_zkp_demo.py with educational output
• Test suite: test/test_merkle_zkp.py for verification
• Detailed README for Merkle ZKP functionality

📦 Installation

Prerequisites

• Apple Silicon Mac (M1/M2/M3)
• Python 3.8+
• Rust toolchain
• uv package manager

Quick Start

Clone and install

git clone https://github.com/garyrob/PyR0.git
cd PyR0
uv sync
uv tool run maturin build --release
uv pip install --force-reinstall target/wheels/PyR0-*-macosx_11_0_arm64.whl

For Merkle demos (optional)

cd merkle
uv tool run maturin build --release
cd ..
uv pip install --force-reinstall target/wheels/merkle_py-*-macosx_11_0_arm64.whl

Install RISC Zero toolchain for demos

cargo install cargo-risczero
cargo risczero install

🚀 Try the New Demo

Run the Merkle ZKP demo

uv run python demo/merkle_zkp_demo.py

This demonstrates:

• Building a Merkle tree with multiple user commitments
• Proving you're in the tree without revealing which user
• Zero-knowledge proof generation and verification

📝 What's Changed

• Added demo/merkle_zkp_demo.py - Complete ZKP demonstration
• Added demo/merkle_proof_guest/ - RISC Zero guest program
• Added src/pyr0/serialization.py::raw_bytes() - New serialization function
• Updated version to 0.0.3 throughout project
• Fixed serialization format for RISC Zero guest programs

🐛 Known Issues

• Experimental API - Interfaces may change in future versions
• Platform Limited - Apple Silicon Macs only (Intel/Linux/Windows planned)
• Build Time - First build takes ~5 minutes to compile RISC Zero
• Toolchain Required - RISC Zero toolchain needed for building guest programs

📚 Documentation

• README.md - Getting started guide
• demo/MERKLE_ZKP_README.md - Details on the new ZKP functionality
• CLAUDE.md - Development notes

🔮 Next Steps

Future releases may include:

• Additional platform support
• More ZKP circuit examples
• Performance optimizations
• Distributed proving support

🙏 Acknowledgments

This release includes significant new functionality for zero-knowledge proofs, building on the original
PyR0 foundation by L2 Iterative.

---

Full Changelog: https://github.com/garyrob/PyR0/commits/v0.0.3