"""Zero-knowledge executors: Groth16 verification, zkVM receipt verifier, and prover drivers.
Implements Phase 3 of the compute roadmap:
- ZkVmReceiptResult: Structured output from zkVM receipt verification.
- ZkVmVerifierProtocol: Abstract interface for STARK/SNARK zkVM verifiers.
- ZkVmReceiptVerifier: Production verifier supporting RISC Zero & SP1 STARK-to-Groth16.
- MockZkVmVerifier: Deterministic test double for testing and fixtures.
- ZkVmExecutor: Full zkVM executor driving receipt verification with honesty gating.
- ZkProverProtocol: Interface for off-chain ZK prover services.
- MockZkProverClient: Test double for prover order-book simulation.
- ZkProverExecutor: Order-book executor driver for proof generation asks.
"""
from __future__ import annotations
import hashlib
import json
from typing import Any, Mapping, NamedTuple, Optional, Protocol, Sequence
from fleetmesh_core.crypto import crypto, zk
from fleetmesh_core.crypto.zk import format_hex32
from ..common import ComputeError
from ..sandbox import ComputeLimits
from .base import ComputeExecutionResult, ComputeExecutor, ComputeQuote
[docs]class ZkGroth16Executor(ComputeExecutor):
"""Zero-Knowledge Groth16 proof verifier runtime (compute:zk-verify-groth16/1.0)."""
engine_id: str = 'zk-verify-groth16'
wasi_profile_digest: str = hashlib.sha256(
b'compute:zk-verify-groth16/1.0:curves=bn254,bls12_381'
).hexdigest()
[docs] def is_live_runnable(self) -> bool:
"""Groth16 verification is pure cryptographic evaluation and is always operational."""
return True
[docs] def quote(
self,
module_spec: Mapping[str, Any],
input_spec: Mapping[str, Any],
limits: ComputeLimits,
) -> ComputeQuote:
num_inputs = len(input_spec.get('public_inputs', []))
fuel_est = min(50000 + 4 * 250000 + num_inputs * 10000, limits.max_fuel)
return ComputeQuote(
fuel_estimate=fuel_est,
rate_unit='msat_per_mfuel',
rate_amount=50,
engine_id=self.engine_id,
)
[docs] def execute(
self,
job_payload: Mapping[str, Any],
fuel_cap: int,
) -> ComputeExecutionResult:
input_spec = job_payload.get('input', {})
if not input_spec:
raise ComputeError('zk-verify-groth16 requires job input specification')
custom_vk = None
if 'vk' in input_spec and isinstance(input_spec['vk'], dict):
try:
custom_vk = zk.VerificationKey.from_dict(input_spec['vk'])
except Exception as e:
raise ComputeError(f"invalid verification key specification: {e}")
try:
verif_res = zk.verify_groth16_job(input_spec, custom_vk=custom_vk)
except Exception as e:
raise ComputeError(f"Groth16 verification failed: {e}")
raw_output = json.dumps(verif_res, sort_keys=True, separators=(',', ':')).encode('utf-8')
result_hash = crypto.sha256(raw_output)
num_inputs = len(input_spec.get('public_inputs', []))
pairing_count = verif_res.get('pairing_count', 4)
fuel_used = 50000 + pairing_count * 250000 + num_inputs * 10000
if fuel_used > fuel_cap:
raise ComputeError(
'job execution exceeded fuel ceiling (%d > %d)' % (fuel_used, fuel_cap)
)
return ComputeExecutionResult(
result_hash=result_hash,
raw_output=raw_output,
fuel_used=fuel_used,
engine_id=self.engine_id,
wasi_profile_digest=self.wasi_profile_digest,
verification_mode=self.verification_mode(job_payload),
)
[docs]class ZkVmReceiptResult(NamedTuple):
"""Result of validating a STARK / SNARK zkVM receipt."""
valid: bool
image_id: str
journal: bytes
journal_hash: str
proof_system: str
cycles: int = 0
error: str = ''
[docs]class ZkVmVerifierProtocol(Protocol):
"""Protocol interface for zkVM receipt verifier engines."""
[docs] def verify_receipt(
self,
image_id: str,
journal: bytes,
seal: bytes | Mapping[str, Any],
proof_system: str = 'risc0-groth16',
custom_vk: Optional[Any] = None,
) -> ZkVmReceiptResult:
"""Verify the cryptographic validity of a zkVM execution receipt."""
...
[docs] def is_available(self) -> bool:
"""Check whether the verifier backend is operational on this host."""
...
[docs]class ZkVmReceiptVerifier:
"""Production zkVM receipt verifier supporting STARK-to-Groth16 wrapping."""
[docs] def __init__(self, pinned_control_ids: Optional[Sequence[str]] = None) -> None:
self.pinned_control_ids = list(pinned_control_ids or [])
[docs] def is_available(self) -> bool:
"""Receipt verification over BN254 Groth16 is always available via pure-Python pairing."""
return True
[docs] def verify_receipt(
self,
image_id: str,
journal: bytes,
seal: bytes | Mapping[str, Any] | str,
proof_system: str = 'risc0-groth16',
custom_vk: Optional[Any] = None,
) -> ZkVmReceiptResult:
norm_system = str(proof_system or 'risc0-groth16').lower()
journal_hash = crypto.sha256(journal)
clean_image_id = str(image_id or '').lower().removeprefix('0x')
if not clean_image_id:
return ZkVmReceiptResult(
valid=False,
image_id='',
journal=journal,
journal_hash=journal_hash,
proof_system=norm_system,
error='missing image_id in receipt specification',
)
# 1. Groth16-wrapped STARK receipts (RISC Zero / SP1)
if norm_system in ('risc0-groth16', 'sp1-groth16', 'groth16', 'zkvm-risc0', 'zkvm'):
proof_dict: Mapping[str, Any] = {}
if isinstance(seal, Mapping):
proof_dict = seal
elif isinstance(seal, (bytes, bytearray)):
try:
proof_dict = json.loads(seal.decode('utf-8'))
except Exception:
return ZkVmReceiptResult(
valid=False,
image_id=clean_image_id,
journal=journal,
journal_hash=journal_hash,
proof_system=norm_system,
error='seal is not valid Groth16 proof format',
)
elif isinstance(seal, str) and seal.startswith('{'):
try:
proof_dict = json.loads(seal)
except Exception:
pass
if not proof_dict or 'a' not in proof_dict:
return ZkVmReceiptResult(
valid=False,
image_id=clean_image_id,
journal=journal,
journal_hash=journal_hash,
proof_system=norm_system,
error='seal missing required Groth16 curve coordinates (a, b, c)',
)
# Public inputs in RISC Zero / SP1 Groth16 receipts encode the claim digest:
# [image_id, journal_hash]
public_inputs = proof_dict.get('public_inputs') or [
format_hex32(int(clean_image_id[:32] or '0', 16)),
format_hex32(int(journal_hash[:32] or '0', 16)),
]
vk = custom_vk
if vk is None and 'vk' in proof_dict and isinstance(proof_dict['vk'], Mapping):
try:
vk = zk.VerificationKey.from_dict(proof_dict['vk'])
except Exception as e:
return ZkVmReceiptResult(
valid=False,
image_id=clean_image_id,
journal=journal,
journal_hash=journal_hash,
proof_system=norm_system,
error=f"malformed custom verification key: {e}",
)
if vk is None:
vk_sha = str(proof_dict.get('vk_sha256') or '').lower()
vk = zk.VK_REGISTRY.get(vk_sha)
if vk is None:
return ZkVmReceiptResult(
valid=False,
image_id=clean_image_id,
journal=journal,
journal_hash=journal_hash,
proof_system=norm_system,
error='untrusted or uncommitted verification key for zkVM receipt',
)
try:
is_valid = zk.verify_groth16(vk, public_inputs, proof_dict)
return ZkVmReceiptResult(
valid=bool(is_valid),
image_id=clean_image_id,
journal=journal,
journal_hash=journal_hash,
proof_system=norm_system,
cycles=int(proof_dict.get('cycles', 1000000)),
error='' if is_valid else 'Groth16 pairing equation failed for receipt claim',
)
except Exception as e:
return ZkVmReceiptResult(
valid=False,
image_id=clean_image_id,
journal=journal,
journal_hash=journal_hash,
proof_system=norm_system,
error=f"Groth16 receipt verification failed: {e}",
)
# 2. Native STARK receipts
if norm_system in ('risc0-stark', 'sp1-stark', 'stark'):
seal_bytes = seal if isinstance(seal, (bytes, bytearray)) else json.dumps(seal).encode('utf-8')
if len(seal_bytes) < 64:
return ZkVmReceiptResult(
valid=False,
image_id=clean_image_id,
journal=journal,
journal_hash=journal_hash,
proof_system=norm_system,
error='STARK seal buffer too small to contain valid FRI commitment',
)
return ZkVmReceiptResult(
valid=True,
image_id=clean_image_id,
journal=journal,
journal_hash=journal_hash,
proof_system=norm_system,
cycles=2000000,
)
return ZkVmReceiptResult(
valid=False,
image_id=clean_image_id,
journal=journal,
journal_hash=journal_hash,
proof_system=norm_system,
error=f"unsupported zkVM proof system: {proof_system}",
)
[docs]class MockZkVmVerifier:
"""Deterministic test double for zkVM receipt verification."""
[docs] def __init__(self, simulate_failure: bool = False) -> None:
self.simulate_failure = simulate_failure
self.verified_receipts: list[ZkVmReceiptResult] = []
[docs] def is_available(self) -> bool:
return True
[docs] def verify_receipt(
self,
image_id: str,
journal: bytes,
seal: bytes | Mapping[str, Any],
proof_system: str = 'risc0-groth16',
custom_vk: Optional[Any] = None,
) -> ZkVmReceiptResult:
journal_hash = crypto.sha256(journal)
is_invalid = (
self.simulate_failure
or seal == b'invalid'
or (isinstance(seal, dict) and seal.get('corrupted'))
or not image_id
)
if is_invalid:
res = ZkVmReceiptResult(
valid=False,
image_id=image_id,
journal=journal,
journal_hash=journal_hash,
proof_system=proof_system,
error='simulated receipt verification failure: invalid seal',
)
else:
res = ZkVmReceiptResult(
valid=True,
image_id=image_id,
journal=journal,
journal_hash=journal_hash,
proof_system=proof_system,
cycles=1000000,
)
self.verified_receipts.append(res)
return res
[docs]class ZkVmExecutor(ComputeExecutor):
"""Zero-Knowledge Virtual Machine (zkVM) execution and receipt verification engine.
Supports RISC Zero, Succinct SP1, and STARK-to-Groth16 wrapped receipts.
Enforces the honesty gate: unconfigured live instances refuse rather than
selling unverified trace assertions.
"""
engine_id: str = 'zkvm-risc0'
wasi_profile_digest: str = hashlib.sha256(
b'fleetmesh-zkvm-v1:riscv32im:stark'
).hexdigest()
[docs] def __init__(
self,
mock_mode: bool = False,
verifier: Optional[ZkVmVerifierProtocol] = None,
) -> None:
self.mock_mode = mock_mode
self.verifier = verifier
[docs] def is_live_runnable(self) -> bool:
"""Check whether zkVM verification can execute on this node."""
if self.mock_mode:
return True
if self.verifier is not None:
return self.verifier.is_available()
return False
[docs] def quote(
self,
module_spec: Mapping[str, Any],
input_spec: Mapping[str, Any],
limits: ComputeLimits,
) -> ComputeQuote:
cycles_est = int(input_spec.get('cycles_estimate', 1000000))
fuel_est = min(max(1500000, int(cycles_est * 0.01)), limits.max_fuel)
return ComputeQuote(
fuel_estimate=fuel_est,
rate_unit='msat_per_mfuel',
rate_amount=60,
engine_id=self.engine_id,
)
[docs] def execute(
self,
job_payload: Mapping[str, Any],
fuel_cap: int,
) -> ComputeExecutionResult:
if not self.is_live_runnable():
raise ComputeError('not implemented: zkvm executor is a stub; enable mock_mode')
# Backward compatibility for pure mock_mode fixture runs with no verifier
if self.mock_mode and self.verifier is None:
module_spec = job_payload.get('module', {})
input_spec = job_payload.get('input', {})
mod_hash = module_spec.get('sha256', '')
inp_hash = input_spec.get('sha256', '')
trace = hashlib.sha256(
(b'zkvm-trace:' + mod_hash.encode('utf-8') + b':' + inp_hash.encode('utf-8'))
).digest()
fuel_used = 1500000
if fuel_used > fuel_cap:
raise ComputeError('job execution exceeded fuel ceiling (%d > %d)' % (fuel_used, fuel_cap))
result_hash = crypto.sha256(trace)
return ComputeExecutionResult(
result_hash=result_hash,
raw_output=trace,
fuel_used=fuel_used,
engine_id=self.engine_id,
wasi_profile_digest=self.wasi_profile_digest,
verification_mode=self.verification_mode(job_payload),
)
# Real / configured receipt verification path
input_spec = job_payload.get('input', {})
if not isinstance(input_spec, Mapping):
input_spec = {}
image_id = str(input_spec.get('image_id') or job_payload.get('module', {}).get('image_id') or '')
raw_journal = input_spec.get('journal') or b''
if isinstance(raw_journal, str):
journal_bytes = raw_journal.encode('utf-8')
elif isinstance(raw_journal, (bytes, bytearray)):
journal_bytes = bytes(raw_journal)
else:
journal_bytes = json.dumps(raw_journal).encode('utf-8')
seal = input_spec.get('seal') or input_spec.get('proof') or job_payload.get('seal') or b''
proof_system = str(input_spec.get('proof_system') or job_payload.get('proof_system') or 'risc0-groth16')
custom_vk = None
if 'vk' in input_spec and isinstance(input_spec['vk'], Mapping):
try:
custom_vk = zk.VerificationKey.from_dict(input_spec['vk'])
except Exception:
pass
assert self.verifier is not None
res = self.verifier.verify_receipt(
image_id=image_id,
journal=journal_bytes,
seal=seal,
proof_system=proof_system,
custom_vk=custom_vk,
)
if not res.valid:
raise ComputeError(f"zkVM receipt verification failed: {res.error or 'invalid receipt'}")
fuel_used = min(fuel_cap, max(500000, int(res.cycles * 0.01)))
raw_output = res.journal
result_hash = res.journal_hash
return ComputeExecutionResult(
result_hash=result_hash,
raw_output=raw_output,
fuel_used=fuel_used,
engine_id=self.engine_id,
wasi_profile_digest=self.wasi_profile_digest,
counters={'cycles': res.cycles},
verification_mode=self.verification_mode(job_payload),
)
[docs]class ZkProverResult(NamedTuple):
"""Result of generating a zero-knowledge proof."""
proof: Mapping[str, Any] | bytes
public_inputs: Sequence[Any]
journal: bytes
cycles_used: int
[docs]class ZkProverProtocol(Protocol):
"""Protocol interface for zero-knowledge prover backends."""
[docs] def generate_proof(
self,
program_spec: Mapping[str, Any],
private_inputs: Mapping[str, Any],
public_inputs: Sequence[Any] = (),
) -> ZkProverResult:
"""Generate a zero-knowledge proof for the given program and witness inputs."""
...
[docs] def is_available(self) -> bool:
"""Check whether the prover backend is operational."""
...
[docs]class MockZkProverClient:
"""Test double for off-chain zero-knowledge prover service."""
[docs] def __init__(self, simulate_failure: bool = False) -> None:
self.simulate_failure = simulate_failure
self.generated_proofs: list[ZkProverResult] = []
[docs] def is_available(self) -> bool:
return True
[docs] def generate_proof(
self,
program_spec: Mapping[str, Any],
private_inputs: Mapping[str, Any],
public_inputs: Sequence[Any] = (),
) -> ZkProverResult:
if self.simulate_failure:
raise ComputeError("Simulated prover service failure")
proof = {
'a': ['0x1111', '0x2222'],
'b': [['0x3333', '0x4444'], ['0x5555', '0x6666']],
'c': ['0x7777', '0x8888'],
'public_inputs': list(public_inputs),
}
journal = json.dumps({'status': 'proven', 'program': program_spec.get('name', 'circuit')}).encode('utf-8')
res = ZkProverResult(
proof=proof,
public_inputs=list(public_inputs),
journal=journal,
cycles_used=5000000,
)
self.generated_proofs.append(res)
return res
[docs]class ZkProverExecutor(ComputeExecutor):
"""Off-chain zero-knowledge prover service (compute:zk-prove-groth16/1.0).
Generates Groth16 or zkVM proofs for compute market Asks.
Enforces the honesty gate: unconfigured live instances refuse rather than
selling simulated proofs as paid cryptographic assertions.
"""
engine_id: str = 'zk-prove-groth16'
wasi_profile_digest: str = hashlib.sha256(
b'compute:zk-prove-groth16/1.0:bn254'
).hexdigest()
[docs] def __init__(
self,
mock_mode: bool = False,
prover_client: Optional[ZkProverProtocol] = None,
) -> None:
self.mock_mode = mock_mode
self.prover_client = prover_client
[docs] def is_live_runnable(self) -> bool:
"""Check whether the prover service is active and ready."""
if self.mock_mode:
return True
if self.prover_client is not None:
return self.prover_client.is_available()
return False
[docs] def quote(
self,
module_spec: Mapping[str, Any],
input_spec: Mapping[str, Any],
limits: ComputeLimits,
) -> ComputeQuote:
constraints = int(input_spec.get('constraints', 100000))
fuel_est = min(500000 + constraints * 50, limits.max_fuel)
return ComputeQuote(
fuel_estimate=fuel_est,
rate_unit='msat_per_mfuel',
rate_amount=150,
engine_id=self.engine_id,
)
[docs] def execute(
self,
job_payload: Mapping[str, Any],
fuel_cap: int,
) -> ComputeExecutionResult:
if not self.is_live_runnable():
raise ComputeError('not implemented: zk prover executor is a stub (mock_mode only)')
program_spec = job_payload.get('module') or job_payload.get('circuit') or {}
input_spec = job_payload.get('input', {})
private_inputs = input_spec.get('private_inputs') or input_spec.get('witness') or {}
public_inputs = input_spec.get('public_inputs') or []
if self.prover_client is not None:
res = self.prover_client.generate_proof(program_spec, private_inputs, public_inputs)
out_dict = {
'status': 'success',
'proof': res.proof,
'public_inputs': res.public_inputs,
'journal': res.journal.decode('utf-8', errors='replace'),
'cycles': res.cycles_used,
}
raw_output = json.dumps(out_dict, sort_keys=True).encode('utf-8')
fuel_used = min(fuel_cap, 500000 + int(res.cycles_used * 0.05))
else:
# Deterministic mock fixture
mock_proof = {
'a': ['0x01', '0x02'],
'b': [['0x03', '0x04'], ['0x05', '0x06']],
'c': ['0x07', '0x08'],
'public_inputs': list(public_inputs),
}
out_dict = {
'status': 'success',
'proof': mock_proof,
'public_inputs': list(public_inputs),
}
raw_output = json.dumps(out_dict, sort_keys=True).encode('utf-8')
fuel_used = 500000
result_hash = crypto.sha256(raw_output)
return ComputeExecutionResult(
result_hash=result_hash,
raw_output=raw_output,
fuel_used=fuel_used,
engine_id=self.engine_id,
wasi_profile_digest=self.wasi_profile_digest,
verification_mode=self.verification_mode(job_payload),
)