feat: implement lp-v3 error codes with backwards compatibility #2501

adklempner · 2025-07-17T16:03:47Z

Problem / Description

js-waku only supported the LightPush v2 protocol.
Clients could not benefit from the new LightPush v3 specification which:

Defines a cleaner request/response structure (requestId, statusCode, statusDesc, …)
Returns machine-readable status codes so that applications can react to failures

Solution

This PR adds full LightPush v3 support while remaining 100 % backward-compatible with v2.

Key changes

Core Protocol
• Added PushRpcV3 handler (packages/core/src/lib/light_push/push_rpc_v3.ts) and new codec /vac/waku/lightpush/3.0.0.
• Generated V3 proto messages (LightPushRequestV3, LightPushResponseV3) with correct field numbers.
• LightPushCore now negotiates the protocol per peer: try v3, fall back to v2 if the peer does not advertise or rejects v3.
Error Handling
• Introduced LightPushStatusCode enum and toLightPushError/getStatusDescription helpers.
• LightPushCore maps status codes ↔ meaningful LightPushError values.
• SDK returns per-peer protocolVersion and full failure details (statusCode + statusDesc).
SDK Enhancements
• packages/sdk/src/light_push/light_push.ts automatically selects v3 when available, else v2 – no API changes for users.
• Added retry/back-off and richer logging including protocol version.
Interfaces / Utils
• Extended @waku/interfaces with new enums and typed results (LightPushSDKResult, LightPushFailure, …).
• Utility funcs for protocol-version inference and RLN-specific checks.
Tests
• Unit: push_rpc_v3.spec.ts covers encode/decode & status helpers.
• Integration: Updated LightPush e2e tests to run against both v2 and v3 peers and ensure correct fallback.
• Updated generated fixtures & mocks.
Protobuf
• Added light_push_v3.proto definitions and regenerated TypeScript (packages/proto/src/generated/light_push.ts).

Notes

• No breaking changes – the public LightPush SDK API is unchanged.
• v3 is preferred but the library gracefully downgrades to v2, enabling mixed-version networks.

Resolves: feat: lightPush v3 #2400 chore: remove ProtocolError, CoreProtocolResult and SDKProtocolResult #2409 lp-v3: determine if light push peer supports v3 #2463 lp-v3: add types for new error codes #2464 lp-v3: handle error codes returned by lp-v3 peers #2465

Checklist

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

packages/interfaces/src/light_push.ts

github-actions · 2025-07-17T16:24:45Z

size-limit report 📦

Path	Size	Loading time (3g)	Running time (snapdragon)	Total time
Waku node	72.26 KB (+1.46% 🔺)	1.5 s (+1.46% 🔺)	442 ms (+39.38% 🔺)	1.9 s
Waku Simple Light Node	123.66 KB (+0.95% 🔺)	2.5 s (+0.95% 🔺)	454 ms (+11.19% 🔺)	3 s
ECIES encryption	22.52 KB (0%)	451 ms (0%)	301 ms (+49.98% 🔺)	751 ms
Symmetric encryption	21.96 KB (0%)	440 ms (0%)	311 ms (+49.14% 🔺)	750 ms
DNS discovery	52.12 KB (+0.94% 🔺)	1.1 s (+0.94% 🔺)	273 ms (-18.94% 🔽)	1.4 s
Peer Exchange discovery	52.82 KB (+0.67% 🔺)	1.1 s (+0.67% 🔺)	317 ms (+22.39% 🔺)	1.4 s
Peer Cache Discovery	46.57 KB (+1.07% 🔺)	932 ms (+1.07% 🔺)	258 ms (-6.66% 🔽)	1.2 s
Privacy preserving protocols	54.18 KB (+1.02% 🔺)	1.1 s (+1.02% 🔺)	447 ms (+49.3% 🔺)	1.6 s
Waku Filter	55.97 KB (+0.83% 🔺)	1.2 s (+0.83% 🔺)	373 ms (-17.99% 🔽)	1.5 s
Waku LightPush	54.16 KB (+2.14% 🔺)	1.1 s (+2.14% 🔺)	348 ms (+10.98% 🔺)	1.5 s
History retrieval protocols	59.86 KB (+0.78% 🔺)	1.2 s (+0.78% 🔺)	449 ms (+28.54% 🔺)	1.7 s
Deterministic Message Hashing	28.87 KB (+1.59% 🔺)	578 ms (+1.59% 🔺)	239 ms (+22.42% 🔺)	816 ms

packages/core/src/index.ts

…pat" This reverts commit 857e12c.

* improve light push core * move back to singualar multicodec property, enable array prop only for light push * implement v2/v3 interop e2e test, re-add useLegacy flag, ensure e2e runs for v2 and v3

weboko

I will address the final changes

weboko · 2025-09-02T21:49:25Z

Problem with E2E tests is due to preparation and stream aquisition taking a lot of time so that push to 2 peers results in two different messages hashes being sent due to difference in timestamp.

Proof:

Solution:
adf8408

Copilot

Pull Request Overview

This PR implements LightPush v3 protocol support with backwards compatibility to v2. The implementation adds machine-readable status codes, cleaner request/response structure, and automatic protocol negotiation while maintaining 100% backward compatibility.

Key changes:

Added LightPush v3 protocol support with new codecs and message structures
Implemented automatic protocol negotiation (v3 preferred, fallback to v2)
Enhanced error handling with specific status codes and improved failure reporting

Reviewed Changes

Copilot reviewed 26 out of 27 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/tests/tests/light-push/v2_interop.spec.ts	New integration test for v2/v3 interoperability
packages/tests/tests/light-push/multiple_pubsub.node.spec.ts	Updated to test both v2 and v3 protocols with parametric tests
packages/tests/tests/light-push/index.node.spec.ts	Enhanced test suite to run against both protocol versions
packages/sdk/src/waku/waku.ts	Updated multicodec handling to support array of codecs
packages/sdk/src/waku/wait_for_remote_peer.ts	Enhanced peer waiting logic for multiple protocol versions
packages/sdk/src/peer_manager/peer_manager.ts	Added support for light-push-v2 protocol distinction
packages/sdk/src/light_push/*.ts	Updated LightPush SDK with v3 support and new error types
packages/relay/src/relay.ts	Updated error types from ProtocolError to LightPushError
packages/interfaces/src/*.ts	Added new error enums, status codes, and result types
packages/core/src/lib/light_push/*.ts	Core v3 implementation with protocol handlers and RPC classes
packages/core/src/lib/filter/filter.ts	Updated to use FilterError instead of ProtocolError

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

packages/tests/tests/light-push/v2_interop.spec.ts

packages/sdk/src/waku/wait_for_remote_peer.ts

packages/sdk/src/light_push/retry_manager.ts

packages/core/src/lib/light_push/protocol_handler.ts

packages/core/src/lib/light_push/light_push.ts

weboko · 2025-09-03T22:35:47Z

dogfooding shows that this branch is stable

https://github.com/waku-org/js-waku/actions/runs/17447341560/job/49544923504

adklempner · 2025-09-04T21:29:52Z

packages/core/src/lib/light_push/light_push.ts

-      }
+    message: IMessage,
+    peerId: PeerId,
+    useLegacy: boolean = false


nit: we should eventually replace this with some kind of generic backwards-compatibility strategy for all (or at least the main) protocols

@adklempner don't understand your comment

packages/core/src/lib/light_push/push_rpc_v3.ts

adklempner · 2025-09-04T21:49:30Z

packages/core/src/lib/light_push/protocol_handler.ts

+      }
+
+      if (decodedRpcV3.relayPeerCount !== undefined) {
+        log.info(`Message relayed to ${decodedRpcV3.relayPeerCount} peers`);


should the relayPeerCount be exposed to the library consumer beyond logging it?

why would they need this?

packages/interfaces/src/sender.ts

adklempner changed the title ~~Feat/lp v3 sdk~~ feat: implement lp-v3 error codes with backwards compatibility Jul 17, 2025

This was referenced Jul 17, 2025

feat: add light push v3 status codes and helpers #2482

Closed

feat: add light push v3 protocol detection and handling #2483

Closed

weboko reviewed Jul 17, 2025

View reviewed changes

packages/interfaces/src/light_push.ts Outdated Show resolved Hide resolved

adklempner force-pushed the feat/lp-v3-sdk branch from 17b0b5b to 43f2b5a Compare July 17, 2025 16:20

adklempner force-pushed the feat/lp-v3-sdk branch 13 times, most recently from e7fe9f4 to ec4c460 Compare July 24, 2025 16:07

adklempner force-pushed the feat/lp-v3-sdk branch 2 times, most recently from 038bb62 to a64cf0a Compare July 25, 2025 05:05

adklempner marked this pull request as ready for review July 25, 2025 05:31

adklempner requested a review from a team as a code owner July 25, 2025 05:31

adklempner force-pushed the feat/lp-v3-sdk branch 6 times, most recently from e7a829e to 0edbf29 Compare July 26, 2025 00:59

weboko reviewed Jul 28, 2025

View reviewed changes

packages/core/src/index.ts Show resolved Hide resolved

adklempner added 9 commits August 21, 2025 22:00

fix: remove unused code

a536f61

feat: use array for multicodec fields

3735ec1

fix: add timestamp if missing in v3 rpc

406563a

fix: resolve on either lp codec when waiting for peer

7896ba4

fix: remove unused util

74682b7

fix: remove unnecessary abstraction

6c58606

feat: accept nwaku docker image as arg, test lp backwards compat

857e12c

fix: revert filter error

3ecaa13

feat: add legacy flag to enable lightpushv2 only

cc7d648

adklempner force-pushed the feat/lp-v3-sdk branch from e2e26fa to cc7d648 Compare August 22, 2025 05:00

adklempner added 2 commits August 22, 2025 11:28

Revert "feat: accept nwaku docker image as arg, test lp backwards com…

c0ee9ec

…pat" This reverts commit 857e12c.

fix: remove unused test

9915ab6

adklempner requested review from fryorcraken and weboko August 23, 2025 03:14

feat: improve lp3 (#2597)

8d536d4

* improve light push core * move back to singualar multicodec property, enable array prop only for light push * implement v2/v3 interop e2e test, re-add useLegacy flag, ensure e2e runs for v2 and v3

weboko requested changes Aug 29, 2025

View reviewed changes

weboko added 3 commits September 1, 2025 23:34

merge with master

90bdf0d

fix v2 v3 condition

24fe74c

generate message package earlier

adf8408

weboko requested a review from Copilot September 3, 2025 22:09

Copilot AI reviewed Sep 3, 2025

View reviewed changes

weboko and others added 2 commits September 4, 2025 00:41

add log, fix condition

5dd9002

Merge branch 'master' into feat/lp-v3-sdk

ca1ff37

weboko approved these changes Sep 3, 2025

View reviewed changes

adklempner commented Sep 4, 2025

View reviewed changes

weboko merged commit 1625302 into master Sep 4, 2025
10 of 11 checks passed

weboko deleted the feat/lp-v3-sdk branch September 4, 2025 22:52

weboko mentioned this pull request Sep 4, 2025

chore: release master #2576

Merged

feat: implement lp-v3 error codes with backwards compatibility #2501

feat: implement lp-v3 error codes with backwards compatibility #2501

Uh oh!

Conversation

adklempner commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem / Description

Solution

Notes

Checklist

Uh oh!

Uh oh!

github-actions bot commented Jul 17, 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 left a comment

Choose a reason for hiding this comment

Uh oh!

weboko commented Sep 2, 2025 • 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!

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

Uh oh!

Uh oh!

adklempner Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

weboko Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adklempner Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

weboko Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

adklempner commented Jul 17, 2025 •

edited

Loading

github-actions bot commented Jul 17, 2025 •

edited

Loading

weboko commented Sep 2, 2025 •

edited

Loading

weboko commented Sep 3, 2025 •

edited

Loading