Overview

The rivellum blockchain now includes three ZK modes:

1. Disabled - No proof generation (maximum performance)
2. Mock - BLAKE3 hash proofs (fast development/testing)
3. Real - Halo2 circuit proofs (experimental cryptographic security)

This document explains how to build, configure, and use the real ZK proof system.

⚠️ EXPERIMENTAL WARNING

The real ZK proof system is a PROTOTYPE for demonstration purposes:

• NOT production-ready - requires extensive security auditing
• Circuit constraints may be incomplete
• No formal verification performed
• Setup parameters are for testing only
• Proof generation is SLOW (1-10 seconds per transfer)
• Large proof size (~10KB-100KB vs 32 bytes for mock)

Building with Real ZK Support

Prerequisites

# Ensure you have Rust 1.70+ installed
rustc --version

# Halo2 compilation requires significant memory and time
# Expect 5-15 minutes for first build

Compilation

# Build with real ZK feature enabled
cargo build --release --features real

# Or build specific binary
cargo build --release --bin rivellum-node --features real

# Check that feature is enabled
cargo tree --features real | grep halo2

Build Without Real ZK (Default)

# Standard build (mock and disabled modes only)
cargo build --release

# This is faster and suitable for most development

Configuration

Config File Setup

Create or modify a .toml config file:

# config/zk-real.toml
data_dir = "./data/zk-real-test"
rpc_bind = "127.0.0.1:8084"
zk_mode = "real"  # Enable real ZK proofs
network_role = "standalone"

ZK Mode Options

Mode	Proof Type	Speed	Proof Size	Security	Use Case
disabled	None	Instant	0 bytes	None	Performance testing
mock	BLAKE3 hash	~1μs	32 bytes	None	Development
real	Halo2 circuit	1-10s	10-100KB	Experimental	Prototype/demo

Running the Node

# Start node with real ZK proofs
./target/release/rivellum-node \
  --config config/zk-real.toml \
  --server

# Monitor logs for proof generation
# Look for: "Generating real ZK proof..." messages

Circuit Architecture

Transfer Circuit Design

The Halo2 circuit proves correct execution of a Transfer operation:

Public Inputs (visible to verifier)

• Gas used
• Fee charged
• (Future: State root commitments)

Private Witnesses (hidden in ZK proof)

• Sender starting balance
• Receiver starting balance
• Transfer amount
• Nonce values

Constraints Enforced

// Constraint 1: Balance integrity (sender)
sender_final_balance = sender_start_balance - transfer_amount - fee

// Constraint 2: Balance integrity (receiver)
receiver_final_balance = receiver_start_balance + transfer_amount

// Constraint 3: Non-negativity (no overdraft)
sender_final_balance >= 0

// Constraint 4: Nonce increment
nonce_final = nonce_start + 1

// Constraint 5: Gas accounting
gas_used = 10  // Fixed for Transfer in prototype

// Constraint 6: Fee deduction
fee = gas_used * gas_price

Circuit Parameters

// Circuit size: 2^k rows
const K: u32 = 8;  // 256 rows (small for testing)

// Advice columns: 6 (for private witnesses)
// Instance columns: 1 (for public inputs)
// Selectors: 1 (to enable constraints)

Performance Characteristics

Proof Generation Time

Operation	Mock Mode	Real Mode (k=8)	Real Mode (k=12)
Single Transfer	~1μs	~1-2 seconds	~5-10 seconds
10 Transfers	~10μs	~10-20 seconds	~50-100 seconds
100 Transfers	~100μs	~2-3 minutes	~8-15 minutes

Proof Size

Mode	Per-Proof Size	1000 Proofs
Mock	32 bytes	32 KB
Real (k=8)	~10-20 KB	~10-20 MB
Real (k=12)	~50-100 KB	~50-100 MB

Memory Usage

• Compilation: 4-8 GB RAM
• Proof Generation: 100-500 MB per proof
• Verification: 10-50 MB per proof

API Usage

Submitting Intents

Same HTTP API as mock mode - proof generation is automatic:

# Submit transfer intent
curl -X POST http://localhost:8084/intents \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "sender": [131, 86, 26, ...],
    "nonce": 1,
    "actions": [{
      "Transfer": {
        "recipient": [30, 237, 41, ...],
        "amount": 100
      }
    }],
    "max_gas": 1000
  }'

# Response includes intent_id, status, gas_used
# Proof generation happens in background

Monitoring Proof Generation

# Watch node logs
tail -f logs/rivellum.log

# Look for:
# - "Generating real ZK proof for intent..."
# - "Real ZK proof generated: XXXX bytes"
# - "ERROR: Real ZK proof generation failed" (fallback to mock)

Replay Verification

# Verify all proofs in ledger
./target/release/rivellum-node \
  --config config/zk-real.toml \
  --replay-ledger

# Output shows:
# ║ ZK Proofs Found:      X
# ║ ZK Proofs Verified:   Y

Troubleshooting

Build Failures

error: no variant or associated item named `Real` found for enum `ZkMode`

Solution: Compile with --features real

error: could not compile `halo2_proofs`

Solution: Update Rust toolchain: rustup update stable

Runtime Issues

Proof generation takes too long

• This is expected - real ZK proofs are computationally expensive
• Consider using k=8 (small circuit) for faster proofs
• Mock mode recommended for development

Proof generation fails

• Check logs for "ERROR: Real ZK proof generation failed"
• Node automatically falls back to mock mode on error
• Verify circuit constraints match execution trace

High memory usage

• Real ZK proofs require substantial RAM
• Increase system resources or reduce k parameter
• Use disabled/mock mode for resource-constrained environments

Migration from Mock to Real

Step 1: Test with Mock Mode

# Start with mock mode
cargo build --release
./target/release/rivellum-node --config config/zk-mock.toml --server

# Submit test intents
# Verify system works correctly

Step 2: Enable Real Mode

# Rebuild with real feature
cargo build --release --features real

# Update config
sed -i 's/zk_mode = "mock"/zk_mode = "real"/' config.toml

# Start node
./target/release/rivellum-node --config config.toml --server

Step 3: Compare Performance

# Time a single intent submission
time curl -X POST http://localhost:8084/intents -d @test_intent.json

# Mock mode: ~10-50ms
# Real mode: ~1-10 seconds (includes proof generation)

Step 4: Verify Proofs

# Run replay to verify all proofs
./target/release/rivellum-node --config config.toml --replay-ledger

# Check output:
# ║ ZK Proofs Verified:   X  (should match Proofs Found)

Future Improvements

Phase 1: Circuit Optimization (Q1 2026)

• Optimize constraint system for smaller proof size
• Implement lookup tables for gas accounting
• Add range checks for balance constraints
• Reduce circuit size (lower k parameter)

Phase 2: Advanced Features (Q2 2026)

• Proof aggregation (batch multiple proofs)
• Recursive proofs (proof of proof verification)
• Public input commitments (state root verification)
• Custom gate optimization

Phase 3: Production Readiness (Q3-Q4 2026)

• Formal security audit
• Trusted setup ceremony (or use universal setup)
• Parameter generation for mainnet
• Proof caching and verification optimization
• Integration with consensus mechanism

References

Halo2 Documentation

• Halo2 Book
• Halo2 GitHub
• Circuit Tutorial

ZK Proof Systems

• PLONK Paper
• Halo Paper
• ZK Whiteboard Sessions

rivellum Architecture

• ZK_ARCHITECTURE.md - Mock vs Real comparison
• README.md - General system overview

Support

For issues with real ZK mode:

1. Check logs: ./logs/rivellum.log
2. Verify feature flag: cargo tree --features real | grep halo2
3. Test with mock mode first: zk_mode = "mock"
4. Report issues with:
   • Circuit size (k parameter)
   • Proof generation time
   • Verification failures

License

Real ZK implementation uses Halo2 library:

• Halo2: MIT/Apache-2.0 License
• rivellum: [Your License]

---

Last Updated: November 24, 2025
Status: Experimental Prototype
Maintainer: rivellum Core Team