Waku v2 Protocol TypeScript Implementation

To use the Rate Limiting Nullifier (RLN) implementation in your Waku project, install the @waku/rln package using npm.

npm install @waku/rln

The @waku/reliability-tests package provides tests designed to identify edge cases, memory leaks, network inconsistencies, or message delivery issues by running realistic message scenarios in loops over extended periods.

Longevity Test (longevity.spec.ts)

This test runs a js-waku <-> nwaku filter scenario continuously for 2 hours. It monitors:

• Message ID
• Timestamp
• Send/receive status
• Transmission errors

A summary report is printed at the end of the run, and any errors encountered during the 2-hour window will cause the test to fail.

# From the project root
npm run test:longevity

To set up the Waku browser test environment locally, follow these steps to build the application, start the server, or run it via Docker.

Local Execution

1. Build the project: npm run build
2. Start the server on port 8080: npm run start:server

Docker Execution

Use Docker to run a containerized simulation of a Waku light node:

1. Build the image: npm run docker:build
2. Run the container: docker run -p 8080:8080 waku-browser-tests:local

# Build the application
npm run build

# Start the server (port 8080)
npm run start:server

# Build and run Docker container
npm run docker:build
docker run -p 8080:8080 waku-browser-tests:local

The @waku/rln package uses wagmi to generate TypeScript bindings for interacting with RLN smart contracts. While these typings are typically bundled, you must manually regenerate them if the underlying waku-rlnv2-contract repository has been updated.

npm run setup:contract-abi

When using Docker, you can pass configuration via environment variables using the -e flag.

# Run with ENR bootstrap
docker run -p 8080:8080 \
  -e WAKU_ENR_BOOTSTRAP="enr:-QEnuE..." \
  -e WAKU_CLUSTER_ID="1" \
  waku-browser-tests:local

# Run with specific configuration (Static Sharding)
docker run -p 8080:8080 \
  -e WAKU_CLUSTER_ID="2" \
  -e WAKU_SHARD="0" \
  waku-browser-tests:local

Symmetric encryption uses a single shared key for both encrypting and decrypting messages. Use generateSymmetricKey to create a new key, createEncoder with that key to encrypt messages for sending, and createDecoder with the same key to decrypt incoming messages.

This is useful when two or more parties already share a secret key.

import {
  createDecoder,
  createEncoder,
  generateSymmetricKey
} from "@waku/message-encryption/symmetric";

// Generate a random key
const key = generateSymmetricKey();

// To send messages, create an encoder
const encoder = createEncoder(contentTopic, key);

// For example
waku.lightPush.push(encoder, { payload });

// To receive messages, create a decoder
const decoder = createDecoder(contentTopic, key);

// For example
await waku.store.queryOrderedCallback([decoder], (msg) => {
  // ...
});

The package includes several test suites for verifying server functionality, integration, and end-to-end flows.

Test Commands

• npm test: Runs basic server functionality tests.
• npm run test:server: Runs server-only tests (server.spec.ts).
• npm run test:e2e: Runs end-to-end tests (e2e.spec.ts) using nwaku nodes.
• npm run test:integration: Runs integration tests (integration.spec.ts) involving Docker container integration.
• npm run test:all: Runs all available tests.

To generate the API documentation on your local machine, clone the repository, install dependencies, and run the documentation build command.

Note: You can also use nix develop to set up the development environment before running these commands.

# Using standard npm
git clone https://github.com/waku-org/js-waku.git
cd js-waku
npm install
npm run doc

# Using Nix shell
git clone https://github.com/waku-org/js-waku.git
cd js-waku
nix develop
npm install
npm run doc