xian-tech-zk

Small native zero-knowledge verification and proving primitives for the Xian workspace.

Purpose

• This package exposes the narrow verifier surface used by the Xian runtime.
• It exposes an external proving toolkit for the shielded-note-token development flow.
• It is intentionally small. It is not a general-purpose zk framework.

Current Scope

• Groth16 verification
• BN254
• Python bindings for runtime integration
• A pure Rust verifier core for cargo-level testing and fixtures
• Shielded-note proving circuits and proof generation helpers
• Shielded scheduler-update authorization circuit and proof helpers
• Deterministic dev bundle generation for local shielded-note workflows
• Note math helpers for commitments, nullifiers, asset ids, and Merkle roots
• Trusted local prover-service support for note, command, and relay proof generation

flowchart LR
  Wallet["Shielded wallet"] --> Request["Proof request"]
  Request --> Prover["xian-zk prover toolkit"]
  Prover --> Proof["Groth16 proof and public inputs"]
  Proof --> Contract["Shielded contract"]
  Contract --> Registry["zk_registry verifying key"]
  Contract --> Bridge["contract-side zk bridge"]
  Bridge --> Verifier["xian-zk verifier"]

API

Python module xian_zk exposes:

• raw and prepared Groth16 BN254 verification
• native public-input, payload-hash, tree, and command digest helpers
• shielded note request/result/prover/wallet types
• shielded command request/result/prover/wallet types
• shielded relay transfer request/result/prover/wallet types
• shielded scheduler authorization request/result/prover types
• registry manifest helpers for note, command, relay, and scheduler authorization verifying keys
• note encryption/decryption, discovery-tag, sync-hint, and wallet sync helpers
• local prover service clients and ShieldedZkProverService

CLI entrypoints:

• uv run xian-zk-shielded-bundle generate-note --output-dir ...
• uv run xian-zk-shielded-bundle generate-command --output-dir ...
• uv run xian-zk-shielded-bundle import-note --bundle ... --output-dir ...
• uv run xian-zk-shielded-bundle import-command --bundle ... --output-dir ...
• uv run xian-zk-shielded-bundle validate-note --bundle ...
• uv run xian-zk-shielded-bundle validate-command --bundle ...
• uv run xian-zk-shielded-bundle promote --network ... --contract-name ... --note-bundle ... --relay-command-bundle ... --output-dir ...
• uv run xian-zk-prover-service --host 127.0.0.1 --port 8787 ...

The Rust crate exposes the verifier core, shielded fixture builders, and proof generation helpers used by the Python bindings and tests.

Encoding

• Verifying keys: compressed canonical bytes as 0x-prefixed hex
• Proofs: compressed canonical bytes as 0x-prefixed hex
• Public inputs: 32-byte big-endian field elements as 0x-prefixed hex

Validation

• cargo test --manifest-path packages/xian-zk/Cargo.toml --no-default-features
• cargo run --manifest-path packages/xian-zk/Cargo.toml --no-default-features --example generate_test_vector
• cargo run --manifest-path packages/xian-zk/Cargo.toml --no-default-features --example generate_shielded_note_fixture
• cd packages/xian-zk && uv sync --group dev && uv run maturin develop && uv run pytest -q
• cd packages/xian-zk && uv run pytest -q -m slow

Build performance: the [profile.dev] block in Cargo.toml sets opt-level = 3, so even a plain maturin develop produces optimized proving/setup. Without it an unoptimized build is ~25x slower (Groth16 setup ~100s vs ~4s) — do not lower it. Published/CI wheels build --release regardless.

Notes

• The runtime-facing verifier surface is intentionally narrow.
• The shielded-note proving helpers are an external proving toolkit slice, not a broad proving framework.
• The shielded-note circuits use Merkle auth paths instead of witnessing the whole leaf set, and the shipped dev bundle / fixture ids are v4 for the note family and v5 for the command family. The circuits hash with Poseidon-BN254 (see src/poseidon.rs).
• The scheduler authorization circuit is intentionally small: it proves knowledge of a hidden owner secret for a public owner commitment and derives an update nullifier from that secret plus the exact public update digest.
• Shielded outputs are addressed to owner_public, not to the recipient's spending secret. That lets senders create recipient outputs without learning the recipient's private shielded spend key.
• The Python toolkit separates spending and viewing authority. A wallet can disclose note contents by sharing only a viewing key or by adding explicit extra viewers to an encrypted note payload without exposing the spend key.
• The Python toolkit ships a first-class ShieldedWallet abstraction for seed backup, state snapshots, record sync, note selection, and request planning for deposit / transfer / withdraw flows.
• The package ships deployment CLI helpers that generate or import proving bundles, emit public registry manifests, write register_and_bind.py operator helpers, and create catalog snippets for promoted ceremony artifacts. Keep private bundles offline; only registry manifests should be used for zk_registry registration.
• The encrypted payload format supports owner delivery plus optional disclosed viewers inside a single on-chain payload blob.
• The encrypted payload format uses anonymous per-viewer discovery tags and ephemeral keys for payloads, so recipient viewing keys are not embedded in cleartext.
• ShieldedWallet.sync_records(...) prefilters candidate payloads before full decryption, and note records expose payload_tags so indexers can persist discovery metadata for later selective queries.
• xian-zk-prover-service is a trusted local proving companion, not a true split-prover protocol. It improves deployability and wallet ergonomics, but the service sees witness material.
• xian-zk-prover-service defaults to 127.0.0.1. IPv6 literal binds are supported with ::1 or [::1]; non-loopback binds such as :: still require --unsafe-allow-remote-host and --auth-token.
• Exact withdraws do not need a forced change note. A withdraw can spend a note set down to zero shielded outputs when value conservation closes exactly.
• The proving requests separate old_root from append_state, which lets a client prove against a recent accepted root while projecting the canonical post-state from the current append frontier.
• Python pytest excludes the slow proof-generation tests by default. Run pytest -m slow explicitly when you want the proving-toolkit path.
• The contract runtime prefers registry-backed verification by vk_id; this package exposes the lower-level raw and prepared-key verifier primitives that runtime builds on.
• ShieldedNoteProver.build_insecure_dev_bundle() is for local development and tests only. Its deterministic setup seed exposes toxic waste and must never be used for a real network.
• ShieldedNoteProver.build_random_bundle(...) and xian-zk-shielded-bundle generate-note generate a single-party random trusted setup. That is appropriate for deployment tooling, but it is not an MPC ceremony.
• Proof generation uses real randomness even when the proving bundle is a deterministic dev bundle.