@puzzlehq/aleo-wasm-web 0.5.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +596 -0
- package/README.md +136 -0
- package/aleo_wasm.d.ts +1224 -0
- package/aleo_wasm.js +3112 -0
- package/aleo_wasm_bg.wasm +0 -0
- package/package.json +31 -0
package/README.md
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
[](https://crates.io/crates/aleo-wasm)
|
|
2
|
+
[](https://aleo.org)
|
|
3
|
+
[](./LICENSE.md)
|
|
4
|
+
|
|
5
|
+
[![github]](https://github.com/AleoHQ/sdk) [![crates-io]](https://crates.io/crates/aleo-wasm) [![docs-rs]](https://docs.rs/aleo-wasm/latest/aleo-wasm/)
|
|
6
|
+
|
|
7
|
+
[github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
|
|
8
|
+
[crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
|
|
9
|
+
[docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
|
|
10
|
+
|
|
11
|
+
# Aleo Wasm
|
|
12
|
+
|
|
13
|
+
Aleo JavaScript and WebAssembly bindings for building zero-knowledge web applications.
|
|
14
|
+
|
|
15
|
+
`Rust` compiles easily to `WebAssembly` but creating the glue code necessary to use compiled WebAssembly binaries
|
|
16
|
+
from other languages such as JavaScript is a challenging task. `wasm-bindgen` is a tool that simplifies this process by
|
|
17
|
+
auto-generating JavaScript bindings to Rust code that has been compiled into WebAssembly.
|
|
18
|
+
|
|
19
|
+
This crate uses `wasm-bindgen` to create JavaScript bindings to Aleo source code so that it can be used to create zero
|
|
20
|
+
knowledge proofs directly within `web browsers` and `NodeJS`.
|
|
21
|
+
|
|
22
|
+
Functionality exposed by this crate includes:
|
|
23
|
+
* Aleo account management objects
|
|
24
|
+
* Aleo primitives such as `Records`, `Programs`, and `Transactions` and their associated helper methods
|
|
25
|
+
* A `ProgramManager` object that contains methods for authoring, deploying, and interacting with Aleo programs
|
|
26
|
+
|
|
27
|
+
More information on these concepts can be found at the [Aleo Developer Hub](https://developer.aleo.org/concepts).
|
|
28
|
+
|
|
29
|
+
## Usage
|
|
30
|
+
The [wasm-pack](https://crates.io/crates/wasm-pack) tool is used to compile the Rust code in this crate into JavaScript
|
|
31
|
+
modules which can be imported into other JavaScript projects.
|
|
32
|
+
|
|
33
|
+
#### Install Wasm-Pack
|
|
34
|
+
```bash
|
|
35
|
+
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Build Instructions
|
|
39
|
+
The general syntax for compiling rust into WebAssembly based JavaScript modules with
|
|
40
|
+
[wasm-pack](https://crates.io/crates/wasm-pack) is as follows:
|
|
41
|
+
```bash
|
|
42
|
+
wasm-pack build --target <target> --out-dir <out-dir> -- --features <crate-features>
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Invoking this command will build a JavaScript module in the current directory with the default name `pkg` (which can
|
|
46
|
+
be changed as necessary using the `--out-dir` flag). This folder can then be imported directly as a JavaScript module
|
|
47
|
+
by other JavaScript modules.
|
|
48
|
+
|
|
49
|
+
There are 3 possible JavaScript modules that [wasm-pack](https://crates.io/crates/wasm-pack) can be used to generate
|
|
50
|
+
when run within this crate:
|
|
51
|
+
1. **NodeJS module:** Used to build NodeJS applications.
|
|
52
|
+
2. **Single-Threaded browser module:** Used to build browser-based web applications.
|
|
53
|
+
3. **Multi-Threaded browser module:** Used to build browser-based web applications which use web-worker based
|
|
54
|
+
multi-threading to achieve significant performance increases.
|
|
55
|
+
|
|
56
|
+
These 3 modules and how to build them are explained in more detail below.
|
|
57
|
+
|
|
58
|
+
### 1. NodeJS Module
|
|
59
|
+
|
|
60
|
+
This module has the features of the NodeJS environment built-in. It is single-threaded and unfortunately cannot yet be
|
|
61
|
+
used to generate Aleo program executions or deployments due to current Aleo protocol limitations. It can however still
|
|
62
|
+
be used to perform Aleo account, record, and program management tasks.
|
|
63
|
+
|
|
64
|
+
#### Build Instructions
|
|
65
|
+
```bash
|
|
66
|
+
wasm-pack build --release --target nodejs -- --features "serial" --no-default-features
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### 2. Single-Threaded browser module
|
|
70
|
+
|
|
71
|
+
This module is very similar to the NodeJS module, however it is built to make use browser-based JavaScript environments
|
|
72
|
+
and can be used for program execution and deployment.
|
|
73
|
+
|
|
74
|
+
If used for program execution or deployment, it suggested to do so on a web-worker as these operations are long-running
|
|
75
|
+
and will cause a browser window to hang if run in the main thread.
|
|
76
|
+
|
|
77
|
+
#### Build Instructions
|
|
78
|
+
```bash
|
|
79
|
+
wasm-pack build --release --target web
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
If you are intending to use this for program execution or deployment, it is recommended to build
|
|
83
|
+
with maximum or close to maximum memory allocation (which is 4 gigabytes for wasm).
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
RUSTFLAGS='-C link-arg=--max-memory=4294967296' wasm-pack build --release --target web
|
|
87
|
+
````
|
|
88
|
+
|
|
89
|
+
### 3. Multi-Threaded browser module
|
|
90
|
+
|
|
91
|
+
This module is also built for browser-based JavaScript environments, however it is built to make use of Rust-native
|
|
92
|
+
threading via web-workers (using the approach outlined in the `rayon-wasm-bindgen` crate). It is the most complex to use,
|
|
93
|
+
but it will run significantly faster when performing Aleo program executions and deployments and should be the choice for
|
|
94
|
+
performance-critical applications.
|
|
95
|
+
|
|
96
|
+
To build with threading enabled, it is necessary to use `nightly Rust` and set certain `RUSTFLAGS` to enable the
|
|
97
|
+
necessary threading features. The `wasm-pack` build command is shown below.
|
|
98
|
+
```bash
|
|
99
|
+
# Set rustflags to enable atomics,
|
|
100
|
+
# bulk-memory, and mutable-globals.
|
|
101
|
+
# Also, set the maximum memory to
|
|
102
|
+
# 4294967296 bytes (4GB).
|
|
103
|
+
export RUSTFLAGS='-C target-feature=+atomics,+bulk-memory,+mutable-globals -C link-arg=--max-memory=4294967296'
|
|
104
|
+
|
|
105
|
+
# Use rustup to run the following commands
|
|
106
|
+
# with the nightly version of Rust.
|
|
107
|
+
rustup run nightly \
|
|
108
|
+
|
|
109
|
+
# Use wasm-pack to build the project.
|
|
110
|
+
# Specify the 'parallel' feature for
|
|
111
|
+
# multi-threading and the 'browser'
|
|
112
|
+
# feature to enable program execution
|
|
113
|
+
# and include necessary unstable options
|
|
114
|
+
# using -Z
|
|
115
|
+
wasm-pack build --release --target web --out-dir pkg-parallel \
|
|
116
|
+
-- --features "parallel, browser" --no-default-features -Z build-std=panic_abort,std
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Testing
|
|
120
|
+
|
|
121
|
+
Run tests in NodeJS
|
|
122
|
+
```bash
|
|
123
|
+
wasm-pack test --node
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Run tests in a browser
|
|
127
|
+
```bash
|
|
128
|
+
wasm-pack test --[firefox/chrome/safari]
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## Building Web Apps
|
|
132
|
+
|
|
133
|
+
Further documentation and tutorials as to how to use the modules built from this crate to build web apps will be built
|
|
134
|
+
in the future. However - in the meantime, the [aleo.tools](https://aleo.tools) website is a good
|
|
135
|
+
example of how to use these modules to build a web app. Its source code can be found in the
|
|
136
|
+
[Aleo SDK](https://github.com/AleoHQ/sdk) repo in the `website` folder.
|