From f80e9f76bb160369053f20d2b63ddcd37b2b7558 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Tue, 3 Dec 2024 08:55:23 -0500 Subject: [PATCH 1/3] Update bridge.md --- waku/standards/core/15/bridge.md | 36 ++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/waku/standards/core/15/bridge.md b/waku/standards/core/15/bridge.md index 60f4bb42..4767b4a1 100644 --- a/waku/standards/core/15/bridge.md +++ b/waku/standards/core/15/bridge.md @@ -7,24 +7,33 @@ tags: waku-core editor: Hanno Cornelius --- -A bridge between Waku v1 and Waku v2. +## Abstract + +This specification describes how [6/WAKU1](/waku/standards/legacy/6/waku1.md) can be used with [10/WAKU2](/waku/standards/core/10/waku2.md). ## Bridge +The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, +“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and +“OPTIONAL” in this document are to be interpreted as described in [2119](https://www.ietf.org/rfc/rfc2119.txt). + A bridge requires supporting both Waku versions: -* Waku v1 - using devp2p RLPx protocol -* Waku v2 - using libp2p protocols +* [6/WAKU1](/waku/standards/legacy/6/waku1.md) - using devp2p RLPx protocol +* [10/WAKU2](/waku/standards/core/10/waku2.md) - using libp2p protocols -Packets received on the Waku v1 network SHOULD be published just once on the -Waku v2 network. More specifically, the bridge SHOULD publish -this through the Waku Relay (PubSub domain). +Packets received on the [6/WAKU1](/waku/standards/legacy/6/waku1.md) network +SHOULD be published just once on the [10/WAKU2](/waku/standards/core/10/waku2.md). +More specifically, the bridge SHOULD publish +this through the [11/WAKU2-RELAY](/waku/standards/core/11/relay.md) (PubSub domain). -Publishing such packet will require the creation of a new `Message` with a -new `WakuMessage` as data field. The `data` and `topic` field from the Waku v1 -`Envelope` MUST be copied to the `payload` and `contentTopic` fields of the -`WakuMessage`. Other fields such as nonce, expiry and ttl will be dropped as -they become obsolete in Waku v2. +Publishing such packet REQUIRES the creation of a new `Message` with a +new `WakuMessage` as data field. +The `data` and +`topic` field from the Waku v1 `Envelope` MUST be copied to the `payload` and +`contentTopic` fields of the `WakuMessage`. +Other fields such as nonce, expiry and +ttl will be dropped as they become obsolete in Waku v2. Before this is done, the usual envelope verification still applies: @@ -32,8 +41,9 @@ Before this is done, the usual envelope verification still applies: * PoW verification * Size verification -Bridging SHOULD occur through the `WakuRelay`, but it MAY also be done on other Waku -v2 protocols (e.g. `WakuFilter`). The latter is however not advised as it will +Bridging SHOULD occur through the `WakuRelay`, +but it MAY also be done on other Wakuv2 protocols (e.g. `WakuFilter`). +The latter is however not advised as it will increase the complexity of the bridge and because of the [Security Considerations](#security-considerations) explained further below. From e31787ec7ff259d0c867b22c49a3b81e8c5b3345 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Wed, 4 Dec 2024 07:50:45 -0500 Subject: [PATCH 2/3] Update bridge.md --- waku/standards/core/15/bridge.md | 75 ++++++++++++++++++++------------ 1 file changed, 47 insertions(+), 28 deletions(-) diff --git a/waku/standards/core/15/bridge.md b/waku/standards/core/15/bridge.md index 4767b4a1..7d2f68e8 100644 --- a/waku/standards/core/15/bridge.md +++ b/waku/standards/core/15/bridge.md @@ -11,7 +11,7 @@ editor: Hanno Cornelius This specification describes how [6/WAKU1](/waku/standards/legacy/6/waku1.md) can be used with [10/WAKU2](/waku/standards/core/10/waku2.md). -## Bridge +## Wire Format The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and @@ -22,18 +22,21 @@ A bridge requires supporting both Waku versions: * [6/WAKU1](/waku/standards/legacy/6/waku1.md) - using devp2p RLPx protocol * [10/WAKU2](/waku/standards/core/10/waku2.md) - using libp2p protocols +## Publishing Packets + Packets received on the [6/WAKU1](/waku/standards/legacy/6/waku1.md) network SHOULD be published just once on the [10/WAKU2](/waku/standards/core/10/waku2.md). More specifically, the bridge SHOULD publish this through the [11/WAKU2-RELAY](/waku/standards/core/11/relay.md) (PubSub domain). -Publishing such packet REQUIRES the creation of a new `Message` with a -new `WakuMessage` as data field. +When publishing such packet, +the creation of a new `Message` with a new `WakuMessage` as data field is REQUIRED. The `data` and -`topic` field from the Waku v1 `Envelope` MUST be copied to the `payload` and -`contentTopic` fields of the `WakuMessage`. -Other fields such as nonce, expiry and -ttl will be dropped as they become obsolete in Waku v2. +`topic` field, from the [6/WAKU1](/waku/standards/legacy/6/waku1.md) `Envelope`, +MUST be copied to the `payload` and `content_topic` fields of the `WakuMessage`. +See [14/WAKU2-MESSAGE](/waku/standards/core/14/message.md#wire-format) for message format details. +Other fields such as `nonce`, `expiry` and +`ttl` will be dropped as they become obsolete in [10/WAKU2](/waku/standards/core/10/waku2.md). Before this is done, the usual envelope verification still applies: @@ -41,38 +44,54 @@ Before this is done, the usual envelope verification still applies: * PoW verification * Size verification -Bridging SHOULD occur through the `WakuRelay`, -but it MAY also be done on other Wakuv2 protocols (e.g. `WakuFilter`). +Bridging SHOULD occur through the [11/WAKU2-RELAY](/waku/standards/core/11/relay.md), +but it MAY also be done on other [10/WAKU2](/waku/standards/core/10/waku2.md) protocols +(e.g. [12/WAKU2-FILTER](/waku/standards/core/12/filter.md)). The latter is however not advised as it will -increase the complexity of the bridge and because of the -[Security Considerations](#security-considerations) explained further below. - -Packets received on the Waku v2 network SHOULD be posted just once on the Waku -v1 network. The Waku v2 `WakuMessage` contains only the `payload` and -`contentTopic` fields. The bridge MUST create a new Waku v1 `Envelope` and -copy over the `payload` and `contentFilter` fields to the `data` and `topic` -fields. Next, before posting on the network, the bridge MUST set a new expiry -and ttl and do the PoW nonce calculation. +increase the complexity of the bridge and +because of the [Security Considerations](#security-considerations) explained further below. + +Packets received on the [64/WAKU2-NETWORK](/waku/standards/core/64/network.md), +SHOULD be posted just once on the [6/WAKU1](/waku/standards/legacy/6/waku1.md) network. +The [14/WAKU2-MESSAGE](/waku/standards/core/14/message.md) contains only the `payload` and +`contentTopic` fields. +The bridge MUST create a new [6/WAKU1](/waku/standards/legacy/6/waku1.md) `Envelope` and +copy over the `payload` and `contentFilter` +fields to the `data` and `topic` fields. +Next, before posting on the network, +the bridge MUST set a new `expiry`, `ttl` and do the PoW `nonce` calculation. ### Security Considerations -As mentioned above, a bridge will be posting new Waku v1 envelopes, which -requires doing the PoW nonce calculation. +As mentioned above, +a bridge will be posting new [6/WAKU1](/waku/standards/legacy/6/waku1.md) envelopes, +which requires doing the PoW `nonce` calculation. -This could be a DoS attack vector, as the PoW calculation will make it more -expensive to post the message compared to the original publishing on the Waku v2 -network. Low PoW setting will lower this problem, but it is likely that it is -still more expensive. +This could be a DoS attack vector, +as the PoW calculation will make it more expensive to post the message +compared to the original publishing on the [64/WAKU2-NETWORK](/waku/standards/core/64/network.md). +Low PoW setting will lower this problem, +but it is likely that it is still more expensive. -For this reason, bridges SHOULD probably be run independently of other nodes, so -that a bridge that gets overwhelmed does not disrupt regular Waku v2 to v2 +For this reason, it is RECOOMENDED to run bridges independently of other nodes, +so that a bridge that gets overwhelmed does not disrupt regular Waku v2 to v2 traffic. Bridging functionality SHOULD also be carefully implemented so that messages do -not bounce back and forth between the two networks. The bridge SHOULD properly -track messages with a seen filter so that no amplification can be achieved here. +not bounce back and forth between the two networks. +The bridge SHOULD properly track messages with a seen filter, +so that no amplification can be achieved here. ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References + +- [6/WAKU1](/waku/standards/legacy/6/waku1.md) +- [10/WAKU2](/waku/standards/core/10/waku2.md) +- [11/WAKU2-RELAY](/waku/standards/core/11/relay.md) +- [14/WAKU2-MESSAGE](/waku/standards/core/14/message.md) +- [12/WAKU2-FILTER](/waku/standards/core/12/filter.md) +- [64/WAKU2-NETWORK](/waku/standards/core/64/network.md) From b5518aaeefa02fd33165c050898be2fe29cbb070 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Wed, 4 Dec 2024 19:30:51 -0500 Subject: [PATCH 3/3] Update bridge.md --- waku/standards/core/15/bridge.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/waku/standards/core/15/bridge.md b/waku/standards/core/15/bridge.md index 7d2f68e8..0335901a 100644 --- a/waku/standards/core/15/bridge.md +++ b/waku/standards/core/15/bridge.md @@ -9,7 +9,8 @@ editor: Hanno Cornelius ## Abstract -This specification describes how [6/WAKU1](/waku/standards/legacy/6/waku1.md) can be used with [10/WAKU2](/waku/standards/core/10/waku2.md). +This specification describes how [6/WAKU1](/waku/standards/legacy/6/waku1.md) +can be used with [10/WAKU2](/waku/standards/core/10/waku2.md). ## Wire Format @@ -34,7 +35,8 @@ the creation of a new `Message` with a new `WakuMessage` as data field is REQUIR The `data` and `topic` field, from the [6/WAKU1](/waku/standards/legacy/6/waku1.md) `Envelope`, MUST be copied to the `payload` and `content_topic` fields of the `WakuMessage`. -See [14/WAKU2-MESSAGE](/waku/standards/core/14/message.md#wire-format) for message format details. +See [14/WAKU2-MESSAGE](/waku/standards/core/14/message.md#wire-format) +for message format details. Other fields such as `nonce`, `expiry` and `ttl` will be dropped as they become obsolete in [10/WAKU2](/waku/standards/core/10/waku2.md). @@ -45,7 +47,7 @@ Before this is done, the usual envelope verification still applies: * Size verification Bridging SHOULD occur through the [11/WAKU2-RELAY](/waku/standards/core/11/relay.md), -but it MAY also be done on other [10/WAKU2](/waku/standards/core/10/waku2.md) protocols +but it MAY also be done on other [10/WAKU2](/waku/standards/core/10/waku2.md) protocols (e.g. [12/WAKU2-FILTER](/waku/standards/core/12/filter.md)). The latter is however not advised as it will increase the complexity of the bridge and @@ -63,7 +65,7 @@ the bridge MUST set a new `expiry`, `ttl` and do the PoW `nonce` calculation. ### Security Considerations -As mentioned above, +As mentioned above, a bridge will be posting new [6/WAKU1](/waku/standards/legacy/6/waku1.md) envelopes, which requires doing the PoW `nonce` calculation. @@ -89,9 +91,9 @@ Copyright and related rights waived via ## References -- [6/WAKU1](/waku/standards/legacy/6/waku1.md) -- [10/WAKU2](/waku/standards/core/10/waku2.md) -- [11/WAKU2-RELAY](/waku/standards/core/11/relay.md) -- [14/WAKU2-MESSAGE](/waku/standards/core/14/message.md) -- [12/WAKU2-FILTER](/waku/standards/core/12/filter.md) -- [64/WAKU2-NETWORK](/waku/standards/core/64/network.md) +* [6/WAKU1](/waku/standards/legacy/6/waku1.md) +* [10/WAKU2](/waku/standards/core/10/waku2.md) +* [11/WAKU2-RELAY](/waku/standards/core/11/relay.md) +* [14/WAKU2-MESSAGE](/waku/standards/core/14/message.md) +* [12/WAKU2-FILTER](/waku/standards/core/12/filter.md) +* [64/WAKU2-NETWORK](/waku/standards/core/64/network.md)