Skip to content
blueshift-ggPublic

About

Zero-knowledge circuits in plain Rust, verified on Solana.

Topics

Resources

Security policy

Stars

54 stars

Watchers

0 watching

Forks

Repository files navigation

xark

CI crates.io License: MIT

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());
}

Why xark

  • 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 client turns 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.

Quickstart

You need Rust 1.89 or newer.

1. Install the CLI, and check your setup:

cargo install xark-cli
xark doctor

2. 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-circuit

3. 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 ... ok

4. 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.00s

Try 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.

Learn more

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

Going to production

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.

Gadgets

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

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>.

Status

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.

Contributing

cargo xtask ci                  # every CI check, side by side
cargo test --workspace --release
cargo xtask digests --check     # every example's circuit is unchanged

crates/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.

License

MIT

About

Zero-knowledge circuits in plain Rust, verified on Solana.

Topics

Resources

Security policy

Stars

54 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages