@provablehq/sdk 0.8.0 → 0.8.1

package/README.md

@@ -12,20 +12,23 @@
 
 ## Tools for Building Zero-Knowledge Web Apps
 
-The Aleo SDK is a collection of JavaScript libraries for building zero-knowledge web applications in both the browser
-and Node.js.
+The Aleo SDK is a JavaScript library for building zero-knowledge web applications in both web browsers and Node.js.
 
 ## Overview
 
-Aleo provides the ability to run programs with the power of zero-knowledge. The Aleo SDK provides the tools to use these programs
-within the browser and all other levels of the web stack to build privacy-preserving applications.
+Aleo provides the ability for users to create programs and execute them in zero knowledge through the usage of the 
+[Varuna ZKSnark](https://alphaswapdex.medium.com/part-ii-the-technical-architecture-of-the-aleo-blockchain-marlin-and-varuna-71c6d48eb355).
+
+The Aleo SDK provides the tools to use these programs both within Nodejs and web browsers allowing users to build
+ privacy-preserving applications throughout the web stack.
 
 The Aleo SDK provides the following functionality (Click to see examples):
 1. [Aleo account management](https://provable.tools/account)
 2. [Web-based program execution and deployment](https://provable.tools/develop)
 3. [Aleo credit transfers](https://provable.tools/transfer)
-4. [Management of program state and data](https://provable.tools/record)
-5. [Communication with the Aleo network](https://provable.tools/rest)
+4. [Management of program state and data](https://provable.tools/protocol)
+5. [Interaction with the Aleo network](https://provable.tools/rest)
+6. [Exposure of Core Aleo Cryptographic Primtives](https://provable.tools/algebra)
 
 ## Table of Contents
 
@@ -64,11 +67,15 @@ To clone the repository, run:
 
 `git clone git@github.com:ProvableHQ/sdk.git`
 
-### NPM
+### NPM & YARN
 
 To install the Aleo SDK from NPM run:
 
-`npm install @provablehq/sdk` in your own project's root, or from within this repo run `cd sdk && yarn add @provablehq/sdk`.
+`npm install @provablehq/sdk` in your own project's root,
+
+To install the Aleo SDK from Yarn run:
+
+`yarn add @provablehq/sdk`.
 
 ### Build from source
 
@@ -90,36 +97,41 @@ In your project's `package.json`, ensure that the following line is added above
 
 ### Create Leo App
 A set of fully functional examples of zero-knowledge web apps can be found in
-[create-leo-app](https://github.com/ProvableHQ/sdk/tree/testnet3/create-leo-app). Create Leo App provides several web app
+[create-leo-app](https://github.com/ProvableHQ/sdk/tree/mainnet/create-leo-app). Create Leo App provides several web app
 templates in common web frameworks such as React that can be used as a starting point for building zero-knowledge web apps.
 
 Developers can get started immediately with create-leo-app by running:
 `npm create leo-app@latest`
 
-### provable.tools
+### Provable.tools
 
 Additionally, the SDK powers [provable.tools](https://provable.tools) - a React app that provides a graphical interface for most
 of the functionality provided by the SDK and can be used as a reference for usage of the SDK. Source code for provable.tools
-can be found [in the SDK repo here](https://github.com/ProvableHQ/sdk/tree/testnet3/website).
+can be found [in the website directory of the SDK repo](https://github.com/ProvableHQ/sdk/tree/mainnet/website).
 
 ## Usage
 
 ## 1. Create an Aleo Account
 
 The first step in operating a zero-knowledge web application is creating a private key which serves as a cryptographic
-identity for a user. After a private key is generated, several keys that enable specialized methods of interacting with
-Aleo programs can be derived.
+identity for a user. From it, the user's address and several other useful cryptographic keys that comprise the user's 
+identity are derived.
+
+The total list of keys which comprise an Aleo account are as follows:
 
-These keys include:
 #### Private Key
-The `Private Key` can be treated as the identity of a user. It is used for critical functions like authorizing zero-knowledge
-program execution, decrypting private data, and proving ownership of user data.
+The `Private Key` can be thought of as the identity of a user and is the most sensitive of the keys within an Aleo account. 
+It is used to sign and create new program executions, to encrypt & decrypt private data within a zero knowledge function 
+execution, and to generate signatures, commitments, and other key material used in zero-knowledge proofs.
 
 #### View Key
 The `View Key` is derived from the private key and can be used to both decrypt encrypted data owned by a user and prove
-ownership of that data.
+ownership of that data. Specific usages of this key include, determining ownership of records, decrypting records, 
+and decrypting private inputs or outputs of a zero-knowledge program generated by the owner of the private key.
+
 #### Compute Key
 The `Compute Key` can be used to trustlessly run applications and generate transactions on a user's behalf.
+
 #### Address
 The `Address` is a user's unique public identifier. It serves as an address for a user to receive both Aleo
 credits and data from other zero-knowledge Aleo programs.
@@ -142,15 +154,15 @@ Please note that all keys are considered sensitive information and should be sto
 
 ### 2.1 Aleo Programs
 
-Aleo programs provide the ability for users to make any input or output of a program private and prove that the program
-was run correctly. Keeping program inputs and outputs private allows developers to build privacy into their applications.
+Aleo programs provide the ability for users to make any input or output of a program function private and prove that the
+function was run correctly without exposing the values of these inputs or outputs. This allows developers to build 
+applications with complete data privacy.
 
-Zero-knowledge programs are written in one of two languages:
-1. [Leo](https://docs.leo-lang.org/leo/language): A high-level, developer-friendly language for developing
-zero-knowledge programs.
+Zero-knowledge programs on Aleo are written in one of two languages:
+1. [Leo](https://docs.leo-lang.org/leo/language): A high-level, developer-friendly language for developing zero-knowledge programs.
 
-2. [Aleo Instructions](https://docs.leo-lang.org/aleo/language): A low-level language that provides developers with fine-grained control over the execution flow of zero-knowledge programs. Leo code is compiled into Aleo Instructions
-under the hood.
+2. [Aleo Instructions](https://docs.leo-lang.org/aleo/language): A low-level language that provides developers with fine-grained control over the execution 
+flow of zero-knowledge programs. Leo code is compiled into Aleo Instructions under the hood.
 
 Documentation for both languages can be found at [docs.leo-lang.org](https://docs.leo-lang.org/).
 
@@ -179,44 +191,45 @@ function hello:
 
 ### 2.2 Program Execution Model
 
-The SDK provides the ability to execute Aleo programs 100% client-side within the browser.
+#### Lifecycle of a Program Execution
+
+When an Aleo program is executed, the following steps occur:
+
+1. **Compilation into an R1CS Circuit:** The function code is compiled into an R1CS circuit and checked for correctness 
+(or more formally, satisfiability).
+2. **Proof of Satisfiability:** The valid R1CS circuit is encoded into a polynomial representation that is then turned
+into a Varuna ZKSnark proof which proves both that the executor is executing the correct function and that the inputs 
+lead to the stated outputs.
+3. **Transaction Generation:** The zero knowledge proof is stored within an `Execution Transaction` and sent to the Aleo
+network. This transaction is then verified by the Aleo network's validator nodes.
+4. **Optional Execution of On-Chain Logic:** Any Aleo function can optionally contain on-chain logic to be executed by
+the Aleo Network's validator nodes. This logic can be used to do further computations and update on-chain key-value 
+stores called `mappings` which store a program's public on-chain state.
+5. **Addition to the Ledger**: If the proof is valid, the transaction is added to the Aleo ledger within a 
+specific block and all changes the execution made to the program's state are recorded within the Aleo blockchain.
+
+
+#### Program Execution with the Aleo SDK
+
+The SDK provides the ability to execute Aleo programs 100% client-side within the browser or Node.js.
 
 The `ProgramManager` object encapsulates the functionality for executing programs and making zero-knowledge proofs about
 them. Under the hood it uses cryptographic code compiled from [SnarkVM](https://docs.leo-lang.org/aleo) into WebAssembly
-with JavaScript bindings that allow for the execution of Aleo programs fully within the browser. Users interested in lower-level
-details on how this is achieved can visit the [aleo-wasm](https://www.npmjs.com/package/@provablehq/wasm) crate.
-
-The basic execution flow of a program is as follows:
-1. A web app is loaded with an instance of the `ProgramManager` object.
-2. The SDK wasm modules are loaded into the browser's WebAssembly runtime.
-2. An Aleo program in `Aleo Instructions` format is loaded into the `ProgramManager` as a wasm object.
-3. The web app provides a user input form for the program.
-4. The user submits the inputs and the zero-knowledge execution is performed entirely within the browser via WebAssembly.
-5. The result is returned to the user.
-6. A fully encrypted zero-knowledge transcript of the execution is optionally sent to the Aleo network.
-
-A diagramatic representation of the program execution flow is shown below:
-```mermaid
-graph LR
-    p1[Leo Program]
-    p2[Aleo Instructions]
-
-    subgraph Browser Web-App
-        subgraph ProgramManager
-            subgraph Aleo-Wasm-Module
-                in-memory-program
-            end
-        end
-    end
+with JavaScript bindings that allow for the execution of Aleo programs fully within the browser. 
 
-    p1-->p2--load program--oin-memory-program-.ZK result.->user
-    user-.user input.->in-memory-program
-    in-memory-program-."ZK result (Optional)".->Aleo-Network
-```
+The basic execution flow of a program within the SDK is as follows:
+1. A web app creates an instance of the `ProgramManager` object.
+2. The SDK wasm modules are loaded into the `WebAssembly` runtime.
+3. An Aleo program in `Aleo Instructions` format is loaded into `WebAssembly` via the `ProgramManager` object.
+4. The web or node app takes user input and begins execution of a program.
+5. The execution is performed entirely within Node.js or the browser via WebAssembly.
+6. The result is returned to the javascript environment in the form of an `Execution Transaction`.
+7. The execution is sent to the Aleo network.
 
-### 2.3 Multithreading
+### 2.3 WebAssembly Initialization
 
-You can enable multithreading by calling the `initThreadPool` function. This will run the SDK on multiple workers, which significantly speeds up performance:
+You can enable multithreading by calling the `initThreadPool` function. This will run the SDK on multiple workers, 
+which significantly speeds up performance:
 
 ```typescript
 import { Account, initThreadPool } from '@provablehq/sdk';
@@ -421,7 +434,7 @@ Program execution is a computationally-expensive process. For this reason, it is
 web workers. Create-Leo-App will automatically create a web worker for you that performs the execution called `worker.js`.
 
 
-A full example of this implementation can be found [here](https://github.com/ProvableHQ/sdk/tree/testnet3/create-leo-app/template-vanilla)
+A full example of this implementation can be found [here](https://github.com/ProvableHQ/sdk/tree/mainnet/create-leo-app/template-vanilla)
 
 ## 3. Aleo Credit Transfers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provablehq/sdk",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "A Software Development Kit (SDK) for Zero-Knowledge Transactions",
   "collaborators": [
     "The Provable Team"
@@ -48,34 +48,34 @@
   "homepage": "https://github.com/ProvableHQ/sdk#readme",
   "dependencies": {
     "@provablehq/wasm": "^0.8.0",
-    "comlink": "^4.4.1",
-    "core-js": "^3.38.1",
-    "mime": "^3.0.0",
-    "sync-request": "^6.1.0"
+    "comlink": "^4.4.2",
+    "core-js": "^3.40.0",
+    "mime": "^4.0.6",
+    "sync-request": "^6.1.0",
+    "xmlhttprequest-ssl": "^3.1.0"
   },
   "devDependencies": {
-    "@rollup/plugin-replace": "^5.0.5",
-    "@types/chai": "^4.3.16",
-    "@types/mime": "^3.0.1",
-    "@types/mocha": "^10.0.7",
+    "@rollup/plugin-replace": "^6.0.2",
+    "@types/chai": "^5.0.1",
+    "@types/mocha": "^10.0.10",
     "@types/sinon": "^17.0.3",
-    "@typescript-eslint/eslint-plugin": "^5.41.0",
-    "@typescript-eslint/parser": "^5.41.0",
+    "@typescript-eslint/eslint-plugin": "^8.22.0",
+    "@typescript-eslint/parser": "^8.22.0",
     "better-docs": "^2.7.3",
-    "chai": "^5.1.1",
+    "chai": "^5.1.2",
     "clean-jsdoc-theme": "^4.3.0",
     "cpr": "^3.0.1",
-    "eslint": "^8.26.0",
-    "eslint-config-prettier": "^8.5.0",
-    "eslint-plugin-import": "^2.26.0",
-    "glob": "^10.4.5",
-    "jsdoc": "^3.6.11",
-    "mocha": "^10.7.0",
-    "prettier": "2.7.1",
-    "rimraf": "^5.0.1",
-    "rollup": "^3.27.2",
+    "eslint": "^9.19.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-import": "^2.31.0",
+    "glob": "^11.0.1",
+    "jsdoc": "^4.0.4",
+    "mocha": "^11.1.0",
+    "prettier": "3.4.2",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.32.0",
     "rollup-plugin-typescript2": "^0.36.0",
-    "sinon": "^18.0.0",
-    "typescript": "^5.2.2"
+    "sinon": "^19.0.2",
+    "typescript": "^5.7.3"
   }
 }

package/dist/mainnet/account.d.ts

@@ -1,137 +0,0 @@
-import { Address, PrivateKey, Signature, ViewKey, PrivateKeyCiphertext, RecordCiphertext } from "./wasm";
-interface AccountParam {
-    privateKey?: string;
-    seed?: Uint8Array;
-}
-/**
- * Key Management class. Enables the creation of a new Aleo Account, importation of an existing account from
- * an existing private key or seed, and message signing and verification functionality.
- *
- * An Aleo Account is generated from a randomly generated seed (number) from which an account private key, view key,
- * and a public account address are derived. The private key lies at the root of an Aleo account. It is a highly
- * sensitive secret and should be protected as it allows for creation of Aleo Program executions and arbitrary value
- * transfers. The View Key allows for decryption of a user's activity on the blockchain. The Address is the public
- * address to which other users of Aleo can send Aleo credits and other records to. This class should only be used
- * environments where the safety of the underlying key material can be assured.
- *
- * @example
- * // Create a new account
- * const myRandomAccount = new Account();
- *
- * // Create an account from a randomly generated seed
- * const seed = new Uint8Array([94, 91, 52, 251, 240, 230, 226, 35, 117, 253, 224, 210, 175, 13, 205, 120, 155, 214, 7, 169, 66, 62, 206, 50, 188, 40, 29, 122, 40, 250, 54, 18]);
- * const mySeededAccount = new Account({seed: seed});
- *
- * // Create an account from an existing private key
- * const myExistingAccount = new Account({privateKey: 'myExistingPrivateKey'})
- *
- * // Sign a message
- * const hello_world = Uint8Array.from([104, 101, 108, 108, 111 119, 111, 114, 108, 100])
- * const signature = myRandomAccount.sign(hello_world)
- *
- * // Verify a signature
- * myRandomAccount.verify(hello_world, signature)
- */
-export declare class Account {
-    _privateKey: PrivateKey;
-    _viewKey: ViewKey;
-    _address: Address;
-    constructor(params?: AccountParam);
-    /**
-     * Attempts to create an account from a private key ciphertext
-     * @param {PrivateKeyCiphertext | string} ciphertext
-     * @param {string} password
-     * @returns {PrivateKey}
-     *
-     * @example
-     * const ciphertext = PrivateKey.newEncrypted("password");
-     * const account = Account.fromCiphertext(ciphertext, "password");
-     */
-    static fromCiphertext(ciphertext: PrivateKeyCiphertext | string, password: string): Account;
-    private privateKeyFromParams;
-    privateKey(): PrivateKey;
-    viewKey(): ViewKey;
-    address(): Address;
-    toString(): any;
-    /**
-     * Encrypt the account's private key with a password
-     * @param {string} ciphertext
-     * @returns {PrivateKeyCiphertext}
-     *
-     * @example
-     * const account = new Account();
-     * const ciphertext = account.encryptAccount("password");
-     */
-    encryptAccount(password: string): any;
-    /**
-     * Decrypts a Record in ciphertext form into plaintext
-     * @param {string} ciphertext
-     * @returns {Record}
-     *
-     * @example
-     * const account = new Account();
-     * const record = account.decryptRecord("record1ciphertext");
-     */
-    decryptRecord(ciphertext: string): any;
-    /**
-     * Decrypts an array of Records in ciphertext form into plaintext
-     * @param {string[]} ciphertexts
-     * @returns {Record[]}
-     *
-     * @example
-     * const account = new Account();
-     * const record = account.decryptRecords(["record1ciphertext", "record2ciphertext"]);
-     */
-    decryptRecords(ciphertexts: string[]): any[];
-    /**
-     * Determines whether the account owns a ciphertext record
-     * @param {RecordCipherText | string} ciphertext
-     * @returns {boolean}
-     *
-     * @example
-     * // Create a connection to the Aleo network and an account
-     * const connection = new AleoNetworkClient("https://api.explorer.provable.com/v1");
-     * const account = Account.fromCiphertext("ciphertext", "password");
-     *
-     * // Get a record from the network
-     * const record = connection.getBlock(1234);
-     * const recordCipherText = record.transactions[0].execution.transitions[0].id;
-     *
-     * // Check if the account owns the record
-     * if account.ownsRecord(recordCipherText) {
-     *     // Then one can do something like:
-     *     // Decrypt the record and check if it's spent
-     *     // Store the record in a local database
-     *     // Etc.
-     * }
-     */
-    ownsRecordCiphertext(ciphertext: RecordCiphertext | string): any;
-    /**
-     * Signs a message with the account's private key.
-     * Returns a Signature.
-     *
-     * @param {Uint8Array} message
-     * @returns {Signature}
-     *
-     * @example
-     * const account = new Account();
-     * const message = Uint8Array.from([104, 101, 108, 108, 111 119, 111, 114, 108, 100])
-     * account.sign(message);
-     */
-    sign(message: Uint8Array): any;
-    /**
-     * Verifies the Signature on a message.
-     *
-     * @param {Uint8Array} message
-     * @param {Signature} signature
-     * @returns {boolean}
-     *
-     * @example
-     * const account = new Account();
-     * const message = Uint8Array.from([104, 101, 108, 108, 111 119, 111, 114, 108, 100])
-     * const signature = account.sign(message);
-     * account.verify(message, signature);
-     */
-    verify(message: Uint8Array, signature: Signature): any;
-}
-export {};

package/dist/mainnet/browser.d.ts

@@ -1,35 +0,0 @@
-import "./polyfill/shared";
-import { Account } from "./account";
-import { AleoNetworkClient, ProgramImports } from "./network-client";
-import { BlockJSON, Header, Metadata } from "./models/blockJSON";
-import { ConfirmedTransactionJSON } from "./models/confirmed_transaction";
-import { DeploymentJSON, VerifyingKeys } from "./models/deployment/deploymentJSON";
-import { DeploymentObject } from "./models/deployment/deploymentObject";
-import { ExecutionJSON, FeeExecutionJSON } from "./models/execution/executionJSON";
-import { ExecutionObject, FeeExecutionObject } from "./models/execution/executionObject";
-import { FinalizeJSON } from "./models/finalizeJSON";
-import { FunctionObject } from "./models/functionObject";
-import { InputJSON } from "./models/input/inputJSON";
-import { InputObject } from "./models/input/inputObject";
-import { OutputJSON } from "./models/output/outputJSON";
-import { OutputObject } from "./models/output/outputObject";
-import { OwnerJSON } from "./models/owner/ownerJSON";
-import { PlaintextArray } from "./models/plaintext/array";
-import { PlaintextLiteral } from "./models/plaintext/literal";
-import { PlaintextObject } from "./models/plaintext/plaintext";
-import { PlaintextStruct } from "./models/plaintext/struct";
-import { TransactionJSON } from "./models/transaction/transactionJSON";
-import { TransactionObject } from "./models/transaction/transactionObject";
-import { TransitionJSON } from "./models/transition/transitionJSON";
-import { TransitionObject } from "./models/transition/transitionObject";
-import { AleoKeyProvider, AleoKeyProviderParams, AleoKeyProviderInitParams, CachedKeyPair, FunctionKeyPair, FunctionKeyProvider, KeySearchParams } from "./function-key-provider";
-import { OfflineKeyProvider, OfflineSearchParams } from "./offline-key-provider";
-import { BlockHeightSearch, NetworkRecordProvider, RecordProvider, RecordSearchParams } from "./record-provider";
-declare function initializeWasm(): Promise<void>;
-export { createAleoWorker } from "./managed-worker";
-export { ProgramManager } from "./program-manager";
-export { logAndThrow } from "./utils";
-export { Address, Ciphertext, Execution as FunctionExecution, ExecutionResponse, Field, Group, OfflineQuery, Plaintext, PrivateKey, PrivateKeyCiphertext, Program, ProgramManager as ProgramManagerBase, ProvingKey, RecordCiphertext, RecordPlaintext, Signature, Scalar, Transaction, Transition, VerifyingKey, ViewKey, initThreadPool, verifyFunctionExecution, } from "./wasm";
-export { initializeWasm };
-export { Key, CREDITS_PROGRAM_KEYS, KEY_STORE, PRIVATE_TRANSFER, PRIVATE_TO_PUBLIC_TRANSFER, PRIVATE_TRANSFER_TYPES, PUBLIC_TRANSFER, PUBLIC_TRANSFER_AS_SIGNER, PUBLIC_TO_PRIVATE_TRANSFER, VALID_TRANSFER_TYPES, } from "./constants";
-export { Account, AleoKeyProvider, AleoKeyProviderParams, AleoKeyProviderInitParams, AleoNetworkClient, BlockJSON, BlockHeightSearch, CachedKeyPair, ConfirmedTransactionJSON, DeploymentJSON, DeploymentObject, ExecutionJSON, ExecutionObject, FeeExecutionJSON, FeeExecutionObject, FinalizeJSON, FunctionObject, FunctionKeyPair, FunctionKeyProvider, Header, InputJSON, InputObject, KeySearchParams, Metadata, NetworkRecordProvider, ProgramImports, OfflineKeyProvider, OfflineSearchParams, OwnerJSON, PlaintextArray, PlaintextLiteral, PlaintextObject, PlaintextStruct, OutputJSON, OutputObject, RecordProvider, RecordSearchParams, TransactionJSON, TransactionObject, TransitionJSON, TransitionObject, VerifyingKeys, };