@provablehq/sdk 0.10.2-rc.1 → 0.10.3

package/dist/mainnet/program-manager.d.ts

@@ -4,7 +4,6 @@ import { ImportedPrograms, ImportedVerifyingKeys } from "./models/imports.js";
 import { RecordProvider } from "./record-provider.js";
 import { RecordSearchParams } from "./models/record-provider/recordSearchParams.js";
 import { FunctionKeyProvider, KeySearchParams } from "./keys/provider/interface.js";
-import { KeyStore } from "./keys/keystore/interface.js";
 import { FunctionKeyPair } from "./models/keyPair.js";
 import { Authorization, ExecutionRequest, ExecutionResponse, OfflineQuery, RecordPlaintext, PrivateKey, Program, ProvingKey, ProvingRequest, VerifyingKey, Transaction } from "./wasm.js";
 import { ExternalSigningOptions } from "./models/external-signing.js";
@@ -121,7 +120,6 @@ interface ExecuteAuthorizationOptions {
     offlineQuery?: OfflineQuery;
     program?: string | Program;
     imports?: ProgramImports;
-    edition?: number;
 }
 /**
  * Represents the options for executing a transaction in the Aleo network.
@@ -215,14 +213,13 @@ declare class ProgramManager {
     networkClient: AleoNetworkClient;
     recordProvider: RecordProvider | undefined;
     inclusionKeysLoaded: boolean;
-    private _keyStore;
     /** Create a new instance of the ProgramManager
      *
      * @param { string | undefined } host A host uri running the official Aleo API
      * @param { FunctionKeyProvider | undefined } keyProvider A key provider that implements {@link FunctionKeyProvider} interface
      * @param { RecordProvider | undefined } recordProvider A record provider that implements {@link RecordProvider} interface
      */
-    constructor(host?: string | undefined, keyProvider?: FunctionKeyProvider | undefined, recordProvider?: RecordProvider | undefined, networkClientOptions?: AleoNetworkClientOptions | undefined, keyStore?: KeyStore | undefined);
+    constructor(host?: string | undefined, keyProvider?: FunctionKeyProvider | undefined, recordProvider?: RecordProvider | undefined, networkClientOptions?: AleoNetworkClientOptions | undefined);
     /**
      * Check if the fee is sufficient to pay for the transaction
      */
@@ -251,64 +248,6 @@ declare class ProgramManager {
      * @param {RecordProvider} recordProvider
      */
     setRecordProvider(recordProvider: RecordProvider): void;
-    /**
-     * Set the key store for automatic key caching across executions.
-     *
-     * @param {KeyStore} keyStore
-     */
-    setKeyStore(keyStore: KeyStore): void;
-    /**
-     * Build a ProgramImportsBuilder from a program and its imports.
-     * Fetches imports from the network if not provided, resolves transitive
-     * dependencies, and optionally pre-loads cached keys from the KeyStore.
-     *
-     * @param loadKeys When true (default), loads cached proving/verifying keys
-     *   from the KeyStore into the builder. Set to false for authorization and
-     *   proving request paths where keys are not synthesized.
-     */
-    private buildProgramImports;
-    /**
-     * Extract `import program_name.aleo;` names from program source via regex.
-     * Avoids a WASM round-trip compared to Program.fromString + getImports.
-     */
-    private static getImportNames;
-    /**
-     * Parse `call program.aleo/function` instructions from program source
-     * to determine which functions of each import are actually in the call chain.
-     * Returns a map of program name -> set of called function names.
-     */
-    private static getCalledFunctions;
-    /**
-     * Resolve the active KeyStore, preferring the directly-set _keyStore
-     * over the KeyProvider's keyStore().
-     */
-    private resolveKeyStore;
-    /**
-     * Resolve the edition and amendment count for a program from the network.
-     * Returns `{ edition, amendment }` or falls back to `{ edition: 1, amendment: 0 }`.
-     */
-    private resolveEditionAndAmendment;
-    /**
-     * Load cached proving/verifying keys from the KeyStore into a ProgramImportsBuilder.
-     * Only loads keys for the specified functions — returns immediately if
-     * functionNames is empty or undefined.
-     * Resolves edition and amendment from the network for accurate key locator
-     * construction when not explicitly provided.
-     */
-    private loadKeysFromStore;
-    /**
-     * Persist newly synthesized keys from the returned ProgramImportsBuilder
-     * into the KeyStore. Only writes keys that are not already in the store,
-     * avoiding unnecessary writes of large proving keys.
-     * Fetches each program's current edition and amendment count from the network
-     * for accurate key locator construction.
-     */
-    private persistExtractedKeys;
-    /**
-     * Resolve top-level function keys, checking the KeyStore first and
-     * falling back to the KeyProvider.
-     */
-    private resolveTopLevelKeys;
     /**
      * Set a header in the `AleoNetworkClient`s header map
      *

package/dist/mainnet/record-provider.d.cts

@@ -0,0 +1,274 @@
+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.provable.com/v2", 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.provable.com/v2", 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.provable.com/v2");
+     * 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.provable.com/v2", 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.provable.com/v2");
+     * 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.provable.com/v2", 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.provable.com/v2");
+ * 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, };