Zero-knowledge circuits in plain Rust, verified on Solana. · xark.gg
You write a circuit as an ordinary Rust function. xark compiles it with your
stable rustc, proves it with Groth16, and gives you a verifier for your Solana
program. Proofs are 256 bytes.
use xark::prelude::*;
/// I know a square root of `result`, and I won't say what it is.
#[circuit]
pub fn square_root(secret: Private<Field>, result: Public<Field>) {
require_eq(secret * secret, result);
}
#[test]
fn only_a_square_root_proves() {
square_root(3, 9).unwrap();
assert!(square_root(3, 10).is_err());
}- It's just Rust. No circuit DSL to learn. You get stable
rustc, your editor,cargo test, and crates. A gadget is a Cargo dependency. - Errors point at your code. Inputs that break the circuit are reported as the line that fails, in tests, at the command line and in the TypeScript client.
- Small proofs, cheap verification. A Groth16 proof over BN254 is 256 bytes and verifies on Solana in about 77k compute units.
- Typed clients.
xark clientturns your circuit's inputs into a typed TypeScript client that proves and verifies in Node or the browser. - The hard gadgets are done. Poseidon, Poseidon2, SHA-256, Keccak, BLAKE2s, BLAKE3, Merkle proofs, AES, and ECDSA (secp256k1, P-256) and Ed25519 signature verification.
You need Rust 1.89 or newer.
1. Install the CLI, and check your setup:
cargo install xark-cli
xark doctor2. Start a project. xark init makes a project with the square-root circuit
above, and two tests, in circuits/my-circuit/:
xark init my-circuit && cd my-circuit3. Test it. At the project's root, xark test builds the circuit, then runs its
tests:
$ xark test
xark building circuit `my-circuit`
xark 2 vars, 1 constraints, 0 witness-gen ops
xark circuit digest 75e3ce529473dfaa2f89a85a0d588228
...
test tests::accepts_valid ... ok
test tests::rejects_invalid ... ok4. Prove. The first proof also makes the key, from your machine's randomness:
$ xark prove --inputs '{"secret": 3, "result": 9}'
...
✅ Proof produced and self-checked (1 public input(s)).
solved in 0.00s, proved in 0.00sTry inputs that don't satisfy the circuit, and xark shows you where:
$ xark prove --inputs '{"secret": 3, "result": 10}'
error: witness does not satisfy the circuit
src/lib.rs:6:16 require_eq(secret * secret, result);5. Verify it on Solana. xark add program writes a Pinocchio program that
verifies the circuit's proofs, and a LiteSVM test that proves with the generated
TypeScript client and sends the proof to it. xark build builds the circuit, its
clients and the program; xark test runs every test. You need the
Solana CLI for cargo build-sbf, and
Node:
$ xark add program my-circuit
$ xark build
...
✅ Onchain verifier crate ready (verifying key embedded).
✅ TypeScript client for `my_circuit` at clients/my-circuit/ts/my_circuit.ts
xark building the programs (cargo build-sbf)
$ npm install && xark test
...
Test Files 1 passed (1)Commit everything xark build writes, the keys in keys/ included: the
generated clients embed the verifying key, and the CI workflow xark init wrote
checks they match the source (xark build --check).
The program depends on clients/my-circuit/rust/, the verifier crate xark build
generates (my-circuit-verifier). Its PublicInputs has the circuit's public
inputs by name, packed for you, and verify takes it:
let proof = my_circuit_verifier::Proof::from_le_bytes(proof_bytes);
let inputs = my_circuit_verifier::PublicInputs {
result: /* from your program's state, 32 bytes little-endian */,
};
if !my_circuit_verifier::verify(&proof, inputs) {
return Err(ProgramError::InvalidArgument);
}A key you make yourself is a single-party trusted setup: whoever relies on your
verifier trusts that you didn't keep its randomness. For a key no one party has to
be trusted for, run a multi-party ceremony: see Trusted setup.
The verifier crate's SETUP constant says which kind of key it embeds.
Writing circuits
- Testing a circuit: the generated validator, failing lines, running circuit code on the host
- Inputs:
#[input]structs, and the built-in types (dates, timestamps, text, enums and sets) - What Rust compiles: the supported subset, and what's rejected
- Editor diagnostics: circuit errors inline in rust-analyzer
Using proofs
- Migrating from 0.3: keep a circuit crate, or move it into a project, keeping your keys
- TypeScript clients: typed provers and verifiers for Node and the browser
@blueshift-gg/xark: the WebAssembly prover and verifier underneathxark-verifier: the on-chain verifier
Going to production
- Trusted setup: a multi-party ceremony instead of a single-party key
- Reproducible builds of the on-chain verifier
- Security and audit status
How it works
- Architecture: Rust → wasm → constraints → Groth16 → Solana
- Toolchains: why a circuit is the same under every stable
rustc
Every command has --help, and xark <command> defaults to the crate in the
current directory.
Each gadget is its own crate under gadgets/. Add the ones you use:
[dependencies]
xark = "0.4"
xark-poseidon2 = "0.4"| Crate | What it does |
|---|---|
xark-poseidon, xark-poseidon2 |
Poseidon and Poseidon2 hashes over BN254, the cheapest in a circuit |
xark-sha256, xark-keccak, xark-blake2s, xark-blake3 |
Standard hashes, matching their native implementations |
xark-mimc, xark-pedersen |
MiMC and Pedersen hashes |
xark-merkle |
Merkle trees: membership, appends, non-membership (indexed trees) |
xark-aes |
AES-128/256 block cipher, CTR and GCM |
xark-secp256k1, xark-secp256r1 |
ECDSA signature verification on secp256k1 and P-256 |
xark-ed25519 |
Ed25519 (EdDSA) signature verification |
xark-grumpkin |
The Grumpkin curve, for recursion and folding, and Schnorr signatures over it |
xark-bits, xark-bignum, xark-curve, xark-hash |
Building blocks for writing your own gadgets |
examples/ has 74 runnable circuits, from cube to zkyc (a private
credential check against a public policy), with the gadgets above at work. Test
any of them with xark test examples/<name>.
Experimental, and not yet audited. Don't deploy a key made in dev mode, and don't rely on xark in production before an independent audit. See audit status.
cargo xtask ci # every CI check, side by side
cargo test --workspace --release
cargo xtask digests --check # every example's circuit is unchangedcrates/lang's test suites are heavy, so CI runs them separately:
cargo test --release -p xark. Toolchains explains why a
change that alters any circuit must update the digests.