1 of 4

Typescript

This section demonstrates how to use the DVR module client SDK to:

Generate a DVR token.
Generate a User Data token.
Generate a zkPass proof.
Verify a zkPass proof.

Running Code

To install the Dvr Module Client lib separately, please refer to this section Installing the Dvr Module Client lib

System Requirements

Ubuntu version 20 or higher, WSL (Windows Subsystem for Linux) is also supported.
Node.js 18.17.0 or later.
Git

Make sure the VPN is off

Installing WSL for Windows users

This command will enable the necessary features to run WSL and install the Ubuntu distribution of Linux.

If your underlying system, like Ubuntu, is already Linux-based, you can skip this step.

If your Windows version is below Windows 10 2004, please refer to this documentation instead.

Open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting "Run as administrator"
Run the command below

wsl --install

Restart your machine
Once you have installed WSL, you will need to create a user account and password for your newly installed Linux distribution.

The above command only works if WSL is not installed at all, if you run wsl --install and see the WSL help text, please try running wsl --list --online to see a list of available distros and run wsl --install -d <DistroName> to install a distro. To uninstall WSL, see Uninstall legacy version of WSL or unregister or uninstall a Linux distribution.

If you have installed WSL before, you can login using the command wsl

For a complete WSL installation guide, refer to this documentation.

Installing Node.js 18.17.0 via NVM

Installing NVM

nvm allows you to quickly install and use different versions of node via the command line.

Run the command below

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

Restart your terminal session

Installing Node 18.17.0 and NPM via NVM

nvm install 18.17.0

To check whether Node has been installed properly, run the commands below:

node -v
npm -v

Complete NVM documentation can be found here.

Installing Git

sudo apt update
sudo apt install git

To check whether Node has been installed properly, run the commands below:

git --version

Complete Git documentation can be found here.

Installing the SDK

If you wish to explore our demo application, feel free to skip this installation step, as it has already been completed in the demo application.

If you want to use our zkpass-client-ts library on your own project / outside the demo application, you can follow this step

Set the npm registry configuration to gdp-labs registry.

npm config set @zkpass:registry=https://us-west1-npm.pkg.dev/gdp-labs/gdplabs-npm-public/

Install the zkpass-client library for typescript

npm install @zkpass/dvr-client-ts

For NextJS projects with App Routing, several configurations have to be made in next.config.js file:

next.config.js

const nextConfig = {
  ...,
  experimental: {
    ...,
    esmExternals: "loose", // Enable ESM imports
    serverComponentsExternalPackages: ["@zkpass/dvr-client-ts"], // Exclude SDK from bundling, to enable reading binary file
  },
};

module.exports = nextConfig;

The serverComponentsExternalPackages configuration ensures that the package @zkpass/dvr-client-ts is excluded from NextJS' bundling and compilation process, allowing it to be imported directly from node_modules. As a result, remember to include the node_modules directory in your production build. See NextJS Deployment Guide.

Running CLI Demo

The demo application will run in a CLI and requires 2 parameters: DVR and user data. Please review zkPass key concepts to have better understanding of the use case.

Cloning Demo

To try our Typescript CLI demo, you can follow these steps

Clone demo repository

git clone https://github.com/gl-zkPass/zkpass-sdk.git

Go to Typescript CLI demo directory (Let's assume this is our root directory for steps below)

cd zkpass-sdk/typescript/

Running Demo

Install packages

npm install

Run Dewi demo

It will run the demo using predefined user data and DVR for Dewi. The expected query result is "false".

npm run demo-dewi

Expected result :

...
...
#### starting zkpass proof verification...
#### verification completed [time=118ms]
the query result is false

Run Ramana demo

It will run the demo using predefined user data and DVR for Ramana. The expected query result is "true".

npm run demo-ramana

Expected result :

...
...
#### starting zkpass proof verification...
#### verification completed [time=60ms]
the query result is true

Run Jane demo

It will run the demo using predefined user data and DVR for Jane. The expected query result is "true".

npm run demo-jane

Expected result :

...
...
#### starting zkpass proof verification...
#### verification completed [time=46ms]
the query result is true

Run demo with custom data

You can run the demo using custom data. Examples for user data and DVR can be found in rust/test/data.

Example running demo using custom data :

npm run demo ../rust/test/data/basic-data.json ../rust/test/data/basic-dvr.json

Expected result :

...
...
#### starting zkpass proof verification...
#### verification completed [time=51ms]
the query result is true

Run demo with multiple user data

You can also run the demo using multiple user data. Examples for multiple user data and DVR can be found in typescript/test/data/multiple.

Example running demo using multiple data:

npm run demo-multi

Code Snippet

This section describes how we use the zkPass SDK in our demo code

Generate Proof

This code snippet generates a zkPass proof. It requires 3 parameters:

SERVICE_URL : you can use https://playground-zkpass.ssi.id , or use your own endpoint if you deploy zkPass on your own server.
API_KEY & API_SECRET: Get yours at https://portal.ssi.id
userDataToken : check section for more details.
dvrToken : check section for more details.

Verify Proof

This code snippet verifies a zkPass proof token. Components :

expectedMetadata : this is the expected metadata of the dvr.
dvrPayload: the dvr payload extracted from Dvr token.

Generate User Data Token

This code snippet generate user data token. Components :

signingKey : a private key used to sign user data.
data : user data in JSON format.
verifyingKey : a public key to verify that user data token.

Generate DVR Token

This code snippet generate DVR token. Components :

signingKey : a private key used to sign dvr.
dvrData : Dvr data to sign.

Directory Structure

Here's the directory structure for Tyepscript SDK tutorial.

├── src
│    ├── libs
│    │    ├── Holder.ts
│    │    ├── Issuer.ts
│    │    └── Verifier.ts
│    └── utils
│         ├── constants.ts
│         ├── dvrTable.ts
│         └── helper.ts
├── index.ts
├── MyHolder.ts
├── MyIssuer.ts
└── MyVerifier.ts

Components :

MyHoder, MyIssuer, and MyVerifier provide an overview of the process.
The Libs folder contains the detailed implementation of each actor.
The Utils folder includes miscellaneous functions.

Code Snippet

This section describes how we use the zkPass SDK in our demo code

Generate Proof

This code snippet generates a zkPass proof. It requires 3 parameters:

SERVICE_URL : you can use https://playground-zkpass.ssi.id , or use your own endpoint if you deploy zkPass on your own server.
API_KEY & API_SECRET: Get yours at https://portal.ssi.id
userDataToken : check section for more details.
dvrToken : check section for more details.

Verify Proof

import { DvrModuleClient, extractPayload } from "@zkpass/dvr-client-ts";

const dvrPayload = extractPayload(dvrToken);
...

// Step 1: Instantiate the zkPassClient object.
const dvrModuleClient = new DvrModuleClient({
      baseUrl: ZKPASS_SERVICE_URL,
      apiKey: API_KEY,
      secretApiKey: API_SECRET,
    });

// Step 2: Create the expected metadata
const expectedMetadata = {
      dvr: JSON.stringify(dvrPayload),
      ttl: EXPECTED_DVR_TTL,
      user_data_verifying_keys: userDataVerifyingKeys,
    };

// Step 3: Call zkPassClient.verifyZkPassProof to verify the proof.
const proofOutput = dvrModuleClient.callDvrVerifyZkPassProof(
      ZKPASS_ZKVM,
      zkPassProofToken,
      expectedMetadata
    );

This code snippet verifies a zkPass proof token. Components :

zkPassProofToken : check section for more details.
expectedMetadata : this is the expected metadata of the dvr.
dvrPayload: the dvr payload extracted from Dvr token.

Generate User Data Token

import { DvrModuleClient } from "@zkpass/dvr-client-ts";

...

// Step 1: Instantiate DvrModuleClient
const dvrModuleClient = new DvrModuleClient({
      baseUrl: SERVICE_URL,
      apiKey: API_KEY,
      secretApiKey: API_SECRET,
    });
//
// Step 2: Call the DVR module client's callDvrGenerateUserDataToken
//         This is to digitally-sign the user data.
const userDataToken = dvrModuleClient.callDvrGenerateUserDataToken(
      signingKey,
      JSON.stringify(data),
      verifyingKey
    );

This code snippet generate user data token. Components :

signingKey : a private key used to sign user data.
data : user data in JSON format.
verifyingKey : a public key to verify that user data token.

Generate DVR Token

import { DvrModuleClient } from "@zkpass/dvr-client-ts";

...

// Step 1: Initiate DvrModuleClient
const dvrModuleClient = new DvrModuleClient({
      baseUrl: SERVICE_URL,
      apiKey: API_KEY,
      secretApiKey: API_SECRET,
    });

// Step 2: Generate Dvr query token
const dvrToken = dvrModuleClient.callDvrGenerateQueryToken(
      signingKey,
      dvrData
    );

This code snippet generate DVR token. Components :

signingKey : a private key used to sign dvr.
dvrData : Dvr data to sign.

Running Code

To install the Dvr Module Client lib separately, please refer to this section Installing the Dvr Module Client lib

System Requirements

Ubuntu version 20 or higher, WSL (Windows Subsystem for Linux) is also supported.
Node.js 18.17.0 or later.
Git

Make sure the VPN is off

Installing WSL for Windows users

This command will enable the necessary features to run WSL and install the Ubuntu distribution of Linux.

If your underlying system, like Ubuntu, is already Linux-based, you can skip this step.

If your Windows version is below Windows 10 2004, please refer to this documentation instead.

Open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting "Run as administrator"
Run the command below

wsl --install

Restart your machine
Once you have installed WSL, you will need to create a user account and password for your newly installed Linux distribution.

If you have installed WSL before, you can login using the command wsl

For a complete WSL installation guide, refer to this documentation.

Installing Node.js 18.17.0 via NVM

Installing NVM

nvm allows you to quickly install and use different versions of node via the command line.

Run the command below

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

Restart your terminal session

Installing Node 18.17.0 and NPM via NVM

nvm install 18.17.0

To check whether Node has been installed properly, run the commands below:

node -v
npm -v

Complete NVM documentation can be found here.

Installing Git

sudo apt update
sudo apt install git

To check whether Node has been installed properly, run the commands below:

git --version

Complete Git documentation can be found here.

Installing the SDK

If you wish to explore our demo application, feel free to skip this installation step, as it has already been completed in the demo application.

If you want to use our zkpass-client-ts library on your own project / outside the demo application, you can follow this step

Set the npm registry configuration to gdp-labs registry.

npm config set @zkpass:registry=https://us-west1-npm.pkg.dev/gdp-labs/gdplabs-npm-public/

Install the zkpass-client library for typescript

npm install @zkpass/dvr-client-ts

For NextJS projects with App Routing, several configurations have to be made in next.config.js file:

next.config.js

const nextConfig = {
  ...,
  experimental: {
    ...,
    esmExternals: "loose", // Enable ESM imports
    serverComponentsExternalPackages: ["@zkpass/dvr-client-ts"], // Exclude SDK from bundling, to enable reading binary file
  },
};

module.exports = nextConfig;

Running CLI Demo

The demo application will run in a CLI and requires 2 parameters: DVR and user data. Please review zkPass key concepts to have better understanding of the use case.

Cloning Demo

To try our Typescript CLI demo, you can follow these steps

Clone demo repository

git clone https://github.com/gl-zkPass/zkpass-sdk.git

Go to Typescript CLI demo directory (Let's assume this is our root directory for steps below)

cd zkpass-sdk/typescript/

Running Demo

Install packages

npm install

Run Dewi demo

It will run the demo using predefined user data and DVR for Dewi. The expected query result is "false".

npm run demo-dewi

Expected result :

...
...
#### starting zkpass proof verification...
#### verification completed [time=118ms]
the query result is false

Run Ramana demo

It will run the demo using predefined user data and DVR for Ramana. The expected query result is "true".

npm run demo-ramana

Expected result :

...
...
#### starting zkpass proof verification...
#### verification completed [time=60ms]
the query result is true

Run Jane demo

It will run the demo using predefined user data and DVR for Jane. The expected query result is "true".

npm run demo-jane

Expected result :

...
...
#### starting zkpass proof verification...
#### verification completed [time=46ms]
the query result is true

Run demo with custom data

You can run the demo using custom data. Examples for user data and DVR can be found in rust/test/data.

Example running demo using custom data :

npm run demo ../rust/test/data/basic-data.json ../rust/test/data/basic-dvr.json

Expected result :

...
...
#### starting zkpass proof verification...
#### verification completed [time=51ms]
the query result is true

Run demo with multiple user data

You can also run the demo using multiple user data. Examples for multiple user data and DVR can be found in typescript/test/data/multiple.

Example running demo using multiple data:

npm run demo-multi