@provablehq/sdk 0.8.2 → 0.8.4

package/README.md

@@ -1,4 +1,9 @@
-# Aleo SDK
+---
+id: overview
+title: SDK for Building Zero Knowledge Web Apps
+sidebar_label: Overview
+---
+
 <p align="center">
     <img alt="Aleo SDK" width="1412" src="../.resources/banner.png">
 </p>
@@ -8,946 +13,57 @@
     <a href="https://circleci.com/gh/ProvableHQ/sdk"><img src="https://circleci.com/gh/ProvableHQ/sdk.svg?style=svg"></a>
     <a href="https://discord.com/invite/aleo"><img src="https://img.shields.io/discord/700454073459015690?logo=discord"/></a>
     <a href="https://github.com/ProvableHQ/sdk#%EF%B8%8F-contributors"><img src="https://img.shields.io/badge/contributors-23-ee8449"/></a>
+    <a href="https://www.npmjs.com/package/@provablehq/sdk"> <img alt="Aleo SDK" src="https://img.shields.io/npm/l/%40provablehq%2Fsdk?label=NPM%20-%20Aleo%20SDK&labelColor=green&color=blue"></a>
 </p>
 
-## Tools for Building Zero-Knowledge Web Apps
-
-The Aleo SDK is a JavaScript library for building zero-knowledge web applications in both web browsers and Node.js.
 
-## Overview
+The [Provable SDK](https://github.com/ProvableHQ/sdk) is an open source TypeScript/JavaScript SDK for building private full stack web applications. The
+SDK provides an easy API for using Aleo's core suite of cryptographic primitives, zk-SNARKs and private program execution
+protocol directly within Javascript. It also provides APIs for interacting with nodes and applications on the Aleo Network.
 
-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).
+Applications built with the Aleo SDK include:
+* **Private DeFi**
+* **Private Data Custody Systems**
+* **Zk Games & Gaming Toolkits**
+* **ZkML**
+* **Zero Knowledge Identity Management**
+* **Aleo Wallets**
 
-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):
+## Features
+The Aleo SDK provides the following features. Follow the links below for live demonstrations of these features on
+[provable.tools](https://provable.tools)
 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/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
-
-* [Installation](#Installation)
-* [Usage](#Usage)
-  * [Zero-Knowledge Web App Examples](#Zero-Knowledge-Web-App-Examples)
-    * [Create Leo App](#create-leo-app)
-    * [Provable.tools](#provabletools)
-  * [Create An Aleo Account](#1-create-an-aleo-account)
-  * [Execute Aleo Programs](#2-execute-aleo-programs)
-    * [Aleo Programs](#21-aleo-programs)
-    * [Program Execution Model](#22-program-execution-model)
-    * [WebAssembly Initialization](#23-wasm-initialization)
-    * [Local Program Execution](#24-local-program-execution)
-    * [Online Program Execution](#25-program-execution-on-the-aleo-network)
-    * [Program Proving Keys and Records](#26-program-proving-keys--program-records)
-    * [Deploy Programs](#27-deploy-a-new-program-to-the-aleo-network)
-    * [React Example](#28-react-example)
-  * [Aleo Credit Transfers](#3-value-transfers)
-    * [Aleo Credits](#31-aleo-credits)
-    * [Transfer Aleo Credits](#32-transfer-aleo-credits)
-    * [Check Public Balances](#32-checking-public-balances)
-  * [Program Data and Private State](#4-managing-program-data-and-private-state)
-    * [Private State Data: Records](#41-private-state-data--records)
-    * [Record Usage Example](#42-record-usage-example--private-value-transfers)
-    * [Public State Data: Mappings](#43-public-state-data--mappings)
-    * [Reading Mappings](#44-reading-mappings)
-    * [Initializing and Updating Mappings](#45-initializing--updating-mappings)
-  * [Communicating with the Aleo Network](#5-communicating-with-the-aleo-network)
-* [Further Documentation](#further-documentation)
-## Installation
-
-### Clone the repository
-
-To clone the repository, run:
-
-`git clone git@github.com:ProvableHQ/sdk.git`
-
-### NPM & YARN
-
-To install the Aleo SDK from NPM run:
-
-`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
-
-To build the project from source, go to the project's root and execute:
-
-`yarn build:all`
-
-### Ensure compatibility with ES modules
-
-In your project's `package.json`, ensure that the following line is added above `scripts`:
-
-```json
-{
-  "type": "module",
-}
-```
-
-## Getting Started: Zero-Knowledge Web App Examples
-
-### 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/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
-
-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 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. 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:
-
-#### Private Key
-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. 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.
-
-All of these keys can be created using the account object:
-```typescript
-import { Account } from '@provablehq/sdk';
-
-const account = new Account();
-
-// Individual keys can be then be accessed through the following methods
-const privateKey = account.privateKey();
-const viewKey = account.viewKey();
-const address = account.address();
-```
-
-Please note that all keys are considered sensitive information and should be stored securely.
-
-## 2. Execute Aleo Programs
-
-### 2.1 Aleo Programs
-
-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 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.
-
-Documentation for both languages can be found at [docs.leo-lang.org](https://docs.leo-lang.org/).
-
-#### "Hello World" in Leo
-```
-// A simple program adding two numbers together
-program helloworld.aleo {
-  transition hello(public a: u32, b: u32) -> u32 {
-      let c: u32 = a + b;
-      return c;
-  }
-}
-```
-
-#### "Hello World" in Aleo Instructions
-```
-program helloworld.aleo;
-
-// The Leo code above compiles to the following Aleo Instructions:
-function hello:
-    input r0 as u32.public;
-    input r1 as u32.private;
-    add r0 r1 into r2;
-    output r2 as u32.private;
-```
-
-### 2.2 Program Execution Model
-
-#### 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. 
-
-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 WebAssembly Initialization
-
-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';
-
-// Enables multithreading
-await initThreadPool();
-
-// Create a new Aleo account
-const account = new Account();
-
-// Perform further program logic...
-````
-
-### 2.4 Local program execution
-
-A simple example of running the "hello world" program locally using Node.js and capturing its outputs is shown below:
-```typescript
-import { Account, ProgramManager } from '@provablehq/sdk';
-
-/// Create the source for the "hello world" 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();
-
-/// 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.deepStrictEqual(result, ['10u32']);
-```
-
-### 2.5 Program execution on the Aleo network
-The SDK provides the ability to execute programs and store an encrypted transcript of the execution on the Aleo
-network that anyone can trustlessly verify.
-
-This process can be thought of as being executed in the following steps:
-1. A program is run locally.
-2. A proof that the program was executed correctly and that the outputs follow from the inputs is generated.
-3. A transcript of the proof is generated client-side containing encrypted proof data (see [Section 2.6](#4-managing-records-and-private-state))
-and any public outputs or state the user of the program wishes to reveal.
-4. The proof transcript is posted to the Aleo network and verified by the Aleo validator nodes in a trustless manner.
-5. If the proof is valid, it is stored and anyone can later verify the proof and read the outputs the author of the
-program has chosen to make public. Private inputs will remain encrypted, but the author of the proof can also choose to
-retrieve this encrypted state at any point and decrypt it locally for their own use.
-
-Posting an execution to the Aleo network serves as a globally trustless and verifiable record of a program execution as well as
-any resulting state changes in private or public data.
-
-A simple example of running the "hello world" program on the Aleo network is shown below:
-```typescript
-import { Account, AleoNetworkClient, NetworkRecordProvider, ProgramManager, AleoKeyProvider } from '@provablehq/sdk';
-
-// Create an account
-const account = new Account();
-
-// Create a network client to connect to the Aleo network
-const networkClient = new AleoNetworkClient("https://api.explorer.provable.com/v1");
-
-// Create a key provider that will be used to find public proving & verifying keys for Aleo programs
-const keyProvider = new AleoKeyProvider();
-keyProvider.useCache = true;
-
-// Create a record provider that will be used to find records and transaction data for Aleo programs
-const recordProvider = new NetworkRecordProvider(account, networkClient);
-
-// Initialize a program manager to talk to the Aleo network with the configured key and record providers
-const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider, recordProvider);
-
-// Set the account for the program manager
-programManager.setAccount(account);
-
-(async () => {
-    try {
-        // Provide a key search parameter to find the correct key for the program if they are stored in a memory cache
-        const keySearchParams = { cacheKey: "helloworld.aleo:main" };
-        console.log("Key search parameters set: ", keySearchParams);
-
-        // Execute the program using the options provided inline
-        const tx_id = await programManager.execute({
-            programName: "helloworld.aleo",
-            functionName: "main",
-            fee: 0.020,
-            privateFee: false, // Assuming a value for privateFee
-            inputs: ["5u32", "5u32"], // Example inputs matching the function definition
-            keySearchParams: keySearchParams,
-            privateKey: account.privateKey() // Set the private key
-        });
-        const transaction = await programManager.networkClient.getTransaction(tx_id);
-        console.log("Transaction details: ", transaction);
-    } catch (error) {
-        console.error("Error executing program:", error);
-    }
-})();
-```
-
-A reader of the above example may notice the `RecordProvider` and `KeyProvider` classes that were not present in the local
-execution example. The `KeyProvider` class helps users of the SDK find `Proving Keys` for programs. `Proving Keys`
-allow zero-knowledge proofs that the programs were executed correctly to be created. The `RecordProvider` class helps
-find `Records` which are private data associated with programs that can be changed and updated throughout time.
-These two concepts are explained in more detail below.
-
-### 2.6 Program proving keys & program records
-
-Executing Aleo programs using zero-knowledge requires two additional pieces of information:
-
-1. **Function Proving & Verifying Keys:** Proving and verifying keys are cryptographic keys that are generated when a
-   program function is executed. These keys are public and unique for each function in a program. The proving keys allows any party to
-   execute the program and generate a proof that the program was executed correctly. The verifying keys allow any party
-   to verify that the proof was generated correctly and the execution is correct. These keys are required to create the
-   zero-knowledge property of program execution.
-2. **Program Records:** Records are private state generated by a program belonging to a unique private keyholder. Records
-   are generated by a program's functions and can be changed and updated when a user runs various functions of the
-   program. These records are private by default and are used to manage updatable private state. One of the most clear
-   usages of records is to the `credits` record in the `credits.aleo` program. Credits records are one of two official ways of
-   representing Aleo credits on the Aleo network and are used to pay all transaction fees on the network. More information
-   on records can be found in the [Records](#41-private-state-data--records) section below.
-
-For this reason, all programs will need proving and verifying keys to operate and many functions in Aleo programs will
-require records as inputs. To simplify the process of managing keys and records, the Aleo SDK provides two abstractions
-for managing these concepts:
-
-1. **KeyProvider:** When program functions execute, they will by default synthesize the proving and verifying keys needed to
-make a zero-knowledge proof of the execution. However, these keys are large and expensive to generate. For this reason, applications may
-want to store these keys and re-use them in future executions. The `KeyProvider` interface provides the ability for
-users of the SDK to provide their own key storage and retrieval mechanism. The SDK provides a default implementation
-of the `KeyProvider` interface via the `AleoKeyProvider` class.
-2. **RecordProvider:** When programs execute, they will often need to find records that belong to a user. The
-`RecordProvider` interface allows users of the SDK to implement their own record storage and retrieval mechanism. The
-SDK provides a default implementation of the `RecordProvider` interface via the `NetworkRecordProvider` class which
-searches the Aleo network for records uniquely belonging to a user.
-
-The `ProgramManager` class is capable of taking a `KeyProvider` and `RecordProvider` as arguments and will use them to
-find the correct keys and records for a program execution.
-
-### 2.7 Deploy a new program to the Aleo Network
-
-The Aleo network contains a public registry of programs that can be executed by anyone. Any user can add an Aleo program
-to the network (as long as it doesn't already exist) by paying a deployment fee in Aleo credits. The SDK
-provides a simple interface for deploying programs to the Aleo network using the program manager.
-
-```typescript
-import { Account, AleoNetworkClient, NetworkRecordProvider, ProgramManager, AleoKeyProvider} from '@provablehq/sdk';
-
-// Create a key provider that will be used to find public proving & verifying keys for Aleo programs
-const keyProvider = new AleoKeyProvider();
-keyProvider.useCache(true);
-
-// Create a record provider that will be used to find records and transaction data for Aleo programs
-const networkClient = new AleoNetworkClient("https://api.explorer.provable.com/v1");
-
-// Use existing account with funds
-const account = new Account({
-    privateKey: "user1PrivateKey",
-});
-
-const recordProvider = new NetworkRecordProvider(account, networkClient);
-
-// Initialize a program manager to talk to the Aleo network with the configured key and record providers
-const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider, recordProvider);
-programManager.setAccount(account)
-
-// Define an Aleo program to deploy
-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";
-
-// Define a fee to pay to deploy the program
-const fee = 3.8; // 3.8 Aleo credits
-
-// Deploy the program to the Aleo network
-const tx_id = await programManager.deploy(program, fee);
-
-// Verify the transaction was successful
-const transaction = await programManager.networkClient.getTransaction(tx_id);
-```
-
-The `NetworkRecordProvider` will attempt to scan the network for a fee record for the account provided. Doing a recent
-public transfer to the deploying account will ensure a record is found quickly, or you can provide a fee record manually
-by [scanning](https://docs.leo-lang.org/testnet/getting_started/deploy_execute/#scan) for a record and passing it as a
-string.
-
-```typescript
-// Set fee record manually
-const feeRecord = "{  owner: aleo1xxx...xxx.private,  microcredits: 2000000u64.private,  _nonce: 123...789group.public}";
-
-// Deploy the program to the Aleo network
-const tx_id = await programManager.deploy(program, fee, undefined, feeRecord);
-```
-
-### 2.8 React example
-
-The above concepts can be tied together in a concrete example of a single-page web app. This example can be installed in one
-step by running:
-
-`npm create leo-app@latest`
-
-You will then be prompted to select either Vanilla, React, or Node.js as the template for the project. For this example, select Vanilla.
-
-#### Program execution
-
-Program execution is a computationally-expensive process. For this reason, it is recommended to execute programs in
-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/mainnet/create-leo-app/template-vanilla)
-
-## 3. Aleo Credit Transfers
-
-### 3.1 Aleo credits
-
-Aleo Credits are used to access blockspace and computational resources on the network, with users paying Credits to submit transactions and have them processed.
-
-Aleo credits are defined in the [credits.aleo](https://explorer.provable.com/program/credits.aleo) program. This program is
-deployed to the Aleo network and defines data structures representing Aleo credits and the functions used to manage them.
-
-There are two ways to hold Aleo credits:
-
-#### 1 - Private balances via  `credits.aleo` records
-The first method is owning a `credits` record which enables a participant in the Aleo
-network to hold a private balance of Aleo credits.
-```
-record credits:
-    owner as address.private;
-    microcredits as u64.private;
-```
-
-A user's total private credits balance will consist of all unspent `credits` records owned by the user with a non-zero
-`microcredits` value.
-
-#### 2 - Public balances via `credits.aleo` account mappings
-The second method is by holding a `balance` in the `account` mapping in the `credits.aleo` program on the Aleo network.
-
-```
-mapping account:
-    key owner as address.public;
-    value microcredits as u64.public;
-```
-
-The total public credits balance of a user is the value of the account mapping at the user's address. Users can hold both private and public balances simultaneously.
-
-More information about `records` and `mappings` and how they are related to private and public balances are explained in the
-[Managing Program Data and Private State](#4-managing-program-data-and-private-state) section.
-
-### 3.2 Transferring Aleo credits
-The `ProgramManager` allows transfers of Aleo credits via the `transfer` method. This function executes the `credits.aleo`
-program under the hood.
-
-There are four transfer functions available.
-
-#### 1. `transfer_private`
-
-Takes a `credits` record owned by the sender, subtracts an amount from it, and adds that amount
-to a new record owned by the receiver. This function is 100% private and does not affect the `account` mapping.
-
-```mermaid
-graph LR
-    user1--record1 \n owner: user1address \n balance: 10000u64-->t1[transfer_private]
-    user1--amount: 4000u64-->t1
-    t1-.record2 \n owner: user1address \n amount: 6000u64.->user1
-    t1--record3  \n owner: user2address \n balance: 4000u64-->user2
-
-```
-
-#### 2. `transfer_private_to_public`
-
-Takes a `credits` record owned by the sender, subtracts an amount from it, and adds
-that amount to the `account` mapping of the receiver. This function is 50% private and 50% public. It consumes a record
-as a private input and generates a public balance in the `account` mapping entry belonging to the receiver.
-
-```mermaid
-graph LR
-    subgraph credits.aleo
-        m1[account mapping \n key: user3address \n value: 3000u64]
-    end
-    user1--record3 \n owner: user2address \n balance: 4000u64-->t1[transfer_private_to_public]
-    t1-.record4 \n owner: user2address \n amount: 1000u64.->user1
-    t1--amount 3000u64-->m1
-```
-
-#### 3. `transfer_public`
-
-Subtracts an amount of `credits` stored in the `account` mapping of the `credits.aleo` program, and
-adds that amount to the `account` mapping of the receiver. This function is 100% public and does not consume or generate
-any records.
-
-```mermaid
-graph LR
-    subgraph credits.aleo account mappings - state 2
-        m3[account mapping \n key: user4address \n value: 3000u64]
-        m4[account mapping \n key: user3address \n value: 0u64]
-    end
-
-    subgraph credits.aleo account mappings - state 1
-        m2[account mapping \n key: user3address \n value: 3000u64]--transfer_public \n recipient: user4address \n amount: 3000u64-->m3
-        m1[account mapping \n key: user4address \n value: N/A]
-    end
-```
-
-#### 4. `transfer_public_to_private`
-
-Subtracts an amount `credits` stored in the `account` mapping of the `credits.aleo program`
-and adds that amount to a new private record owned by the receiver. This function is 50% private and 50% public.
-It publicly consumes a balance in the `account` mapping entry belonging to the sender and generates a private record
-as a private output.
-
-```mermaid
-graph LR
-    subgraph credits.aleo account mappings - state 2
-        m2[account mapping \n key: user5address \n value: 0u64]
-    end
-
-    subgraph credits.aleo account mappings - state 1
-        m1[account mapping \n key: user5address \n value: 3000u64]
-    end
-
-    m1--recipient: user6address \n amount: 3000u64-->transfer_public_to_private
-    transfer_public_to_private--record5 \n owner: user6address \n amount: 3000u64-->user6
-```
-
-All four of these functions can be used to transfer credits between users via the `transfer` function in the
-`ProgramManager` by specifying the transfer type as the third argument.
-
-```typescript
-import { Account, ProgramManager, AleoKeyProvider, NetworkRecordProvider, AleoNetworkClient } from '@provablehq/sdk';
-
-// Create a new NetworkClient, KeyProvider, and RecordProvider
-const account = Account.from_string({privateKey: "user1PrivateKey"});
-const networkClient = new AleoNetworkClient("https://api.explorer.provable.com/v1");
-const keyProvider = new AleoKeyProvider();
-const recordProvider = new NetworkRecordProvider(account, networkClient);
-
-// Initialize a program manager with the key provider to automatically fetch keys for executions
-const USER_1_ADDRESS = "user1Address";
-const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider, recordProvider);
-programManager.setAccount(account);
-
-// Send a private transfer to yourself
-const tx_id = await programManager.transfer(1, USER_1_ADDRESS, "transfer_private", 0.2);
-
-// Update or initialize a public balance in your own account mapping
-const tx_id_2 = await programManager.transfer(1, USER_1_ADDRESS, "transfer_private_to_public", 0.2);
-
-// Check the value of your public balance
-let public_balance = programManager.networkClient.getMappingValue("credits.aleo", USER_1_ADDRESS);
-assert(public_balance === 0.2*1_000_000);
-
-/// Send public transfer to another user
-const USER_2_ADDRESS = "user2Address";
-const tx_id_3 = await programManager.transfer(1, USER_2_ADDRESS, "transfer_public", 0.1);
-
-// Check the value of the public balance and assert that it has been updated
-public_balance = programManager.networkClient.getMappingValue("credits.aleo", USER_1_ADDRESS);
-const user2_public_balance = programManager.networkClient.getMappingValue("credits.aleo", USER_1_ADDRESS);
-assert(public_balance === 0.1*1_000_000);
-assert(user2_public_balance === 0.1*1_000_000);
-
-/// Create a private record from a public balance
-const tx_id_4 = await programManager.transfer(1, USER_1_ADDRESS, "transfer_public_to_private", 0.1);
-
-// Check the value of the public balance and assert that it has been updated
-public_balance = programManager.networkClient.getMappingValue("credits.aleo", USER_1_ADDRESS);
-assert(public_balance === 0);
-```
-
-### 3.2 Checking public balances
-As shown above, a public balance of any address can be checked with `getMappingValue` function of the `NetworkClient`.
-
-```typescript
-const networkClient = new AleoNetworkClient("https://api.explorer.provable.com/v1");
-const USER_1_ADDRESS = "user1Address";
-const public_balance = networkClient.getMappingValue("credits.aleo", USER_1_ADDRESS);
-```
-
-## 4. Managing Program Data and Private State
-
-### 4.1 Private state data: records
-Records are analogous to the concept of [UTXOs](https://en.wikipedia.org/wiki/Unspent_transaction_output). When a record is
-created by a program, it can then be consumed later by the same program as an input to a function. Once a record is used
-as an input, it is considered consumed and cannot be used again. In many cases a new record will be created from the output
-of the function. Records are private by default and are associated with a single Aleo program and a single private key
-representing a user.
-
-### 4.2 Record usage example: private value transfers
-
-A straightforward example of a usage of records in a program can be demonstrated by explaining the process of private
-value transfers of Aleo credits on the Aleo network.
-
-Aleo credits are used for all on-chain execution and deployment fees. Credits can be public
-or private. Private credits are represented by the `credits` record in the [credits.aleo](https://www.aleo.network/programs/credits.aleo)
-program.
-
-```
-record credits:
-    owner as address.private;
-    microcredits as u64.private;
-```
-
-Credits records contain an `owner` field representing the address which owns the record and a `microcredits` field
-representing the amount of microcredits in the record. 1 credit is equal to 1,000,000 microcredits.
-
-An example of an Aleo function that both takes a record as input and outputs a record is the `transfer_private` function
-of the `credits.aleo` program. This function takes a private `credits` record as input and outputs two new private `credits`
-records as output (one that sends the credits to the recipient and one that sends the remaining credits to the sender).
-
-The source code for the `transfer_private` is:
-```
-function transfer_private:
-    input r0 as credits.record;
-    input r1 as address.private;
-    input r2 as u64.private;
-    sub r0.microcredits r2 into r3;
-    cast r1 r2 into r4 as credits.record;
-    cast r0.owner r3 into r5 as credits.record;
-    output r4 as credits.record;
-    output r5 as credits.record;
-```
-
-The `transfer_private` function can be graphically represented by the graph below. In the graph the first record, Record 1,
-is consumed and can never be used again. From the data in Record 1, two more records are created. One containing
-the intended amount for the recipient which is now owned by the recipient and another containing the remaining credits
-which are sent back to the sender.
-
-```mermaid
-graph LR
-    User1[Sender Address]
-    i1[Input 1: Credits Record 1]-->p1
-    i2[Input 2: Recipient Address]-->p1
-    p1[Credits.aleo:transfer_private]
-    p1--Credits Record 2-->User1
-    p1--Credits Record 3-->R1[Recipient Address]
-```
-
-This chain of ownership is tracked by the Aleo blockchain when users choose to submit their transactions to the Aleo
-network. This allows other users who receive records to receive the updated data and verify that this data was
-provably generated by the intended program.
-
-What this process allows is a private chain of state to be created between multiple users. In the context of value
-transfers, a chain of state might look like the following:
-
-```mermaid
-graph LR
-    user1--record1-->t1[transfer_private]
-    t1-.record2.->user1
-    t1--record3-->user2
-    user2--record3-->t2[transfer_private]
-    t2--record5-->user3
-    t2-.record4.->user2
-```
-
-The above state chain would be executed in the following way using the SDK:
-#### Step 1 - User 1 sends a private value transfer to User 2
-```typescript
-// USER 1
-import { Account, ProgramManager, AleoKeyProvider, NetworkRecordProvider, AleoNetworkClient } from '@provablehq/sdk';
-
-// Create a new NetworkClient, KeyProvider, and RecordProvider
-const account = Account.from_string({privateKey: "user1PrivateKey"});
-const networkClient = new AleoNetworkClient("https://api.explorer.provable.com/v1");
-const keyProvider = new AleoKeyProvider();
-const recordProvider = new NetworkRecordProvider(account, networkClient);
-
-// Initialize a program manager with the key provider to automatically fetch keys for executions
-const USER_2_ADDRESS = "user2Address";
-const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider, recordProvider);
-programManager.setAccount(account);
-
-/// Send private transfer to User 2
-const tx_id = await programManager.transfer(1, USER_2_ADDRESS, "transfer_private", 0.2);
-```
-
-#### Step 2 - User 2 receives the transaction ID and fetches the credits record they received from User 1 from the network. They then send it to User 3
-
-```typescript
-// USER 2
-import { Account, ProgramManager, AleoKeyProvider, NetworkRecordProvider, AleoNetworkClient } from '@provablehq/sdk';
-
-// Create a new NetworkClient, KeyProvider, and RecordProvider
-const account = Account.from_string({privateKey: "user2PrivateKey"});
-const networkClient = new AleoNetworkClient("https://api.explorer.provable.com/v1");
-const keyProvider = new AleoKeyProvider();
-const recordProvider_User2 = new NetworkRecordProvider(account, networkClient);
-
-// Initialize a program manager with the key provider to automatically fetch keys for executions
-const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider, recordProvider);
-programManager.setAccount(account);
-
-// Fetch the transaction from the network that user 1 sent
-const transaction = await programManager.networkClient.getTransaction(tx_id);
-const record = <string>transaction.execution.transitions[0].outputs[0].value;
-
-// Decrypt the record with the user's view key
-const recordCiphertext = <RecordCiphertext>RecordCiphertext.fromString(record);
-const recordPlaintext = <RecordPlaintext>recordCiphertext.decrypt(account.viewKey());
-
-// Send a transfer to user 3 using the record found above
-const USER_3_ADDRESS = "user3Address";
-const tx_id = await programManager.transfer(1, USER_3_ADDRESS, "transfer_private", 0.2, undefined, recordPlaintext);
-```
-
-When an execution such as `transfer_private` consumes or generates a record, an encrypted transcript of the execution containing an encrypted version of the record output and a transaction ID is posted on the network.
-
-Because the records are encrypted when they're posted on the network, they do not reveal any information about the party
-who executed the program, nor the contents of the record. The only information that is revealed is the program ID,
-function name, encrypted function inputs, and the transaction ID of the program execution. No user except for the recipient
-of the record can see the contents of the record.
-
-Below, you can see the exact data which is posted to the Aleo network when `transfer_private` is run. Note that the
-record, the amount transferred, and both the sender and recipient addresses are all encrypted.
-
-<details>
-<summary>`transfer_private` Execution Transcript</summary>
-
-```json
-  "transactions": [
-    {
-      "status": "accepted",
-      "type": "execute",
-      "index": 0,
-      "transaction": {
-        "type": "execute",
-        "id": "at1s7dxunms8xhdzgaxrwf0yvq2dqgxtf4a3j8g878rhfr0zwhap5gqywsw8y",
-        "execution": {
-          "transitions": [
-            {
-              "id": "as1thy8fvkz0rkls5wnmfq5udrcvvzurq7mqk8pkhjf63htqjf9mugqp0mfhd",
-              "program": "credits.aleo",
-              "function": "transfer_private",
-              "inputs": [
-                {
-                  "type": "record",
-                  "id": "1406044754369042876058586523429806531093330762697573675195902502647806778955field",
-                  "tag": "242626059121157295593694555515381893342956813170338731374395259242800138642field"
-                },
-                {
-                  "type": "private",
-                  "id": "1533599744296862879610225011439684001995294756698105572984689232395187168232field",
-                  "value": "ciphertext1qgqgpu7m8p0rwjahwffyvm4g4n6903d6ufqty74z4504w4rn356hgp9jvpuvx8suu0pukr3sl7n8x65dz35nu4jdy4lgcguxldygufrfpyqd6xr5"
-                },
-                {
-                  "type": "private",
-                  "id": "4081557229261486898857101724786348855190759711760925564309233047223407640812field",
-                  "value": "ciphertext1qyqxd9wue0qh8hs6dgevn7zleedfkzf7pft8ecked2xq3pw54pgqzyqr69sgx"
-                }
-              ],
-              "outputs": [
-                {
-                  "type": "record",
-                  "id": "1388064668770056715587596299070268626507043043686185311840561493640415146425field",
-                  "checksum": "5376939704883651492329501631722578074516322228314928758786996843926470523116field",
-                  "value": "record1qyqsq4r7mcd3ystjvjqda0v2a6dxnyzg9mk2daqjh0wwh359h396k7c9qyxx66trwfhkxun9v35hguerqqpqzqzshsw8dphxlzn5frh8pknsm5zlvhhee79xnhfesu68nkw75dt2qgrye03xqm4zf5xg5n6nscmmzh7ztgptlrzxq95syrzeaqaqu3vpzqf03s6"
-                },
-                {
-                  "type": "record",
-                  "id": "4635504195534945632234501197115926012056789160185660629718795843347495373207field",
-                  "checksum": "3428805926164481449334365355155755448945974546383155334133384781819684465685field",
-                  "value": "record1qyqsp2vsvvfulmk0q0tmxq7p9pffhfhha9h9pxsftujh57kkjuahx9s0qyxx66trwfhkxun9v35hguerqqpqzq8etfmzt2elj37hkf9fen2m2qes8564sr8k970zyud5eqmq7ztzq5r3095mkfdzqzz7yp6qfavqsl3t22t6dvgauqqt2xqk98zwmtusq5ck7fm"
-                }
-              ],
-              "tpk": "5283803395323806407328334221689294196419052177553228331323093330938016699852group",
-              "tcm": "4398026033398688325681745841147300822741685834906186660771751747897598751646field"
-            }
-          ],
-```
-</details>
-
-
-#### Record Decryption
-
-If a user receives a private record from a program execution, they can use the SDK to decrypt encrypted records with
-their view keys and view their contents. Only records that are owned by the user can be decrypted. Decryption of records
-that are not owned by the user will fail.
-
-Record decryption and ownership verification can be done in the SDK using the following code:
-
-```typescript
-import { Account, RecordCiphertext, RecordPlaintext } from '@provablehq/sdk';
-
-// Create an account from an existing private key
-const account = Account.from_string({privateKey: "existingPrivateKey"});
-
-// Record value received as a string from program output or found on the Aleo network
-const record = "record1qyqsq4r7mcd3ystjvjqda0v2a6dxnyzg9mk2daqjh0wwh359h396k7c9qyxx66trwfhkxun9v35hguerqqpqzqzshsw8dphxlzn5frh8pknsm5zlvhhee79xnhfesu68nkw75dt2qgrye03xqm4zf5xg5n6nscmmzh7ztgptlrzxq95syrzeaqaqu3vpzqf03s6";
-
-const recordCiphertext = RecordCiphertext.fromString(record);
-
-// Check ownership of the record. If the account is the owner, decrypt the record
-if (RecordCiphertext.is_owner(account.viewKey())) {
-   // Decrypt the record with the account's view key
-   const recordPlaintext = recordCiphertext.decrypt(account.viewKey());
-
-   // View the record data
-   console.log(recordPlaintext.toString());
-}
-```
-
-### 4.3 Public State Data: Mappings
-Mappings are simple key value stores defined in a program. They are represented by a key and a value each of a specified
-type. They are stored directly within the Aleo blockchain and can be publicly read by any participant in the Aleo network.
-
-An example of a mapping usage is the `account` mapping in the `credits.aleo` program.
-```
-mapping account:
-    key owner as address.public;
-    value microcredits as u64.public;
-```
-
-The `account` mapping is used to store public credit balances on the Aleo network. It takes a public address as a key
-and a public `u64` value representing the number of microcredits owned by the address.
-
-Mappings within programs are identified by the `mapping` identifier. Any program where this keyword appears contains an
-on-chain mapping. An example of a program that uses a mapping is shown below:
-```
-program player_mapping_example.aleo
-
-// The mapping identifier representing a score
-mapping score:
-    key player as address.public;
-    value score as u64.public;
-
-// The update score function
-function update_score:
-    input r0 as address.public;
-    input r1 as u64.public;
-
-// The finalize code block will be executed by Aleo network nodes.
-// When it runs it will update the value of the mapping.
-finalize update_score:
-    input r0 as address.public;
-    input r1 as u64.public;
-    get.or_use score[r0] 0u64 into r2;
-    add r1 r2 into r3;
-    set r3 into account[r0];
-```
-
-Note that the above function has a `finalize` identifier. This identifier is used to identify a portion of a function's
-code that should be executed by nodes on the Aleo network. Program mappings are updated exclusively by code run by nodes
-on the Aleo network written in `finalize` blocks.
-
-### 4.4 Reading mappings
-Any state within a program mapping is public and can be read by any participant in the Aleo network. The `NetworkClient`
-class provides the `getMapping` method to read the public mappings within an program and the `getMappingValue` method to
-read the value of a specific key within a mapping.
-
-```typescript
-import { AleoNetworkClient } from '@provablehq/sdk';
-
-const networkClient = new AleoNetworkClient("https://api.explorer.provable.com/v1");
-const creditsMappings = networkClient.getMappings("credits.aleo");
-assert(creditsMappings === ["account"]);
-
-const publicCredits = networkClient.getMapping("credits.aleo", "[a valid aleo account with zero balance]");
-assert(publicCredits === "0u64");
-```
-
-### 4.5 Initializing & updating mappings
-Updating mappings is done by executing a program function on the Aleo network which has a finalize block that updates the
-program's mapping. For instance, the `transfer_public` function in the `credits.aleo` program updates the `account`
-mapping (and thus a user's balance) when called.
-
-```
-// The public interface called by users
-function transfer_public:
-    input r0 as address.public;
-    input r1 as u64.public;
-    finalize self.caller r0 r1;
-
-// The finalize block run by nodes on the Aleo network which update a user's public balance
-finalize transfer_public:
-    input r0 as address.public;
-    input r1 as address.public;
-    input r2 as u64.public;
-    get.or_use account[r0] 0u64 into r3;
-    sub r3 r2 into r4;
-    set r4 into account[r0];
-    get.or_use account[r1] 0u64 into r5;
-    add r5 r2 into r6;
-    set r6 into account[r1];
-```
-
-From the perspective of the caller of the API, this is as simple as executing a normal Aleo function. Given the inputs
-to a function with a finalize scope that updates a mapping are valid, the mapping will either be intialized or updated
-by the Aleo network. All that the user of the SDK must do is ensure that the inputs to the function are valid.
-
-If function inputs are invalid, the network will return an error, but the fee paid for the transaction will still be
-consumed. Therefore, it is important to ensure that the inputs to a function are valid before executing it.
-
-A simple example of a mapping update can be shown by simply executing `transfer_public` as shown below.
-
-```typescript
-import { Account, ProgramManager, AleoKeyProvider, NetworkRecordProvider, AleoNetworkClient } from '@provablehq/sdk';
+2. [Aleo cryptographic primitives](https://provable.tools/algebra)
+3. [Web based zero knowledge program execution and deployment](https://provable.tools/develop)
+4. [Aleo credit transfers and staking](https://provable.tools/transfer)
+5. [Management of program state](https://provable.tools/protocol)
+6. [Communication with the Aleo network](https://provable.tools/rest)
 
-// Create a new NetworkClient, KeyProvider, and RecordProvider
-const account = Account.from_string({privateKey: "user1PrivateKey"});
-const networkClient = new AleoNetworkClient("https://api.explorer.provable.com/v1");
-const keyProvider = new AleoKeyProvider();
-const recordProvider = new NetworkRecordProvider(account, networkClient);
 
-// Initialize a program manager with the key provider to automatically fetch keys for executions
-const RECIPIENT_ADDRESS = "user1Address";
-const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider, recordProvider);
-programManager.setAccount(account);
+## Start Building
 
-// Update or initialize a public balance
-const tx_id = await programManager.transfer(1, RECIPIENT_ADDRESS, "transfer_private_to_public", 0.2);
-```
+Developers interested in using the SDK to build private web applications can get started with the following resources.
 
+### [The SDK Guide](https://docs.explorer.provable.com/docs/sdk/6p7047svvq2ox-intro-to-aleo)
+<a href="https://www.npmjs.com/package/@provablehq/sdk"> <img alt="Aleo SDK" src="https://img.shields.io/npm/l/%40provablehq%2Fsdk?label=NPM%20-%20Aleo%20SDK&labelColor=green&color=blue"></a>
 
-## 5. Communicating with the Aleo network
+A step-by-step guide to building private web applications with the Aleo SDK. The guide covers creating Aleo accounts,
+transferring and receiving aleo credits, executing/deploying/interacting with Aleo programs, managing private and public
+state, and best practices for building private web applications.
 
-Communication with the Aleo network is done through the `AleoNetworkClient` class. This class provides methods to query
-data from Aleo network nodes and submit transactions to the Aleo network.
+### [Create-Leo-App](https://docs.leo-lang.org/sdk/create-leo-app/tutorial)
 
-A full list of methods provided by the `AleoNetworkClient` class and usage examples can be found in the
-[Network Client API documentation](https://docs.leo-lang.org/sdk/typescript/aleo_network_client).
+<a href="https://www.npmjs.com/package/create-leo-app"> <img alt="Create Leo App" src="https://img.shields.io/npm/l/create-leo-app?label=NPM%20-%20Create-Leo-App&labelColor=green&color=blue"></a>
 
-## Further Documentation
+A suite of examples and templates for building private web applications in a variety of Javascript frameworks. These
+examples can be easily installed and run using the `create-leo-app` command line tool. The examples cover a wide range
+of use cases such as Private NFTs, offline transaction signing, and usage of the SDK in React, Next, and VanillaJS.
 
-API documentation for this package, the Leo Language, and Aleo instructions can be found in the [Leo Developer Docs](https://docs.leo-lang.org/getting_started).
+### [SDK API Documentation](https://docs.explorer.provable.com/docs/sdk/0qgi3uyhotv62-account)
+For developers who prefer to dive straight into the code, the SDK API documentation provides a comprehensive reference
+for all the SDK's classes, methods, and interfaces. The documentation is generated from the SDK's TypeScript source code.
 
-To view the API documentation for this package locally, open `docs/index.html`.
-To regenerate the documentation, run `npx jsdoc --configure jsdoc.json --verbose`
+### [Leo Language Documentation](https://docs.leo-lang.org)
+For developers who want to build their own zero knowledge programs, the Leo Language provides an easy-to-use imperative
+programming language for writing zero knowledge programs on Aleo. In conjuction with the SDK, private programs built
+using Leo can be turned into fully functional private web applications.