diff --git a/.wordlist.txt b/.wordlist.txt index 130233d..6c21335 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,27 +1,140 @@ +ABIs +addListener ALLOC +api +AsyncAPI +autosharding +AutoShardingConfig BCP +bool Bradner +camelCase +cd +centric +config +ConnectionStatus +ConnectionStatusEvent +contentTopic +contentTopics +createNode creativecommons +cryptographic danielkaiser +DefaultAutoShardingConfig +DefaultMessageValidation +DefaultNetworkingConfig +dev DHT +discv +DISCV DoS encodings +enrtree +enum +eth +Eth +ETH +EventEmitter +EventSource +eventType +fb +fBF +getAvailableConfigs +getAvailableNodeInfoIds +getAvailableNodeInfoItems +getMerkleRoot +getNodeInfo github GITHUB gossipsub GossipSub +HealthConnectionStatusEvent +healthEvents +HealthEvents https iana IANA +IDL implementers +implementor +Inclusivity +Init +ipv +iterable +Jazzz +JSON +KiB +Kozlov +libp libp2p +LIGHTPUSH md +MessageEnvelope +MessageErrorEvent +messageEvents +MessageEvents +MessagePropagatedEvent +MessageReceivedEvent +MessageSendErrorEvent +MessageSendPropagatedEvent +MessageSentEvent +MessageValidation +multiaddr +NetworkConfig +NetworkingConfig +nim +nodeConfig +NodeConfig +nodeInfoId +num +Oleksandr +onEvent +OpenAPI +PartiallyConnected +PascalCase +Pax +Prathi +pre +Prem +ProtocolsConfig pubsub +pubsub +Raya +Raya's +RequestId +responder +rfc rfc RFC +RFC +rln +RLN +RlnConfig +Royer +rpc +RPC +Saro +sharding SHARDING subnets +SubscriptionError +TBD +tcp +TCP +TheWakuNetworkMessageValidation +TheWakuNetworkPreset +TODO +TWN +udp +UDP +uint +waku Waku WAKU +WakuNode www +xB +yaml +YAML +yml ZXCV \ No newline at end of file diff --git a/README.md b/README.md index 66bd734..26b9864 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ This repository contains specifications for the Waku suite of protocols. |[TOR-PUSH](standards/application/tor-push.md)| Waku Tor Push | |[RLN-KEYSTORE](standards/application/rln-keystore.md)| Waku RLN Keystore JSON schema | |[P2P-RELIABILITY](standards/application/p2p-reliability.md)| Waku P2P Reliability | +|[WAKU-API](standards/application/waku-api.md)| Waku API | ### Informational diff --git a/informational/chat_cast.md b/informational/chat_cast.md new file mode 100644 index 0000000..1965997 --- /dev/null +++ b/informational/chat_cast.md @@ -0,0 +1,104 @@ +--- +title: CHAT-CAST +name: Roles and Entities Used in Chat Protocol Documentation +status: raw +category: Informational +tags: [chat/informational] +editor: Jazzz +contributors: +--- + +## Abstract + +This document defines a reusable cast of characters to be used in chat protocol documentation and related supporting materials. +The goal is to improve clarity and consistency when describing protocol roles, actors, and message flows. + +## Background + +When documenting applications and protocols, it is often beneficial to define a consistent set of characters representing common roles. +A shared cast allows authors to convey meaning and intent quickly to readers. +Readers are not required to understand these meanings, however consistent usage can make comprehension faster to achieve. + +This approach is well established in cryptographic literature, where `Alice` and `Bob` are commonly used to describe participants in key exchange protocols. +Within that context, Alice typically initiates the exchange and Bob responds. +Readers familiar with this convention can quickly understand protocol flows without additional explanation. + +In messaging and communication protocols, a similar approach can be helpful, particularly when describing multiple actors and roles required for correct protocol operation. +However, reusing `Alice` and `Bob` in these contexts can introduce ambiguity: + +- In cryptography, Alice is the initiator of a key exchange, but in a communication protocol the initiator role may vary by sub-protocol or phase. +- Complex, multi-step systems may embed multiple cryptographic and application-level processes, each with their own initiator and responder. +- The use of Alice and Bob implicitly frames the discussion as cryptographic, which may be misleading when describing application-level behavior such as message encoding, routing, or reliability. + +For these reasons, when documenting communication protocols that integrate multiple roles and procedures, it is preferable to use a context-specific cast of characters designed for that domain. + +## Guidelines + +### Use of Alice and Bob + +`Alice` and `Bob` SHOULD be used when describing novel cryptographic constructions or key exchange mechanisms that are not embedded within higher-layer communication protocols. +These names are widely understood in cryptographic contexts, and introducing alternatives would reduce clarity. + +Communication protocols may incorporate cryptographic components, but they are not themselves cryptographic key exchanges. +When documenting application-centric or protocol-level processes, the cast defined in this document SHOULD be used instead. +This separation establishes clear contextual boundaries and prepares the reader to reason about different layers independently. + +### Standalone Documents + +Knowledge of this cast MUST NOT be a requirement to understand a given document. +Documents MUST be fully standalone and understandable to first-time readers. + +### Consistency + +Use of the cast is optional. +Characters SHOULD only be used when their presence improves understanding. +Using characters in the wrong context can negatively impact comprehension by implying incorrect information. +It is always acceptable to use other identifiers. + +## Character List + +The following characters are defined for use throughout the documentation of chat protocols. Documentation and examples focus on a portion of a real clients operation for simplicity. Using the character who corresponds to the role or perspective being highlighted, can help convey this information to readers. + +**Saro** +Sender :: +Saro is the participant who sends the first message within a given time window or protocol context. +Saro MAY be the party who initiates a conversation, or simply the first participant to act relative to a defined starting reference. + +**Raya** +Recipient :: +Raya is the participant who receives the first message sent by Saro. +After the initial exchange, Raya MAY send messages and behave as a regular participant in the conversation. +When documenting message receipt or processing, Raya’s perspective SHOULD be used. + +**Pax** +Participant :: +Pax represents an additional member of a conversation, typically in a group context. +Pax is often used when the specific identity or perspective of the participant is not relevant to the discussion. + +## Decision Criteria + +The following criteria SHOULD be applied when considering the introduction of new character names or roles. + +### Clarity + +Names without strong pre-existing associations or implied behavior SHOULD be preferred where possible. + +### Brevity + +Short, easily distinguishable names SHOULD be preferred, provided they do not reduce clarity. + +### Inclusivity + +The cast of characters SHOULD be diverse, culturally neutral, and avoid reinforcing stereotypes. + +### Mnemonic Naming + +Where possible the characters name should hint at their role in order to make them easier to remember. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References + +[A global cast of characters for cryptography](https://github.com/jhaaaa/alix-and-bo) \ No newline at end of file diff --git a/standards/application/OpChan.md b/standards/application/OpChan.md new file mode 100644 index 0000000..29b6eb4 --- /dev/null +++ b/standards/application/OpChan.md @@ -0,0 +1,249 @@ +--- +title: OP-CHAN +name: OpChan Decentralized Forum +status: raw +category: Standards Track +tags: waku +editor: +contributors: + - Jimmy Debe +--- + +## Abstract + +This document specifies the architecture of OpChan, +a decentralized forum application. +The specification is transport-agnostic, +with Waku as the reference delivery mechanism. + +## Background + +In a decentralized forum, content is hosted on multiple nodes, +making it difficult for a user's post to be censored. +Users own their post data, so data cannot be removed by a third party, +and forum boards will not rely on moderators remaining active. + +OpChan clients distribute content through a peer-to-peer network +rather than relying on centralized server storage. +OpChan supports ephemeral anonymous sessions +using a locally generated [ED25519][ed25519] key pair for identity and signing. +Additionally, OpChan supports wallet-backed identities and identity key delegation. + +## Terminology + +- Channel: A discussion board or channel that hosts posts and moderation controls. +- Post: User content created within a forum. +- Comment: A reply to a `Post` or other `Comment` (threaded discussion). +- Participant: Any user able to publish or consume messages (anonymous or + wallet-backed). +- Anonymous session: A client-generated ed25519 keypair used as + identity for a user without a wallet identity. + +## Specification + +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 [RFC 2119][rfc2119]. + +OpChan distributes forum content amongst peers using a publish-subscribe messaging layer. +All messages are cryptographically signed using [ED25519][ed25519] keys generated by the client locally. + +OpChan supports two types of messages, +content and control messages. +Content messages are user-generated content on the forum. +The message types include the following: + +- Channel: Includes the metadata information like name, description, and admins of a forum feed. +- Post: User content created within a channel. +- Comment: Users reply to a post or another comment. +- Vote: To cast upvote or downvote for a post or comment. +- User: Includes username, delegation proofs, and identities. +See the [Identity](#identity) section for more information. +- Bookmark: A user bookmarking a post or comment. + +Control messages consist of the user activity/interactions on the forum. +This includes the management of the current forum state, +permissions, and moderations. +The message types include the following: + +- Create Channel: The initial event of creating a new channel within the forum. +- Delegation Events: Channel admins granting or revoking channel rights. +- Moderation Events: Channel admins are able to hide, remove, pin/unpin a post or comment, + promote new admins, and change the ownership of a channel. + +### Message Format + +Each channel is assigned a unique topic identifier that clients MUST subscribe to +in order to discover messages from that channel. + +All messages MUST include the following envelope fields: + +``` js +{ + "id": "string", + "type": "CHANNEL_CREATED | POST_CREATED | COMMENT_CREATED | VOTE | BOOKMARK | MODERATION | DELEGATION", + "timestamp": "uint64" + "author": "string" // author public key or wallet address + "signature": "bytes" // ed25519 signature + "delegationProof": "bytes" // optional wallet signature authorizing the browser key + "body": object // The message content +} + +``` + +Every message SHOULD be signed using `signature` owned by the publishing user. +Clients SHOULD verify the signature against the `author` public key and, +when present, verify `delegationProof`. + +Signing Flow: + +1. Serialize `body` fields in stable key order. +2. Construct signing bytes with: `type`, `timestamp`, `author` and `body`. +3. Sign with the user's cryptographic keys, `signature`, for the session. + +### Identity + +There are two types of identities for users: +anonymous session and wallet delegation. +A wallet delegation MAY be an ENS (Ethereum Name Service) verified user. +An anonymous session generates an [ED25519][ed25519] keypair locally with the client. +The key is used to sign all messages and +a username MAY be attached to the post or comments. +An anonymous user SHOULD NOT be granted an admin role, +create moderation events, or create a channel. + +A wallet delegation is a user blockchain wallet's private key used to sign a message, +which is the `delegationProof`. +The `delegationProof` SHOULD be a short-lived message, +RECOMMENDED a few minutes to a few hours. +Once a `delegationProof` is generated, +the client SHOULD be able to sign messages, +without the need for repeated wallet prompts requesting to sign. + +#### Delegation Flow + +1. The client generates a new `browserKey`, which is an Ed25519 keypair. +2. The client generates a delegation request to authorize `browserKey` to sign. +3. The user's wallet signs the delegation request and +returns a `delegationProof` with an expiration timestamp, `expiry`. +4. The client stores the `delegationProof`, `browserKey`, +and `expiry`. + +A `delegationProof` could become revoked by the wallet owner or +after the `expiry` time. +If a wallet delegation is revoked, +clients SHOULD ignore subsequent messages from the revoked delegation key. + +### Moderation & Permissions + +A post MAY have moderation message types assigned by the channel admin. +The moderation types include: + +- `HIDE`: Hide a post or comment from the channel feed. +- `REMOVE`: Permanently remove a post or comment. +- `PIN`: Pin a post to the top of a channel feed or pin a comment to the top of a thread. +- `UNPIN`: Remove a `PIN` from a post feed or comment thread. +- `CHANGE_OWNERSHIP`: Change the `author` of a post or comment. + +Moderation messages MUST be signed by an admin, +who is recognized as the `author` of the channel. +Clients SHOULD validate the admin before applying moderation events locally. + +#### User Flagging + +Users MAY flag content for review by moderators. +A `FLAG` is user-initiated and distinct from admin moderation actions. +Flagged content SHOULD be queued for moderator review +but does not automatically result in content removal. + +### Relevance Score + +A post can gain better visibility on the forum channel and +the forum's search through the content relevance score. +Clients with verified wallet identities MUST be favored over an anonymous session identity. + +There are a few RECOMMENDED areas that collect points when calculating the relevance score of a post: + +Basic points include the activities that each user is able to engage in. + +- A channel has a score value of 15 +- Each post within a channel has a score value of 10 +- A base value if comments are present within a post boosts the relevance score by a value of 5 + +Engagement points include the different user activities for each post or comment. + +- Each wallet delegation upvote adds a score value of 1. +- Each individual comment adds a score value of 0.5. +- The total number of posts multiplied by 0.5. +The total number of upvotes multiplied by 0.1. +These two values are added together. + +For identity verification points, +participants of posts or comments that use wallet-based identities, +including an optional ENS, +the score is boosted over the anonymous identities. +If a participant has a verified ENS and a verified connected wallet, +only the ENS multiplier SHOULD be applied. + +- Participants who have a verified ENS name gain a value multiplier of 1.25(25%). +- For wallet connect participant the multiplier is 1.1(10%). +- For verified upvote participants the multiplier is 0.1. +- For verified comment participants the multiplier is 0.05. + +There is a time decay that reduces the relevance score over time. +The older a post or comment was made the lower its score. + +$$ +\text{timeDecayMultiplier} = e^{-\lambda \cdot \text{daysOld}} +$$ + +Where $$\( -\lambda \)$$ is the time-decay rate per day. + +There SHOULD be a moderation penalty that reduces the score when a post or +comment is moderated with a value of 0.5(50%). +This penalty is applied once a post is `HIDDEN`, `REMOVED` or flagged by users to be reviewed by a moderator. + +$$ +\text{moderationPenalty} = \begin{cases} 0.5, & \text{if moderated} \\ +1, & \text{otherwise} \end{cases} +$$ + +Below is the final relevance score based on the RECOMMENDED points above: + +$$ +\text{Total RelevanceScore} = (\text{basic} + \text{engagement} + \text{verifiedUpvote}) +\cdot (1 + \text{verifyIdentity}) \cdot \text{timeDecay} \cdot \text{moderationPenalty} +$$ + +## Waku as Delivery Mechanism + +This section describes how OpChan MAY use the Waku protocol as the delivery mechanism. + +OpChan clients MAY use the [10/WAKU2][waku2] network for the distribution of forum content amongst peers. +The messages are [14/WAKU-MESSAGE][waku-message] objects. +Users SHOULD use the [19/WAKU2-LIGHTPUSH][waku-lightpush] protocol +to send messages to Waku nodes storing the forum's content. + +Message routing and discovery are handled by [23/WAKU2-TOPICS][waku-topics]. +Each channel is assigned a `content_topic` that clients MUST subscribe to +in order to discover messages from that channel. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References + +- [RFC 2119][rfc2119] +- [ED25519][ed25519] +- [10/WAKU2][waku2] +- [14/WAKU-MESSAGE][waku-message] +- [19/WAKU2-LIGHTPUSH][waku-lightpush] +- [23/WAKU2-TOPICS][waku-topics] + +[rfc2119]: https://www.ietf.org/rfc/rfc2119.txt +[ed25519]: https://datatracker.ietf.org/doc/html/rfc8032 +[waku2]: https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md +[waku-message]: https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md +[waku-lightpush]: https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md +[waku-topics]: https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md index 03d4bf6..2f38096 100644 --- a/standards/application/waku-api.md +++ b/standards/application/waku-api.md @@ -24,11 +24,25 @@ contributors: * [Language mappings](#language-mappings) * [Application](#application) * [The Waku API](#the-waku-api) - * [Initialise Waku node](#initialise-waku-node) - * [Type definitions](#type-definitions) - * [Function definitions](#function-definitions) - * [Predefined values](#predefined-values) - * [Extended definitions](#extended-definitions) + * [Common](#common) + * [Common type definitions](#common-type-definitions) + * [Init node](#init-node) + * [Init node type definitions](#init-node-type-definitions) + * [Init node function definitions](#init-node-function-definitions) + * [Init node predefined values](#init-node-predefined-values) + * [Init node extended definitions](#init-node-extended-definitions) + * [Messaging](#messaging) + * [Messaging type definitions](#messaging-type-definitions) + * [Messaging function definitions](#messaging-function-definitions) + * [Messaging extended definitions](#messaging-extended-definitions) + * [Subscriptions](#subscriptions) + * [Subscriptions type definitions](#subscriptions-type-definitions) + * [Subscriptions function definitions](#subscriptions-function-definitions) + * [Subscriptions extended definitions](#subscriptions-extended-definitions) + * [Health](#health) + * [Health type definitions](#health-type-definitions) + * [Health function definitions](#health-function-definitions) + * [Health extended definitions](#health-extended-definitions) * [The Validation API](#the-validation-api) * [Security/Privacy Considerations](#securityprivacy-considerations) * [Copyright](#copyright) @@ -39,10 +53,10 @@ contributors: This document specifies an Application Programming Interface (API) that is RECOMMENDED for developers of the [WAKU2](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/10/waku2.md) clients to implement, and for consumers to use as a single entry point to its functionalities. -This API defines the RECOMMENDED interface for leveraging Waku protocols to send and receive messages. +This API defines the RECOMMENDED interface for leveraging Waku protocols to send and receive messages. Application developers SHOULD use it to access capabilities for peer discovery, message routing, and peer-to-peer reliability. -TODO: This spec must be further extended to include connection health inspection, message sending, subscription and store hash queries. +TODO: This spec must be further extended to include connection health inspection, subscription, and store hash queries. ## Motivation @@ -69,12 +83,13 @@ An alternative would be to choose a programming language. However, such choice m ### Primitive types and general guidelines - No `default` means that the value is mandatory, meaning a `default` value implies an optional parameter. -- Primitive types are `string`, `int`, `bool`, `enum` and `uint` +- Primitive types are `string`, `int`, `bool`, `byte`, `enum` and `uint` - Complex pre-defined types are: - `object`: object and other nested types. - - `array`: iterable object containing values of all the same type. + - `array`: iterable object containing values of all the same type. Syntax: `array` where `T` is the element type (e.g., `array`, `array`). - `result`: an enum type that either contains a value or void (success), or an error (failure); The error is left to the implementor. - `error`: Left to the implementor on whether `error` types are `string` or `object` in the given language. + - `event_emitter`: an object that emits events with specific event names and associated event data types. - Usage of `result` is RECOMMENDED, usage of exceptions is NOT RECOMMENDED, no matter the language. TODO: Review whether to specify categories of errors. @@ -90,11 +105,13 @@ language_mappings: - functions: "camelCase" - variables: "camelCase" - types: "PascalCase" + event_emitter: "Use EventEmitter object with `emit`, `addListener`, etc; with event name the string specified in IDL. For example. eventEmitter.emit('message:sent',...)" nim: naming_convention: - functions: "camelCase" - variables: "camelCase" - types: "PascalCase" + event_emitter: TBD ``` ### Application @@ -109,15 +126,39 @@ library_name: "waku" description: "Waku: a private and censorship-resistant message routing library." ``` -### Initialise Waku node +### Common -#### Type definitions +This section describes common types used throughout the API. + +Note that all types in the API are described once in this document, in a single section. Types should just forward-reference other types when needed. + +#### Common type definitions ```yaml types: + WakuNode: type: object description: "A Waku node instance." + fields: + messageEvents: + type: MessageEvents + description: "The node's messaging event emitter" + healthEvents: + type: HealthEvents + description: "The node's health monitoring event emitter" + + RequestId: + type: string + description: "A unique identifier for a request" +``` + +### Init node + +#### Init node type definitions + +```yaml +types: NodeConfig: type: object @@ -151,6 +192,7 @@ types: description: "The passed nodes are prioritised for store queries." cluster_id: type: uint + description: "The cluster ID for the Waku network. Cluster IDs are defined in [RELAY-SHARDING](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/51/relay-sharding.md) and allocated in [RELAY-STATIC-SHARD-ALLOC](https://github.com/waku-org/specs/blob/master/informational/relay-static-shard-alloc.md)." auto_sharding_config: type: AutoShardingConfig default: DefaultAutoShardingConfig @@ -201,19 +243,20 @@ types: fields: contract_address: type: string - description: "The address of the RLN contract exposes `root` and `getMerkleRoot` ABIs" + description: "The address of the RLN contract that exposes `root` and `getMerkleRoot` ABIs" chain_id: type: uint - description: "The chain id on which the RLN contract is deployed" + description: "The chain ID on which the RLN contract is deployed" epoch_size_sec: type: uint description: "The epoch size to use for RLN, in seconds" ``` -#### Function definitions +#### Init node function definitions ```yaml functions: + createNode: description: "Initialise a Waku node instance" parameters: @@ -224,7 +267,7 @@ functions: type: result ``` -#### Predefined values +#### Init node predefined values ```yaml values: @@ -244,6 +287,7 @@ values: static_store_nodes: [] cluster_id: 1 auto_sharding_config: + type: AutoShardingConfig fields: num_shards_in_cluster: 8 message_validation: TheWakuNetworkMessageValidation @@ -253,6 +297,7 @@ values: fields: max_message_size: "150 KiB" rln_config: + type: RlnConfig fields: contract_address: "0xB9cd878C90E49F797B4431fBF4fb333108CB90e6" chain_id: 59141 @@ -273,7 +318,7 @@ values: rln_config: none ``` -#### Extended definitions +#### Init node extended definitions **`mode`**: @@ -291,7 +336,6 @@ If the `mode` set is `core`, the initialised `WakuNode` SHOULD use: - [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) - [LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) as service node - [FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) as service node -- [PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md) as service node - [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) as client - [METADATA](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/66/metadata.md) as client and service node - [P2P-RELIABILITY](/standards/application/p2p-reliability.md) @@ -302,6 +346,247 @@ If the `mode` set is `core`, the initialised `WakuNode` SHOULD use: `edge` mode SHOULD be used if node functions in resource restricted environment, whereas `core` SHOULD be used if node has no strong hardware or bandwidth restrictions. +### Messaging + +#### Messaging type definitions + +```yaml +types: + + MessageEnvelope: + type: object + fields: + content_topic: + type: string + description: "Content-based filtering field as defined in [TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md#content-topics)" + payload: + type: array + description: "The message data." + ephemeral: + type: bool + default: false + description: "Whether the message is ephemeral. Read at [ATTRIBUTES](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md#message-attributes)" + + MessageReceivedEvent: + type: object + description: "Event emitted when a message is received from the network" + fields: + message: + type: MessageEnvelope + description: "The received message's payload and metadata" + + MessageSentEvent: + type: object + description: "Event emitted when a message is sent to the network" + fields: + request_id: + type: RequestId + description: "The request ID associated with the sent message" + message_hash: + type: string + description: "Hash of the message that got sent to the network" + + MessageSendErrorEvent: + type: object + description: "Event emitted when a message send operation fails" + fields: + request_id: + type: RequestId + description: "The request ID associated with the failed message" + message_hash: + type: string + description: "Optional property. Hash of the message that got error" + error: + type: string + description: "Error message describing what went wrong" + + MessageSendPropagatedEvent: + type: object + description: "Confirmation that a message has been correctly delivered to some neighbouring nodes." + fields: + request_id: + type: RequestId + description: "The request ID associated with the propagated message in the network" + message_hash: + type: string + description: "Hash of the message that got propagated within the network" + + MessageEvents: + type: event_emitter + description: "Event source for message-related events" + events: + "message:received": + type: MessageReceivedEvent + "message:sent": + type: MessageSentEvent + "message:send-error": + type: MessageSendErrorEvent + "message:send-propagated": + type: MessageSendPropagatedEvent +``` + +#### Messaging function definitions + +```yaml +functions: + + send: + description: "Send a message through the network." + parameters: + - name: message + type: MessageEnvelope + description: "Parameters for sending the message." + returns: + type: result +``` + +#### Messaging extended definitions + +A first `message` sent with a certain `contentTopic` SHOULD trigger a subscription for such `contentTopic` as described in the `Subscriptions` section. + +The node uses [P2P-RELIABILITY](/standards/application/p2p-reliability.md) strategies to ensure message delivery. + +### Subscriptions + +#### Subscriptions type definitions + +```yaml +types: + + SubscriptionError: + type: object + description: "A content topic subscription-related operation failed synchronously and irremediably" + fields: + content-topic: + type: string + description: "Content topic that the node failed to subscribe to or unsubscribe from" + error: + type: string + description: "Error message describing what went wrong" +``` + +#### Subscriptions function definitions + +```yaml +functions: + + subscribe: + description: "Subscribe to specific content topics" + parameters: + - name: contentTopics + type: Array + description: "The content topics for the node to subscribe to." + returns: + type: result> + + unsubscribe: + description: "Unsubscribe from specific content topics" + parameters: + - name: contentTopics + type: Array + description: "The content topics for the node to unsubscribe from." + returns: + type: result> +``` + +#### Subscriptions extended definitions + +**`mode`**: + +If the `mode` set is `edge`, `subscribe` SHOULD trigger set up a subscription using [FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) as client and [P2P-RELIABILITY](/standards/application/p2p-reliability.md). + +If the `mode` set is `core`, `subscribe` SHOULD trigger set up a subscription using [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) and [P2P-RELIABILITY](/standards/application/p2p-reliability.md). +This MAY trigger joining a new shard if not already set. + +Only messages on subscribed content topics SHOULD be emitted by a `MessageEvents` event source, meaning messages received via `RELAY` SHOULD be filtered by content topics before emission. + +**`error`**: + +Only irremediable failures should lead to synchronously returning a subscription error for failed subscribe or unsubscribe operations. + +Failure to reach nodes can be omitted, and should be handled via the health events; +[P2P-RELIABILITY](/standards/application/p2p-reliability.md) SHOULD handle automated re-subscriptions and redundancy. + +Examples of irremediable failures are: + +- Invalid content topic format +- Exceeding number of content topics +- Node not started +- Already unsubscribed +- Other node-level configuration issue + +### Health + +#### Health type definitions + +```yml +types: + + ConnectionStatus: + type: enum + values: [Disconnected, PartiallyConnected, Connected] + description: "Used to identify health of the operating node" + + HealthConnectionStatusEvent: + type: object + description: "Event emitted when the overall node health status changes" + fields: + connection-status: + type: ConnectionStatus + description: "The node's new connection status" + + HealthEvents: + type: event_emitter + description: "Event source for health-related events." + events: + "health:connection-status": + type: HealthConnectionStatusEvent +``` + +#### Health function definitions + +TODO + +#### Health extended definitions + +`Disconnected` indicates that the node has lost connectivity for message reception, +sending, or both, and as a result, it cannot reliably receive or transmit messages. + +`PartiallyConnected` indicates that the node meets the minimum operational requirements: +it is connected to at least one peer with a protocol to send messages ([LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md)), +one peer with a protocol to receive messages ([FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) or [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md)), +and one peer with [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) service capabilities, +although performance or reliability may still be impacted. + +`Connected` indicates that the node is operating optimally, +with full support for message reception and transmission. + +### Debug + +#### Debug function definitions + +```yaml +functions: + getAvailableNodeInfoIds: + description: "Returns a list of available node information identifiers. e.g., [ version, my_peer_id, metrics ]." + returns: + type: result, error> + + getNodeInfo: + description: "Returns the JSON formatted node's information that is requested. Expect single value or list results depending on requested information." + parameters: + - name: nodeInfoId + type: string + description: "Information identifier. The only supported values are the ones returned by getAvailableNodeInfoItems function." + returns: + type: result + + getAvailableConfigs: + description: "Returns a list of all available options, their description and default values." + returns: + type: string +``` + ## The Validation API [WAKU2-RLN-RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md) is currently the primary message validation mechanism in place. diff --git a/standards/core/mix.md b/standards/core/mix.md index f75d851..e00264c 100644 --- a/standards/core/mix.md +++ b/standards/core/mix.md @@ -1,10 +1,10 @@ --- title: WAKU-MIX name: Waku Mix -editor: Prem Chaitanya Prathi +editor: Prem Chaitanya Prathi contributors: - - Akshaya Mani - - Hanno Cornelius + - Akshaya Mani + - Hanno Cornelius --- ## Tags @@ -12,7 +12,8 @@ contributors: `waku/core-protocol` # Abstract -The document describes [libp2p mix](https://rfc.vac.dev/vac/raw/mix/) integration into waku. + +The document describes [libp2p mix](https://lip.logos.co/ift-ts/raw/mix.html) integration into waku. This integration provides higher anonymity for users publishing or querying for messages to/from the Waku network. This document covers integration of mix with [lightpush](https://rfc.vac.dev/waku/standards/core/19/lightpush) and [store](https://rfc.vac.dev/waku/standards/core/13/store) protocols. @@ -38,6 +39,7 @@ This network of mix nodes SHALL relay mix messages anonymously to the recepient. Anonymity of [Filter](https://rfc.vac.dev/waku/standards/core/12/filter) users is not addressed by this document. ## Terminology + The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119.txt). @@ -79,15 +81,18 @@ Resource-restricted/Edge nodes with short connection windows MUST _only_ act as Each waku node that supports the `mix intermediary or exit role` SHOULD indicate the same in its discoverable [ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md). The following fields MUST be set as part of the discoverable ENR of a mix waku node: + - The `bit 5` in the [waku2 ENR key](https://github.com/waku-org/specs/blob/master/standards/core/enr.md#waku2-enr-key) is reserved to indicate `mix` support. This bit MUST be set to true to indicate `mix` support. - A new field `mix-key` SHOULD be set to the `ed25519 public key` which is used for sphinx encryption. -Adding these fields to the ENR may cause the ENR size to cross the 300 byte limit especially in case a node supports multiple transports. +Adding these fields to the ENR may cause the ENR size to cross the 300 byte limit especially in case a node supports multiple transports. This limitation will have to be addressed in future. + ### Discovery Mix protocol provides better anonymity when a sender node has a sufficiently large pool of mix nodes to do path selection. This moves the problem into discovery domain and requires the following from discovery mechanisms: + 1. It is important for nodes to be able to discover as many nodes as possible quickly. This becomes especially important for edge nodes that come online just to publish/query messages for a short period of time. 2. The discovery mechanism MUST be unbiased and not biased toward specific subsets (e.g., nodes that are topologically closer). 3. It is important to have the most recent online status of the nodes so that mix paths that are selected are not broken which lead to reliability issues. @@ -101,15 +106,16 @@ Mix protocol in waku network SHOULD have `rate-limiting/spam` protection to hand 1. Any node can generate a mix packet and publish into the mix network. Hence there needs to be some validation as to who is allowed to publish and whether the user is within allowed rate-limits. 2. Any node can intentionally generate paths which are broken and send messages into the mix network. -3. An attacker can spawn a huge number of mix nodes so that user behaviour is observed in order to determine traffic patterns and deanonymize users. +3. An attacker can spawn a huge number of mix nodes so that user behaviour is observed in order to determine traffic patterns and deanonymize users. -There is a need to enforce rate-limits and spam protect the mix network. +There is a need to enforce rate-limits and spam protect the mix network. The rate-limiting and spam protection shall be addressed as part of future work. ## Tradeoffs Using `mix` protocol for publishing and querying messages adds certain overhead which is primarily the delay in delivering message to the destination. The overall additional delay `D` depends on the following params: + - path length `L` - delay added by each intermediary node `dm` - connection establishment time `dc` @@ -129,8 +135,9 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). ## References - - [libp2p mix](https://rfc.vac.dev/vac/raw/mix/) - - [waku lightpush](https://rfc.vac.dev/waku/standards/core/19/lightpush) - - [waku relay](https://rfc.vac.dev/waku/standards/core/11/relay) - - [ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md) - - [sphinx encryption](https://cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf) \ No newline at end of file + +- [libp2p mix](https://lip.logos.co/ift-ts/raw/mix.html) +- [waku lightpush](https://rfc.vac.dev/waku/standards/core/19/lightpush) +- [waku relay](https://rfc.vac.dev/waku/standards/core/11/relay) +- [ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md) +- [sphinx encryption](https://cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf) diff --git a/standards/core/rendezvous.md b/standards/core/rendezvous.md index 6a42abd..292be4c 100644 --- a/standards/core/rendezvous.md +++ b/standards/core/rendezvous.md @@ -1,66 +1,121 @@ --- title: WAKU-RENDEZVOUS name: Waku Rendezvous discovery -editor: Simon-Pierre Vivier -contributors: +editor: Prem Chaitanya Prathi +contributors: Simon-Pierre Vivier --- ## Abstract + This document describes the goal, -strategy and usage of the libp2p rendezvous protocol by Waku. +strategy, usage, and changes to the libp2p rendezvous protocol by Waku. Rendezvous is one of the discovery methods that can be used by Waku. It supplements Discovery v5 and Waku peer exchange. ## Background and Rationale -How do new nodes join the network is the question that discovery answers. -Discovery must be fast, pertinent and resilient to attacks. -Rendezvous is both fast and allow the discovery of relevant peers, -although it design can be easily abused -due to it's lack of protection against denial of service atacks. -The properties of rendezvous complements well the slower but safer methods like Discv5. -To contribute well, a Waku node must know a sufficient number of peers with -a wide variety of capabilities. -By using rendezvous in combination with -[Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md#node-discovery-protocol-v5) and -[34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md#abstract), -Waku nodes will reach a good number of meaningful peers -faster than through a single discovery method. + +Waku needs discovery mechanism(s) that are both rapid and robust against attacks. +Fully centralised discovery (such as DNS lookup) may be fast but is not secure. +Fully decentralised discovery (such as discv5) may be robust, but too slow for some bootstrapping use cases +Rendezvous provides a limited, balanced solution that trades off some robustness for speed. +It's meant to complement not replaced fully decentralised discovery mechanisms, like discv5 + +By combining rendezvous with +[Discv5](https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/discv5/discv5.md#node-discovery-protocol-v5) and +[34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/dd397adc594c121ce3e10b7e81b5c2ed4818c0a6/waku/standards/core/34/peer-exchange.md#abstract), +Waku nodes can more quickly reach a meaningful set of peers +than by relying on a single discovery method. ## Semantics -Waku rendezvous fully inherits the [libp2p rendezvous semantics](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#rendezvous-protocol). + +Waku rendezvous extends the [libp2p rendezvous semantics](https://github.com/libp2p/specs/blob/69c4fdf5da3a07d2f392df6a892c07256c1885c0/rendezvous/README.md#rendezvous-protocol) by using `WakuPeerRecord` instead of the standard libp2p `PeerRecord`. +This allows nodes to advertise additional Waku-specific metadata beyond what is available in the standard libp2p peer record. ## Specifications -The namespaces used to register and request MUST be in the format `rs/cluster-id/shard`. -Refer to [RELAY-SHARDING](https://github.com/waku-org/specs/blob/master/standards/core/relay-sharding.md) for cluster and shard information. -Every [Waku Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) node SHOULD be initialized as a rendezvous point. +**Libp2p Protocol identifier**: `/vac/waku/rendezvous/1.0.0` + +### Wire Protocol + +Nodes advertise their information through `WakuPeerRecord`, a custom peer record structure designed for Waku rendezvous. +Since this is a customPeerRecord, we define a private multicodec value of `0x300000` as per [multicodec table](https://github.com/multiformats/multicodec/blob/0c6c7d75f1580af329847dbc9900859a445ed980/table.csv). +The `WakuPeerRecord` is defined as follows: + +**WakuPeerRecord fields:** + +- `peer_id`: The libp2p PeerId of the node. +- `seqNo`: The time at which the record was created or last updated (Unix epoch, seconds). +- `multiaddrs`: A list of multiaddresses for connectivity. +- `mix_public_key`: The Mix protocol public key (only present for nodes supporting Mix). + +**Encoding:** +WakuPeerRecord is encoded as a protobuf message. The exact schema is: + +```protobuf +message WakuPeerRecord { + string peer_id = 1; + uint64 seqNo = 2; + repeated string multiaddrs = 3; + optional bytes mix_public_key = 4; +} +``` + +When a node discovers peers through rendezvous, it receives the complete `WakuPeerRecord` for each peer, allowing it to make informed decisions about which peers to connect to based on their advertised information. + +### Namespace Format + +The [rendezvous namespaces](https://github.com/libp2p/specs/blob/69c4fdf5da3a07d2f392df6a892c07256c1885c0/rendezvous/README.md#the-protocol) used to register and request peer records +MUST be in the format `rs//`. +`` is a string representing the individual capability for which a discoverable Waku peer record is registered. +The Waku peer record is separately registered against each capability for which discovery is desired. +The only defined capability for now is `mix`, representing [Waku Mix](https://github.com/waku-org/specs/blob/fe5cfdf823085b8c9560df81b38bc342d6b1cb38/standards/core/mix.md) support. +For example, a Waku peer record for a node supporting mix protocol in cluster `1` will be registered against a namespace: `rs/1/mix`. + +This allows for discovering peers with specific capabilities within a given cluster. +Currently, this is used for Mix protocol discovery where the capability field specifies `mix`. + +Refer to [RELAY-SHARDING](https://github.com/waku-org/specs/blob/fe5cfdf823085b8c9560df81b38bc342d6b1cb38/standards/core/relay-sharding.md) for cluster information. + +### Registration and Discovery + +Every [Waku Relay](https://github.com/vacp2p/rfc-index/blob/dd397adc594c121ce3e10b7e81b5c2ed4818c0a6/waku/standards/core/11/relay.md) node SHOULD be initialized as a rendezvous point. Each relay node that participates in discovery MUST register with random rendezvous points at regular intervals. +The RECOMMENDED registration interval is 10 seconds. -We RECOMMEND a registration interval of 10 seconds. -The node SHOULD register once for every shard it supports, -registering only the namespace corresponding to that shard. +All relay nodes participating in rendezvous discovery SHOULD advertise their information using `WakuPeerRecord`. For nodes supporting the Mix protocol, the `mix_public_key` field MUST be included. +All advertised records MUST conform to the `WakuPeerRecord` definition. -We RECOMMEND that rendezvous points expire registrations after 1 minute, -in order to keep discovered peer records to those recentrly online. +It is RECOMMENDED that rendezvous points expire registrations after 1 minute (60 seconds TTL) +to keep discovered peer records limited to those recently online. -At startup, every Waku node SHOULD discover peers by -sending requests to random rendezvous points, -once for each shard it supports. +At startup, every Waku node supporting Mix SHOULD discover peers by +sending requests to random rendezvous points for the Mix capability namespace. -We RECOMMEND a maximum of 12 peers will be requested each time. -This number is enough for good GossipSub connectivity and -minimize the load on rendezvous points. +It is RECOMMENDED a maximum of 12 peers be requested each time. +This number is sufficient for good GossipSub connectivity and +minimizes the load on rendezvous points. -We RECOMMEND that bootstrap nodes participate in rendezvous discovery and -that other discovery methods are used in conjunction and +### Operational Recommendations + +It is RECOMMENDED that bootstrap nodes participate in rendezvous discovery and +that other discovery methods are used in conjunction and continue discovering peers for the lifetime of the local node. +For resource-constrained devices or light clients, a client-only mode MAY be used +where nodes only query for peers without acting as rendezvous points themselves +and without advertising their own peer records. + ## Future Work -Namespaces will not contain capabilities yet but may in the future. If the need arise nodes could use rendezvous to discover peers with specific capabilities. +The protocol currently supports advertising Mix-specific capabilities (Mix public keys) through `WakuPeerRecord`. +Future enhancements could include: + +- Extending `WakuPeerRecord` to advertise other Waku protocol capabilities (Relay, Store, Filter, Lightpush, etc.) +- Supporting shard-based namespaces (e.g., `rs//`) for general relay peer discovery without capability filtering +- Batch registration support allowing nodes to register across multiple namespaces in a single request # Copyright @@ -68,7 +123,9 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). # References - - [Discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md#node-discovery-protocol-v5) - - [34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md#abstract) - - [Libp2p Rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README.md#rendezvous-protocol) - - [Relay](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) + +- [Discv5](https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/discv5/discv5.md#node-discovery-protocol-v5) +- [ENR](https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/enr.md) +- [34/WAKU2-PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/dd397adc594c121ce3e10b7e81b5c2ed4818c0a6/waku/standards/core/34/peer-exchange.md#abstract) +- [Libp2p Rendezvous](https://github.com/libp2p/specs/blob/69c4fdf5da3a07d2f392df6a892c07256c1885c0/rendezvous/README.md#rendezvous-protocol) +- [Relay](https://github.com/vacp2p/rfc-index/blob/dd397adc594c121ce3e10b7e81b5c2ed4818c0a6/waku/standards/core/11/relay.md)