Quick Start
Quick Start
Basic Tutorials
We need to register your dApps' domain to maintain the whitelist for production usage. If you are only debugging locally, simply follow the steps below to complete the call. For better tech support, please contact the Primus team through our community.
Step 1. Install zkTLS SDK
You can install it via npm or yarn:
npm install --save @padolabs/mpctls-js-sdk
yarn add --save @padolabs/mpctls-js-sdk
Step 2. Initialize zkTLS SDK
You must set up a dAppSymbol (string) of your dApp, this will be displayed on the Extension - Attestation page as a mark of the proof that was completed by your dApp.
You only need to do this step once.
- Return:string The version number of the Extension. Please ensure that the version is 0.3.15 or higher.
Example:
import MPCTLSJSSDK from "@padolabs/mpctls-js-sdk";
const sdkInstance = new MPCTLSJSSDK();
try {
const initAttestaionResult = await sdkInstance.initAttestation("yourdAppSymbol");
console.log(initAttestaionResult); //Output: 0.3.15
} catch (e) {
alert(`Initialize failed,code: ${e.code} ,message: ${e.message}`);
}
Step 3. Set parameters to request data verification process
Before starting the data verification process, a few parameters should be configured and transmitted to the zkTLS SDK. This configuration is required regardless of how you set up your users' operation steps in you dApp.
The parameters should be configured in the following order:
- chainID (must)
- walletAddress (must)
- attestationTypeID (must)
- attestationParameters (must, according to different attestationTypeID)
1. chainID (number)
The ID of the blockchain to which you want users to submit their proof.
console.log(sdkInstance.supportedChainList); // Output: [
// {text: 'Linea', value: 59144 },
// {text: 'BNB Chain', value: 56 },
// {text: 'opBNB', value: 204 },
// {text: 'Arbitrum', value: 42161 },
// {text: 'Scroll', value: 534352 },
// {text: 'Sepolia', value: 11155111 },
// {text: 'BNB Testnet', value: 97 },
// {text: 'opBNB Testnet', value: 5611 },
// {text: 'Scroll Sepolia', value: 534351 },
// ]
To test your integration and business workflow, simply input the chainID parameter using one of the four test networks we support: Sepolia, BSC Testnet, opBNB Testnet, and Scroll Sepolia.
2. walletAddress (string)
The wallet address of the user. This address will be used as an index for queries on the blockchain.
3. attestationTypeID (string)
We have assigned different IDs to each attestation type, which can be transmitted to initialize the associated data verification process.
console.log(sdkInstance.supportedAttestationTypeList); // Output: [
// {text: 'binance kyc status', value: '1' },
// {text: 'binance account ownership', value: '2' },
// {text: 'x account ownership', value: '3' },
// {text: 'okx kyc status', value: '4' },
// {text: 'tiktok account ownership', value: '6' },
// {text: 'binance assets balance', value: '9' },
// {text: 'binance token holding', value: '10' },
// {text: 'okx assets balance', value: '11' },
// {text: 'okx token holding', value: '12' },
// {text: 'X social connections', value: '15' },
// {text: 'binance spot 30d trade vol', value: '16' },
// {text: 'okx spot 30d trade vol', value: '17' },
// {text: 'On-chain transactions on BNB Chain since 2024 July', value: '101' },
// ]
4. attestationParameters (array)
For the attestationTypeID 1, 2, 3, 4, and 6, you need to transmit a default value []
in attestationParameters, like this:
{
chainID: 56,
walletAddress: '0x',
attestationTypeID: '1',
attestationParameters: []
}
For attestationTypeID 9, 10, 11, 12, 15, 16, 17, and 101, you need to transmit with different inputs.
(1) For attestationTypeID 9 & 11
The attestationParameters should include a USD value (numeric), with a minimum value of 0.000001 and restricted to a 6-decimal-place. If the attestationParameters is set to ['100']
, it will complete a data verification process to verify if the user's asset balance is greater than USD 100.
Example parameters should look like this:
{
chainID: 56,
walletAddress: '0x',
attestationTypeID: '11',
attestationParameters: ['100'],
}
(2) For attestationTypeID 10 & 12
The attestationParameters should include a token name (alphabet). If the attestationParameters is set to ['USDT']
, it will complete a data verification process to verify if the user holds USDT equivalent to more than USD 0.1.
Example parameter should look like this:
{
chainID: 56,
walletAddress: '0x',
attestationTypeID: '10',
attestationParameters: ['USDT'],
}
(3) For attestationTypeID 15
The attestationParameters should include a follower number (numeric), with a minimum value of 0. If the attestationParameters is set to ['10']
, it will complete a data verification process to verify if the user has more than 10 X followers.
Example parameter should look like this:
{
chainID: 56,
walletAddress: '0x',
attestationTypeID: '15',
attestationParameters: ['10'],
}
(4) For attestationTypeID 16 & 17
The attestationParameters should include a USD value (numeric), with a minimum value of 0.000001 and restricted to a 6-decimal-place. If the attestationParameters is set to ['500']
, it will complete a data verification process to verify if the user's spot 30-day trade volume is greater than USD 500.
Example parameter should look like this:
{
chainID: 56,
walletAddress: '0x',
attestationTypeID: '16',
attestationParameters: ['500'],
}
(5) For attestationTypeID 101
This attestation integrates the Brevis' SDK to enable on-chain transaction proof, allowing verification of whether a user has conducted on-chain transactions on the BNB Chain since July 2024.
The attestationParameters should include a signature from the user’s wallet address, which needs to be attested to confirm ownership of the address, along with a timestamp indicating the time of the signature. The input should follow this order: first, ‘user signature’; second, ‘timestamp’.
Example parameter should look like this:
{
chainID: 56,
walletAddress: '0x',
attestationTypeID: '101',
attestationParameters: ['0xxx....', '1728546495272'],
}
In order to confirm that the user truly owns the address to be attested, you must verify that the transmitted ‘user signature’ was signed from that address. The verification method is:
import { ethers } from "ethers";
const connectedAddress = '0x'
const timestamp = +new Date() + ""; // '1728546495272'
const provider = new ethers.providers.Web3Provider(window.ethereum);
const typedData = {
types: {
EIP712Domain: [{ name: "name", type: "string" }],
Request: [
{ name: "desc", type: "string" },
{ name: "address", type: "string" },
{ name: "timestamp", type: "string" },
],
},
primaryType: "Request",
domain: {
name: "PADO Labs",
},
message: {
desc: "PADO Labs",
address: connectedAddress,
timestamp,
},
};
const userSignature = await provider.send("eth_signTypedData_v4", [
connectedAddress,
typedData,
]);
console.log("userSignature", userSignature); // 0xxx....
Step 4. Start zkTLS process
Note: You can call startAttestation only after the initAttestation method is called.
try {
const startAttestaionResult = await sdkInstance.startAttestation({
chainID: 56,
walletAddress: '0x',
attestationTypeID: '9',
attestationParameters: ['100'],
});
console.log(startAttestaionResult); // Output:
// {
// eip712MessageRawDataWithSignature:
// {
// types: {
// Attest: [
// {
// name: "schema",
// type: "bytes32",
// },
// {
// name: "recipient",
// type: "address",
// },
// {
// name: "expirationTime",
// type: "uint64",
// },
// {
// name: "revocable",
// type: "bool",
// },
// {
// name: "refUID",
// type: "bytes32",
// },
// {
// name: "data",
// type: "bytes",
// },
// {
// name: "deadline",
// type: "uint64",
// },
// ],
// },
// primaryType: "Attest",
// message: {
// schema: "0x",
// recipient: "0x",
// expirationTime: 0,
// revocable: true,
// data: "0x",
// refUID:
// "0x0000000000000000000000000000000000000000000000000000000000000000",
// deadline: 0,
// },
// domain: {
// name: "xxx",
// version: "xxx",
// chainId: "xxx",
// verifyingContract: "0x",
// salt: null,
// },
// uid: null,
// signature: {
// v: 28,
// r: "0x",
// s: "0x",
// },
// }
// };
console.log("Attest successfully!");
} catch (e) {
alert(`Attest failed,code: ${e.code} ,message: ${e.message}`);
}
Step 5. Verify attestation result
After receiving the verified result, you need to verify whether the result is trustworthy.
Parameters
- startAttestationReturnParams:StartAttestationReturnParams An object containing the properties of eip712MessageRawDataWithSignature, which is the return value of the startAttestation method.
Return:boolean Whether the signature is successfully verified.
Example
const verifyAttestationResult = sdkInstance.verifyAttestation(
startAttestaionResult
);
console.log(verifyAttestation); // Output: true
Step 6. Submit the verified data result (proof) to the blockchain
You can only submit the proof to the chainID associated with the configuration in Step 2.
Parameters
- startAttestationReturnParams:StartAttestationReturnParams An object containing the properties of eip712MessageRawDataWithSignature, which is the return value of the startAttestation method.
- wallet:any The wallet object
Return:string Transaction details URL
Example
try {
const sendToChainResult = sdkInstance.sendToChain(
startAttestaionResult,
window.ethereum
);
console.log(sendToChainResult); // Output: https://bascan.io/attestation/0x
console.log("SendToChain successfully!");
} catch (e) {
alert(`SendToChain failed,code: ${e.code} ,message: ${e.message}`);
}
Step 7. Check the submitted proof on-chain
After completing the submission, you can find the on-chain details using the corresponding blockchain links below.
Mainnet
- Linea Mainnet: https://lineascan.build/
- BNB Chain: https://bascan.io/
- opBNB: https://scan.sign.global/
- Arbitrum: https://arbitrum.easscan.org/
- Scroll Mainnet: https://scrollscan.com/
Testnet
- Sepolia: https://sepolia.easscan.org/
- BNBTestnet: https://testnet.bascan.io/
- opBNBTestnet: https://testnet-scan.sign.global/
- Scroll Sepolia: https://sepolia.scrollscan.com/
Examples of the zkTLS SDK operations
Here's a simple example demonstrating how to perform basic operations with the zkTLS SDK.
import MPCTLSJSSDK from "@padolabs/mpctls-js-sdk";
const sdkInstance = new MPCTLSJSSDK();
try {
const initAttestaionResult = await sdkInstance.initAttestation(
"yourdAppSymbol"
); // Initialize the SDK
console.log(initAttestaionResult); //Output: 0.3.15
console.log(sdkInstance.supportedChainList); // View supported chains
console.log(sdkInstance.supportedAttestationTypeList); // View supported attestation types
// Generate attestation process
const startAttestaionResult = await sdkInstance.startAttestation({
chainID: 56, // Select from the supported chain list
walletAddress: "0x", // User's wallet address
attestationTypeID: "9", // Select from the supported attestation types
attestationParameters: ["100"], // Input the corresponding fields (if needed) according to the selected attestationTypeID
});
// Verify attestation result
const verifyAttestationResult = await sdkInstance.verifyAttestati(startAttestaionResult);
// Upload Proof to Blockchain
const sendToChainResult = await sdkInstance.sendToChain(
startAttestaionResult,
window.ethereum
);
console.log("Generated Proof:", startAttestaionResult);
console.log("Proof on Chain:", sendToChainResult);
console.log("Is Proof Valid:", verifyAttestationResult);
} catch (e) {
alert(`Failed, code: ${e.code} , message: ${e.message}`);
}
Error Codes
We have defined some error codes in the SDK. When an error occurs during the data verification process, you can refer to the following list for troubleshooting.
1. General errors
Error Code | Situation |
---|---|
00001 | The zkTLS algorithm has not been initialized. Please restart the process. |
00002 | The process did not respond within 5 minutes. |
00003 | A data verification process is currently being generated. Please try again later. |
00004 | The user closes or cancels the attestation process. |
00005 | Wrong parameters! |
00006 | No extension version 0.3.15 or above was detected as installed. |
00007 | Insufficient wallet balance. |
00008 | Failed to submit the proof on-chain. Or other errors in the Wallet operations. |
00009 | Your dApp is not registered. Please contact the Primus team. |
99999 | Undefined error. Contact the Primus team for further support |
2. Data source related errors
Error Code | Situation |
---|---|
00102 | Attestation requirements not met. Insufficient assets balance in Binance Spot Account. |
00104 | Attestation requirements not met. |
3. zkTLS related errors
Error Code | Situation |
---|---|
10001 | The internet condition is not stable enough to complete the data verification flow. Please try again later. |
10002 | The attestation process has been interrupted due to some unknown network error. Please try again later. |
10003 | Can't connect attestation server due to unstable internet condition. Please try again later. |
10004 | Can't connect data source server due to unstable internet condition. Please try again later. |
20005 | Can't complete the attestation due to some workflow error. Please try again later. |
30001 ~ 30004 | Can't complete the attestation flow due to response error. Please try again later. |
50007 | Can't complete the attestation due to algorithm execution issues. |
50008 | Can't complete the attestation due to abnormal execution results. |
50009 | The algorithm service did not respond within 5 minutes. |
50010 | Can't complete the attestation due to some compatibility issues. |
50011 | Can't complete the attestation due to algorithm version issues. |
For any other error codes not mentioned here, please contact our community for further support.