DEV Community: Jet Halo

How to Create a Zero Knowledge DApp: From Zero to Production, Case 2: zk P2P

Jet Halo — Tue, 21 Apr 2026 13:26:25 +0000

Can a P2P on-ramp still work without a platform acting as escrow?

In the world of crypto, the first thing a newcomer really has to do to enter the space is usually not trading and not doing DeFi, but completing an on-ramp first.

And the on-ramp flow most people are familiar with is usually an OTC exchange on an exchange: the user sends fiat first, and after the platform confirms the payment, it releases USDT or USDC.

The reason this works has never been just matching. The exchange holds the decision-making power in the middle. It custody-holds one side of the assets first, judges whether the off-chain payment is real, and then decides whether the crypto should be released. As long as those three things stay in the platform’s hands, users assume the trade can be completed.

The question is: what happens if you remove that layer of platform-backed escrow?

The buyer can send a bank transfer directly to the seller, and the seller can promise that they have enough stablecoin liquidity. But the hard parts show up immediately:

Who guarantees that the seller’s on-chain funds are actually ready
Who guarantees that the buyer’s off-chain payment is real, instead of a screenshot or a forged receipt
Who guarantees that this payment corresponds to the current order
Who prevents the same payment proof from being reused to exchange for crypto again

The reason the platform model is stable is that the platform keeps handling these four things for the user.

Without relying on an exchange to make the final decision, can a P2P fiat-to-USDC on-ramp still work, and can the final release step be turned into an on-chain release driven by verification results? This article tries to achieve that with zk.

If you want to run this case first, you can go directly to the installation steps in the zkVerify zk-p2p example docs. The demo site is at zkp2p-demo-web.vercel.app, and the GitHub repository is JetHalo/zkp2p-demo.

After reading this article, you will probably come away with three things:
First, if a P2P fiat-to-USDC on-ramp does not rely on exchange arbitration, how the on-chain funds should be locked first;
Second, how a Wise payment record goes through zkTLS / TLSNotary, the verifier, and wiseReceiptHash to enter the proving path;
Third, how a Noir proof generated locally in the browser eventually goes through Kurier, zkVerify, and the aggregation tuple before being consumed on-chain by releaseWithProof(...).

1. Why P2P on-ramps still rely on platform-backed escrow today

The flow on a traditional OTC platform looks smooth:

The seller posts an order
The buyer places an order
The buyer pays off-chain
The platform confirms receipt
The platform releases the crypto

But this path works because the platform controls the state on both sides at the same time.

On one side, it controls the assets in an on-chain or custodial account. The platform can hold that portion of the crypto first so it cannot move before the trade is completed. On the other side, it controls confirmation of the off-chain payment. The platform gets to decide whether a receipt, a screenshot, or a bank transfer record counts as completed payment, together with confirmation from both parties. And once there is a dispute between buyer and seller, the platform can directly arbitrate.

So in the platform model, the core of the on-ramp is never “the buyer and seller agreed by themselves,” but “the platform holds the final authority to decide whether the crypto should be released.”

Once the platform is removed, the real problem is no longer matching efficiency, but how to rebuild these three layers of trust:

Liquidity has to be locked first
Payment has to be verifiable
After verification passes, the release action has to be completed by the chain itself

If any one of these three layers still depends on manual judgment, then the platform-backed escrow has not really been removed.

2. What zkp2p is and how it works

zkp2p can be understood in simple terms like this:

The buyer pays on Wise first, the system turns that payment into a piece of verifiable evidence, and then the chain releases the USDC that the seller locked earlier on-chain to the buyer.

Below, this path is unfolded step by step:

The seller first deposits the USDC they want to sell into an on-chain pool
The buyer creates an intent on the page, which locks part of that liquidity first
The buyer then completes a real payment on Wise
The browser extension and zkTLS/TLSNotary turn that payment into an attestation
The backend verifier validates the attestation and compresses it into wiseReceiptHash
The browser locally generates a proof with Noir + UltraHonk
Your Web API submits the proof to Kurier and waits for zkVerify to complete verification and aggregation
After the frontend gets the aggregation tuple, the buyer calls releaseWithProof(...) themselves
Only after contract verification passes does the previously locked USDC get sent to the buyer

So the key to this path is not simply “prove that a payment happened,” but making three things true at the same time:

The funds have already been locked on-chain in advance
The payment has been compressed into verification input that the later system can continue to consume
The final release is not based on a platform judgment, but on-chain verification of the aggregation result

First, take a look at the overall architecture diagram.

There are actually three different flows in this overall diagram.

The first is the fund flow. The seller first puts the assets into the Deposit Pool, and after the buyer completes the off-chain payment, the chain releases the corresponding portion of USDC from the pool.

The second is the proof flow. The payment data on the Wise page is first captured by the zkTLS/TLSNotary plugin, then compressed by the verifier into wiseReceiptHash, and then a proof is generated locally in the browser.

The third is the on-chain consumption flow. The proof itself is not consumed directly by the contract. It first goes through Kurier and zkVerify and is then assembled into an aggregation tuple. The frontend reads that tuple back from the Kurier API, and the place that actually consumes and verifies it is the gateway and DepositPool on the Horizen target chain.

If these three flows are mixed together, it becomes easy to assume that “once the browser generates a proof, the money is released.” In reality, one of the most important design points here is this: there is still an independent verification and aggregation path between the proof and the payout.

3. What components make up the system

Before talking about sequence, first make the object boundaries clear.

Because the easiest thing to mix up in this project is to treat the browser plugin, the TLSN-side artifact, your verifier service, your Web API, and Kurier / zkVerify as one big blob called “the backend.”

But their responsibilities inside the system are completely different.

After looking at this diagram, we can understand it from five directions.

First, Seller and Buyer are not directly making an on-chain transfer between each other.

The seller provides liquidity by first putting funds into the on-chain Deposit Pool. The buyer uses the dApp and plugin in the browser, and in the end it is also the buyer who signs the releaseWithProof() transaction. The seller does not manually send crypto directly to the buyer anywhere in this path.

Second, the browser itself is not a single frontend block either.

The dApp is responsible for placing the order, creating the intent, showing status, and finally providing the release entrypoint.
The Proof Plugin is responsible for capture, letting the user select the target transfer from recent payments, triggering proving, submitting the proof, and polling status.
The Local Prover is the Noir runtime and proving backend that actually runs in the browser.

Third, zkTLS/TLSNotary.

apps/tlsn-wise-plugin is responsible for producing the Wise-specific TLSN wasm artifact, while apps/tlsn-wasm-host only hosts that wasm. Their job is to “generate the attestation,” not to “verify the attestation,” and even less to “submit the proof to zkVerify.”

Fourth, the services are split into two layers.

tlsn-verifier: dedicated to attestation verification, normalizing transfer fields, and producing wiseReceiptHash
apps/web API: responsible for /api/verify-wise-attestation, /api/submit-proof, /api/proof-status, and /api/proof-aggregation

Fifth, Kurier + zkVerify are the proof relay and the verification network.

4. How the seller’s money gets locked first

First, fix the numbers for this order:

seller deposit 1000 USDC
buyer reserve 100 USDC

The first step is deposit().

function deposit(uint256 amount) external {
    if (amount == 0) revert InvalidAmount();

    bool ok = token.transferFrom(msg.sender, address(this), amount);
    if (!ok) revert TransferFailed();

    sellerDeposits[msg.sender] += amount;
    totalDeposited += amount;
    availableBalance += amount;

    emit Deposited(msg.sender, amount);
}

Code location: contracts/src/Zkp2pDepositPool.sol

After this step, there are three new pieces of on-chain state:

sellerDeposits[msg.sender]
totalDeposited
availableBalance

At this point there is still no order. The contract has only placed the seller’s liquidity into the pool first.

The second step is createIntent().

function _createIntent(
    bytes32 intentId,
    address seller,
    uint256 amount,
    uint256 deadline,
    bytes32 nullifierHash,
    bytes32 intentHash,
    bytes32[] memory cleanupIntentIds
)
    private
{
    if (seller == address(0)) revert InvalidSeller();
    if (amount == 0) revert InvalidAmount();
    if (deadline <= block.timestamp) revert InvalidDeadline();

    if (availableBalance < amount) revert InsufficientAvailableBalance();
    if (sellerDeposits[seller] < sellerReserved[seller] + amount) revert SellerDepositTooLow();

    intents[intentId] = Intent({
        seller: seller,
        buyer: msg.sender,
        amount: amount,
        deadline: deadline,
        reserved: true,
        released: false,
        cancelled: false,
        nullifierHash: nullifierHash,
        intentHash: intentHash
    });

    availableBalance -= amount;
    reservedBalance += amount;
    sellerReserved[seller] += amount;
}

Code location: contracts/src/Zkp2pDepositPool.sol

This step is where the order is actually written on-chain. What the contract records is:

Which seller this order belongs to
Who the buyer address is
How much the amount is
When it expires
The nullifierHash that must match later during release
The intentHash that must match later during release

At the same time, availableBalance goes down, while reservedBalance and sellerReserved[seller] go up. That is how the 100 USDC is split out and locked from the seller’s total liquidity.

Once this contract section is done, there is already a locked intent on-chain. The later payment proof, proof, and tuple all continue downward around this intent.

The contract also prepares a recovery path when the order expires:

function cancelExpiredIntent(bytes32 intentId) external {
    Intent storage intent = intents[intentId];
    if (!intent.reserved) revert IntentNotReserved();
    if (intent.released) revert IntentAlreadyReleased();
    if (intent.cancelled) revert IntentAlreadyCancelled();
    if (block.timestamp <= intent.deadline) revert IntentNotExpired();

    intent.reserved = false;
    intent.cancelled = true;

    reservedBalance -= intent.amount;
    availableBalance += intent.amount;
    sellerReserved[intent.seller] -= intent.amount;
}

Code location: contracts/src/Zkp2pDepositPool.sol

This part returns the seller’s amount back to the available state after timeout, so later orders can continue to use it.

5. The browser layer: the page prepares the order first, then hands the proving work to the plugin

Next, go back to the page. The page first computes all the fields needed for the current order, then hands this group of fields to the plugin.

The entrypoint on the page is reserveIntentOnChain().

const intentId = randomHex32();
const intentHash = intentId;
const proverSecret = randomFieldSecret();
const nullifierHash = buildNullifier({ secret: proverSecret, intentId });
const businessDomain = nonEmptyString(process.env.NEXT_PUBLIC_BUSINESS_DOMAIN, "zkp2p-horizen");
const appId = nonEmptyString(KURIER_API_ID, "zkp2p");
const statement = buildStatement({
  intentId,
  buyerAddress: buyerAddress as `0x${string}`,
  amount,
  chainId: network.chainId,
  timestamp: nowSec,
  businessDomain,
  appId
});

tx = await contract["createIntent(bytes32,address,uint256,uint256,bytes32,bytes32)"](
  intentId,
  order.quote.sellerAddress,
  amount,
  deadline,
  nullifierHash,
  intentHash
);

Code location: apps/web/pages/zkp2p-horizen-release.tsx

Here the page prepares all the core fields needed later in one shot:

intentId
intentHash
proverSecret
nullifierHash
statement

In the current implementation, intentHash = intentId. This convention is carried forward later in the plugin and in the circuit as well.

After the page creates the on-chain intent, it hands this order context to the plugin. The code is inside startPluginProofWithAmount().

const payload = {
  proofId,
  intentId,
  intentHash,
  buyerAddress: walletAddress ?? defaultBuyerAddress,
  amount: String(Math.round(amountUsdc * 1_000_000)),
  businessDomain: nonEmptyString(reservation?.businessDomain, fallbackBusinessDomain),
  aggregationDomainId: KURIER_AGGREGATION_DOMAIN_ID,
  appId: nonEmptyString(reservation?.appId, fallbackAppId),
  chainId: reservationChainId ?? fallbackChainId,
  timestamp: reservationTimestamp ?? fallbackTimestamp,
  nullifier,
  proverSecret,
  verificationMode: "aggregation-kurier",
  proofSystem: "ultrahonk",
  submitEndpoint: `${location.origin}/api/submit-proof`,
  statusEndpoint: `${location.origin}/api/proof-status`,
  aggregationEndpoint: `${location.origin}/api/proof-aggregation`,
  wiseAttestationEndpoint:
    process.env.NEXT_PUBLIC_TLSN_VERIFIER_URL ?? `${location.origin}/api/verify-wise-attestation`,
  tlsnPluginUrl: process.env.NEXT_PUBLIC_TLSN_WISE_PLUGIN_URL ?? "",
  statement: reservation?.statement ?? null,
  deadline: reservation?.deadline ?? null
};

const result = await plugin.startProof(payload);

Code location: apps/web/pages/zkp2p-horizen-release.tsx

This puts three groups of information into the same session in one go:

The on-chain intent context
The fields used by browser proving
The three later backend entrypoints for submit/status/aggregation

From here, the plugin has the full proof session. The later capture, verify, prove, submit, and poll steps all proceed around this session.

Mapped onto the sequence diagram, it is this section below:

6. zkTLS / TLSNotary: first turn the Wise page into an attestation

Next, the page hands the work to the plugin. The plugin first enters the capture stage.

At this point, two concepts need to be explained clearly first: TLSNotary and wasm.

TLSNotary can be understood first as a kind of “webpage forensics” tool. When we open the Wise page, the payment record on the page is just a string of text shown in the browser. A screenshot can capture that text too, but a screenshot cannot prove that this content really came from Wise, and it cannot prove that the content was obtained inside a real TLS session. What TLSNotary is trying to do is turn “I saw this payment in the browser” into an attestation that can continue to be verified later.

wasm does not need to be made too complicated here. It is just a binary program that can run in the browser. The wise.plugin.wasm in this project is not a normal frontend resource and not contract bytecode. It is more like a small program written specifically for the browser plugin to execute. After the plugin loads it, this wasm interacts with the Wise page according to prewritten rules, gathers the page content and TLS session material that is needed, and finally generates the attestation.

So the relationship at this layer can be remembered simply like this:

TLSNotary is responsible for turning webpage content into a verifiable attestation
wise.plugin.wasm is the program in the browser that executes this job
proof-plugin is responsible for invoking this program inside the current order and then passing the result forward into the later verifier and proving flow

Once these two concepts are in place, the code below will not feel abrupt.

In apps/proof-plugin/background.js, the core capture logic is this section:

const bridgeCandidates = [window.tlsn, window.__tlsn, window.tlsnExtension];
const tlsnBridge = bridgeCandidates.find(
  (candidate) => candidate && typeof candidate.connect === "function"
);
if (!tlsnBridge) {
  throw new Error("TLSNotary runtime missing");
}

const provider = await tlsnBridge.connect();
if (!provider || typeof provider.runPlugin !== "function") {
  throw new Error("tlsn provider missing runPlugin");
}
tlsn.attestation = await provider.runPlugin(tlsnPluginUrl, {});
tlsn.ok = true;

Code location: apps/proof-plugin/background.js

The tlsnPluginUrl here points to wise_plugin.tlsn.wasm. This wasm comes from the cooperation of two directories:

apps/tlsn-wise-plugin: produces the Wise-specific TLSN plugin artifact
apps/tlsn-wasm-host: exposes this wasm as a URL that the browser can access

This layer then proceeds in the following four steps:

apps/tlsn-wise-plugin produces wise.plugin.wasm
apps/tlsn-wasm-host hosts it
The plugin executes it on the Wise page through runPlugin()
The browser gets the attestation

After capture ends, the plugin pushes the result together with several recent payments into the proof session:

return {
  amountText,
  recipientText,
  transferTimeText,
  pageTitle: document.title,
  pageUrl: location.href,
  recentTransfers,
  tlsn,
  capturedAt: new Date().toISOString()
};

Code location: apps/proof-plugin/background.js

After capture ends, the plugin holds two kinds of things:

tlsn.attestation
recentTransfers

The first is used by the verifier later, and the second is used in the popup so the user can select the payment corresponding to the current order.

7. `tlsn-verifier`: verify the attestation first, then compress it into `wiseReceiptHash`

The next step enters apps/tlsn-verifier.

This service first performs local TLSN verification. The core code is in src/lib.js:

const presentationHex = extractPresentationHex(attestation);
if (!presentationHex) {
  throw new Error("unable to extract presentation hex from attestation payload");
}

const rawResult = await Promise.resolve(verifyPresentation(presentationHex, notaryPublicKeyPem));
const sent = typeof rawResult?.sent === "string" ? rawResult.sent : "";
const recv = typeof rawResult?.recv === "string" ? rawResult.recv : "";
const serverName = pickString(asRecord(rawResult), ["server_name", "serverName", "sourceHost", "host"]);

Code location: apps/tlsn-verifier/src/lib.js

After local verification completes, the service has already obtained:

presentationHex
sent / recv from the TLS session
The connected server host
The session timestamp

Then in src/server.js, the service matches the transfer selected by the user against recent transfers and then normalizes the fields.

localVerification = await verifyPresentationLocally({
  attestation: payload.attestation,
  notaryPublicKeyPem,
  verifyPresentation
});

const recentTransfers = extractRecentTransfers(attestationRaw, localVerification.recv, recentCount);
const selectedTransfer = findMatchingRecentTransfer(recentTransfers, payload.selectedTransfer);

const normalized = normalizedCheck.normalized;
const wiseReceiptHash =
  typeof raw.wiseReceiptHash === "string" && raw.wiseReceiptHash.startsWith("0x")
    ? raw.wiseReceiptHash
    : buildWiseReceiptHash(normalized, payload.attestation);

Code location: apps/tlsn-verifier/src/server.js

What the service returns to the frontend is a group of stable fields:

amount
timestamp
payerRef
transferId
sourceHost
wiseReceiptHash

wiseReceiptHash then continues into the later circuit inputs, Web API anti-replay checks, and proof submit.

8. `apps/web API`: what these four API routes each do

This apps/web layer corresponds to four API routes.

`/api/verify-wise-attestation`

This route forwards the attestation from the browser to the verifier, and then aligns it once more with the order context.

if (
  payload.expected?.amount &&
  isUnsignedIntegerText(payload.expected.amount) &&
  isUnsignedIntegerText(normalized.amount as string) &&
  payload.expected.amount !== normalized.amount
) {
  return res.status(400).json({
    error: "amount mismatch with expected order amount"
  });
}

if (normalizedTransferId !== expectedTransferId) {
  return res.status(400).json({
    error: "transferId mismatch with selected payment"
  });
}

const attestationDigest = sha256Hex(JSON.stringify(payload.attestation));
const wiseReceiptHash = sha256Hex(
  [
    "wise",
    normalized.sourceHost,
    normalizedTransferId,
    normalized.payerRef,
    normalized.amount,
    String(Math.trunc(normalized.timestamp as number)),
    attestationDigest
  ].join("|")
);

Code location: apps/web/pages/api/verify-wise-attestation.ts

This puts three things together and checks them:

The amount in the current order
The transferId selected by the current user
The normalized payment fields returned by the verifier

After the check passes, it returns wiseReceiptHash to the plugin.

`/api/submit-proof`

After the plugin generates the proof locally, it sends the proof and public inputs to this route.

This route first performs one anti-replay layer:

const nullifierReserved = reserveNullifier(payload.nullifier);
if (!nullifierReserved) {
  return res.status(409).json({ error: "anti-replay violation: nullifier already seen" });
}

const wiseReceiptReserved = reserveWiseReceiptHash(payload.wiseReceiptHash);
if (!wiseReceiptReserved) {
  releaseNullifier(payload.nullifier);
  return res.status(409).json({ error: "anti-replay violation: wise receipt hash already seen" });
}

Code location: apps/web/pages/api/submit-proof.ts

The in-memory store used here is in proof-store.ts:

const nullifierSet = new Set<string>();
const wiseReceiptHashSet = new Set<string>();
const statusByProofId = new Map<string, ProofStatusResponse>();
const tupleByProofId = new Map<string, ProofAggregationTuple>();

Code location: apps/web/src/zk/zkp2p-horizen-release/store/proof-store.ts

Then this route converts the payload into a body that Kurier accepts and tries several compatible endpoints:

for (const body of buildKurierSubmitBodies(payload, env)) {
  for (const target of buildSubmitTargets(env)) {
    upstream = await postSubmitCandidate(target, env.apiKey, body);
    if (upstream.ok) break;
  }
  if (upstream?.ok) break;
}

Code location: apps/web/pages/api/submit-proof.ts

`/api/proof-status`

After the proof enters Kurier, this route maps the upstream job status into the few statuses needed by the page:

export function mapProofStatus(rawStatus: string): "pending" | "verified" | "aggregated" | "failed" {
  const s = rawStatus.toLowerCase();
  if (s.includes("fail") || s.includes("error") || s.includes("reject") || s.includes("invalid")) {
    return "failed";
  }
  if (s.includes("aggregated") || s.includes("aggregationpublished") || s.includes("published")) {
    return "aggregated";
  }
  if (
    s.includes("verified") ||
    s.includes("included") ||
    s.includes("finalized") ||
    s.includes("aggregation pending") ||
    s.includes("aggregationpending")
  ) {
    return "verified";
  }
  return "pending";
}

Code location: apps/web/src/zk/zkp2p-horizen-release/api/kurier.ts

`/api/proof-aggregation`

After the proof enters the aggregation stage, this route extracts the tuple that will be consumed on-chain from the job status:

function tupleFromJobStatusRaw(
  raw: Record<string, unknown>,
  proofId: string,
  aggregationDomainId: string,
  intentHash?: string,
  nullifier?: string
): ProofAggregationTuple | null {
  const details = raw.aggregationDetails;
  const row = details as Record<string, unknown>;

  const aggregationId = String(raw.aggregationId ?? row.aggregationId ?? "").trim();
  const leaf = String(row.leaf ?? raw.statement ?? "").trim();
  const leafCount = String(row.numberOfLeaves ?? row.leafCount ?? "").trim();
  const index = String(row.leafIndex ?? row.index ?? "").trim();
  const merklePath = Array.isArray(row.merkleProof)
    ? row.merkleProof.map((x) => String(x))
    : Array.isArray(row.merklePath)
      ? row.merklePath.map((x) => String(x))
      : [];

Code location: apps/web/pages/api/proof-aggregation.ts

What the browser is waiting for at this stage is exactly this tuple.

9. The `Noir` circuit: the browser loads the artifact and generates the proof locally with `UltraHonk`

The core code for local proving is in browser-prover.ts.

async function installBrowserProver() {
  await initNoirWasmRuntime();
  const circuit = await fetchCircuitArtifact();

  const noir = new Noir(circuit as never);
  const backend = new UltraHonkBackend(circuit.bytecode);
  const ultraHonkOptions = { keccak: true as const };

  window.__ZKP2P_NOIR_PROVER__ = {
    async prove(payload: WitnessPayload): Promise<ProofResult> {
      const { witness } = await noir.execute(payload.circuitInputs);
      const generated = await backend.generateProof(witness, ultraHonkOptions);
      const locallyVerified = await backend.verifyProof(generated, ultraHonkOptions);
      if (!locallyVerified) {
        throw new Error("Local UltraHonk verification failed (oracle hash / VK mismatch)");
      }

      return {
        proof: toHex(generated.proof),
        publicInputs: Array.isArray(generated.publicInputs)
          ? generated.publicInputs.map(normalizePublicInputToHex)
          : []
      };
    }
  };
}

Code location: apps/web/src/zk/zkp2p-horizen-release/browser-prover.ts

The actual runtime assets used here are:

Circuit source file: circuits/zkp2p-horizen-release/noir/src/main.nr
Artifact loaded by the frontend: /api/circuit-artifact?name=zkp2p_horizen_release
Proving backend: UltraHonkBackend
Verification key: circuits/zkp2p-horizen-release/noir/target/vk

This runtime model is different from the usual circom wasm + zkey frontend mental model. What the page gets here is a Noir artifact JSON; what is initialized locally is Noir + ACVM + bb.js; and what comes out in the end is proof + publicInputs.

When the plugin actually triggers proving, it is calling exactly this browser runtime:

if (!session.wiseReceiptHash) throw new Error("wise receipt hash missing, run capture first");

await patchSession(proofId, { status: SESSION_STATUS.PROVING });
const proving = await runBrowserProving({ session, capture: session.capture });

const patched = await patchSession(proofId, {
  proof: proving.proof,
  publicInputs: proving.publicInputs,
  status: SESSION_STATUS.PROOF_READY
});

Code location: apps/proof-plugin/background.js

At this point, the proof has been fully generated inside the browser.

10. What exactly the circuit binds: `statement`, `nullifier`, `wiseReceiptHash`

Next, unfold the circuit itself.

First, unfold the inputs and constraints of main():

fn main(
    business_domain: pub Field,
    app_id: pub Field,
    user_addr: pub Field,
    chain_id: pub Field,
    timestamp: pub Field,
    intent_id: pub Field,
    amount: pub Field,
    wise_receipt_hash: pub Field,
    nullifier: pub Field,
    statement: pub Field,
    secret: Field,
    wise_witness_hash: Field,
) {
    let expected_statement = compute_statement(
        business_domain,
        app_id,
        user_addr,
        chain_id,
        timestamp,
        intent_id,
        amount,
    );
    assert(statement == expected_statement);

    let expected_nullifier = compute_nullifier(secret, intent_id);
    assert(nullifier == expected_nullifier);

    let expected_wise_witness_hash =
        compute_wise_witness_hash(amount, timestamp, user_addr, wise_receipt_hash, secret);
    assert(wise_witness_hash == expected_wise_witness_hash);
}

Code location: circuits/zkp2p-horizen-release/noir/src/main.nr

This code makes the relationship in the current circuit very clear:

The public inputs carry the order context
The private inputs carry secret
statement must be recomputable from the order context
nullifier must be recomputable from secret + intent_id
wise_witness_hash must be recomputable from the payment fields and secret

First look at statement. The TS side and the circuit keep the same order.

export function buildStatementField(input: StatementInput): bigint {
  const businessDomain = stringToField(input.businessDomain);
  const appId = stringToField(input.appId);
  const userAddr = hexToField(input.buyerAddress);
  const intentId = hexToField(input.intentId);
  const amount = mod(input.amount);
  const chainId = mod(input.chainId);
  const timestamp = mod(input.timestamp);

  let acc = mimc7Hash2(intentId, userAddr);
  acc = mimc7Hash2(acc, amount);
  acc = mimc7Hash2(acc, chainId);
  acc = mimc7Hash2(acc, timestamp);
  acc = mimc7Hash2(acc, businessDomain);
  return mimc7Hash2(acc, appId);
}

Code location: apps/web/src/zk/zkp2p-horizen-release/statement.ts

Once this order is fixed, statement folds the following into one value:

intentId
buyerAddress
amount
chainId
timestamp
businessDomain
appId

Next, look at how the plugin assembles the witness. deriveCircuitInputs() arranges the fields in the session into circuit inputs, and it also preserves one current implementation detail here:

const intentIdHex = normalizeHex32(session.intentId, "intentId");
const intentHashHex = normalizeHex32(session.intentHash || session.intentId, "intentHash");

if (intentHashHex !== intentIdHex) {
  throw new Error(
    `intentHash mismatch: intentHash=${intentHashHex} intentId=${intentIdHex}. ` +
      "Current circuit binds intentHash to intentId."
  );
}

Code location: apps/proof-plugin/lib/circuit-inputs.js

This shows that in the current version, the actual binding of intentHash is still equal to intentId. The page, the plugin, and the contract all keep using this assumption.

Finally, look at wiseWitnessHash. The plugin folds the payment fields together with wiseReceiptHash one more time and then places the result into the private inputs:

const wiseWitnessHashField = computeWiseWitnessHash({
  amountField,
  timestampField,
  userAddrField,
  wiseReceiptHashField,
  secretField
});

const privateInputsByName = {
  secret: secretField.toString(),
  wise_witness_hash: wiseWitnessHashField.toString()
};

Code location: apps/proof-plugin/lib/circuit-inputs.js

By the end of this circuit section, the order context, the payment digest, and the one-time consumption right have all been placed into the same witness relation.

11. After the proof leaves the browser, how the frontend waits for results from Kurier and zkVerify

After the browser gets proof + publicInputs, the plugin immediately submits them to /api/submit-proof.

const body = {
  proofId: session.proofId,
  verificationMode: session.verificationMode,
  proofSystem: session.proofSystem,
  proof: session.proof,
  publicInputs: session.publicInputs,
  appId: session.appId,
  businessDomain: session.businessDomain,
  aggregationDomainId: session.aggregationDomainId,
  userAddr: session.buyerAddress,
  chainId: session.chainId,
  timestamp: session.timestamp,
  intentId: session.intentId,
  intentHash: session.intentHash || session.intentId,
  amount: session.amount,
  wiseReceiptHash: session.wiseReceiptHash,
  nullifier: session.nullifier
};

const submit = await postJson(session.submitEndpoint, body);

Code location: apps/proof-plugin/background.js

This section deserves to be discussed in more detail, because from this point on, the proof has already left the browser, and the later flow enters the full Kurier -> zkVerify -> aggregation tuple path.

First, separate these two roles:

Kurier is the relay and status outlet. It processes the proof payload forwarded by your backend, returns providerJobId, exposes job status and the aggregation tuple, and synchronizes zkVerify’s results into the target-chain verification path.
zkVerify is the verification and aggregation network. After the proof enters this layer, it goes through verification and aggregation, eventually corresponding to an aggregation result that the target-chain gateway can verify.

Two things should be remembered here first:

What the frontend polls later is actually the upstream job corresponding to providerJobId
Even though the page reads the tuple back from the Kurier API, the place that actually executes verifyProofAggregation(...) and releaseWithProof() is the Horizen target chain

/api/submit-proof first performs one round of business-field validation, and then submits this proof upward together with the current order context.

if (payload.appId !== env.appId) {
  return res.status(400).json({ error: "appId mismatch with server env" });
}

if (payload.aggregationDomainId !== env.aggregationDomainId) {
  return res.status(400).json({ error: "aggregationDomainId mismatch with server env" });
}

const nullifierReserved = reserveNullifier(payload.nullifier);
if (!nullifierReserved) {
  return res.status(409).json({ error: "anti-replay violation: nullifier already seen" });
}

const wiseReceiptReserved = reserveWiseReceiptHash(payload.wiseReceiptHash);
if (!wiseReceiptReserved) {
  releaseNullifier(payload.nullifier);
  return res.status(409).json({ error: "anti-replay violation: wise receipt hash already seen" });
}

Code location: apps/web/pages/api/submit-proof.ts

This step makes two layers of constraints explicit:

The appId and aggregationDomainId inside the proof must match the current backend environment
The same nullifier and wiseReceiptHash cannot be submitted twice

After the validation passes, the backend packages the proof into a body accepted by Kurier. It explicitly carries vk, proof, and publicSignals, while also preserving the order-related fields:

const modern = {
  proofType: payload.proofSystem,
  proofOptions,
  vkRegistered: true,
  proofData: {
    vk: env.vkHash,
    proof: normalizedProof,
    publicSignals: normalizedPublicSignals
  },
  mode: payload.verificationMode,
  appId: payload.appId,
  businessDomain: payload.businessDomain,
  aggregationDomainId: payload.aggregationDomainId,
  userAddr: payload.userAddr,
  chainId: payload.chainId,
  timestamp: payload.timestamp,
  intentId: payload.intentId,
  intentHash: payload.intentHash,
  amount: payload.amount,
  nullifier: payload.nullifier
};

Code location: apps/web/pages/api/submit-proof.ts

The meaning here is very clear: what gets submitted to Kurier is a proof payload that has already been bound to the current order. The proof system, vk, public signals, intent context, and nullifier all enter upstream together at this layer.

After the backend submits successfully, it pulls providerJobId out of the upstream response and binds the local proofId to that upstream job.

const providerJobId = extractProviderJobId(raw);
if (!providerJobId) {
  releaseNullifier(payload.nullifier);
  releaseWiseReceiptHash(payload.wiseReceiptHash);
  return res.status(502).json({
    error: "kurier submit response missing jobId"
  });
}

const status: ProofStatusResponse = {
  proofId: payload.proofId,
  status: failed ? "failed" : "pending",
  rawStatus,
  updatedAt: new Date().toISOString(),
  source: "kurier-keyed",
  availableKeys: Object.keys(raw),
  providerJobId,
  intentHash: payload.intentHash,
  nullifier: payload.nullifier
};

Code location: apps/web/pages/api/submit-proof.ts

After this step, the page holds two sets of IDs:

The local proofId of this proof session
The upstream Kurier / zkVerify job providerJobId

It is the second one that is actually used later to query status.

After successful submission, the plugin saves submitResponse and starts polling status:

const statusUrl = new URL(session.statusEndpoint);
statusUrl.searchParams.set("proofId", String(proofId));
if (typeof providerJobId === "string" && providerJobId.trim()) {
  statusUrl.searchParams.set("providerJobId", providerJobId.trim());
}

const statusResp = await getJson(statusUrl.toString());

Code location: apps/proof-plugin/background.js

/api/proof-status first uses providerJobId to query Kurier job status, and then maps the upstream status into a few more stable statuses for the page:

export function mapProofStatus(rawStatus: string): "pending" | "verified" | "aggregated" | "failed" {
  const s = rawStatus.toLowerCase();
  if (s.includes("fail") || s.includes("error") || s.includes("reject") || s.includes("invalid")) {
    return "failed";
  }
  if (s.includes("aggregated") || s.includes("aggregationpublished") || s.includes("published")) {
    return "aggregated";
  }
  if (
    s.includes("verified") ||
    s.includes("included") ||
    s.includes("finalized") ||
    s.includes("aggregation pending") ||
    s.includes("aggregationpending")
  ) {
    return "verified";
  }
  return "pending";
}

Code location: apps/web/src/zk/zkp2p-horizen-release/api/kurier.ts

The status here can be understood as having two layers:

rawStatus preserves the raw upstream wording from Kurier / zkVerify, which is useful for debugging
pending / verified / aggregated / failed is the page’s own stable state machine

The page itself also polls along with it:

const resp = await plugin.queryStatus(activeProofId).catch(() => null);
const rawStatus =
  statusPayload.statusResponse?.rawStatus ??
  statusPayload.statusResponse?.status ??
  statusPayload.status ??
  "pending";
applyProofStatus(activeProofId, rawStatus);

Code location: apps/web/pages/zkp2p-horizen-release.tsx

After the status reaches aggregated, the plugin then fetches the aggregation tuple:

const tupleUrl = new URL(session.aggregationEndpoint);
tupleUrl.searchParams.set("proofId", String(proofId));
if (typeof providerJobId === "string" && providerJobId.trim()) {
  tupleUrl.searchParams.set("providerJobId", providerJobId.trim());
}

const tupleResp = await getJson(tupleUrl.toString());
await patchSession(proofId, { tuple: tupleResp.json });

Code location: apps/proof-plugin/background.js

/api/proof-aggregation extracts the aggregation result produced by zkVerify from the job status:

function tupleFromJobStatusRaw(
  raw: Record<string, unknown>,
  proofId: string,
  aggregationDomainId: string,
  intentHash?: string,
  nullifier?: string
): ProofAggregationTuple | null {
  const details = raw.aggregationDetails;
  if (!details || typeof details !== "object") return null;
  const row = details as Record<string, unknown>;

  const aggregationId = String(raw.aggregationId ?? row.aggregationId ?? "").trim();
  const leaf = String(row.leaf ?? raw.statement ?? "").trim();
  const leafCount = String(row.numberOfLeaves ?? row.leafCount ?? "").trim();
  const index = String(row.leafIndex ?? row.index ?? "").trim();
  const merklePath = Array.isArray(row.merkleProof)
    ? row.merkleProof.map((x) => String(x))
    : Array.isArray(row.merklePath)
      ? row.merklePath.map((x) => String(x))
      : [];

Code location: apps/web/pages/api/proof-aggregation.ts

This layer is where zkVerify’s aggregation result is finally organized into the format consumed by the target chain. All the statuses, logs, and job information returned earlier by Kurier and zkVerify are eventually reduced to this set of fields:

aggregationDomainId
aggregationId
leaf
merklePath
leafCount
index

These are the inputs that the target-chain gateway verifyProofAggregation(...) can actually understand.

What the page really uses later from the tuple is:

aggregationDomainId
aggregationId
leaf
merklePath
leafCount
index

For Chapter 11, the relationship to remember first is this:

The browser is responsible for generating the proof locally
The Web API is responsible for binding the proof to the business fields and then submitting it to Kurier
Kurier sends this proof into zkVerify’s verification / aggregation flow, and exposes job status / tuple to the frontend
After the frontend gets the tuple, the actual verification happens on the gateway / deposit pool of the Horizen target chain
What the page is waiting for in the end is this tuple, not a piece of status text

Only after this proof relay section is complete does the page truly have the parameters needed to call releaseWithProof() on-chain.

12. How the final `releaseWithProof()` happens

Finally, go back to the page and the contract.

Before the buyer signs, the page has already arranged the tuple and the intent-related fields. The place where the transaction is actually sent is in apps/web/pages/zkp2p-horizen-release.tsx:

appendPluginLog("releaseWithProof 提交中...");
const tx = await contract.releaseWithProof(
  intentId,
  nullifier,
  proofIntentHash,
  domainId,
  aggregationId,
  leaf,
  merklePath,
  leafCount,
  index
);
appendPluginLog(`release tx: ${tx.hash}`);
const receipt = await tx.wait();

Code location: apps/web/pages/zkp2p-horizen-release.tsx

After the contract receives this set of parameters, it checks them in order:

Intent storage intent = intents[intentId];
if (!intent.reserved) revert IntentNotReserved();
if (intent.released) revert IntentAlreadyReleased();
if (intent.cancelled) revert IntentAlreadyCancelled();
if (block.timestamp > intent.deadline) revert IntentExpired();
if (msg.sender != intent.buyer) revert OnlyIntentBuyer();
if (nullifierUsed[nullifierHash]) revert NullifierAlreadyUsed();
if (intent.nullifierHash != nullifierHash) revert NullifierMismatch();
if (intent.intentHash != proofIntentHash) revert IntentHashMismatch();

bool verified = gateway.verifyProofAggregation(domainId, aggregationId, leaf, merklePath, leafCount, index);
if (!verified) revert VerificationFailed();

nullifierUsed[nullifierHash] = true;
intent.reserved = false;
intent.released = true;

bool transferred = token.transfer(intent.buyer, intent.amount);
if (!transferred) revert TransferFailed();

Code location: contracts/src/Zkp2pDepositPool.sol

After the transaction is confirmed, both the on-chain state and the funds land at the same time:

nullifierHash is marked as used
The current intent changes from reserved to released
The seller’s locked amount is reduced
The USDC corresponding to intent.amount is transferred to the buyer

At this point, the entire path is closed.

Each earlier layer does one thing of its own:

The contract locks the seller’s liquidity out first
The page prepares the order context
The plugin obtains the attestation from the Wise page
tlsn-verifier verifies the attestation and compresses it into wiseReceiptHash
The browser locally generates the proof with Noir + UltraHonk
The Web API sends the proof into Kurier and zkVerify
After the page gets the aggregation tuple, the buyer initiates releaseWithProof() themselves

That way, this full P2P fiat-to-USDC on-ramp path lands end to end. The seller locks liquidity first, the buyer then completes the Wise payment, the browser pushes the payment evidence into proving, Kurier synchronizes zkVerify’s aggregation result outward, and after the frontend gets the tuple, validation and release are finally completed by releaseWithProof() on the Horizen target chain.

How to Create a Zero Knowledge DApp: From Zero to Production, Case 1: zk Escrow

Jet Halo — Tue, 21 Apr 2026 12:54:18 +0000

This article is about understanding an end-to-end zk application from a full-stack, end-to-end perspective.

It uses the ZK Escrow Release repository as the concrete example, and walks through one escrow flow from the business problem, to the contract, the circuit, the frontend, the verification layer, and finally on-chain consumption.

The goal here is not to walk through the code line by line, and it is not to repeat the install, run, and deployment commands. Those are better kept in step-by-step docs. This article is focused on a different question: if you want to build a complete zk app yourself, what should you think about first, what should you build next, what is each layer responsible for, and where exactly zkVerify fits in the whole path.

This article will cover:

where this escrow project is similar to Tornado Cash, and where it is not
what parts usually make up a complete zk app
what the contract, circuit, frontend, backend, and verification layer each do
how to think about zkVerify once it is part of the system

If, by the end, the reader can explain from a full-system perspective which parts a zk app needs, why those parts exist, how they connect to each other, and why zkVerify appears at the verification layer, then this article has done its job.

You can treat it as a development map, not as an operations manual.

Suggested reading approach
It is best to first follow the zkVerify installation guide and get the project running locally, then read this article alongside the code. The installation steps are here: Tutorial 01: Operations Only. The code repository used in this tutorial is here: ZK Escrow Release. That way, when you reach each section, you can jump straight to the matching module in the repo and compare the contract, circuit, frontend, and API together. It makes the whole end-to-end flow much easier to understand.

Understanding What Tornado Cash Is

Tornado Cash had a huge influence on ZK. Even today, many people first think of the controversy around it, but for developers, what it really left behind is a way of thinking:

you do not have to hand the secret directly to the chain in order for the chain to accept a valid spend.

That is why it is still hard to talk about how a zk app is built without talking about Tornado Cash first. Not because this article is trying to retell Tornado Cash itself, but because many later ZK applications, especially projects that use structures like commitment, nullifier, and a Merkle tree, are easiest to understand when you start from there.

Of course, Tornado Cash is not only those pieces. It is a complete protocol with its own deposit pools, withdrawal flow, verifier, relayer, and frontend interaction. Here, the point is to focus on its core cryptographic skeleton, because the escrow project in this repo borrows that skeleton while changing the business goal.

What Tornado Cash Actually Does

Start with Tornado Cash.

If you compress its core idea into one sentence, it looks like this:

a user deposits assets into a pool and gets a note that only they know. Later, when withdrawing, the user does not reveal the original deposit directly to the chain. Instead, they use that note to generate a proof and show the contract that they really do have the right to withdraw from the pool.

The key point is that the funds can finally be withdrawn to a new address. The contract knows the withdrawal is valid, but it does not know which original deposit inside the pool it came from. What Tornado Cash is really doing is cutting that link.

To do that, Tornado Cash naturally grows a structure like this:

generate a note at deposit time
derive a commitment from that note
place all commitments into a Merkle tree
at withdrawal time, use a proof to show “I know the secret behind one commitment, and that commitment belongs to this tree”
use a nullifier or nullifier hash to prevent the same credential from being spent twice

At that point, Tornado Cash already gives enough of a reference model for the rest of this article.

Now look at this project.

This project borrows the same cryptographic skeleton, but it is not doing anonymous withdrawals.

The flow here is more direct:

user A deposits funds into the contract
at deposit time, the recipient address B is written on-chain
the frontend first generates a credential locally and computes the corresponding commitment
later, whoever holds that credential and successfully proves it can trigger release
but the funds can only go to the originally bound B

That is the most fundamental difference from Tornado Cash.

In Tornado Cash, the withdrawal address can be a fresh new address.

This project does not work like that. Here, the recipient is already locked in when the deposit happens. The later proof is not deciding who gets paid. It is proving that the funds can now be released to the address that was bound from the beginning.

So even though both systems contain commitment, nullifier, a Merkle tree, and a proof, those pieces are serving different goals.

Reconstructing the Product Flow from the User's Point of View

Do not rush into the circuit yet, and do not rush into zkVerify yet either.

First, walk through one concrete transfer inside this project. After that, it becomes much easier to come back and break down what each layer is doing.

Suppose we have this escrow:

user A deposits 0.1 ETH into the contract
at deposit time, the recipient address B is written on-chain together with it

After this step, the chain remembers two kinds of things.

The first kind is the escrow's own data, such as the amount, the recipient, and whether the funds have already been spent.

The second kind is data related to the proof, namely the commitment derived from the credential. That commitment is inserted into the on-chain Merkle tree and becomes one of the members that later proofs will refer to.

Before the deposit transaction is sent, the frontend first generates a credential locally and computes the corresponding commitment. When the transaction goes on-chain, what actually enters the contract is the commitment and the recipient address B. The contract does not keep the credential for the user, and it does not write the raw secret on-chain. Later, if anyone wants to trigger release, they must first have that local credential.

At release time, the browser uses that credential to do several things:

compute the commitment that belongs to this credential
find its position in the Merkle tree locally
generate a zk proof

At that point, the proof is not sent straight into the contract yet.

In this project, the proof first goes to the server API, then to Kurier, and then into zkVerify's verification path. Only after zkVerify returns a result that the chain can consume does the frontend continue.

At the end of the flow, the frontend calls the contract's finalize() with the aggregation result returned by zkVerify together with the publicInputs for this proof.

When the contract receives those parameters, it does not release the funds immediately. It first checks:

whether this commitment has a matching deposit in the contract
whether this credential has already been used
whether the statement behind the current proof is correct
whether zkVerify's aggregation result can pass on-chain verification

Only after all of those checks pass does the contract send the original 0.1 ETH to the B that was bound at deposit time, rather than to the person currently calling finalize().

So, at a rough level, the full path can be remembered like this:

A deposits 0.1 ETH -> B is locked in -> the frontend generates a local credential -> the browser produces a local proof -> the proof enters zkVerify's verification path -> the contract calls finalize -> 0.1 ETH is sent to B

What `commitment` Is

If you send the raw credential to the chain, the secret is gone. So the chain does not store nullifier and secret directly. It only stores the result derived from them, and that result is the commitment.

One good way to think about commitment is this:

you put the raw credential into a sealed envelope. Other people cannot see what is inside, but they can see the unique mark on the outside. Later, that mark is what the system recognizes.

When we say “you cannot reverse it back to the original content,” that does not mean it is mathematically impossible in an absolute sense. It means:

if all you can see is the commitment, it is very hard to recover the original nullifier and secret. That is exactly the job of the hash function here. It is easy to go from input to output, and hard to go from output back to input.

This project uses Pedersen hash. For now, you can think of it as a hash function designed to be friendly to ZK circuits. That is why it is common in zk projects and fits naturally into Circom-style constraints.

In the frontend, the source of pedersen is straightforward. It is loaded from circomlibjs:

const circomlib = await import('circomlibjs');
pedersenCache = await circomlib.buildPedersenHash();

Code location: apps/web/src/zk/escrow/prover.ts in loadPedersen()

In this project, the frontend first generates nullifier and secret locally, then combines them and computes the commitment:

const commitmentBytes = new Uint8Array(62);
commitmentBytes.set(nullifierBytes, 0);
commitmentBytes.set(secretBytes, 31);

const commitmentPoint = pedersen.hash(commitmentBytes);
const commitmentUnpacked = babyJub.unpackPoint(commitmentPoint);
const commitment = babyJub.F.toObject(commitmentUnpacked[0]);

Code location: apps/web/src/zk/escrow/prover.ts in computeCommitment()

Once it is computed, what actually gets written into the contract is not the raw credential, but that commitment:

function deposit(bytes32 commitment, address recipient) external payable {
    deposits[commitment] = DepositRecord({
        recipient: recipient,
        amount: msg.value,
        spent: false
    });

    uint32 leafIndex = _insert(commitment);
}

Code location: contracts/src/ZKEscrowRelease.sol in deposit()

So the role of commitment is very direct: the frontend keeps the real secret, while the chain stores only a verifiable result that is hard to reverse.

Looking at `nullifierHash`

commitment alone is not enough.

Because once someone gets the credential, they could in theory keep using it to trigger release again and again. The system still needs a way to know whether that credential has already been used.

That is what nullifierHash is for.

You can think of it as a one-time redemption code.

The most important point is this: the same credential always produces the same nullifierHash. That is because it is derived only from nullifier, and nullifier is a fixed part of the credential.

So the whole thing works a lot like a one-time ticket:

the first time, the system sees a redemption code it has never seen before, so it allows it
after allowing it, the system records that code
the second time, the same ticket produces the same code again
the system checks its record, sees that the code was already used, and rejects it

This means the system can detect “this is the same spend again, not a new valid spend” without exposing the raw credential itself.

In the frontend, nullifierHash is not computed from nullifier + secret. It is computed from nullifier alone:

const nullifierPoint = pedersen.hash(nullifierBytes);
const nullifierUnpacked = babyJub.unpackPoint(nullifierPoint);
const nullifierHash = babyJub.F.toObject(nullifierUnpacked[0]);

Code location: apps/web/src/zk/escrow/prover.ts in computeCommitment()

In the contract, finalize() reads publicInputs[1] as nullifierHash, then checks whether it has already been used:

bytes32 nullifierHash = bytes32(publicInputs[1]);
require(!nullifierUsed[nullifierHash], "nullifier used");

nullifierUsed[nullifierHash] = true;
dep.spent = true;

Code location: contracts/src/ZKEscrowRelease.sol in finalize()

The circuit also hard-binds this relationship: the private nullifier that you submit must really derive the public nullifierHash. That means you cannot swap in a fresh nullifierHash and pretend it is a first-time use.

hasher.nullifierHash === nullifierHash;
hasher.commitment === commitment;

Code location: circuits/escrow/circom/escrowRelease.circom

So nullifierHash is not solving generic “deduplication.” It solves a very specific problem:

when the same credential comes back a second time, it exposes the same one-time redemption code, so the contract can stop it.

Finally, the Merkle Tree

commitment solves “you cannot store the raw secret on-chain,” and nullifierHash solves “the same credential cannot be used twice,” but one more piece is still missing:

how does the system know that the commitment you are presenting really belongs to the set of valid on-chain deposits, rather than being something you just invented locally?

That is what the Merkle tree is doing.

You can think of it as a very long membership list. You do not have to bring the entire list with you. You only need to provide one path from “my item” up to the final summary, and the system can check whether you really are a member.

In this project, every time the contract receives a new deposit, it inserts the corresponding commitment into the tree:

uint32 leafIndex = _insert(commitment);
emit MerkleRootUpdated(getLastRoot(), leafIndex);

Code location: contracts/src/ZKEscrowRelease.sol in deposit()

The tree maintenance logic itself lives in MerkleTreeWithHistory.sol. After a new leaf is inserted, the root is recomputed upward. Later, finalize() uses isKnownRoot() to check whether the root provided by the proof is a root the contract has seen before.

function _insert(bytes32 _leaf) internal returns (uint32 index) { ... }

function isKnownRoot(bytes32 _root) public view returns (bool) { ... }

Code location: contracts/src/MerkleTreeWithHistory.sol

Before generating a proof locally, the frontend also computes the path for this leaf from the current commitment list:

const { root, pathElements, pathIndices } = await buildMerkleProof(
  leaves,
  leafIndex,
);

Code location: apps/web/src/zk/escrow/prover.ts in buildMerkleProof()

Inside the circuit, the actual membership check looks like this:

tree.leaf <== hasher.commitment;
tree.root <== merkleRoot;
tree.pathElements[i] <== merklePath[i];
tree.pathIndices[i] <== merkleIndex[i];

Code location: circuits/escrow/circom/escrowRelease.circom

If you translate those lines directly into plain English:

tree.leaf <== hasher.commitment; tells the circuit that the leaf being checked is the commitment derived from this credential
tree.root <== merkleRoot; tells the circuit that the target root is the public merkleRoot
tree.pathElements[i] <== merklePath[i]; gives the circuit the sibling node for each level
tree.pathIndices[i] <== merkleIndex[i]; tells the circuit whether the current node is on the left or on the right at each level

Taken together, what the circuit is really doing is:

starting from the commitment leaf, recompute upward level by level following merklePath and merkleIndex. If the final result really equals the public merkleRoot, then this commitment really belongs to the tree.

If the path is fake, or the leaf is not really in the tree, the recomputed root will not match, and the proof will fail.

So the Merkle tree solves: how do you prove that this credential really belongs to one of the system's deposits?

Put the three pieces together and their roles become clear:

commitment turns the raw credential into something the chain can store
nullifierHash makes sure the credential can only be used once
the Merkle tree proves that the credential really belongs to the set of valid on-chain deposits

What State the Contract Actually Stores On-Chain

As explained earlier, this project is not “if the proof passes, then decide who gets paid.” Instead, the contract first records an escrow on-chain at deposit time, and the later proof only authorizes release.

So this section focuses on one question: what exactly does the contract store on-chain?

The First Kind of State: the Data of Each Escrow

The most important part is the deposits mapping:

mapping(bytes32 => DepositRecord) public deposits;

struct DepositRecord {
    address recipient;
    uint256 amount;
    bool spent;
}

Code location: contracts/src/ZKEscrowRelease.sol

Its key is commitment, and its value is the record for that escrow.

Only three pieces of data are actually stored there:

recipient: who the funds are allowed to go to
amount: how much money is locked
spent: whether the escrow has already been released

That is why this article has kept repeating that the recipient is locked at deposit time. The chain really stores it. Later, finalize() does not decide the recipient again. It reads that existing record.

The Second Kind of State: Which Commitments Belong to Valid Deposits

Storing deposits alone is not enough.

Because the proof is not only proving “I know a credential.” It also needs to prove “the commitment behind this credential really belongs to one of the on-chain deposits.”

So inside deposit(), the contract does two things:

deposits[commitment] = DepositRecord({
    recipient: recipient,
    amount: msg.value,
    spent: false
});

uint32 leafIndex = _insert(commitment);
emit MerkleRootUpdated(getLastRoot(), leafIndex);

Code location: contracts/src/ZKEscrowRelease.sol in deposit()

The first half stores the escrow record. The second half inserts the commitment into the Merkle tree.

The tree does not keep only the latest root. It also keeps a short history of roots:

mapping(uint256 => bytes32) public roots;
uint32 public constant ROOT_HISTORY_SIZE = 30;
uint32 public currentRootIndex = 0;
uint32 public nextIndex = 0;

Code location: contracts/src/MerkleTreeWithHistory.sol

The reason is straightforward: when a user generates a proof locally, they may not happen to do it at the exact moment the latest root exists. As long as the proof's root still belongs to the contract's known root history, finalize() can accept it.

That is why finalize() starts with this check:

require(isKnownRoot(merkleRoot), "root not known");

Code location: contracts/src/ZKEscrowRelease.sol in finalize()

The Third Kind of State: Which Credentials Have Already Been Consumed

The same credential must not be used twice, so the contract also keeps a list of already-used credentials:

mapping(bytes32 => bool) public nullifierUsed;

Code location: contracts/src/ZKEscrowRelease.sol

Inside finalize(), the contract first checks whether this nullifierHash has already appeared:

require(!nullifierUsed[nullifierHash], "nullifier used");

nullifierUsed[nullifierHash] = true;
dep.spent = true;

Code location: contracts/src/ZKEscrowRelease.sol in finalize()

Two things are updated here at the same time:

nullifierUsed[nullifierHash] = true
dep.spent = true

The first prevents the same credential from being used again. The second marks the escrow itself as already released.

The Fourth Kind of State: Which Business Context This Proof Is Supposed to Belong To

This project does not only validate “whether the proof is formally valid.” It also validates “whether the proof belongs to this business flow.”

So the contract stores several expected configuration values:

IZKVerifyAggregation public zkVerify;
bytes32 public vkHash;
uint256 public expectedDomain;
uint256 public expectedAppId;
uint256 public expectedChainId;

Code location: contracts/src/ZKEscrowRelease.sol

These fields do different jobs:

zkVerify: which aggregation verification contract the chain should call
vkHash: which verification key this statement is tied to
expectedDomain / expectedAppId / expectedChainId: which business domain, application, and chain this proof is supposed to belong to

So before actually releasing the funds, finalize() also checks:

require(domain == expectedDomain, "domain mismatch");
require(appId == expectedAppId, "appId mismatch");
require(chainId == expectedChainId && chainId == block.chainid, "chainId mismatch");

Code location: contracts/src/ZKEscrowRelease.sol in finalize()

Putting Those Kinds of State Together

If you think of the contract as a state container, it is really doing four things:

using deposits to store the recipient, amount, and spent flag for each escrow
using the Merkle tree and root history to store which commitments belong to valid deposits
using nullifierUsed to store which credentials have already been consumed
using zkVerify / vkHash / expectedDomain / expectedAppId / expectedChainId to store what the verification path is supposed to look like

So later, finalize() is not “release funds if there is a proof.” It compares the current proof against these on-chain states, one by one, and decides whether this is really a release the contract is willing to accept.

What the Circuit Actually Proves, and How the Browser Computes the Proof

For many people, the moment they see the circuit, they immediately fall into details: which signals are public, which are private, which line does hashing, which line creates constraints.

But if the overall structure is not clear first, those details quickly turn into a pile of symbols that are hard to follow.

So start with the conclusion.

This circuit is not proving:

“I am the recipient B”
“I am the person who originally made the deposit”
“I can now choose any address to receive the funds”

What this circuit is really proving is this:

In plain language, the circuit is only proving two things:

you really do hold the original credential
the commitment derived from that credential really belongs to the on-chain Merkle tree

If those two facts hold, the system knows this is not a fake credential invented on the spot. It is a real credential tied to a real on-chain deposit.

In other words, the circuit is only deciding one thing: whether this release request is backed by a valid credential that corresponds to an on-chain deposit. Who the funds are finally sent to is not decided here. That was already written into the contract record earlier, during deposit.

That is also exactly what the comment in the circuit file says:

// Authorization‑only escrow release (no recipient in circuit)

Code location: circuits/escrow/circom/escrowRelease.circom

First Look at the Two Kinds of Inputs in This Circuit

Inside EscrowRelease(levels), the inputs are explicitly split into public and private.

The public inputs are:

signal input merkleRoot;
signal input nullifierHash;
signal input commitment;
signal input domain;
signal input appId;
signal input chainId;
signal input timestamp;

The private inputs are:

signal input nullifier;
signal input secret;
signal input merklePath[levels];
signal input merkleIndex[levels];

Code location: circuits/escrow/circom/escrowRelease.circom

In plain language:

public inputs are values the outside world can see and verify against
private inputs are values the prover knows but does not reveal

Applied to this project:

nullifier and secret are raw credential data, so they must be private
merklePath and merkleIndex are used for membership proof, so they are also private
commitment, nullifierHash, and merkleRoot are values the verifier must use, so they must be public
domain, appId, chainId, and timestamp are the business context for this proof, so they must also be public, otherwise the later statement and contract checks cannot bind the proof to the correct scenario

Part One of the Circuit: Recompute the Public Results from the Private Credential

The circuit does not start by checking the tree. It starts by recomputing:

can the private nullifier and secret in this witness really derive the public commitment and nullifierHash?

That logic lives in CommitmentHasher():

template CommitmentHasher() {
    signal input nullifier;
    signal input secret;
    signal output commitment;
    signal output nullifierHash;

    component commitmentHasher = Pedersen(496);
    component nullifierHasher = Pedersen(248);

Code location: circuits/escrow/circom/escrowRelease.circom

You can split that logic into two steps.

First, nullifier and secret are broken into bits.

Second, commitmentHasher computes commitment from nullifier + secret, while nullifierHasher computes nullifierHash from nullifier alone.

These two lines are the key constraints:

hasher.nullifierHash === nullifierHash;
hasher.commitment === commitment;

They do not mean “recompute it once and see what happens.” They mean:

the circuit forces the private witness and the public inputs to match.

If someone fills in a public commitment arbitrarily, but the nullifier and secret they hold cannot really derive it, this part fails.

If someone tries to change nullifierHash into a fresh, unused value to dodge replay protection, this part also fails, because it must really come from the same nullifier.

Part Two of the Circuit: Check That This Commitment Really Belongs to the Tree

The previous part proves only one thing: you know a raw credential that really derives the public commitment and nullifierHash.

But one more step is still missing.

The system still has to know that this commitment is not something you just invented locally, but something that really belongs to the set of valid on-chain deposits.

So the circuit next calls MerkleTreeChecker(levels):

component tree = MerkleTreeChecker(levels);
tree.leaf <== hasher.commitment;
tree.root <== merkleRoot;
for (var i = 0; i < levels; i++) {
    tree.pathElements[i] <== merklePath[i];
    tree.pathIndices[i] <== merkleIndex[i];
}

Code location: circuits/escrow/circom/escrowRelease.circom

The meaning is clear:

the leaf is the commitment derived from this credential
the target root is the public merkleRoot
the prover must provide the path from that leaf up to the root

MerkleTreeChecker simply recomputes upward level by level:

selectors[i].in[0] <== i == 0 ? leaf : hashers[i - 1].hash;
selectors[i].in[1] <== pathElements[i];
selectors[i].s <== pathIndices[i];

hashers[i].left <== selectors[i].out[0];
hashers[i].right <== selectors[i].out[1];

Code location: circuits/escrow/circom/merkleTree.circom

There are two key points here:

pathElements[i] gives the sibling node at each level
pathIndices[i] tells the circuit whether the current node is on the left or on the right

Because the left-right order matters, the final hash changes when the order changes. So if any path element is fake, or any left-right order is wrong, the final root will not match.

The last line in MerkleTreeChecker is:

root === hashers[levels - 1].hash;

Its meaning is very direct: the root recomputed by the circuit must equal the public merkleRoot.

Part Three of the Circuit: Bind the Proof to the Current Business Context

If the circuit only checked commitment and Merkle membership, one piece would still be missing.

Because the same membership proof could be reused elsewhere if there were no context binding.

So this circuit also includes domain, appId, chainId, and timestamp in the public inputs:

signal input domain;
signal input appId;
signal input chainId;
signal input timestamp;

Then it forces those fields to participate in constraints:

signal d2;
signal a2;
signal c2;
signal t2;
d2 <== domain * domain;
a2 <== appId * appId;
c2 <== chainId * chainId;
t2 <== timestamp * timestamp;

Code location: circuits/escrow/circom/escrowRelease.circom

Those lines look simple, but they matter.

The point is not to add a complicated new layer of business logic. The point is to make sure those public fields are actually used by the circuit, so they really become part of the statement behind this proof. Later, the contract checks them against expectedDomain, expectedAppId, and the current chainId, and only then is the proof truly bound to this business flow.

So What Is This Circuit Really Proving?

Put the three parts together, and the circuit is really proving:

the prover knows nullifier and secret
those private values really derive the public commitment and nullifierHash
that commitment really belongs to the public merkleRoot
the proof also carries the public context fields domain / appId / chainId / timestamp

So this is not a vague “I am allowed to release.”

A more accurate sentence is:

I know a valid credential, the commitment derived from it really belongs to an on-chain root, and this proof belongs to the current business context.

How the Browser Computes This Proof

Once the circuit is clear, the order inside the frontend proveEscrow() becomes much easier to follow.

It does not call snarkjs immediately. It first prepares every input the circuit needs:

const { nullifier, secret } = parseCredential(credential);
const { commitment, nullifierHash } = await computeCommitment(nullifier, secret);
const { root, pathElements, pathIndices } = await buildMerkleProof(
  leaves,
  leafIndex,
);

Code location: apps/web/src/zk/escrow/prover.ts in proveEscrow()

Those three steps line up directly with the three things the circuit needs:

the raw private credential: nullifier, secret
the public results derived from it: commitment, nullifierHash
the membership path: root, pathElements, pathIndices

After that, the frontend packs those values into one circuit input object:

const input = {
  merkleRoot: root.toString(),
  nullifierHash: nullifierHash.toString(),
  commitment: commitment.toString(),
  domain: domain.toString(),
  appId: appId.toString(),
  chainId: chainId.toString(),
  timestamp: timestamp.toString(),
  nullifier: nullifier.toString(),
  secret: secret.toString(),
  merklePath: pathElements.map((v) => v.toString()),
  merkleIndex: pathIndices,
};

Code location: apps/web/src/zk/escrow/prover.ts in proveEscrow()

Only then does it actually generate the proof:

const { proof, publicSignals } = await snarkjs.groth16.fullProve(
  input,
  wasmPath,
  zkeyPath,
);

Code location: apps/web/src/zk/escrow/prover.ts in proveEscrow()

So browser-side proving is not “throw some data into a library and magically get a proof.”

It is doing something very specific:

prepare the full witness and public inputs that the circuit needs, then let snarkjs generate a proof that an external verifier can check.

At that point, the meaning of the proof is finally complete.

Where zkVerify Enters the Flow After the Proof Is Generated

By now, the contract and the circuit have each been explained on their own. The next step is to go back to the whole business flow, because that makes the later verification path much easier to understand. In a zk project, the circuit and the contract are only two layers. The full flow also includes proof generation, proof verification, and the way the verification result is finally consumed on-chain. So first look at the general zk flow, then map this project onto it.

Before going further, it helps to place the overall flow in one frame.

A zk project usually goes through two stages:

first, generate a proof
second, verify that proof

The first stage happens on the prover side. The browser takes the inputs into the circuit, computes the witness, and calls the proving tool to generate a proof. That is where wasm and zkey are used. What is actually produced here is the new proof for this user action.

The second stage happens on the verifier side. The verification system takes that proof together with the public inputs and checks whether it is valid. This stage uses the verification material tied to the circuit, namely vk, or its identifier vkHash.

One timing detail matters here: proof is generated fresh every time a user asks for a proof. vk is not generated at that moment. It belongs to the earlier circuit preparation phase, where it is paired with zkey for this circuit.

Once you look at the timeline that way, the logic becomes much clearer.
The first timeline is the “prepare the circuit” phase, which usually happens once.

You first write the Circom circuit and compile it. After compilation, you get the wasm and the corresponding constraint system. Then you run the Groth16 setup for that circuit, which gives you the proving material you need later: zkey and the corresponding vk.
So zkey and vk do not appear out of nowhere. They both come from the same circuit, but they serve different roles: zkey is for the prover to generate proofs, and vk is for the verifier to check them.

The second timeline is what happens every time a user actually asks for a proof.

For example, when a user unlocks an escrow, the browser first prepares the inputs, then uses wasm + zkey to generate a new proof.

What is new every time is the proof, not the vk. The vk was already prepared during the earlier setup phase, and it stays tied to this circuit.

As for vkHash, you can think of it as an identifier for the vk.
Many systems do not pass around the full vk every time during runtime. Instead, they register the verification material up front and later use only an identifier such as vkHash.
This project works that way: the browser generates the proof, while the later verification path is built around proof, publicInputs, and vkHash.

In other words, what is generated fresh for each user action in this project is the proof, while vk / vkHash points to the verification material that was already prepared for this circuit.

In this project, the browser is responsible for generating the proof;
the later verification path goes through Kurier and zkVerify;
and what the chain finally consumes is not simply “the raw proof that just came out of the browser,” but the verification result returned by zkVerify.

At this point, the browser can already do something powerful:

it can generate a proof locally that says “I know a valid credential, and it belongs to some on-chain root.”

But that is still not the end of the flow.

Because what the business logic needs is not “a proof appeared in the browser.” It needs “the contract is willing to execute a real release based on that proof.”

There is still one verification layer between those two things.

That is exactly the layer zkVerify fills in this system.

Why Generating the Proof Is Still Not Enough

If the system used the route where the contract verifies the Groth16 proof directly, then once the browser generated the proof, the next step would simply be to send that proof into a verifier contract.

But this project does not work like that.

The route here is:

the browser first generates the proof locally
the server forwards the proof to Kurier
Kurier and zkVerify process that proof
the frontend receives an aggregation result that the chain can consume
finally, the contract uses verifyProofAggregation(...) to decide whether finalize() can pass

So zkVerify here is not the prover, and it is not the place where the credential is generated.

Its job is this: take an already-generated proof and turn it into a verification result that an on-chain contract can rely on.

What `/api/submit-proof` Does

Once the proof comes out of the browser, the first stop is not the contract. It is the server-side /api/submit-proof.

This layer has two jobs.

First, it keeps the Kurier API key on the server rather than exposing it to the frontend.

Second, before forwarding the proof, it cross-checks several key fields so that the frontend does not send out a proof whose context is inconsistent.

The most important checks are:

const chainFromInputs = normalize(publicInputs[5]);
if (chainFromInputs && String(chainId) !== chainFromInputs) { ... }

const domainFromInputs = normalize(publicInputs[3]);
if (domainFromInputs && String(domain) !== domainFromInputs) { ... }

const appIdFromInputs = normalize(publicInputs[4]);
if (appIdFromInputs && String(appId) !== appIdFromInputs) { ... }

const nullifierFromInputs = normalize(publicInputs[1]);
if (nullifierFromInputs && String(antiReplay.nullifier) !== nullifierFromInputs) { ... }

Code location: apps/web/src/pages/api/submit-proof.ts

In other words, the server is not blindly forwarding the proof. It first confirms:

the request chainId and the proof's publicInputs[5] are the same value
the request domain and appId really match the proof's public inputs
the anti-replay nullifier also matches the proof's nullifierHash

Only after those checks pass does the server build the Kurier submission payload:

return {
  proofType: 'groth16',
  chainId: Number(chainId),
  vkRegistered: true,
  proofOptions: getProofOptions(),
  proofData: {
    proof,
    publicSignals: publicInputs,
    vk: vkHash,
  },
};

Code location: apps/web/src/pages/api/submit-proof.ts in buildKurierSubmitPayload()

What `/api/proof-status` Does

After the proof is submitted, the frontend needs to know where it is in the pipeline.

That is the job of /api/proof-status. It queries Kurier for the job status, then normalizes several possible raw fields into a frontend-friendly status:

const statusRaw =
  result.data.status ||
  result.data.state ||
  result.data.jobStatus ||
  result.data.data?.status ||
  result.data.data?.state ||
  result.data.data?.jobStatus;

res.status(200).json({
  proofId,
  status: normalizeKurierStatus(statusRaw),
  rawStatus: statusRaw ?? 'unknown',
  updatedAt,
  statement,
  aggregationDetails,
});

Code location: apps/web/src/pages/api/proof-status.ts

One point matters here.

The Kurier status string is useful, but it is not the final condition that decides whether finalize() can pass on-chain. It is mostly telling the frontend where the proof is in the pipeline.

What really determines whether the contract can consume the result is whether the correct aggregation tuple can be retrieved later, and whether that tuple can pass the on-chain verifyProofAggregation(...) check.

What `/api/proof-aggregation` Does

When the proof reaches the aggregated status, the frontend requests /api/proof-aggregation.

This layer is not verifying the proof again. It is extracting the exact fields from Kurier's response that the contract actually needs later:

domainId
aggregationId
leafCount
index
merklePath
leaf

Code location: apps/web/src/pages/api/proof-aggregation.ts

The most important point here is:

the domainId here is not the same thing as the circuit public input domain.

The code explicitly says:

// zkVerify domainId (aggregation domain) is NOT the same semantic field as
// circuit public input domain/app domain. Never fallback to DOMAIN=1 here.

Code location: apps/web/src/pages/api/proof-aggregation.ts

Those two concepts have completely different roles:

domain in the circuit is part of the business context
domainId here is the zkVerify aggregation domain

If those two ideas get mixed up, finalize() is very likely to fail.

What zkVerify Ultimately Provides

By this point, what zkVerify gives this flow is not an abstract “verified” badge. It gives a set of data that the contract can actually consume.

From the frontend's point of view, the two most important outputs are:

the aggregation tuple: domainId / aggregationId / leafCount / index / merklePath
the corresponding leaf in the aggregation tree

Once the frontend has those two things, it can first compare the statement locally, then let the contract call:

zkVerify.verifyProofAggregation(
    domainId,
    aggregationId,
    leaf,
    merklePath,
    leafCount,
    index
)

Code location: contracts/src/ZKEscrowRelease.sol in finalize()

So if you had to summarize zkVerify's role here in one sentence, it would be:

the browser generates the proof, and zkVerify turns that proof into a verification result that the contract can consume.

How the Frontend Uses the zkVerify Result on the Target Chain

Now the previous sections connect into one flow.

Look at it in the real order.

Step 1: Start from the Credential and Produce the Local Proof

When the unlock flow starts, the frontend reads the user-provided credential, fetches the on-chain commitments, and finds the leaf that corresponds to that credential:

const commitments = await fetchCommitments();
const parsed = parseCredential(withdrawCredential);
const { commitment } = await computeCommitment(
  parsed.nullifier,
  parsed.secret,
);
const leafIndex = commitments.findIndex((c) => c === commitment);

Code location: apps/web/src/pages/escrow.tsx in handleUnlock()

Once it finds the leaf, the frontend calls proveEscrow():

const bundle = await proveEscrow({
  credential: withdrawCredential,
  leaves: commitments,
  leafIndex,
  domain: domainId,
  appId,
  chainId: BigInt(activeChainId),
  timestamp,
});

Code location: apps/web/src/pages/escrow.tsx in handleUnlock()

At that point, the browser already holds the local proof and the publicInputs for that proof.

Step 2: Run Local Prechecks First

After the proof is generated, the frontend still does not submit it immediately.

It first checks two things:

whether the proof's merkleRoot is a root the contract recognizes
whether the proof's chainId matches the chain the wallet is currently connected to

The corresponding code is:

const known = await publicClient.readContract({
  address: escrowAddress,
  abi: escrowAbi,
  functionName: 'isKnownRoot',
  args: [proofRoot],
});

if (proofChainId !== activeChainId) {
  throw new Error(
    `chainId mismatch (wallet=${activeChainId}, proof=${proofChainId})`,
  );
}

Code location: apps/web/src/pages/escrow.tsx in handleUnlock()

The purpose is simple: stop proofs that are obviously impossible before they go any further.

Step 3: Submit the Proof, Then Poll for Status

After the prechecks pass, the frontend calls /api/submit-proof:

const submitRes = await fetch('/api/submit-proof', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    proofId: `proof_${Date.now()}`,
    proof: bundle.proof,
    publicInputs: bundle.publicInputs,
    appId: appId.toString(),
    domain: domainId.toString(),
    userAddr: address,
    chainId: proofChainId,
    timestamp: Number(timestamp),
    antiReplay: {
      nullifier: bundle.nullifierHash.toString(),
    },
  }),
});

Code location: apps/web/src/pages/escrow.tsx in handleUnlock()

Once submission succeeds, the frontend keeps calling /api/proof-status until the status becomes aggregated. That status does not mean the business flow is finished. It means the frontend can now fetch the aggregation tuple.

One more time: aggregated is not the end of the flow. It only means zkVerify's side has finished preparing the verification result. The step that actually makes the business logic happen has not happened yet. The frontend still needs to send a finalize() transaction to the escrow contract on the target chain. Only when that on-chain call succeeds is the release really complete.

Step 4: Fetch the Aggregation Tuple and Confirm It Really Belongs to This Proof

Once the status becomes aggregated, the frontend calls /api/proof-aggregation:

const aggRes = await fetch('/api/proof-aggregation', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    proofId: submitData.proofId,
  }),
});

Code location: apps/web/src/pages/escrow.tsx in handleUnlock()

What comes back is not “another proof.” It is the aggregation tuple that the later on-chain verification will use.

But the frontend also performs one very important comparison:

it reads the on-chain vkHash, recomputes the statement locally from the current publicInputs, and compares that to the leaf returned from the aggregation:

const onChainVkHash = await publicClient.readContract({
  address: escrowAddress,
  abi: escrowAbi,
  functionName: 'vkHash',
});
const localStatement = computeLocalStatement(publicInputs, onChainVkHash);
if (localStatement.toLowerCase() !== aggLeaf.toLowerCase()) {
  throw new Error(
    `Proof/job mismatch (statement=${localStatement}, leaf=${aggLeaf}).`,
  );
}

Code location: apps/web/src/pages/escrow.tsx in handleUnlock()

What this step is asking is:

is the leaf returned by zkVerify really the statement produced by this exact proof?

If that does not match, then even with the tuple in hand, the later contract call will not pass.

Step 5: Run the zkVerify Precheck, Then Call `finalize()`

After the statement matches, the frontend still does not send a transaction immediately.

It first uses that tuple to call the zkVerify contract through a read-only precheck. The zkVerifyAddr used here is not just any address. It is the official zkVerify gateway/proxy address configured in the escrow contract:

Note
The zkVerifyAddr read here is not just some hardcoded contract address inside the project. It is the official zkVerify gateway/proxy address provided on the target chain. For the Base Sepolia setup used in this tutorial, the official address is 0x0807C544D38aE7729f8798388d89Be6502A1e8A8. For the full list of addresses, see the zkVerify docs: Contract Addresses.

zkvOk = await publicClient.readContract({
  address: zkVerifyAddr,
  abi: zkVerifyAbi,
  functionName: 'verifyProofAggregation',
  args: [domainIdFromAgg, aggregationId, localStatement, merklePath, leafCount, index],
});

Code location: apps/web/src/pages/escrow.tsx in handleUnlock()

This call is an eth_call. Its purpose is to ask one question first: if the frontend now really sends finalize() to the target chain, will the official zkVerify gateway/proxy contract accept this aggregation check?

Only after that precheck passes does the frontend simulate finalize(), then actually send the transaction:

await publicClient.simulateContract({
  address: escrowAddress,
  abi: escrowAbi,
  functionName: 'finalize',
  args: [
    domainIdFromAgg,
    aggregationId,
    merklePath,
    leafCount,
    index,
    publicInputs,
  ],
  account: address,
});

const txHash = await writeContractAsync({
  address: escrowAddress,
  abi: escrowAbi,
  functionName: 'finalize',
  args: [domainIdFromAgg, aggregationId, merklePath, leafCount, index, publicInputs],
});

Code location: apps/web/src/pages/escrow.tsx in handleUnlock()

In other words, the real allow path is:

the local proof is generated
the Kurier job reaches aggregated
the aggregation tuple is fetched successfully
the local statement matches the aggregation leaf
the verifyProofAggregation(...) precheck passes
only then is finalize() actually sent on-chain

One more thing needs to be said here: the read-only precheck does not mean the business flow is complete. Once finalize() is really sent, the escrow contract on the target chain will internally call the official zkVerify gateway/proxy contract's verifyProofAggregation(...) again. Only if that on-chain call also passes does finalize() continue to release the funds.

Final Summary

At this point, the frontend has already prepared everything it can.

The parameters received by finalize() are:

domainIdFromAgg
aggregationId
merklePath
leafCount
index
publicInputs

Then the contract runs one final round of checks:

whether publicInputs has the correct length
whether merkleRoot is a known root
whether domain / appId / chainId / timestamp are correct
whether verifyProofAggregation(...) passes
whether nullifierHash has already been used
whether deposits[commitment] exists and is still not spent

Only after all of those checks pass does the contract actually send the funds to the recipient that was locked at deposit time.

DEV Community: Jet Halo

How to Create a Zero Knowledge DApp: From Zero to Production, Case 2: zk P2P

Can a P2P on-ramp still work without a platform acting as escrow?

1. Why P2P on-ramps still rely on platform-backed escrow today

2. What zkp2p is and how it works

3. What components make up the system

4. How the seller’s money gets locked first

5. The browser layer: the page prepares the order first, then hands the proving work to the plugin

6. zkTLS / TLSNotary: first turn the Wise page into an attestation

7. tlsn-verifier: verify the attestation first, then compress it into wiseReceiptHash

8. apps/web API: what these four API routes each do

/api/verify-wise-attestation

/api/submit-proof

/api/proof-status

/api/proof-aggregation

9. The Noir circuit: the browser loads the artifact and generates the proof locally with UltraHonk

10. What exactly the circuit binds: statement, nullifier, wiseReceiptHash

11. After the proof leaves the browser, how the frontend waits for results from Kurier and zkVerify

12. How the final releaseWithProof() happens

How to Create a Zero Knowledge DApp: From Zero to Production, Case 1: zk Escrow

Understanding What Tornado Cash Is

What Tornado Cash Actually Does

Reconstructing the Product Flow from the User's Point of View

What commitment Is

Looking at nullifierHash

Finally, the Merkle Tree

What State the Contract Actually Stores On-Chain

The First Kind of State: the Data of Each Escrow

The Second Kind of State: Which Commitments Belong to Valid Deposits

The Third Kind of State: Which Credentials Have Already Been Consumed

The Fourth Kind of State: Which Business Context This Proof Is Supposed to Belong To

Putting Those Kinds of State Together

What the Circuit Actually Proves, and How the Browser Computes the Proof

First Look at the Two Kinds of Inputs in This Circuit

Part One of the Circuit: Recompute the Public Results from the Private Credential

Part Two of the Circuit: Check That This Commitment Really Belongs to the Tree

Part Three of the Circuit: Bind the Proof to the Current Business Context

So What Is This Circuit Really Proving?

How the Browser Computes This Proof

Where zkVerify Enters the Flow After the Proof Is Generated

Why Generating the Proof Is Still Not Enough

What /api/submit-proof Does

What /api/proof-status Does

What /api/proof-aggregation Does

What zkVerify Ultimately Provides

How the Frontend Uses the zkVerify Result on the Target Chain

Step 1: Start from the Credential and Produce the Local Proof

Step 2: Run Local Prechecks First

Step 3: Submit the Proof, Then Poll for Status

Step 4: Fetch the Aggregation Tuple and Confirm It Really Belongs to This Proof

Step 5: Run the zkVerify Precheck, Then Call finalize()

Final Summary

7. `tlsn-verifier`: verify the attestation first, then compress it into `wiseReceiptHash`

8. `apps/web API`: what these four API routes each do

`/api/verify-wise-attestation`

`/api/submit-proof`

`/api/proof-status`

`/api/proof-aggregation`

9. The `Noir` circuit: the browser loads the artifact and generates the proof locally with `UltraHonk`

10. What exactly the circuit binds: `statement`, `nullifier`, `wiseReceiptHash`

12. How the final `releaseWithProof()` happens

What `commitment` Is

Looking at `nullifierHash`

What `/api/submit-proof` Does

What `/api/proof-status` Does

What `/api/proof-aggregation` Does

Step 5: Run the zkVerify Precheck, Then Call `finalize()`