Learn-skills.dev jolt

Invoke when the user says: "make this Jolt provable", "wrap this in Jolt", "prove this with Jolt", "add ZK proofs to this", "make this zero-knowledge", "make this provable", "jolt-ify this".

Step 1 — Identify the computation to prove

Look for a pure, deterministic Rust function — inputs in, result out, no I/O or side effects. If not obvious, ask:

"What function should I make provable? It needs to be a pure Rust function with no I/O or side effects."

Before writing any guest code, verify the target function and its entire module path are

pub

pub

Step 2 — Analyze and adapt the signature

The guest has a real heap —

Vec

String

Vec<T>

[T; N], len: u32

[T; N]

usize

u32

f32

f64

i64 * 1_000_000

std::io

std::net

Build mode: read the library's

Cargo.toml

Step 3 — Install Jolt

jolt --version  # check if installed
cargo install --git https://github.com/a16z/jolt --force jolt  # if not

Step 4 — Scaffold

If inside an existing Rust library repo, propose:

"I'll create

<library-name>-jolt/

here with the proof scaffold and import your library as a path dependency. Sound good?"

jolt new <project-name>        # standard mode
jolt new <project-name> --zk   # with PrivateInput + BlindFold support

This generates a workspace with a

fib

fib

<fn>

src/main.rs

guest/src/lib.rs

[patch.crates-io]

Cargo.toml

Step 5 — Write the guest (

guest/src/lib.rs

)

no_std mode (default):

#![cfg_attr(feature = "guest", no_std)]
extern crate alloc;  // heap always available

#[jolt::provable]
fn <fn>(<params>) -> <ret> { ... }

std mode — in

guest/Cargo.toml

jolt = { package = "jolt-sdk", git = "https://github.com/a16z/jolt", features = ["guest-std", "thread", "stdout"] }

Include

"thread"

"stdout"

println!

cfg_attr

Macro parameters — use

#[jolt::provable]

stack_size

stack overflow

max_trace_length

max_trace_length exceeded

analyze_<fn>

heap_size

heap allocation failed

Prover-only inputs — two options depending on whether you need cryptographic privacy:

• jolt::UntrustedAdvice<T>

  — prover-only; excluded from the verifier API but values may be recoverable from the proof

• jolt::PrivateInput<T>

  — same underlying type, signals that values should be cryptographically hidden via BlindFold (requires

  zk

  on the host, not the guest)

#[jolt::provable]
fn my_fn(public: u64, secret: jolt::UntrustedAdvice<[u8; 32]>) -> bool {
    let secret = *secret;
    // ...
}

Host prove call:

prove(..., UntrustedAdvice::new(val))

use jolt_sdk::UntrustedAdvice;

For

PrivateInput<T>

zk

TrustedAdvice<T>

commit_trusted_advice_<fn>(...)

Dependencies — add to

guest/Cargo.toml

<library> = { path = "../.." }

default-features = false

jolt-inlines-sha2

jolt-inlines-keccak256

jolt-inlines-secp256k1

Multiple functions — each

#[jolt::provable]

compile_*

preprocess_*

build_prover_*

build_verifier_*

Advice functions — for expensive witness computation that should run outside the proof, use

#[jolt::advice]

jolt::check_advice_eq!(computed, expected)

Cycle tracking — instrument sections of the guest to measure per-section cycle counts (visible in the prover log):

use jolt::{start_cycle_tracking, end_cycle_tracking};

start_cycle_tracking("my section");
// ... code to measure ...
end_cycle_tracking("my section");

Step 6 — Write the host (

src/main.rs

)

use std::time::Instant;
use tracing::info;

pub fn main() {
    tracing_subscriber::fmt().with_env_filter(
        tracing_subscriber::EnvFilter::from_default_env()
    ).init();

    let target_dir = "/tmp/jolt-guest-targets";
    let mut program = guest::compile_<fn>(target_dir);
    let shared = guest::preprocess_shared_<fn>(&mut program);
    let prover_prep = guest::preprocess_prover_<fn>(shared.clone());
    let verifier_setup = prover_prep.generators.to_verifier_setup();
    let verifier_prep = guest::preprocess_verifier_<fn>(shared, verifier_setup, None);
    let prove = guest::build_prover_<fn>(program, prover_prep);
    let verify = guest::build_verifier_<fn>(verifier_prep);

    let t = Instant::now();
    let (output, proof, io) = prove(<inputs>);
    info!("Prover runtime: {} s", t.elapsed().as_secs_f64());

    // io.panic is true if the guest panicked; the verifier checks it matches the proof
    let is_valid = verify(<inputs>, output, io.panic, proof);
    info!("output: {:?}", output);
    info!("valid: {is_valid}");
    assert!(is_valid);
}

For multiple functions, replicate the block per function. To measure cycles before proving:

guest::analyze_<fn>(<inputs>).write_to_file("summary.txt".into()).unwrap()

Step 7 — Run

Before running, estimate peak memory from

max_trace_length

If

max_trace_length

"This may require ~X GB of RAM. I can: (a) run

analyze_<fn>

first to get the actual cycle count — if it's well below

max_trace_length

we can lower it and reduce memory significantly, or (b) proceed directly. Which do you prefer?"

RUST_LOG=info cargo run --release

For full zero-knowledge (hides witness via BlindFold protocol), enable

zk

jolt new --zk

Host

Cargo.toml

jolt-sdk = { git = "https://github.com/a16z/jolt", features = ["host", "zk"] }

Guest

Cargo.toml

jolt = { package = "jolt-sdk", git = "https://github.com/a16z/jolt", features = ["zk"] }

In the host, pass

BlindfoldSetup

let blindfold_setup = prover_prep.blindfold_setup();
let verifier_prep = guest::preprocess_verifier_<fn>(shared, verifier_setup, Some(blindfold_setup));

Preprocessing runs once on first invocation and is not included in "Prover runtime". Diagnose failures:

max_trace_length exceeded

max_trace_length = N

heap allocation failed

heap_size = N

stack overflow

stack_size

Illegal instruction

could not find crate

does not implement Serialize

#[derive(serde::Serialize, serde::Deserialize)]

Step 8 — Summarize

Tell the user: what function was made provable, what type adaptations were applied and why, std or no_std mode, and how to run it.

Once the proof runs end-to-end, always offer a performance optimization pass:

"The proof works! Want me to optimize it? I can tighten

max_trace_length

to reduce memory and proving time, profile which sections dominate cycle count, and offload expensive witness computation."

Step 9 — Optimize (offer after Step 8 succeeds)

Work through these in order:

1. Tighten

max_trace_length

guest::analyze_<fn>(<inputs>)

max_trace_length

2. Find the bottleneck — add

start_cycle_tracking

end_cycle_tracking

analyze_<fn>

3. Offload expensive witness computation — if a section is expensive to compute but cheap to verify (sorting, hashing, witness generation), convert it to

#[jolt::advice]

#[jolt::advice]
fn sort_array(input: &[u64]) -> jolt::UntrustedAdvice<Vec<u64>> {
    let mut v = input.to_vec();
    v.sort_unstable();
    v
}

#[jolt::provable]
fn my_fn(input: &[u64]) -> bool {
    let adv = sort_array(input);
    let sorted = &*adv;
    // O(n) verification: sorted order + length
    jolt::check_advice!(sorted.windows(2).all(|w| w[0] <= w[1]));
    jolt::check_advice!(sorted.len() == input.len());
    true
}

4. Use crypto inlines — for SHA-2, Keccak, secp256k1, replace standard crate calls with

jolt-inlines-*

jolt-inlines-sha2 = { git = "https://github.com/a16z/jolt" }

5. Trim

stack_size

heap_size

max_trace_length