feat: waku api send #3669

NagyZoltanPeter · 2025-12-15T15:30:46Z

Notice

This PR is still under work, do expect some additions and fixes.
For completion:

WIP: Add a dynamic service peer manager, that register last state (result of dial and libp2p call) of the service peer and can select next one accordingly - Will follow up in next PR
WIP: Fix Event- and RequestBroker implementation to support multiple usage context within a single thread.
Currently the brokers are thread wise global, but this leads to test failures where we instantiate many Waku node instances.
Subscribe API added to support auto - subscribe upon send.
WIP: all-round unit testing, tests are not pushed yet as they fail to compile and run in many cases.

Description

Introduce new, simple send interface at ~~waku~~logos-messaging api level. That takes a new abstraction call MessageEnvelop which embodies content_topic and payload and ephemeral information in client side.

The interface returns with a RequestId - unique to each call and enables tracking of message events - on success, or error description.
The operation is non blocking, which means at the moment of call there are very limited what information can be reported to the caller.
Therefore user can expect three events to be emitted upon the operation result.

MessagePropagatedEvent - Message is delivered to the network with less confidence (is relayed or lightpush initiated with success)
MessageSentEvent - Message is validated via a store node, ensures that message is on the gossip network.
MessageErrorEvent - Message could not be sent, reason is described as string.

Former - unused - DeliverManager is reworked completely to fulfill the role of DeliveryService. Send is supported by SendService that manages DeliveryTasks in a state machine manner and takes care of Message event reporting.

Breaking change:

Relay publish will return error NoPeersToPublish instead of returning OK with 0 peer count!
This derives to REST Api use of relay and lightpush also.

Issue

feat: implement opinionated and simple to use SEND operation #3432

Ivansete-status

Awesome PR! Thanks so much for it! 🙌
Just adding some nitpicks that I hope you find useful.

Ivansete-status · 2026-01-15T09:19:52Z

waku/api/api.nim

+  let healthStatus = RequestNodeHealth.request(w.brokerCtx)
+
+  if healthStatus.isErr():
+    warn "Failed to get Waku node health status: ", error = healthStatus.error
+    # Let's suppose the node is hesalthy enough, go ahead
+  else:
+    if healthStatus.get().healthStatus != NodeHealth.Unhealthy:
+      return err("Waku node is not healthy, has got no connections.")


I think is better to make sure the health API is working properly. If not, we are blind.

Suggested change

let healthStatus = RequestNodeHealth.request(w.brokerCtx)

if healthStatus.isErr():

warn "Failed to get Waku node health status: ", error = healthStatus.error

# Let's suppose the node is hesalthy enough, go ahead

else:

if healthStatus.get().healthStatus != NodeHealth.Unhealthy:

return err("Waku node is not healthy, has got no connections.")

let healthStatus = RequestNodeHealth.request(w.brokerCtx).valueOr:

return err("could not retrieve node's health: " & $error)

if healthStatus.healthStatus != NodeHealth.Unhealthy:

return err("Waku node is not healthy, has got no connections.")

btw, this healthStatus.healthStatus seems not super correct :)

I'll address the issue here in #3689

waku/api/request_id.nim

waku/api/types.nim

waku/waku_core/event/event_emitter.nim

waku/waku_core/message/digest.nim

waku/waku_lightpush/callbacks.nim

waku/waku_lightpush/client.nim

waku/waku_rln_relay/rln_relay.nim

Ivansete-status

Awesome PR! Thanks so much for it! 🙌
Just adding some nitpicks that I hope you find useful.

NagyZoltanPeter · 2026-01-23T16:02:39Z

Basic tests are now working, I consider feature ready as an initial state (more PRs to follow).
Subscribe API was added as it is inherently connected with send API due to node auto subscribe needs.
Currently relay subscribe is supported.
Broker context is set and test concept proved to work in test_send_api.nim
cc: @Ivansete-status @fcecin

waku/node/delivery_service/send_service/send_service.nim

fcecin

LGTM!

Added events and requests for support. Reworked delivery_monitor into a featured devlivery_service, that - supports relay publish and lightpush depending on configuration but with fallback options - if available and configured it utilizes store api to confirm message delivery - emits message delivery events accordingly Notice: There are parts still in WIP and needs review and follow ups. prepare for use in api_example

… but return with result properly

… where appropriate, removed leftover

…auto-subscribe for send api

github-actions · 2026-01-25T23:36:49Z

You can find the image built from this PR at

quay.io/wakuorg/nwaku-pr:3669

Built from e258e11

Copilot

Pull request overview

This PR implements a comprehensive Waku Send API that provides an opinionated, high-level interface for reliably sending messages over the Waku network. The implementation introduces a delivery service architecture with event-driven feedback and multi-protocol fallback mechanisms.

Changes:

Introduces a new Send API with MessageEnvelope abstraction and RequestId tracking for non-blocking message delivery
Implements DeliveryService with SendService, RecvService, and SubscriptionService for managing message lifecycle
Replaces observer pattern with EventBroker and RequestBroker systems for decoupled, context-aware event handling
Adds delivery tracking with three event types: MessagePropagatedEvent, MessageSentEvent, and MessageErrorEvent
Refactors protocol signatures to remove unused peer parameters from PushMessageHandler

Reviewed changes

Copilot reviewed 58 out of 58 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
waku/api/api.nim	New high-level Send API implementation with health checks and delivery task creation
waku/api/types.nim	Core types including MessageEnvelope, RequestId, and NodeHealth enumerations
waku/api/api_conf.nim	Configuration support for Edge mode and p2pReliability settings
waku/events/message_events.nim	Event definitions for message delivery lifecycle tracking
waku/events/delivery_events.nim	Filter subscription and delivery feedback event definitions
waku/node/delivery_service/send_service/send_service.nim	Main delivery orchestration with retry logic, store validation, and event emission
waku/node/delivery_service/send_service/delivery_task.nim	State machine for tracking individual message delivery attempts
waku/node/delivery_service/send_service/relay_processor.nim	Relay protocol delivery processor with fallback logic
waku/node/delivery_service/send_service/lightpush_processor.nim	Lightpush protocol delivery processor implementation
waku/node/delivery_service/recv_service/recv_service.nim	Refactored receive service with event-based subscription handling
waku/node/delivery_service/subscription_service.nim	Manages relay/filter subscriptions for content topics
waku/node/delivery_service/delivery_service.nim	Top-level delivery service coordinating send/receive operations
waku/node/waku_node.nim	Integration of broker context and request providers for shard deduction
waku/node/kernel_api/relay.nim	Updated relay API to return peer count and support isSubscribed query
waku/factory/waku.nim	Replaced DeliveryMonitor with DeliveryService, added health provider setup
waku/common/broker/broker_context.nim	Thread-safe broker context implementation for multi-instance support
waku/common/broker/event_broker.nim	Generic event broker macro for type-safe, decoupled event handling
waku/common/broker/request_broker.nim	Request/response broker for synchronous cross-module communication
waku/requests/rln_requests.nim	RLN proof generation request abstraction
waku/requests/health_request.nim	Health status request definitions for node and relay topics
waku/requests/node_requests.nim	Node-level requests for relay shard deduction
waku/waku_rln_relay/rln_relay.nim	RLN proof generation exposed via request broker
waku/waku_relay/protocol.nim	Removed PublishObserver pattern, added health provider, subscribe triggers health update
waku/waku_lightpush/client.nim	Refactored sendPushRequest with unified connection handling
waku/waku_lightpush/common.nim	Updated PushMessageHandler signature (removed peer parameter)
waku/waku_lightpush/protocol.nim	Updated to use new PushMessageHandler signature
waku/waku_lightpush/callbacks.nim	Updated handler implementations for signature change
waku/waku_lightpush_legacy/*	Legacy lightpush updated for signature compatibility
waku/waku_filter_v2/client.nim	Replaced subscription observers with event broker emissions
waku/waku_core/message/digest.nim	Added to0xHex helper for message hash logging
waku/node/health_monitor/topic_health.nim	Added NOT_SUBSCRIBED state for topic health
waku/node/delivery_monitor/*	Removed old delivery monitor implementation
examples/api_example/api_example.nim	New example demonstrating send API usage with event listeners
tests/api/test_api_send.nim	Comprehensive test suite for send API with multiple scenarios
tests/wakunode2/test_app.nim	Updated for new stop() signature returning Result
apps/wakunode2/wakunode2.nim	Updated shutdown handlers for Result-based stop

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

waku/api/api.nim

waku/node/delivery_service/send_service/send_service.nim

waku/waku_lightpush/client.nim

waku/api/send_api.md

waku/node/delivery_service/send_service/relay_processor.nim

waku/waku_filter_v2/client.nim

waku/node/waku_node.nim

waku/api/send_api.md

Ivansete-status

It is looking really great! 🙌
Adding some more nitpick comments.

waku/api/api.nim

waku/factory/waku.nim

waku/node/delivery_service/send_service/send_service.nim

…ggings and typos

Ivansete-status · 2026-01-29T00:06:09Z

@NagyZoltanPeter - something I forgot to mention is that we need to expose the Send API in libwaku.nim ( maybe other functions too .)
Also, CI should be green but the js jobs ;P

NagyZoltanPeter · 2026-01-29T06:21:30Z

@NagyZoltanPeter - something I forgot to mention is that we need to expose the Send API in libwaku.nim ( maybe other functions too .) Also, CI should be green but the js jobs ;P

@Ivansete-status
I have doubt about adding expose Waku/LMN Api in libwaku!
I thought LMN-Api will have it's own liblmnapi that only expose the high level API while we may deprecate libwaku as KernelApi shall be hidden from public use. WDYT?

CI: I fixed some more as I found rln and rest relay tests was failing due to my changes.

Ivansete-status · 2026-01-29T09:20:42Z

@Ivansete-status I have doubt about adding expose Waku/LMN Api in libwaku! I thought LMN-Api will have it's own liblmnapi that only expose the high level API while we may deprecate libwaku as KernelApi shall be hidden from public use. WDYT?

That's a great idea indeed! Let's have a new liblmapi, liblm or liblemon. (I wouldn't mention the Nim part.)

Re libwaku I think for now, we just need to rename it to liblmkernel and document that we discourage its usage. And little by little deprecate it as liblmapi gains relevance in Status.

CI: I fixed some more as I found rln and rest relay tests was failing due to my changes.

Thanks! 🙌 Ping m if there's anything I can check.

fcecin · 2026-01-29T09:58:40Z

@Ivansete-status I have doubt about adding expose Waku/LMN Api in libwaku! I thought LMN-Api will have it's own liblmnapi that only expose the high level API while we may deprecate libwaku as KernelApi shall be hidden from public use. WDYT?

That's a great idea indeed! Let's have a new liblmapi, liblm or liblemon. (I wouldn't mention the Nim part.)

What about "waku" being retconned as the name of the internals of "logos-messaging" / "lm"? So the current "libwaku" in an internal library by definition. Everything "lm" or "logos-messaging" is the product interface, and everything "waku" is internals (all previous product interfaces named waku are either de-productized or renamed to "lm").

NagyZoltanPeter · 2026-01-29T11:37:36Z

@Ivansete-status I have doubt about adding expose Waku/LMN Api in libwaku! I thought LMN-Api will have it's own liblmnapi that only expose the high level API while we may deprecate libwaku as KernelApi shall be hidden from public use. WDYT?

That's a great idea indeed! Let's have a new liblmapi, liblm or liblemon. (I wouldn't mention the Nim part.)

Re libwaku I think for now, we just need to rename it to liblmkernel and document that we discourage its usage. And little by little deprecate it as liblmapi gains relevance in Status.

CI: I fixed some more as I found rln and rest relay tests was failing due to my changes.

Thanks! 🙌 Ping m if there's anything I can check.

Yes, agreed, that's the way. As remember of a discussion with Franck before, keep lmapi simple as is for the first time and if any verifiable demand arise we can add it instead of exposing kernel-api. So that can be good guideline for lmapi future.

NagyZoltanPeter · 2026-01-29T20:11:46Z

nwaku-nwaku-interop-tests. fails due to the Relay publish breaking change as returning error in case no peers found for relaying.

logos-messaging/logos-messaging-interop-tests#157

NagyZoltanPeter self-assigned this Dec 15, 2025

NagyZoltanPeter requested review from Ivansete-status and weboko December 16, 2025 09:44

NagyZoltanPeter mentioned this pull request Dec 17, 2025

chore: context aware brokers #3674

Merged

Ivansete-status approved these changes Jan 15, 2026

View reviewed changes

NagyZoltanPeter requested review from darshankabariya and fcecin January 23, 2026 16:00

NagyZoltanPeter marked this pull request as ready for review January 23, 2026 16:00

fcecin reviewed Jan 23, 2026

View reviewed changes

waku/node/delivery_service/send_service/send_service.nim Show resolved Hide resolved

fcecin approved these changes Jan 23, 2026

View reviewed changes

NagyZoltanPeter added 12 commits January 25, 2026 23:45

Fix edge mode config and test added

11c2ac3

Fix some import issues, start and stop waku shall not throw exception…

e9df811

… but return with result properly

Utlize sync RequestBroker, adapt to non-async broker usage and gcsafe…

7e68a66

… where appropriate, removed leftover

add api_example app to examples2

e8bbf56

Adapt after merge from master

1f691ae

Adapt code for using broker context

d27ce37

Fix brokerCtx settings for all usedbrokers, cover locked node init

36fdba3

Various fixes upon test failures. Added initial of subscribe API and …

4b163ea

…auto-subscribe for send api

More test added

5af834b

Fix multi propagate event emit, fix fail send test case

fc8e9f6

Fix rebase

3642646

NagyZoltanPeter force-pushed the feat-waku-api-send branch from b98b8dd to 3642646 Compare January 25, 2026 23:28

NagyZoltanPeter requested a review from Copilot January 26, 2026 13:00

Copilot started reviewing on behalf of NagyZoltanPeter January 26, 2026 13:01 View session

Copilot AI reviewed Jan 26, 2026

View reviewed changes

Fix PushMessageHandlers in tests

66ebce6

NagyZoltanPeter added 2 commits January 27, 2026 09:28

adapt libwaku to api changes

a97de82

Fix relay test by adapting publish return error in case NoPeersToPublish

c00ad8d

Ivansete-status reviewed Jan 27, 2026

View reviewed changes

fcecin mentioned this pull request Jan 28, 2026

feat: implement Waku API Health spec (WIP) #3689

Draft

Addressing all remaining review findings. Removed leftovers. Fixed lo…

cc32e91

…ggings and typos

NagyZoltanPeter added 3 commits January 29, 2026 07:06

Fix rln relay broker, missed brokerCtx

98de544

Fix rest relay test failed, due to publish will fail if no peer avail

35c4456

ignore anvil test state file

37d34e0

Make terst_wakunode_rln_relay broker context aware to fix

fbe22a6

NagyZoltanPeter added 2 commits January 29, 2026 14:05

Fix waku rln tests by having them broker context aware

b82c697

fix typo in test_app.nim

a7dd6f2

NagyZoltanPeter mentioned this pull request Jan 29, 2026

Fix test checks where no peers found for relaying messages. logos-messaging/logos-messaging-interop-tests#157

Merged

Merge branch 'master' into feat-waku-api-send

ae4147b

NagyZoltanPeter merged commit 1fd2535 into master Jan 30, 2026
19 of 28 checks passed

NagyZoltanPeter deleted the feat-waku-api-send branch January 30, 2026 00:06

feat: waku api send #3669

feat: waku api send #3669

Uh oh!

Conversation

NagyZoltanPeter commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notice

Description

Breaking change:

Issue

Uh oh!

Ivansete-status left a comment

Choose a reason for hiding this comment

Uh oh!

Ivansete-status Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

fcecin Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Ivansete-status left a comment

Choose a reason for hiding this comment

Uh oh!

NagyZoltanPeter commented Jan 23, 2026

Uh oh!

Uh oh!

fcecin left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Ivansete-status left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Ivansete-status commented Jan 29, 2026

Uh oh!

NagyZoltanPeter commented Jan 29, 2026

Uh oh!

Ivansete-status commented Jan 29, 2026

Uh oh!

fcecin commented Jan 29, 2026

Uh oh!

NagyZoltanPeter commented Jan 29, 2026

Uh oh!

NagyZoltanPeter commented Jan 29, 2026

NagyZoltanPeter commented Dec 15, 2025 •

edited

Loading

github-actions bot commented Jan 25, 2026 •

edited

Loading