diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index 91ab2450..00000000 Binary files a/.DS_Store and /dev/null differ diff --git a/.github/workflows/.gitignore b/.github/workflows/.gitignore new file mode 100644 index 00000000..e43b0f98 --- /dev/null +++ b/.github/workflows/.gitignore @@ -0,0 +1 @@ +.DS_Store diff --git a/.github/workflows/.markdownlint.json b/.github/workflows/.markdownlint.json index 23c35d9a..472afbbb 100644 --- a/.github/workflows/.markdownlint.json +++ b/.github/workflows/.markdownlint.json @@ -1,6 +1,4 @@ { - "MD013": { - "tables": false, - "code_blocks" : false - } + "MD013": false, + "MD024": false } diff --git a/nomos/.DS_Store b/nomos/.DS_Store deleted file mode 100644 index 89dcafab..00000000 Binary files a/nomos/.DS_Store and /dev/null differ diff --git a/status/.DS_Store b/status/.DS_Store deleted file mode 100644 index 8043d3f2..00000000 Binary files a/status/.DS_Store and /dev/null differ diff --git a/status/raw/simple-scaling.md b/status/raw/simple-scaling.md index 6940d31c..e8516b61 100644 --- a/status/raw/simple-scaling.md +++ b/status/raw/simple-scaling.md @@ -63,14 +63,14 @@ efficient way will be part of a future document. Sharding the [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md) network is an integral part of scaling the Status app. -[51/WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md) +[WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) specifies shards clusters, which are sets of `1024` shards (separate pubsub mesh networks). Content topics specified by application protocols can be distributed over these shards. The Status app protocols are assigned to shard cluster `16`, -as defined in [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc.md). +as defined in [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/master/informational/relay-static-shard-alloc.md). -[WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md) +[WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) specifies three sharding methods. This document uses *static sharding*, which leaves the distribution of content topics to application protocols, @@ -88,7 +88,7 @@ The 1024 shards within the main Status shard cluster are allocated as follows. | 768 - 895 | 1:1 chat | | 896 - 1023 | media and control msgs | -Shard indices are mapped to pubsub topic names as follows (specified in [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md)). +Shard indices are mapped to pubsub topic names as follows (specified in [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md)). `/waku/2/rs//` @@ -154,7 +154,7 @@ message CommunityDescription { } ``` -> *Note*: Currently, Status app has allocated shared cluster `16` in [52/WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc.md). +> *Note*: Currently, Status app has allocated shared cluster `16` in [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/master/informational/relay-static-shard-alloc.md). Status app could allocate more shard clusters, for instance to establish a test net. We could add the shard cluster index to the community description as well. The recommendation for now, @@ -168,7 +168,7 @@ Status communities can be mapped to shards in two ways: static, and owner-based. With static mapping, communities are assigned a specific shard index within the Status shard cluster. -This mapping is similar in nature to the shard cluster allocation in [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc.md). +This mapping is similar in nature to the shard cluster allocation in [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/master/informational/relay-static-shard-alloc.md). Shard indices allocated in that way are in the range `16 - 127`. The Status CC community uses index `16` (not to confuse with shard cluster index `16`, which is the Status shard cluster). @@ -310,7 +310,7 @@ Light protocols comprise * [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md) for sending messages * [12/WAKU2-FILTER](../../waku/standards/core/12/filter.md) for requesting messages with specific attributes -* [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/peer-exchange/peer-exchange.md) +* [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/master/standards/core/peer-exchange.md) for discovering peers ## Waku Archive @@ -333,7 +333,7 @@ In fact, the archive service can be offered by infrastructure nodes. ## Discovery -Shard discovery is covered by [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md). +Shard discovery is covered by [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md). This allows the Status app to abstract from the discovery process and simply address shards by their index. @@ -344,7 +344,7 @@ this document suggests using [libp2p rendezvous](https://github.com/libp2p/specs Nodes can check whether they are behind a restrictive NAT using the [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README.md). -> *Note:* The following will move into [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md), +> *Note:* The following will move into [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md), or [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5.md): Nodes behind restrictive NATs SHOULD not announce their publicly unreachable address via [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5.md) discovery. @@ -369,9 +369,9 @@ functionality offered by the libp2p circuit relay protocols, and to upgrade to a direct connection. Nodes that do not announce themselves at all and only plan to use light protocols, -MAY use rendezvous discovery instead of or along-side [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/peer-exchange/peer-exchange.md). +MAY use rendezvous discovery instead of or along-side [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/master/standards/core/peer-exchange.md). For these nodes, rendezvous and -[WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/peer-exchange/peer-exchange.md) +[WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/master/standards/core/peer-exchange.md) offer the same functionality, but return node sets sampled in different ways. Using both can help increasing connectivity. @@ -401,7 +401,7 @@ The string conversion SHOULD remove leading zeros. field is of type string, a more efficient byte encoding is not utilized. Registering shard 2 in the Status shard cluster (with shard cluster index 16, -see [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc.md), +see [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/master/informational/relay-static-shard-alloc.md), the register query would look like ```rs @@ -601,7 +601,7 @@ It could be rate-limited with RLN. This document makes several trade-offs to privacy and anonymity. Todo: elaborate. -See [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/waku-RFC/informational/adversarial-models.md) +See [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/master/informational/adversarial-models.md) for information on Waku Anonymity. ## Copyright @@ -614,12 +614,12 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public * [55/STATUS-1TO1-CHAT](../55/1to1-chat.md) * [23/WAKU2-TOPICS](../../waku/informational/23/topics.md) * [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md) -* [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md) -* [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/waku-RFC/informational/relay-static-shard-alloc.md) +* [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) +* [WAKU2-RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/master/informational/relay-static-shard-alloc.md) * [30/ADAPTIVE-NODES](../../waku/informational/30/adaptive-nodes.md) * [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md) * [12/WAKU2-FILTER](../../waku/standards/core/12/filter.md) -* [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/peer-exchange/peer-exchange.md) +* [WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/master/standards/core/peer-exchange.md) * [13/WAKU2-STORE](../../waku/standards/core/13/store.md) * [libp2p rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README.md) * [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README.md) @@ -629,9 +629,9 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public * [DCUtR](https://github.com/libp2p/specs/blob/master/relay/DCUtR.md) * [scoring](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#extended-validators) * [Circuit Relay](https://docs.libp2p.io/concepts/nat/circuit-relay/) -* [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/waku-RFC/informational/adversarial-models.md) +* [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/master/informational/adversarial-models.md) ## Informative * [Circuit Relay](https://docs.libp2p.io/concepts/nat/circuit-relay/) -* [WAKU2-ENR](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr.md) +* [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md) diff --git a/status/raw/status-app-protocols.md b/status/raw/status-app-protocols.md index 14d09d22..150e9584 100644 --- a/status/raw/status-app-protocols.md +++ b/status/raw/status-app-protocols.md @@ -58,8 +58,8 @@ Status currently defines functionality to support three main application feature Each application-level function, regardless which feature set it supports, has the following properties: 1. Functional scope -1. Content topic -1. Ephemerality +2. Content topic +3. Ephemerality ### Functional Scope @@ -92,17 +92,18 @@ All Status messages MUST have one of these functional scopes: #### Community scope -3. _Community control_: messages enabling the basic functioning of the app to control features _only relevant to members of a specific community_. Examples include Community Membership Updates, community Status Updates, etc. -4. _Community content_: messages carrying user-generated content _only for members of a specific community_. +1._Community control_: messages enabling the basic functioning of the app to control features _only relevant to members of a specific community_. Examples include Community Membership Updates, community Status Updates, etc. +2. _Community content_: messages carrying user-generated content _only for members of a specific community_. #### Local scope -5. _Local_: messages related to functions that are only relevant to a single user. Also known as _self-addressed messages_. Examples include messages used to exchange information between app installations, such as User Backup and Sync messages. +1. _Local_: messages related to functions that are only relevant to a single user. Also known as _self-addressed messages_. Examples include messages used to exchange information between app installations, such as User Backup and Sync messages. Note that the functional scope is a logical property of Status messages. It SHOULD however inform the underlying [transport layer sharding](#pubsub-topics-and-sharding) and [transport layer subscriptions](#subscribing). In general a Status client SHOULD subscribe to participate in: -- all global functions, + +- all global functions - (only) the community functions for communities of which it is a member, and - its own local functions. @@ -140,7 +141,7 @@ App-level messages that are considered ephemeral, MUST set the `ephemeral` field The end-to-end reliability layer contains the functions related to one of the two end-to-end reliability schemes defined for Status app messages: 1. Minimum Viable protocol for Data Synchronisation, or MVDS (see [STATUS-MVDS-USAGE](./status-mvds.md)) -1. Scalable distributed log reliability (spec and a punchier name TBD, see the [original forum post announcement](https://forum.vac.dev/t/end-to-end-reliability-for-scalable-distributed-logs/293/16)) +2. Scalable distributed log reliability (spec and a punchier name TBD, see the [original forum post announcement](https://forum.vac.dev/t/end-to-end-reliability-for-scalable-distributed-logs/293/16)) Ephemeral messages SHOULD omit this layer. Non-ephemeral 1:1 chat messages SHOULD make use of MVDS to achieve reliable data synchronisation between the two parties involved in the communication. @@ -243,8 +244,8 @@ useful for the user functions specific to that instance of the application. The specific Waku discovery protocol used for discovery depends on the use case and resource-availability of the client. 1. [EIP-1459: DNS-based discovery](https://eips.ethereum.org/EIPS/eip-1459) is useful for initial connection to bootstrap peers. -1. [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5.md) allows decentralized discovery of Waku peers. -1. [34/WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/315264c202e0973476e2f1e2d0b01bea4fe1ad31/standards/core/peer-exchange.md) allows requesting peers from a service node +2. [33/WAKU2-DISCV5](../../waku/standards/core/33/discv5.md) allows decentralized discovery of Waku peers. +3. [34/WAKU2-PEER-EXCHANGE](https://github.com/waku-org/specs/blob/315264c202e0973476e2f1e2d0b01bea4fe1ad31/standards/core/peer-exchange.md) allows requesting peers from a service node and is appropriate for resource-restricted discovery. All clients SHOULD use DNS-based discovery on startup @@ -263,14 +264,14 @@ and to enable the user functions specific to that instance of the application. The specific Waku protocol used for subscription depends on the resource-availability of the client: 1. Filter client protocol, as specified in [12/WAKU2-FILTER](../../waku/standards/core/12/filter.md), allows subscribing for traffic with content topic granularity and is appropriate for resource-restricted subscriptions. -1. Relay protocol, as specified in [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md), allows subscribing to traffic only with pubsub topic granularity and therefore is more resource-intensive. Relay subscription also allows the application instance to contribute to the overall routing infrastructure, which adds to its overall higher resource usage but benefits the ecosystem. +2. Relay protocol, as specified in [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md), allows subscribing to traffic only with pubsub topic granularity and therefore is more resource-intensive. Relay subscription also allows the application instance to contribute to the overall routing infrastructure, which adds to its overall higher resource usage but benefits the ecosystem. Full clients SHOULD use relay protocol as preferred method to subscribe to pubsub topics matching the scopes: 1. Global control -1. Global content -1. Community control, for each community of which the app user is a member -1. Community content, for each community of which the app user is a member +2. Global content +3. Community control, for each community of which the app user is a member +4. Community content, for each community of which the app user is a member Light clients SHOULD use filter protocol to subscribe only to the content topics relevant to the user. @@ -290,14 +291,14 @@ The application MUST publish user and app generated messages via the Waku transp The specific Waku protocol used for publishing depends on the resource-availability of the client: 1. Lightpush protocol, as specified in [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md) allows publishing to a pubsub topic via an intermediate "full node" and is more appropriate for resource-restricted publishing. -1. Relay protocol, as specified in [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md), allows publishing directly into the relay routing network and is therefore more resource-intensive. +2. Relay protocol, as specified in [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md), allows publishing directly into the relay routing network and is therefore more resource-intensive. Full clients SHOULD use relay protocol to publish to pubsub topics matching the scopes: 1. Global control -1. Global content -1. Community control, for each community of which the app user is a member -1. Community content, for each community of which the app user is a member +2. Global content +3. Community control, for each community of which the app user is a member +4. Community content, for each community of which the app user is a member Light clients SHOULD use lightpush protocol to publish control and content messages. @@ -397,13 +398,13 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public ## References 1. [55/STATUS-1TO1-CHAT](../55/1to1-chat.md) -1. [56/STATUS-COMMUNITIES](../56/communities.md) -1. [10/WAKU2](../../waku/standards/core/10/waku2.md) -1. [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md) -1. [12/WAKU2-FILTER](../../waku/standards/core/12/filter.md) -1. [14/WAKU2-MESSAGE](../../waku/standards/core/14/message.md) -1. [23/WAKU2-TOPICS](../../waku/informational/23/topics.md) -1. [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md) -1. [Scalable distributed log reliability](https://forum.vac.dev/t/end-to-end-reliability-for-scalable-distributed-logs/293/16) -1. [STATUS-MVDS-USAGE](./status-mvds.md) -1. [WAKU2-STORE](https://github.com/waku-org/specs/blob/8fea97c36c7bbdb8ddc284fa32aee8d00a2b4467/standards/core/store.md) +2. [56/STATUS-COMMUNITIES](../56/communities.md) +3. [10/WAKU2](../../waku/standards/core/10/waku2.md) +4. [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md) +5. [12/WAKU2-FILTER](../../waku/standards/core/12/filter.md) +6. [14/WAKU2-MESSAGE](../../waku/standards/core/14/message.md) +7. [23/WAKU2-TOPICS](../../waku/informational/23/topics.md) +8. [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md) +9. [Scalable distributed log reliability](https://forum.vac.dev/t/end-to-end-reliability-for-scalable-distributed-logs/293/16) +10. [STATUS-MVDS-USAGE](./status-mvds.md) +11. [WAKU2-STORE](https://github.com/waku-org/specs/blob/8fea97c36c7bbdb8ddc284fa32aee8d00a2b4467/standards/core/store.md) diff --git a/status/raw/url-data.md b/status/raw/url-data.md index 5c7bdeaa..1a5662ab 100644 --- a/status/raw/url-data.md +++ b/status/raw/url-data.md @@ -26,7 +26,7 @@ this specification proposes a standard method for encoding data within URLs. - Community: Refer to [STATUS-COMMUNITIES](../56/communities.md) - Channel: Refer to terminology in [STATUS-COMMUNITIES](../56/communities.md) - User: Refer to terminology in [STATUS-COMMUNITIES](../56/communities.md) -- Shard Refer to terminology in [51/WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) +- Shard Refer to terminology in [WAKU2-RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) ## Wire Format diff --git a/vac/.DS_Store b/vac/.DS_Store deleted file mode 100644 index e7408ba5..00000000 Binary files a/vac/.DS_Store and /dev/null differ diff --git a/vac/raw/mix.md b/vac/raw/mix.md index b317b96e..f0064071 100644 --- a/vac/raw/mix.md +++ b/vac/raw/mix.md @@ -735,7 +735,7 @@ ii. **Verify Timestamp** - If the timestamp is outside the acceptable window, the exit node discards the message. -iii. **Verifiy Response** +iii. **Verify Response** - Compute the SHA-256 hash of the `message` and check if the hash meets the difficulty requirement, _i.e._, has at least 18 leading zeros. diff --git a/vac/template.md b/vac/template.md index 48ea3222..815258e5 100644 --- a/vac/template.md +++ b/vac/template.md @@ -1,9 +1,9 @@ --- slug: XX -title: XX/(WAKU2|LOGOS|CODEX|*)-TEMPLATE -name: (Waku v2 | Logos | Codex) RFC Template -status: (raw|draft|stable) -category: (Standards Track|Informational|Best Current Practice) +title: TEMPLATE +name: RFC Template +status: raw/draft/stable/deprecated +category: Standards Track/Informational/Best Current Practice tags: an optional list of tags, not standard editor: Daniel Kaiser contributors: diff --git a/waku/.DS_Store b/waku/.DS_Store deleted file mode 100644 index b86f5c40..00000000 Binary files a/waku/.DS_Store and /dev/null differ diff --git a/waku/deprecated/.DS_Store b/waku/deprecated/.DS_Store deleted file mode 100644 index 57773832..00000000 Binary files a/waku/deprecated/.DS_Store and /dev/null differ diff --git a/waku/informational/.DS_Store b/waku/informational/.DS_Store deleted file mode 100644 index c402fd69..00000000 Binary files a/waku/informational/.DS_Store and /dev/null differ diff --git a/waku/informational/23/topics.md b/waku/informational/23/topics.md index 934faeb9..02e0beab 100644 --- a/waku/informational/23/topics.md +++ b/waku/informational/23/topics.md @@ -19,9 +19,9 @@ In [10/WAKU2 spec](../../standards/core/10/waku2.md) there are two types of topi ## Pubsub Topics Pubsub topics are used for routing of messages (see [11/WAKU2-RELAY](../../standards/core/11/relay.md)), -and can be named implicitly by Waku sharding (see [RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md)). +and can be named implicitly by Waku sharding (see [RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md)). This document comprises recommendations for explicitly naming pubsub topics -(e.g. when choosing *named sharding* as specified in [RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md)). +(e.g. when choosing *named sharding* as specified in [RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md)). ### Pubsub Topic Format @@ -80,7 +80,7 @@ but for different domains completely. ### Named Topic Sharding Example -The following is an example of named sharding, as specified in [RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md). +The following is an example of named sharding, as specified in [RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md). ```text waku/2/waku-9_shard-0/ @@ -175,7 +175,7 @@ Copyright and related rights waived via - [10/WAKU2 spec](../../standards/core/10/waku2.md) - [11/WAKU2-RELAY](../../standards/core/11/relay.md) -- [RELAY-SHARDING](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/relay-sharding.md) +- [RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) - [Ethereum 2 P2P spec](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/p2p-interface.md#topics-and-messages) - [14/WAKU2-MESSAGE](../../standards/core/14/message.md) - [12/WAKU2-FILTER](../../standards/core/12/filter.md) diff --git a/waku/standards/.DS_Store b/waku/standards/.DS_Store deleted file mode 100644 index 92eaf995..00000000 Binary files a/waku/standards/.DS_Store and /dev/null differ diff --git a/waku/standards/application/.DS_Store b/waku/standards/application/.DS_Store deleted file mode 100644 index 32b85ce7..00000000 Binary files a/waku/standards/application/.DS_Store and /dev/null differ diff --git a/waku/standards/core/.DS_Store b/waku/standards/core/.DS_Store deleted file mode 100644 index 1807b824..00000000 Binary files a/waku/standards/core/.DS_Store and /dev/null differ diff --git a/waku/standards/core/10/waku2.md b/waku/standards/core/10/waku2.md index c326b8da..b1e81d35 100644 --- a/waku/standards/core/10/waku2.md +++ b/waku/standards/core/10/waku2.md @@ -224,7 +224,7 @@ It is possible to bypass the discovery domain by specifying static nodes. #### Use of ENR -[31/WAKU2-ENR](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr.md) +[WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md) describes the usage of [EIP-778 ENR (Ethereum Node Records)](https://eips.ethereum.org/EIPS/eip-778) for Waku v2 discovery purposes. It introduces two new ENR fields, `multiaddrs` and @@ -574,7 +574,7 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public 17. [Node Discovery v5](https://github.com/ethereum/devp2p/blob/8fd5f7e1c1ec496a9d8dc1640a8548b8a8b5986b/discv5/discv5.md) -18. [31/WAKU2-ENR](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr.md) +18. [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md) 19. [EIP-778 ENR (Ethereum Node Records)](https://eips.ethereum.org/EIPS/eip-778) diff --git a/waku/standards/core/12/.DS_Store b/waku/standards/core/12/.DS_Store deleted file mode 100644 index 18d01199..00000000 Binary files a/waku/standards/core/12/.DS_Store and /dev/null differ diff --git a/waku/standards/core/14/message.md b/waku/standards/core/14/message.md index 694e66ce..af30ee57 100644 --- a/waku/standards/core/14/message.md +++ b/waku/standards/core/14/message.md @@ -118,7 +118,7 @@ The key agreement is performed out of band. And provides an encrypted signature and padding for some form of unlinkability. - **Version 2:** -The payload SHOULD be encoded according to [35/WAKU2-NOISE]([/spec/35](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/noise.md)). +The payload SHOULD be encoded according to [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise.md). Waku Noise protocol provides symmetric encryption and asymmetric key exchange. Any `version` value not included in this list is reserved for future specification. @@ -254,5 +254,5 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public - [6/WAKU1](../../legacy/6/waku1.md) - [Google Protocol buffers v3](https://developers.google.com/protocol-buffers/) - [26/WAKU-PAYLOAD](../../application/26/payload.md) -- [35/WAKU2-NOISE]([/spec/35](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/noise.md)) +- [WAKU2-NOISE](https://github.com/waku-org/specs/blob/master/standards/application/noise.md) - [62/STATUS-PAYLOADS](../../../../status/62/payloads.md/#clock-vs-timestamp-and-message-ordering) diff --git a/waku/standards/core/17/rln-relay.md b/waku/standards/core/17/rln-relay.md index 5a1ff909..b199181c 100644 --- a/waku/standards/core/17/rln-relay.md +++ b/waku/standards/core/17/rln-relay.md @@ -18,7 +18,7 @@ This specification describes the `17/WAKU2-RLN-RELAY` protocol, which is an extension of [`11/WAKU2-RELAY`](../11/relay.md) to provide spam protection using [Rate Limiting Nullifiers (RLN)](../../../../vac/32/rln-v1.md). -The security objective is to contain spam activity in the (64/WAKU-NETWORK)[] +The security objective is to contain spam activity in the [64/WAKU-NETWORK](../64/network.md) by enforcing a global messaging rate to all the peers. Peers that violate the messaging rate are considered spammers and their message is considered spam. @@ -374,9 +374,10 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public ## References 1. [`11/WAKU2-RELAY`](../11/relay.md) -2. [RLN](../../../../vac/32/rln-v1.md) -3. [14/WAKU2-MESSAGE](../14/message.md) -4. [RLN documentation](https://hackmd.io/tMTLMYmTR5eynw2lwK9n1w?view) -5. [Public inputs to the RLN circuit](https://hackmd.io/tMTLMYmTR5eynw2lwK9n1w?view#Public-Inputs) -6. [Shamir secret sharing scheme used in RLN](https://hackmd.io/tMTLMYmTR5eynw2lwK9n1w?view#Linear-Equation-amp-SSS) -7. [RLN internal nullifier](https://hackmd.io/tMTLMYmTR5eynw2lwK9n1w?view#Nullifiers) +2. [64/WAKU-NETWORK](../64/network.md) +3. [RLN](../../../../vac/32/rln-v1.md) +4. [14/WAKU2-MESSAGE](../14/message.md) +5. [RLN documentation](https://hackmd.io/tMTLMYmTR5eynw2lwK9n1w?view) +6. [Public inputs to the RLN circuit](https://hackmd.io/tMTLMYmTR5eynw2lwK9n1w?view#Public-Inputs) +7. [Shamir secret sharing scheme used in RLN](https://hackmd.io/tMTLMYmTR5eynw2lwK9n1w?view#Linear-Equation-amp-SSS) +8. [RLN internal nullifier](https://hackmd.io/tMTLMYmTR5eynw2lwK9n1w?view#Nullifiers) diff --git a/waku/standards/core/19/lightpush.md b/waku/standards/core/19/lightpush.md index 97baa310..82c10b5b 100644 --- a/waku/standards/core/19/lightpush.md +++ b/waku/standards/core/19/lightpush.md @@ -114,6 +114,6 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public ## References * [11/WAKU2-RELAY](../11/relay.md) -* [WAKU2-DANDELION](https://github.com/waku-org/specs/blob/waku-RFC/standards/application/dandelion.md) +* [WAKU2-DANDELION](https://github.com/waku-org/specs/blob/master/standards/application/dandelion.md) * [17/WAKU2-RLN-RELAY](../17/rln-relay.md) * [WAKU2-INCENTIVIZATION](https://github.com/waku-org/specs/blob/master/standards/core/incentivization.md) diff --git a/waku/standards/core/33/discv5.md b/waku/standards/core/33/discv5.md index b4abdafd..d4f48a82 100644 --- a/waku/standards/core/33/discv5.md +++ b/waku/standards/core/33/discv5.md @@ -41,8 +41,8 @@ within the network. in order of increasing decentralization * hard coded bootstrap nodes -* [`DNS discovery`](https://rfc.vac.dev/spec/10/#discovery-domain) (based on [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459)) -* `peer-exchange` (work in progress) +* [`DNS discovery`](/waku/standards/10/waku2.md/#discovery-domain) (based on [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459)) +* [`34/WAKU2-PEER-EXCHANGE`](/waku/standards/core/34/peer-exchange.md) * `33/WAKU2-DISCV5` (specified in this document) The purpose of ambient node discovery within [10/WAKU2](../10/waku2.md) @@ -74,7 +74,7 @@ This also increases decentralization. isolated from the Ethereum Discovery v5 network. Another simple solution would be taking part in the Ethereum Discovery network, -and filtering Waku nodes based on whether they support [WAKU2-ENR](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr.md). +and filtering Waku nodes based on whether they support [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md). This solution is more resilient towards eclipse attacks. However, this discovery method is very inefficient for small percentages of Waku nodes @@ -205,20 +205,20 @@ raises research questions that we will address in future stages of our discv5 ro ## References 1. [10/WAKU2](../10/waku2.md) -1. [11/WAKU2-RELAY](../11/relay.md) -1. [`WAKU2-ENR`](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr.md) -1. [Node Discovery Protocol v5 (`discv5`)](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) -1. [`discv5` semantics](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md). -1. [`discv5` wire protocol](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-wire.md) -1. [`discv5` topic discovery](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md#topic-advertisement) -1. [Waku DNS discovery](https://rfc.vac.dev/spec/10/#discovery-domain) -1. [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README.md) -1. [`EIP-1459`](https://eips.ethereum.org/EIPS/eip-1459) -1. [`GossipSub`](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md) -1. [Waku discv5 roadmap discussion](https://forum.vac.dev/t/waku-v2-discv5-roadmap-discussion/121) -1. [discovery efficiency estimation](https://forum.vac.dev/t/waku-v2-discv5-roadmap-discussion/121/8) -1. [implementation: Nim](https://github.com/kaiserd/nim-eth/blob/add-selectable-protocol-id-static/eth/p2p/discoveryv5/encoding.nim) -1. [implementation: Go](https://github.com/status-im/go-waku/blob/master/waku/v2/discv5/discover.go) +2. [`34/WAKU2-PEER-EXCHANGE`](/waku/standards/core/34/peer-exchange.md) +3. [11/WAKU2-RELAY](../11/relay.md) +4. [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md) +5. [Node Discovery Protocol v5 (`discv5`)](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) +6. [`discv5` semantics](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md). +7. [`discv5` wire protocol](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-wire.md) +8. [`discv5` topic discovery](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md#topic-advertisement) +9. [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README.md) +10. [`EIP-1459`](https://eips.ethereum.org/EIPS/eip-1459) +11. [`GossipSub`](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md) +12. [Waku discv5 roadmap discussion](https://forum.vac.dev/t/waku-v2-discv5-roadmap-discussion/121) +13. [discovery efficiency estimation](https://forum.vac.dev/t/waku-v2-discv5-roadmap-discussion/121/8) +14. [implementation: Nim](https://github.com/kaiserd/nim-eth/blob/add-selectable-protocol-id-static/eth/p2p/discoveryv5/encoding.nim) +15. [implementation: Go](https://github.com/status-im/go-waku/blob/master/waku/v2/discv5/discover.go) ## Copyright diff --git a/waku/standards/core/34/images/protocol.svg b/waku/standards/core/34/images/protocol.svg new file mode 100644 index 00000000..dda2157a --- /dev/null +++ b/waku/standards/core/34/images/protocol.svg @@ -0,0 +1,118 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/waku/standards/core/34/peer-exchange.md b/waku/standards/core/34/peer-exchange.md new file mode 100644 index 00000000..9c00c9b9 --- /dev/null +++ b/waku/standards/core/34/peer-exchange.md @@ -0,0 +1,231 @@ +--- +slug: 34 +title: 34/WAKU2-PEER-EXCHANGE +name: Waku2 Peer Exchange +status: draft +category: Standards Track +tags: waku/core-protocol +editor: Hanno Cornelius +contributors: +- Daniel Kaiser +--- + +## Abstract + +This document specifies a simple request-response peer exchange protocol. +Responders send information about a requested number of peers. +The main purpose of this protocol is providing resource restricted devices with peers. + +***Protocol Identifier*** + +> /vac/waku/peer-exchange/2.0.0-alpha1 + +## Background and Motivation + +It may not be feasible, on resource restricted devices, +to take part in distributed random sampling ambient peer discovery protocols, +such as [33/WAKU2-DISCV5](/waku/standards/core/33/discv5.md). +The Waku peer discovery protocol, specified in this document, +allows resource restricted devices to request a list of peers from a service node. +Network parameters necessary to connect to this service node COULD be learned +from a static bootstrapping method or +using [EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459). +The advantage of using Waku peer exchange to discover new peers, +compared to relying on a static peer list or DNS discovery, is a more even load distribution. +If a lot of resource restricted nodes would use the same service nodes as relay +or store nodes, the load on these would be very high. +Heavily used static nodes also add a centralized element. +Downtime of such a node might significantly impact the network. + +However, the resource efficiency of this protocol comes at an anonymity cost, +which is explained in the +[Security/Privacy Considerations](#security-considerations) section. +This protocol SHOULD only be used if [33/WAKU2-DISCV5](/waku/standards/core/33/discv5.md) is infeasible. + +## Theory and Protocol Semantics + +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). + +The peer exchange protocol, specified in this document, +is a simple request-response protocol. +As Figure 1 illustrates, the requesting node sends a request to a peer, +which acts as the responder. +The responder replies with a list of ENRs as specified in [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md). +The [multiaddresses](https://docs.libp2p.io/concepts/addressing/) +used to connect to the respective peers can be extracted from the ENRs. + +![Figure 1: The responder provides a list of ENRs to the requester. These ENRs contain the information necessary for connecting to the respective peers.](/waku/standards/core/34/images/protocol.svg) + +In order to protect its anonymity, +the responder MUST NOT provide peers from its actively used peer list +as this opens pathways to *Neighbourhood Surveillance* attacks, as described in the +[Security/Privacy Considerations Section](#security-considerations). +The responder SHOULD provide a set of peers +that has been retrieved using ambient peer discovery methods supporting random sampling, +e.g. [33/WAKU2-DISCV5](/waku/standards/core/33/discv5.md). +This both protects the responder's anonymity as well as helps distributing load. + +To allow for fast responses, responders SHOULD retrieve peers unsolicited +(before receiving a query) and +maintain a queue of peers for the purpose of providing them in peer exchange responses. +To get the best anonymity properties with respect to response peer sets, +responders SHOULD use each of these peers only once. + +To save bandwidth, and as a trade off to anonymity, +responders MAY maintain a larger cache of exchange peers and +randomly sample response sets from this local cache. +The size of the cache SHOULD be large enough to allow randomly sampling peer sets +that (on average) do not overlap too much. +The responder SHOULD periodically replace the oldest peers in the cache. +The RECOMMENDED options for the cache size are described in the +[Implementation Suggestions Section](#implementation-suggestions). + +Requesters, in the context of the specified peer exchange protocol, +SHOULD be resource restricted devices. +While any node could technically act as a requester, +using the peer exchange protocol comes with two drawbacks: + +* reducing [anonymity](#security-considerations) +* causing load on responder nodes + +## Wire Format Specification + +```protobuf +syntax = "proto3"; + +message PeerInfo { + bytes enr = 1; +} + +message PeerExchangeQuery { + uint64 num_peers = 1; +} + +message PeerExchangeResponse { + repeated PeerInfo peer_infos = 1; +} + +message PeerExchangeRPC { + PeerExchangeQuery query = 1; + PeerExchangeResponse response = 2; +} + +``` + +The `enr` field contains a Waku ENR as specified in [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md). + +Requesters send a `PeerExchangeQuery` to a peer. +Responders SHOULD include a maximum of `num_peers` `PeerInfo` instances into a response. +Responders send a `PeerExchangeResponse` to requesters +containing a list of `PeerInfo` instances, which in turn hold an ENR. + +## Implementation Suggestions + +### Discovery Interface + +Implementations can implement the libp2p discovery interface: + +* [nim](https://github.com/status-im/nim-libp2p/issues/140) +* [javascript](https://github.com/libp2p/js-libp2p-interfaces/tree/master/packages/interface-peer-discovery). + +### Exchange Peer Cache Size + +The size of the (optional) exchange peer cache discussed in +[Theory and Protocol Semantics](#theory-and-protocol-semantics) +depends on the average number of requested peers, +which is expected to be the outbound degree of the underlying +[libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md) +mesh network. +The RECOMMENDED value for this outbound degree is 6 (see parameter `D` in [29/WAKU2-CONFIG](/waku/informational/29/config.md)). +It is RECOMMENDED for the cache to hold at least 10 times as many peers (60). + +The RECCOMENDED cache size also depends on the number of requesters a responder +is expected to serve within a *refresh cycle*. +A refresh cycle is the time interval in which all peers in the cache +are expected to be replaced. +If the number of requests expected per refresh cycle exceeds 600 +(10 times the above recommended 60), +it is RECOMMENDED to increase the cache size to at least a tenth of that number. + +## Security Considerations + +### Privacy and Anonymity + +The peer exchange protocol specified in this document comes with anonymity and +security implications. +We differentiate these implications into the requester and responder side, respectively. + +### Requester + +With a simple peer exchange protocol, +the requester is inherently susceptible to both *neighbourhood surveillance* and +*controlled neighbourhood* attacks. + +To mount a *neighbourhood surveillance* attack, +an attacker has to connect to the peers of the victim node. +The peer exchange protocol allows a malicious responder to easily get into this position. +The responder connects to a set of peers and +simply returns this set of peers to the requester. + +The peer exchange protocol also makes it much easier to get into the position +required for the *controlled neighbourhood* attack: +A malicious responder provides controlled peers in the response peer list. + +More on these attacks may be found in our [research log article](https://vac.dev/wakuv2-relay-anon). + +As a weak mitigation the requester MAY ask several peers and +select a subset of the returned peers. + +### Responder + +Responders that answer with active mesh peers are more vulnerable +to a *neighbourhood surveillance* attack. +Responding with the set of active mesh peers allows a malicious requester to +get into the required position more easily. +It takes away the first hurdle of the *neighbourhood surveillance* attack: +The attacker knows which peers to try to connect to. +This increased vulnerability can be avoided by only responding +with randomly sampled sets of peers, +e.g. by requesting a random peer set via [33/WAKU2-DISCV5](/waku/standards/core/33/discv5.md). +(As stated in the [Theory and Protocol Semantics Section](#theory-and-protocol-semantics), +these peer sets SHOULD be retrieved unsolicitedly before +receiving requests to achieve faster response times.) + +Responders are also susceptible to amplification DoS attacks. +Requesters send a simple message request which causes responders to +engage in ambient peer discovery to retrieve a new random peer set. +As a mitigation, responders MAY feature a `seen cache` for requests and +only answer once per time interval. +The exchange-peer cache discussed in [Theory and Protocol Semantics Section](#theory-and-protocol-semantics) +also provides mitigation. +Still, frequent queries can tigger the refresh cycle more often. +The `seen cache` MAY be used in conjunction to provide additional mitigation. + +### Further Considerations + +The response field contains ENRs as specified in [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md). +While ENRs contain signatures, they do not violate the [Waku relay no-sign policy](/waku/standards/core/11/relay.md#signature-policy), +because they are part of the discovery domain and +are not propagated in the relay domain. +However, there might still be some form of leakage: +ENRs could be used to track peers and facilitate linking attacks. +We will investigate this further in our Waku anonymity analysis. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References + +* [33/WAKU2-DISCV5](/waku/standards/core/33/discv5.md) +* [EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459) +* [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md) +* [multiaddress](https://docs.libp2p.io/concepts/addressing/) +* [libp2p discovery interface in nim](https://github.com/status-im/nim-libp2p/issues/140) +* [libp2p discovery interface in javascript](https://github.com/libp2p/js-libp2p-interfaces/tree/master/packages/interface-peer-discovery) +* [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md) +* [29/WAKU2-CONFIG](/waku/informational/29/config.md) +* [Waku Relay Anonymity](https://vac.dev/wakuv2-relay-anon) +* [Waku relay no-sign policy](/waku/standards/core/11/relay.md#signature-policy) diff --git a/waku/standards/legacy/.DS_Store b/waku/standards/legacy/.DS_Store deleted file mode 100644 index 895ae261..00000000 Binary files a/waku/standards/legacy/.DS_Store and /dev/null differ