mirror of
https://github.com/vacp2p/rfc.vac.dev.git
synced 2026-01-09 16:07:54 -05:00
1 line
39 KiB
JavaScript
1 line
39 KiB
JavaScript
"use strict";(self.webpackChunklogos_docs_template=self.webpackChunklogos_docs_template||[]).push([[518],{99590:(e,t,a)=>{a.r(t),a.d(t,{assets:()=>o,contentTitle:()=>r,default:()=>u,frontMatter:()=>i,metadata:()=>l,toc:()=>p});var s=a(87462),n=(a(67294),a(3905));const i={title:"STATUS-PROTOCOLS",name:"Status Protocol Stack",status:"raw",category:"Standards Track",description:"Specifies the Status application protocol stack.",editor:"Hanno Cornelius <hanno@status.im>",contributors:["Jimmy Debe <jimmy@status.im>","Aaryamann Challani <p1ge0nh8er@proton.me>"]},r=void 0,l={unversionedId:"raw/status-app-protocols",id:"raw/status-app-protocols",title:"STATUS-PROTOCOLS",description:"Specifies the Status application protocol stack.",source:"@site/status/raw/status-app-protocols.md",sourceDirName:"raw",slug:"/raw/status-app-protocols",permalink:"/status/raw/status-app-protocols",draft:!1,tags:[],version:"current",frontMatter:{title:"STATUS-PROTOCOLS",name:"Status Protocol Stack",status:"raw",category:"Standards Track",description:"Specifies the Status application protocol stack.",editor:"Hanno Cornelius <hanno@status.im>",contributors:["Jimmy Debe <jimmy@status.im>","Aaryamann Challani <p1ge0nh8er@proton.me>"]},sidebar:"defaultSidebar",previous:{title:"STATUS-SIMPLE-SCALING",permalink:"/status/raw/simple-scaling"},next:{title:"STATUS-MVDS-USAGE",permalink:"/status/raw/status-mvds"}},o={},p=[{value:"Abstract",id:"abstract",level:2},{value:"Status protocol stack",id:"status-protocol-stack",level:2},{value:"Status application layer",id:"status-application-layer",level:2},{value:"Functional Scope",id:"functional-scope",level:3},{value:"Global general scope",id:"global-general-scope",level:4},{value:"Global community scope",id:"global-community-scope",level:4},{value:"Local scope",id:"local-scope",level:4},{value:"Content topics",id:"content-topics",level:3},{value:"Ephemerality",id:"ephemerality",level:3},{value:"End-to-end reliability layer",id:"end-to-end-reliability-layer",level:2},{value:"Encryption layer",id:"encryption-layer",level:2},{value:"Waku transport layer",id:"waku-transport-layer",level:2},{value:"Waku messages",id:"waku-messages",level:3},{value:"Pubsub topics and sharding",id:"pubsub-topics-and-sharding",level:3},{value:"Self-addressed messages",id:"self-addressed-messages",level:4},{value:"Global messages",id:"global-messages",level:4},{value:"Community messages",id:"community-messages",level:4},{value:"Large messages",id:"large-messages",level:4},{value:"Resource usage",id:"resource-usage",level:3},{value:"Discovery",id:"discovery",level:3},{value:"Subscribing",id:"subscribing",level:3},{value:"Self-addressed messages",id:"self-addressed-messages-1",level:4},{value:"Large messages",id:"large-messages-1",level:4},{value:"Publishing",id:"publishing",level:3},{value:"Self-addressed messages",id:"self-addressed-messages-2",level:4},{value:"Large messages",id:"large-messages-2",level:4},{value:"Retrieving historical messages",id:"retrieving-historical-messages",level:3},{value:"Store queries for reliability",id:"store-queries-for-reliability",level:4},{value:"Self-addressed messages",id:"self-addressed-messages-3",level:4},{value:"Large messages",id:"large-messages-3",level:4},{value:"Providing services",id:"providing-services",level:3},{value:"Self-addressed messages",id:"self-addressed-messages-4",level:3},{value:"Large messages",id:"large-messages-4",level:3},{value:"Chunking",id:"chunking",level:4},{value:"Copyright",id:"copyright",level:2},{value:"References",id:"references",level:2}],c={toc:p};function u(e){let{components:t,...a}=e;return(0,n.kt)("wrapper",(0,s.Z)({},c,a,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"Status: raw"),(0,n.kt)("li",{parentName:"ul"},"Category: Standards Track"),(0,n.kt)("li",{parentName:"ul"},"Editor: Hanno Cornelius ","<",(0,n.kt)("a",{parentName:"li",href:"mailto:hanno@status.im"},"hanno@status.im"),">"),(0,n.kt)("li",{parentName:"ul"},"Contributors:",(0,n.kt)("ul",{parentName:"li"},(0,n.kt)("li",{parentName:"ul"},"Jimmy Debe ","<",(0,n.kt)("a",{parentName:"li",href:"mailto:jimmy@status.im"},"jimmy@status.im"),">"),(0,n.kt)("li",{parentName:"ul"},"Aaryamann Challani ","<",(0,n.kt)("a",{parentName:"li",href:"mailto:p1ge0nh8er@proton.me"},"p1ge0nh8er@proton.me"),">")))),(0,n.kt)("h2",{id:"abstract"},"Abstract"),(0,n.kt)("p",null,"This specification describes the Status Application protocol stack.\nIt focuses on elements and features in the protocol stack for all application-level functions:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"functional scope (also ",(0,n.kt)("em",{parentName:"li"},"broadcast audience"),")"),(0,n.kt)("li",{parentName:"ul"},"content topic"),(0,n.kt)("li",{parentName:"ul"},"ephemerality"),(0,n.kt)("li",{parentName:"ul"},"end-to-end reliability layer"),(0,n.kt)("li",{parentName:"ul"},"encryption layer"),(0,n.kt)("li",{parentName:"ul"},"transport layer (Waku)")),(0,n.kt)("p",null,"It also introduces strategies to restrict resource usage, distribute large messages, etc.\nApplication-level functions are out of scope and specified separately. See:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",{parentName:"li",href:"../55/1to1-chat"},"55/STATUS-1TO1-CHAT")),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("a",{parentName:"li",href:"../56/communities"},"56/STATUS-COMMUNITIES"))),(0,n.kt)("h2",{id:"status-protocol-stack"},"Status protocol stack"),(0,n.kt)("p",null,"The keywords \u201cMUST\u201d, \u201cMUST NOT\u201d, \u201cREQUIRED\u201d, \u201cSHALL\u201d, \u201cSHALL NOT\u201d,\n\u201cSHOULD\u201d, \u201cSHOULD NOT\u201d, \u201cRECOMMENDED\u201d, \u201cMAY\u201d, and\n\u201cOPTIONAL\u201d in this document are to be interpreted as described in ",(0,n.kt)("a",{parentName:"p",href:"https://www.ietf.org/rfc/rfc2119.txt"},"2119"),".\nSee the simplified diagram of the Status application protocol stack:"),(0,n.kt)("table",null,(0,n.kt)("thead",{parentName:"table"},(0,n.kt)("tr",{parentName:"thead"},(0,n.kt)("th",{parentName:"tr",align:null}))),(0,n.kt)("tbody",{parentName:"table"},(0,n.kt)("tr",{parentName:"tbody"},(0,n.kt)("td",{parentName:"tr",align:null},"Status application layer")),(0,n.kt)("tr",{parentName:"tbody"},(0,n.kt)("td",{parentName:"tr",align:null},"End-to-end reliability layer")),(0,n.kt)("tr",{parentName:"tbody"},(0,n.kt)("td",{parentName:"tr",align:null},"Encryption layer")),(0,n.kt)("tr",{parentName:"tbody"},(0,n.kt)("td",{parentName:"tr",align:null},"Transport layer (Waku)")),(0,n.kt)("tr",{parentName:"tbody"},(0,n.kt)("td",{parentName:"tr",align:null})))),(0,n.kt)("h2",{id:"status-application-layer"},"Status application layer"),(0,n.kt)("p",null,"Application level functions are defined in the ",(0,n.kt)("em",{parentName:"p"},"application")," layer.\nStatus currently defines functionality to support three main application features:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"Status Communities, as specified in ",(0,n.kt)("a",{parentName:"li",href:"../56/communities"},"56/STATUS-COMMUNITIES")),(0,n.kt)("li",{parentName:"ul"},"Status 1:1 Chat, as specified in ",(0,n.kt)("a",{parentName:"li",href:"../55/1to1-chat"},"55/STATUS-1TO1-CHAT")),(0,n.kt)("li",{parentName:"ul"},"Status Private Group Chat, as specified in a subsection of ",(0,n.kt)("a",{parentName:"li",href:"../55/1to1-chat##negotiation-of-a-11-chat-amongst-multiple-participants-group-chat"},"55/STATUS-1TO1-CHAT"))),(0,n.kt)("p",null,"Each application-level function, regardless which feature set it supports, has the following properties:"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},"Functional scope"),(0,n.kt)("li",{parentName:"ol"},"Content topic"),(0,n.kt)("li",{parentName:"ol"},"Ephemerality")),(0,n.kt)("h3",{id:"functional-scope"},"Functional Scope"),(0,n.kt)("p",null,"Each Status app-level message MUST define a functional scope.\nThe functional scope MUST define the ",(0,n.kt)("em",{parentName:"p"},"minimum")," scope of the audience that should ",(0,n.kt)("em",{parentName:"p"},"participate")," in the app function the message is related to.\nIn other words, it determines the minimum subset of Status app participants\nthat should have access to messages related to that function."),(0,n.kt)("p",null,"Note that the functional scope is distinct from the number of participants that is ",(0,n.kt)("em",{parentName:"p"},"addressed")," by a specific message.\nFor example, a participant will address a 1:1 chat to only one other participant.\nHowever, since all users of the Status app MUST be able to participate in 1:1 chats,\nthe functional scope of messages enabling 1:1 chats MUST be a global scope.\nSimilarly, since private group chats can be set up between any subset of Status app users,\nthe functional scope for messages related to private group chats MUST be global.\nAlong the same principle, messages that originate within communities are of global interest\nfor all users who have an interest in the Status Communities feature.\nSuch messages MUST have a global functional scope,\nthat can be accessed by any app users interested in communities.\nA different group of messages are addressed only to the participant that generated those messages itself.\nThese ",(0,n.kt)("em",{parentName:"p"},"self-addressed")," messages MUST have a local functional scope."),(0,n.kt)("p",null,'If we further make a distinction between "control" and "content" messages,\nwe can distinguish five distinct functional scopes.'),(0,n.kt)("p",null,"All Status messages MUST have one of these functional scopes:"),(0,n.kt)("h4",{id:"global-general-scope"},"Global general scope"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("em",{parentName:"li"},"Global control"),": messages enabling the basic functioning of the app to control general features that all app users should be able to participate in. Examples include Contact Requests, global Status Updates, Group Chat Invites, etc."),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("em",{parentName:"li"},"Global content"),": messages carrying user-generated content for global functions. Examples include 1:1 chat messages, images shared over private group chats, etc.")),(0,n.kt)("h4",{id:"global-community-scope"},"Global community scope"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("em",{parentName:"li"},"Global community control"),": messages enabling the basic functioning of the app to control features related to communities. Examples include Community Invites, Community Membership Updates, community Status Updates, etc."),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("em",{parentName:"li"},"Global community content"),": messages carrying user-generated content for members of any community.")),(0,n.kt)("p",null,">"," ",(0,n.kt)("strong",{parentName:"p"},"Note:")," a previous iteration of the Status Communities feature defined separate community-wide scopes for each community.\nHowever, this model was deprecated and all communities now operate on a global, shared scope.\nThis implies that different communities will share shards on the routing layer."),(0,n.kt)("h4",{id:"local-scope"},"Local scope"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("em",{parentName:"li"},"Local"),": messages related to functions that are only relevant to a single user. Also known as ",(0,n.kt)("em",{parentName:"li"},"self-addressed messages"),". Examples include messages used to exchange information between app installations, such as User Backup and Sync messages.")),(0,n.kt)("p",null,"Note that the functional scope is a logical property of Status messages.\nIt SHOULD however inform the underlying ",(0,n.kt)("a",{parentName:"p",href:"#pubsub-topics-and-sharding"},"transport layer sharding")," and ",(0,n.kt)("a",{parentName:"p",href:"#subscribing"},"transport layer subscriptions"),".\nIn general a Status client SHOULD subscribe to participate in:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"all global functions"),(0,n.kt)("li",{parentName:"ul"},"global community functions if it is interested in this feature, and"),(0,n.kt)("li",{parentName:"ul"},"its own local functions.")),(0,n.kt)("h3",{id:"content-topics"},"Content topics"),(0,n.kt)("p",null,"Each Status app-level message MUST define a content topic that links messages in related app-level functions and sub-functions together.\nThis MUST be based on the filter use cases for ",(0,n.kt)("a",{parentName:"p",href:"#subscribing"},"transport layer subscriptions"),"\nand ",(0,n.kt)("a",{parentName:"p",href:"#retrieving-historical-messages"},"retrieving historical messages"),".\nA content topic SHOULD be identical across all messages that are always part of the same filter use case (or always form part of the same content-filtered query criteria).\nIn other words, the number of content topics defined in the app SHOULD match the number of filter use cases.\nFor the sake of illustration, consider the following common content topic and filter use cases:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"if all messages belonging to the same 1:1 chat are always filtered together, they SHOULD use the same content topic (see ",(0,n.kt)("a",{parentName:"li",href:"../55/1to1-chat"},"55/STATUS-1TO1-CHAT"),")"),(0,n.kt)("li",{parentName:"ul"},"if all messages belonging to the same Community are always filtered together, they SHOULD use the same content topic (see ",(0,n.kt)("a",{parentName:"li",href:"../56/communities"},"56/STATUS-COMMUNITIES"),").")),(0,n.kt)("p",null,"The app-level content topic MUST be populated in the ",(0,n.kt)("inlineCode",{parentName:"p"},"content_topic")," field in the encapsulating Waku message (see ",(0,n.kt)("a",{parentName:"p",href:"#waku-messages"},"Waku messages"),")."),(0,n.kt)("h3",{id:"ephemerality"},"Ephemerality"),(0,n.kt)("p",null,"Each Status app-level message MUST define its ",(0,n.kt)("em",{parentName:"p"},"ephemerality"),".\nEphemerality is a boolean value, set to ",(0,n.kt)("inlineCode",{parentName:"p"},"true"),' if a message is considered ephemeral.\nEphemeral messages are messages emitted by the app that are transient in nature.\nThey only have temporary "real-time" value\nand SHOULD NOT be stored and retrievable from historical message stores and sync caches.\nSimilarly, ephemeral message delivery is best-effort in nature and SHOULD NOT be considered in message reliability mechanisms (see ',(0,n.kt)("a",{parentName:"p",href:"#end-to-end-reliability-layer"},"End-to-end reliability layer"),")."),(0,n.kt)("p",null,"An example of ephemeral messages would be periodic status update messages, indicating a particular user's online status.\nSince only a user's current online status is of value, there is no need to store historical status update messages.\nSince status updates are periodic, there is no strong need for end-to-end reliability as subsequent updates are always to follow."),(0,n.kt)("p",null,"App-level messages that are considered ephemeral, MUST set the ",(0,n.kt)("inlineCode",{parentName:"p"},"ephemeral")," field in the encapsulating Waku message to ",(0,n.kt)("inlineCode",{parentName:"p"},"true")," (see ",(0,n.kt)("a",{parentName:"p",href:"#waku-messages"},"Waku messages"),")"),(0,n.kt)("h2",{id:"end-to-end-reliability-layer"},"End-to-end reliability layer"),(0,n.kt)("p",null,"The end-to-end reliability layer contains the functions related to one of the two end-to-end reliability schemes defined for Status app messages:"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},"Minimum Viable protocol for Data Synchronisation, or MVDS (see ",(0,n.kt)("a",{parentName:"li",href:"./status-mvds"},"STATUS-MVDS-USAGE"),")"),(0,n.kt)("li",{parentName:"ol"},"Scalable distributed log reliability (spec and a punchier name TBD, see the ",(0,n.kt)("a",{parentName:"li",href:"https://forum.vac.dev/t/end-to-end-reliability-for-scalable-distributed-logs/293/16"},"original forum post announcement"),")")),(0,n.kt)("p",null,"Ephemeral messages SHOULD omit this layer.\nNon-ephemeral 1:1 chat messages SHOULD make use of MVDS to achieve reliable data synchronisation between the two parties involved in the communication.\nNon-ephemeral private group chat messages build on a set of 1:1 chat links\nand consequently SHOULD also make use of MVDS to achieve reliable data synchronisation between all parties involved in the communication.\nNon-ephemeral 1:1 and private group chat messages MAY make use of of ",(0,n.kt)("a",{parentName:"p",href:"https://forum.vac.dev/t/end-to-end-reliability-for-scalable-distributed-logs/293/16"},"scalable distributed log reliability")," in future.\nSince MVDS does not scale for large number of participants in the communication,\nnon-ephemeral community messages MUST use scalable distributed log reliability as defined in this ",(0,n.kt)("a",{parentName:"p",href:"https://forum.vac.dev/t/end-to-end-reliability-for-scalable-distributed-logs/293/16"},"original forum post announcement"),".\nThe app MUST use a single channel ID per community."),(0,n.kt)("h2",{id:"encryption-layer"},"Encryption layer"),(0,n.kt)("p",null,"The encryption layer wraps the Status App and Reliability layers in an encrypted payload."),(0,n.kt)("h2",{id:"waku-transport-layer"},"Waku transport layer"),(0,n.kt)("p",null,"The Waku transport layer contains the functions allowing Status protocols to use ",(0,n.kt)("a",{parentName:"p",href:"../../waku/standards/core/10/waku2"},"10/WAKU2")," infrastructure as transport."),(0,n.kt)("h3",{id:"waku-messages"},"Waku messages"),(0,n.kt)("p",null,"Each Status application message MUST be transformed to a ",(0,n.kt)("a",{parentName:"p",href:"../../waku/standards/core/14/message"},"14/WAKU2-MESSAGE")," with the following structure:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-protobuf"},'syntax = "proto3";\n\nmessage WakuMessage {\n bytes payload = 1;\n string content_topic = 2;\n optional uint32 version = 3;\n optional sint64 timestamp = 10;\n optional bytes meta = 11;\n optional bool ephemeral = 31;\n}\n')),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("inlineCode",{parentName:"li"},"payload")," MUST be set to the full encrypted payload received from the higher layers"),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("inlineCode",{parentName:"li"},"version")," MUST be set to ",(0,n.kt)("inlineCode",{parentName:"li"},"1")),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("inlineCode",{parentName:"li"},"ephemeral")," MUST be set to ",(0,n.kt)("inlineCode",{parentName:"li"},"true")," if the app-level message is ephemeral"),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("inlineCode",{parentName:"li"},"content_topic")," MUST be set to the app-level content topic"),(0,n.kt)("li",{parentName:"ul"},(0,n.kt)("inlineCode",{parentName:"li"},"timestamp")," MUST be set to the current Unix epoch timestamp (in nanosecond precision)")),(0,n.kt)("h3",{id:"pubsub-topics-and-sharding"},"Pubsub topics and sharding"),(0,n.kt)("p",null,"All Waku messages are published to pubsub topics as defined in ",(0,n.kt)("a",{parentName:"p",href:"../../waku/informational/23/topics"},"23/WAKU2-TOPICS"),".\nSince pubsub topics define a routing layer for messages,\nthey can be used to shard traffic.\nThe pubsub topic used for publishing a message depends on the app-level ",(0,n.kt)("a",{parentName:"p",href:"#functional-scope"},"functional scope"),"."),(0,n.kt)("h4",{id:"self-addressed-messages"},"Self-addressed messages"),(0,n.kt)("p",null,"The application MUST define at least one distinct pubsub topic for self-addressed messages.\nThe application MAY define a set of more than one pubsub topic for self-addressed messages to allow traffic sharding for scalability."),(0,n.kt)("h4",{id:"global-messages"},"Global messages"),(0,n.kt)("p",null,"The application MUST define at least one distinct pubsub topic for global control messages and global content messages.\nThe application MAY defined a set of more than one pubsub topic for global messages to allow traffic sharding for scalability.\nIt is RECOMMENDED that separate pubsub topics be used for global control messages and global content messages."),(0,n.kt)("h4",{id:"community-messages"},"Community messages"),(0,n.kt)("p",null,"The application SHOULD define at least one distinct pubsub topic for global community control messages and global community content messages.\nThe application MAY define a set of more than one pubsub topic for global community messages to allow traffic sharding for scalability.\nIt is RECOMMENDED that separate pubsub topics be used for global community control messages and global community content messages."),(0,n.kt)("h4",{id:"large-messages"},"Large messages"),(0,n.kt)("p",null,"The application MAY define separate pubsub topics for large messages.\nThese pubsub topics for large messages MAY be distinct for each functional scope."),(0,n.kt)("h3",{id:"resource-usage"},"Resource usage"),(0,n.kt)("p",null,"The application SHOULD use a range of Waku protocols to interact with the Waku transport layer.\nThe specific set of Waku protocols used depend on desired functionality and resource usage profile for the specific client.\nResources can be restricted in terms of bandwidth and computing resources."),(0,n.kt)("p",null,'Waku protocols that are more appropriate for resource-restricted environments are often termed "light protocols".\nWaku protocols that consume more resources, but simultaneously contribute more to Waku infrastructure, are often termed "full protocols".\nThe terms "full" and "light" is just a useful abstraction than a strict binary, though,\nand Status clients can operate along a continuum of resource usage profiles,\neach using the combination of "full" and "light" protocols most appropriate to match its environment and motivations.'),(0,n.kt)("p",null,'To simplify interaction with the selection of "full" and "light" protocols,\nStatus clients MUST define a "full mode" and "light mode"\nto allow users to select whether their client would prefer "full protocols" or "light protocols" by default.\nStatus Desktop clients are assumed to have more resources available and SHOULD use full mode by default.\nStatus Mobile clients are assumed to operate with more resource restrictions and SHOULD use light mode by default.'),(0,n.kt)("p",null,'For the purposes of the rest of this document,\nclients in full mode will be referred to as "full clients" and\nclients in light mode will be referred to as "light clients".'),(0,n.kt)("h3",{id:"discovery"},"Discovery"),(0,n.kt)("p",null,"The application MUST make use of at least one discovery method to discover and connect to Waku peers\nuseful for the user functions specific to that instance of the application."),(0,n.kt)("p",null,"The specific Waku discovery protocol used for discovery depends on the use case and resource-availability of the client."),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"https://eips.ethereum.org/EIPS/eip-1459"},"EIP-1459: DNS-based discovery")," is useful for initial connection to bootstrap peers."),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"../../waku/standards/core/33/discv5"},"33/WAKU2-DISCV5")," allows decentralized discovery of Waku peers."),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"https://github.com/waku-org/specs/blob/315264c202e0973476e2f1e2d0b01bea4fe1ad31/standards/core/peer-exchange.md"},"34/WAKU2-PEER-EXCHANGE")," allows requesting peers from a service node\nand is appropriate for resource-restricted discovery.")),(0,n.kt)("p",null,"All clients SHOULD use DNS-based discovery on startup\nto discover a set of bootstrap peers for initial connection."),(0,n.kt)("p",null,"Full clients SHOULD use ",(0,n.kt)("a",{parentName:"p",href:"../../waku/standards/core/33/discv5"},"33/WAKU2-DISCV5")," for continuous ambient peer discovery."),(0,n.kt)("p",null,"Light clients SHOULD use ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/waku-org/specs/blob/315264c202e0973476e2f1e2d0b01bea4fe1ad31/standards/core/peer-exchange.md"},"34/WAKU2-PEER-EXCHANGE")," to discover a set of service peers\nused by that instance of the application."),(0,n.kt)("h3",{id:"subscribing"},"Subscribing"),(0,n.kt)("p",null,"The application MUST subscribe to receive the traffic necessary for minimal app operation\nand to enable the user functions specific to that instance of the application."),(0,n.kt)("p",null,"The specific Waku protocol used for subscription depends on the resource-availability of the client:"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},"Filter client protocol, as specified in ",(0,n.kt)("a",{parentName:"li",href:"../../waku/standards/core/12/filter"},"12/WAKU2-FILTER"),", allows subscribing for traffic with content topic granularity and is appropriate for resource-restricted subscriptions."),(0,n.kt)("li",{parentName:"ol"},"Relay protocol, as specified in ",(0,n.kt)("a",{parentName:"li",href:"../../waku/standards/core/11/relay"},"11/WAKU2-RELAY"),", allows subscribing to traffic only with pubsub topic granularity and therefore is more resource-intensive. Relay subscription also allows the application instance to contribute to the overall routing infrastructure, which adds to its overall higher resource usage but benefits the ecosystem.")),(0,n.kt)("p",null,"Full clients SHOULD use relay protocol as preferred method to subscribe to pubsub topics matching the scopes:"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},"Global control"),(0,n.kt)("li",{parentName:"ol"},"Global content"),(0,n.kt)("li",{parentName:"ol"},"Global community control, if the client has activated the Status Communities feature"),(0,n.kt)("li",{parentName:"ol"},"Global community content, if the client has activated the Status Communities feature")),(0,n.kt)("p",null,"Light clients SHOULD use filter protocol to subscribe only to the content topics relevant to the user."),(0,n.kt)("h4",{id:"self-addressed-messages-1"},"Self-addressed messages"),(0,n.kt)("p",null,"Status clients (full or light) MUST NOT subscribe to topics for messages with self-addressed scopes.\nSee ",(0,n.kt)("a",{parentName:"p",href:"#self-addressed-messages-4"},"Self-addressed messages"),"."),(0,n.kt)("h4",{id:"large-messages-1"},"Large messages"),(0,n.kt)("p",null,"Status clients (full or light) SHOULD NOT subscribe to topics set aside for large messages.\nSee ",(0,n.kt)("a",{parentName:"p",href:"#large-messages-4"},"Large messages"),"."),(0,n.kt)("h3",{id:"publishing"},"Publishing"),(0,n.kt)("p",null,"The application MUST publish user and app generated messages via the Waku transport layer.\nThe specific Waku protocol used for publishing depends on the resource-availability of the client:"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},"Lightpush protocol, as specified in ",(0,n.kt)("a",{parentName:"li",href:"../../waku/standards/core/19/lightpush"},"19/WAKU2-LIGHTPUSH"),' allows publishing to a pubsub topic via an intermediate "full node" and is more appropriate for resource-restricted publishing.'),(0,n.kt)("li",{parentName:"ol"},"Relay protocol, as specified in ",(0,n.kt)("a",{parentName:"li",href:"../../waku/standards/core/11/relay"},"11/WAKU2-RELAY"),", allows publishing directly into the relay routing network and is therefore more resource-intensive.")),(0,n.kt)("p",null,"Full clients SHOULD use relay protocol to publish to pubsub topics matching the scopes:"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},"Global control"),(0,n.kt)("li",{parentName:"ol"},"Global content"),(0,n.kt)("li",{parentName:"ol"},"Global community control, if the client has activated the Status Communities feature"),(0,n.kt)("li",{parentName:"ol"},"Global community content, if the client has activated the Status Communities feature")),(0,n.kt)("p",null,"Light clients SHOULD use lightpush protocol to publish control and content messages."),(0,n.kt)("h4",{id:"self-addressed-messages-2"},"Self-addressed messages"),(0,n.kt)("p",null,"Status clients (full or light) MUST use lightpush protocol to publish self-addressed messages.\nSee ",(0,n.kt)("a",{parentName:"p",href:"#self-addressed-messages-4"},"Self-addressed messages"),"."),(0,n.kt)("h4",{id:"large-messages-2"},"Large messages"),(0,n.kt)("p",null,"Status clients (full or light) SHOULD use lightpush protocols to publish to pubsub topics set aside for large messages.\nSee ",(0,n.kt)("a",{parentName:"p",href:"#large-messages-4"},"Large messages"),"."),(0,n.kt)("h3",{id:"retrieving-historical-messages"},"Retrieving historical messages"),(0,n.kt)("p",null,"Status clients SHOULD use the store query protocol, as specified in ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/waku-org/specs/blob/8fea97c36c7bbdb8ddc284fa32aee8d00a2b4467/standards/core/store.md"},"WAKU2-STORE"),", to retrieve historical messages relevant to the client from store service nodes in the network."),(0,n.kt)("p",null,"Status clients SHOULD use ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/waku-org/specs/blob/8fea97c36c7bbdb8ddc284fa32aee8d00a2b4467/standards/core/store.md#content-filtered-queries"},"content filtered queries")," with ",(0,n.kt)("inlineCode",{parentName:"p"},"include_data")," set to ",(0,n.kt)("inlineCode",{parentName:"p"},"true"),",\nto retrieve the full contents of historical messages that the client may have missed during offline periods,\nor to populate the local message database when the client starts up for the first time."),(0,n.kt)("h4",{id:"store-queries-for-reliability"},"Store queries for reliability"),(0,n.kt)("p",null,"Status clients MAY use periodic content filtered queries with ",(0,n.kt)("inlineCode",{parentName:"p"},"include_data")," set to ",(0,n.kt)("inlineCode",{parentName:"p"},"false"),",\nto retrieve only the message hashes of past messages on content topics relevant to the client.\nThis can be used to compare the hashes available in the local message database with the hashes in the query response\nin order to identify possible missing messages.\nOnce the Status client has identified a set of missing message hashes\nit SHOULD use ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/waku-org/specs/blob/8fea97c36c7bbdb8ddc284fa32aee8d00a2b4467/standards/core/store.md#message-hash-lookup-queries"},"message hash lookup queries")," with ",(0,n.kt)("inlineCode",{parentName:"p"},"include_data")," set to ",(0,n.kt)("inlineCode",{parentName:"p"},"true"),"\nto retrieve the full contents of the missing messages based on the hash."),(0,n.kt)("p",null,"Status clients MAY use ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/waku-org/specs/blob/8fea97c36c7bbdb8ddc284fa32aee8d00a2b4467/standards/core/store.md#presence-queries"},"presence queries"),"\nto determine if one or more message hashes known to the client is present in the store service node.\nClients MAY use this method to determine if a message that originated from the client\nhas been successfully stored."),(0,n.kt)("h4",{id:"self-addressed-messages-3"},"Self-addressed messages"),(0,n.kt)("p",null,"Status clients (full or light) SHOULD use store queries (rather than subscriptions) to retrieve self-addressed messages relevant to that client.\nSee ",(0,n.kt)("a",{parentName:"p",href:"#self-addressed-messages-4"},"Self-addressed messages"),"."),(0,n.kt)("h4",{id:"large-messages-3"},"Large messages"),(0,n.kt)("p",null,"Status clients (full or light) SHOULD use store queries (rather than subscriptions) to retrieve large messages relevant to that client.\nSee ",(0,n.kt)("a",{parentName:"p",href:"#large-messages-4"},"Large messages"),"."),(0,n.kt)("h3",{id:"providing-services"},"Providing services"),(0,n.kt)("p",null,"Status clients MAY provide service-side protocols to other clients."),(0,n.kt)("p",null,"Full clients SHOULD mount\nthe filter service protocol (see ",(0,n.kt)("a",{parentName:"p",href:"../../waku/standards/core/12/filter"},"12/WAKU2-FILTER"),")\nand lightpush service protocol (see ",(0,n.kt)("a",{parentName:"p",href:"../../waku/standards/core/19/lightpush"},"19/WAKU2-LIGHTPUSH"),")\nin order to provide light subscription and publishing services to other clients\nfor each pubsub topic to which they have a relay subscription."),(0,n.kt)("p",null,"Full clients SHOULD mount\nthe peer exchange service protocol (see ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/waku-org/specs/blob/315264c202e0973476e2f1e2d0b01bea4fe1ad31/standards/core/peer-exchange.md"},"34/WAKU2-PEER-EXCHANGE"),")\nto provide light discovery services to other clients."),(0,n.kt)("p",null,"Status clients MAY mount the store query protocol as service node (see ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/waku-org/specs/blob/8fea97c36c7bbdb8ddc284fa32aee8d00a2b4467/standards/core/store.md"},"WAKU2-STORE"),")\nto store historical messages and\nprovide store services to other clients\nfor each pubsub topic to which they have a relay subscription"),(0,n.kt)("h3",{id:"self-addressed-messages-4"},"Self-addressed messages"),(0,n.kt)("p",null,"Messages with a ",(0,n.kt)("em",{parentName:"p"},"local")," functional scope (see ",(0,n.kt)("a",{parentName:"p",href:"#functional-scope"},"Functional scope"),"),\nalso known as ",(0,n.kt)("em",{parentName:"p"},"self-addressed")," messages,\nMUST be published to a distinct pubsub topic or a distinct ",(0,n.kt)("em",{parentName:"p"},"set")," of pubsub topics\nused exclusively for messages with local scope (see ",(0,n.kt)("a",{parentName:"p",href:"#pubsub-topics-and-sharding"},"Pubsub topics and sharding"),").\nStatus clients (full or light) MUST use lightpush protocol to publish self-addressed messages (see ",(0,n.kt)("a",{parentName:"p",href:"#publishing"},"Publishing"),").\nStatus clients (full or light) MUST NOT subscribe to topics for messages with self-addressed scopes (see ",(0,n.kt)("a",{parentName:"p",href:"#subscribing"},"Subscribing"),").\nStatus clients (full or light) SHOULD use store queries (rather than subscriptions) to retrieve self-addressed messages relevant to that client (see ",(0,n.kt)("a",{parentName:"p",href:"#retrieving-historical-messages"},"Retrieving historical messages"),")."),(0,n.kt)("h3",{id:"large-messages-4"},"Large messages"),(0,n.kt)("p",null,"The application MAY define separate pubsub topics for large messages.\nThese pubsub topics for large messages MAY be distinct for each functional scope (see ",(0,n.kt)("a",{parentName:"p",href:"#pubsub-topics-and-sharding"},"Pubsub topics and sharding"),").\nStatus clients (full or light) SHOULD use lightpush protocols to publish to pubsub topics set aside for large messages (see ",(0,n.kt)("a",{parentName:"p",href:"#publishing"},"Publishing"),").\nStatus clients (full or light) SHOULD NOT subscribe to topics set aside for large messages (see ",(0,n.kt)("a",{parentName:"p",href:"#subscribing"},"Subscribing"),").\nStatus clients (full or light) SHOULD use store queries (rather than subscriptions) to retrieve large messages relevant to that client (see ",(0,n.kt)("a",{parentName:"p",href:"#retrieving-historical-messages"},"Retrieving historical messages"),")."),(0,n.kt)("h4",{id:"chunking"},"Chunking"),(0,n.kt)("p",null,"The Status application MAY use a chunking mechanism to break down large payloads\ninto smaller segments for individual Waku transport.\nThe definition of a large message is up to the application.\nHowever, the maximum size for a ",(0,n.kt)("a",{parentName:"p",href:"../../waku/standards/core/14/message"},"14/WAKU2-MESSAGE"),' payload is 150KB.\nStatus application payloads that exceed this size MUST be chunked into smaller pieces\nand MUST be considered a "large message".'),(0,n.kt)("h2",{id:"copyright"},"Copyright"),(0,n.kt)("p",null,"Copyright and related rights waived via ",(0,n.kt)("a",{parentName:"p",href:"https://creativecommons.org/publicdomain/zero/1.0/"},"CC0"),"."),(0,n.kt)("h2",{id:"references"},"References"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"../55/1to1-chat"},"55/STATUS-1TO1-CHAT")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"../56/communities"},"56/STATUS-COMMUNITIES")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"../../waku/standards/core/10/waku2"},"10/WAKU2")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"../../waku/standards/core/11/relay"},"11/WAKU2-RELAY")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"../../waku/standards/core/12/filter"},"12/WAKU2-FILTER")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"../../waku/standards/core/14/message"},"14/WAKU2-MESSAGE")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"../../waku/informational/23/topics"},"23/WAKU2-TOPICS")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"../../waku/standards/core/19/lightpush"},"19/WAKU2-LIGHTPUSH")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"https://forum.vac.dev/t/end-to-end-reliability-for-scalable-distributed-logs/293/16"},"Scalable distributed log reliability")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"./status-mvds"},"STATUS-MVDS-USAGE")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("a",{parentName:"li",href:"https://github.com/waku-org/specs/blob/8fea97c36c7bbdb8ddc284fa32aee8d00a2b4467/standards/core/store.md"},"WAKU2-STORE"))))}u.isMDXComponent=!0},3905:(e,t,a)=>{a.d(t,{Zo:()=>c,kt:()=>m});var s=a(67294);function n(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function i(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var s=Object.getOwnPropertySymbols(e);t&&(s=s.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,s)}return a}function r(e){for(var t=1;t<arguments.length;t++){var a=null!=arguments[t]?arguments[t]:{};t%2?i(Object(a),!0).forEach((function(t){n(e,t,a[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(a)):i(Object(a)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(a,t))}))}return e}function l(e,t){if(null==e)return{};var a,s,n=function(e,t){if(null==e)return{};var a,s,n={},i=Object.keys(e);for(s=0;s<i.length;s++)a=i[s],t.indexOf(a)>=0||(n[a]=e[a]);return n}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(s=0;s<i.length;s++)a=i[s],t.indexOf(a)>=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(n[a]=e[a])}return n}var o=s.createContext({}),p=function(e){var t=s.useContext(o),a=t;return e&&(a="function"==typeof e?e(t):r(r({},t),e)),a},c=function(e){var t=p(e.components);return s.createElement(o.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return s.createElement(s.Fragment,{},t)}},d=s.forwardRef((function(e,t){var a=e.components,n=e.mdxType,i=e.originalType,o=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),d=p(a),m=n,h=d["".concat(o,".").concat(m)]||d[m]||u[m]||i;return a?s.createElement(h,r(r({ref:t},c),{},{components:a})):s.createElement(h,r({ref:t},c))}));function m(e,t){var a=arguments,n=t&&t.mdxType;if("string"==typeof e||n){var i=a.length,r=new Array(i);r[0]=d;var l={};for(var o in t)hasOwnProperty.call(t,o)&&(l[o]=t[o]);l.originalType=e,l.mdxType="string"==typeof e?e:n,r[1]=l;for(var p=2;p<i;p++)r[p]=a[p];return s.createElement.apply(null,r)}return s.createElement.apply(null,a)}d.displayName="MDXCreateElement"}}]); |