mirror of https://github.com/waku-org/specs.git
87 lines
3.6 KiB
Markdown
87 lines
3.6 KiB
Markdown
---
|
|
title: WAKU2-LIGHTPUSH
|
|
name: Waku Light Push
|
|
editor: Zoltan Nagy <zoltan@status.im>
|
|
contributors:
|
|
- Hanno Cornelius <hanno@status.im>
|
|
- Daniel Kaiser <danielkaiser@status.im>
|
|
- Oskar Thorén <oskarth@titanproxy.com>
|
|
---
|
|
|
|
previous version: `/vac/waku/lightpush/2.0.0-beta1` [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/waku/standards/core/19/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
|
|
|
|
```protobuf
|
|
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](https://rfc.vac.dev/waku/standards/core/11/relay) protocol on the specified `pubsub_topic`. Depending on the network configuration, user may not need to provide `pubsub_topic` ([WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md)).
|
|
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](https://rfc.vac.dev/waku/standards/core/17/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](https://creativecommons.org/publicdomain/zero/1.0/).
|
|
|
|
## References
|
|
|
|
* [11/WAKU2-RELAY](https://rfc.vac.dev/waku/standards/core/11/relay)
|
|
* [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/waku/standards/core/17/rln-relay)
|