From cd581a887128dbf63e2afa0165941807e943303f Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Fri, 19 Sep 2025 08:56:00 -0700 Subject: [PATCH 01/14] Add template --- standards/application/chatdefs.md | 97 +++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 standards/application/chatdefs.md diff --git a/standards/application/chatdefs.md b/standards/application/chatdefs.md new file mode 100644 index 0000000..91c238a --- /dev/null +++ b/standards/application/chatdefs.md @@ -0,0 +1,97 @@ +--- +title: CHAT_DEF +name: Shared definitions for Chat Protocols +category: Informational +tags: definitions, terminology, reference +editor: Jazzz +contributors: +--- + +## Abstract + +This specification establishes a common vocabulary and standardized definitions for terms used across chat protocol specifications. It serves as a normative reference to ensure consistent interpretation of terminology across application level specifications. + +## Background / Rationale / Motivation + +Chat protocol specifications often employ similar terminology with subtle but important semantic differences. The absence of standardized definitions leads to ambiguity in specification interpretation and implementation inconsistencies across different protocol variants. + +Establishing a shared definitions document provides several benefits: + +1. **Semantic Consistency**: Ensures uniform interpretation of common terms across multiple specifications +2. **Implementation Clarity**: Reduces ambiguity for protocol implementers +3. **Specification Quality**: Enables more precise and concise specification language through reference to established definitions +4. **Ecosystem Coherence**: Promotes consistent understanding within the chat protocol ecosystem. + +This specification provides normative definitions that other chat protocol specifications MAY reference to establish precise semantic meaning for common terminology. + +## Theory / Semantics + +### Definition Categories + +Terms are organized into the following categories for clarity and ease of reference: + +- **Roles**: Defined entity types that determine how a participant behaves within a communication protocol. +- **Message Types**: Classifications and categories of protocol messages +- **Transports**: Abstract methods of transmitting payloads +## Definitions + +### Accounts + Identity + +### Roles + +**Sender**: [TODO] + +**Recipient**: [TODO] + +**Participant**: [TODO] + +**Operator**: [TODO] + +### Message Types + +**Payload**: [TODO] + +**Frame**: [TODO] + +**Content**: [TODO] + +**ContentType**: [TODO] + +**Delivery Acknowledgement**: [TODO] + +**Invite**: [TODO] + + +### Transports + +**Out of Band**: [TODO] + +**Delivery Service**: [TODO] + + +### TBD + +**Client**: [TODO] + +**Application**: [TODO] + + + + +## Wire Format Specification / Syntax + +This specification does not define wire format elements. All definitions are semantic and apply to the interpretation of terms used in other specifications that do define wire formats. + +## Security/Privacy Considerations + +This specification defines terminology only and does not introduce security or privacy considerations beyond those present in specifications that reference these definitions. + +The definitions provided in this specification do not alter the security or privacy properties of implementations that adopt the defined terminology. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References + +[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. \ No newline at end of file From 58bfa54427163568c340b590c69daf896018e141 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 25 Sep 2025 09:33:58 -0700 Subject: [PATCH 02/14] relocate to informational folder --- {standards/application => informational}/chatdefs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename {standards/application => informational}/chatdefs.md (99%) diff --git a/standards/application/chatdefs.md b/informational/chatdefs.md similarity index 99% rename from standards/application/chatdefs.md rename to informational/chatdefs.md index 91c238a..9457448 100644 --- a/standards/application/chatdefs.md +++ b/informational/chatdefs.md @@ -1,5 +1,5 @@ --- -title: CHAT_DEF +title: CHAT-DEFINITIONS name: Shared definitions for Chat Protocols category: Informational tags: definitions, terminology, reference From da323c9c17df83f707a92c46e5376a3cb66eda0e Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 25 Sep 2025 17:22:12 -0700 Subject: [PATCH 03/14] Updated roles --- informational/chatdefs.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/informational/chatdefs.md b/informational/chatdefs.md index 9457448..1e04766 100644 --- a/informational/chatdefs.md +++ b/informational/chatdefs.md @@ -39,21 +39,19 @@ Terms are organized into the following categories for clarity and ease of refere ### Roles -**Sender**: [TODO] +**Sender**: A client which is pushing a payload on to the network, to one or more recipients. -**Recipient**: [TODO] +**Recipient**: A client which is the intended receiver of a payload. In a group context there maybe multiple recipients -**Participant**: [TODO] - -**Operator**: [TODO] +**Participant**: A generic term for the rightful members of a conversation. Senders and Recipients are roles that participants can hold. ### Message Types -**Payload**: [TODO] +**Payload**: The encoded bytes as produced by a chat protocol. The term `message` is avoided due to conlicts with other layers. **Frame**: [TODO] -**Content**: [TODO] +**Content**: The information that is intended for end-users or applications. This is in contrast with a `frame` which is **ContentType**: [TODO] From f9b946498876ebc2f8950753ad22b8f57d938752 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Thu, 25 Sep 2025 22:19:43 -0700 Subject: [PATCH 04/14] Update message types --- informational/chatdefs.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/informational/chatdefs.md b/informational/chatdefs.md index 1e04766..d66904c 100644 --- a/informational/chatdefs.md +++ b/informational/chatdefs.md @@ -49,13 +49,13 @@ Terms are organized into the following categories for clarity and ease of refere **Payload**: The encoded bytes as produced by a chat protocol. The term `message` is avoided due to conlicts with other layers. -**Frame**: [TODO] +**Frame**: A datastructure which is required to implement a chat protocol. Frames are used to disambiguate the objects defined by chat protocols from transport 'messages' and application `content`. -**Content**: The information that is intended for end-users or applications. This is in contrast with a `frame` which is +**Content**: The data that is intended for end-users or applications. Chat protocols transmit and route content between clients. -**ContentType**: [TODO] +**ContentType**: The structured format of content. These datastructures represent specific encodings of Text, Image, Audio data. -**Delivery Acknowledgement**: [TODO] +**Delivery Acknowledgement**: A notification from a receiving client to sender that their message was successfully received. While similar to a read-receipt delivery acknowledgements differ in that the acknowledgement originates based on the client, where read-receipts are fired when they are displayed to a user. **Invite**: [TODO] From c02bdb32c9c465be3444c1c07eb33d9a7acf4fff Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Fri, 26 Sep 2025 07:11:53 -0700 Subject: [PATCH 05/14] Updated definitions for OOB, client, app --- informational/chatdefs.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/informational/chatdefs.md b/informational/chatdefs.md index d66904c..d27960c 100644 --- a/informational/chatdefs.md +++ b/informational/chatdefs.md @@ -57,22 +57,19 @@ Terms are organized into the following categories for clarity and ease of refere **Delivery Acknowledgement**: A notification from a receiving client to sender that their message was successfully received. While similar to a read-receipt delivery acknowledgements differ in that the acknowledgement originates based on the client, where read-receipts are fired when they are displayed to a user. -**Invite**: [TODO] +**Invite**: An protocol message from one client to another to estblish a communication channel. Invites notify a client that somone wants to communicate with them, and provides the required information to do so. ### Transports -**Out of Band**: [TODO] - -**Delivery Service**: [TODO] +**Out-of-Band**: The transfer of information using a channel separate from the defined protocol channel. Data sent Out-of-Band is transmitted using an undefined mechanism. This is used when protocols requires information to be shared with another entity, but it does not describe how that should occur. The responsibility to define how this occurs is on implementors or other protocols in the suite. ### TBD -**Client**: [TODO] - -**Application**: [TODO] +**Client**: Software that implements a chat protocol. It is responsible for establishing and maintaining communication with the underlying network, performing protocol operations (e.g., encryption, key management, frame generation), and exposing an interface for higher-level software. A Client serves as the technical component that provides messaging capabilities to Applications. +**Application**: Software that integrates with a Client in order to send and receive content. From 6a62b7145d49131b5d8486cd3d52b94c53efc37c Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Fri, 26 Sep 2025 08:00:39 -0700 Subject: [PATCH 06/14] Update spelling + aspell --- .spellcheck.yml | 2 ++ .wordlist.txt | 6 +++++- informational/chatdefs.md | 14 +++++++------- 3 files changed, 14 insertions(+), 8 deletions(-) diff --git a/.spellcheck.yml b/.spellcheck.yml index 33142a5..592eee2 100644 --- a/.spellcheck.yml +++ b/.spellcheck.yml @@ -5,6 +5,8 @@ matrix: expect_match: false # false -> supress errors if no markdown files were edited aspell: lang: en + mode: none + add-filter: url dictionary: wordlists: - .wordlist.txt diff --git a/.wordlist.txt b/.wordlist.txt index 4d6c057..6ade513 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -20,4 +20,8 @@ gossipsub libp2p pubsub subnets -ZXCV \ No newline at end of file +ZXCV +BCP +Bradner +encodings +implementers \ No newline at end of file diff --git a/informational/chatdefs.md b/informational/chatdefs.md index d27960c..7daeda5 100644 --- a/informational/chatdefs.md +++ b/informational/chatdefs.md @@ -3,7 +3,7 @@ title: CHAT-DEFINITIONS name: Shared definitions for Chat Protocols category: Informational tags: definitions, terminology, reference -editor: Jazzz +editor: contributors: --- @@ -47,25 +47,25 @@ Terms are organized into the following categories for clarity and ease of refere ### Message Types -**Payload**: The encoded bytes as produced by a chat protocol. The term `message` is avoided due to conlicts with other layers. +**Payload**: The encoded bytes as produced by a chat protocol. The term `message` is avoided due to conflicts with other layers. -**Frame**: A datastructure which is required to implement a chat protocol. Frames are used to disambiguate the objects defined by chat protocols from transport 'messages' and application `content`. +**Frame**: A data structure which is required to implement a chat protocol. Frames are used to disambiguate the objects defined by chat protocols from transport 'messages' and application `content`. **Content**: The data that is intended for end-users or applications. Chat protocols transmit and route content between clients. -**ContentType**: The structured format of content. These datastructures represent specific encodings of Text, Image, Audio data. +**ContentType**: The structured format of content. These data structures represent specific encodings of Text, Image, Audio data. **Delivery Acknowledgement**: A notification from a receiving client to sender that their message was successfully received. While similar to a read-receipt delivery acknowledgements differ in that the acknowledgement originates based on the client, where read-receipts are fired when they are displayed to a user. -**Invite**: An protocol message from one client to another to estblish a communication channel. Invites notify a client that somone wants to communicate with them, and provides the required information to do so. +**Invite**: An protocol message from one client to another to establish a communication channel. Invites notify a client that someone wants to communicate with them, and provides the required information to do so. ### Transports -**Out-of-Band**: The transfer of information using a channel separate from the defined protocol channel. Data sent Out-of-Band is transmitted using an undefined mechanism. This is used when protocols requires information to be shared with another entity, but it does not describe how that should occur. The responsibility to define how this occurs is on implementors or other protocols in the suite. +**Out-of-Band**: The transfer of information using a channel separate from the defined protocol channel. Data sent Out-of-Band is transmitted using an undefined mechanism. This is used when protocols requires information to be shared with another entity, but it does not describe how that should occur. The responsibility to define how this occurs is the implementer or other protocols in the suite. -### TBD +### Software Entities **Client**: Software that implements a chat protocol. It is responsible for establishing and maintaining communication with the underlying network, performing protocol operations (e.g., encryption, key management, frame generation), and exposing an interface for higher-level software. A Client serves as the technical component that provides messaging capabilities to Applications. From 540607ce3943b73893d1f2eb0515a14e86917522 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Fri, 26 Sep 2025 08:10:16 -0700 Subject: [PATCH 07/14] Add html filter to aspell --- .spellcheck.yml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.spellcheck.yml b/.spellcheck.yml index 592eee2..154a6db 100644 --- a/.spellcheck.yml +++ b/.spellcheck.yml @@ -6,14 +6,16 @@ matrix: aspell: lang: en mode: none - add-filter: url + add-filter: + - url dictionary: wordlists: - .wordlist.txt - encoding: utf-8 pipeline: - pyspelling.filters.markdown + - pyspelling.filters.html: + comments: false + attributes: false - pyspelling.filters.text default_encoding: utf-8 suggest: true - From cf24695fc4b80bf7fa664acca636b3ec28605cf6 Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Fri, 26 Sep 2025 08:16:39 -0700 Subject: [PATCH 08/14] Fix pyspell error --- .spellcheck.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.spellcheck.yml b/.spellcheck.yml index 154a6db..0e94ad8 100644 --- a/.spellcheck.yml +++ b/.spellcheck.yml @@ -15,7 +15,6 @@ matrix: - pyspelling.filters.markdown - pyspelling.filters.html: comments: false - attributes: false - pyspelling.filters.text default_encoding: utf-8 suggest: true From 1dd97400ca42a11e7291387eb37bd6ac31254e7a Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Fri, 26 Sep 2025 08:19:52 -0700 Subject: [PATCH 09/14] fix spell of contentTypes --- informational/chatdefs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/informational/chatdefs.md b/informational/chatdefs.md index 7daeda5..79aecbf 100644 --- a/informational/chatdefs.md +++ b/informational/chatdefs.md @@ -53,7 +53,7 @@ Terms are organized into the following categories for clarity and ease of refere **Content**: The data that is intended for end-users or applications. Chat protocols transmit and route content between clients. -**ContentType**: The structured format of content. These data structures represent specific encodings of Text, Image, Audio data. +**Content Type**: The structured format of content. These data structures represent specific encodings of Text, Image, Audio data. **Delivery Acknowledgement**: A notification from a receiving client to sender that their message was successfully received. While similar to a read-receipt delivery acknowledgements differ in that the acknowledgement originates based on the client, where read-receipts are fired when they are displayed to a user. From b3a724a60e93775ed1bb93cc93434be894c61d8a Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Tue, 28 Oct 2025 21:51:14 -0700 Subject: [PATCH 10/14] chore: sort wordlist --- .wordlist.txt | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index 6ade513..130233d 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,27 +1,27 @@ ALLOC -IANA -SHARDING -WAKU -Waku -danielkaiser -creativecommons -github -GITHUB -https -iana -md -rfc -RFC -www -DHT -DoS -GossipSub -gossipsub -libp2p -pubsub -subnets -ZXCV BCP Bradner +creativecommons +danielkaiser +DHT +DoS encodings -implementers \ No newline at end of file +github +GITHUB +gossipsub +GossipSub +https +iana +IANA +implementers +libp2p +md +pubsub +rfc +RFC +SHARDING +subnets +Waku +WAKU +www +ZXCV \ No newline at end of file From 887318e2aa34c44b09179a3df0923418f170b61e Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Mon, 24 Nov 2025 08:03:30 -0800 Subject: [PATCH 11/14] Update informational/chatdefs.md Co-authored-by: kaichao --- informational/chatdefs.md | 1 + 1 file changed, 1 insertion(+) diff --git a/informational/chatdefs.md b/informational/chatdefs.md index 79aecbf..2c32a69 100644 --- a/informational/chatdefs.md +++ b/informational/chatdefs.md @@ -33,6 +33,7 @@ Terms are organized into the following categories for clarity and ease of refere - **Roles**: Defined entity types that determine how a participant behaves within a communication protocol. - **Message Types**: Classifications and categories of protocol messages - **Transports**: Abstract methods of transmitting payloads + ## Definitions ### Accounts + Identity From cb5f1b69de59a70e6c2ccc7243bda0b832330ebf Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Mon, 24 Nov 2025 09:08:37 -0800 Subject: [PATCH 12/14] Clarify Content, Frames, Payloads --- informational/chatdefs.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/informational/chatdefs.md b/informational/chatdefs.md index 2c32a69..5377a23 100644 --- a/informational/chatdefs.md +++ b/informational/chatdefs.md @@ -48,17 +48,22 @@ Terms are organized into the following categories for clarity and ease of refere ### Message Types -**Payload**: The encoded bytes as produced by a chat protocol. The term `message` is avoided due to conflicts with other layers. +The term "message" often has multiple meanings depending on context. The following definitions are used to disambiguate between different abstraction levels. -**Frame**: A data structure which is required to implement a chat protocol. Frames are used to disambiguate the objects defined by chat protocols from transport 'messages' and application `content`. +**Content**: The data that is intended for end-users or applications - this includes text, images and other user valued data. These messages originate from the application, and are ultimately delivered to other applications. -**Content**: The data that is intended for end-users or applications. Chat protocols transmit and route content between clients. +**Frame**: The data generated by a chat protocol. Frames are messages used by protocols to provide functionality - they are how clients exchange information with eachother and coordinate state. + +**Payload**: The encoded data or datastructures used by lower layer protocols. This includes the encoded bytes passed to a delivery service or subsequent layers. Payloads are usually associated with the delivery process, which is not defined by chat protocols. + + +Other specfic message types include: **Content Type**: The structured format of content. These data structures represent specific encodings of Text, Image, Audio data. **Delivery Acknowledgement**: A notification from a receiving client to sender that their message was successfully received. While similar to a read-receipt delivery acknowledgements differ in that the acknowledgement originates based on the client, where read-receipts are fired when they are displayed to a user. -**Invite**: An protocol message from one client to another to establish a communication channel. Invites notify a client that someone wants to communicate with them, and provides the required information to do so. +**Invite**: A frame used to initialize a new conversation. Invites notify a client that someone wants to communicate with them, and provides the required information to do so. ### Transports @@ -68,9 +73,9 @@ Terms are organized into the following categories for clarity and ease of refere ### Software Entities -**Client**: Software that implements a chat protocol. It is responsible for establishing and maintaining communication with the underlying network, performing protocol operations (e.g., encryption, key management, frame generation), and exposing an interface for higher-level software. A Client serves as the technical component that provides messaging capabilities to Applications. +**Client**: A Software component that provides messaging capabilities to Applications. Clients are responsible for establishing and maintaining communication with the underlying network, performing protocol operations (e.g., encryption, key management, frame generation), and exposing an interface for higher-level software. -**Application**: Software that integrates with a Client in order to send and receive content. +**Application**: Software that integrates with a Client in order to send and receive content. Applications are responsible for displaying content and controlling what content gets sent. From 2c69efa7e5d07001e3625e84e25a65685cf2908c Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Mon, 24 Nov 2025 09:12:23 -0800 Subject: [PATCH 13/14] spelling fixes --- informational/chatdefs.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/informational/chatdefs.md b/informational/chatdefs.md index 5377a23..888333b 100644 --- a/informational/chatdefs.md +++ b/informational/chatdefs.md @@ -52,12 +52,12 @@ The term "message" often has multiple meanings depending on context. The followi **Content**: The data that is intended for end-users or applications - this includes text, images and other user valued data. These messages originate from the application, and are ultimately delivered to other applications. -**Frame**: The data generated by a chat protocol. Frames are messages used by protocols to provide functionality - they are how clients exchange information with eachother and coordinate state. +**Frame**: The data generated by a chat protocol. Frames are messages used by protocols to provide functionality - they are how clients exchange information with each other and coordinate state. -**Payload**: The encoded data or datastructures used by lower layer protocols. This includes the encoded bytes passed to a delivery service or subsequent layers. Payloads are usually associated with the delivery process, which is not defined by chat protocols. +**Payload**: The encoded data or data structures used by lower layer protocols. This includes the encoded bytes passed to a delivery service or subsequent layers. Payloads are usually associated with the delivery process, which is not defined by chat protocols. -Other specfic message types include: +Other specific message types include: **Content Type**: The structured format of content. These data structures represent specific encodings of Text, Image, Audio data. From 10ff3a31232d814ca5ba8ec33a697157331326fa Mon Sep 17 00:00:00 2001 From: Jazz Turner-Baggs <473256+jazzz@users.noreply.github.com> Date: Sun, 30 Nov 2025 23:56:15 -0800 Subject: [PATCH 14/14] Update informational/chatdefs.md Co-authored-by: kaichao --- informational/chatdefs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/informational/chatdefs.md b/informational/chatdefs.md index 888333b..e80f2c7 100644 --- a/informational/chatdefs.md +++ b/informational/chatdefs.md @@ -68,7 +68,7 @@ Other specific message types include: ### Transports -**Out-of-Band**: The transfer of information using a channel separate from the defined protocol channel. Data sent Out-of-Band is transmitted using an undefined mechanism. This is used when protocols requires information to be shared with another entity, but it does not describe how that should occur. The responsibility to define how this occurs is the implementer or other protocols in the suite. +**Out-of-Band**: The transfer of information using a channel separate from the defined chat protocol. Data sent Out-of-Band is transmitted using an undefined mechanism. This is used when protocols requires information to be shared with another entity, but it does not describe how that should occur. The responsibility to define how this occurs is the implementer or other protocols in the suite. ### Software Entities