ZKPassport SDK

https://docs.zkpassport.id
Admin
ZKPassport SDK enables privacy-preserving identity verification using passports and ID cards with...
Tokens:29,573
Snippets:228
Trust Score:7.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Import ZKPassport SDK

Source: https://docs.zkpassport.id/getting-started/quick-start

Import the ZKPassport class into your project after installation. This is the only setup step needed.

```javascript
import { ZKPassport } from "@zkpassport/sdk";  

```

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

### Install ZKPassport SDK using npm

Source: https://docs.zkpassport.id/getting-started/quick-start

Install the ZKPassport SDK package using npm or any other JavaScript package manager.

```bash
npm install @zkpassport/sdk  

```

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

### Initiate Verification Request

Source: https://docs.zkpassport.id/api

Starts a new verification request with specified options. Use this to get the necessary data for the mobile app to generate a proof. Ensure logo URL is valid.

```typescript
async request(options: {
  name: string;
  logo: string;
  purpose: string;
  scope?: string;
  validity?: number;
  devMode?: boolean;
  cloudProverUrl?: string;
  bridgeUrl?: string;
}): Promise<QueryBuilder>
```

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

### Handle ZKPassport Proof Generation Event

Source: https://docs.zkpassport.id/getting-started/basic-usage

Implement the onGeneratingProof callback to handle the event when the user has accepted the request and the proof generation process has started. Use this to display a progress indicator to the user.

```javascript
// No parameters are passed to the callback
// You can use this to update your UI to show a progress indicator as now the proof is being generated
// Expect it to take up to 10 seconds to get the results back if the connection is decent
onGeneratingProof(() => {
  console.log("Generating proof");
});

```

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

### ZKPassport Contract Implementation

Source: https://docs.zkpassport.id/getting-started/onchain

Example implementation of a smart contract that uses ZKPassport for user registration and verification. It verifies proofs, checks scopes, age, nationality, and bound data.

```solidity
contract YourContract {
    IZKPassportVerifier public zkPassportVerifier;

    // Map users to their verified unique identifiers
    mapping(address => bytes32) public userIdentifiers;

    constructor(address _verifierAddress) {
        zkPassportVerifier = IZKPassportVerifier(_verifierAddress);
    }

    function register(ProofVerificationParams calldata params, bool isIDCard) public returns (bytes32) {
        // Verify the proof
        (bool verified, bytes32 uniqueIdentifier, IZKPassportHelper helper) = zkPassportVerifier.verify(params);
        require(verified, "Proof is invalid");

        // Check the proof was generated using your domain name (scope) and the subscope
        // you specified
        require(
          helper.verifyScopes(params.proofVerificationData.publicInputs, "your-domain.com", "my-scope"),
          "Invalid scope"
        );

        // Check if the user is at least 18 years old
        bool isAgeAboveOrEqual = helper.isAgeAboveOrEqual(
          18,
          params.committedInputs
        );

        // Get the disclosed data to retrieve the nationality
        DisclosedData memory disclosedData = helper.getDisclosedData(
          params.committedInputs,
          isIDCard
        );
        // Alpha 3 code of the nationality (e.g. FRA, USA, etc.)
        // Warning: as it is the raw MRZ bytes, Germany will be "D<<" and not "DEU"
        // Other countries follow the standard ISO 3166-1 alpha-3 code format.
        string memory nationality = disclosedData.nationality;

        // Use the getBoundData function to get the data bound to the proof
        BoundData memory boundData = helper.getBoundData(params.committedInputs);
        // Make sure the user's address is the one that is calling the contract
        require(boundData.senderAddress == msg.sender, "Not the expected sender");
        // Make sure the chain id is the same as the one you specified in the query builder
        require(boundData.chainId == block.chainid, "Invalid chain id");
        // You could also check the custom data if you bound any to the proof
        require(boundData.customData == "my-custom-data", "Invalid custom data");
        // If you didn't specify any custom data, make sure the string is empty
        // ...
        userIdentifiers[msg.sender] = uniqueIdentifier;
        return uniqueIdentifier;
    }
}
```

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

### Get Solidity Verifier Parameters

Source: https://docs.zkpassport.id/api

Generates the necessary parameters to call the Solidity verifier. Use `devMode: true` if verifying mock proofs.

```typescript
getSolidityVerifierParameters({
  proof,
  validityPeriodInSeconds,
  domain,
  scope,
  devMode,
}: {
  proof: ProofResult
  validityPeriodInSeconds?: number
  domain?: string
  scope?: string
  devMode?: boolean
}): SolidityVerifierParameters
```

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

### Get Solidity Verifier Details

Source: https://docs.zkpassport.id/api

Retrieves the address, function name, and ABI for the Solidity verifier contract. This is useful for on-chain verification.

```typescript
getSolidityVerifierDetails(): {
  address: `0x${string}`
  functionName: string
  abi: {
    type: "function" | "event" | "constructor"
    name: string
    inputs: { name: string; type: string; internalType: string }[]
    outputs: { name: string; type: string; internalType: string }[]
  }[]
}
```

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

### Get Request URL

Source: https://docs.zkpassport.id/api

Generates the URL for a specific request, which can be used for QR codes or direct links.

```typescript
getUrl(requestId: string): string
```

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

### Connect Frontend to Smart Contract with ZKPassport SDK

Source: https://docs.zkpassport.id/getting-started/onchain

Use this function to connect your frontend to your smart contract for on-chain verification. Ensure you have the necessary viem clients and wallet provider set up. Replace placeholders like YOUR_CONTRACT_ADDRESS and YOUR_CONTRACT_ABI with your actual contract details.

```typescript
import { ZKPassport } from "@zkpassport/sdk";  
import { createWalletClient, createPublicClient, http } from "viem";  
import { mainnet } from "viem/chains";  
import { custom } from "viem/wallet";  
  
async function verifyOnChain(proofResult, walletProvider, isIDCard) {  
  const zkPassport = new ZKPassport("your-domain.com");  
  
  // Get verification parameters  
  const verifierParams = zkPassport.getSolidityVerifierParameters({  
    proof: proofResult,  
    // Use the same scope as the one you specified with the request function  
    scope: "my-scope",  
    // Enable dev mode if you want to use mock passports, otherwise keep it false  
    devMode: false,  
  });  
  
  // Create wallet client  
  const walletClient = createWalletClient({  
    chain: mainnet,  
    transport: custom(walletProvider),  
  });  
  
  // Get the account  
  const [account] = await walletClient.getAddresses();  
  
  // Create a public client  
  const publicClient = createPublicClient({  
    chain: mainnet,  
    transport: http(),  
  });  
  
  // Call your contract with the verification parameters  
  const hash = await walletClient.writeContract({  
    address: YOUR_CONTRACT_ADDRESS,  
    abi: YOUR_CONTRACT_ABI,  
    functionName: "register",  
    args: [verifierParams, isIDCard],  
    account,  
  });  
  
  // Wait for the transaction  
  await publicClient.waitForTransactionReceipt({ hash });  
  
  console.log("Verification completed on-chain!");  
}  

```

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

### Initialize ZKPassport SDK with Domain

Source: https://docs.zkpassport.id/getting-started/basic-usage

Initialize the ZKPassport SDK with your domain. This is required for server-side or Node.js environments.

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

// Initialize ZKPassport with your domain
const zkPassport = new ZKPassport("your-domain.com");

```

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

### Initialize ZKPassport SDK

Source: https://docs.zkpassport.id/api

Creates a new instance of the ZKPassport SDK. The domain is optional and can be inferred in a browser environment.

```typescript
new ZKPassport(domain?)
```

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

### Node.js Express Server for ZKPassport Registration

Source: https://docs.zkpassport.id/examples/client-server

Implement a server to handle user registration with ZKPassport. This includes initializing the SDK, verifying proofs, and creating a user in your database. Ensure the ZKPassport SDK is initialized with the correct domain.

```javascript
const express = require("express");
const { ZKPassport } = require("@zkpassport/sdk");
const bodyParser = require("body-parser");
const { createUser } = require("./db"); // Your database logic

const app = express();
app.use(bodyParser.json());

app.post("/register", async (req, res) => {
  try {
    const { email, password, verification } = req.body;

    if (!verification || !verification.proofs || !verification.queryResult) {
      return res.status(400).json({
        success: false,
        error: "Missing ZKPassport verification data",
      });
    }

    // Initialize the ZKPassport SDK on the server
    // Note: This should be the same domain as the client-side implementation
    // and you cannot skip it unlike in the browser where it's automatically detected
    const zkPassport = new ZKPassport("your-domain.com");

    // Verify the proofs
    const { verified, queryResultErrors, uniqueIdentifier } = await zkPassport.verify({
      proofs: verification.proofs,
      queryResult: verification.queryResult,
    });

    if (!verified) {
      console.error("Verification failed:", queryResultErrors);
      return res.status(400).json({
        success: false,
        error: "Identity verification failed",
      });
    }

    if (!uniqueIdentifier) {
      return res.status(400).json({
        success: false,
        error: "Could not extract the unique identifier",
      });
    }

    // Extract any disclosed information
    const nationality = verification.queryResult.nationality?.disclose?.result;

    // Create a user in your database with the uniqueIdentifier
    const user = await createUser({
      email,
      password, // Remember to hash this password!
      id: uniqueIdentifier,
      nationality: nationality || null,
      // Add other registration fields as needed
    });

    return res.json({
      success: true,
      userId: user.id,
    });
  } catch (error) {
    console.error("Registration error:", error);
    res.status(500).json({
      success: false,
      error: "Server error during registration",
    });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

```

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

### Get Verifier Contract Details

Source: https://docs.zkpassport.id/getting-started/onchain

Retrieves the necessary details for interacting with the deployed ZKPassport verifier contract on EVM chains. The address is deterministic and consistent across supported networks.

```typescript
const {  
  // The address of the deployed verifier contract  
  // Since it's deterministic, it will be the same for all networks  
  address,  
  // The function name to call on the verifier contract  
  functionName,  
  // The ABI of the verifier contract  
  abi,  
} = zkPassport.getSolidityVerifierDetails();  

```

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

### Verify Numeric Field Within Range

Source: https://docs.zkpassport.id/api

Verifies if a numeric field falls within a specified range (inclusive start and end). Currently supported for age, birthdate, and expiry_date.

```typescript
range<T extends NumericalIDCredential>(
  key: T,
  start: IDCredentialValue<T>,
  end: IDCredentialValue<T>
): QueryBuilder
```

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

### IDCredentialValue Type

Source: https://docs.zkpassport.id/api

A generic type that maps credential types to their expected value types. For example, 'nationality' or 'issuing_country' map to CountryName or Alpha3Code, while 'birthdate' or 'expiry_date' map to Date.

```typescript
type IDCredentialValue<T> = T extends "nationality" | "issuing_country"
  ? CountryName | Alpha3Code
  : T extends "birthdate" | "expiry_date"
  ? Date
  : T extends "age"
  ? number
  : string;
```

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

### request

Source: https://docs.zkpassport.id/api

Initiates a new verification request, returning a QueryBuilder instance for constructing the verification query.

```APIDOC
## request

### Description
Initiates a new verification request.

### Method
`async request(options: {
  name: string;
  logo: string;
  purpose: string;
  scope?: string;
  validity?: number;
  devMode?: boolean;
  cloudProverUrl?: string;
  bridgeUrl?: string;
}): Promise<QueryBuilder>

### Parameters
#### Path Parameters
- **name** (string) - Required - Your application name
- **logo** (string) - Required - URL to your application's logo
- **purpose** (string) - Required - Description of why you're requesting verification
- **scope** (string) - Optional - Scope for the unique identifiers
- **validity** (number) - Optional - How many seconds ago the proof should have been generated
- **devMode** (boolean) - Optional - Whether to enable dev mode (defaults to false). Dev mode will accept mock proofs generated from the mock passports in the app.
- **cloudProverUrl** (string) - Optional - The url of the cloud prover to use for compressed proofs. Defaults to ZKPassport's Cloud Prover.
- **bridgeUrl** (string) - Optional - The url of the websocket to use to connect to the mobile app. Defaults to ZKPassport's Bridge.

### Returns
A `QueryBuilder` instance for building the verification query.
```

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

### Initialize ZKPassport SDK in Browser

Source: https://docs.zkpassport.id/getting-started/basic-usage

Initialize the ZKPassport SDK without a domain parameter when running in a browser. The SDK will automatically infer the domain from the window location.

```javascript
// The SDK will fill in your domain from you using the window location object behind the scenes
const zkPassport = new ZKPassport();

```

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

### clearAllRequests

Source: https://docs.zkpassport.id/api

Cancels all active requests and cleans up associated resources. This method closes all active WebSocket connections, clears all stored request data, removes all event handlers, and resets the SDK state. Use this method when you want to clean up all pending requests, for example when your application is shutting down or when you want to reset the SDK state.

```APIDOC
## clearAllRequests

### Description
Cancels all active requests and cleans up associated resources.

### Method
`clearAllRequests(): void`

### Details
* Closes all active WebSocket connections
* Clears all stored request data
* Removes all event handlers
* Resets the SDK state
```

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

### Handle Individual Proof Generation

Source: https://docs.zkpassport.id/getting-started/basic-usage

This callback is triggered when a single proof is generated for one of the verifications. It provides access to the proof, verification key hash, version, and name of the proof. You may need this to update your UI as multiple proofs are generated.

```typescript
onProofGenerated(({ proof, vkeyHash, version, name }: ProofResult) => {
  console.log("Proof generated", proof);
  console.log("Verification key hash", vkeyHash);
  console.log("Version", version);
  console.log("Name", name);
});
```

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

### ZKPassport Constructor

Source: https://docs.zkpassport.id/api

Creates a new instance of the ZKPassport SDK. The domain is optional and can be inferred in a browser environment.

```APIDOC
## constructor

### Description
Creates a new instance of the ZKPassport SDK.

### Parameters
#### Path Parameters
- **domain** (string) - Optional - Your application's domain. If not provided in a browser environment, it will be automatically inferred from the window location.
```

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

### Build ZKPassport Query with Conditions

Source: https://docs.zkpassport.id/getting-started/basic-usage

Build a query using the queryBuilder object to specify required attributes and conditions for identity verification. This includes disclosing attributes, verifying age, and checking nationality against specific country lists.

```javascript
// Build your query with the required attributes or conditions you want to verify
const {
  url,
  requestId,
  onRequestReceived,
  onGeneratingProof,
  onProofGenerated,
  onResult,
  onReject,
  onError,
} = queryBuilder
  // Disclose the user's firstname
  .disclose("firstname")
  // Verify the user's age is greater than or equal to 18
  .gte("age", 18)
  // Verify the user's nationality is in the European Union
  // EU_COUNTRIES is a constant exported by the SDK containing all the EU countries
  .in("nationality", EU_COUNTRIES)
  // Verify the user's nationality is not from a Scandinavian country
  // Note: Norway is not an EU country
  .out("nationality", ["Sweden", "Denmark"]) 
  // Finalize the query
  .done();

```

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

### Generate Verification Parameters for Onchain

Source: https://docs.zkpassport.id/getting-started/onchain

Prepares parameters required to verify a ZKPassport proof on an EVM chain. This function takes the proof result and scope, and optionally enables dev mode for mock passports.

```typescript
let proof: ProofResult;  
// Use the proofResult from the onProofGenerated callback to get the proof  
onProofGenerated((proofResult: ProofResult) => {  
  proof = proofResult;  
});  
  
onResult(  
  ({  
    uniqueIdentifier,  
    verified,  
    result,  
  }: {  
    uniqueIdentifier: string;  
    verified: boolean;  
    result: QueryResult;  
  }) => {  
    if (!verified) {  
      // If the proof is not verified, save yourself some gas and return straight away  
      console.log("Proof is not verified");  
      return;  
    }  
  
    // Get the verification parameters  
    const verifierParams = zkPassport.getSolidityVerifierParameters({  
      proof: proof,  
      // Use the same scope as the one you specified with the request function  
      scope: "my-scope",  
      // Enable dev mode if you want to use mock passports, otherwise keep it false  
      devMode: false,  
    });  
  
    // Get the wallet provider  
    const walletProvider = await getWalletProvider();  
  
    // Verify the proof on-chain  
    // The function is defined in the next steps below  
    await verifyOnChain(  
      verifierParams,  
      walletProvider,  
      // Use the document type to determine if the proof is for an ID card or passport  
      // Residence permit are essentially like ID cards as they follow the same structure  
      result.document_type.disclose.result !== "passport"  
    );  
  }  
);  

```

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

### IZKPassportHelper Interface

Source: https://docs.zkpassport.id/getting-started/onchain

Provides utility functions to verify proof details and retrieve disclosed information.

```APIDOC
## function verifyScopes(bytes32[] calldata publicInputs, string calldata domain, string calldata scope) external pure returns (bool)

### Description
Verifies that the proof was generated for the specified domain and scope.

### Method
`external pure`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **publicInputs** (bytes32[]) - The public inputs of the proof.
- **domain** (string) - The domain to check against. Must match the domain specified in the SDK.
- **scope** (string) - The scope to check against. Must match the scope specified in the request using the TypeScript SDK.

### Request Example
```json
{
  "publicInputs": ["0x..."],
  "domain": "example.com",
  "scope": "user_profile"
}
```

### Response
#### Success Response (200)
- **result** (bool) - True if the proof was generated for the given domain and scope, false otherwise.

#### Response Example
```json
{
  "result": true
}
```
```

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

### onGeneratingProof Event Handler

Source: https://docs.zkpassport.id/api

This handler is invoked when the user accepts the request and proof generation begins. Proof generation typically takes up to 10 seconds with a good connection.

```typescript
onGeneratingProof(callback: () => void): void

```

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

### done()

Source: https://docs.zkpassport.id/api

Finalizes the query and returns an object containing the URL to redirect users to the ZKPassport app, a unique requestId, and event handlers to track the verification progress.

```APIDOC
## done()

### Description
Finalizes the query and returns an object containing the URL to redirect users to the ZKPassport app, a unique requestId, and event handlers to track the verification progress.

### Returns
- `object` - An object containing:
  - `url` (string): URL to redirect users to the ZKPassport app.
  - `requestId` (string): Unique identifier for this request.
  - `onRequestReceived` (function): Callback for when the request is received.
  - `onGeneratingProof` (function): Callback for when proof generation starts.
  - `onProofGenerated` (function): Callback for when an individual proof is generated.
  - `onResult` (function): Callback for when all proofs are generated and verified.
  - `onReject` (function): Callback for when the user rejects the request.
  - `onError` (function): Callback for when an error occurs.
  - `onBridgeConnect` (function): Callback for when the bridge connects.
  - `isBridgeConnected` (function): Returns true if the bridge is connected.
  - `requestReceived` (function): Returns true if the request has been received.
```

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

### Event Handlers

Source: https://docs.zkpassport.id/api

The SDK provides several event handlers to track the progress of a verification request.

```APIDOC
## Event Handlers

### onRequestReceived

#### Description
Called when the user has scanned the QR code or clicked the link and sees the request popup on their mobile device. Use this to update your UI to show that the request has been received.

#### Signature
```
onRequestReceived(callback: () => void): void
```

### onGeneratingProof

#### Description
Called when the user has accepted the request and the proof generation has started. The proof generation typically takes up to 10 seconds with a good connection.

#### Signature
```
onGeneratingProof(callback: () => void): void
```

### onProofGenerated

#### Description
Called when an individual proof has been generated. Multiple proofs may be generated for a single request. The callback receives a `ProofResult` object.

#### Signature
```
onProofGenerated(callback: (result: ProofResult) => void): void
```

### onResult

#### Description
Called when all proofs have been generated and verified. This is the main callback you'll use to handle the verification results. The callback receives a response object.

#### Signature
```
onResult(callback: (response: {
  uniqueIdentifier: string | undefined;
  verified: boolean;
  result: QueryResult;
  queryResultErrors?: QueryResultErrors;
}) => void): void
```

### onReject

#### Description
Called when the user rejects the verification request.

#### Signature
```
onReject(callback: () => void): void
```

### onError

#### Description
Called if an error occurs during the verification process.

#### Signature
```
onError(callback: (error: string) => void): void
```

### onBridgeConnect

#### Description
Called when the bridge connects.

#### Signature
```
onBridgeConnect(callback: () => void): void
```
```

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

### getSolidityVerifierParameters

Source: https://docs.zkpassport.id/api

Generates the parameters required for calling the Solidity verifier.

```APIDOC
## getSolidityVerifierParameters

### Description
Returns the parameters needed to call the Solidity verifier.

### Method
`getSolidityVerifierParameters({
  proof,
  validityPeriodInSeconds,
  domain,
  scope,
  devMode,
}: {
  proof: ProofResult
  validityPeriodInSeconds?: number
  domain?: string
  scope?: string
  devMode?: boolean
}): SolidityVerifierParameters

### Parameters
#### Path Parameters
- **proof** (ProofResult) - Required - The proof to verify
- **validityPeriodInSeconds** (number) - Optional - The validity period of the proof in seconds
- **domain** (string) - Optional - The domain of the request
- **scope** (string) - Optional - The scope of the request
- **devMode** (boolean) - Optional - Whether to use dev mode (use it if you're verifying mock proofs)

### Returns
An object containing:
  * `version`: The version of the proof
  * `proofVerificationData`: The proof verification data (i.e. vkey hash, proof, public inputs)
  * `committedInputs`: The committed inputs to the proof
  * `serviceConfig`: The service configuration (i.e. validity period, domain, scope, dev mode)
```

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

### Bind Data to Proof

Source: https://docs.zkpassport.id/api

Binds data to the proof, with a total size limit of 500 bytes. Supported keys are user_address (raw bytes), chain (converted to chain ID), and custom_data (ASCII encoded text).

```typescript
bind(key: "user_address" | "chain" | "custom_data", value: string): QueryBuilder
```

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

### Request KYC Information with ZKPassport SDK

Source: https://docs.zkpassport.id/examples/kyc

Use this snippet to request and verify identity information for KYC purposes. It includes disclosing personal details, performing sanctions checks, and facial matching. The `onResult` callback handles the verification outcome.

```javascript
import { ZKPassport } from "@zkpassport/sdk";  
  
const zkPassport = new ZKPassport("your-domain.com");  
  
const queryBuilder = await zkPassport.request({
  name: "ZKPassport",
  logo: "https://zkpassport.id/logo.png",
  purpose: "Prove your identity",
  scope: "identity",
});  
  
const { url, onResult } = queryBuilder  
  .disclose("nationality")  
  .disclose("birthdate")  
  // Fullname includes middle names and secondary given names  
  // while disclosing firstname and lastname will not include them  
  .disclose("fullname")  
  // The expiry date is checked during the proof generation  
  // but in this context you may need to know when the ID will expire  
  .disclose("expiry_date")  
  // This is sensitive information, so be careful when handling it  
  .disclose("document_number")  
  // Check the user is not on any of the available sanctions lists (US, UK, EU, Switzerland)  
  .sanctions()  
  // Verify the person generating the proof is the one on the ID  
  .facematch("strict")  
  .done();  
  
onResult(({ verified, result }) => {  
  if (verified) {  
    const nationality = result.nationality.disclose.result;  
    const dateOfBirth = result.birthdate.disclose.result;  
    const fullname = result.fullname.disclose.result;  
    const expiryDate = result.expiry_date.disclose.result;  
    const documentNumber = result.document_number.disclose.result;  
    const faceMatchVerified = result.facematch.passed;  
    const sanctionsVerified = result.sanctions.passed;  
    if (!faceMatchVerified) {  
      console.log("FaceMatch verification failed");  
    }
    if (!sanctionsVerified) {  
      console.log("Sanctions check failed");  
    }
    console.log("User is verified", nationality, dateOfBirth, fullname, expiryDate, documentNumber);
  } else {  
    console.log("Verification failed");  
  }
});  
```

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

### Solidity Smart Contract Structures for ZKPassport

Source: https://docs.zkpassport.id/getting-started/onchain

Defines the necessary structs and interfaces for interacting with the ZKPassport verifier contract on-chain. Includes data structures for bound data, disclosed data, proof verification parameters, and the verifier and helper interfaces.

```solidity
pragma solidity ^0.8.21;  
  
/**  
 * @notice The data that can be bound to the proof  
 */  
struct BoundData {  
  // The address of the ID holder  
  address senderAddress;  
  // The chain id (block.chainid)  
  uint256 chainId;  
  // The custom data (encoded as ASCII string)  
  string customData;  
}  
  
/**  
 * @notice The data that can be disclosed by the proof  
 */  
struct DisclosedData {  
    // The name of the ID holder (includes the angular brackets from the MRZ)  
    string name;  
    // The issuing country of the ID  
    string issuingCountry;  
    // The nationality of the ID holder  
    string nationality;  
    // The gender of the ID holder  
    string gender;  
    // The birth date of the ID holder  
    string birthDate;  
    // The expiry date of the ID  
    string expiryDate;  
    // The document number of the ID  
    string documentNumber;  
    // The type of the document  
    string documentType;  
}  
  
// ProofVerificationParams  
// │  
// ├── bytes32 version                        // Version identifier of the verifier  
// │  
// ├── ProofVerificationData proofVerificationData  
// │   ├── bytes32 vkeyHash                   // Verification key hash  
// │   ├── bytes proof                        // The actual ZK proof  
// │   └── bytes32[] publicInputs             // Array of public inputs (7+ elements)  
// │       │                                  // Use PublicInputsCast.asStruct() for structured access:  
// │       ├── [0] certificate_registry_root  // Field - struct.certificateRegistryRoot  
// │       ├── [1] circuit_registry_root      // Field - struct.circuitRegistryRoot  
// │       ├── [2] current_date               // u64 - PublicInputsCast.getCurrentDate(struct)  
// │       ├── [3] service_scope              // Field - struct.serviceScope  
// │       ├── [4] service_subscope           // Field - struct.serviceSubscope  
// │       ├── [5:5+N] param_commitments      // Field[N] - PublicInputsCast.getParamCommitment(array, index)  
// │       ├── [5+N] nullifier_type           // u8 - PublicInputsCast.getNullifierType(array, paramCount)  
// │       └── [6+N] scoped_nullifier         // Field - PublicInputsCast.getScopedNullifier(array, paramCount)  
// │  
// ├── bytes committedInputs              // Preimages of param_commitments  
// │  
// └── ServiceConfig serviceConfig  
//     ├── uint256 validityPeriodInSeconds    // How long the proof is valid  
//     ├── string domain                      // Service domain  
//     ├── string scope                       // Service scope  
//     └── bool devMode                       // Development mode flag  
struct ProofVerificationParams {
  bytes32 version;
  ProofVerificationData proofVerificationData;
  bytes committedInputs;
  ServiceConfig serviceConfig;
}

struct ProofVerificationData {
  bytes32 vkeyHash;
  bytes proof;
  bytes32[] publicInputs;
}

struct ServiceConfig {
  uint256 validityPeriodInSeconds;
  string domain;
  string scope;
  bool devMode;
}

enum FaceMatchMode {
  NONE,
  REGULAR,
  STRICT
}

enum OS {
  ANY,
  IOS,
  ANDROID
}

/**  
 * @notice The public interface for the ZKPassport verifier contract  
 */  
interface IZKPassportVerifier {
  /**  
   * @notice Verifies a proof from ZKPassport  
   * @param params The proof verification parameters  
   * @return verified True if the proof is valid, false otherwise  
   * @return uniqueIdentifier The unique identifier associated to the identity document that generated the proof  
   * @return helper The ZKPassportHelper contract that can be used to verify the information or conditions that are checked by the proof  
   */  
  function verify(ProofVerificationParams calldata params) external returns (bool verified, bytes32 uniqueIdentifier, IZKPassportHelper helper);
}

/**  
 * @notice You can use to helper contract verifying the information or conditions that are checked by the proof  
 */  
interface IZKPassportHelper {
  /**  
   * @notice Verifies that the proof was generated for the given domain and scope  
   * @param publicInputs The public inputs of the proof  
   * @param domain The domain to check against (must match exactly the domain you specified in the SDK)  
   * @param scope The scope to check against (must match exactly the scope you specified in the request using the TypeScript SDK)  
   * @return True if the proof was generated for the given domain and scope, false otherwise  
   */  
  function verifyScopes(bytes32[] calldata publicInputs, string calldata domain, string calldata scope) external pure returns (bool);
  
  // ===== Helper functions to get the information revealed by the proof =====  
  
  // ===== Retrieve the disclosed data =====  
  
  /**  
   * @notice Gets the data disclosed by the proof  

```

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

### SolidityVerifierParameters Type

Source: https://docs.zkpassport.id/api

Defines the parameters required for verifying proofs using Solidity, including proof data and service configuration.

```APIDOC
## SolidityVerifierParameters

### Description
Defines the parameters required for verifying zero-knowledge proofs using Solidity smart contracts.

### Types
- **SolidityProofVerificationData**:
  - **vkeyHash** (string) - Hash of the verification key.
  - **proof** (string) - The generated zero-knowledge proof.
  - **publicInputs** (Array<string>) - Public inputs for verification.

- **SolidityServiceConfig**:
  - **validityPeriodInSeconds** (number) - The validity period of the service in seconds.
  - **domain** (string) - The domain of the service.
  - **scope** (string) - The scope of the service.
  - **devMode** (boolean) - Flag indicating if the service is in development mode.

### Main Type
- **SolidityVerifierParameters**:
  - **version** (string) - Version of the proof system.
  - **proofVerificationData** (SolidityProofVerificationData) - Data for proof verification.
  - **committedInputs** (string) - Committed inputs for the verification.
  - **serviceConfig** (SolidityServiceConfig) - Configuration for the verification service.
```

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

### Handle Final Verification Result

Source: https://docs.zkpassport.id/getting-started/basic-usage

This is the most important callback, triggered when all proofs are generated, verified by the SDK, and the final result is ready. It provides the unique identifier for the user, the overall verification status, and detailed results for each query. If `verified` is false, do not trust the results.

```typescript
onResult(
  ({
    uniqueIdentifier,
    verified,
    result,
  }: {
    uniqueIdentifier: string;
    verified: boolean;
    result: QueryResult;
  }) => {
    // Access the verification results
    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);

    // Access the original request parameters
    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);

    // Verify proof validity
    console.log("proofs are valid", verified);

    // Get unique identifier
    console.log("unique identifier", uniqueIdentifier);
  }
);
```

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

### Build Query for Onchain Verification

Source: https://docs.zkpassport.id/getting-started/onchain

Constructs a verification request using the ZKPassport SDK. Set the mode to 'compressed-evm' for onchain verification and define attributes to disclose or conditions to meet.

```typescript
import { ZKPassport } from "@zkpassport/sdk";  
  
const zkPassport = new ZKPassport("your-domain.com");  
  
// Create a request with your app details  
const queryBuilder = await zkPassport.request({
  name: "Your App Name",  
  // A path to your app's logo  
  logo: "https://your-domain.com/logo.png",  
  // A description of the purpose of the request  
  purpose: "Doing something",  
  // Optional scope for the user's unique identifier  
  scope: "my-scope",  
  // To verify proofs on EVM chains, you need to set the mode to "compressed-evm"  
  mode: "compressed-evm",  
});  
  
// Build your query with the required attributes or conditions you want to verify  
const {  
  url,  
  requestId,  
  onRequestReceived,  
  onGeneratingProof,  
  onProofGenerated,  
  onResult,  
  onReject,  
  onError,  
} = queryBuilder  
  // Disclose the user's nationality  
  .disclose("nationality")  
  // Disclose the user's document type  
  .disclose("document_type")  
  // Verify the user's age is greater than or equal to 18  
  .gte("age", 18)  
  // Bind the user's address to the proof  
  .bind("user_address", "0x1234567890123456789012345678901234567890")  
  // Bind to the chain where the proof will be verified  
  // This is strongly typed to the networks we support and plan to support in the near future  
  .bind("chain", "ethereum")  
  // Bind custom data to the proof  
  .bind("custom_data", "my-custom-data")  
  // Finalize the query  
  .done();  

```

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

### RequestOptions Type Definition

Source: https://docs.zkpassport.id/api

Defines the options for requesting a verification. Includes application name, logo, purpose, and optional parameters like proof mode, scope, and validity.

```typescript
// The type of proof to request
// fast: Fast proof generation, slightly less privacy in regards to the issuing country
// and not verifiable on-chain
// compressed: Compressed proof generation, full privacy in regards to the issuing country
// but not verifiable on EVM chains
// compressed-evm: Compressed proof generation, full privacy in regards to the issuing country
// and verifiable on EVM chains
type ProofMode = "fast" | "compressed" | "compressed-evm";

interface RequestOptions {
  name: string; // Your application name
  logo: string; // URL to your application's logo
  purpose: string; // Description of why you're requesting verification
  mode?: ProofMode; // Specify the type of proof to request
  scope?: string; // Optional scope for the unique identifier
  validity?: number; // (Optional) How many seconds ago the proof should have been generated
  // (defaults to 7 days in seconds)
  devMode?: boolean; // Optional flag to enable dev mode (defaults to false)
  topicOverride?: string; // Optional override for the request ID
  keyPairOverride?: {
    // Optional override for the ECDH key pair
    privateKey: Uint8Array;
    publicKey: Uint8Array;
  };
  // Advanced configuration: feel free to contact us if you need to use these options
  cloudProverUrl?: string; // Optional override for the cloud prover URL
  bridgeUrl?: string; // Optional override for the bridge URL
}

```

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

### Generate QR Code for ZKPassport URL

Source: https://docs.zkpassport.id/getting-started/basic-usage

Generate a QR code from the ZKPassport verification URL using the 'qrcode' library. This is useful for displaying the verification link on desktop or in print.

```javascript
import qrcode from "qrcode";

// This is assuming you have a canvas tag with id canvas on your HTML page
// i.e. <canvas id="canvas"></canvas>
qrcode.toCanvas(document.getElementById("canvas"), url);

```

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

### verify

Source: https://docs.zkpassport.id/api

Verifies proofs received from the mobile app against a query result. This can be used for server-side verification.

```APIDOC
## verify

### Description
Verifies the proofs received from the mobile app. You can store the proofs and query result and use this method to verify them later, for example server-side after running the SDK logic client-side.

### Method
`async verify({
  proofs,
  queryResult,
  scope,
  devMode,
  validity,
}: {
  proofs: Array<ProofResult>;
  queryResult: QueryResult;
  scope?: string;
  devMode?: boolean;
  validity?: number;
}): Promise<{ 
  uniqueIdentifier: string | undefined;
  verified: boolean;
  queryResultErrors?: QueryResultErrors;
}>  

### Parameters
#### Path Parameters
- **proofs** (Array<ProofResult>) - Required - The proofs to verify
- **queryResult** (QueryResult) - Required - The query result to verify against
- **scope** (string) - Optional - The scope used when requesting the proof
- **devMode** (boolean) - Optional - Whether to enable dev mode (defaults to false). Dev mode will accept mock proofs generated from the mock passports in the app.
- **validity** (number) - Optional - How many seconds ago the proof should have been generated

### Returns
An object containing:
  * `uniqueIdentifier`: The unique identifier associated with the user
  * `verified`: Whether the proofs were successfully verified
  * `queryResultErrors`: Detailed error information if verification fails (undefined if verification succeeds)
```

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

### ProofResult Interface

Source: https://docs.zkpassport.id/api

Represents the result of a generated zero-knowledge proof, containing the proof itself, verification data, and metadata.

```APIDOC
## ProofResult

### Description
Represents the result of a generated zero-knowledge proof.

### Fields
- **proof** (string) - The generated zero-knowledge proof.
- **vkeyHash** (string) - Hash of the verification key.
- **version** (string) - Version of the proof system.
- **name** (string) - Name of the proof.
- **index** (number) - Index of the proof (starting from 0).
- **total** (number) - Total number of proofs that should be sent back by the mobile app.
```

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

### Enable Dev Mode in ZKPassport SDK

Source: https://docs.zkpassport.id/getting-started/dev-mode

Set the `devMode` parameter to `true` when building a request with the `request` function to enable the SDK to validate proofs from mock passports. Without this, proofs from mock passports will be considered invalid.

```javascript
import { ZKPassport } from "@zkpassport/sdk";  
  
const zkPassport = new ZKPassport("your-domain.com");  
  
const request = await zkPassport.request({
  name: "Your App Name",  
  // A path to your app's logo  
  logo: "https://your-domain.com/logo.png",  
  // A description of the purpose of the request  
  purpose: "Your Purpose",  
  // Optional scope for the user's unique identifier  
  scope: "your-scope",  
  // Enable dev mode here  
  devMode: true,  
});  

```

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

### onResult Event Handler

Source: https://docs.zkpassport.id/api

This is the main callback used to handle verification results after all proofs have been generated and verified. It receives a response object containing verification status and details. If `verified` is `false`, do not trust any results.

```typescript
onResult(callback: (response: {
  uniqueIdentifier: string | undefined;
  verified: boolean;
  result: QueryResult;
  queryResultErrors?: QueryResultErrors;
}) => void): void

```

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

### Verify Proofs

Source: https://docs.zkpassport.id/api

Verifies proofs received from the mobile app against a query result. This method can be used server-side after client-side SDK logic. Ensure scope and devMode match the request.

```typescript
async verify({
  proofs,
  queryResult,
  scope,
  devMode,
  validity,
}: {
  proofs: Array<ProofResult>;
  queryResult: QueryResult;
  scope?: string;
  devMode?: boolean;
  validity?: number;
}): Promise<{ 
  uniqueIdentifier: string | undefined;
  verified: boolean;
  queryResultErrors?: QueryResultErrors;
}>
```

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

### getBoundData

Source: https://docs.zkpassport.id/getting-started/onchain

Retrieves data that has been bound to a specific proof.

```APIDOC
## getBoundData

### Description
Retrieves data that has been bound to a specific proof. This is useful for accessing associated information linked to a verified identity.

### Method
External Pure Function

### Parameters
#### Path Parameters
- **committedInputs** (bytes calldata) - The committed inputs representing the proof.

### Returns
- **boundData** (BoundData memory) - The memory object containing the bound data.
```

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

### getSolidityVerifierDetails

Source: https://docs.zkpassport.id/api

Retrieves the necessary details to interact with the Solidity verifier contract.

```APIDOC
## getSolidityVerifierDetails

### Description
Returns the details of the Solidity verifier.

### Method
`getSolidityVerifierDetails(): {
  address: `0x${string}`
  functionName: string
  abi: {
    type: "function" | "event" | "constructor"
    name: string
    inputs: { name: string; type: string; internalType: string }[]
    outputs: { name: string; type: string; internalType: string }[]
  }[]
}

### Returns
An object containing:
  * `address`: The address of the verifier (same for all networks)
  * `functionName`: The name of the function to call on the verifier
  * `abi`: The ABI of the verifier
```

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

### Check Residency in a Specific Country (France)

Source: https://docs.zkpassport.id/examples/residency

Use this snippet to verify if a user is a resident of a specific country, like France, by checking their electronic residence permit. Ensure the ZKPassport SDK is imported and initialized.

```typescript
import { ZKPassport } from "@zkpassport/sdk";  
  
const zkPassport = new ZKPassport("your-domain.com");  
  
const queryBuilder = await zkPassport.request({
  name: "ZKPassport",
  logo: "https://zkpassport.id/logo.png",
  purpose: "Prove you are resident in France",
  scope: "france-resident",
});  
  
const { url, onResult } = queryBuilder  
  .eq("document_type", "residence_permit")  
  .eq("issuing_country", "France")  
  .done();  
  
onResult(({ verified, result }) => {
  if (verified) {
    const isResidentInFrance = result.document_type.eq.result && result.issuing_country.eq.result;
    console.log("User is resident in France", isResidentInFrance);
  } else {
    console.log("Verification failed");
  }
});

```
Tokens:
Raw