docs: add WebAssembly README file

Author: jan-ferdinand

README.md

@@ -11,40 +11,25 @@ A collection of cryptography primitives written in Rust.
 This library contains primarily the following cryptographic primitives:
 
 - The Tip5 hash function
-  - [The Tip5 Hash Function for Recursive STARKs](https://eprint.iacr.org/2023/107)
+    - [The Tip5 Hash Function for Recursive STARKs](https://eprint.iacr.org/2023/107)
 - Lattice-crypto
-  - arithmetic for the quotient ring $\mathbb{F}_ p[X] / \langle X^{64} + 1 \rangle$
-  - arithmetic for modules over this quotient ring
-  - a IND-CCA2-secure key encapsulation mechanism
-  - [Lattice-Based Cryptography in Miden VM](https://eprint.iacr.org/2022/1041)
+    - arithmetic for the quotient ring $\mathbb{F}_ p[X] / \langle X^{64} + 1 \rangle$
+    - arithmetic for modules over this quotient ring
+    - a IND-CCA2-secure key encapsulation mechanism
+    - [Lattice-Based Cryptography in Miden VM](https://eprint.iacr.org/2022/1041)
 - `BFieldElement`, `XFieldElement`
-  - The prime-field type $\mathbb{F}_p$ where $p = 2^{64} - 2^{32} + 1$
-  - The extension field $\mathbb{F}_p[x]/(x^3 - x + 1)$
-  - A codec trait for encoding and decoding structs as `Vec`s of `BFieldElement`
-  - [An efficient prime for number-theoretic transforms](https://cp4space.hatsya.com/2021/09/01/an-efficient-prime-for-number-theoretic-transforms/)
+    - The prime-field type $\mathbb{F}_p$ where $p = 2^{64} - 2^{32} + 1$
+    - The extension field $\mathbb{F}_p[x]/(x^3 - x + 1)$
+    - A codec trait for encoding and decoding structs as `Vec`s of `BFieldElement`
+    - [An efficient prime for number-theoretic transforms](https://cp4space.hatsya.com/2021/09/01/an-efficient-prime-for-number-theoretic-transforms/)
 - NTT
-  - Number Theoretic Transform (discrete Fast Fourier Transform)
-  - [Anatomy of a STARK, Part 6: Speeding Things Up](https://neptune.cash/learn/stark-anatomy/faster/)
-- Univariate and multivariate polynomials
+    - Number Theoretic Transform (discrete Fast Fourier Transform)
+    - [Anatomy of a STARK, Part 6: Speeding Things Up](https://neptune.cash/learn/stark-anatomy/faster/)
+- Univariate polynomials
 - Merkle Trees
 - Merkle Mountain Ranges
 
-## Release protocol
+## Wasm support
 
-While twenty-first's version is `0.x.y`, releasing a new version:
-
-1. Is the release backwards-compatible?
-   Then the new version is `0.x.y+1`. Otherwise the new version is `0.x+1.0`.
-2. Checkout the last commit on Mjolnir, and run `make bench-publish`. Save the benchmark's result
-   and verify that there is no performance degradation.
-3. Create a commit that increases `version = "0.x.y"` in twenty-first/Cargo.toml.
-   The commit message should give a one-line summary of each release change. Include the benchmark
-   result at the bottom.
-4. Have a `v0.x.y` [git tag][tag] on this commit created. (`git tag v0.x.y [sha]`, `git push upstream --tags`)
-5. Have this commit `cargo publish`ed on [crates.io][crates] and in GitHub [tags][tags].
-
-[tag]: https://git-scm.com/book/en/v2/Git-Basics-Tagging
-[tags]: https://github.com/Neptune-Crypto/twenty-first/tags
-[crates]: https://crates.io/crates/twenty-first/versions
-
-If you do not have the privilege to create git tags or run `cargo publish`, submit a PR and the merger will take care of these.
+The `twenty-first` library can be built for WebAssembly. See the [dedicated readme](twenty-first/README-wasm32.md) for
+further information.

twenty-first/README-wasm32.md

@@ -0,0 +1,71 @@
+# Building and Testing `twenty-first` for wasm32
+
+This document provides instructions on how to build and test the `twenty-first` crate for the `wasm32-unknown-unknown`
+target, which allows the library to run in WebAssembly environments.
+
+## What is wasm32?
+
+WebAssembly (Wasm) is a binary instruction format for a stack-based virtual machine. The `wasm32-unknown-unknown` target
+allows Rust code to be compiled into Wasm, enabling high-performance applications to run directly in web browsers and
+other Wasm-compatible environments. This is ideal for bringing computationally intensive tasks, like the cryptographic
+operations in `twenty-first`, to the web without sacrificing performance.
+
+For more detailed information, see the official [WebAssembly website](https://webassembly.org/).
+
+## Required Tools and Setup
+
+To build and test for `wasm32`, you need to set up your Rust environment with the correct target and tooling.
+
+### Add the `wasm32` Target
+
+First, add the `wasm32-unknown-unknown` target to your Rust toolchain using `rustup`:
+
+```shell
+rustup target add wasm32-unknown-unknown
+```
+
+### Install `wasm-pack`
+
+`wasm-pack` is the primary tool for building, testing, and publishing Rust-generated WebAssembly. It coordinates the
+build process and handles the interaction with other tools like `wasm-bindgen`.
+
+Install `wasm-pack` using `cargo`:
+
+```shell
+cargo install wasm-pack
+```
+
+### Install Node.js (for Testing)
+
+Running the `wasm32` test suite requires a JavaScript runtime. `wasm-pack` uses Node.js for this purpose.
+
+You must have Node.js v20 (LTS) or later installed. The `getrandom` crate, a dependency for our tests, requires the Web
+Crypto API, which is stable and fully supported in all modern LTS releases of Node.js.
+
+You can download Node.js from the [official Node.js website](https://nodejs.org/) or install it using a version manager
+like `nvm`.
+
+## Build and Test Commands
+
+With the environment configured, you can now build and test the crate. Make sure your current working directory is
+`twenty-first/twenty-first` before executing any of the commands below.
+
+### Build the Crate
+
+To compile the `twenty-first` crate for WebAssembly, run the following command:
+
+```shell
+wasm-pack build --target nodejs
+```
+
+This command compiles the crate and generates the necessary JavaScript bindings, placing the output in a `pkg/`
+directory.
+
+### Run Tests
+
+To run the test suite for the `wasm32` target, use the `test` command from `wasm-pack`. This command will compile the
+tests and execute them using your installed Node.js runtime.
+
+```shell
+wasm-pack test --node
+```