feat: implement lp-v3 error codes with backwards compatibility#2501
Merged
Conversation
adklempner
changed the title
This was referenced Jul 17, 2025
weboko
reviewed
Jul 17, 2025
adklempner
force-pushed
the
feat/lp-v3-sdk
branch
from
July 17, 2025 16:20
17b0b5b to
43f2b5a
Compare
size-limit report 📦
|
adklempner
force-pushed
the
feat/lp-v3-sdk
branch
13 times, most recently
from
July 24, 2025 16:07
e7fe9f4 to
ec4c460
Compare
adklempner
force-pushed
the
feat/lp-v3-sdk
branch
2 times, most recently
from
July 25, 2025 05:05
038bb62 to
a64cf0a
Compare
adklempner
marked this pull request as ready for review
July 25, 2025 05:31
adklempner
force-pushed
the
feat/lp-v3-sdk
branch
6 times, most recently
from
July 26, 2025 00:59
e7a829e to
0edbf29
Compare
weboko
reviewed
Jul 28, 2025
adklempner
force-pushed
the
feat/lp-v3-sdk
branch
from
August 22, 2025 05:00
e2e26fa to
cc7d648
Compare
…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
requested changes
Aug 29, 2025
weboko
left a comment
weboko
left a comment
Collaborator
There was a problem hiding this comment.
I will address the final changes
Collaborator
|
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: |
There was a problem hiding this comment.
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.
Collaborator
|
dogfooding shows that this branch is stable https://github.com/waku-org/js-waku/actions/runs/17447341560/job/49544923504 |
weboko
approved these changes
Sep 3, 2025
adklempner
commented
Sep 4, 2025
| } | ||
| message: IMessage, | ||
| peerId: PeerId, | ||
| useLegacy: boolean = false |
Member
Author
There was a problem hiding this comment.
nit: we should eventually replace this with some kind of generic backwards-compatibility strategy for all (or at least the main) protocols
| } | ||
|
|
||
| if (decodedRpcV3.relayPeerCount !== undefined) { | ||
| log.info(`Message relayed to ${decodedRpcV3.relayPeerCount} peers`); |
Member
Author
There was a problem hiding this comment.
should the relayPeerCount be exposed to the library consumer beyond logging it?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem / Description
js-wakuonly supported the LightPush v2 protocol.Clients could not benefit from the new LightPush v3 specification which:
requestId,statusCode,statusDesc, …)Solution
This PR adds full LightPush v3 support while remaining 100 % backward-compatible with v2.
Key changes
Core Protocol
• Added
PushRpcV3handler (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.•
LightPushCorenow negotiates the protocol per peer: try v3, fall back to v2 if the peer does not advertise or rejects v3.Error Handling
• Introduced
LightPushStatusCodeenum andtoLightPushError/getStatusDescriptionhelpers.•
LightPushCoremaps status codes ↔ meaningfulLightPushErrorvalues.• SDK returns per-peer
protocolVersionand full failure details (statusCode + statusDesc).SDK Enhancements
•
packages/sdk/src/light_push/light_push.tsautomatically 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/interfaceswith new enums and typed results (LightPushSDKResult,LightPushFailure, …).• Utility funcs for protocol-version inference and RLN-specific checks.
Tests
• Unit:
push_rpc_v3.spec.tscovers 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.protodefinitions 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.
Checklist