Snip 36

SNIP-36

Overview

SNIP-36 allows executing a single INVOKE_TXN_V3 off-chain against a reference Starknet block's state, then submitting a stwo-cairo proof on-chain. The proof extends the standard v3 transaction hash by appending a proof_facts_hash. Contracts verify this via get_execution_info_v3_syscall.

Core value: Run arbitrary Cairo logic off-chain (heavy computation, privacy checks, game outcomes, attribute proofs) and commit only the verified result on-chain — without revealing private inputs.

Spec: https://community.starknet.io/t/snip-36-in-protocol-proof-verification/116123

Reference implementation: https://github.com/starknet-innovation/snip-36-prover-backend

Quick Start

1. Review the operator checklist.
2. Add a virtual create_proof function that emits one L2->L1 message.
3. Prove an unsigned virtual tx with snip36 prove virtual-os.
4. Submit verify_result with { proof, proofFacts } and the decoded message.

When to Use

• The user asks for SNIP-36, virtual block proving, off-chain Starknet proof generation, or proof-backed on-chain verification.
• The workflow needs heavy Cairo computation, privacy-preserving inputs, anonymous voting, secret whitelist checks, or replay-safe nullifier patterns.
• The implementation needs a Cairo virtual function, proof server, starknet.js signing flow, and on-chain verify_result contract pattern.

When NOT to Use

• The user needs a normal Starknet transaction that should be broadcast and fee-estimated through standard RPC.
• The proof cannot run on a backend with native binaries, disk, and about 18 GB RAM.
• The security model requires SNOS-native verification instead of Phase 1 sequencer-side proof verification.

Use Cases

• Heavy computation: prove a large hash or algorithm result, then store only the verified output.
• Private attributes: prove age, whitelist membership, or voting weight with a nullifier and public boolean/result.
• Provable games: commit coin flips, seeds, bets, and outcomes for on-chain settlement.
• ZKThread or shard transitions: prove { old_root, new_root, ... } before updating L2 state.

Generic 3-Phase Pattern

textCopy code
PHASE 1 — CREATE (off-chain build)
  Build a signed INVOKE_TXN_V3 that calls the virtual function.
  Never broadcast. Includes public_input + private_input in calldata.

PHASE 2 — PROVE (proof server)
  POST { blockNumber, tx } → snip36 prove virtual-os
  Returns { proof, proofFacts, l2ToL1Messages }
  Duration: ~40-50s, ~18 GB RAM

PHASE 3 — VERIFY (on-chain)
  execute(verify_call, { proof, proofFacts })
  Contract reads proof_facts, recomputes message hash, applies state change.

Part 1 — Cairo Contract

Scarb.toml requirements

tomlCopy code
[[target.starknet-contract]]
allowed-libfuncs-list.name = "all"   # required for get_execution_info_v3_syscall

Virtual function pattern

cairoCopy code
// Called VIRTUALLY (by proof server). Never call directly on-chain.
// public_input  → included in L2→L1 message (visible to verifier)
// private_input → used in computation but NEVER revealed on-chain
fn create_proof(
    ref self: ContractState,
    public_input: PublicInput,
    private_input: PrivateInput,
) {
    // 1. Compute result using both inputs
    let result = heavy_computation(public_input, private_input);

    // 2. Commit result as L2→L1 message — this becomes the proof output
    let mut payload: Array<felt252> = array![];
    // serialize fields the verifier will need:
    payload.append(public_input.field1);
    payload.append(result);
    send_message_to_l1_syscall(
        to_address: 0,   // unused for SNIP-36 (no L1 delivery)
        payload: payload.span()
    ).unwrap();
}

On-chain verify function pattern

cairoCopy code
// Called ON-CHAIN with proof attached via { proof, proofFacts }.
fn verify_result(
    ref self: ContractState,
    public_message: PublicMessage,  // decoded from l2ToL1Messages[0].payload
) {
    // 1. Read proof_facts committed by SNIP-36
    let info = starknet::syscalls::get_execution_info_v3_syscall()
        .unwrap_syscall().unbox();
    let proof_facts = info.tx_info.unbox().proof_facts;

    // 2. Recompute message hash from the submitted public_message
    let message_hash = compute_message_hash(get_contract_address(), @public_message);

    // 3. Assert proof integrity: proof_facts[8] must equal our hash
    assert(*proof_facts[8] == message_hash, 'Proof message mismatch');

    // 4. Apply state change (nullifier, store result, transfer funds, etc.)
    // ...
}

proof_facts layout

textCopy code
index: [0,  1,  2,                   3,  4,            5,          6,              7,          8,             ...]
value: [0,  0,  virtual_OS_prog_hash, 0,  block_number, block_hash, OS_config_hash, n_messages, msg_hash_0,    msg_hash_1, ...]

• [7] = number of L2→L1 messages emitted (usually 1)
• [8] = Poseidon hash of first message (checked against recomputed hash)

Message hash computation (Cairo)

cairoCopy code
fn compute_message_hash(contract_addr: ContractAddress, msg: @PublicMessage) -> felt252 {
    let mut payload: Array<felt252> = array![];
    (*msg).serialize(ref payload);
    let mut data: Array<felt252> = array![
        contract_addr.into(),
        0_felt252,
        payload.len().into(),
    ];
    for f in payload.span() { data.append(*f); }
    poseidon_hash_span(data.span())
}

Nullifier pattern (for replay protection)

cairoCopy code
const NULLIFIER_DOMAIN: felt252 = 'my_app_nullifier_v1';

fn compute_nullifier(unique_id: felt252, secret: Span<felt252>) -> felt252 {
    let secret_hash = poseidon_hash_span(secret);
    poseidon_hash_span(array![NULLIFIER_DOMAIN, unique_id, secret_hash].span())
}

TypeScript equivalent (must match exactly):

typescriptCopy code
const NULLIFIER_DOMAIN = shortString.encodeShortString("my_app_nullifier_v1");

function computeNullifier(uniqueId: string, secret: string[]): string {
    const secretHash = hash.computePoseidonHashOnElements(secret);
    return hash.computePoseidonHashOnElements([NULLIFIER_DOMAIN, uniqueId, secretHash]);
}

Part 2 — Proof Server (Node.js + Rust CLI)

Setup

bashCopy code
git clone https://github.com/starknet-innovation/snip-36-prover-backend
cd snip-36-prover-backend
cargo build --release -p snip36-cli
./target/release/snip36 setup

cp .env.example .env
# STARKNET_RPC_URL=...      (v0.8+ JSON-RPC, e.g. Alchemy)
# STARKNET_ACCOUNT_ADDRESS=...
# STARKNET_PRIVATE_KEY=...
# STARKNET_GATEWAY_URL=https://alpha-sepolia.starknet.io

Express server

typescriptCopy code
// src/index.ts
import express from "express";
import { ensureBuilt } from "./build";
import { proveRouter } from "./prove";

ensureBuilt();
const app = express();
app.use(express.json());
app.use(proveRouter);
app.listen(Number(process.env.PORT ?? 3030));

POST /prove — SSE streaming endpoint

typescriptCopy code
// src/prove.ts
proveRouter.post("/prove", (req, res) => {
    const { blockNumber, tx } = req.body ?? {};
    if (!Number.isInteger(blockNumber) || blockNumber < 0 || typeof tx !== "object" || tx == null) {
        res.status(400).json({ code: "SNIP36_INVALID_REQUEST", message: "blockNumber or tx is invalid" });
        return;
    }

    const txJsonPath = `./tmp/tx-${Date.now()}.json`;
    const outputBase = `./output/prove-${Date.now()}`;
    const proofPath = `${outputBase}.proof`;
    const proofFactsPath = `${outputBase}.proof_facts`;
    const rawMessagesPath = `${outputBase}.raw_messages.json`;
    const cleanupPaths = [txJsonPath, proofPath, proofFactsPath, rawMessagesPath];
    const args = [
        "prove", "virtual-os",
        "--block-number", String(blockNumber),
        "--tx-json", txJsonPath,
        "--rpc-url", process.env.STARKNET_RPC_URL!,
        "--output", proofPath,
    ];

    res.setHeader("Content-Type", "text/event-stream");
    res.flushHeaders();

    let child: ReturnType<typeof spawn> | undefined;
    let timeout: NodeJS.Timeout | undefined;
    let settled = false;
    let timedOut = false;
    const errorDetails = (error: unknown) => error instanceof Error ? error.message : String(error);
    const send = (event: "log" | "done" | "error", data: object) =>
        !settled && res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);

    const cleanup = () => {
        for (const p of cleanupPaths) {
            try {
                if (fs.existsSync(p)) fs.unlinkSync(p);
            } catch (error) {
                send("log", { stream: "cleanup", line: `failed to remove ${p}: ${errorDetails(error)}` });
            }
        }
    };

    const finish = () => {
        if (settled) return;
        if (timeout) clearTimeout(timeout);
        cleanup();
        settled = true;
        res.end();
    };

    try {
        fs.mkdirSync("./tmp", { recursive: true });
        fs.mkdirSync("./output", { recursive: true });
        fs.writeFileSync(txJsonPath, JSON.stringify(tx));
        child = spawn(BINARY, args, { cwd: REPO_CWD, env: process.env });
    } catch (error) {
        send("error", { code: "SNIP36_PROVER_START_FAILED", message: "failed to start snip36", details: errorDetails(error) });
        finish();
        return;
    }

    timeout = setTimeout(() => {
        timedOut = true;
        send("error", { code: "SNIP36_PROVER_TIMEOUT", message: "snip36 timed out", details: "terminated after 10 minutes" });
        child?.kill("SIGTERM");
    }, 10 * 60 * 1000);

    child.on("error", error => {
        send("error", { code: "SNIP36_PROVER_START_FAILED", message: "snip36 process failed", details: errorDetails(error) });
        finish();
    });
    child.stdout.on("data", c => send("log", { stream: "stdout", line: c.toString() }));
    child.stderr.on("data", c => send("log", { stream: "stderr", line: c.toString() }));

    child.on("close", code => {
        if (settled) return;
        try {
            if (timedOut) return;
            if (code !== 0) {
                send("error", { code: "SNIP36_PROVER_EXIT_NON_ZERO", message: "snip36 exited non-zero", details: `exit code ${code}` });
                return;
            }
            if (!fs.existsSync(proofPath) || !fs.existsSync(proofFactsPath)) {
                throw new Error("missing proof or proof_facts artifact");
            }
            const proof = fs.readFileSync(proofPath, "ascii").trim();
            const proofFacts = JSON.parse(fs.readFileSync(proofFactsPath, "ascii"));
            const l2ToL1Messages = fs.existsSync(rawMessagesPath)
                ? JSON.parse(fs.readFileSync(rawMessagesPath, "ascii")).l2_to_l1_messages
                : undefined;
            send("done", { proof, proofFacts, ...(l2ToL1Messages && { l2ToL1Messages }) });
        } catch (error) {
            send("error", { code: "SNIP36_ARTIFACT_READ_FAILED", message: "failed to read proof artifacts", details: errorDetails(error) });
        } finally {
            finish();
        }
    });
});

Output artifacts and env

The CLI emits *.proof (base64 stwo proof), *.proof_facts (JSON hex felt252s), and optional *.raw_messages.json with l2_to_l1_messages.

Required env: STARKNET_RPC_URL, STARKNET_ACCOUNT_ADDRESS, STARKNET_PRIVATE_KEY, STARKNET_GATEWAY_URL, STARKNET_CHAIN_ID, and PORT.

Part 3 — Starknet.js Integration

SSE client

typescriptCopy code
// requestProof.ts
type ProveResult = { proof: string; proofFacts: BigNumberish[]; l2ToL1Messages?: { payload: BigNumberish[] }[] };

export async function requestProof(blockNumber: number, tx: INVOKE_TXN_V3): Promise<ProveResult> {
    const res = await fetch(`${process.env.PROOF_SERVER_URL ?? "http://localhost:3030"}/prove`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ blockNumber, tx }),
    });

    const reader = res.body!.getReader();
    const dec = new TextDecoder();
    let buf = "";
    let result: ProveResult | undefined;

    while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        buf += dec.decode(value, { stream: true });
        const parts = buf.split("\n\n");
        buf = parts.pop() ?? "";
        for (const msg of parts) {
            const event = msg.match(/^event: (\w+)/)?.[1];
            const data = JSON.parse(msg.match(/^data: (.+)$/m)?.[1] ?? "null");
            if (event === "done") result = data;
            if (event === "error") throw Object.assign(new Error(data.message), { code: data.code, details: data.details });
        }
    }
    if (!result) throw new Error("No proof result");
    return result;
}

Virtual transaction build + proof orchestration

typescriptCopy code
// server-side only: private inputs and signing keys must never reach the browser.
async function proveAndVerify(publicInput: unknown, privateInput: unknown): Promise<string> {
    const provider = new RpcProvider({ nodeUrl: process.env.RPC_URL! });
    const account = new Account({
        provider,
        address: process.env.ACCOUNT_ADDRESS!,
        signer: process.env.PRIVATE_KEY!,
    });
    const contract = new Contract({ abi, address: CONTRACT_ADDRESS, providerOrAccount: account });

    // 1. Build virtual call (never broadcast)
    const call = contract.populate("create_proof", { public_input: publicInput, private_input: privateInput });

    // 2. Must set resourceBounds manually; fee estimation would expose private calldata.
    const prices = await provider.getGasPrices();
    const M = 2n;
    const resourceBounds = {
        l2_gas:     { max_amount: 0x279fc0n * M, max_price_per_unit: prices.l2GasPrice * M },
        l1_gas:     { max_amount: 0xbd2an * M,   max_price_per_unit: prices.l1GasPrice * M },
        l1_data_gas:{ max_amount: 0xc0n * M,     max_price_per_unit: prices.l1DataGasPrice * M },
    };

    // 3. Requires the proof-enabled starknet.js fork, not standard starknet.js.
    const tx: INVOKE_TXN_V3 = await account.getSignedTransaction(call, { resourceBounds });
    const blockNumber = await provider.getBlockNumber();
    const proofResult = await requestProof(blockNumber, tx);

    const cd = new CallData(abi);
    const publicMessage = cd.decodeParameters(
        "my_contract::PublicMessage",
        proofResult.l2ToL1Messages![0].payload as string[]
    );

    const verifyCall = contract.populate("verify_result", { public_message: publicMessage });
    const { transaction_hash } = await account.execute(verifyCall, {
        proof: proofResult.proof,
        proofFacts: proofResult.proofFacts,
    } as any);

    return transaction_hash;
}

SNIP-36 transaction hash extension

textCopy code
Standard v3: poseidon(INVOKE, version, sender, tip_rb_hash, paymaster_hash,
                      chain_id, nonce, da_mode, acct_deploy_hash, calldata_hash)

SNIP-36:     poseidon(INVOKE, version, sender, tip_rb_hash, paymaster_hash,
                      chain_id, nonce, da_mode, acct_deploy_hash, calldata_hash,
                      proof_facts_hash)    ← appended only when proof_facts present

account.execute(call, { proof, proofFacts }) handles the hash extension automatically in starknet.js.

Frontend boundaries

• Browser: collect public inputs, optionally request a wallet signature, and poll for the final transaction hash.
• Server: keep RPC_URL, ACCOUNT_ADDRESS, PRIVATE_KEY, PROOF_SERVER_URL, getSignedTransaction(), and /prove calls off the client.
• RPC proxy: route browser RPC through a server endpoint if the provider key is sensitive.

Only expose NEXT_PUBLIC_CONTRACT_ADDRESS or other non-secret addresses to the browser.

Critical Pitfalls

Error Codes & Recovery

Quick Reference

textCopy code
Contract: create_proof(public, private) -> emit L2->L1 message
Contract: verify_result(public_msg) -> check proof_facts[8] and apply state
Optional: read_result() -> query stored result/nullifier
Facts:    proof_facts[7] = n_messages; proof_facts[8] = poseidon(contract, 0, len, payload)
CLI:      snip36 prove virtual-os --block-number N --tx-json tx.json --rpc-url URL --output out.proof
HTTP:     POST /prove { blockNumber, tx } -> SSE log* then done|error
JS:       getSignedTransaction(call, { resourceBounds }) then execute(verifyCall, { proof, proofFacts })