@chrom-ar/waku-client

A TypeScript client library for the Waku protocol, simplifying decentralized communication with end-to-end encryption support.

Overview

@chrom-ar/waku-client provides a simplified interface to connect, subscribe, and publish messages to the Waku network - a family of privacy-preserving, peer-to-peer messaging protocols built on libp2p. This client makes it easy to integrate Waku's decentralized communication capabilities into your applications.

Features

• 🔄 Easy connection to Waku nodes
• 📬 Simple subscribe/publish messaging patterns
• 🔒 End-to-end encryption (ECIES) support
• 🌐 Custom topic namespacing
• 🔁 Automatic reconnection handling
• 📝 Comprehensive logging
• 🧩 TypeScript support

Installation

npm install @chrom-ar/waku-client
# or
yarn add @chrom-ar/waku-client

Quick Start

import WakuClient from '@chrom-ar/waku-client';

// Configure environment variables for Waku
process.env.WAKU_TOPIC_PLACEHOLDER = '/placeholder/';
process.env.WAKU_TOPIC_DEFAULT = '/myapp/v1';
process.env.WAKU_STATIC_PEERS = '/dns4/node-01.do-ams3.waku.connect.storage/tcp/443/wss/p2p/16Uiu2HAm6HVpMpSFe9w7WJ7TYY3WxzqZMiDPn6PeVkxQTbuGkTgb';

// Initialize the client
const client = await WakuClient.start();

// Subscribe to a topic
await client.subscribe('chat', (message) => {
  console.log('Received message:', message.body);
}, { expirationSeconds: 60 });

// Send a message
await client.sendMessage(
  { text: 'Hello, Waku world!' },
  'chat', 
  '' // replyTo (optional)
);

// Unsubscribe when done
await client.unsubscribe('chat');

// Stop the client when your application exits
await client.stop();

Configuration

The client can be configured through environment variables:

| Variable | Description | Default | |----------|-------------|---------| | WAKU_TOPIC_PLACEHOLDER | Placeholder for topic substitution | Required | | WAKU_TOPIC_DEFAULT | Default topic value | Required | | WAKU_PING_COUNT | Number of connection attempts | 5 | | WAKU_STATIC_PEERS | Comma-separated list of peer addresses | Empty string | | WAKU_STATIC_CLUSTER_ID | Waku cluster ID | -1 | | WAKU_STATIC_SHARD | Waku shard number | -1 | | WAKU_ENCRYPTION_PRIVATE_KEY | Hex-encoded private key for message encryption | Optional |

You can also pass a custom configuration getter to the start method:

const client = await WakuClient.start((key) => {
  // Custom logic to retrieve configuration values
  return myConfigStore[key];
});

Encryption

To enable end-to-end encryption:

1. Generate a private key (or use an existing one)
2. Set the WAKU_ENCRYPTION_PRIVATE_KEY environment variable
3. Enable encryption when subscribing:

// Subscribe with encryption enabled
await client.subscribe('private-chat', (message) => {
  console.log('Received encrypted message:', message.body);
}, { encrypted: true });

// Send an encrypted message to a specific recipient
await client.sendMessage(
  { text: 'Secret message!' },
  'private-chat',
  '',
  recipientPublicKey // The recipient's public key
);

API Reference

WakuClient

Static Methods

• start(settingGetter?: Function): Promise<WakuClient>
  Initialize and connect a new WakuClient.

Instance Methods

• subscribe(topic: string, callback: Function, options?: Object): Promise<void>
  Subscribe to messages on a specific topic.

• sendMessage(body: object, topic: string, replyTo: string, encryptionPubKey?: string): Promise<void>
  Send a message to a specific topic.

• unsubscribe(topic: string): Promise<void>
  Unsubscribe from a topic.

• stop(): Promise<void>
  Disconnect and clean up resources.

• setLogger(logger: Logger): void
  Set a custom logger.

• defaultIntentsTopic(): string
  Get the default topic for intents.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.