Skip to main content

Protocol Definitions

Background​

As we embark on building out the core of the protocol, it is necessary to have a shared understanding of the terminology and goals of the system. This is intended to be a high level document that we can reference and continually improve as we refine our understanding of what the protocol is.

Protocol Goals​

The protocol governs the transmission of data between many different types of actors in XMTP. It defines the rules that clients, nodes, and smart contracts on external blockchains must follow. When designing the protocol, I propose we make decisions based on the following goals:

  1. Clients can reliably send/receive messages to/from XMTP nodes
  2. The protocol will reject messages that do not pass validation against message acceptance criteria
  3. The protocol will fairly allocate network incentives to XMTP nodes who perform incentivized actions
  4. The protocol will accept valid postage proofs for limited network actions
  5. The protocol will be resistant against spam, DOS attacks, and malicious network actors
  6. The protocol will ensure that any message asserting to be sent from a given wallet address was sent from a client connected to that wallet.
  7. The protocol will enforce that messages are encrypted and only readable by the holder of the private keys associated with a recipient wallet address.

Definition styleguide​

  • ✅ DO use lowercase unless
    • it is at the beginning of a sentence
    • it refers to a proper noun (e.g. XMTP)
  • ✅ DO wrap terms contained within definitions with inline code spans
  • ✅ DO link to other terms from within definitions
  • 🛑 DO NOT wrap or link self-referential terms
    • i.e. don't wrap or link any other instances a term from within its own definition
  • 🛑 DO NOT wrap or link subsequent instances of a term within a definition beyond the first use
    • except when the additional use of the term occurs in a subsequent bullet

Terms in use​

application level​

  • Refers to actions that occur within clients and do not directly affect the network

client​

  • Clients are software applications that interface with the XMTP network on behalf of their users.
  • A client MUST connect to one or more nodes as a peer. Each client MUST be connected to a wallet to be considered active on the XMTP network. A client MUST have a key bundle used for message encryption and authentication. A client is able to send and receive messages through the network, and MAY store those messages.
  • Clients MAY be capable of interacting with blockchain smart contracts to enable limited network actions by way of paying postage or validating staked tokens.

conversation​

  • A conversation is an application level abstraction where messages sent between two or more parties appear to be displayed in a chat-like contiguous fashion. Clients may choose to display messages as conversations, or any other UX.

DOS​

headers​

  • To be written

key bundle​

limited network action​

  • A function executed by an XMTP node that requires a postage proof before it is executed. For example, sending an introductory message to a new contact or an unsolicited invitation to a group chat.

message​

message contents​

  • Message contents are the encrypted payload encoded as a field in the XMTP envelope. XMTP nodes cannot validate the contents of the message, as they are encrypted. As such, message contents can be of any format and may be unreadable upon decryption. Message contents MUST conform to XIP-X (add in Martin's XIP here), and clients SHOULD reject messages that are non-compliant.

message storage​

  • Message storage referes to all types of facilities used to persist messages throughout their lifecycle. Due to the changing requirements for storage as the message progresses on its journey it seems prudent to distinguish at least pre-delivery and post-delivery storage.

network​

  • Unless otherwise specified, use of this term refers to the xmtp network.

peer​

payload​

  • To be written

pre-delivery storage​

  • Message delivery requires storage because the recipient may not be available at the time the message is sent. The message may also travel through multiple nodes to reach its destination, the network must make sure it doesn't get lost while in transit.

post-delivery storage​

  • Once a message reaches the recipient it needs to be stored to allow the user to see past and current conversations. At that point the message doesn't need to reach another party, just be available to the same one as long as desirable, albeit usually through multiple devices.

protocol​

  • The set of rules and standards that govern the interaction between clients, XMTP nodes, and smart contracts on external blockchains.

session​

spam​

wallet address​

wallet signature​

  • A cryptographic signature generated by the private keys associated with a given wallet address.

XIP​

  • Short for "XMTP Improvement Proposal"
  • An XIP is a design document providing information to the XMTP community, or describing a new feature for XTMP or its processes or environment.

XMTP​

  • Abbreviation for "Extensible Message Transport Protocol"
  • When in use, it may also refer to:

XMTP envelope​

XMTP network​

  • To be written

XMTP node​

XRC​

  • An XMTP Request for Comment
  • Includes application-level standards and conventions, including message payload formats and applications

user​

  • To be written

Waku envelope​

  • The Waku Envelope is the outermost container for a message. The msg field is where the xmtp-envelope is stored

Terms in the works​

connection request​

  • A connection request represents an intent to create a messaging session between 2 or more wallet addresses. Connection requests are opted into by all involved parties and may happen off the XMTP network using a preconstructed code, or over the network which could require postage.

incentivized action​

message acceptance criteria​

  • A set of rules that govern whether a given message is to be forwarded to other XMTP nodes and clients.
  • Some examples include:
    • The message is well-formed with all required headers
    • The message does not exceed any size limits enforced by the XMTP network
    • The message is signed by the correct private key
    • The private key used to sign the message was signed by a wallet address that matches the sender address
    • If a postage proof is required for this message, ensure that the proof is valid
    • If no postage proof is included with the message, ensure that no proof is required

network incentive​

postage​

  • Postage represents a transaction between a client and a smart contract in order to gain permission for the client to execute a limited network action. A valid request for postage, where the requester has paid or staked sufficient funds, MUST result in a confirmation being sent to the client, which MUST be used to construct a postage proof.

postage proof​

XMTP token​

  • To be written

Terms reservered​

Definitions to be added later

Attachment​

Channel​

Chat​

Group​

Invitation​

Notification​

Profile​

Reply​

Subject​

Subnet​

Thread​