zkPass Developer's Guide

TypeScript/Next.js/Linux

Quick start tutorial for the TypeScript/Next.js binding of the zkPass SDK

To install the zkpass-client-ts lib separately, please refer to this section Installing the zkpass-client-ts lib

System Requirements

  1. Ubuntu version 20 or higher, WSL (Windows Subsystem for Linux) is also supported.

  2. Node.js 18.17.0 or later.

  3. 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.

  1. Open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting "Run as administrator"

  2. Run the command below

wsl --install

  1. Restart your machine

  2. 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.

  1. Run the command below

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

  1. Restart your terminal session

Installing Node 18.17.0 and NPM via NVM

nvm install 18.17

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.

Running "Employee Onboarding" Demo Application

The demo application is an implementation of the "Employee Onboarding" use case. In this scenario, MyNamaste is the application representing the Data Holder or User client.

Overview

Please review zkPass key concepts to have better understanding of the use case.

Cloning Demo

To try our zkPass demo, you can follow these steps

  1. Clone demo repository

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

  1. Go to zkPass demo typescript directory (Let's assume this is our root directory for steps below)

cd zkpass-sdk/typescript/node-js

Running Issuer-Verifier

The Issuer-Verifier runs only as a server and doesn't have any user interface.

  1. From zkpass-sdk/typescript/node-js directory go to issuer-verifier directory

cd issuer-verifier/

  1. Install packages in issuer-verifier directory

npm install

  1. Run issuer-verifier

npm run dev

  1. Issuer-verifier is running on http://localhost:3001

Running "MyNamaste" Application

  1. From zkpass-sdk/typescript/node-js directory go to client directory

cd client/

  1. Install packages

npm install

  1. Run "MyNamaste" Application

npm run dev

  1. "MyNamaste" is running on http://localhost:3000

Testing the Demo (Single User Data)

Ensure that "MyNamaste" application & Issuer-Verifier are running.

In this demo, "MyNamaste" will request Data Verification Request (DVR) and User Data from Issuer-Verifier based on logged-in user. After the user verifies DVR and User Data, "MyNamaste" sends a request zkPass service to generate the proof. "MyNamaste" will then send the generated proof to Issuer-Verifier to verify.

  1. Open "MyNamaste" Application http://localhost:3000

  2. Login using username : John and password : John. Check available users if we want to try another user.

  1. Click button Start Employee Onboarding (Single User Data). "MyNamaste" will fetch user data and Data Verification Request (DVR) from issuer-verifier. You can also use the multiple user data and available scenarios

  1. Check the DVR data displayed on the page, click button Confirm and continue

  1. Check the User data displayed on the page, after that click Confirm and generate proof to start generating the proof. "MyNamaste" will sending request to zkPass service to generate proof

  1. "MyNamaste" encrypt User data and DVR data before sending a request to generate proof to zkPass service.

  2. After "MyNamaste" receives the proof from the zkPass service, "MyNamaste" will send the proof to the Issuer-Verifier for verification.

  3. If everything is working fine, John should get The blood test succeeded onboarding requirements. You can click the Back to Home button to go to step 3.

  1. If we want to simulate a failed onboarding case, we can use another user (e.g., Jane) in our demo.

    1. In the top right corner, click LOGOUT: JOHN

    2. Login using username : Jane and password : Jane

  2. Repeat the process from number 3 to 5.

  3. If everything is working fine, Jane should get The blood test failed onboarding requirements. You can click the Back to Home button to go to step 3.

Testing the Demo (Multiple User Data)

Same as the single user data scenario, perform the same step 1 and 2.

  1. Click button Start Employee Onboarding (Multiple User Data). "MyNamaste" will fetch user data and Data Verification Request (DVR) from issuer-verifier.

  1. Check the DVR data displayed on the page, click button Confirm and continue

  1. Check the User data displayed on the page, you can view both user data (we prepared 2 user data: blood test and KYC data). After that click Confirm and generate proof to start generating the proof. "MyNamaste" will sending request to zkPass service to generate proof

  1. "MyNamaste" encrypt User data and DVR data before sending a request to generate proof to zkPass service.

  2. After "MyNamaste" receives the proof from the zkPass service, "MyNamaste" will send the proof to the Issuer-Verifier for verification.

  3. If everything is working fine, John should get The blood test and kyc succeeded onboarding requirements.You can click the Back to Home button to go to step 3.

Onboarding Scenarios

Here are the onboarding scenarios:

  • Pass means the generate proof is succesful and verified

  • Not Pass means the proof is invalid or not verified because the person not met some criteria.

[Optional] Modifying the Demo

These steps are optional. You can proceed with them if you want to modify zkPass demo

Add new User

  1. You can add new user in issuer-verifier/public/verifier/users.json, for example you can add maya

{
...
    "maya": {
        "firstName": "Maya",
        "lastName": "Maya",
        "dateOfBirth": "1985-12-12"
    }
...
}

  1. After creating a new user named Maya, you need to add Maya's blood test. Add them in issuer-verifier/public/issuer/blood-tests.json

{
...
  "maya": {
      "testID": "SCREEN-7083-12345",
      "testName": "QualityHealth Comprehensive Screen",
      "testDate": "2023-08-27T14:00:00Z",
      "lab": {
        "name": "QualityHealth Labs",
        "ID": "QH801874",
        "address": "1234 Elm St, Oakland, USA"
      },
      "subject": {
        "firstName": "Maya",
        "lastName": "Maya",
        "dateOfBirth": "1985-12-12",
        "bloodType": "A+",
        "DNAInfo": {
          "markers": {
            "APOE": ["E3", "E3"],
            "BRCA1": "Normal",
            "MTHFR": ["C677T", "A1298C"]
          },
          "haplogroups": {
            "paternal": "R1b1",
            "maternal": "H1a1"
          }
        },
        "contact": {
          "email": "maya.test@gmail.com",
          "phone": "650-555-1234"
        },
        "address": {
          "street": "789 Oak Street",
          "city": "San Jose",
          "state": "CA",
          "zip": "95134"
        }
      },
      "measuredPanelsNgML": {
        "amphetamines": 0,
        "cocaine": 7,
        "opiates": 102,
        "benzodiazepines": 0
      }
  }
...
}

Modify DVR query

  1. We can also modify DVR query in issuer-verifier/src/app/verifier/dvrs/route.ts method _generateBloodTestQuery depends on which case we want to achieve.

  2. We can see the supported operators that we can use here.

Running Tests

Unit Test

Each of the client and issuer-verifier folders contains its own set of unit tests. The expected outcome is that all tests will pass successfully, achieving 100% code coverage across all components. This means that every function, line of code, and condition should be fully tested and verified.

Client Unit Test

  1. Go to client folder

    cd zkpass-sdk/typescript/node-js/client

  2. Install packages

    npm install

  3. Run the test

    npm run test

Issuer Verifier Unit Test

  1. Go to issuer-verifier folder

    cd zkpass-sdk/typescript/node-js/issuer-verifier

  2. Install packages

    npm install

  3. Run the test

    npm run test

End to End Test

The end-to-end test will cover multiple scenarios for the "Employee Onboarding" use case, using Playwright to execute the tests. Make sure you have already run the npm install command in both the client and issuer-verifier projects before executing the tests.

  1. Go to e2e-test directory on client folder

    cd zkpass-sdk/typescript/node-js/client/e2e-test

  2. Install packages

    npm install

  3. Run the test

    npm run test

When running the test, Playwright will automatically run the UI (client) and Issuer Verifier (issuer-verifier) applications. Note that for each test case below, Playwright will test on Chrome, Firefox, and Microsoft Edge.

  1. Authentication

    1. Login with valid credentials

    2. Login with invalid credentials

    3. Logout

  2. Login as John

    1. Testing Single User Data

    2. Testing Multiple User Data

  3. Login as Jane

    1. Testing Single User Data

    2. Testing Multiple User Data

Code Snippets

Please refer to Typescript/Node.js/Linux Code Snippets section.

PreviousQuick StartNextTypeScript/Node.js/Linux

Last updated