Offline Key Provider

Overview

A key provider meant for building transactions offline on devices such as hardware wallets. This key provider is not able to contact the internet for key material and instead relies on the user to insert Aleo function proving & verifying keys from local storage prior to usage.

Kind: global class

• OfflineSearchParams

  • constructor
    • new OfflineSearchParams(cacheKey, verifyCreditsKeys)
  • static
    • .bondPublicKeyParams() ⇒ OfflineSearchParams
    • .bondValidatorKeyParams() ⇒ OfflineSearchParams
    • .claimUnbondPublicKeyParams() ⇒ OfflineSearchParams
    • .feePrivateKeyParams() ⇒ OfflineSearchParams
    • .feePublicKeyParams() ⇒ OfflineSearchParams
    • .inclusionKeyParams() ⇒ OfflineSearchParams
    • .joinKeyParams() ⇒ OfflineSearchParams
    • .setValidatorStateKeyParams() ⇒ OfflineSearchParams
    • .splitKeyParams() ⇒ OfflineSearchParams
    • .transferPrivateKeyParams() ⇒ OfflineSearchParams
    • .transferPrivateToPublicKeyParams() ⇒ OfflineSearchParams
    • .transferPublicKeyParams() ⇒ OfflineSearchParams
    • .transferPublicAsSignerKeyParams() ⇒ OfflineSearchParams
    • .transferPublicToPrivateKeyParams() ⇒ OfflineSearchParams
    • .unbondPublicKeyParams() ⇒ OfflineSearchParams

• OfflineKeyProvider

  • constructor
    • new OfflineKeyProvider()
  • instance
    • .bondPublicKeys() ⇒ Promise.<FunctionKeyPair>
    • .bondValidatorKeys() ⇒ Promise.<FunctionKeyPair>
    • .cacheKeys(keyId, keys)
    • .claimUnbondPublicKeys() ⇒ Promise.<FunctionKeyPair>
    • .functionKeys(params) ⇒ Promise.<FunctionKeyPair>
    • .verifyCreditsKeys(locator, provingKey, verifyingKey) ⇒ boolean
    • .feePrivateKeys() ⇒ Promise.<FunctionKeyPair>
    • .feePublicKeys() ⇒ Promise.<FunctionKeyPair>
    • .inclusionKeys() ⇒ Promise.<FunctionKeyPair>
    • .joinKeys() ⇒ Promise.<FunctionKeyPair>
    • .splitKeys() ⇒ Promise.<FunctionKeyPair>
    • .transferKeys(visibility) ⇒ Promise.<FunctionKeyPair>
    • .unBondPublicKeys() ⇒ Promise.<FunctionKeyPair>
    • .insertBondPublicKeys(provingKey)
    • .insertClaimUnbondPublicKeys(provingKey)
    • .insertFeePrivateKeys(provingKey)
    • .insertFeePublicKeys(provingKey)
    • .insertInclusionKeys(provingKey)
    • .insertJoinKeys(provingKey)
    • .insertSetValidatorStateKeys(provingKey)
    • .insertSplitKeys(provingKey)
    • .insertTransferPrivateKeys(provingKey)
    • .insertTransferPrivateToPublicKeys(provingKey)
    • .insertTransferPublicKeys(provingKey)
    • .insertTransferPublicToPrivateKeys(provingKey)
    • .insertUnbondPublicKeys(provingKey)

Class OfflineSearchParams

Search parameters for the offline key provider. This class implements the KeySearchParams interface and includes a convenience method for creating a new instance of this class for each function of the credits.aleo program.

Constructor

Create a new OfflineSearchParams instance for searching keys in the offline key provider cache.

new OfflineSearchParams(cacheKey, verifyCreditsKeys)

Param	Type	Description
cacheKey	string	Key used to store the local function proving & verifying keys. This should be stored under the naming convention "programName/functionName" (i.e. "myprogram.aleo/myfunction")
verifyCreditsKeys	boolean	Optional. Whether to verify the keys against the credits.aleo program, defaults to false, but should be set to true if using keys from the credits.aleo program

Example

// If storing a key for a custom program function
const offlineSearchParams = new OfflineSearchParams("myprogram.aleo/myfunction");

// If storing a key for a credits.aleo program function
const bondPublicKeyParams = OfflineSearchParams.bondPublicKeyParams();

Static Methods

bondPublicKeyParams

Creates pre-configured OfflineSearchParams for the bond_public function of the credits.aleo program.

OfflineSearchParams.bondPublicKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the bond_public function

---

bondValidatorKeyParams

Creates pre-configured OfflineSearchParams for the bond_validator function of the credits.aleo program.

OfflineSearchParams.bondValidatorKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the bond_validator function

---

claimUnbondPublicKeyParams

Creates pre-configured OfflineSearchParams for the claim_unbond_public function of the credits.aleo program.

OfflineSearchParams.claimUnbondPublicKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the claim_unbond_public function

---

feePrivateKeyParams

Creates pre-configured OfflineSearchParams for the fee_private function of the credits.aleo program.

OfflineSearchParams.feePrivateKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the fee_private function

---

feePublicKeyParams

Creates pre-configured OfflineSearchParams for the fee_public function of the credits.aleo program.

OfflineSearchParams.feePublicKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the fee_public function

---

inclusionKeyParams

Creates pre-configured OfflineSearchParams for the inclusion prover function.

OfflineSearchParams.inclusionKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the inclusion prover function

---

joinKeyParams

Creates pre-configured OfflineSearchParams for the join function of the credits.aleo program.

OfflineSearchParams.joinKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the join function

---

setValidatorStateKeyParams

Creates pre-configured OfflineSearchParams for the set_validator_state function of the credits.aleo program.

OfflineSearchParams.setValidatorStateKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the set_validator_state function

---

splitKeyParams

Creates pre-configured OfflineSearchParams for the split function of the credits.aleo program.

OfflineSearchParams.splitKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the split function

---

transferPrivateKeyParams

Creates pre-configured OfflineSearchParams for the transfer_private function of the credits.aleo program.

OfflineSearchParams.transferPrivateKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the transfer_private function

---

transferPrivateToPublicKeyParams

Creates pre-configured OfflineSearchParams for the transfer_private_to_public function of the credits.aleo program.

OfflineSearchParams.transferPrivateToPublicKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the transfer_private_to_public function

---

transferPublicKeyParams

Creates pre-configured OfflineSearchParams for the transfer_public function of the credits.aleo program.

OfflineSearchParams.transferPublicKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the transfer_public function

---

transferPublicAsSignerKeyParams

Creates pre-configured OfflineSearchParams for the transfer_public_as_signer function of the credits.aleo program.

OfflineSearchParams.transferPublicAsSignerKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the transfer_public_as_signer function

---

transferPublicToPrivateKeyParams

Creates pre-configured OfflineSearchParams for the transfer_public_to_private function of the credits.aleo program.

OfflineSearchParams.transferPublicToPrivateKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the transfer_public_to_private function

---

unbondPublicKeyParams

Creates pre-configured OfflineSearchParams for the unbond_public function of the credits.aleo program.

OfflineSearchParams.unbondPublicKeyParams()

Parameters	Type	Description
return	OfflineSearchParams	Search params for the unbond_public function

---

Class OfflineKeyProvider

Constructor

Create a new OfflineKeyProvider instance for managing keys offline on devices such as hardware wallets.

new OfflineKeyProvider()

Example

import { OfflineKeyProvider } from "@provablehq/sdk/mainnet.js";

// Create an offline key provider
const offlineKeyProvider = new OfflineKeyProvider();

---

OfflineKeyProvider Example

// Create an offline program manager
const programManager = new ProgramManager();

// Create a temporary account for the execution of the program
const account = new Account();
programManager.setAccount(account);

// Create the proving keys from the key bytes on the offline machine
console.log("Creating proving keys from local key files");
const program = "program hello_hello.aleo; function hello: input r0 as u32.public; input r1 as u32.private; add r0 r1 into r2; output r2 as u32.private;";
const myFunctionProver = await getLocalKey("/path/to/my/function/hello_hello.prover");
const myFunctionVerifier = await getLocalKey("/path/to/my/function/hello_hello.verifier");
const feePublicProvingKeyBytes = await getLocalKey("/path/to/credits.aleo/feePublic.prover");

const myFunctionProvingKey = ProvingKey.fromBytes(myFunctionProver);
const myFunctionVerifyingKey = VerifyingKey.fromBytes(myFunctionVerifier);
const feePublicProvingKey = ProvingKey.fromBytes(feePublicProvingKeyBytes);

// Create an offline key provider
console.log("Creating offline key provider");
const offlineKeyProvider = new OfflineKeyProvider();

// Cache the keys
// Cache the proving and verifying keys for the custom hello function
offlineKeyProvider.cacheKeys("hello_hello.aleo/hello", [myFunctionProvingKey, myFunctionVerifyingKey]);

// Cache the proving key for the fee_public function (the verifying key is automatically cached)
offlineKeyProvider.insertFeePublicKeys(feePublicProvingKey);

// Create an offline query using the latest state root in order to create the inclusion proof
const offlineQuery = new OfflineQuery("latestStateRoot");

// Insert the key provider into the program manager
programManager.setKeyProvider(offlineKeyProvider);

// Create the offline search params
const offlineSearchParams = new OfflineSearchParams("hello_hello.aleo/hello");

// Create the offline transaction
const offlineExecuteTx = await programManager.buildExecutionTransaction({
    programName: "hello_hello.aleo",
    functionName: "hello",
    priorityFee: 1,
    privateFee: false,
    inputs: ["5u32", "5u32"],
    keySearchParams: offlineSearchParams,
    offlineQuery: offlineQuery,
    program: program
});

// Broadcast the transaction later on a machine with internet access
const networkClient = new AleoNetworkClient("https://api.explorer.provable.com/v1");
const txId = await networkClient.submitTransaction(offlineExecuteTx);

Methods

bondPublicKeys

Get bond_public function keys from the credits.aleo program. The keys must be cached prior to calling this method for it to work.

bondPublicKeys()

Parameters	Type	Description
return	Promise.<FunctionKeyPair>	Proving and verifying keys for the bond_public function

---

bondValidatorKeys

Get bond_validator function keys from the credits.aleo program. The keys must be cached prior to calling this method for it to work.

bondValidatorKeys()

Parameters	Type	Description
return	Promise.<FunctionKeyPair>	Proving and verifying keys for the bond_public function

---

cacheKeys

Cache a set of keys. This will overwrite any existing keys with the same keyId. The user can check if a keyId exists in the cache using the containsKeys method prior to calling this method if overwriting is not desired.

cacheKeys(keyId, keys)

Parameters	Type	Description
keyId	string	access key for the cache
keys	FunctionKeyPair	keys to cache

---

claimUnbondPublicKeys

Get unbond_public function keys from the credits.aleo program. The keys must be cached prior to calling this method for it to work.

claimUnbondPublicKeys()

Parameters	Type	Description
return	Promise.<FunctionKeyPair>	Proving and verifying keys for the unbond_public function

---

functionKeys

Get arbitrary function key from the offline key provider cache.

functionKeys(params)

Parameters	Type	Description
params	KeySearchParams	Optional search parameters for the key provider
return	Promise.<FunctionKeyPair>	Proving and verifying keys for the specified program

Examples

/// First cache the keys from local offline resources
const offlineKeyProvider = new OfflineKeyProvider();
const myFunctionVerifyingKey = VerifyingKey.fromString("verifier...");
const myFunctionProvingKeyBytes = await readBinaryFile('./resources/myfunction.prover');
const myFunctionProvingKey = ProvingKey.fromBytes(myFunctionProvingKeyBytes);

/// Cache the keys for future use with a memorable locator
offlineKeyProvider.cacheKeys("myprogram.aleo/myfunction", [myFunctionProvingKey, myFunctionVerifyingKey]);

/// When they're needed, retrieve the keys from the cache

/// First create a search parameter object with the same locator used to cache the keys
const keyParams = new OfflineSearchParams("myprogram.aleo/myfunction");

/// Then retrieve the keys
const [myFunctionProver, myFunctionVerifier] = await offlineKeyProvider.functionKeys(keyParams);

---

verifyCreditsKeys

Determines if the keys for a given credits function match the expected keys.

verifyCreditsKeys(locator, provingKey, verifyingKey) ⇒ boolean

Parameters	Type	Description
locator	string	The locator of the credits function (e.g. "credits.aleo/transfer_public")
provingKey	ProvingKey	The proving key to verify
verifyingKey	VerifyingKey	The verifying key to verify
return	boolean	Whether the keys match the expected keys

---

feePrivateKeys

Get fee_private function keys from the credits.aleo program. The keys must be cached prior to calling this method for it to work.

feePrivateKeys()

Parameters	Type	Description
return	Promise.<FunctionKeyPair>	Proving and verifying keys for the join function

---

feePublicKeys

Get fee_public function keys from the credits.aleo program. The keys must be cached prior to calling this method for it to work.

feePublicKeys()

Parameters	Type	Description
return	Promise.<FunctionKeyPair>	Proving and verifying keys for the fee_public function

---

inclusionKeys

Get the inclusion prover keys. The keys must be cached prior to calling this method for it to work.

inclusionKeys()

Parameters	Type	Description
return	Promise.<FunctionKeyPair>	Proving and verifying keys for the inclusion prover

---

joinKeys

Get join function keys from the credits.aleo program. The keys must be cached prior to calling this method for it to work.

joinKeys()

Parameters	Type	Description
return	Promise.<FunctionKeyPair>	Proving and verifying keys for the join function

---

splitKeys

Get split function keys from the credits.aleo program. The keys must be cached prior to calling this method for it to work.

splitKeys()

Parameters	Type	Description
return	Promise.<FunctionKeyPair>	Proving and verifying keys for the join function

---

transferKeys

Get keys for a variant of the transfer function from the credits.aleo program.

transferKeys(visibility)

Parameters	Type	Description
visibility	string	Visibility of the transfer function (private, public, privateToPublic, publicToPrivate)
return	Promise.<FunctionKeyPair>	Proving and verifying keys for the specified transfer function

Examples

// Create a new OfflineKeyProvider
const offlineKeyProvider = new OfflineKeyProvider();

// Cache the keys for future use with the official locator
const transferPublicProvingKeyBytes = await readBinaryFile('./resources/transfer_public.prover.a74565e');
const transferPublicProvingKey = ProvingKey.fromBytes(transferPublicProvingKeyBytes);

// Cache the transfer_public keys for future use with the OfflinKeyProvider's convenience method for
// transfer_public (the verifying key will be cached automatically)
offlineKeyProvider.insertTransferPublicKeys(transferPublicProvingKey);

/// When they're needed, retrieve the keys from the cache
const [transferPublicProvingKey, transferPublicVerifyingKey] = await keyProvider.transferKeys("public");

---

unBondPublicKeys

Get unbond_public function keys from the credits.aleo program

unBondPublicKeys()

Parameters	Type	Description
return	Promise.<FunctionKeyPair>	Proving and verifying keys for the join function

---

insertBondPublicKeys

Insert the proving and verifying keys for the bond_public function into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for bond_public before inserting them into the cache.

insertBondPublicKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the bond_public function

---

insertClaimUnbondPublicKeys

Insert the proving and verifying keys for the claim_unbond_public function into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for claim_unbond_public before inserting them into the cache.

insertClaimUnbondPublicKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the claim_unbond_public function

---

insertFeePrivateKeys

Insert the proving and verifying keys for the fee_private function into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for fee_private before inserting them into the cache.

insertFeePrivateKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the fee_private function

---

insertFeePublicKeys

Insert the proving and verifying keys for the fee_public function into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for fee_public before inserting them into the cache.

insertFeePublicKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the fee_public function

---

insertInclusionKeys

Insert the proving and verifying keys for the inclusion prover into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for the inclusion prover.

insertInclusionKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the inclusion prover

---

insertJoinKeys

Insert the proving and verifying keys for the join function into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for join before inserting them into the cache.

insertJoinKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the join function

---

insertSetValidatorStateKeys

Insert the proving and verifying keys for the set_validator_state function into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for set_validator_state before inserting them into the cache.

insertSetValidatorStateKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the set_validator_state function

---

insertSplitKeys

Insert the proving and verifying keys for the split function into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for split before inserting them into the cache.

insertSplitKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the split function

---

insertTransferPrivateKeys

Insert the proving and verifying keys for the transfer_private function into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for transfer_private before inserting them into the cache.

insertTransferPrivateKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the transfer_private function

---

insertTransferPrivateToPublicKeys

Insert the proving and verifying keys for the transfer_private_to_public function into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for transfer_private_to_public before inserting them into the cache.

insertTransferPrivateToPublicKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the transfer_private_to_public function

---

insertTransferPublicKeys

Insert the proving and verifying keys for the transfer_public function into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for transfer_public before inserting them into the cache.

insertTransferPublicKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the transfer_public function

---

insertTransferPublicToPrivateKeys

Insert the proving and verifying keys for the transfer_public_to_private function into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for transfer_public_to_private before inserting them into the cache.

insertTransferPublicToPrivateKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the transfer_public_to_private function

---

insertUnbondPublicKeys

Insert the proving and verifying keys for the unbond_public function into the cache. Only the proving key needs to be inserted, the verifying key is automatically inserted by the SDK. This function will automatically check that the keys match the expected checksum for unbond_public before inserting them into the cache.

insertUnbondPublicKeys(provingKey)

Parameters	Type	Description
provingKey	ProvingKey	The proving key for the unbond_public function