logos-delivery-rust-bindings/waku-bindings

Waku Rust bindings

Rust api on top of waku-sys bindgen bindings to the logos-delivery C FFI.

Usage

Add this to your Cargo.toml:

[dependencies]
waku-bindings = "0.1.0"

Testing

Prerequisites

Before running tests you need the following tools installed:

• Rust toolchain (stable) — install via rustup
• Nim 2.x — required to compile the underlying logos-delivery library
• Make — used by the build script to compile the native library
• GCC or Clang — C compiler required by the build

Setup

Clone the repository with submodules:

git clone --recurse-submodules https://github.com/logos-messaging/logos-delivery-rust-bindings.git
cd logos-delivery-rust-bindings

If you already cloned without submodules:

git submodule update --init --recursive

The cargo build step (including test builds) will automatically:

1. Initialize and update git submodules
2. Build the native libwaku static library via make libwaku STATIC=1
3. Generate Rust FFI bindings via bindgen

Running the tests

From the repo root or the waku-bindings/ directory:

cargo test

Tests must run serially — they spin up real Waku nodes that bind to local TCP ports. Running them in parallel causes port conflicts. The serial_test crate enforces this automatically, but if you run tests manually ensure only one test process is active at a time.

To run a specific test:

cargo test <test_name>

For example:

cargo test default_echo
cargo test node_restart

To see log output while testing:

cargo test -- --nocapture

What the tests cover

Test	Description
default_echo	Creates two nodes, subscribes both to a relay topic, publishes a message from node 1, and verifies node 2 receives it
node_restart	Creates a node, starts and stops it three times in a row to verify lifecycle correctness

About Waku

Waku is the communication layer for Web3. Decentralized communication that scales.

Private. Secure. Runs anywhere.

What is Waku?

Waku is a suite of privacy-preserving, peer-to-peer messaging protocols.

Waku removes centralized third parties from messaging, enabling private, secure, censorship-free communication with no single point of failure.

Waku provides privacy-preserving capabilities, such as sender anonymity, metadata protection and unlinkability to personally identifiable information.

Waku is designed for generalized messaging, enabling human-to-human, machine-to-machine or hybrid communication.

Waku runs everywhere: desktop, server, including resource-restricted devices, such as mobile devices and browsers.

The first version of Waku had its origins in the Whisper protocol, with optimizations for scalability and usability. Waku v2 is a complete rewrite. Its relay protocol implements pub/sub over libp2p, and also introduces additional capabilities:

1. Retrieving historical messages for mostly-offline devices.
2. Adaptive nodes, allowing for heterogeneous nodes to contribute.
3. Bandwidth preservation for light nodes.

This makes it ideal for running a p2p protocol on mobile, or in other similarly resource-restricted environments.

Read the Waku docs