pado-network-sdk

Overview

The pado-network-sdk helps developers use PADO Network, which provides trustless and confidential computing capabilities. You can learn more about PADO Network.

Quick Start

Demos

Usage

Installation

Install package by npm

npm install --save @padolabs/pado-network-sdk

import wasm

Introduce lhe.js into the HTML file as follows:

<!--    When the JS is introduced, the WASM will automatically load. -->
<script type="text/javascript" src="https://pado-online.s3.ap-northeast-1.amazonaws.com/resources/v2/lhe.js"></script>

If you meet the following error in your browser's console:

_stream_writable.js:57 Uncaught ReferenceError: process is not defined
    at node_modules/readable-stream/lib/_stream_writable.js (_stream_writable.js:57:18)
    at __require2 (chunk-BYPFWIQ6.js?v=4d6312bd:19:50)

You can refer to project using vite. link

Getting Started

Utils

Generate Key

Generate public-private key pairs for submitting tasks and retrieving task results.

generateKey(param_obj?: any): Promise<KeyInfo>;

Example

import {Utils} from "@padolabs/pado-network-sdk";

//The generated key pair will be used for submitTask() and `getTaskResult()
const keyInfo = await new Utils().generateKey();

PadoNetworkContractClient

Import Client

import {PadoNetworkContractClient} from '@padolabs/pado-network-sdk'

Instantiate Client

The constructor for the PadoNetworkContractClient.

  constructor(chainName: ChainName, wallet: any, storageType: StorageType = StorageType.ARSEEDING);

Parameters

chainName: The blockchain the client wants to connect to. Learn more about ChainName
wallet: The wallet that interacts with the blockchain.
storageType (optional): The storage option the client wants to use for data. The default is StorageType.ARSEEDING. Learn more about StorageType

Note:

By default, StorageType is ARWEAVE when chainName is ao, and ARSEEDING when chainName is holesky or ethereum.

When using ARSEEDING as storage, user need to deposit ETH to EverPay to cover storage, computation, data, and other costs. You can learn more about EverPay at:

Homepage: https://everpay.io/

Docs: https://docs.everpay.io/en/docs/guide/overview

Deposit: https://app.everpay.io/deposit/ethereum-eth-0x0000000000000000000000000000000000000000

When using ARWEAVE as storage, user will pay AR to cover storage, computation, data, and other costs by ArConnect.

chainName	storageType	Wallet
ao	ARWEAVE	window.arweaveWallet(ArConnect)
holesky	ARSEEDING	window.ethereum(metamask)
ethereum	ARSEEDING	window.ethereum(metamask)

Returns
**Example **

const chainName = 'holesky';
const storageType = StorageType.ARSEEDING;
//if chainName is holesky or ethereum, wallet should be window.ethereum;
//if chainName is ao, wallet should be window.arweaveWallet;
const wallet = window.ethereum;
const padoNetworkClient = new PadoNetworkContractClient(chainName, wallet, storageType);

Upload Data

Uploading data to the storage chain.

uploadData(data: Uint8Array, dataTag: CommonObject, priceInfo: PriceInfo, permissionCheckers?: string[], encryptionSchema?: EncryptionSchema): Promise<string>;

Parameters
- data: The data to be uploaded, which should be of type Uint8Array.
- dataTag: The data's metadata object. Note: Please use an object format, not a string.
- priceInfo: The data price symbol. Leran more bout PriceInfo
  Different chainName values correspond to different symbols.
  
  chainName symbol minimum price(1 means)
  
  ao wAR(the Wrapped AR in AO) 0.000000000001 wAR
  
  holesky ETH 1 wei
  
  ethereum ETH 1 wei
- permissionCheckers(optional): The addresses of the checkers. The default is an empty array. Learn more about IDataPermission
- encryptionSchema(optional): Parameters used by the algorithm. The default is:
```
{
  t: '2',
  n: '3'
}
```
Returns
- dataId: A unique identifier for the data.
Example

chainName	symbol	minimum price(1 means)
ao	wAR(the Wrapped AR in AO)	0.000000000001 wAR
holesky	ETH	1 wei
ethereum	ETH	1 wei

//padoNetworkClient is the object instantiated in the previous section 
const data = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
const dataTag = { 'filename': 'testFileName' };
const priceInfo = { price: '200000000', symbol: 'wAR' };
//No data permission check by default
const dataId = await padoNetworkClient.uploadData(data, dataTag, priceInfo);
//If you want to set data permission checking contracts
const permissionCheckers = ['0x.....','0x.......']
const dataId = await padoNetworkClient.uploadData(data, dataTag, priceInfo, permissionCheckers);

Submit Task

Submit a task to the PADO Network. You must pay both the data fee corresponding to the data provider and the computing fee for the workers.

submitTask(taskType: TaskType, dataId: string, dataUserPk: string): Promise<string>;

Parameters
- taskType: The type of the task. Just support TaskType.DATA_SHARING now. Leran more about TaskType
- dataId: The dataId returned by the uploadData interface.
- dataUserPk: The The user's public key generated by generateKey of Utils..
Returns
- taskId: The ID of the task.
Example

const userDataId = 'returned by the uploadData';

const taskId = await padoNetworkClient.submitTask(TaskType.DATA_SHARING, userDataId, keyInfo.pk);

Note:

keyInfo is generated at Generate Key

Get Task Result

Get the result of the task.

getTaskResult(taskId: string, dataUserSk: string, timeout?: number): Promise<Uint8Array>;

Parameters
- taskId: taskId returned by submitTask
- dataUserSk: The user's secret key generated by generateKey of Utils
- timeout(optional): The timeout in milliseconds for getting the result, if you wait longer than this time a timeout exception will be thrown. Default 60000(60 seconds).
Returns
- Uint8Array: The result of the task in plain text.
Example

const taskId = 'returned by the getTaskResult';
const timeout = 20000;//milliseconds
//The format of data is Uint8Array, you should handle this data additionally, such as saving it to a file etc.
const data = await padoNetworkClient.getTaskResult(taskId, keyInfo.sk, timeout);

Note

You need to make sure that the dataUserSk used and the dataUserPk used by the submitTask are part of the same key pair. keyInfo is generated at Generate Key

Get balance can withdraw

Get the balance of your wallet that can be withdrawn

getBalance(userAddress: Address, tokenSymbol: string): Promise<Balance>;

Parameters
- userAddress: Address to search
- tokenSymbol: What token to search for. Now is ETH
Returns
- Balance: The token of the address. Leran more about Balance
Example

const balance = await padoNetworkClient.getBalance(address, 'ETH');
console.log(balance.locked.toString());
//The amount of free can be withdrawn
console.log(balance.free.toString());

Withdraw token

Withdraw token.

withdrawToken(toAddress: Address, tokenSymbol: string, amount: Uint256): Promise<Transaction>;

Parameters
- toAddress: Address to receive token
- tokenSymbol: Which token to withdraw. Now is ETH
- amoun: The amount you want to withdraw needs to be less than free above.
Returns
- Transaction: Transaction infomation.
Example

const amount = balance.free;
debugger
const transaction = await padoNetworkClient.withdrawToken(address, 'ETH', amount);
console.log(transaction);

Type And Enum

KeyInfo

type KeyInfo = {
		//publick key
    pk: string;
    //private key
    sk: string;
};

ChainName

type ChainName = 'ao' | 'holesky' | 'ethereum';

StorageType

enum StorageType {
    ARWEAVE = "arweave",
    ARSEEDING = "arseeding"
}

PriceInfo

/**
 * Price of data
 * if symbol is 'wAR'(chainName is ao), a price of 1 means that the data price is 0.000000000001 wAR.
 * if symbol is 'ETH'(chainName is holesky or ethereum)，a price of 1 means that the data price is 1wei
 * price: The price of data
 * symbol: The token symbol of price
 */
interface PriceInfo {
    price: string;
    symbol: string;
}

TaskType

enum TaskType{
  DATA_SHARING = 'dataSharing'
}

Balance

type Balance = {
  free: Uint256;
  locked: Uint256;
}

Solidity: IDataPermission

Developers should implement the IDataPermission contract to create custom checking logic. Data provider can assign a checker contract address for data permission checking while uploading data. When task submitted by a data user, the PADO Network Contract requests permission from the assigned contract and then decides whether to continue or terminate the task based on the results returned.

sequenceDiagram
    Data User->>+PADO Network Contracts: submitTask
    PADO Network Contracts->>+DataPermission Checker Contract: isPermitted
    DataPermission Checker Contract-->>PADO Network Contracts: true or false
    deactivate DataPermission Checker Contract
    alt isPermitted:false
        PADO Network Contracts->>Data User: task failed
    else isPermitted:true
        PADO Network Contracts->>PADO Network Contracts: runTask
        PADO Network Contracts-->>Data User: task result
    end

    deactivate PADO Network Contracts

IDataPermission.sol

interface IDataPermission {
    /**
     * @notice Check whether data user can buy the data
     * @param dataUser The data user to buy the data.
     * @return Return true if the data user can buy the data, else false.
     */
    function isPermitted(address dataUser) external returns (bool);
}

An example for checking data whitelisting can be found at WhiteListDataPermission

ujnss/pado-network-sdk