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

chore: address review feedback for OpChan RFC

Browse Source 
- Make spec transport-agnostic, add "Waku as Delivery Mechanism" section
- Remove platform-specific language (web application)
- Add ED25519 reference link (RFC 8032)
- Clarify FLAGGED (user-initiated) vs admin moderation
- Fix typo delegrationProof -> delegationProof
- Use reference-style links for cleaner body text
- Fix linting issues (trailing spaces, list markers)
This commit is contained in:
Cofson 2026-02-05 18:53:03 +01:00
parent de0720a38c
commit ea0b56ed07
No known key found for this signature in database
GPG Key ID: 4698A1B5A5ECBE2C
1 changed files with 76 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
standards/application/OpChan.md
View File

@ -4,15 +4,17 @@ name: OpChan Decentralized Forum
status: raw status: raw
category: Standards Track category: Standards Track
tags: waku tags: waku
editor: editor:
contributors: contributors:
- Jimmy Debe <jimmy@status.im> - Jimmy Debe <jimmy@status.im>
--- ---
## Abstract ## Abstract
This document specifies the architecture of OpChan. This document specifies the architecture of OpChan,
OpChan is a decentralized forum application built on the Waku protocol. a decentralized forum application.
The specification is transport-agnostic,
with Waku as the reference delivery mechanism.
## Background ## Background
@ -21,16 +23,11 @@ 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, Users own their post data, so data cannot be removed by a third party,
and forum boards will not rely on moderators remaining active. and forum boards will not rely on moderators remaining active.
OpChan is a web application hosted by some party through a web server. OpChan clients distribute content through a peer-to-peer network
The content being published by users is not stored by the server, rather than relying on centralized server storage.
but by distributing the messages peer to peer. OpChan supports ephemeral anonymous sessions
OpChan supports ephemeral anonymous web sessions, using a locally generated [ED25519][ed25519] key pair for identity and signing.
supporting a locally generated ED25519 key pair for identity and Additionally, OpChan supports wallet-backed identities and identity key delegation.
signing.
Wallet-backed identities, identity key delegation, and
content stored locally while distributing messages using the [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) protocol.
- WAKU-LIGHTPUSH
## Terminology ## Terminology
@ -44,21 +41,18 @@ content stored locally while distributing messages using the [10/WAKU2](https://
## Specification ## Specification
The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
“OPTIONAL” in this document are to be interpreted as described in [2119](https://www.ietf.org/rfc/rfc2119.txt). "OPTIONAL" in this document are to be interpreted as described in [RFC 2119][rfc2119].
OpChan uses the [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md) OpChan distributes forum content amongst peers using a publish-subscribe messaging layer.
network for the distribution of forum content amongst peers. All messages are cryptographically signed using [ED25519][ed25519] keys generated by the client locally.
The messages, which are [14/WAKU-MESSAGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md) objects,
are cryptographically signed using Ed25519 keys generated by the client locally.
Users SHOULD use the [19WAKU2-LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) protocol to send messages to Waku nodes storing the forum's content.
OpChan supports two types of messages, OpChan supports two types of messages,
content and control messages. content and control messages.
Content messages are user-generated content on the forum. Content messages are user-generated content on the forum.
The message types include the following: The message types include the following:
- Channel: Includes the metadata information like name, description, and admins of a forum feed. - Channel: Includes the metadata information like name, description, and admins of a forum feed.
- Post: User content created within a channel. - Post: User content created within a channel.
- Comment: Users reply to a post or another comment. - Comment: Users reply to a post or another comment.
@ -72,23 +66,21 @@ This includes the management of the current forum state,
permissions, and moderations. permissions, and moderations.
The message types include the following: The message types include the following:
- Create Channel: The initial event of creating a new channel within the forum. - Create Channel: The initial event of creating a new channel within the forum.
- Delegation Events: Channel admins granting or revoking channel rights. - Delegation Events: Channel admins granting or revoking channel rights.
- Moderation Events: Channel admins are able to hide, remove, and - Moderation Events: Channel admins are able to hide, remove, pin/unpin a post or comment,
pin/unpin a post or comment. promote new admins, and change the ownership of a channel.
Also, it can promote new admins and change the ownership of a channel.
### Message Format ### Message Format
Message routing and Each channel is assigned a unique topic identifier that clients MUST subscribe to
discovery are handled by [23/WAKU2-TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md). in order to discover messages from that channel.
Each content is assigned a `pubsub_topic` that clients MUST subscribe to discovery messages from the channel.
All messages transmitted over the Waku network MUST include the following envelope fields: All messages MUST include the following envelope fields:
``` js ``` js
{ {
"id": "string", "id": "string",
"type": "CHANNEL_CREATED | POST_CREATED | COMMENT_CREATED | VOTE | BOOKMARK | MODERATION | DELEGATION", "type": "CHANNEL_CREATED | POST_CREATED | COMMENT_CREATED | VOTE | BOOKMARK | MODERATION | DELEGATION",
"timestamp": "uint64" "timestamp": "uint64"
"author": "string" // author public key or wallet address "author": "string" // author public key or wallet address
@ -111,24 +103,24 @@ Signing Flow:
### Identity ### Identity
There are two types of identities for users, There are two types of identities for users:
anonymous session and wallet delegation. anonymous session and wallet delegation.
A wallet delegation MAY be an ENS(Ethereum Name Service) verified user. A wallet delegation MAY be an ENS (Ethereum Name Service) verified user.
An anonymous session generates an Ed25519 keypair locally with the client. An anonymous session generates an [ED25519][ed25519] keypair locally with the client.
The key is used to sign all messages and The key is used to sign all messages and
a username MAY choose a username attached to the post or comments. a username MAY be attached to the post or comments.
An anonymous user SHOULD NOT be granted an admin role, An anonymous user SHOULD NOT be granted an admin role,
create moderation events, or create a channel. create moderation events, or create a channel.
A wallet delegation is a user blockchain wallet's private key used to sign a message, A wallet delegation is a user blockchain wallet's private key used to sign a message,
which is the `delegationProof`. which is the `delegationProof`.
The `delegationProof` SHOULD be a short-lived message, The `delegationProof` SHOULD be a short-lived message,
RECOMMENDED a few minutes to a few hours. RECOMMENDED a few minutes to a few hours.
Once a `delegationProof` is generated, Once a `delegationProof` is generated,
the client SHOULD be able to sign messages, the client SHOULD be able to sign messages,
without the need for repeated wallet prompts requesting to sign. without the need for repeated wallet prompts requesting to sign.
#### Delegation Flow: #### Delegation Flow
1. The client generates a new `browserKey`, which is an Ed25519 keypair. 1. The client generates a new `browserKey`, which is an Ed25519 keypair.
2. The client generates a delegation request to authorize `browserKey` to sign. 2. The client generates a delegation request to authorize `browserKey` to sign.
@ -137,26 +129,33 @@ returns a `delegationProof` with an expiration timestamp, `expiry`.
4. The client stores the `delegationProof`, `browserKey`, 4. The client stores the `delegationProof`, `browserKey`,
and `expiry`. and `expiry`.
A `delegrationProof` could become revoked by the wallet owner or A `delegationProof` could become revoked by the wallet owner or
after the `expiry` time. after the `expiry` time.
If a wallet delegation is revoked, If a wallet delegation is revoked,
clients SHOULD ignore subsequent messages from the revoked delegation key. clients SHOULD ignore subsequent messages from the revoked delegation key.
### Moderation & Permissions ### Moderation & Permissions
A post MAY be have moderation message types assigned by the channel admin. A post MAY have moderation message types assigned by the channel admin.
The moderation types include: The moderation types include:
- `HIDE` : To hide a post or comment. - `HIDE`: Hide a post or comment from the channel feed.
- `REMOVE` : To permanently remove a post or comment. - `REMOVE`: Permanently remove a post or comment.
- `PIN` : To pin a post to the top of a channel feed or pin a comment to the top of a thread. - `PIN`: Pin a post to the top of a channel feed or pin a comment to the top of a thread.
- `UNPIN` : To remove a `PIN` from a post feed or comment thread. - `UNPIN`: Remove a `PIN` from a post feed or comment thread.
- `CHANGE_OWNERSHIP` : Change the `author` of a post or comment. - `CHANGE_OWNERSHIP`: Change the `author` of a post or comment.
Moderation messages MUST be signed by an admin, Moderation messages MUST be signed by an admin,
which recognized the `author` of the channel. who is recognized as the `author` of the channel.
Clients SHOULD validate the admin before applying moderation events locally. 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 ### Relevance Score
A post can gain better visibility on the forum channel and A post can gain better visibility on the forum channel and
@ -204,7 +203,7 @@ There SHOULD be a moderation penalty that reduces the score when a post or
comment is moderated with a value of 0.5(50%). 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. 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} \\ \text{moderationPenalty} = \begin{cases} 0.5, & \text{if moderated} \\
1, & \text{otherwise} \end{cases} 1, & \text{otherwise} \end{cases}
$$ $$
@ -216,13 +215,35 @@ $$
\cdot (1 + \text{verifyIdentity}) \cdot \text{timeDecay} \cdot \text{moderationPenalty} \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
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
## References ## References
- [10/WAKU2](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/10/waku2.md)
- [19WAKU2-LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) - [RFC 2119][rfc2119]
- [14/WAKU-MESSAGES](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/14/message.md) - [ED25519][ed25519]
- [23/WAKU2-TOPICS](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md) - [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