Source code for fleetmesh_node.planes.services.compute.executors.zk

"""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), )