3.6 KiB
| title | name | editor | contributors | |||
|---|---|---|---|---|---|---|
| WAKU2-LIGHTPUSH | Waku Light Push | Zoltan Nagy <zoltan@status.im> |
|
previous version: /vac/waku/lightpush/2.0.0-beta1 19/WAKU2-LIGHTPUSH
Protocol identifier: /vac/waku/lightpush/3.0.0
Motivation and Goals
Light nodes with short connection windows and limited bandwidth wish to push messages to other nodes in the Waku network to request message services.
A common use case is to request that service node to publish the message to a 11/WAKU2-RELAY pubsub topic.
Additionally, there is sometimes a need for confirmation that a message has been received "by the network"
(here, at least one node).
WAKU-LIGHTPUSH is a request/response protocol for this.
Payloads
syntax = "proto3";
message LightPushRequest {
string request_id = 1;
uin32 request_type = 10; // 10 Reserved for future `request_type`. Currently RELAY is only available service.
optional string pubsub_topic = 20;
WakuMessage message = 21;
}
message LightPushResponse {
string request_id = 1;
uint32 status_code = 10; // non zero in case of failure, see appendix
optional string status_desc = 11;
uint32 relay_peer_count = 12;
}
Message Relaying
Nodes that respond to LightPushRequest MUST either relay the encapsulated message via 11/WAKU2-RELAY protocol on the specified pubsub_topic. Depending on the network configuration, user may not need to provide pubsub_topic (WAKU2-RELAY-SHARDING).
If they are unable to do so for some reason, they SHOULD return an error code in LightPushResponse.
Examples of possible error codes
| Result | Code | Note |
|---|---|---|
| SUCCESS | 200 | Successfull push, response's relay_peer_count holds the number of peers the message is pushed. |
| BAD_REQUEST | 400 | Wrong request payload. |
| PAYLOAD_TOO_LARGE | 413 | Message exceeds certain size limit, it can depend on network configuration, see status_desc for details. |
| UNSUPPORTED_TOPIC | 421 | Requested push on pubsub_topic is not possible as the service node does not support it. |
| TOO_MANY_REQUESTS | 429 | DOS protection prevented this request as the current request exceeds the configured request rate. |
| INTERNAL_SERVER_ERROR | 500 | status_desc holds explanation of the error. |
| NO_PEERS_TO_RELAY | 503 | Lightpush service not available as node has no relay peers. |
The list of error codes are not complete and can be extended in the future.
Security Considerations
Since this can introduce an amplification factor, it is RECOMMENDED for the node relaying to the rest of the network to take extra precautions. Therefore Waku applies or will apply:
- DOS protection through request rate limitation on the service itself.
- message rate limiting via 17/WAKU2-RLN-RELAY, applied via network membership subscription.
These features are under development.
Future work
- Add support attaching RLN proof for the message requested to be relayed.
- Add support for other request types.
- Incentivization of the service
Copyright
Copyright and related rights waived via CC0.