feat: introduce Send API #2583

weboko · 2025-08-20T20:54:45Z

Problem / Description

Creation of unified Send method is needed.

Solution

Make sending a message over the network completely lean.

This PR adds:

to IWaku - new .send method that accepts lean data structure to route the message
navigating where to send message relies on present networkConfig on IWaku node
implements back-end for Subscribe functionality by creating AckManager facade
when message is sent - subscription automatically gets created

Notes

Resolves feat: implement Send API #2627 and feat: Messaging Storage API and Ack Manager #2381
Spec - Add Send API to Waku API specs#87

Checklist

Code changes are covered by unit tests.
Code changes are covered by e2e tests, if applicable.
Dogfooding has been performed, if feasible.
A test version has been published, if required.
All CI checks pass successfully.

…-api

github-actions · 2025-09-24T22:58:47Z

size-limit report 📦

Path	Size	Loading time (3g)	Running time (snapdragon)	Total time
Waku node	97.36 KB (+1.31% 🔺)	2 s (+1.31% 🔺)	693 ms (-13.4% 🔽)	2.7 s
Waku Simple Light Node	148.63 KB (+0.85% 🔺)	3 s (+0.85% 🔺)	819 ms (+47.15% 🔺)	3.8 s
ECIES encryption	22.56 KB (+0.25% 🔺)	452 ms (+0.25% 🔺)	207 ms (-13.05% 🔽)	658 ms
Symmetric encryption	22 KB (+0.4% 🔺)	440 ms (+0.4% 🔺)	161 ms (-41.72% 🔽)	601 ms
DNS discovery	52.11 KB (-0.08% 🔽)	1.1 s (-0.08% 🔽)	523 ms (-8.7% 🔽)	1.6 s
Peer Exchange discovery	52.83 KB (-0.15% 🔽)	1.1 s (-0.15% 🔽)	659 ms (+3.17% 🔺)	1.8 s
Peer Cache Discovery	46.58 KB (+0.02% 🔺)	932 ms (+0.02% 🔺)	597 ms (+27.23% 🔺)	1.6 s
Privacy preserving protocols	77.14 KB (+0.11% 🔺)	1.6 s (+0.11% 🔺)	713 ms (-30.67% 🔽)	2.3 s
Waku Filter	79.68 KB (-0.02% 🔽)	1.6 s (-0.02% 🔽)	985 ms (+35.4% 🔺)	2.6 s
Waku LightPush	77.79 KB (+0.02% 🔺)	1.6 s (+0.02% 🔺)	720 ms (+24.97% 🔺)	2.3 s
History retrieval protocols	83.56 KB (-0.06% 🔽)	1.7 s (-0.06% 🔽)	720 ms (-12.47% 🔽)	2.4 s
Deterministic Message Hashing	28.89 KB (-0.05% 🔽)	578 ms (-0.05% 🔽)	353 ms (+18.48% 🔺)	931 ms

…ntity

…-api

packages/sdk/src/waku/waku.ts

…-api

weboko · 2025-10-07T22:34:49Z

I still need to add some E2E Tests and better dogfooding example.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting

@codex fix this CI failure
@codex address that feedback

packages/sdk/src/light_push/light_push.ts

packages/sdk/src/waku/waku.ts

packages/sdk/src/messaging/ack_manager.ts

Copilot

Pull Request Overview

This PR introduces a unified Send API for Waku nodes, simplifying message sending by providing a lean interface that handles routing, acknowledgments, and retry logic internally.

Adds send method to IWaku interface that accepts simplified message data structure
Implements messaging backend with automatic acknowledgment tracking via filter and store protocols
Integrates retry logic and subscription management for reliable message delivery

Reviewed Changes

Copilot reviewed 23 out of 24 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/interfaces/src/waku.ts	Adds `send` method to IWaku interface and deprecation warnings
packages/interfaces/src/message.ts	Defines ISendMessage and RequestId types for new API
packages/sdk/src/waku/waku.ts	Integrates Messaging class into WakuNode implementation
packages/sdk/src/messaging/*	Complete messaging system with sender, ack manager, and message store
packages/core/src/lib/light_push/*	Extends light push to return proto messages for acknowledgment tracking
packages/interfaces/src/sender.ts	Adds numPeersToUse option to ISendOptions

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

packages/sdk/src/messaging/sender.ts

packages/sdk/src/messaging/sender.spec.ts

packages/sdk/src/messaging/ack_manager.ts

packages/sdk/src/waku/waku.ts

packages/sdk/src/messaging/ack_manager.ts

adklempner · 2025-10-07T23:12:46Z

packages/sdk/src/messaging/ack_manager.ts

+        this.filterAckManager.subscribe(decoder),
+        this.storeAckManager.subscribe(decoder)
+      ])
+    ).some((success) => success);


why is only one success sufficient?

we rely on background process of Filter to automatically recover subscriptions or Store to continue querying

js-waku/packages/sdk/src/filter/subscription.ts

Line 281 in ad0bed6

if (this.toSubscribeContentTopics.size > 0) {

that's why enough to get confirmation for at least one successful in-place subscription
because later it will recover in async way

adklempner · 2025-10-07T23:34:24Z

packages/sdk/src/messaging/ack_manager.ts

+  }
+}
+
+class StoreAckManager {


nit: splitting StoreAckManager and FilterAckManager into separate classes from AckManager seems overkill, unless there's a good reason for someone to use them outside of AckManager

I disagree, it seems logical to keep them separate and might be useful once we want to provide other ack mechanics such as SDS.

might be useful

I would recommend avoiding introducing complexity for a might and just proceed with a refactoring once this complexity becomes necessary.

once we want to provide other ack mechanics such as SDS.

We already provide those via ReliableChannel and I am not convinced we want to merge routing (Waku API) and application (Reliable Channel) level concepts in the same objects.

…-api

fryorcraken · 2025-10-13T04:20:19Z

Will wait for agreement on the spec before review of this PR.

fryorcraken · 2025-10-17T04:30:20Z

packages/interfaces/src/message.ts

+  contentTopic: string;
+  payload: Uint8Array;
+  ephemeral?: boolean;
+  rateLimitProof?: boolean;


I don't think the API consumer should be exposed to the rate limit proof, this sit behind the Waku API. see createNode spec for details.

fryorcraken · 2025-10-17T04:34:19Z

packages/interfaces/src/waku.ts

+   * @param {ISendMessage} message - The message to send.
+   * @returns {Promise<RequestId>} A promise that resolves to the request ID
+   */
+  send(message: ISendMessage): Promise<RequestId>;


the Waku message Id must be exposed in the API to enable SDS's retrieval hints.

I strongly recommend for it to be returned by send to avoid issues with timestamp and pubsubtopic (both being used to calculate message id)

fryorcraken · 2025-10-17T04:38:35Z

packages/interfaces/src/message.ts

+/**
+ * Send message data structure used in {@link IWaku.send}.
+ */
+export interface ISendMessage {


I am not convinced we need a type here, it just makes it harder to understand the API.

Just do

send: ( contentTopic: string; payload: Uint8Array; ephemeral?: boolean; ) => Promise<Uint8Array | undefined>;

weboko added 5 commits August 20, 2025 22:54

add draft

d29994d

Merge branch 'master' of github.com:waku-org/js-waku into weboko/send…

97f0fb2

…-api

add draft api

01288ff

Merge branch 'master' of github.com:waku-org/js-waku into weboko/send…

e54645a

…-api

implement basic entites and structure, decouple into separate files

3de906a

weboko added 3 commits September 25, 2025 01:32

implement main ack manager, improve message store, implement Sender e…

4fe8bfd

…ntity

implement background send, requestID

37ee490

Merge branch 'master' of github.com:waku-org/js-waku into weboko/send…

998c2a1

…-api

weboko force-pushed the weboko/send-api branch from 69052e1 to 998c2a1 Compare September 29, 2025 20:36

weboko added 2 commits September 29, 2025 22:40

add utils, fix typings

0c852e4

add ICodec

9e7719e

weboko mentioned this pull request Sep 29, 2025

feat: introduce Codec entity #2577

Closed

1 task

weboko added 2 commits September 30, 2025 00:12

implement send on waku

ad675d8

implement and fix queuing mechanics of message store

7c67abe

fryorcraken reviewed Oct 1, 2025

View reviewed changes

packages/sdk/src/waku/waku.ts Outdated Show resolved Hide resolved

weboko added 2 commits October 2, 2025 18:53

implement acks and message hash saving for sent messages

4385104

move from encoder/decoder/codec to simple message parameter

7f98bb1

weboko mentioned this pull request Oct 6, 2025

feat: Waku API's subscribe #2667

Closed

8 tasks

weboko added 3 commits October 7, 2025 00:00

implement working version of sendind

da11478

merge with master

62b43f0

remove Codec, update types

80cef4b

This was referenced Oct 6, 2025

Add Send API to Waku API waku-org/specs#87

Open

feat: Messaging Storage API and Ack Manager #2381

Open

weboko changed the title ~~feat: send api~~ feat: introduce Send API Oct 6, 2025

weboko added 2 commits October 7, 2025 22:08

Merge branch 'master' of github.com:waku-org/js-waku into weboko/send…

82be279

…-api

add unit tests

969330d

weboko marked this pull request as ready for review October 7, 2025 22:34

weboko requested a review from a team as a code owner October 7, 2025 22:34

chatgpt-codex-connector bot reviewed Oct 7, 2025

View reviewed changes

packages/sdk/src/light_push/light_push.ts Show resolved Hide resolved

packages/sdk/src/waku/waku.ts Show resolved Hide resolved

packages/sdk/src/messaging/ack_manager.ts Outdated Show resolved Hide resolved

weboko requested a review from Copilot October 7, 2025 23:00

Copilot AI reviewed Oct 7, 2025

View reviewed changes

adklempner approved these changes Oct 8, 2025

View reviewed changes

weboko added 3 commits October 8, 2025 23:20

Merge branch 'master' of github.com:waku-org/js-waku into weboko/send…

de70791

…-api

address review

e39c6c9

fix start

974fb21

fryorcraken requested changes Oct 17, 2025

View reviewed changes

fryorcraken reviewed Oct 17, 2025

View reviewed changes

feat: introduce Send API #2583

Are you sure you want to change the base?

feat: introduce Send API #2583

Uh oh!

Conversation

weboko commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem / Description

Solution

Notes

Checklist

Uh oh!

github-actions bot commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

Uh oh!

weboko commented Oct 7, 2025

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fryorcraken commented Oct 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

weboko commented Aug 20, 2025 •

edited

Loading

github-actions bot commented Sep 24, 2025 •

edited

Loading