ZKPassport

https://github.com/zkpassport/zkpassport-packages
Admin
ZKPassport is a privacy-preserving identity verification platform using passports and ID cards with...
Tokens:11,597
Snippets:67
Trust Score:7.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Start Registry Explorer Dev Server

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/registry-explorer/README.md

Navigate to the registry explorer directory and start the development server.

```bash
cd packages/registry-explorer
bun run dev
```

--------------------------------

### Install ZKPassport Registry SDK

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/registry-sdk/README.md

Install the ZKPassport registry package using Bun.

```bash
bun i @zkpassport/registry
```

--------------------------------

### Install Dependencies

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/zkpassport-sdk/README.md

Installs project dependencies using Bun. Ensure you have Bun installed before running this command.

```sh
bun install
```

--------------------------------

### Install ZKPassport SDK

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/zkpassport-sdk/README.md

Install the ZKPassport SDK using npm. This is the first step to integrate the SDK into your project.

```bash
npm install @zkpassport/sdk
```

--------------------------------

### Frontend Example using App Router

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/zkpassport-sdk/README.md

This example demonstrates how to fetch a verification URL from the backend API and display a button to initiate the identity verification process. It uses React's `useEffect` hook to fetch data when the component mounts.

```tsx
"use client"
import { useEffect, useState } from "react"

export default function Home() {
  const [verificationUrl, setVerificationUrl] = useState<string | null>(null)

  useEffect(() => {
    fetch("/api/zkpassport")
      .then((res) => res.json())
      .then((data) => setVerificationUrl(data.url))
      .catch(console.error)
  }, [])

  return (
    <div>
      <h1>ZKPassport Demo</h1>
      {verificationUrl ? (
        <a href={verificationUrl} target="_blank" rel="noopener noreferrer">
          <button>Verify Identity</button>
        </a>
      ) : (
        <p>Loading...</p>
      )}
    </div>
  )
}
```

--------------------------------

### Run and Deploy Contracts

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/registry-explorer/README.md

Start an Anvil instance, deploy contracts, and update roots. This should be run in a separate terminal.

```bash
cd packages/registry-contracts
script/bash/run-and-deploy.sh
```

--------------------------------

### Next.js Integration Pattern

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Example of server-side request creation and client-side URL rendering with the ZKPassport SDK in a Next.js App Router project.

```APIDOC
## Next.js Integration Pattern

Full example of server-side request creation and client-side URL rendering with the ZKPassport SDK in a Next.js App Router project.

```typescript
// app/api/zkpassport/route.ts  (Server — creates the request + bridge)
import { NextResponse } from "next/server"
import { ZKPassport, EU_COUNTRIES } from "@zkpassport/sdk"

export async function GET() {
  const zkPassport = new ZKPassport("app.example.com")
  const qb = await zkPassport.request({
    name: "My Next.js App",
    logo: "https://app.example.com/logo.png",
    purpose: "Prove you are an adult EU citizen",
    scope: "eu-adult",
  })
  const { url, requestId } = qb
    .disclose("firstname")
    .gte("age", 18)
    .in("nationality", EU_COUNTRIES)
    .done()
  return NextResponse.json({ url, requestId })
}

// app/page.tsx  (Client — renders the QR code / link)
"use client"
import { useEffect, useState } from "react"
import QRCode from "react-qr-code"

export default function VerifyPage() {
  const [verifyUrl, setVerifyUrl] = useState<string | null>(null)

  useEffect(() => {
    fetch("/api/zkpassport")
      .then(r => r.json())
      .then(data => setVerifyUrl(data.url))
  }, [])

  if (!verifyUrl) return <p>Loading…</p>
  return (
    <div>
      <h1>Scan with ZKPassport app</h1>
      <QRCode value={verifyUrl} />
      <p>Or on mobile: <a href={verifyUrl}>Open in ZKPassport</a></p>
    </div>
  )
}
```
```

--------------------------------

### Retrieve Request URL

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Get the deep link URL for a given request ID, useful for regenerating QR codes.

```APIDOC
## `zkPassport.getUrl()`

### Description
Returns the deep link URL for a given `requestId` after the request was created. Useful for regenerating QR codes without reconstructing the request.

### Usage
```typescript
const url = zkPassport.getUrl(requestId)
console.log(url)
```

### Parameters
- **requestId** (string) - Required - The ID of the request for which to retrieve the URL.
```

--------------------------------

### Build Registry SDK

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/registry-explorer/README.md

Navigate to the registry SDK directory and run the build command.

```bash
cd packages/registry-sdk
bun run build
```

--------------------------------

### Initialize and Use RegistryClient

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Connect to different Ethereum chains and interact with certificate and circuit registries. Fetch roots, details, and packaged certificates or circuits.

```typescript
import { RegistryClient } from "@zkpassport/registry"

// Connect to Ethereum Mainnet (chainId 1), Base Mainnet (8453), or Sepolia (11155111)
const registry = new RegistryClient({ chainId: 1 })

// --- Certificate Registry ---
const latestCertRoot = await registry.getLatestCertificateRoot()
console.log("Latest cert root:", latestCertRoot)

const isValid = await registry.isCertificateRootValid("0xabc123...")
console.log("Root valid:", isValid)

const certDetails = await registry.getCertificateRootDetails()
console.log("Index:", certDetails.index, "Valid from:", certDetails.validFrom)

// Fetch and validate packaged certificates (validates Merkle root by default)
const certs = await registry.getCertificates(undefined, { validate: true })
console.log(`Loaded ${certs.certificates.length} certificates`)

// Paginated historical roots
const { roots, isLastPage } = await registry.getHistoricalCertificateRoots(1, 50)
roots.forEach(r => console.log(r.root, r.validFrom, r.isLatest))

// --- Circuit Registry ---
const latestCircuitRoot = await registry.getLatestCircuitRoot()
const circuitManifest = await registry.getCircuitManifest(undefined, { validate: true })
console.log("Manifest version:", circuitManifest.version)
console.log("Circuits:", Object.keys(circuitManifest.circuits))

// Fetch a specific packaged circuit with vkey validation
const circuit = await registry.getPackagedCircuit("compare_age", circuitManifest)
console.log("Circuit:", circuit.name, "Noir:", circuit.noir_version)

// --- Document Support Check ---
const support = await registry.isDocumentSupported(
  "USA",                  // ISO 3166-1 alpha-3 country code
  new Date("2023-06-01"), // issue date (optional)
  "passport",             // "passport" | "id_card" | "residence_permit"
)
// Returns: NOT_SUPPORTED | TENTATIVE_SUPPORT | PARTIAL_SUPPORT | GOOD_SUPPORT | FULL_SUPPORT
console.log("Document support:", support)

// --- Registry Addresses ---
console.log("Root Registry:", registry.getRootRegistryAddress())
console.log("Registry Helper:", registry.getRegistryHelperAddress())
const certAddr = await registry.getCertificateRegistryAddress()
const circuitAddr = await registry.getCircuitRegistryAddress()
```

--------------------------------

### Initialize and Use Registry Client

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/registry-sdk/README.md

Initialize the RegistryClient with a chain ID and demonstrate fetching the latest certificate root, retrieving certificates for the latest root, fetching certificates for a specific root, and validating certificates against a root.

```typescript
import { RegistryClient } from "@zkpassport/registry"

// Initialize registry client
const client = new RegistryClient({ chainId: 11155111 })

// Get latest certificates root
const root = await client.getLatestCertificateRoot()
console.log(`Latest certificates root: ${root}`)

// Get latest certificates (for latest root)
const certs = await client.getCertificates()
console.log(`Got ${certs.length} certificates`)

// Get certificates for a specific root
const forRoot = "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
const certsForRoot = await client.getCertificates(forRoot)
console.log(`Got ${certs.length} certificates for root ${forRoot}`)

// Validate certificates against a root
const valid = await client.validateCertificates(certsForRoot, forRoot)
console.log(`Certificates are ${valid ? "valid" : "invalid"}`)
```

--------------------------------

### Run Tests

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/zkpassport-sdk/README.md

Executes the project's test suite using Bun. This command verifies the integrity and functionality of the SDK.

```sh
bun test
```

--------------------------------

### Clone ZKPassport SDK Repository

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/zkpassport-sdk/README.md

Instructions for cloning the ZKPassport SDK repository from GitHub. This is the first step to setting up the project locally.

```sh
git clone https://github.com/zkpassport/zkpassport-sdk.git
cd zkpassport-sdk
```

--------------------------------

### Instantiate ZKPassport Class

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Instantiate the main SDK class. In a browser, the domain is inferred from window.location.hostname. In Node.js, it must be provided explicitly.

```typescript
import { ZKPassport } from "@zkpassport/sdk"

// Browser: domain auto-detected from window.location.hostname
const zkPassport = new ZKPassport()

// Node.js / server-side: domain must be provided
const zkPassport = new ZKPassport("app.example.com")
```

--------------------------------

### ZKPassport Class Constructor

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Instantiate the main ZKPassport SDK class. In a browser, the domain is automatically detected. In Node.js, the domain must be provided explicitly.

```APIDOC
## ZKPassport Class — Constructor

Instantiate the main SDK class with your domain. In a browser, the domain is inferred from `window.location.hostname`; in Node.js it must be provided explicitly.

```typescript
import { ZKPassport } from "@zkpassport/sdk"

// Browser: domain auto-detected from window.location.hostname
const zkPassport = new ZKPassport()

// Node.js / server-side: domain must be provided
const zkPassport = new ZKPassport("app.example.com")
```
```

--------------------------------

### RegistryClient Initialization

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/registry-sdk/README.md

Initializes the RegistryClient with a specific chain ID.

```APIDOC
## Initialize RegistryClient

### Description
Initializes the ZKPassport RegistryClient with the provided chain ID.

### Method
`new RegistryClient(options: { chainId: number })`

### Parameters
#### Constructor Parameters
- **options** (object) - Required - Configuration options for the client.
  - **chainId** (number) - Required - The ID of the blockchain network to connect to.
```

--------------------------------

### Build Credential Request with QueryBuilder

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Use the QueryBuilder to specify which fields to disclose, apply numerical and date range filters, perform exact matches, filter by country, screen for sanctions, bind to an Ethereum address, and perform facematch checks. The `.done()` method finalizes the request and returns a URL.

```typescript
import { ZKPassport, SCHENGEN_COUNTRIES, NullifierType } from "@zkpassport/sdk"

const zkPassport = new ZKPassport("app.example.com")
const qb = await zkPassport.request({
  name: "KYC Service",
  logo: "https://kyc.example.com/logo.png",
  purpose: "Full KYC verification",
  uniqueIdentifierType: NullifierType.NON_SALTED, // stable cross-session identifier
})

const { url } = qb
  // Disclose specific fields from the ID
  .disclose("firstname")
  .disclose("lastname")
  .disclose("birthdate")
  .disclose("nationality")
  .disclose("document_number")
  .disclose("document_type")
  // Numerical comparisons for age
  .gte("age", 18)           // age >= 18
  .lt("age", 120)           // age < 120
  // Numerical range for expiry date
  .range("expiry_date", new Date(), new Date("2030-01-01"))
  // Exact match
  .eq("gender", "M")
  // Country inclusion / exclusion (accepts full names or ISO 3166-1 alpha-3 codes)
  .in("issuing_country", SCHENGEN_COUNTRIES)
  .out("nationality", ["RUS", "BLR"])
  // Sanctions screening against all global lists
  .sanctions("all", "all", { strict: false })
  // Bind proof to a specific Ethereum address (on-chain use)
  .bind("user_address", "0xAbCd1234...")
  .bind("chain", "ethereum")
  // Liveness / facematch check (requires ZKPassport app v2+)
  .facematch("regular")   // "regular" | "strict"
  .done()

console.log("Scan this URL:", url)
```

--------------------------------

### zkPassport.verify() - Manual Server-Side Proof Verification

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

The `verify()` method is used for manual server-side verification of proofs received from the mobile app against the original query. This method is automatically called by the SDK in online mode but can be invoked manually for server-side or split-flow architectures. It takes proofs, the original query, query results, validity period, scope, and other options as arguments.

```APIDOC
## `zkPassport.verify()` — Manual Server-Side Proof Verification

Verifies an array of proofs received from the mobile app against the original query. Called automatically by the SDK in online mode; call it manually for server-side / split-flow architectures.

```typescript
import { ZKPassport } from "@zkpassport/sdk"

const zkPassport = new ZKPassport("app.example.com")

// Proofs and queryResult arrive from the client via your own transport
const { proofs, queryResult } = req.body

// Reconstruct the original query server-side
const { query: originalQuery } = zkPassport
  .createQuery()
  .gte("age", 18)
  .disclose("nationality")
  .done()

const {
  uniqueIdentifier,
  uniqueIdentifierType,
  verified,
  queryResultErrors,
} = await zkPassport.verify({
  proofs,
  originalQuery,
  queryResult,
  validity: 7 * 24 * 60 * 60,  // max age of proof in seconds
  scope: "eu-adult-check",
  devMode: false,
  writingDirectory: "/tmp",      // required on serverless (e.g. Vercel)
})

if (!verified) {
  console.error("Verification failed:", queryResultErrors)
  return res.status(403).json({ error: "Invalid proof" })
}

res.json({ uniqueIdentifier, nationality: queryResult.nationality?.disclose?.result })
```
```

--------------------------------

### zkPassport.createQuery() - Offline Query Builder

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

The `createQuery()` method allows for the construction of a query object without establishing a network connection. This is useful on the server-side for reconstructing the original query for tamper-proof verification. The `.done()` method finalizes the query construction.

```APIDOC
## `zkPassport.createQuery()` — Offline Query Builder

Creates a query object without establishing a bridge connection. Useful server-side to reconstruct the original query for tamper-proof verification.

```typescript
import { ZKPassport } from "@zkpassport/sdk"

const zkPassport = new ZKPassport("app.example.com")

// Build the canonical query on the server — no network calls made
const { query } = zkPassport
  .createQuery()
  .gte("age", 18)
  .in("nationality", ["FRA", "DEU", "ITA"])
  .disclose("firstname")
  .sanctions()
  .done()

// `query` can now be compared against the query embedded in received proofs
console.log(JSON.stringify(query))
// {
//   age: { gte: 18 },
//   nationality: { in: ["FRA", "DEU", "ITA"] },
//   firstname: { disclose: true },
//   sanctions: { countries: "all", lists: "all", strict: false }
// }
```
```

--------------------------------

### Create Online Verification Request with QueryBuilder

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Creates a bridge session and returns a QueryBuilder for constructing credential queries. The URL generated by `.done()` can be rendered as a QR code or deep link. Event handlers can be attached to monitor the verification process.

```typescript
import { ZKPassport, EU_COUNTRIES } from "@zkpassport/sdk"

const zkPassport = new ZKPassport("app.example.com")

const queryBuilder = await zkPassport.request({
  name: "My App",
  logo: "https://app.example.com/logo.png",
  purpose: "Verify you are an adult EU citizen",
  scope: "eu-adult-check",      // optional: scopes the unique identifier
  validity: 7 * 24 * 60 * 60,  // optional: proof freshness in seconds (default 7 days)
  devMode: false,               // optional: allow ZKR mock passports for testing
  mode: "fast",                 // optional: "fast" | "compressed-evm"
})

const { 
  url,
  requestId,
  onRequestReceived,
  onGeneratingProof,
  onBridgeConnect,
  onProofGenerated,
  onResult,
  onReject,
  onError,
  isBridgeConnected,
  requestReceived,
} = queryBuilder
  .disclose("firstname")
  .disclose("nationality")
  .gte("age", 18)
  .in("nationality", EU_COUNTRIES)
  .out("nationality", ["Sweden", "Norway", "Denmark"])
  .done()

// Render url as a QR code or <a href={url}> for mobile

onBridgeConnect(() => console.log("Bridge ready"))
onRequestReceived(() => console.log("User opened the request on their phone"))
onGeneratingProof(() => console.log("User accepted — generating proof…"))
onProofGenerated((proof) => console.log("Partial proof received:", proof.name))

onResult(({ uniqueIdentifier, verified, result, queryResultErrors }) => {
  if (!verified) {
    console.error("Proof verification failed", queryResultErrors)
    return
  }
  console.log("First name:", result.firstname?.disclose?.result)
  console.log("Nationality:", result.nationality?.disclose?.result)
  console.log("Is adult:", result.age?.gte?.result)        // boolean
  console.log("In EU:", result.nationality?.in?.result)    // boolean
  console.log("Not Scandinavian:", result.nationality?.out?.result)
  console.log("Unique ID:", uniqueIdentifier)              // stable per domain+scope+passport
})

onReject(() => console.warn("User rejected the request"))
onError((err) => console.error("Error:", err))
```

--------------------------------

### On-Chain EVM Verification with ZKPassport

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Use `getSolidityVerifierDetails` and `getSolidityVerifierParameters` to verify proofs on-chain. Requires the request to be created with `mode: "compressed-evm"`. The verifier contract address is deterministic across networks.

```typescript
import { ZKPassport } from "@zkpassport/sdk"
import { createPublicClient, http } from "viem"
import { mainnet } from "viem/chains"

const zkPassport = new ZKPassport("app.example.com")

// Step 1: Request with EVM-compatible proof mode
const qb = await zkPassport.request({
  name: "On-Chain App",
  logo: "https://onchain.example.com/logo.png",
  purpose: "Verify age for token gating",
  mode: "compressed-evm",
})
const { url, onResult } = qb.gte("age", 18).bind("user_address", "0xABCD...").done()

onResult(async ({ verified, result }) => {
  if (!verified) return

  // Step 2: Get the outer_evm proof from the result for on-chain use
  const outerEvmProof = /* proof received from onProofGenerated with name "outer_evm_*" */ null as any

  // Step 3: Get verifier contract details
  const { address, abi, functionName } = zkPassport.getSolidityVerifierDetails()
  // address: "0x1D000001000EFD9a6371f4d90bB8920D5431c0D8" (deterministic on all networks)

  // Step 4: Format proof parameters
  const params = zkPassport.getSolidityVerifierParameters({
    proof: outerEvmProof,
    validityPeriodInSeconds: 7 * 24 * 60 * 60,
    domain: "app.example.com",
    scope: "token-gate",
    devMode: false,
  })

  // Step 5: Call the contract
  const client = createPublicClient({ chain: mainnet, transport: http() })
  const [isValid] = await client.readContract({ address, abi, functionName, args: [params] })
  console.log("On-chain verification result:", isValid)
})
```

--------------------------------

### Display ZKPassport Project Structure

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/README.md

This snippet displays the directory structure of the ZKPassport monorepo. It is useful for understanding the organization of different packages within the project.

```bash
zkpassport-packages/
├── packages/
│   ├── registry-contracts/     # Registry Contracts
│   ├── registry-sdk/           # Registry SDK
│   ├── registry-explorer/      # Registry Explorer
│   ├── zkpassport-sdk/         # ZKPassport SDK
│   └── zkpassport-utils/       # ZKPassport Utils
```

--------------------------------

### zkPassport.request() — Create an Online Verification Request

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Creates a bridge session and returns a `QueryBuilder` to construct the credential query. The `.done()` method returns a URL to be rendered as a QR code or deep link.

```APIDOC
## `zkPassport.request()` — Create an Online Verification Request

Creates a bridge session, returns a fluent `QueryBuilder` for building the credential query. The `url` returned by `.done()` should be rendered as a QR code or a deep link button.

```typescript
import { ZKPassport, EU_COUNTRIES } from "@zkpassport/sdk"

const zkPassport = new ZKPassport("app.example.com")

const queryBuilder = await zkPassport.request({
  name: "My App",
  logo: "https://app.example.com/logo.png",
  purpose: "Verify you are an adult EU citizen",
  scope: "eu-adult-check",      // optional: scopes the unique identifier
  validity: 7 * 24 * 60 * 60,  // optional: proof freshness in seconds (default 7 days)
  devMode: false,               // optional: allow ZKR mock passports for testing
  mode: "fast",                 // optional: "fast" | "compressed-evm"
})

const {
  url,
  requestId,
  onRequestReceived,
  onGeneratingProof,
  onBridgeConnect,
  onProofGenerated,
  onResult,
  onReject,
  onError,
  isBridgeConnected,
  requestReceived,
} = queryBuilder
  .disclose("firstname")
  .disclose("nationality")
  .gte("age", 18)
  .in("nationality", EU_COUNTRIES)
  .out("nationality", ["Sweden", "Norway", "Denmark"])
  .done()

// Render url as a QR code or <a href={url}> for mobile

onBridgeConnect(() => console.log("Bridge ready"))
onRequestReceived(() => console.log("User opened the request on their phone"))
onGeneratingProof(() => console.log("User accepted — generating proof…"))
onProofGenerated((proof) => console.log("Partial proof received:", proof.name))

onResult(({ uniqueIdentifier, verified, result, queryResultErrors }) => {
  if (!verified) {
    console.error("Proof verification failed", queryResultErrors)
    return
  }
  console.log("First name:", result.firstname?.disclose?.result)
  console.log("Nationality:", result.nationality?.disclose?.result)
  console.log("Is adult:", result.age?.gte?.result)        // boolean
  console.log("In EU:", result.nationality?.in?.result)    // boolean
  console.log("Not Scandinavian:", result.nationality?.out?.result)
  console.log("Unique ID:", uniqueIdentifier)              // stable per domain+scope+passport
})

onReject(() => console.warn("User rejected the request"))
onError((err) => console.error("Error:", err))
```
```

--------------------------------

### getCertificates

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/registry-sdk/README.md

Retrieves certificates from the registry, optionally filtered by a specific root hash.

```APIDOC
## getCertificates

### Description
Retrieves a list of certificates from the ZKPassport registry. If a root hash is provided, it fetches certificates associated with that specific root.

### Method
`client.getCertificates(root?: string): Promise<Array<any>>`

### Parameters
#### Query Parameters
- **root** (string) - Optional - The root hash of the certificate tree to filter by. If omitted, certificates for the latest root are fetched.
```

--------------------------------

### Simulate Websocket Messages

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/zkpassport-sdk/README.md

Scripts to simulate websocket messages for mobile and frontend clients. Use these to test real-time communication flows.

```sh
bun run scripts/simulate.ts mobile
```

```sh
bun run scripts/simulate.ts frontend
```

--------------------------------

### RegistryClient - Onchain Registry Client

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Interact with ZKPassport's onchain certificate and circuit registries on Ethereum, Base, or Sepolia.

```APIDOC
## `RegistryClient` — Onchain Registry Client

The `@zkpassport/registry` package provides `RegistryClient` to interact with ZKPassport's onchain certificate and circuit registries on Ethereum, Base, or Sepolia.

```typescript
import { RegistryClient } from "@zkpassport/registry"

// Connect to Ethereum Mainnet (chainId 1), Base Mainnet (8453), or Sepolia (11155111)
const registry = new RegistryClient({ chainId: 1 })

// --- Certificate Registry ---
const latestCertRoot = await registry.getLatestCertificateRoot()
console.log("Latest cert root:", latestCertRoot)

const isValid = await registry.isCertificateRootValid("0xabc123...")
console.log("Root valid:", isValid)

const certDetails = await registry.getCertificateRootDetails()
console.log("Index:", certDetails.index, "Valid from:", certDetails.validFrom)

// Fetch and validate packaged certificates (validates Merkle root by default)
const certs = await registry.getCertificates(undefined, { validate: true })
console.log(`Loaded ${certs.certificates.length} certificates`)

// Paginated historical roots
const { roots, isLastPage } = await registry.getHistoricalCertificateRoots(1, 50)
roots.forEach(r => console.log(r.root, r.validFrom, r.isLatest))

// --- Circuit Registry ---
const latestCircuitRoot = await registry.getLatestCircuitRoot()
const circuitManifest = await registry.getCircuitManifest(undefined, { validate: true })
console.log("Manifest version:", circuitManifest.version)
console.log("Circuits:", Object.keys(circuitManifest.circuits))

// Fetch a specific packaged circuit with vkey validation
const circuit = await registry.getPackagedCircuit("compare_age", circuitManifest)
console.log("Circuit:", circuit.name, "Noir:", circuit.noir_version)

// --- Document Support Check ---
const support = await registry.isDocumentSupported(
  "USA",                  // ISO 3166-1 alpha-3 country code
  new Date("2023-06-01"), // issue date (optional)
  "passport",             // "passport" | "id_card" | "residence_permit"
)
// Returns: NOT_SUPPORTED | TENTATIVE_SUPPORT | PARTIAL_SUPPORT | GOOD_SUPPORT | FULL_SUPPORT
console.log("Document support:", support)

// --- Registry Addresses ---
console.log("Root Registry:", registry.getRootRegistryAddress())
console.log("Registry Helper:", registry.getRegistryHelperAddress())
const certAddr = await registry.getCertificateRegistryAddress()
const circuitAddr = await registry.getCircuitRegistryAddress()
```
```

--------------------------------

### QueryBuilder - Credential Query Methods

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

The QueryBuilder provides a fluent interface for constructing credential requests. Methods like `disclose`, `gte`, `lt`, `range`, `eq`, `in`, `out`, `sanctions`, `bind`, and `facematch` can be chained to specify the desired credentials and conditions. The `.done()` method finalizes the request and returns a URL.

```APIDOC
## `QueryBuilder` — Credential Query Methods

The query builder is a fluent chainable interface returned by `request()` and `createQuery()`. All methods return `this` (the same builder), and `.done()` finalizes the request.

```typescript
import { ZKPassport, SCHENGEN_COUNTRIES, NullifierType } from "@zkpassport/sdk"

const zkPassport = new ZKPassport("app.example.com")
const qb = await zkPassport.request({
  name: "KYC Service",
  logo: "https://kyc.example.com/logo.png",
  purpose: "Full KYC verification",
  uniqueIdentifierType: NullifierType.NON_SALTED, // stable cross-session identifier
})

const { url } = qb
  // Disclose specific fields from the ID
  .disclose("firstname")
  .disclose("lastname")
  .disclose("birthdate")
  .disclose("nationality")
  .disclose("document_number")
  .disclose("document_type")
  // Numerical comparisons for age
  .gte("age", 18)           // age >= 18
  .lt("age", 120)           // age < 120
  // Numerical range for expiry date
  .range("expiry_date", new Date(), new Date("2030-01-01"))
  // Exact match
  .eq("gender", "M")
  // Country inclusion / exclusion (accepts full names or ISO 3166-1 alpha-3 codes)
  .in("issuing_country", SCHENGEN_COUNTRIES)
  .out("nationality", ["RUS", "BLR"])
  // Sanctions screening against all global lists
  .sanctions("all", "all", { strict: false })
  // Bind proof to a specific Ethereum address (on-chain use)
  .bind("user_address", "0xAbCd1234...")
  .bind("chain", "ethereum")
  // Liveness / facematch check (requires ZKPassport app v2+)
  .facematch("regular")   // "regular" | "strict"
  .done()

console.log("Scan this URL:", url)
```
```

--------------------------------

### Manual Server-Side Proof Verification

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Manually verify proofs received from the mobile app against the original query using `zkPassport.verify()`. This is for server-side or split-flow architectures. Ensure proofs are within the specified `validity` period.

```typescript
import { ZKPassport } from "@zkpassport/sdk"

const zkPassport = new ZKPassport("app.example.com")

// Proofs and queryResult arrive from the client via your own transport
const { proofs, queryResult } = req.body

// Reconstruct the original query server-side
const { query: originalQuery } = zkPassport
  .createQuery()
  .gte("age", 18)
  .disclose("nationality")
  .done()

const { 
  uniqueIdentifier,
  uniqueIdentifierType,
  verified,
  queryResultErrors,
} = await zkPassport.verify({
  proofs,
  originalQuery,
  queryResult,
  validity: 7 * 24 * 60 * 60,  // max age of proof in seconds
  scope: "eu-adult-check",
  devMode: false,
  writingDirectory: "/tmp",      // required on serverless (e.g. Vercel)
})

if (!verified) {
  console.error("Verification failed:", queryResultErrors)
  return res.status(403).json({ error: "Invalid proof" })
}

res.json({ uniqueIdentifier, nationality: queryResult.nationality?.disclose?.result })
```

--------------------------------

### getLatestCertificateRoot

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/registry-sdk/README.md

Retrieves the latest root hash of the certificates from the registry.

```APIDOC
## getLatestCertificateRoot

### Description
Fetches the most recent root hash for the certificate tree from the ZKPassport registry.

### Method
`client.getLatestCertificateRoot(): Promise<string>`

### Returns
- **Promise<string>** - A promise that resolves to the latest certificate root hash as a string.
```

--------------------------------

### Backend API Route for ZKPassport Request (Next.js App Router)

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/zkpassport-sdk/README.md

Set up a Next.js API route to handle ZKPassport requests. This backend route generates the verification URL which can then be used by the frontend.

```typescript
import { NextResponse } from "next/server"
import { ZKPassport } from "@zkpassport/sdk"

export async function GET() {
  const zkPassport = new ZKPassport("demo.zkpassport.id") // Replace with your domain
  const queryBuilder = await zkPassport.request({
    name: "ZKPassport Demo",
    logo: "https://via.placeholder.com/150",
    purpose: "Verify user nationality and first name",
  })
  const { url } = queryBuilder.disclose("nationality").disclose("firstname").done()
  return NextResponse.json({ url })
}
```

--------------------------------

### Create Query Object Offline with QueryBuilder

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Use `zkPassport.createQuery()` to build a query object server-side without network calls. This is useful for reconstructing the original query for tamper-proof verification.

```typescript
import { ZKPassport } from "@zkpassport/sdk"

const zkPassport = new ZKPassport("app.example.com")

// Build the canonical query on the server — no network calls made
const { query } = zkPassport
  .createQuery()
  .gte("age", 18)
  .in("nationality", ["FRA", "DEU", "ITA"])
  .disclose("firstname")
  .sanctions()
  .done()

// `query` can now be compared against the query embedded in received proofs
console.log(JSON.stringify(query))
```

--------------------------------

### Next.js Integration: Client-side QR Code Rendering

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Client-side component in a Next.js App Router project to fetch the ZKPassport verification URL and render it as a QR code. Requires 'react-qr-code' and 'useState', 'useEffect' hooks.

```typescript
// app/page.tsx  (Client — renders the QR code / link)
"use client"
import { useEffect, useState } from "react"
import QRCode from "react-qr-code"

export default function VerifyPage() {
  const [verifyUrl, setVerifyUrl] = useState<string | null>(null)

  useEffect(() => {
    fetch("/api/zkpassport")
      .then(r => r.json())
      .then(data => setVerifyUrl(data.url))
  }, [])

  if (!verifyUrl) return <p>Loading…</p>
  return (
    <div>
      <h1>Scan with ZKPassport app</h1>
      <QRCode value={verifyUrl} />
      <p>Or on mobile: <a href={verifyUrl}>Open in ZKPassport</a></p>
    </div>
  )
}
```

--------------------------------

### Next.js Integration: Server-side Request Creation

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Server-side route in a Next.js App Router project to create a ZKPassport request URL and requestId. Requires NextResponse and ZKPassport SDK.

```typescript
// app/api/zkpassport/route.ts  (Server — creates the request + bridge)
import { NextResponse } from "next/server"
import { ZKPassport, EU_COUNTRIES } from "@zkpassport/sdk"

export async function GET() {
  const zkPassport = new ZKPassport("app.example.com")
  const qb = await zkPassport.request({
    name: "My Next.js App",
    logo: "https://app.example.com/logo.png",
    purpose: "Prove you are an adult EU citizen",
    scope: "eu-adult",
  })
  const { url, requestId } = qb
    .disclose("firstname")
    .gte("age", 18)
    .in("nationality", EU_COUNTRIES)
    .done()
  return NextResponse.json({ url, requestId })
```

--------------------------------

### On-Chain EVM Verification

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Retrieve contract details and format parameters for on-chain verification of proofs using the ZKPassport SDK. This is used when the request is created with `mode: "compressed-evm"`.

```APIDOC
## `zkPassport.getSolidityVerifierDetails()` and `getSolidityVerifierParameters()`

### Description
Returns the contract address, ABI, and formatted call parameters needed to verify a proof on Ethereum or Base using the deployed `ZKPassportVerifier` contract. Requires the request to be created with `mode: "compressed-evm"`.

### Usage
```typescript
// Step 3: Get verifier contract details
const { address, abi, functionName } = zkPassport.getSolidityVerifierDetails()

// Step 4: Format proof parameters
const params = zkPassport.getSolidityVerifierParameters({
  proof: outerEvmProof,
  validityPeriodInSeconds: 7 * 24 * 60 * 60,
  domain: "app.example.com",
  scope: "token-gate",
  devMode: false,
})

// Step 5: Call the contract
const client = createPublicClient({ chain: mainnet, transport: http() })
const [isValid] = await client.readContract({
  address,
  abi,
  functionName,
  args: [params],
})
console.log("On-chain verification result:", isValid)
```

### Parameters for `getSolidityVerifierParameters`
- **proof** (any) - Required - The generated proof for verification.
- **validityPeriodInSeconds** (number) - Required - The validity period of the proof in seconds.
- **domain** (string) - Required - The domain of the application.
- **scope** (string) - Required - The scope of the verification.
- **devMode** (boolean) - Required - Flag to enable development mode.
```

--------------------------------

### Request Identity Verification

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/zkpassport-sdk/README.md

Initialize ZKPassport and create a request for identity verification. Specify app details and the purpose of the request. This sets up the data disclosure and verification criteria.

```typescript
import { ZKPassport, EU_COUNTRIES } from "@zkpassport/sdk"

// Replace with your domain
const zkPassport = new ZKPassport("demo.zkpassport.id")

// Specify your app name, logo and the purpose of the request
// you'll send to your visitors or users
const queryBuilder = await zkPassport.request({
  name: "ZKPassport",
  logo: "https://zkpassport.id/logo.png",
  purpose: "Prove you are an adult from the EU but not from Scandinavia",
  // The scope is optional and can be used to scope the unique identifier
  // of the request to a specific use case
  // By default, the request's unique identifier is scoped to your domain name only
  scope: "eu-adult-not-scandinavia",
})

// Specify the data you want to disclose
// Then you can call the `done` method to get the url and the callbacks to follow the progress
// and get back the result along with the proof
// The example below requests to disclose the firstname, prove the user is at least 18 years old,
// prove the user is from the EU but not from a Scandinavian country (note that Norway is not in the EU)
const {
  url,
  requestId,
  onRequestReceived,
  onGeneratingProof,
  onProofGenerated,
  onResult,
  onReject,
  onError,
} = queryBuilder
  .disclose("firstname")
  .gte("age", 18)
  .in("nationality", EU_COUNTRIES)
  .out("nationality", ["Sweden", "Denmark"])
  .done()

// Generate a QR Code with the url and let your user scan it
// or transform it into a button if the user is on their phone

onRequestReceived(() => {
  // The user scanned the QR code or clicked the link to the request
  // Essentially, this means the request popup is now opened
  // on the user phone
  console.log("Request received")
})

onGeneratingProof(() => {
  // The user accepted the request and the proof is being generated
  console.log("Generating proof")
})

// You probably don't need to use this callback
// But if you want to get the proofs and verify them manually, it's here
onProofGenerated(({ proof, vkeyHash, version, name }: ProofResult) => {
  // One of the proofs has been generated
  // Here, you can retrieve the proof manually and verify it
  // But note that the verification of the proofs is handled
  // automatically by the SDK
  console.log("Proof generated", proof)
  console.log("Verification key hash", vkeyHash)
  console.log("Version", version)
  console.log("Name", name)
})

// That's the callback you're looking for
onResult(
  ({ 
    uniqueIdentifier,
    verified,
    result,
  }: { 
    uniqueIdentifier: string
    verified: boolean
    result: QueryResult
  }) => {
    // All the proofs have been generated and the final result is available
    console.log("firstname", result.firstname.disclose.result)
    console.log("age over 18", result.age.gte.result)
    console.log("nationality in EU", result.nationality.in.result)
    console.log("nationality not from Scandinavia", result.nationality.out.result)
    // You can also retrieved what were the values originally requested
    console.log("age over", result.age.gte.expected)
    console.log("nationality in", result.nationality.in.expected)
    console.log("nationality not in", result.nationality.out.expected)
    // You can make sure the proof are valid by checking verified is set to true
    console.log("proofs are valid", verified)
    // You can also retrieve the unique identifier associated to this request
    // The assumption is that the unique identifier will be the same if coming
    // from the same ID for the same domain name and scope
    // So you can use it to identify if the user has already provided the proof
    // for this specific use case
    console.log("unique identifier", uniqueIdentifier)
  },
)

```

--------------------------------

### Use Exported Country Lists with ZKPassport SDK

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Utilize predefined country lists for filtering in ZKPassport requests. Ensure the ZKPassport SDK is imported.

```typescript
import {
  EU_COUNTRIES,
  EEA_COUNTRIES,
  SCHENGEN_COUNTRIES,
  ASEAN_COUNTRIES,
  MERCOSUR_COUNTRIES,
  SANCTIONED_COUNTRIES,
} from "@zkpassport/sdk"

const zkPassport = new ZKPassport("app.example.com")
const qb = await zkPassport.request({
  name: "Regional Access",
  logo: "https://example.com/logo.png",
  purpose: "Verify EEA residency, exclude sanctioned countries",
})

const { url } = qb
  .in("nationality", EEA_COUNTRIES)           // EU + Iceland, Liechtenstein, Norway
  .out("issuing_country", SANCTIONED_COUNTRIES)
  .gte("age", 18)
  .done()
```

--------------------------------

### validateCertificates

Source: https://github.com/zkpassport/zkpassport-packages/blob/main/packages/registry-sdk/README.md

Validates a list of certificates against a given root hash.

```APIDOC
## validateCertificates

### Description
Validates a provided list of certificates against a specified root hash using the ZKPassport registry's validation mechanism.

### Method
`client.validateCertificates(certificates: Array<any>, root: string): Promise<boolean>`

### Parameters
#### Request Body Parameters
- **certificates** (Array<any>) - Required - An array of certificates to validate.
- **root** (string) - Required - The root hash to validate the certificates against.
```

--------------------------------

### Session Management

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Manage active ZKPassport bridge sessions by canceling specific requests or clearing all active sessions.

```APIDOC
## `zkPassport.cancelRequest()` and `clearAllRequests()`

### Description
Cancel a specific pending request or all active bridge sessions, cleaning up WebSocket connections and state.

### Usage
```typescript
// Cancel a specific request
zkPassport.cancelRequest(requestId)

// Clear all active sessions
zkPassport.clearAllRequests()
```

### Parameters for `cancelRequest`
- **requestId** (string) - Required - The ID of the request to cancel.
```

--------------------------------

### Retrieve ZKPassport Request URL

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Use `getUrl(requestId)` to retrieve the deep link URL for a previously created request. This is useful for regenerating QR codes without needing to reconstruct the entire request configuration.

```typescript
import { ZKPassport } from "@zkpassport/sdk"

const zkPassport = new ZKPassport("app.example.com")
const qb = await zkPassport.request({
  name: "My App",
  logo: "https://example.com/logo.png",
  purpose: "Nationality check",
})
const { requestId } = qb.disclose("nationality").done()

// Later, regenerate the URL without rebuilding the request
const url = zkPassport.getUrl(requestId)
// "https://zkpassport.id/r?d=app.example.com&t=<bridgeId>&c=<base64config>&..."
console.log(url)
```

--------------------------------

### Exported Country Lists

Source: https://context7.com/zkpassport/zkpassport-packages/llms.txt

Predefined ISO 3166-1 alpha-3 country lists exported from `@zkpassport/sdk` for use with query methods.

```APIDOC
## Exported Country Lists

Predefined ISO 3166-1 alpha-3 country lists are exported directly from `@zkpassport/sdk` for convenience with `.in()` and `.out()` query methods.

```typescript
import {
  EU_COUNTRIES,
  EEA_COUNTRIES,
  SCHENGEN_COUNTRIES,
  ASEAN_COUNTRIES,
  MERCOSUR_COUNTRIES,
  SANCTIONED_COUNTRIES,
} from "@zkpassport/sdk"

const zkPassport = new ZKPassport("app.example.com")
const qb = await zkPassport.request({
  name: "Regional Access",
  logo: "https://example.com/logo.png",
  purpose: "Verify EEA residency, exclude sanctioned countries",
})

const { url } = qb
  .in("nationality", EEA_COUNTRIES)           // EU + Iceland, Liechtenstein, Norway
  .out("issuing_country", SANCTIONED_COUNTRIES)
  .gte("age", 18)
  .done()
```
```
Tokens:
Raw