diff --git a/standards/core/lightpush.md b/standards/core/lightpush.md index 081c0ca..3a45ccd 100644 --- a/standards/core/lightpush.md +++ b/standards/core/lightpush.md @@ -1,6 +1,5 @@ --- -slug: 19 -title: 19/WAKU2-LIGHTPUSH +title: WAKU2-LIGHTPUSH name: Waku v2 Light Push status: draft editor: Zoltan Nagy @@ -13,15 +12,16 @@ contributors: 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/2.0.0-beta2` +**Protocol identifier**: `/vac/waku/lightpush/3.0.0` ## Motivation and Goals -Light nodes with short connection windows and limited bandwidth wish to publish messages into the Waku network. +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). -`19/WAKU2-LIGHTPUSH` is a request/response protocol for this. +`WAKU2-LIGHTPUSH` is a request/response protocol for this. ## Payloads @@ -29,30 +29,15 @@ Additionally, there is sometimes a need for confirmation that a message has been syntax = "proto3"; message LightPushRequest { - enum RequestType { // Future extension point - RELAY = 0; - } - - string request_id = 1; - RequestType kind = 10; // default is RELAY, placeholder for future extensions - string pubsub_topic = 20; + string request_id = 1; + uin32 request_type = 10; // reserved for future request type selection, currently it is always RELAY (0) + string topic = 20; WakuMessage message = 21; } message LightPushResponse { - enum Status { - SUCCESS = 0; - BAD_REQUEST = 400; - NO_PEERS_TO_RELAY = 404; - PAYLOAD_TOO_LARGE = 413; - UNSUPPORTED_TOPIC = 415; - TOO_MANY_REQUESTS = 429; - INTERNAL_SERVER_ERROR = 500; - SERVICE_UNAVAILABLE = 503; - } - string request_id = 1; - Status status_code = 10; + uint32 status_code = 10; // non zero in case of failure, see appendix optional string status_desc = 11; uint32 relay_peer_count = 12; } @@ -60,22 +45,38 @@ message LightPushResponse { ### 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`, -or forward the `LightPushRequest` via 19/LIGHTPUSH on a [WAKU2-DANDELION](https://github.com/waku-org/specs/blob/waku-RFC/standards/application/dandelion.md) stem. +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` or `shard` ([WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md)) depending on the network configuration. 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 | 0 | Successfull push, response's relay_peer_count holds the number of peers the message is pushed. | +| BAD_REQUEST | 400 | | +| NO_PEERS_TO_RELAY | 404 | Service node has no relay peers | +| PAYLOAD_TOO_LARGE | 413 | Message exceeds certain size limit, it can depend on network configuration, see status_desc for details. | +| UNSUPPORTED_TOPIC | 415 | Requested push on pubsub_topic or shard is not possible as the service node is not subscibed to. | +| 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. | +| SERVICE_UNAVAILABLE | 503 | Lightpush service not available | + +> 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. -This can be done by rate limiting via [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/waku/standards/core/17/rln-relay). +Therefore Waku2 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. -Note that the above is currently not fully implemented. +> 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 @@ -84,5 +85,4 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public ## References * [11/WAKU2-RELAY](https://rfc.vac.dev/waku/standards/core/11/relay) -* [WAKU2-DANDELION](https://github.com/waku-org/specs/blob/waku-RFC/standards/application/dandelion.md) * [17/WAKU2-RLN-RELAY](https://rfc.vac.dev/waku/standards/core/17/rln-relay)