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
Ubuntu version 20 or higher, WSL (Windows Subsystem for Linux) is also supported.
Node.js 18.17.0 or later.
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
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
Restart your terminal session
Installing Node 18.17.0 and NPM via NVM
To check whether Node has been installed properly, run the commands below:
Complete NVM documentation can be found here.
Installing Git
To check whether Node has been installed properly, run the commands below:
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
Clone demo repository
Go to zkPass demo typescript directory (Let's assume this is our root directory for steps below)
Running Issuer-Verifier
The Issuer-Verifier runs only as a server and doesn't have any user interface.
From
zkpass-sdk/typescript/node-js
directory go toissuer-verifier
directory
Install packages in
issuer-verifier
directory
Run issuer-verifier
Issuer-verifier is running on http://localhost:3001
Running "MyNamaste" Application
From
zkpass-sdk/typescript/node-js
directory go toclient
directory
Install packages
Run "MyNamaste" Application
"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.
Open "MyNamaste" Application http://localhost:3000
Login using
username : John
andpassword : John
. Check available users if we want to try another user.
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
Check the DVR data displayed on the page, click button
Confirm and continue
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
"MyNamaste" encrypt User data and DVR data before sending a request to generate proof to zkPass service.
After "MyNamaste" receives the proof from the zkPass service, "MyNamaste" will send the proof to the Issuer-Verifier for verification.
If everything is working fine, John should get
The blood test succeeded onboarding requirements
. You can click theBack to Home
button to go to step 3.
If we want to simulate a failed onboarding case, we can use another user (e.g., Jane) in our demo.
In the top right corner, click
LOGOUT: JOHN
Login using
username : Jane
andpassword : Jane
Repeat the process from number 3 to 5.
If everything is working fine, Jane should get
The blood test failed onboarding requirements
. You can click theBack 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.
Click button
Start Employee Onboarding (Multiple User Data)
. "MyNamaste" will fetch user data and Data Verification Request (DVR) from issuer-verifier.
Check the DVR data displayed on the page, click button
Confirm and continue
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
"MyNamaste" encrypt User data and DVR data before sending a request to generate proof to zkPass service.
After "MyNamaste" receives the proof from the zkPass service, "MyNamaste" will send the proof to the Issuer-Verifier for verification.
If everything is working fine, John should get
The blood test and kyc succeeded onboarding requirements
.You can click theBack 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
You can add new user in
issuer-verifier/public/verifier/users.json
, for example you can addmaya
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
Modify DVR query
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.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
Go to client folder
Install packages
Run the test
Issuer Verifier Unit Test
Go to issuer-verifier folder
Install packages
Run the 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.
Go to e2e-test directory on client folder
Install packages
Run the 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.
Authentication
Login with valid credentials
Login with invalid credentials
Logout
Login as John
Testing Single User Data
Testing Multiple User Data
Login as Jane
Testing Single User Data
Testing Multiple User Data
Code Snippets
Please refer to Typescript/Node.js/Linux Code Snippets section.
Last updated