> For the complete documentation index, see [llms.txt](https://chainedx.gitbook.io/chainedx-protocol/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://chainedx.gitbook.io/chainedx-protocol/5.-messaging.md). # 5. Messaging ChainedX addresses messaging as a first-order concept so users can communicate with each other through a social graph. Posts, replies, reactions/likes, and direct messages are all examples of different message types today in social networks. To enable messaging, several key components are needed: **Announcement:** A structure representing that a message exists **Announcement Metadata:** Key metadata embedded in a announcement allowing message verification and simple correlation of related messages . **Content:** Detailed data containing the message text, additional metadata, and media links Combined, these components allow for a minimal model of most current social network messaging use cases, including broadcast and directed messaging types, as well as public and private messaging types. They may also be adapted to Layer 2 strategies to manage Combined, these components allow for a minimal model of most current social network messaging use cases, including broadcast and directed messaging types, as well as public and private messaging types. They may also be adapted to Layer 2 strategies to manage.

Figure 4: Key Storage and Retrieval scale and cost. An example of this is Batch Message Announcements, as described in Appendix A.

**5.1 Announcements** Announcements allow users to become aware of messages in different ways, depending on the type of message. Email uses SMTP to communicate between persistent nodes. Existing balkanized social networks perform this task by directly updating their internal systems. In a decentralized network without unique persistent nodes, however, the difficulty in making Announcements is twofold. First, the route to the receiver is not fixed; a user may be in multiple locations or using multiple devices. Second, the receiver may have only intermittent connectivity, so the network needs to maintain Announcements until the receiver is available. In addition, in the social media case, users expect that messages sent today will persist for followers added in the future, indefinitely. These constraints lead to a system of Announcements that are stored on the blockchain. This system allows message recipients to replay messages as necessary or to monitor the blockchain for incremental Announcements as they are created. To accomplish this task, blockchain Announcements include a minimal set of essential metadata that can be used to quickly filter messages needed for a given user. **5.2 Announcement Metadata** The protocol models a flexible Announcement data structure. All Announcements have at least four key attributes, but the format allows extensions to this data set to accomplish additional use cases. The four key attributes are: • Message Type • Social Identity that is the source of the message • URI of the content • Hash of the content located by the content URI These key attributes allow Announcements to answer four key questions: 1. What type of message is this? 2. Did the author really send this message? 3. Where is the content located? 4. How is content authenticated? The four key attributes defined as metadata on each Announcement answer this set of questions for all Announcement types, and help prove the validity and authenticity of the related data.

Figure 5: Announcement Metadata Structure

5.2.1 What type of message is this? Messages are modeled as events on the blockchain. Each Message Type is represented by a different event. The simplest is a Broadcast message, which has only the four key attributes already identified for an Announcement. Message Types may define additional attributes needed for their specific use case. **5.2.2 Did the author really send this message?** As described in the section on Social Identity, the user has the ability to authorize third parties to take actions on their behalf on their smart contract. This means that a valid message must come from the user’s Social Identity smart contract, but that the smart contract may be invoked by the user or an authorized third party. This allows more flexible use cases, such as delayed sending and cost shifting. When verifying a message sent in this manner, the blockchain security mechanism combined with the smart contract implementation can be used to ensure that only an authorized party sent the author’s message. While authenticating authorship is expected to be primarily the domain of aggregators or other intermediaries, it is important that any message recipient be able to directly and independently authenticate message authorship in order to ensure portability and system integrity. **5.2.3 Where is the content located?** Content hosting is assumed, by default, to be the responsibility of the sender. It is, however, possible for the sender to delegate this responsibility to a third party. The only criteria for content hosting is that the data should be persistently available and have unrestricted access for retrieval. The Announcement contains a URI of the content location, enabling recipients to retrieve the content. The URI is expected to most often be an HTTPS8 URL, allowing direct access to the referenced content, but any other protocol that is generally accessible may be substituted. Examples include Swarm or IPFS, with the caveat that protocols not supported by a recipient’s user agent may limit interoperability. **5.2.4 How is content authenticated?** The Announcement contains a Hash of the content referenced by the content URI. When the content is retrieved, the retrieved content can be hashed using the same algorithm and compared with the Hash in the Announcement. Matching Hashes indicate that the content is valid. To ensure unique hashes between Social Identities, the contents of the message must include an author property that matches the announcing identity. Content retrieved from a proxy or cache can also be validated, even when from a different URI, as long as the content is not transformed by such mechanisms. **5.3 Content** After a user has received a message Announcement and retrieved and authenticated the contents of a message, the content must still be interpreted. DSNP is adapting the W3C Recommendation on Activity Streams\[8] to represent content data and metadata. Only minimal changes to the standard are needed to achieve integration with the blockchain related use cases, and the expected changes may be compatible with existing tools. In addition, this may make it possible to bridge the unified graph emanating from the protocol and other Activity Stream implementations, as a result of common data models for content. Required changes to Activity Streams include enhancements to implement additional data for certain elements. An example is the Link model in Activity Streams for linking to images. While content can be authenticated through a chain of hashes or signatures back from Announcement to the trust of the blockchain, complete validation would require that the chain of hashes or signatures continue to the images or other data linked in the content. “Link” is augmented with a hash that can be used to easily verify that the linked content has not changed. **5.4 Broadcast and Directed Messaging** As previously described, the Message Type specifies the behavior and ancillary attributes of a message. Four key Message Types are defined here, though additional types may be created: Broadcast: A message with no recipient Reply: A message with a referent or source message Direct: A message with a public recipient Dead Drop: A message with a private recipient **5.4.1 Broadcast** A Broadcast message is an Announcement with no recipient. Users primarily discover these messages by following the author and monitoring for messages with the author as the sender. Such messages may also be aggregated into public feeds and presented by recommendation algorithms. This form of message is analogous to public X (twitter) platform's posts. **5.4.2 Reply** A Reply message is just like a Broadcast Announcement, but with a referent (“In Reply To”) message ID. A Reply message Announcement depends on the fact that content Hashes are unique for any content and Social Identity combination. As mentioned before, the content needs to include a matching author to validate. Each message may then generate its Hash before the Announcement is made and can therefore be referred to in an unambiguous fashion. A Reply Announcement uses this value as the referent message ID. A Reply message can reference a Broadcast Announcement or another Reply Announcement. This form of message is analogous to a comment on a public post on a Facebook page. Replies do not need to have complex content and can be used to represent reactions such as likes or upvotes. The need for this additional piece of information at the Announcement level instead of in content metadata is driven by discoverability. Users are often interested in replies to messages they have already discovered or are otherwise made aware of from Social Identities they do not follow. By placing the reference message in the Announcement, users can discover entire subtrees of content related to messages they have already received. Without such a mechanism, they would need to monitor all messages on the chain, retrieve the content URL, and examine it for relevance. At any scale, such actions are prohibitively inefficient.

Figure 6: Message Types and Replies

**5.4.3 Direct** A Direct message is sent to a specific Social Identity through the recipient’s smart contract. Both the sender and the receiver are public, although the contents of the message would usually be encrypted. This message is analogous to an invitation to connect on LinkedIn. One of the ways users discover relevant message Announcements is by looking for Direct messages sent to their Social Identity. Friend requests or other cases where a recipient might not otherwise know to look for message Announcements from the message sender can use Direct messages to establish communications. **5.4.4 Dead Drop** A Dead Drop message is an Announcement that uses a special mechanism, called a Dead Drop Identifier (DDID), to indicate the recipient of the message, instead of a Social Identity. The intention is to provide end-to-end encryption and metadata privacy by concealing the intended recipient, in order to avoid revealing the receiver’s private social graph relationships through metadata analysis. This is analogous to a Twitter direct message, where outside parties can neither read the message nor even determine that the two parties are communicating with each other. DSNP extends this protection, preventing service providers from reading message contents or knowing who is communicating. Dead Drop Announcements must be addressed with care. The intended recipient needs to know that the Announcement is for them, but the network must not. One option for a user to discover a message intended for them with an encrypted recipient field is to attempt to decrypt every encrypted message on the network. The Whisper protocol from the Ethereum Foundation uses this model.9 As referenced for Reply Announcements, this option is prohibitively inefficient at scale. The protocol uses a novel Dead Drop ID system similar to the dead drops that are a staple of classic spycraft. For example, Alice places a message under a bench in the park. Anyone who stumbles upon the message would be unable to identify the intended recipient. Bob, however, knows the dead-drop location and can privately discover, retrieve, and read the message. Classic dead drops have a major logistical issue: The dead-drop location must be known to both the sending and receiving parties, but not to anyone else. This means the two parties must have an initial means of communicating before they establish the dead drop. No matter how secure the dead-drop mechanism is on its own, it relies on the security of the initial means of communication. Unlike the physical realm, public key cryptography provides a means to independently derive a common shared secret without prior private communication. Dead Drop Announcements leverage this shared secret to algorithmically create unique Dead Drop Identifiers that cannot be traced to the intended recipient.

Figure 7: DDID Flow For Alice with Two Associates

The identifiers are unique based on each sender-receiver, so each user has a different Dead Drop Identifier for sending a message to the other. This is analogous to Alice passing messages to Bob by leaving them under a park bench, and Bob passing messages to Alice by leaving them in a planter outside the hardware store: Two private, simplex channels with recipient privacy create a single, duplex channel with recipient privacy. At the blockchain level, an observer can see that Alice and Bob are both sending messages, but cannot determine that they are sending messages to each other. If Alice and Bob each run their own blockchain node for retrieving content, or use nodes not run by a bad actor, they should also not be susceptible to information retrieval attacks, though timing attacks exploiting correlation between their activities are not prevented. While Dead Drop Identifiers can be derived without a separate secure communication channel, there must be some trigger for two users to start listening to each others’ DDIDs. This intent may be communicated out of band, but may also be triggered implicitly or explicitly by on-chain actions. For example, user agents can choose to monitor DDIDs for all public followers of a Social Identity, whether perpetually or for a specific period of time after a follow notification. Alternatively, a Direct message Announcement could be sent from one user to the other with encrypted content expressing the desire to communicate with DDIDs, causing both to derive and monitor the relevant DDID values. **5.4.5 Other Message Types** The Announcement Message Types are extensible and are a flexible mechanism for adding new features to the core messaging capabilities of the protocol. For example, spam scoring services can express a spam score about Broadcast messages by extending Reply messages with a new Message Type and including scoring data in the Announcement or content. The same mechanism can be used for other services, such as fact checking, reputation scoring, or moderation, to add arbitrary metadata to an existing message. A Message Type may also be constructed to refer to a group of Announcements. This type enables “batching” or Layer 2 Announcements to reach the blockchain in a cost-efficient structure, while still preserving the authenticity of messages. A simple Batch Message Announcement structure is described in Appendix A. Another Message Type common to social media is a Reaction type. Reactions are similar to Reply Announcements, but with different metadata attached. A Reaction might have a sentiment value of positive, neutral, or negative, as well as a suggested rendering. The sentiment allows for simple cross-client display of reactions, while a suggested rendering can be used to expand the range of emotion for supporting clients. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://chainedx.gitbook.io/chainedx-protocol/5.-messaging.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.