4.5 KiB
| title | name | editor | contributors | |||
|---|---|---|---|---|---|---|
| WAKU-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 the service node publish the message to an 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;
// 10 Reserved for future `request_type`. Currently, RELAY is the only available service.
optional string pubsub_topic = 20;
WakuMessage message = 21;
}
message LightPushResponse {
string request_id = 1;
uint32 status_code = 10; // has value 200 in case of success, see appendix
optional string status_desc = 11;
optional uint32 relay_peer_count = 12; // number of peers, the message is successfully relayed to
}
Message Relaying
Nodes that respond to LightPushRequest SHOULD
- either relay the encapsulated message via 11/WAKU2-RELAY protocol on the specified
pubsub_topic - or perform another requested service.
Services beyond [11/WAKU2-RELAY](https://rfc.vac.dev/waku/standards/core/11/relay) are yet to be defined.
Depending on the network configuration, the lightpush client may not need to provide pubsub_topic (WAKU2-RELAY-SHARDING).
If the node is unable to perform the request for some reason, it SHOULD return an error code in LightPushResponse.
Once the relay is successful, the relay_peer_count will indicate the number of peers that the node has managed to relay the message to. It's important to note that this number may vary depending on the node subscriptions and support for the requested pubsub_topic. The client can use this information to either consider the relay as successful or take further action, such as switching to a lightpush service peer with better connectivity.
The field
relay_peer_countmay not be present or has the value zero in case of error or in other future use cases, where no relay is involved.
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_PUBSUB_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 is not available as the node has no relay peers. |
The list of error codes is 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.