Installation

Beo JavaScript and WebAssembly bindings for building zero-knowledge web applications.

Rust compiles easily to WebAssembly but creating the glue code necessary to use compiled WebAssembly binaries from other languages such as JavaScript is a challenging task. wasm-bindgen is a tool that simplifies this process by auto-generating JavaScript bindings to Rust code that has been compiled into WebAssembly.

This crate uses wasm-bindgen to create JavaScript bindings to Beo source code so that it can be used to create zero knowledge proofs directly within web browsers and NodeJS.

Functionality exposed by this crate includes:

• Beoaccount management objects

• Beo primitives such as Records, Programs, and Transactions and their associated helper methods

• A ProgramManager object that contains methods for authoring, deploying, and interacting with Beo programs

More information on these concepts can be found at the Beo Developer Hub.

Usage​

The wasm-pack tool is used to compile the Rust code in this crate into JavaScript modules which can be imported into other JavaScript projects.

Install Wasm-Pack​

curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

Build Instructions​

The general syntax for compiling rust into WebAssembly based JavaScript modules with wasm-pack is as follows:

wasm-pack build --target <target> --out-dir <out-dir> -- --features <crate-features>

Invoking this command will build a JavaScript module in the current directory with the default name pkg (which can be changed as necessary using the --out-dir flag). This folder can then be imported directly as a JavaScript module by other JavaScript modules.

There are 3 possible JavaScript modules that wasm-pack can be used to generate

when run within this crate:

1. NodeJS module: Used to build NodeJS applications.

2. Single-Threaded browser module: Used to build browser-based web applications.

3. Multi-Threaded browser module: Used to build browser-based web applications which use web-worker based multi-threading to achieve significant performance increases.

These 3 modules and how to build them are explained in more detail below.

1. NodeJS Module​

This module has the features of the NodeJS environment built-in. It is single-threaded and unfortunately cannot yet be used to generate Beo program executions or deployments due to current Beo protocol limitations. It can however still be used to perform Beo account, record, and program management tasks.

Build Instructions​

wasm-pack build --release --target nodejs -- --features "serial" --no-default-features

2. Single-Threaded browser module​

This module is very similar to the NodeJS module, however it is built to make use browser-based JavaScript environments and can be used for program execution and deployment.

If used for program execution or deployment, it is suggested to do so on a web-worker as these operations are long-running and will cause a browser window to hang if run in the main thread.

Build Instructions​

wasm-pack build --release --target web

If you are intending to use this for program execution or deployment, it is recommended to build with maximum or close to maximum memory allocation (which is 4 gigabytes for wasm).

RUSTFLAGS='-C link-arg=--max-memory=4294967296' wasm-pack build --release --target web

3. Multi-Threaded browser module​

This module is also built for browser-based JavaScript environments, however it is built to make use of Rust-native threading via web-workers (using the approach outlined in the rayon-wasm-bindgen crate). It is the most complex to use, but it will run significantly faster when performing Beo program executions and deployments and should be the choice for performance-critical applications.

To build with threading enabled, it is necessary to use nightly Rust and set certain RUSTFLAGS to enable the necessary threading features. The wasm-pack build command is shown below.

# Set rustflags to enable atomics, 
# bulk-memory, and mutable-globals. 
# Also, set the maximum memory to 
# 4294967296 bytes (4GB).
export RUSTFLAGS='-C target-feature=+atomics,+bulk-memory,+mutable-globals -C link-arg=--max-memory=4294967296'

# Use rustup to run the following commands 
# with the nightly version of Rust.
rustup run nightly \

# Use wasm-pack to build the project. 
# Specify the 'parallel' feature for 
# multi-threading and the 'browser' 
# feature to enable program execution
# and include necessary unstable options
# using -Z
wasm-pack build --release --target web --out-dir pkg-parallel \
-- --features "parallel, browser" --no-default-features -Z build-std=panic_abort,std

Testing​

Run tests in NodeJS

wasm-pack test --node

Run tests in a browser

wasm-pack test --[firefox/chrome/safari]

Building Web Apps​

Further documentation and tutorials as to how to use the modules built from this crate to build web apps will be built in the future. However - in the meantime, the provable.tools website is a good example of how to use these modules to build a web app. Its source code can be found in the Provable SDK repo in the website folder.