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:

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,
  });
  // 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 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}`);
});

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.

Customized parameters​

Extra Data​

Developers can include custom additional parameters as auxiliary data when submitting proof requests, and the additional parameters will be returned along with the proof. For example, developers can pass the user's ID and other business parameters.

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

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 this

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

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
  ]
}

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.