Skip to main content

ZK Proof System

zkIdentity's privacy guarantees rest on its zero-knowledge proof system. This document explains how proofs are generated, what they prove, and how they are verified.

Overview​

Zero-knowledge proofs (ZKPs) allow one party (the prover) to convince another party (the verifier) that a statement is true without revealing any information beyond the truth of the statement itself. In zkIdentity, the statement being proven is: "A licensed KYC provider has verified this user's identity, and the provider returned a positive result."

The system achieves this using zkFetch with TLS tunnels. zkFetch establishes a cryptographic tunnel to the KYC provider's API, fetches the verification result, and produces proofs that attest to both the authenticity of the response and specific claims about its content -- all without revealing the response body.

How zkFetch Works​

TLS Tunnel Establishment​

The proof generation process begins with establishing a TLS connection to the KYC provider's API. zkFetch interposes on the TLS handshake to create a cryptographic record of the session:

  1. Connection initiation: The attestor (running inside the TEE) initiates a TLS connection to the provider's API endpoint.

  2. Session key commitment: zkFetch records the TLS session keys in a way that allows the prover to later demonstrate what data was received without revealing the decryption keys to verifiers.

  3. Request execution: The attestor sends an authenticated API request to the provider using the provider's API key, which remains sealed inside the TEE.

  4. Response capture: The TLS-encrypted response from the provider is captured along with the cryptographic artifacts needed for proof generation.

  5. Session finalization: The TLS session is closed. The attestor now holds the provider response and the cryptographic material needed to prove its authenticity.

Proof Generation Pipeline​

After the TLS session completes, zkFetch enters the proof generation phase. This produces 14 distinct ZK proofs per verification request.

Provider Response (TLS-protected)
        |
        v
+-------------------+
| Response Parsing  |  Extract structured fields from JSON response
+-------------------+
        |
        v
+-------------------+
| Claim Extraction  |  Identify provable claims (status, country, etc.)
+-------------------+
        |
        v
+-------------------+
| Circuit Execution |  Run ZK circuits for each claim
+-------------------+
        |
        v
+-------------------+
| Proof Assembly    |  Combine individual proofs into attestation bundle
+-------------------+
        |
        v
  14 ZK Proofs + Metadata

The 14 ZK Proofs​

Each verification request generates exactly 14 ZK proofs. At a high level, these proofs cover three categories:

TLS Authenticity Proofs​

These proofs establish that the data genuinely came from the KYC provider's server over a legitimate TLS connection. They cover:

  • The TLS certificate belongs to the claimed provider domain.
  • The TLS session occurred within an acceptable time window (prevents replay attacks).
  • The response body was received over this specific TLS session (not fabricated).
  • The request that produced this response corresponds to the correct verification session.

Content Proofs​

These proofs attest to specific claims about the provider's response without revealing the full response body. They cover claims such as:

  • The provider returned a positive verification status.
  • The response came from a recognized KYC provider.
  • The verification was performed for a specific country jurisdiction.
  • The verification was completed within an acceptable time window.
  • The verification result corresponds to the correct user session.

Integrity Proofs​

These proofs ensure the overall integrity of the attestation:

  • The verification is bound to the user's specific DID.
  • The non-PII metadata extracted for on-chain storage is consistent with the proven claims.
  • All preceding proofs are internally consistent and form a valid attestation bundle.

What the Proofs Do NOT Reveal​

The zero-knowledge property ensures that the following information is never exposed:

  • The user's name, date of birth, or any biographical data
  • Document numbers (passport number, national ID number)
  • The user's photograph or biometric data
  • The user's address or phone number
  • The provider's raw API response body
  • The provider's API keys or authentication credentials
  • The TLS session keys

A verifier can confirm "this wallet holder passed KYC in a specific country" without learning anything else about the individual.

Proof Verification​

ZK proofs can be verified by anyone with access to the proof data and the verification keys. Verification occurs at two levels:

On-Chain Verification​

When the attestation is submitted to the Cartesi rollup, the rollup's RISC-V virtual machine executes the proof verification logic. This ensures:

  • All 14 proofs are valid.
  • The proofs are internally consistent.
  • The non-PII metadata matches the proven claims.
  • The DID binding is correct.

Only attestations with fully valid proof sets are accepted into the rollup state.

Off-Chain Verification​

Any third party can verify proofs off-chain by:

  1. Fetching the proof hashes from the rollup state.
  2. Retrieving the full proof data via the rollup's query interface.
  3. Running the verification algorithm locally using the published verification keys.

Proof Lifecycle​

Generation​

Proofs are generated inside the TEE attestor immediately after the KYC provider webhook is received and the provider's API response is fetched via zkFetch.

Storage​

Proof hashes are stored on the Cartesi rollup as part of the attestation record. Full proof data is available via the rollup's query endpoints for anyone who needs to perform off-chain verification.

Expiry​

Proofs themselves do not expire. However, the attestation they support may have an expiry policy defined at the application level.

Revocation​

If a KYC provider retroactively revokes a verification (e.g., due to fraud detection), the attestor can submit a revocation input to the Cartesi rollup, which updates the attestation status. The original proofs remain valid (they correctly prove what the provider said at the time), but the attestation status changes to "revoked."

Security Considerations​

Soundness​

The ZK proof system is computationally sound: an adversary cannot generate valid proofs for a verification that did not occur without breaking the underlying cryptographic assumptions.

Completeness​

If the KYC provider returns a valid positive result, the zkFetch pipeline will successfully generate all 14 proofs.

Zero-Knowledge​

The proofs reveal only the non-PII claims (verification status, country, provider, timestamp) and nothing more. This is enforced by the circuit design.

Replay Protection​

Freshness and timestamp proofs together prevent replay attacks. An adversary cannot reuse proofs from a previous session to attest a new verification.