Simple Example

Simple Example

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

Prerequisites

Before you begin, ensure you have:

• Installed the SDK (see Installation Guide)

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 the Overview section.

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

Implementation

You can get the PRIMUS_APP_ID and PRIMUS_APP_SECRET from the Primus Developer Hub.

const { PrimusCoreTLS } = require("@primuslabs/zktls-core-sdk");

async function primusProofTest() {
    // Initialize parameters, the init function is recommended to be called when the program is initialized.
    const appId = "PRIMUS_APP_ID";
    const appSecret= "PRIMUS_APP_SECRET";
    const zkTLS = new PrimusCoreTLS();
    const initResult = await zkTLS.init(appId, appSecret);
    console.log("primusProof initResult=", initResult);

    // Set request and responseResolves.
    const request ={
        url: "YOUR_CUSTOM_URL", // Request endpoint.
        method: "REQUEST_METHOD", // Request method.
        header: {}, // Request headers.
        body: "" // Request body.
    };
    // The responseResolves is the response structure of the url.
    // For example the response of the url is: {"data":[{ ..."instFamily": "","instType":"SPOT",...}]}.
    const responseResolves = [
        {
            keyName: 'CUSTOM_KEY_NAME', // According to the response keyname, such as: instType.
            parsePath: 'CUSTOM_PARSE_PATH', // According to the response parsePath, such as: $.data[0].instType.
        }
    ];
    // Generate attestation request.
    const generateRequest = zkTLS.generateRequestParams(request, responseResolves);

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

    // Start attestation process.
    const attestation = await zkTLS.startAttestation(generateRequest);
    console.log("attestation=", attestation);
    
    const verifyResult = zkTLS.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.
    }
}

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.