Quick start tutorial for installing the Rust/Linux binding of the zkpass-client library, and building and running the sample application.
Ubuntu version 20 or higher WSL (Windows Subsystem for Linux) is also supported. Other similar Linux distros should also work.
For WSL installation guide, read here.
Some APT package dependencies Run the following to install the required packages:
Rust compiler toolchain Follow this 2-step instruction to install the Rust toolchain.
Follow these steps to install the zkPass SDK and to run the demo application.
For the purposes of this guide, the zkpass-sdk repository is cloned under the home directory of the current user, retaining its default name. This places the root directory for the zkpass-sdk repository at ~/zkpass-sdk. As a result, the directory for the Rust/Linux binding of the SDK is set at ~/zkpass-sdk/rust.
Should you choose to clone the zkpass-sdk repository into a different location, ensure that you adjust any referenced paths in the instructions to match your chosen directory structure.
Clone the zkpass-sdk repo
Enter zkpass-sdk/rust Directory
From the zkpass-sdk/rust directory, execute test.sh script to build the SDK and run the demo application:
The correct output of zkpass-demo should look like the following:
This error is indicated by the error message "reqwest::Error ... source: TimedOut".
This could happen when the demo runs and fails to fetch several keys needed. Here are several solutions:
Make sure you have a stable internet connection when running the script
Turn off any of your VPN and try again
This error is indicated by the error message "libr0_zkpass_query.so: cannot open shared object file: No such file or directory".
This may be caused by missing or corrupt .so files after executing cargo build -r command in the test.sh script. Several solutions:
Make sure you have a stable internet connection when running the script
Turn off any of your VPN and try again
Download .so file manually
Downloadlibsp1_zkpass_query.so and libr0_zkpass_query.so file from the website.
Move these files to zkpass-sdk/rust/lib folder
Run the test.sh script, error should be resolved
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
Ubuntu version 20 or higher, WSL (Windows Subsystem for Linux) is also supported.
or later.
Make sure the VPN is off
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 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 or .
If you have installed WSL before, you can login using the command wsl
nvm allows you to quickly install and use different versions of node via the command line.
Run the command below
Restart your terminal session
To check whether Node has been installed properly, run the commands below:
To check whether Node has been installed properly, run the commands below:
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.
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)
The Issuer-Verifier runs only as a server and doesn't have any user interface.
From zkpass-sdk/typescript/node-js directory go to issuer-verifier directory
Install packages in issuer-verifier directory
Run issuer-verifier
From zkpass-sdk/typescript/node-js directory go to client directory
Install packages
Run "MyNamaste" Application
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.
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 the Back 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 and password : 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 the Back to Home button to go to step 3.
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 the Back to Home button to go to step 3.
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.
These steps are optional. You can proceed with them if you want to modify zkPass demo
You can add new user in issuer-verifier/public/verifier/users.json, for example you can add maya
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
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.
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.
Go to client folder
Install packages
Run the test
Go to issuer-verifier folder
Install packages
Run the test
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
Quick start tutorial for the TypeScript/Node.js binding of the zkPass SDK
To install the zkpass-client-ts lib separately, please refer to this section
Ubuntu version 20 or higher, WSL (Windows Subsystem for Linux) is also supported.
or later.
Make sure the VPN is off
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 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 or .
If you have installed WSL before, you can login using the command wsl
nvm allows you to quickly install and use different versions of node via the command line.
Run the command below
Restart your terminal session
To check whether Node has been installed properly, run the commands below:
To check whether Node has been installed properly, run the commands below:
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.
Install the zkpass-client library for typescript
For NextJS projects with App Routing, several configurations have to be made in next.config.js file:
To try our Typescript CLI demo, you can follow these steps
Clone demo repository
Go to Typescript CLI demo directory (Let's assume this is our root directory for steps below)
Install packages
Run Dewi demo
It will run the demo using predefined user data and DVR for Dewi. The expected query result is "false".
Expected result :
Run Ramana demo
It will run the demo using predefined user data and DVR for Ramana. The expected query result is "true".
Expected result :
Run Jane demo
It will run the demo using predefined user data and DVR for Jane. The expected query result is "true".
Expected result :
Run demo with custom data
You can run the demo using custom data. Examples for user data and DVR can be found in typescript/node-js/cli/test-data.
Example running demo using custom data :
Expected result :
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/node-js/cli/test-data/multiple.
Example running demo using multiple data:
The integration test will run all available demo in package.json script using CLI.
Go to Typescript CLI demo directory
Install packages
Run the tests
The test will run all demo tests one by one and expect every test result is passed. List of Tests:
demo.test.ts
demo-basic.test.ts
demo-basic-false.test.ts
demo-dewi.test.ts
demo-ramana.test.ts
demo-jane.test.ts
demo-multi.test.ts
This section describes how we use the zkPass SDK in our demo code
This code snippet generates a zkPass proof. It requires 3 parameters:
zkPassServiceURL : you can use https://playground-zkpass.ssi.id/proof , or use your own endpoint if you deploy zkPass on your own server.
This code snippet verifies a zkPass proof token. It requires 2 parameters:
This code snippet generate user data token. It requires 3 parameters:
PRIVATE_KEY : a private key used to sign user data.
userData : user data in JSON format.
PUBLIC_KEY_JWKS : a public key JWKS used by zkPass to verify that user data token is not tampered during transport.
This code snippet generate DVR token. It has 2 steps, generate DVR and sign DVR.
Generate DVR requires 7 parameters:
zkvm : Your choice of zkvm (currently available zkvm = r0)
dvr_title : title of your DVR.
dvr_id : ID of your DVR. When the verifier issues a DVR, they will save it. When the verifier verifies the zkPassProofToken, they will check whether the zkPassProofToken was generated using the DVR issued by them.
query_engine_ver : query engine version of the SDK you currently use.
query_method_ver : query method version of the SDK you currently use.
user_data_url : this parameter is not used by zkPass when generating proof. However, it can be utilized by the holder in scenarios where they obtain the DVR but do not have user data yet. The holder can retrieve user data from this URL.
user_data_verifying_key : a public key JWKS used by zkPass to verify that user data token is not tampered during transport.
dvr_verifying_key : a public key JWKS used by zkPass to verify that data verification request is not tampered during transport.
Sign DVR requires 2 parameters:
PRIVATE_KEY : a private key used to sign user data.
PUBLIC_KEY_JWKS : a public key JWKS used by zkPass to verify that dvr token is not tampered during transport.
For a complete WSL installation guide, refer to .
Complete NVM documentation can be found .
Complete Git documentation can be found .
Please review to have better understanding of the use case.
Issuer-verifier is running on
"MyNamaste" is running on
Open "MyNamaste" Application
Login using username : John and password : John. Check if we want to try another user.
Same as the scenario, perform the same step 1 and 2.
| Name | Single User Data | Multiple User Data |
|---|
We can see the supported operators that we can use .
The end-to-end test will cover multiple scenarios for the "Employee Onboarding" use case, using 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.
Please refer to section.
For a complete WSL installation guide, refer to .
Complete NVM documentation can be found .
Complete Git documentation can be found .
The serverComponentsExternalPackages configuration ensures that the package @didpass/zkpass-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 .
The demo application will run in a CLI and requires 2 parameters: DVR and user data. Please review to have better understanding of the use case.
userDataToken : check section for more details.
dvrToken : check section for more details.
| Name | Reference |
|---|
zkPassProofToken : check section for more details.
proofMetadataValidator : this is a Class that implements , it's up to verifier to verify metadata of zkpassProofToken.
| Name | Reference |
|---|
| Name | Reference |
|---|
query : queryObject is a , you need to make them into a string
| Name | Reference |
|---|
John | Pass | Pass |
Jake | Pass | Not pass (mismatch the |
Jane | Not pass (high value on cocaine) | Not pass (high value on cocaine) |
Rob | Pass | Not pass (mismatch |
Kyle | Not pass (high value on cocaine) | Not pass (high value on cocaine an mismatch |
The zkPass Software Development Kit (SDK) consists of the following components:
Client Libraries
At the heart of the zkPass SDK is the client library calledzkpass-client. There are three versions of the client library for supporting different language/platform configurations, but basically, they all work the same way. These libraries are essential for participants in the zkPass ecosystem. They simplify and streamline various processes, including the digital signing and verification of data, the generation of proofs, and the validation of these proofs. By using these libraries, developers can efficiently integrate zkPass functionalities into their applications, ensuring secure and reliable data handling.
Developer Tool The SDK includes a convenient Command-Line Interface (CLI) tool known as 'zkpass-query-tool'. This tool is specifically designed to assist developers in learning how to craft zkPass queries effectively. It's an invaluable resource for testing and refining query scripts, making the learning curve smoother for those new to writing zkPass queries.
Sample Demo Applications To further aid in understanding and implementation, the zkPass SDK provides a range of sample demo applications. These applications serve as practical examples, showcasing the coding practices and steps involved in integrating apps with the zkPass Service. They are invaluable for developers looking to get a hands-on feel of how zkPass works in real-world scenarios.
Documentation The Developer’s Guide (this book) is an integral component of the SDK. It serves as a comprehensive source of information, covering everything from basic setup to advanced functionalities of zkPass. This guide is the go-to reference for developers seeking to deepen their understanding of the zkPass system and leverage its capabilities effectively.
Each of these components plays a critical role in making the zkPass SDK a robust and versatile toolkit for developers looking to harness the power of Zero-Knowledge Proofs in their applications.
The zkPass Software Development Kit (SDK) library, called the zkpass-client, is available in three bindings based on the language/platform/OS configuration. These bindings facilitate the integration of zkPass services by providing a client-side library tailored to streamline the implementation process.
Typescript/Node.js/Linux
Suitable for server-side applications running on Node.js.
The library is called zkpass-client-ts NPM package.
Typescript/React Native/Android
Ideal for client-side applications, specifically in React Native mobile app development.
The library is called zkpass-client-react-native.
Rust/Linux
Provides a robust option for system-level and high-performance applications.
The library is called zkpass-client crate.
All library versions are designed with parallel functionality, ensuring a consistent development experience. They empower developers to efficiently harness the capabilities of zkPass within their applications. Regardless of the language/platform binding, all zkpass-client libs behave the same way in terms of how they interact in the zkPass workflow, as depicted in the diagram.
|
|
Generate |
Generate |
|
|
|
|
|
|
|
|
|
