js-rln/README.md

# `@waku/rln`

This browser library enables the usage of RLN with Waku, as specified in the [Waku v2 RLN Relay RFC](https://rfc.vac.dev/spec/17/).

## Purpose

### RLN Cryptography

The RLN cryptographic function are provided by [zerokit](https://github.com/vacp2p/zerokit/).
This is imported via the `@waku/zerokit-rln-wasm` dependencies which contains a WASM extract of zerokit's RLN functions.

Note that RLN Credentials generated with `zerokit`, and hence `@waku/rln`, are compatible with semaphore credentials.

Note that the WASM blob uses browser APIs, **NodeJS is not supported**.

### Waku Interfaces

This library implements the [`IEncoder`](https://github.com/waku-org/js-waku/blob/604ba1a889f1994bd27f5749107c3a5b2ef490d5/packages/interfaces/src/message.ts#L43)
and [`IDecoder`](https://github.com/waku-org/js-waku/blob/604ba1a889f1994bd27f5749107c3a5b2ef490d5/packages/interfaces/src/message.ts#L58)
interfaces of [js-waku](https://github.com/waku-org/js-waku).

This enables a seamless usage with js-waku applications, as demonstrated in the [rln-js example](https://github.com/waku-org/js-waku-examples/tree/master/examples/rln-js).

### Comparison to Existing Work

[Rate-Limiting-Nullifier/rlnjs](https://github.com/Rate-Limiting-Nullifier/rlnjs)
is an existing JavaScript / TypeScript library that already provides RLN cryptographic functionalities for the browser.

The core difference is that `@waku/rln` uses [zerokit](https://github.com/vacp2p/zerokit/) for cryptography and provide opinionated interfaces to use RLN specifically in the context of Waku.

## Install

```
npm install @waku/rln

# or with yarn

yarn add @waku/rln
```

Or to use ESM import directly from a `<script>` tag:

```html
<script type="module">
  import * as rln from "https://unpkg.com/@waku/rln@0.0.13/bundle/index.js";
</script>
```

## Running example app

```
git clone https://github.com/waku-org/js-rln

cd js-rln/example

npm install  # or yarn

npm start
```

Browse http://localhost:8080 and open the dev tools console to see the proof being generated and its verification

## Usage

### Initializing the Library

```js
import * as rln from "@waku/rln";

const rlnInstance = await rln.create();
```

#### Generating RLN Membership Credentials

```js
let credentials = rlnInstance.generateIdentityCredentials();
```

### Generating RLN Membership Keypair Using a Seed

This can be used to generate credentials from a signature hash (e.g. signed by an Ethereum account).

```js
let credentials = rlnInstance.generateSeededIdentityCredentials(seed);
```

### Adding Membership Keys Into Merkle Tree

```js
rlnInstance.insertMember(credentials.IDCommitment);
```

### Generating a Proof

```js
// prepare the message
const uint8Msg = Uint8Array.from(
  "Hello World".split("").map((x) => x.charCodeAt())
);

// setting up the epoch (With 0s for the test)
const epoch = new Uint8Array(32);

// generating a proof
const proof = await rlnInstance.generateProof(
  uint8Msg,
  index,
  epoch,
  credentials.IDSecretHash
);
```

### Verifying a Proof

```js
try {
  // verify the proof
  const verificationResult = rlnInstance.verifyProof(proof, uint8Msg);
  console.log("Is proof verified?", verificationResult ? "yes" : "no");
} catch (err) {
  console.log("Invalid proof");
}
```

### Updating Circuit, Verification Key and Zkey

The RLN specs defines the defaults.
These values are fixed and should not change.
Currently, these [resources](https://github.com/vacp2p/zerokit/tree/master/rln/resources/tree_height_20) are being used.
If they change, this file needs to be updated in `resources.ts` which
contains these values encoded in base64 in this format:

```
const verification_key = "...";
const circuit = "..."; // wasm file generated by circom
const zkey = "...";
export {verification_key, circuit, zkey};
```

A tool like GNU's `base64` could be used to encode this data.

### Updating Zerokit

1. Make sure you have NodeJS installed and a C compiler
2. Install wasm-pack

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

3. Compile RLN for wasm

```
git clone https://github.com/vacp2p/zerokit
cd zerokit/rln-wasm
wasm-pack build --release
```

4. Copy `pkg/rln*` into `src/zerokit`

## Bugs, Questions & Features

If you encounter any bug or would like to propose new features, feel free to [open an issue](https://github.com/waku-org/js-rln/issues/new/).

For more general discussion, help and latest news, join [Vac Discord](https://discord.gg/PQFdubGt6d) or [Telegram](https://t.me/vacp2p).

## License

Licensed and distributed under either of

- MIT license: [LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT

or

- Apache License, Version 2.0, ([LICENSE-APACHE-v2](LICENSE-APACHE-v2) or http://www.apache.org/licenses/LICENSE-2.0)

at your option. These files may not be copied, modified, or distributed except according to those terms.