Skip to main content

Production Example

image

Production Example​

This guide will walk you through the fundamental steps to integrate Primus's zkTLS SDK and complete a basic data verification process through your application. You can learn about the integration process through this simple demo.

note

Integration in a production environment requires proper server setup and configuration of specific SDK parameters.

Prerequisites​

Before you begin, ensure you have the following:

  • A paired appId and appSecret, along with a selected Template ID. These can be obtained from the Primus Developer Hub
  • The SDK installed. For installation instructions, refer to the Installation Guide.

Customized Parameters​

// Generate attestation request.
  const request = primusZKTLS.generateRequestParams(attTemplateID, userAddress);

1. Extra Data​

Developers can include custom additional parameters as auxiliary data when submitting an attestation request. These parameters will be returned alongside the proof results. For example, developers can pass the user's ID or other business-related parameters.

// Set additionParams.
const additionParams = JSON.stringify({
  YOUR_CUSTOM_KEY: "YOUR_CUSTOM_VALUE",
  YOUR_CUSTOM_KEY2: "YOUR_CUSTOM_VALUE2",
});
request.setAdditionParams(additionParams);

2. zkTLS Models​

We offer two modes in various user scenarios:

  1. proxytls
  2. mpctls

For more details about these two models, you can refer to Overview section.

// Set zkTLS mode, default is proxy model.
request.setAttMode({
  algorithmType: "proxytls",
});

3. Verification Logics​

By default, the zkTLS SDK retrieves a plaintext verification result. We offer two types of verification logic to accommodate different requirements:

  1. Hashed result

Setting example :

// Set Attestation conditions
request.setAttConditions([
  [
   {
    field: 'YOUR_CUSTOM_DATA_FIELD',
    op: 'SHA256',
    },
  ],
]);
  1. Conditions result

Setting example :

// Set Attestation conditions
request.setAttConditions([
 [
  {
    field: 'YOUR_CUSTOM_DATA_FIELD',
    op: '>',
    value: 'YOUR_CUSTOM_TARGET_DATA_VALUE',
   },
  ],
]);

For more details about these two verification logics, you can refer to the Verification Logics section.

Frontend Implementation​

note

Integration in a production environment involves configuring some customized parameters. The examples provide default configurations for these parameters, which can be adjusted to suit your specific requirements.

import { PrimusZKTLS } from "@primuslabs/zktls-js-sdk";

// Initialize parameters, the init function is recommended to be called when the page is initialized.
const primusZKTLS = new PrimusZKTLS();
const appId = "YOUR_APPID";
const initAttestaionResult = await primusZKTLS.init(appId);
console.log("primusProof initAttestaionResult=", initAttestaionResult);

export async function primusProof() {
  // Set TemplateID and user address.
  const attTemplateID = "YOUR_TEMPLATEID";
  const userAddress = "YOUR_USER_ADDRESS";
  // Generate attestation request.
  const request = primusZKTLS.generateRequestParams(attTemplateID, userAddress);

  // Set additionParams. (This is optional)
  const additionParams = JSON.stringify({
    YOUR_CUSTOM_KEY: "YOUR_CUSTOM_VALUE",
  });
  request.setAdditionParams(additionParams);

  // Set zkTLS mode, default is proxy model. (This is optional)
  const workMode = "proxytls";
  request.setAttMode({
    algorithmType: workMode,
  });

  // Set attestation conditions. (These are optional)
  // 1. Hashed result.
  // const attConditions = JSON.stringify([
  //  [
  //   { 
  //     field:'YOUR_CUSTOM_DATA_FIELD',
  //     op:'SHA256',
  //   },
  //  ],
  // ]);
  // 2. Conditions result.
  //const attConditions = JSON.stringify([
  //  [
  //    {
  //      field: "YOUR_CUSTOM_DATA_FIELD",
  //      op: ">",
  //      value: "YOUR_CUSTOM_TARGET_DATA_VALUE",
  //    },
  //  ],
  // ]);
  // request.setAttConditions(attConditions);


  // Transfer request object to string.
  const requestStr = request.toJsonString();

  // Get signed resopnse from backend.
  const response = await fetch(`http://YOUR_URL:PORT?YOUR_CUSTOM_PARAMETER`);
  const responseJson = await response.json();
  const signedRequestStr = responseJson.signResult;

  // Start attestation process.
  const attestation = await primusZKTLS.startAttestation(signedRequestStr);
  console.log("attestation=", attestation);

  // Verify siganture
  const verifyResult = await primusZKTLS.verifyAttestation(attestation);
  console.log("verifyResult=", verifyResult);

  if (verifyResult === true) {
    // Business logic checks, such as attestation content and timestamp checks
    // do your own business logic.
  } else {
    // If failed, define your own logic.
  }
}

Backend Implementation​

Here’s a basic example of how to configure and initialize the Primus zkTLS SDK on the backend:

const express = require("express");
const cors = require("cors");
const { PrimusZKTLS } = require("@primuslabs/zktls-js-sdk");

const app = express();
const port = YOUR_PORT;

// Just for test, developers can modify it.
app.use(cors());

// Listen to the client's signature request and sign the attestation request.
app.get("/primus/sign", async (req, res) => {
  const appId = "YOUR_APPID";
  const appSecret = "YOUR_SECRET";

  // Create a PrimusZKTLS object.
  const primusZKTLS = new PrimusZKTLS();

  // Set appId and appSecret through the initialization function.
  await primusZKTLS.init(appId, appSecret);

  // Sign the attestation request.
  console.log("signParams=", req.query.signParams);
  const signResult = await primusZKTLS.sign(req.query.signParams);
  console.log("signResult=", signResult);

  // Return signed result.
  res.json({ signResult });
});

app.listen(port, () => {
  console.log(`Server is running at http://localhost:${port}`);
});

Understanding the Attestation Structure​

When a successful data verification process is completed, you will receive a standard attestation structure with the following details:

  {
  "recipient": "YOUR_USER_ADDRESS", // user's wallet address
  "request": {
    "url": "REQUEST_URL", // request url
    "header": "REQUEST_HEADER", // request header
    "method": "REQUEST_METHOD", // request method
    "body": "REQUEST_BODY" // request body
  },
  "reponseResolve": [
    {
      "keyName": "VERIFY_DATA_ITEMS", // the "verify data items" you set in the template
      "parseType": "",
      "parsePath": "DARA_ITEM_PATH" // json path of the data for verification
    }
  ],
  "data": "{ACTUAL_DATA}", // actual data items in the request, stringified JSON object
  "attConditions": "[RESPONSE_CONDITIONS]", // response conditions, stringified JSON object
  "timestamp": TIMESTAMP_OF_VERIFICATION_EXECUTION, // timestamp of execution
  "additionParams": "", // additionParams from zkTLS sdk
  "attestors": [ // information of the attestors
    {
      "attestorAddr": "ATTESTOR_ADDRESS",  // the address of the attestor
      "url": "https://primuslabs.org"        // the attestor's url
    }
  ],
  "signatures": [
    "SIGNATURE_OF_THIS_VERIFICATION" // attestor's signature for this verification
  ]
}

Submit Attestation On-chain (optional)​

To submit the verified data result (proof) to the blockchain, you’ll need to invoke the appropriate smart contract method. For detailed instructions, please refer to the onchain interactions.

Error Codes​

We have defined several error codes in the SDK. If an error occurs during the data verification process, you can refer to the error code list for troubleshooting.