Example

Example

This guide will walk you through the fundamental steps to integrate Primus's Network SDK and complete a basic data verification process through your application.

Prerequisites

Before you begin, ensure you have the following:

• A valid Template ID. （obtainable from the Primus Developer Hub）
• The SDK installed. (see Installation Guide for instructions)

Key Features

1. SDK Initialization

Connect to specified blockchain networks.

Function Name: init

Parameter Description:

Parameter Name	Type	Required	Description
provider	Provider	Yes	Web3 provider, can be: - An instance of ethers.providers.JsonRpcProvider - An instance of ethers.providers.Web3Provider - An instance of ethers.providers.JsonRpcSigner
chainId	number	Yes	The blockchain network ID to connect to. Must be one of the supported chain IDs

2. Task Submission

Submit tasks to require an attestation from the network.

Function Name: submitTask

Parameter Description:

Parameter Name	Type	Required	Description
templateId	string	Yes	Template ID
address	string	Yes	User address

3. Attestation Execution

Execute the zkTLS protocol with the network attestor node, and return an attestation issued by the attestor node.

Function Name: attest

Parameter Description:

Parameter Name	Type	Required	Description
templateId	string	Yes	Template ID
address	string	Yes	User address
taskId	string	Yes	Task ID
taskTxHash	string	Yes	Task transaction hash
taskAttestors	<string>Array	Yes	Array of attestor IDs
additionParams	string	No	Extended parameters in JSON format. Developers can include custom business parameters (e.g., user IDs, session info),These parameters will be returned with the final results const additionParams = JSON.stringify({ YOUR_CUSTOM_KEY: "YOUR_CUSTOM_VALUE" })
attMode	string	No	proxytls or mpctls,default is proxytls. you can refer to Overview section for more details.
attConditions	Array	No	By default, the zkTLS SDK retrieves a plaintext verification result. We offer two types of verification logic to accommodate different requirements: 1.Hashed result const attConditions = [[{field: "YOUR_CUSTOM_DATA_FIELD",op: "SHA256"}]] 2.Conditions result const attConditions = [[{field: "YOUR_CUSTOM_DATA_FIELD",op: ">",value: "YOUR_CUSTOM_TARGET_DATA_VALUE"}]].you can refer to the Verification Logics section for more details.

4. Verify & Poll Task Result

Verify and poll task results. The function is additonally provided for any use case that requires to double check the validity of an created attestation through Primus contracts.

Function Name: verifyAndPollTaskResult

Parameter Description:

Parameter Name	Type	Required	Description
taskId	string	Yes	The ID of the task to poll
reportTxHash	string	No	Report transaction hash (optional)
intervalMs	number	No	Polling interval in milliseconds, default is 2000
timeoutMs	number	No	Total timeout duration in milliseconds, default is 1 minute

5. Balance Withdrawal

Retrieve the fees for unsettled tasks.

Function Name: withdrawBalance

Parameter Description:

Parameter Name	Type	Required	Description
tokenSymbol	TokenSymbol	No	Token type to withdraw, default is ETH
limit	number	No	Withdrawal amount limit, default is 100

6. List of supported chains

Property Name：supportedChainIds

Currently supports Base Sepolia and Base mainnet, additional chains will be added in upcoming releases.

Complete Example

import { PrimusNetwork } from "@primuslabs/network-js-sdk";

async function main() {
  const provider = window.ethereum;
  const primusNetwork = new PrimusNetwork();
  console.log(primusNetwork.supportedChainIds); // [84532, 8453]

  try {
    // 1. Initialize
    await primusNetwork.init(provider, 84532); // The Base chain changes 84532 to 8453
    console.log("SDK initialized");

    // 2. Submit task, set TemplateID and user address.
    const submitTaskParams = {
      templateId: "YOUR_TEMPLATEID",
      address: "YOUR_USER_ADDRESS",
    };
    const submitTaskResult = await primusNetwork.submitTask(submitTaskParams);
    console.log("Task submitted:", submitTaskResult);


    // 3. Perform attestation
    const attestParams = {
      ...submitTaskParams,
      ...submitTaskResult,
      // extendedParams: JSON.stringify({ attUrlOptimization: true }), //Optional,optimization the url of attestation.
    };
    const attestResult = await primusNetwork.attest(attestParams);
    console.log('Attestation completed:', attestResult);

    // 4. Verify & poll task result
    const verifyAndPollTaskResultParams = {
      taskId: attestResult[0].taskId,
      reportTxHash: attestResult[0].reportTxHash,
    }
    const taskResult = await primusNetwork.verifyAndPollTaskResult(verifyAndPollTaskResultParams);
    console.log("Final result:", taskResult);

    // Optional withdrawal
    // const settledTaskIds = await primusNetwork.withdrawBalance();
    // console.log('Withdrawn:', settledTaskIds  );
  } catch (error) {
    console.error("Main flow error:", error);
  }
}

main();

Understanding the Attestation Structure

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

  [
      {
        "attestor": "ATTESTOR_ADDRESS", // attestor's address
        "taskId": "TASK_ID", // the task id
        "attestation": {
            "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
                }
            ],
            "responseResolve": [
                {
                    "oneUrlResponseResolve": [
                        {
                            "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
        }
      }
  ]

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.