ves-stark

Python bindings for the VES STARK proof system. Generate and verify zero-knowledge compliance proofs for VES events.

Installation

pip install ves-stark

Requirements

• Python >= 3.8
• Supported platforms: Linux (x64, arm64), macOS (x64, arm64), Windows (x64)

Usage

Generate a Compliance Proof

import ves_stark

# Create a policy (AML threshold of 10,000)
policy = ves_stark.Policy.aml_threshold(10000)

# Compute the policy hash
policy_hash = ves_stark.compute_policy_hash("aml.threshold", {"threshold": 10000})

# Create public inputs
public_inputs = ves_stark.CompliancePublicInputs(
    event_id="550e8400-e29b-41d4-a716-446655440000",
    tenant_id="550e8400-e29b-41d4-a716-446655440001",
    store_id="550e8400-e29b-41d4-a716-446655440002",
    sequence_number=12345,
    payload_kind=1,
    payload_plain_hash="a" * 64,  # 64-char lowercase hex
    payload_cipher_hash="b" * 64,
    event_signing_hash="c" * 64,
    policy_id="aml.threshold",
    policy_params={"threshold": 10000},
    policy_hash=policy_hash
)

# Generate proof (amount must be < threshold for aml.threshold)
proof = ves_stark.prove(5000, public_inputs, policy)

print(f"Proof generated in {proof.proving_time_ms}ms")
print(f"Proof size: {proof.proof_size} bytes")
print(f"Proof hash: {proof.proof_hash}")
print(f"Witness commitment (hex): {proof.witness_commitment_hex}")

Verify a Proof

import ves_stark

public_inputs_bound = ves_stark.CompliancePublicInputs(
    event_id=public_inputs.event_id,
    tenant_id=public_inputs.tenant_id,
    store_id=public_inputs.store_id,
    sequence_number=public_inputs.sequence_number,
    payload_kind=public_inputs.payload_kind,
    payload_plain_hash=public_inputs.payload_plain_hash,
    payload_cipher_hash=public_inputs.payload_cipher_hash,
    event_signing_hash=public_inputs.event_signing_hash,
    policy_id=public_inputs.policy_id,
    policy_params=public_inputs.policy_params,
    policy_hash=public_inputs.policy_hash,
    witness_commitment=proof.witness_commitment_hex,
)

result = ves_stark.verify(
    proof.proof_bytes,
    public_inputs_bound,
    proof.witness_commitment,
)

if result.valid:
    print("Proof is valid!")
    print(f"Verified in {result.verification_time_ms}ms")
    print(f"Policy: {result.policy_id} (limit: {result.policy_limit})")
else:
    print(f"Verification failed: {result.error}")

# VerificationResult is also truthy/falsy
if result:
    print("Valid!")

ves_stark.verify(...) now binds the supplied witness commitment into the public inputs before verification, so local verification is witness-bound by default.

For payload-to-amount binding, derive a canonical binding artifact and verify against it directly:

amount_binding = ves_stark.create_payload_amount_binding(public_inputs, 5000)
bound_result = ves_stark.verify_with_amount_binding(
    proof.proof_bytes,
    public_inputs,
    amount_binding,
)

API Reference

Classes

Policy

Represents a compliance policy.

# Create AML threshold policy (proves amount < threshold)
policy = ves_stark.Policy.aml_threshold(10000)

# Create order total cap policy (proves amount <= cap)
policy = ves_stark.Policy.order_total_cap(50000)

# Create agent authorization policy (proves amount <= maxTotal)
policy = ves_stark.Policy.agent_authorization(20000, "11" * 32)

# Properties
policy.policy_id   # "aml.threshold", "order_total.cap", or "agent.authorization.v1"
policy.limit       # The threshold/cap/maxTotal value

CompliancePublicInputs

Public inputs for proof generation and verification.

public_inputs = ves_stark.CompliancePublicInputs(
    event_id="...",           # UUID string
    tenant_id="...",          # UUID string
    store_id="...",           # UUID string
    sequence_number=12345,    # u64
    payload_kind=1,           # u32
    payload_plain_hash="...", # 64-char lowercase hex
    payload_cipher_hash="...",
    event_signing_hash="...",
    policy_id="aml.threshold",
    policy_params={"threshold": 10000},  # dict
    policy_hash="...",        # 64-char lowercase hex
    witness_commitment=None,  # optional 64-char lowercase hex (witnessCommitment)
    authorization_receipt_hash=None,  # optional 64-char lowercase hex
    amount_binding_hash=None,  # optional 64-char lowercase hex
)

# All fields are readable and writable
public_inputs.sequence_number = 12346

ComplianceProof

Result of proof generation.

proof.proof_bytes         # bytes - raw proof data
proof.proof_hash          # str - SHA-256 hash of proof
proof.proving_time_ms     # int - generation time in ms
proof.proof_size          # int - size in bytes
proof.witness_commitment  # list[int] - 4-element commitment
proof.witness_commitment_hex  # str - 64-char lowercase hex commitment

VerificationResult

Result of proof verification.

result.valid               # bool - whether proof is valid
result.verification_time_ms # int - verification time in ms
result.error               # str | None - error message if invalid
result.policy_id           # str - verified policy ID
result.policy_limit        # int - verified policy limit

# Supports boolean conversion
if result:
    print("Valid!")

Functions

prove(amount, public_inputs, policy)

Generate a STARK compliance proof.

proof = ves_stark.prove(
    amount=5000,
    public_inputs=public_inputs,
    policy=policy
)

Parameters:

• amount (int): The amount to prove compliance for
• public_inputs (CompliancePublicInputs): Event metadata and policy info
• policy (Policy): The policy to prove compliance against

Returns: ComplianceProof

Raises:

• ValueError: If inputs are invalid
• RuntimeError: If proof generation fails

verify(proof_bytes, public_inputs, witness_commitment)

Verify a STARK compliance proof.

result = ves_stark.verify(
    proof_bytes=proof.proof_bytes,
    public_inputs=public_inputs,
    witness_commitment=proof.witness_commitment
)

Parameters:

• proof_bytes (bytes): Raw proof bytes from prove()
• public_inputs (CompliancePublicInputs): Must match proving inputs and include witness_commitment when using canonical bound verification
• witness_commitment (list[int]): 4-element list from proof

Returns: VerificationResult

Raises:

• ValueError: If arguments are malformed

verify_agent_authorization(proof_bytes, public_inputs, witness_commitment, receipt)

Verify an agent.authorization.v1 proof against a canonical authorization receipt, deriving the payload amount binding from receipt["amount"].

verify_with_amount_binding(proof_bytes, public_inputs, amount_binding)

Verify a proof against a canonical payload-derived amount binding.

verify_agent_authorization_with_amount_binding(proof_bytes, public_inputs, amount_binding, receipt)

Verify an agent.authorization.v1 proof against both a payload-derived amount binding and a canonical authorization receipt. This is equivalent to verify_agent_authorization(...) when the binding matches receipt["amount"], but keeps the artifact explicit.

create_payload_amount_binding(public_inputs, amount)

Create a canonical payload amount binding artifact for the supplied public inputs and extracted amount.

compute_policy_hash(policy_id, policy_params)

Compute the canonical policy hash.

hash = ves_stark.compute_policy_hash("aml.threshold", {"threshold": 10000})

Parameters:

• policy_id (str): Policy identifier
• policy_params (dict): Policy parameters

Returns: str - 64-character lowercase hex hash

Policy Types

Building from Source

Requires maturin:

# Create & activate a virtualenv (required for `maturin develop`)
python -m venv .venv
source .venv/bin/activate

# Install maturin
python -m pip install --upgrade pip maturin

# Build and install in development mode
cd crates/ves-stark-python
maturin develop --release

# Build release wheel
maturin build --release

Performance

Typical performance on modern hardware:

• Proof generation: 500-2000ms
• Proof verification: 50-200ms
• Proof size: ~100-200 KB

Example: Full Round-Trip

import ves_stark

# Setup
policy = ves_stark.Policy.aml_threshold(10000)
policy_hash = ves_stark.compute_policy_hash("aml.threshold", {"threshold": 10000})

public_inputs = ves_stark.CompliancePublicInputs(
    event_id="550e8400-e29b-41d4-a716-446655440000",
    tenant_id="550e8400-e29b-41d4-a716-446655440001",
    store_id="550e8400-e29b-41d4-a716-446655440002",
    sequence_number=1,
    payload_kind=1,
    payload_plain_hash="0" * 64,
    payload_cipher_hash="0" * 64,
    event_signing_hash="0" * 64,
    policy_id="aml.threshold",
    policy_params={"threshold": 10000},
    policy_hash=policy_hash
)

# Prove
amount = 5000  # Must be < 10000
proof = ves_stark.prove(amount, public_inputs, policy)
print(f"Generated {proof.proof_size} byte proof in {proof.proving_time_ms}ms")

# Verify
result = ves_stark.verify(proof.proof_bytes, public_inputs, proof.witness_commitment)
assert result.valid, f"Verification failed: {result.error}"
print(f"Verified in {result.verification_time_ms}ms")

License

MIT