logos-messaging/specs
1
0
Fork 0
mirror of https://github.com/logos-messaging/specs.git synced 2026-04-03 12:53:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' of github.com:waku-org/specs into jazzz/chatdefs

Browse Source
This commit is contained in:
Jazz Turner-Baggs 2026-03-04 11:02:54 +00:00
commit b1b7237560
No known key found for this signature in database
7 changed files with 883 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
.wordlist.txt
View File

@ -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

1
README.md
View File

@ -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

104
informational/chat_cast.md Normal file
View File

@ -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 <jazz@status.im>
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)

249
standards/application/OpChan.md Normal file
View File

@ -0,0 +1,249 @@
---
title: OP-CHAN
name: OpChan Decentralized Forum
status: raw
category: Standards Track
tags: waku
editor:
contributors:
- Jimmy Debe <jimmy@status.im>
---
## 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

319
standards/application/waku-api.md
View File

@ -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<T>` where `T` is the element type (e.g., `array<string>`, `array<byte>`).
- `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<WakuNode, error>
```
#### 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<byte>
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<RequestId, error>
```
#### 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<string>
description: "The content topics for the node to subscribe to."
returns:
type: result<void, array<SubscriptionError>>
unsubscribe:
description: "Unsubscribe from specific content topics"
parameters:
- name: contentTopics
type: Array<ContentTopic>
description: "The content topics for the node to unsubscribe from."
returns:
type: result<void, array<SubscriptionError>>
```
#### 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<array<string>, 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<string, error>
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.

31
standards/core/mix.md
View File

@ -1,10 +1,10 @@
---
title: WAKU-MIX
name: Waku Mix
editor: Prem Chaitanya Prathi <premprathi@proton.me>
editor: Prem Chaitanya Prathi <prem@status.im>
contributors:
- Akshaya Mani <akshaya@status.im>
- Hanno Cornelius <hanno@status.im>
- Akshaya Mani <akshaya@status.im>
- Hanno Cornelius <hanno@status.im>
---
## 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)
- [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)

133
standards/core/rendezvous.md
View File

@ -1,66 +1,121 @@
---
title: WAKU-RENDEZVOUS
name: Waku Rendezvous discovery
editor: Simon-Pierre Vivier <simvivier@status.im>
contributors:
editor: Prem Chaitanya Prathi <premprathi@proton.me>
contributors: Simon-Pierre Vivier <simvivier@status.im>
---
## 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/<cluster-id>/<capability>`.
`<capability>` 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/<cluster-id>/<shard>`) 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)