ZKD is a deterministic, backend-agnostic STARK proving engine that ships with a CLI, a stable C ABI, and maintained language bindings. It targets developers who need portable proofs across devices and stacks, with clear validation, golden vectors, and an emphasis on honest determinism at the proof layer rather than brittle binary reproducibility. The workspace contains the core library, adapters, crypto bundles, docs, tests, examples, and multi-language FFI bindings.
Mantra: same input, same output, any backend.
- Why ZKD
- Features
- Architecture
- Backends and Capabilities
- Determinism Policy
- Install
- Quickstart
- CLI Reference
- C ABI and Language Bindings
- WASM and Mobile
- Pre-baked Profiles
- EVM Interop
- Recursion (Aggregations)
- Testing, Golden Vectors, and CI
- Roadmap
- Security and Threat Model
- Contributing
- License
- Deterministic by contract: identical inputs with the same backend and profile produce identical proof digests. Determinism is validated at the proof layer with manifest hashing and golden vectors.
- Backend-agnostic: a portable AIR-IR and adapter layer allow multiple engines to coexist without changing your AIR. Swap backends while preserving public output digests.
- Developer-friendly: clean CLI, stable C ABI, and maintained bindings for Node, Python, Flutter/Dart, and WASI (Go/.NET/Java/Kotlin/Swift follow the bindings cookbook until official releases return).
- Privacy gadgets: Pedersen commitments, range checks, and Merkle tools shipped as reusable bundles.
- Ready profiles: drop-in AIRs for auth, allowlists, balance checks, age gates, and more.
- Portable AIR-IR with YAML front matter and canonical encoding.
- Backend adapters for a reference native path and real engines like Winterfell and Plonky families.
- Profile system for predictable performance envelopes on desktop and mobile.
- C ABI with six core functions exposed through safe bindings across languages.
- Commitments and crypto: Poseidon2, Rescue, Merkle (arity 2 and 4), Keccak, Pedersen.
- Golden vectors and validation reports wired into CI to catch drift.
ZKD is a layered stack:
CLI / SDK / FFI
Coordinator (capability checks, orchestration)
AIR-IR (backend-neutral algebra)
Bundle engine (gadgets like Merkle, Range, Pedersen)
Backend adapters (native, Winterfell, Plonky2/3)
Crypto core (field math, FRI, Merkle, transcripts)
Responsibilities are strictly separated, which keeps proofs portable and the system extensible.
Adapters advertise a capability matrix, including fields, hashes, FRI arities, recursion support, and commitment gadgets. Example entries include native, winterfell@0.6, and the Plonky family.
ZKD guarantees proof-level determinism. Verify determinism by rebuilding from source and comparing proof digests against the golden vectors in tests/golden_vectors. Prebuilt binaries are convenience only. ([GitHub][1])
git clone https://github.com/EqualFiLabs/zkd
cd zkd
cargo build
cargo testLinux:
cargo build -p zkprov-ffi-c --release
ls target/release/libzkprov.somacOS:
cargo build -p zkprov-ffi-c --release
ls target/release/libzkprov.dylibAndroid (NDK), with toolchain on PATH:
export NDK_HOME="$HOME/Library/Android/sdk/ndk/26.1.10909125"
export TOOLCHAIN="$NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin"
export PATH="$TOOLCHAIN:$PATH"
export TARGET=aarch64-linux-android
cargo build -p zkprov-ffi-c --release --target $TARGET
ls target/$TARGET/release/libzkprov.soReference scaffold and commands are present in the repo README. ([GitHub][1])
CLI:
cargo run -p zkd -- backend-ls
cargo run -p zkd -- profile-lsMinimal prove and verify for a toy program (example paths):
zkd prove -p tests/fixtures/toy.air -i tests/fixtures/toy.json -b native --profile balanced -o /tmp/toy.proof
zkd verify -p tests/fixtures/toy.air -i tests/fixtures/toy.json -b native --profile balanced -P /tmp/toy.proofExpected: proof verifies with stats printed.
Core commands:
zkd compileconverts YAML into canonical AIR.zkd proveruns the selected backend under a given profile.zkd verifyreplays the transcript deterministically.zkd profile lslists available profiles.zkd backend lsshows registered adapters and capabilities.zkd vector validateenforces golden vector parity.
Exit codes and common flags are documented in docs/INTERFACES.md.
Exported symbols:
zkp_init,zkp_prove,zkp_verify,zkp_list_backends,zkp_list_profiles,zkp_free- plus helpers like
zkp_version,zkp_set_callback,zkp_cancelfor richer integrations. Error returns are UTF-8 JSON blobs that callers must free viazkp_free. The context is thread safe and supports concurrent prove and verify.
Official bindings ship for Node, Python, Flutter/Dart, and WASI. Go, .NET, Java/Kotlin, and Swift rely on the DIY bindings cookbook until official packages return. Each wrapper maps the C ABI into idiomatic APIs and types.
- WASI target exports the same C ABI for serverless and browsers. A small JS loader exposes
proveandverifythat mirror the Node API. - Flutter plugin wraps the shared library for Android and iOS and includes finalizers that call
zkp_free. Cookbook guidance covers minimal Swift overlays until the Ecosystem phase adds an official package.
ZKD ships a catalog of ready profiles:
zk-auth-pedersen-secretfor passwordless authzk-allowlist-merklefor set membershipzk-attr-rangefor bounded attributeszk-balance-geqfor balance thresholdzk-age-overfor simple mobile age gates- and more, each with a defined public IO schema and gadgets.
Profiles share a canonical digest rule that binds profile_id, version, public inputs, and proof bytes:
D = H(profile_id || profile_version || canon_pub_inputs || proof_bytes)
This ensures deterministic cross-backend behavior.
ZKD emits a Solidity-ready digest D that a simple verifier stub can check on chain. The digest uses Solidity ABI packing of:
(uint64 backendIdHash, uint64 profileIdHash, uint64 pubioHash, uint64 bodyLen, bytes body)
and then Keccak256. There is a Foundry stub and parity harness in the repo. ([GitHub][1])
To reproduce locally:
cargo test --test evm_interop
(cd examples/evm_verifier && forge test -vv)These exact commands are shown in the repo README. ([GitHub][1])
ZKD defines a backend-neutral Recursion IR so outer proofs can verify multiple inner proofs and reduce them to a single digest. Modes include stark-in-stark with Plonky adapters and an optional SNARK wrapper later. Mobile profiles cap rows and the number of inner proofs to avoid OOM.
The test plan covers unit, integration, cross-backend parity, negative tests, fuzzing, and performance budgets. CI enforces vector parity and emits validation reports. Targets include native and Winterfell in Phase 0, with Plonky adapters added later.
Determinism tests assert equal seeds, headers, and digest D across runs and hosts. Failures raise specific drift errors.
- Phase 0: foundation, commitments, EVM interop, C ABI, bindings, docs.
- Phase 1: portability with Plonky2 and mobile profiles.
- Phase 2: acceleration, Plonky3, recursion execution, optional SNARK wrapper.
- Phase 3: service mode, Docker, SDKs, metrics, cache, auth.
- Phase 4: registry, docs site, public CI matrix, security hardening, v1.0 packaging.
For a detailed task map and acceptance gates, see docs/TASKLIST.md.
- Proof integrity depends on deterministic transcripts and validated manifests.
- Commitment gadgets bind public outputs to constraints and enforce curve checks and blinding rules.
- Golden Vectors and manifest hashes provide a reproducibility oracle to spot supply chain tampering.
Read docs/threat-model.md for complete coverage.
Issues and PRs are welcome. Please include:
- a concise problem statement
- reproducible steps or fixtures
- CI-ready tests and updated docs where relevant
See the test plan and interfaces docs for expected outputs and error contracts.
MIT © EqualFi Labs. ([GitHub][1])
- This README reflects the repo’s current scaffold and commands, including the EVM digest encoding and example Foundry flow shown on the GitHub page. ([GitHub][1])
- Section details map directly to the architecture, interfaces, profiles, recursion, testing, and threat model documents in
docs/.