Javascript/Typescript

Tools for Building Zero Knowledge Web Apps​

The Provable SDK is a collection of JavaScript libraries for building zero knowledge web applications in both the browser and node.js.

Overview​

Beo provides the ability to run programs in zero knowledge. The Provable SDK provides the tools to use these programs within the browser and all other levels of the web stack to build privacy preserving applications.

The Provable SDK provides the following functionality (Click to see examples):

1. Beo account management

2. Web-based program execution and deployment

3. Beo credit transfers

4. Management of program state and data

5. Communication with the Beo network

Table of Contents​

• Installation

• Usage

  • Zero Knowledge Web App Examples

    • Create Leo App

    • provable.tools

  • Create An Beo Account

  • Execute Beo Programs

    • Beo Programs

    • Program Execution Model

    • WebAssembly Initialization

    • Local Program Execution

    • Online Program Execution

    • Program Proving Keys and Records

    • Deploy Programs

    • React Example

  • Beo Credit Transfers

    • Beo Credits

    • Transfer Beo Credits

    • Check Public Balances

  • Program Data and Private State

    • Private State Data: Records

    • Record Usage Example

    • Public State Data: Mappings

    • Reading Mappings

    • Initializing and Updating Mappings

  • Communicating with the Beo Network

• Further Documentation

Installation​

NPM / Yarn​

To install Provable SDK, run the following commands in your project's root:

npm install @provablehq/sdk or yarn add @provablehq/sdk.

Build from source​

To build the project from source, clone the sdk repository and execute the following command at /sdk:

yarn build:all

Ensure compatibility with ES modules​

In your project's package.json, ensure that the following line is added above scripts:

{
  "type": "module",
}

Usage​

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. 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-react-app by running: npm create leo-app@latest

Provable Tools​

Additionally, the SDK powers 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

1. Create an Beo Account​

The first step in operating a zero knowledge web application is creating a cryptographic identity for a user. In the context of Beo, this process starts by generating a private key. From this private key, several keys that enable a user to interact with Beo programs can be derived.

These keys include:

Private Key​

The key used to represent an identity of an individual user. This key is used to authorize zero knowledge program execution.

View Key​

This key is derived from the private key and can be used to identify all records and transaction data that belongs to an individual user.

Compute Key​

A key that can be used to trustlessly run applications and generate transactions on a user's behalf.

Address​

A public address that can be used to trustlessly identify a user in order for that user to receive official Beo credits or unique data defined by other zero-knowledge Beo programs.

All of these keys can be created using the account object:

import { Account } from '@provablehq/sdk';

const account = new Account();

// Individual keys can 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 Beo Programs​

2.1 Beo Programs​

Beo 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.

Zero-Knowledge programs are written in one of two languages:

1. Leo: A high level, developer friendly language for developing zero knowledge programs.

2. Beo Instructions: A low level language that provides developers fine grained control over the execution flow of zero knowledge programs. Leo programs are compiled into Beo Instructions under the hood.

Hello world in the Leo Language​

// A simple program adding two numbers together
program helloworld.Beo{
  transition hello(public a: u32, b: u32) -> u32 {
      let c: u32 = a + b;
      return c;
  }
}

Hello world in Beo instructions​

program helloworld.Beo;

// The leo code above compiles to the following Beo 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​

The SDK provides the ability to execute Beo Instructions programs %100 client-side within the browser.

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 into WebAssembly. JavaScript bindings to this WebAssembly code allows execution of programs in zero knowledge fully within the browser without requiring any external communication with the internet. Users interested in lower level details on how this is achieved can visit the Beo-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. An Beo program in beo 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 client-side within WebAssembly

5. The result is returned to the user

6. (Optional) A fully encrypted zero knowledge transcript of the execution is optionally sent to the Beo network