@provablehq/sdk
Version:
A Software Development Kit (SDK) for Zero-Knowledge Transactions
275 lines (274 loc) • 14.6 kB
TypeScript
import { Account } from "./account.js";
import { AleoNetworkClient } from "./network-client.js";
import { EncryptedRecord } from "./models/record-provider/encryptedRecord.js";
import { OwnedRecord } from "./models/record-provider/ownedRecord.js";
import { RecordSearchParams } from "./models/record-provider/recordSearchParams.js";
import { RecordsResponseFilter } from "./models/record-scanner/recordsResponseFilter.js";
/**
* Interface for a record provider. A record provider is used to find records for use in deployment and execution
* transactions on the Aleo Network. A default implementation is provided by the NetworkRecordProvider class. However,
* a custom implementation can be provided (say if records are synced locally to a database from the network) by
* implementing this interface.
*/
interface RecordProvider {
/**
* The account used to search for records.
*/
account?: Account;
/**
* Find encrypted records from the chosen provider.
*
* @param {RecordSearchParams} recordsFilter The filter used to find the records.
* @param {RecordsResponseFilter} responseFilter The filter used to filter the response.
* @returns {Promise<EncryptedRecord[]>} The encrypted records.
*/
encryptedRecords(recordsFilter: RecordSearchParams, responseFilter?: RecordsResponseFilter): Promise<EncryptedRecord[]>;
/**
* Check if a list of serial numbers exist in the chosen provider.
*
* @param {string[]} serialNumbers The serial numbers to check.
* @returns {Promise<Record<string, boolean>>} Map of Aleo Record serial numbers and whether they appeared in any inputs on chain. If boolean corresponding to the Serial Number has a true value, that Record is considered spent by the Aleo Network.
*/
checkSerialNumbers(serialNumbers: string[]): Promise<Record<string, boolean>>;
/**
* Check if a list of tags exist in the chosen provider.
*
* @param {string[]} tags The tags to check.
* @returns {Promise<Record<string, boolean>>} Map of Aleo Record tags and whether they appeared in any inputs on chain. If boolean corresponding to the tag has a true value, that Record is considered spent by the Aleo Network.
*/
checkTags(tags: string[]): Promise<Record<string, boolean>>;
/**
* Find a credits.aleo record with a given number of microcredits from the chosen provider.
*
* @param {number} microcredits The number of microcredits to search for.
* @param {RecordSearchParams} searchParameters Additional parameters to search for.
* @returns {Promise<OwnedRecord>} The record if one is found.
*
* @example
* // A class implementing record provider can be used to find a record with a given number of microcredits
* const record = await recordProvider.findCreditsRecord(5000, { unspent: true, nonces: [] });
*
* // When a record is found but not yet used, its nonce should be added to the nonces array so that it is not
* // found again if a subsequent search is performed
* const record2 = await recordProvider.findCreditsRecord(5000, { unspent: true, nonces: [record.nonce()] });
*
* // When the program manager is initialized with the record provider it will be used to find automatically find
* // fee records and amount records for value transfers so that they do not need to be specified manually
* const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider, recordProvider);
* programManager.transfer(1, "aleo166q6ww6688cug7qxwe7nhctjpymydwzy2h7rscfmatqmfwnjvggqcad0at", "public", 0.5);
*/
findCreditsRecord(microcredits: number, searchParameters: RecordSearchParams): Promise<OwnedRecord>;
/**
* Find a list of credit.aleo records with a given number of microcredits from the chosen provider
*
* @param {number[]} microcreditAmounts A list of separate microcredit amounts to search for (e.g. [5000, 100000]).
* @param {RecordSearchParams} searchParameters Additional parameters to search for.
* @returns {Promise<OwnedRecord[]>} A list of records with a value greater or equal to the amounts specified if such records exist, otherwise an error.
*
* @example
* // A class implementing record provider can be used to find a record with a given number of microcredits
* const records = await recordProvider.findCreditsRecords([5000, 5000], { unspent: true, nonces: [] });
*
* // When a record is found but not yet used, it's nonce should be added to the nonces array so that it is not
* // found again if a subsequent search is performed
* const nonces = [];
* records.forEach(record => { nonces.push(record.nonce()) });
* const records2 = await recordProvider.findCreditsRecord(5000, { unspent: true, nonces });
*
* // When the program manager is initialized with the record provider it will be used to find automatically find
* // fee records and amount records for value transfers so that they do not need to be specified manually
* const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider, recordProvider);
* programManager.transfer(1, "aleo166q6ww6688cug7qxwe7nhctjpymydwzy2h7rscfmatqmfwnjvggqcad0at", "public", 0.5);
*/
findCreditsRecords(microcreditAmounts: number[], searchParameters: RecordSearchParams): Promise<OwnedRecord[]>;
/**
* Find an arbitrary record
* @param {RecordSearchParams} searchParameters Additional parameters to search for.
* @returns {Promise<OwnedRecord>} The record if found, otherwise an error.
*
* @example
* // The RecordSearchParams interface can be used to create parameters for custom record searches which can then
* // be passed to the record provider. An example of how this would be done for the credits.aleo program is shown
* // below.
*
* class CustomRecordSearch implements RecordSearchParams {
* startHeight: number;
* endHeight: number;
* amount: number;
* program: string;
* recordName: string;
* nonces: string[];
* unspent: boolean;
* constructor(
* startHeight: number,
* endHeight: number,
* credits: number,
* maxRecords: number,
* programName: string,
* recordName: string,
* nonces: string[],
* unspent: boolean
* ) {
* this.startHeight = startHeight;
* this.endHeight = endHeight;
* this.amount = amount;
* this.program = programName;
* this.recordName = recordName;
* this.nonces = nonces;
* this.unspent = unspent;
* }
* }
*
* const params = new CustomRecordSearch(0, 100, 5000, "credits.aleo", "credits", [], true);
*
* const record = await recordProvider.findRecord(params);
*/
findRecord(searchParameters: RecordSearchParams): Promise<OwnedRecord>;
/**
* Find multiple records from arbitrary programs
*
* @param {RecordSearchParams} searchParameters Additional parameters to search for.
* @returns {Promise<OwnedRecord[]>} The records if found, otherwise an error.
*
* @example
* // The RecordSearchParams interface can be used to create parameters for custom record searches which can then
* // be passed to the record provider. An example of how this would be done for the credits.aleo program is shown
* // below.
*
* class CustomRecordSearch implements RecordSearchParams {
* startHeight: number;
* endHeight: number;
* credits: number;
* program: string;
* recordName: string;
* nonces: string[];
* unspent: boolean;
* constructor(
* startHeight: number,
* endHeight: number,
* credits: number,
* maxRecords: number,
* programName: string,
* recordName: string,
* nonces: string[],
* unspent: boolean
* ) {
* this.startHeight = startHeight;
* this.endHeight = endHeight;
* this.credits = credits;
* this.program = programName;
* this.recordName = recordName;
* this.nonces = nonces;
* this.unspent = unspent;
* }
* }
*
* const params = new CustomRecordSearch(0, 100, 5000, 2, "credits.aleo", "credits");
* const records = await recordProvider.findRecord(true, [], params);
*/
findRecords(searchParameters: RecordSearchParams): Promise<OwnedRecord[]>;
}
/**
* A record provider implementation that uses the official Aleo API to find records for usage in program execution and
* deployment, wallet functionality, and other use cases.
*/
declare class NetworkRecordProvider implements RecordProvider {
account: Account;
networkClient: AleoNetworkClient;
constructor(account: Account, networkClient: AleoNetworkClient);
/**
* Set the account used to search for records
*
* @param {Account} account The account used to use for searching for records.
*/
setAccount(account: Account): void;
/**
* Find a list of credit records with a given number of microcredits by via the official Aleo API
*
* @param {number[]} microcredits The number of microcredits to search for.
* @param {RecordSearchParams} searchParameters Additional parameters to search for.
* @returns {Promise<OwnedRecord[]>} The records if found, otherwise an error.
*
* @example
* // Create a new NetworkRecordProvider
* const networkClient = new AleoNetworkClient("https://api.explorer.provable.com/v1");
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
*
* // The record provider can be used to find records with a given number of microcredits
* const record = await recordProvider.findCreditsRecord(5000, { unspent: true, nonces: [] });
*
* // When a record is found but not yet used, it's nonce should be added to the nonces parameter so that it is not
* // found again if a subsequent search is performed
* const records = await recordProvider.findCreditsRecords(5000, { unspent: true, nonces: [record.nonce()] });
*
* // When the program manager is initialized with the record provider it will be used to find automatically find
* // fee records and amount records for value transfers so that they do not need to be specified manually
* const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider, recordProvider);
* programManager.transfer(1, "aleo166q6ww6688cug7qxwe7nhctjpymydwzy2h7rscfmatqmfwnjvggqcad0at", "public", 0.5);
*
* */
findCreditsRecords(microcredits: number[], searchParameters: RecordSearchParams): Promise<OwnedRecord[]>;
/**
* Find a credit record with a given number of microcredits by via the official Aleo API
*
* @param {number} microcredits The number of microcredits to search for.
* @param {RecordSearchParams} searchParameters Additional parameters to search for.
* @returns {Promise<OwnedRecord>} The record if found, otherwise an error.
*
* @example
* // Create a new NetworkRecordProvider
* const networkClient = new AleoNetworkClient("https://api.explorer.provable.com/v1");
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
*
* // The record provider can be used to find records with a given number of microcredits
* const record = await recordProvider.findCreditsRecord(5000, { unspent: true, nonces: [] });
*
* // When a record is found but not yet used, it's nonce should be added to the nonces parameter so that it is not
* // found again if a subsequent search is performed
* const records = await recordProvider.findCreditsRecords(5000, { unspent: true, nonces: [record.nonce()] });
*
* // When the program manager is initialized with the record provider it will be used to find automatically find
* // fee records and amount records for value transfers so that they do not need to be specified manually
* const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider, recordProvider);
* programManager.transfer(1, "aleo166q6ww6688cug7qxwe7nhctjpymydwzy2h7rscfmatqmfwnjvggqcad0at", "public", 0.5);
*/
findCreditsRecord(microcredits: number, searchParameters: RecordSearchParams): Promise<OwnedRecord>;
/**
* Find an arbitrary record. WARNING: This function is not implemented yet and will throw an error.
*/
findRecord(searchParameters: RecordSearchParams): Promise<OwnedRecord>;
/**
* Find multiple records from a specified program.
*/
findRecords(searchParameters: RecordSearchParams): Promise<OwnedRecord[]>;
encryptedRecords(recordsFilter: RecordSearchParams, responseFilter?: RecordsResponseFilter): Promise<EncryptedRecord[]>;
checkSerialNumbers(serialNumbers: string[]): Promise<Record<string, boolean>>;
checkTags(tags: string[]): Promise<Record<string, boolean>>;
}
/**
* BlockHeightSearch is a RecordSearchParams implementation that allows for searching for records within a given
* block height range.
*
* @example
* // Create a new BlockHeightSearch
* const params = new BlockHeightSearch(89995, 99995);
*
* // Create a new NetworkRecordProvider
* const networkClient = new AleoNetworkClient("https://api.explorer.provable.com/v1");
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
*
* // The record provider can be used to find records with a given number of microcredits and the block height search
* // can be used to find records within a given block height range
* const record = await recordProvider.findCreditsRecord(5000, { unspent: true, nonces: [], ...params });
*
*/
declare class BlockHeightSearch implements RecordSearchParams {
startHeight: number;
endHeight: number;
unspent: boolean;
constructor(startHeight: number, endHeight: number, unspent?: boolean);
}
export { BlockHeightSearch, NetworkRecordProvider, RecordProvider, };