@provablehq/sdk
Version:
A Software Development Kit (SDK) for Zero-Knowledge Transactions
941 lines • 91.5 kB
TypeScript
import { Account } from "./account.js";
import { AleoNetworkClient, AleoNetworkClientOptions, ProgramImports } from "./network-client.js";
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";
/**
* Represents the options for deploying and upgrading a transaction in the Aleo network.
* This interface is used to specify the parameters required for building and submitting an deployment transaction.
*
* @property {string} program - The program source code to be deployed.
* @property {number} priorityFee - The priority fee to be paid for the transaction.
* @property {boolean} privateFee - If true, uses a private record to pay the fee; otherwise, uses the account's public credit balance.
* @property {RecordSearchParams} [recordSearchParams] - Parameters for searching for a record to pay the execution transaction fee.
* @property {string | RecordPlaintext} [feeRecord] - Fee record to use for the transaction.
* @property {PrivateKey} [privateKey] - Private key to use for the transaction.
*/
interface DeployOptions {
program: string;
priorityFee: number;
privateFee: boolean;
recordSearchParams?: RecordSearchParams;
feeRecord?: string | RecordPlaintext;
privateKey?: PrivateKey;
}
/**
* Represents the options for executing a transaction in the Aleo network.
* This interface is used to specify the parameters required for building and submitting an execution transaction.
*
* @property {string} programName - The name of the program containing the function to be executed.
* @property {string} functionName - The name of the function to execute within the program.
* @property {number} priorityFee - The priority fee to be paid for the transaction.
* @property {boolean} privateFee - If true, uses a private record to pay the fee; otherwise, uses the account's public credit balance.
* @property {string[]} inputs - The inputs to the function being executed.
* @property {RecordSearchParams} [recordSearchParams] - Parameters for searching for a record to pay the execution transaction fee.
* @property {KeySearchParams} [keySearchParams] - Parameters for finding the matching proving & verifying keys for the function.
* @property {string | RecordPlaintext} [feeRecord] - Fee record to use for the transaction.
* @property {ProvingKey} [provingKey] - Proving key to use for the transaction.
* @property {VerifyingKey} [verifyingKey] - Verifying key to use for the transaction.
* @property {PrivateKey} [privateKey] - Private key to use for the transaction.
* @property {OfflineQuery} [offlineQuery] - Offline query if creating transactions in an offline environment.
* @property {string | Program} [program] - Program source code to use for the transaction.
* @property {ProgramImports} [imports] - Programs that the program being executed imports.
* @property {number} [edition] - Edition of the program to execute the function in.
*/
interface ExecuteOptions {
programName: string;
functionName: string;
priorityFee: number;
privateFee: boolean;
inputs: string[];
recordSearchParams?: RecordSearchParams;
keySearchParams?: KeySearchParams;
feeRecord?: string | RecordPlaintext;
provingKey?: ProvingKey;
verifyingKey?: VerifyingKey;
privateKey?: PrivateKey;
offlineQuery?: OfflineQuery;
program?: string | Program;
imports?: ProgramImports;
edition?: number;
}
/**
* Options for building an Authorization for a function.
*
* @property {string} programName Name of the program containing the function to build the authorization for.
* @property {string} functionName Name of the function name to build the authorization for.
* @property {string[]} inputs The inputs to the function.
* @property {string | Program} [programSource] The optional source code for the program to build an execution for.
* @property {PrivateKey} [privateKey] Optional private key to use to build the authorization.
* @property {ProgramImports} [programImports] The other programs the program imports.
* @property {edition} [edition]
*/
interface AuthorizationOptions {
programName: string;
functionName: string;
inputs: string[];
programSource?: string | Program;
privateKey?: PrivateKey;
programImports?: ProgramImports;
edition?: number;
}
/**
* Options for executing a fee authorization.
*
* @property {string} deploymentOrExecutionId The id of a previously built Execution or Authorization.
* @property {number} baseFeeCredits The number of Aleo Credits to pay for the base fee.
* @property {number} [priorityFeeCredits] The number of Aleo Credits to pay for the priority fee.
* @property {PrivateKey} [privateKey] Optional private key to specify for the authorization.
* @property {RecordPlaintext} [feeRecord] A record to specify to pay the private fee. If this is specified a `fee_private` authorization will be built.
*/
interface FeeAuthorizationOptions {
deploymentOrExecutionId: string;
baseFeeCredits: number;
priorityFeeCredits?: number;
privateKey?: PrivateKey;
feeRecord?: RecordPlaintext;
}
/**
* Represents the options for executing a transaction on the Aleo Network from an authorization.
*
* @property {string} programName - The name of the program containing the function to be executed.
* @property {KeySearchParams} [keySearchParams] - Optional parameters for finding the matching proving & verifying keys for the function.
* @property {ProvingKey} [provingKey] - Optional proving key to use for the transaction.
* @property {VerifyingKey} [verifyingKey] - Optional verifying key to use for the transaction.
* @property {OfflineQuery} [offlineQuery] - Optional offline query if creating transactions in an offline environment.
* @property {string | Program} [program] - Optional program source code to use for the transaction.
* @property {ProgramImports} [imports] - Optional programs that the program being executed imports.
*/
interface ExecuteAuthorizationOptions {
programName: string;
authorization: Authorization;
feeAuthorization?: Authorization;
keySearchParams?: KeySearchParams;
provingKey?: ProvingKey;
verifyingKey?: VerifyingKey;
offlineQuery?: OfflineQuery;
program?: string | Program;
imports?: ProgramImports;
edition?: number;
}
/**
* Represents the options for executing a transaction in the Aleo network.
* This interface is used to specify the parameters required for building and submitting an execution transaction.
*
* @property {string} programName - The name of the program containing the function to be executed.
* @property {string} functionName - The name of the function to execute within the program.
* @property {number} [baseFee] - The base fee to be paid for the transaction.
* @deprecated Base fee is now estimated automatically; this option is ignored and will be removed in a future version.
* @property {number} priorityFee - The optional priority fee to be paid for the transaction.
* @property {boolean} privateFee - If true, uses a private record to pay the fee; otherwise, uses the account's public credit balance.
* @property {string[]} inputs - The inputs to the function being executed.
* @property {RecordSearchParams} [recordSearchParams] - Optional parameters for searching for a record to pay the execution transaction fee.
* @property {string | RecordPlaintext} [feeRecord] - Optional fee record to use for the transaction.
* @property {PrivateKey} [privateKey] - Optional private key to use for the transaction.
* @property {string | Program} [program] - Optional program source code to use for the transaction.
* @property {string} uri - The URI send the ProvingRequest to.
* @property {ProgramImports} [imports] - Optional programs that the program being executed imports.
* @property {boolean} broadcast - Whether to broadcast the Transaction generated by the remove prover to the Aleo network.
* @property {boolean} unchecked - Whether to execute the transaction without checking the validity of the authorization (faster but may fail).
* @property {number} [edition] - Edition of the program to execute the function in.
* @property {boolean} [useFeeMaster] - Whether to use the FeeMaster account to execute the transaction.
*/
interface ProvingRequestOptions {
programName: string;
functionName: string;
priorityFee: number;
privateFee: boolean;
inputs?: string[];
baseFee?: number;
recordSearchParams?: RecordSearchParams;
feeRecord?: string | RecordPlaintext;
privateKey?: PrivateKey;
programSource?: string | Program;
programImports?: ProgramImports;
broadcast?: boolean;
unchecked?: boolean;
edition?: number;
useFeeMaster?: boolean;
executionRequest?: ExecutionRequest;
}
/**
* Fee estimate options.
*
* @property {string} programName - The name of the program containing the function to estimate the fee for.
* @property {string} functionName - The name of the function to execute within the program to estimate the fee for.
* @property {string} [program] - Program source code to use for the fee estimate.
* @property {ProgramImports} [imports] - Programs that the program imports.
* @property {number} [edition] - Edition of the program to estimate the fee for.
* @property {Authorization} authorization - An authorization to estimate the fee for.
*/
interface FeeEstimateOptions {
programName: string;
functionName?: string;
program?: string | Program;
imports?: ProgramImports;
edition?: number;
authorization?: Authorization;
}
/**
* Options for verifying a single Aleo zkSnark proof.
*
* @property {string} verifyingKey - The verifying key string for the circuit
* @property {string[]} inputs - Array of public input strings — either field elements (e.g. "1field") or Aleo types (e.g. "1u32", "{ x: 1u8 }")
* @property {string} proof - The proof string to verify
*/
interface VerificationOptions {
verifyingKey: string;
inputs: string[];
proof: string;
}
/**
* Options for verifying a batch Aleo zkSnark proof.
*
* @property {string[]} verifyingKeys - Array of verifying key strings, one per circuit
* @property {string[][][]} inputs - 3D array of input strings [circuit_idx][instance_idx][input_idx]
* @property {string} proof - The batch proof string to verify
*/
interface BatchVerificationOptions {
verifyingKeys: string[];
inputs: string[][][];
proof: string;
}
/**
* The ProgramManager class is used to execute and deploy programs on the Aleo network and create value transfers.
*/
declare class ProgramManager {
account: Account | undefined;
keyProvider: FunctionKeyProvider;
host: string;
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);
/**
* Pre-load the inclusion prover for offline execution. Required when the
* user provides an explicit OfflineQuery (truly offline — can't fetch lazily).
* For CallbackQuery, snarkVM handles inclusion key loading on demand.
*/
private ensureInclusionKeys;
/**
* Create a CallbackQuery that delegates all state fetching to the
* transport-aware network client. WASM calls back into these functions
* during trace.prepare_async() instead of making its own reqwest calls.
*
* This handles ALL programs including those with DynamicRecord inputs.
*/
private buildCallbackQuery;
/**
* Check if the fee is sufficient to pay for the transaction
*/
checkFee(address: string, feeAmount: bigint): Promise<void>;
/**
* Set the account to use for transaction submission to the Aleo network
*
* @param {Account} account Account to use for transaction submission
*/
setAccount(account: Account): void;
/**
* Set the key provider that provides the proving and verifying keys for programs
*
* @param {FunctionKeyProvider} keyProvider
*/
setKeyProvider(keyProvider: FunctionKeyProvider): void;
/**
* Set the host peer to use for transaction submission to the Aleo network
*
* @param host {string} Peer url to use for transaction submission
*/
setHost(host: string): void;
/**
* Set the record provider that provides records for transactions
*
* @param {RecordProvider} recordProvider
*/
setRecordProvider(recordProvider: RecordProvider): void;
/**
* Set the key store for automatic key caching across executions.
*
* @param {KeyStore} keyStore
*/
setKeyStore(keyStore: KeyStore): void;
/**
* Collect static imports declared by the entry program together with any
* caller-provided imports, then resolve missing transitive dependencies.
* Caller-provided program sources take precedence over network sources.
*/
private collectProgramImports;
/**
* Build a ProgramImportsBuilder from a program and its imports.
* Fetches missing imports from the network, 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;
/**
* Convert the JS object returned by Program.getCallGraph() into a
* Map<string, Set<string>> for use in buildProgramImports.
*/
private static callGraphToMap;
/**
* 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
*
* @param {string} headerName The name of the header to set
* @param {string} value The header value
*
* @example
* import { ProgramManager } from "@provablehq/sdk/mainnet.js";
*
* // Create a ProgramManager
* const programManager = new ProgramManager("https://api.provable.com/v2");
*
* // Set the value of the `Accept-Language` header to `en-US`
* programManager.setHeader('Accept-Language', 'en-US');
*/
setHeader(headerName: string, value: string): void;
/**
* Set the inclusion prover into the wasm memory. This should be done prior to any execution of a function with a
* private record.
*
* @param {ProvingKey} [provingKey]
*
* @example
* import { ProgramManager, AleoKeyProvider } from "@provablehq/sdk/mainnet.js";
*
* const keyProvider = new AleoKeyProvider();
* keyProvider.useCache(true);
*
* // Create a ProgramManager
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider);
*
* // Set the inclusion keys.
* programManager.setInclusionProver();
*/
setInclusionProver(provingKey?: ProvingKey): Promise<void>;
/**
* Remove a header from the `AleoNetworkClient`s header map
*
* @param {string} headerName The name of the header to be removed
*
* @example
* import { ProgramManager } from "@provablehq/sdk/mainnet.js";
*
* // Create a ProgramManager
* const programManager = new ProgramManager("https://api.provable.com/v2");
*
* // Remove the default `X-Aleo-SDK-Version` header
* programManager.removeHeader('X-Aleo-SDK-Version');
*/
removeHeader(headerName: string): void;
/**
* Builds a deployment transaction for submission to the Aleo network.
*
* @param {string} program Program source code
* @param {number} priorityFee The optional priority fee to be paid for that transaction.
* @param {boolean} privateFee Use a private record to pay the fee. If false this will use the account's public credit balance
* @param {RecordSearchParams | undefined} recordSearchParams Optional parameters for searching for a record to use pay the deployment fee
* @param {string | RecordPlaintext | undefined} feeRecord Optional Fee record to use for the transaction
* @param {PrivateKey | undefined} privateKey Optional private key to use for the transaction
* @returns {string} The transaction id of the deployed program or a failure message from the network
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a program manager with the key provider to automatically fetch keys for deployments
* const program = "program hello_hello.aleo;\n\nfunction hello:\n input r0 as u32.public;\n input r1 as u32.private;\n add r0 r1 into r2;\n output r2 as u32.private;\n";
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
* programManager.setAccount(Account);
*
* // Define a fee in credits
* const priorityFee = 0.0;
*
* // Create the deployment transaction.
* const tx = await programManager.buildDeploymentTransaction(program, fee, false);
* await programManager.networkClient.submitTransaction(tx);
*
* // Verify the transaction was successful
* setTimeout(async () => {
* const transaction = await programManager.networkClient.getTransaction(tx.id());
* assert(transaction.id() === tx.id());
* }, 20000);
*/
buildDeploymentTransaction(program: string, priorityFee: number, privateFee: boolean, recordSearchParams?: RecordSearchParams, feeRecord?: string | RecordPlaintext, privateKey?: PrivateKey): Promise<Transaction>;
/**
* Builds a deployment transaction for submission to the Aleo network that upgrades an existing program.
*
* @param {DeployOptions} options The deployment options.
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a program manager with the key provider to automatically fetch keys for deployments
* const program = "program hello_hello.aleo;\n\nfunction hello:\n input r0 as u32.public;\n input r1 as u32.private;\n add r0 r1 into r2;\n output r2 as u32.private;\n";
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
* programManager.setAccount(Account);
*
* // Define a fee in credits
* const priorityFee = 0.0;
*
* // Create the deployment transaction.
* const tx = await programManager.buildUpgradeTransaction({program: program, priorityFee: fee, privateFee: false});
* await programManager.networkClient.submitTransaction(tx);
*
* // Verify the transaction was successful
* setTimeout(async () => {
* const transaction = await programManager.networkClient.getTransaction(tx.id());
* assert(transaction.id() === tx.id());
* }, 20000);
*/
buildUpgradeTransaction(options: DeployOptions): Promise<Transaction>;
/**
* Deploy an Aleo program to the Aleo network
*
* @param {string} program Program source code
* @param {number} priorityFee The optional fee to be paid for the transaction
* @param {boolean} privateFee Use a private record to pay the fee. If false this will use the account's public credit balance
* @param {RecordSearchParams | undefined} recordSearchParams Optional parameters for searching for a record to used pay the deployment fee
* @param {string | RecordPlaintext | undefined} feeRecord Optional Fee record to use for the transaction
* @param {PrivateKey | undefined} privateKey Optional private key to use for the transaction
* @returns {string} The transaction id of the deployed program or a failure message from the network
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider.
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a program manager with the key provider to automatically fetch keys for deployments
* const program = "program hello_hello.aleo;\n\nfunction hello:\n input r0 as u32.public;\n input r1 as u32.private;\n add r0 r1 into r2;\n output r2 as u32.private;\n";
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
*
* // Define a fee in credits
* const priorityFee = 0.0;
*
* // Deploy the program
* const tx_id = await programManager.deploy(program, fee, false);
*
* // Verify the transaction was successful
* setTimeout(async () => {
* const transaction = await programManager.networkClient.getTransaction(tx_id);
* assert(transaction.id() === tx_id);
* }, 20000);
*/
deploy(program: string, priorityFee: number, privateFee: boolean, recordSearchParams?: RecordSearchParams, feeRecord?: string | RecordPlaintext, privateKey?: PrivateKey): Promise<string>;
/**
* Builds an execution transaction for submission to the Aleo network.
*
* @param {ExecuteOptions} options - The options for the execution transaction.
* @returns {Promise<Transaction>} - A promise that resolves to the transaction or an error.
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider.
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a program manager with the key provider to automatically fetch keys for executions
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
*
* // Build and execute the transaction
* const tx = await programManager.buildExecutionTransaction({
* programName: "hello_hello.aleo",
* functionName: "hello_hello",
* priorityFee: 0.0,
* privateFee: false,
* inputs: ["5u32", "5u32"],
* keySearchParams: { "cacheKey": "hello_hello:hello" }
* });
*
* // Submit the transaction to the network
* await programManager.networkClient.submitTransaction(tx.toString());
*
* // Verify the transaction was successful
* setTimeout(async () => {
* const transaction = await programManager.networkClient.getTransaction(tx.id());
* assert(transaction.id() === tx.id());
* }, 10000);
*/
buildExecutionTransaction(options: ExecuteOptions): Promise<Transaction>;
/**
* Builds an execution transaction for submission to the Aleo network from an Authorization and Fee Authorization.
* This method is helpful if signing and authorization needs to be done in a secure environment separate from where
* transactions are built.
*
* @param {ExecuteAuthorizationOptions} options - The options for executing the authorizations.
* @returns {Promise<Transaction>} - A promise that resolves to the transaction or an error.
*
* @example
* import { AleoKeyProvider, PrivateKey, initThreadPool, ProgramManager } from "@provablehq/sdk";
*
* await initThreadPool();
*
* // Create a new KeyProvider.
* const keyProvider = new AleoKeyProvider();
* keyProvider.useCache(true);
*
* // Initialize a program manager with the key provider to automatically fetch keys for executions.
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider);
*
* // Build the `Authorization`.
* const privateKey = new PrivateKey(); // Change this to a private key that has an aleo credit balance.
* const authorization = await programManager.buildAuthorization({
* programName: "credits.aleo",
* functionName: "transfer_public",
* privateKey,
* inputs: [
* "aleo1vwls2ete8dk8uu2kmkmzumd7q38fvshrht8hlc0a5362uq8ftgyqnm3w08",
* "10000000u64",
* ],
* });
*
* console.log("Getting execution id");
*
* // Derive the execution ID and base fee.
* const executionId = authorization.toExecutionId().toString();
*
* console.log("Estimating fee");
*
* // Get the base fee in microcredits.
* const baseFeeMicrocredits = await programManager.estimateFeeForAuthorization(authorization, "credits.aleo");
* const baseFeeCredits = Number(baseFeeMicrocredits)/1000000;
*
* console.log("Building fee authorization");
*
* // Build a credits.aleo/fee_public `Authorization`.
* const feeAuthorization = await programManager.buildFeeAuthorization({
* deploymentOrExecutionId: executionId,
* baseFeeCredits,
* privateKey
* });
*
* console.log("Executing authorizations");
*
* // Build and execute the transaction.
* const tx = await programManager.buildTransactionFromAuthorization({
* programName: "credits.aleo",
* authorization,
* feeAuthorization,
* });
*
* // Submit the transaction to the network.
* await programManager.networkClient.submitTransaction(tx.toString());
*
* // Verify the transaction was successful.
* setTimeout(async () => {
* const transaction = await programManager.networkClient.getTransaction(tx.id());
* console.log(transaction);
* }, 10000);
*/
buildTransactionFromAuthorization(options: ExecuteAuthorizationOptions): Promise<Transaction>;
/**
* Builds a SnarkVM `Authorization` for a specific function.
*
* @param {AuthorizationOptions} options - The options for building the `Authorization`
* @returns {Promise<Authorization>} - A promise that resolves to an `Authorization` or throws an Error.
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider.
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a ProgramManager with the key and record providers.
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
*
* // Build the `Authorization`.
* const authorization = await programManager.buildAuthorization({
* programName: "credits.aleo",
* functionName: "transfer_public",
* inputs: [
* "aleo1vwls2ete8dk8uu2kmkmzumd7q38fvshrht8hlc0a5362uq8ftgyqnm3w08",
* "10000000u64",
* ],
* });
*/
buildAuthorization(options: AuthorizationOptions): Promise<Authorization>;
/**
* Builds a SnarkVM `Authorization` for a specific function without building a circuit first. This should be used when fast authorization generation is needed and the invoker is confident inputs are coorect.
*
* @param {AuthorizationOptions} options - The options for building the `Authorization`
* @returns {Promise<Authorization>} - A promise that resolves to an `Authorization` or throws an Error.
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider.
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a ProgramManager with the key and record providers.
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
*
* // Build the unchecked `Authorization`.
* const authorization = await programManager.buildAuthorizationUnchecked({
* programName: "credits.aleo",
* functionName: "transfer_public",
* inputs: [
* "aleo1vwls2ete8dk8uu2kmkmzumd7q38fvshrht8hlc0a5362uq8ftgyqnm3w08",
* "10000000u64",
* ],
* });
*/
buildAuthorizationUnchecked(options: AuthorizationOptions): Promise<Authorization>;
/**
* Builds a `ProvingRequest` for submission to a prover for execution. If building a proving request with an ExecutionRequest, a private key must be explicitly provided.
*
* @param {ProvingRequestOptions} options - The options for building the proving request
* @returns {Promise<ProvingRequest>} - A promise that resolves to the transaction or an error.
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider.
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a ProgramManager with the key and record providers.
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
*
* // Build the proving request.
* const provingRequest = await programManager.provingRequest({
* programName: "credits.aleo",
* functionName: "transfer_public",
* priorityFee: 0,
* privateFee: false,
* inputs: [
* "aleo1vwls2ete8dk8uu2kmkmzumd7q38fvshrht8hlc0a5362uq8ftgyqnm3w08",
* "10000000u64",
* ],
* broadcast: false,
* });
*/
provingRequest(options: ProvingRequestOptions): Promise<ProvingRequest>;
/**
* Builds a SnarkVM fee `Authorization` for `credits.aleo/fee_private` or `credits.aleo/fee_public`. If a record is provided `fee_private` will be executed, otherwise `fee_public` will be executed.
*
* @param {FeeAuthorizationOptions} options - The options for building the `Authorization`.
* @returns {Promise<Authorization>} - A promise that resolves to an `Authorization` or throws an Error.
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider.
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a ProgramManager with the key and record providers.
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
*
* // Build a credits.aleo/fee_public `Authorization`.
* const feePublicAuthorization = await programManager.buildFeeAuthorization({
* deploymentOrExecutionId: "2423957656946557501636078245035919227529640894159332581642187482178647335171field",
* baseFeeCredits: 0.1,
* });
*
* // Build a credits.aleo/fee_private `Authorization`.
* const record = "{ owner: aleo1j7qxyunfldj2lp8hsvy7mw5k8zaqgjfyr72x2gh3x4ewgae8v5gscf5jh3.private, microcredits: 1500000000000000u64.private, _nonce: 3077450429259593211617823051143573281856129402760267155982965992208217472983group.public }";
* const feePrivateAuthorization = await programManager.buildFeeAuthorization({
* deploymentOrExecutionId: "2423957656946557501636078245035919227529640894159332581642187482178647335171field",
* baseFeeCredits: 0.1,
* feeRecord: record,
* });
*/
buildFeeAuthorization(options: FeeAuthorizationOptions): Promise<Authorization>;
/**
* Builds an execution transaction for submission to the Aleo network.
*
* @param {ExecuteOptions} options - The options for the execution transaction.
* @returns {Promise<string>} - The transaction id
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider using official Aleo record, key, and network providers
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a program manager with the key provider to automatically fetch keys for executions
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
*
* // Build and execute the transaction
* const tx_id = await programManager.execute({
* programName: "hello_hello.aleo",
* functionName: "hello_hello",
* priorityFee: 0.0,
* privateFee: false,
* inputs: ["5u32", "5u32"],
* keySearchParams: { "cacheKey": "hello_hello:hello" }
* });
*
* // Verify the transaction was successful
* setTimeout(async () => {
* const transaction = await programManager.networkClient.getTransaction(tx_id);
* assert(transaction.id() === tx_id);
* }, 10000);
*/
execute(options: ExecuteOptions): Promise<string>;
/**
* Prepares user-provided inputs for a function call by auto-converting bare
* string identifiers to field elements where the function signature expects
* a `field` type. This lets callers of dynamic-dispatch programs pass
* human-readable strings (e.g. `"my_program"`) instead of requiring
* `stringToField("my_program").toString()`.
*
* Inputs that already look like a numeric field literal (matching
* `/^\d+field$/` after trimming whitespace) are left untouched. Non-field
* inputs are returned as-is. If introspection fails for any reason the
* original inputs are returned unchanged.
*
* @param {string | Program} programSource - The program source code or Program object
* @param {string} functionName - The function to inspect
* @param {string[]} inputs - The raw user-provided inputs
* @returns {string[]} The (possibly converted) inputs
*/
prepareInputs(programSource: string | Program, functionName: string, inputs: string[]): string[];
/**
* Run an Aleo program in offline mode
*
* @param {string} program Program source code containing the function to be executed
* @param {string} function_name Function name to execute
* @param {string[]} inputs Inputs to the function
* @param {number} proveExecution Whether to prove the execution of the function and return an execution transcript that contains the proof.
* @param {string[] | undefined} imports Optional imports to the program
* @param {KeySearchParams | undefined} keySearchParams Optional parameters for finding the matching proving & verifying keys for the function
* @param {ProvingKey | undefined} provingKey Optional proving key to use for the transaction
* @param {VerifyingKey | undefined} verifyingKey Optional verifying key to use for the transaction
* @param {PrivateKey | undefined} privateKey Optional private key to use for the transaction
* @param {OfflineQuery | undefined} offlineQuery Optional offline query if creating transactions in an offline environment
* @returns {Promise<ExecutionResponse>} The execution response containing the outputs of the function and the proof if the program is proved.
*
* @example
* /// Import the mainnet version of the sdk used to build executions.
* import { Account, ProgramManager } from "@provablehq/sdk/mainnet.js";
*
* /// Create the source for the "helloworld" program
* const program = "program helloworld.aleo;\n\nfunction hello:\n input r0 as u32.public;\n input r1 as u32.private;\n add r0 r1 into r2;\n output r2 as u32.private;\n";
* const programManager = new ProgramManager(undefined, undefined, undefined);
*
* /// Create a temporary account for the execution of the program
* const account = new Account();
* programManager.setAccount(account);
*
* /// Get the response and ensure that the program executed correctly
* const executionResponse = await programManager.run(program, "hello", ["5u32", "5u32"]);
* const result = executionResponse.getOutputs();
* assert(result === ["10u32"]);
*/
run(program: string, function_name: string, inputs: string[], proveExecution: boolean, imports?: ProgramImports, keySearchParams?: KeySearchParams, provingKey?: ProvingKey, verifyingKey?: VerifyingKey, privateKey?: PrivateKey, offlineQuery?: OfflineQuery, edition?: number): Promise<ExecutionResponse>;
/**
* Join two credits records into a single credits record
*
* @param {RecordPlaintext | string} recordOne First credits record to join
* @param {RecordPlaintext | string} recordTwo Second credits record to join
* @param {number} priorityFee The optional priority fee to be paid for the transaction
* @param {boolean} privateFee Use a private record to pay the fee. If false this will use the account's public credit balance
* @param {RecordSearchParams | undefined} recordSearchParams Optional parameters for finding the fee record to use to pay the fee for the join transaction
* @param {RecordPlaintext | string | undefined} feeRecord Fee record to use for the join transaction
* @param {PrivateKey | undefined} privateKey Private key to use for the join transaction
* @param {OfflineQuery | undefined} offlineQuery Optional offline query if creating transactions in an offline environment
* @returns {Promise<string>} The transaction id
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a program manager with the key provider to automatically fetch keys for executions
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
* const record_1 = "{ owner: aleo184vuwr5u7u0ha5f5k44067dd2uaqewxx6pe5ltha5pv99wvhfqxqv339h4.private, microcredits: 45000000u64.private, _nonce: 4106205762862305308495708971985748592380064201230396559307556388725936304984group.public}"
* const record_2 = "{ owner: aleo184vuwr5u7u0ha5f5k44067dd2uaqewxx6pe5ltha5pv99wvhfqxqv339h4.private, microcredits: 45000000u64.private, _nonce: 1540945439182663264862696551825005342995406165131907382295858612069623286213group.public}"
* const tx_id = await programManager.join(record_1, record_2, 0.05, false);
*
* // Verify the transaction was successful
* setTimeout(async () => {
* const transaction = await programManager.networkClient.getTransaction(tx_id);
* assert(transaction.id() === tx_id);
* }, 10000);
*/
join(recordOne: RecordPlaintext | string, recordTwo: RecordPlaintext | string, priorityFee: number, privateFee: boolean, recordSearchParams?: RecordSearchParams | undefined, feeRecord?: RecordPlaintext | string | undefined, privateKey?: PrivateKey, offlineQuery?: OfflineQuery): Promise<string>;
/**
* Split credits into two new credits records
*
* @param {number} splitAmount Amount in microcredits to split from the original credits record
* @param {RecordPlaintext | string} amountRecord Amount record to use for the split transaction
* @param {PrivateKey | undefined} privateKey Optional private key to use for the split transaction
* @param {OfflineQuery | undefined} offlineQuery Optional offline query if creating transactions in an offline environment
* @returns {Promise<string>} The transaction id
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a program manager with the key provider to automatically fetch keys for executions
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
* const record = "{ owner: aleo184vuwr5u7u0ha5f5k44067dd2uaqewxx6pe5ltha5pv99wvhfqxqv339h4.private, microcredits: 45000000u64.private, _nonce: 4106205762862305308495708971985748592380064201230396559307556388725936304984group.public}"
* const tx_id = await programManager.split(25000000, record);
*
* // Verify the transaction was successful
* setTimeout(async () => {
* const transaction = await programManager.networkClient.getTransaction(tx_id);
* assert(transaction.id() === tx_id);
* }, 10000);
*/
split(splitAmount: number, amountRecord: RecordPlaintext | string, privateKey?: PrivateKey, offlineQuery?: OfflineQuery): Promise<string>;
/**
* Pre-synthesize proving and verifying keys for a program
*
* @param program {string} The program source code to synthesize keys for
* @param function_id {string} The function id to synthesize keys for
* @param inputs {Array<string>} Sample inputs to the function
* @param privateKey {PrivateKey | undefined} Optional private key to use for the key synthesis
*
* @returns {Promise<FunctionKeyPair>}
*/
synthesizeKeys(program: string, function_id: string, inputs: Array<string>, privateKey?: PrivateKey): Promise<FunctionKeyPair>;
/**
* Build a transaction to transfer credits to another account for later submission to the Aleo network
*
* @param {number} amount The amount of credits to transfer
* @param {string} recipient The recipient of the transfer
* @param {string} transferType The type of transfer to perform - options: 'private', 'privateToPublic', 'public', 'publicToPrivate'
* @param {number} priorityFee The optional priority fee to be paid for the transaction
* @param {boolean} privateFee Use a private record to pay the fee. If false this will use the account's public credit balance
* @param {RecordSearchParams | undefined} recordSearchParams Optional parameters for finding the amount and fee records for the transfer transaction
* @param {RecordPlaintext | string} amountRecord Optional amount record to use for the transfer
* @param {RecordPlaintext | string} feeRecord Optional fee record to use for the transfer
* @param {PrivateKey | undefined} privateKey Optional private key to use for the transfer transaction
* @param {OfflineQuery | undefined} offlineQuery Optional offline query if creating transactions in an offline environment
* @returns {Promise<Transaction>} The transaction object
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a program manager with the key provider to automatically fetch keys for executions
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
* const tx = await programManager.buildTransferTransaction(1, "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px", "public", 0.2, false);
* await programManager.networkClient.submitTransaction(tx.toString());
*
* // Verify the transaction was successful
* setTimeout(async () => {
* const transaction = await programManager.networkClient.getTransaction(tx.id());
* assert(transaction.id() === tx.id());
* }, 10000);
*/
buildTransferTransaction(amount: number, recipient: string, transferType: string, priorityFee: number, privateFee: boolean, recordSearchParams?: RecordSearchParams, amountRecord?: RecordPlaintext | string, feeRecord?: RecordPlaintext | string, privateKey?: PrivateKey, offlineQuery?: OfflineQuery): Promise<Transaction>;
/**
* Build a transfer_public transaction to transfer credits to another account for later submission to the Aleo network
*
* @param {number} amount The amount of credits to transfer
* @param {string} recipient The recipient of the transfer
* @param {number} priorityFee The optional priority fee to be paid for the transfer
* @param {PrivateKey | undefined} privateKey Optional private key to use for the transfer transaction
* @param {OfflineQuery | undefined} offlineQuery Optional offline query if creating transactions in an offline environment
* @returns {Promise<Transaction>} The transaction object
*
* @example
* /// Import the mainnet version of the sdk.
* import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
*
* // Create a new NetworkClient, KeyProvider, and RecordProvider
* const keyProvider = new AleoKeyProvider();
* const recordProvider = new NetworkRecordProvider(account, networkClient);
* keyProvider.useCache(true);
*
* // Initialize a program manager with the key provider to automatically fetch keys for executions
* const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
* const tx = await programManager.buildTransfer