docs: make the available operations discoverable; document local use

Consuming apps depend on this crate from a local checkout, and the
operations were hard to find: the crate root was `pub use waku_sys::*`,
so everything a caller can do was hidden as methods on a glob-exported
LogosDeliveryCtx.

The crate-root docs now carry an Operations map — node lifecycle,
messaging, reliable channels, and the typed event listeners — with the
method names and a runnable example, so `cargo doc` and reading lib.rs
both show what is callable. The low-level waku_* kernel surface is noted
as the tier beneath.

The README gains a "Using the crate" section: clone + checkout, the
local path dependency, and the Nim/make/Rust build prerequisites.

Also fixes stale rustdoc links in the restored store DTOs and a bare URL
in the config docs, so the doc build is warning-clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -17,6 +17,48 @@
 Rust layer on top of [`logos-messaging-nim`](https://github.com/logos-messaging/logos-messaging-nim) [C FFI bindings](https://github.com/logos-messaging/logos-messaging-nim/blob/master/library/libwaku.h).
 
 
+## Using the crate
+
+For now this crate is consumed from a local checkout rather than a registry.
+
+1. Clone the repo and check out the branch you want:
+
+   ```sh
+   git clone --recurse-submodules https://github.com/logos-messaging/logos-delivery-rust-bindings
+   cd logos-delivery-rust-bindings
+   git checkout <branch>
+   git submodule update --init --recursive
+   ```
+
+2. Point your app at it by path:
+
+   ```toml
+   # your app's Cargo.toml
+   [dependencies]
+   waku-bindings = { path = "../logos-delivery-rust-bindings/waku-bindings" }
+   ```
+
+### Build prerequisites
+
+`waku-bindings` builds the underlying Nim library from source the first time,
+so the toolchain has to be present:
+
+- **Nim** and **nimble** (installed by the vendored `make` targets, or bring
+  your own on `PATH`)
+- **make** and a C/C++ toolchain
+- A **Rust** toolchain (RLN is built from source)
+
+The first build compiles the whole logos-delivery tree and is slow; subsequent
+builds are incremental.
+
+## What you can call
+
+Everything is driven through `LogosDeliveryCtx` (re-exported at the crate root).
+The crate docs group the available operations — node lifecycle, messaging,
+reliable channels, and the typed event listeners — under **Operations**; run
+`cargo doc --open -p waku-bindings` for the full, linked method list. A minimal
+end-to-end example lives in [`examples/basic`](examples/basic).
+
 ## About Waku
 
 [Waku](https://waku.org/) is a family of robust and censorship-resistant communication protocols enabling privacy-focused messaging for Web3 applications.

waku-bindings/src/general/store.rs

@@ -127,10 +127,10 @@ pub struct StoreResponse {
     #[allow(unused)]
     pub status_desc: String,
 
-    /// Array of retrieved historical messages in [`WakuMessage`] format
+    /// Array of retrieved historical messages in `WakuMessage` format
     // #[serde(default)]
     pub messages: Vec<StoreWakuMessageResponse>,
-    /// Paging information in [`PagingOptions`] format from which to resume further historical queries
+    /// Paging information in `PagingOptions` format from which to resume further historical queries
     #[serde(skip_serializing_if = "Option::is_none")]
     pub pagination_cursor: Option<MessageHash>,
 }

waku-bindings/src/lib.rs

@@ -1,16 +1,79 @@
-//! # Waku
+//! # waku-bindings
 //!
-//! The FFI surface is generated from the Nim source by nim-ffi and re-exported
-//! here wholesale: drive a node through `LogosDeliveryCtx`, and observe it
-//! through its typed `add_on_*_listener` methods. What this crate adds on top is
-//! the domain layer — [`WakuMessage`], [`WakuContentTopic`], [`MessageHash`] and
-//! friends — plus [`WakuNodeConfig`], which serialises to the JSON that
-//! `LogosDeliveryCtx::create` expects.
+//! Rust bindings for logos-delivery (Waku). A node is driven through
+//! [`LogosDeliveryCtx`], generated from the Nim source by nim-ffi and
+//! re-exported here; this crate adds the typed domain layer ([`WakuMessage`],
+//! [`WakuContentTopic`], [`MessageHash`]) and [`WakuNodeConfig`], which
+//! serialises to the JSON [`LogosDeliveryCtx::create`] expects.
+//!
+//! ## Operations
+//!
+//! Every operation is an `async` method on [`LogosDeliveryCtx`] (each also has a
+//! blocking twin without the `_async` suffix). Events are registered with
+//! `add_on_*_listener`, which hand back a typed payload.
+//!
+//! ### Node lifecycle
+//! - [`LogosDeliveryCtx::new_async`] / [`create`](LogosDeliveryCtx::create) —
+//!   build a node from a [`WakuNodeConfig`] JSON string
+//! - [`start_node_async`](LogosDeliveryCtx::start_node_async) /
+//!   [`stop_node_async`](LogosDeliveryCtx::stop_node_async)
+//! - teardown is the `Drop` impl — there is no explicit destroy
+//!
+//! ### Messaging
+//! - [`subscribe_async`](LogosDeliveryCtx::subscribe_async) /
+//!   [`unsubscribe_async`](LogosDeliveryCtx::unsubscribe_async) — by content topic
+//! - [`send_async`](LogosDeliveryCtx::send_async) — takes a [`SendRequest`]
+//!
+//! ### Reliable channels
+//! - [`channel_create_async`](LogosDeliveryCtx::channel_create_async) —
+//!   `(channel_id, content_topic, sender_id, encryption)`; `encryption` is
+//!   `"noop"` today
+//! - [`channel_send_async`](LogosDeliveryCtx::channel_send_async) — takes a
+//!   [`ChannelSendRequest`]
+//! - [`channel_close_async`](LogosDeliveryCtx::channel_close_async)
+//!
+//! ### Events (typed listeners)
+//! - messaging: `add_on_message_{sent,error,propagated,received}_listener`
+//! - connectivity: `add_on_connection_{change,status_change}_listener`,
+//!   `add_on_topic_health_change_listener`
+//! - relay: `add_on_received_message_listener`
+//! - channels: `add_on_channel_message_{received,sent,error}_listener`
+//! - drop one with [`remove_event_listener`](LogosDeliveryCtx::remove_event_listener)
+//!
+//! Beneath these sits the lower-level `waku_*` kernel surface (relay publish,
+//! filter, store, peer management, discovery) — also on [`LogosDeliveryCtx`],
+//! `"use at your own risk"`.
+//!
+//! ## Example
+//!
+//! ```no_run
+//! use waku_bindings::{LogosDeliveryCtx, WakuNodeConfig};
+//! use std::time::Duration;
+//!
+//! # async fn run() -> Result<(), String> {
+//! let config = serde_json::to_string(&WakuNodeConfig {
+//!     tcp_port: Some(60000),
+//!     ..Default::default()
+//! }).unwrap();
+//!
+//! let node = LogosDeliveryCtx::new_async(config, Duration::from_secs(30)).await?;
+//! node.add_on_received_message_listener(|event| {
+//!     println!("received on {}", event.waku_message.content_topic);
+//! });
+//! node.start_node_async().await?;
+//! node.waku_relay_subscribe_async("test".to_string()).await?;
+//! // node is torn down when dropped
+//! # Ok(())
+//! # }
+//! ```
+
 pub mod general;
 pub mod node;
 
-// The generated bindings: LogosDeliveryCtx, ListenerHandle, and one payload type
-// per event.
+// The full generated FFI surface: LogosDeliveryCtx and its methods, the request
+// types (SendRequest, ChannelSendRequest), and one payload type per event. See
+// the Operations section above for the map; browse `LogosDeliveryCtx` in the
+// docs for the complete method list.
 pub use waku_sys::*;
 
 // Required so functions inside libwaku can call RLN functions even if we
@@ -19,6 +82,7 @@ pub use waku_sys::*;
 #[allow(unused)]
 use rln;
 
+// The typed domain layer this crate adds on top of the generated surface.
 pub use general::contenttopic::{Encoding, WakuContentTopic};
 pub use general::store::{StoreQueryRequest, StoreResponse, StoreWakuMessageResponse};
 pub use general::{messagehash::MessageHash, Result, WakuMessage, WakuMessageVersion};

waku-bindings/src/node/config.rs

@@ -94,7 +94,7 @@ pub struct RLNConfig {
     /// On-chain dynamic group management
     #[serde(skip_serializing_if = "Option::is_none")]
     pub dynamic: Option<bool>,
-    /// Path to the RLN merkle tree sled db (https://github.com/spacejam/sled)
+    /// Path to the RLN merkle tree sled db (<https://github.com/spacejam/sled>)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub tree_path: Option<String>,
     /// Message rate in bytes/sec after which verification of proofs should happen