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