Definitions # Term Description Peer The other nodes that a node is connected to. Record Defines a payload element of either the type OFFER, REQUEST, MESSAGE or ACK Node Some process that is able to store data, do processing and communicate for MVDS.">
Definitions # Term Description Peer The other nodes that a node is connected to. Record Defines a payload element of either the type OFFER, REQUEST, MESSAGE or ACK Node Some process that is able to store data, do processing and communicate for MVDS." />
Dean Eigenmann <ahref="mailto:dean@status.im">dean@status.im</a>
,
Oskar Thorén <ahref="mailto:oskar@status.im">oskar@status.im</a>
</li>
</ul><p>In this specification, we describe a minimum viable protocol for data synchronization inspired by the Bramble Synchronization Protocol<supid="fnref:1"><ahref="#fn:1"class="footnote-ref"role="doc-noteref">1</a></sup>. This protocol is designed to ensure reliable messaging between peers across an unreliable peer-to-peer (P2P) network where they may be unreachable or unresponsive.</p>
<p>We present a reference implementation<supid="fnref:2"><ahref="#fn:2"class="footnote-ref"role="doc-noteref">2</a></sup> including a simulation to demonstrate its performance.</p>
<h2id="definitions">
Definitions
<aclass="anchor"href="#definitions">#</a>
</h2>
<table>
<thead>
<tr>
<th>Term</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Peer</strong></td>
<td>The other nodes that a node is connected to.</td>
</tr>
<tr>
<td><strong>Record</strong></td>
<td>Defines a payload element of either the type <code>OFFER</code>, <code>REQUEST</code>, <code>MESSAGE</code> or <code>ACK</code></td>
</tr>
<tr>
<td><strong>Node</strong></td>
<td>Some process that is able to store data, do processing and communicate for MVDS.</td>
</tr>
</tbody>
</table>
<h2id="wire-protocol">
Wire Protocol
<aclass="anchor"href="#wire-protocol">#</a>
</h2>
<h3id="secure-transport">
Secure Transport
<aclass="anchor"href="#secure-transport">#</a>
</h3>
<p>This specification does not define anything related to the transport of packets. It is assumed that this is abstracted in such a way that any secure transport protocol could be easily implemented. Likewise, properties such as confidentiality, integrity, authenticity and forward secrecy are assumed to be provided by a layer below.</p>
<h3id="payloads">
Payloads
<aclass="anchor"href="#payloads">#</a>
</h3>
<p>Payloads are implemented using <ahref="https://developers.google.com/protocol-buffers/">protocol buffers v3</a>.</p>
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#66d9ef">bytes</span> body <spanstyle="color:#f92672">=</span><spanstyle="color:#ae81ff">6003</span>;<spanstyle="color:#960050;background-color:#1e0010">
</span></span></span></code></pre></div><p><em>The payload field numbers are kept more “unique” to ensure no overlap with other protocol buffers.</em></p>
<p>Each payload contains the following fields:</p>
<ul>
<li><strong>Acks:</strong> This field contains a list (can be empty) of <code>message identifiers</code> informing the recipient that sender holds a specific message.</li>
<li><strong>Offers:</strong> This field contains a list (can be empty) of <code>message identifiers</code> that the sender would like to give to the recipient.</li>
<li><strong>Requests:</strong> This field contains a list (can be empty) of <code>message identifiers</code> that the sender would like to receive from the recipient.</li>
<li><strong>Messages:</strong> This field contains a list of messages (can be empty).</li>
</ul>
<p><strong>Message Identifiers:</strong> Each <code>message</code> has a message identifier calculated by hashing the <code>group_id</code>, <code>timestamp</code> and <code>body</code> fields as follows:</p>
</code></pre><p><strong>Group Identifiers:</strong> Each <code>message</code> is assigned into a <strong>group</strong> using the <code>group_id</code> field, groups are independent synchronization contexts between peers.</p>
<p>The current <code>HASH</code> function used is <code>sha256</code>.</p>
<h2id="synchronization">
Synchronization
<aclass="anchor"href="#synchronization">#</a>
</h2>
<h3id="state">
State
<aclass="anchor"href="#state">#</a>
</h3>
<p>We refer to <code>state</code> as set of records for the types <code>OFFER</code>, <code>REQUEST</code> and <code>MESSAGE</code> that every node SHOULD store per peer. <code>state</code> MUST NOT contain <code>ACK</code> records as we do not retransmit those periodically. The following information is stored for records:</p>
<ul>
<li><strong>Type</strong> - Either <code>OFFER</code>, <code>REQUEST</code> or <code>MESSAGE</code></li>
<li><strong>Send Count</strong> - The amount of times a record has been sent to a peer.</li>
<li><strong>Send Epoch</strong> - The next epoch at which a record can be sent to a peer.</li>
</ul>
<h3id="flow">
Flow
<aclass="anchor"href="#flow">#</a>
</h3>
<p>A maximum of one payload SHOULD be sent to peers per epoch, this payload contains all <code>ACK</code>, <code>OFFER</code>, <code>REQUEST</code> and <code>MESSAGE</code> records for the specific peer. Payloads are created every epoch, containing reactions to previously received records by peers or new records being sent out by nodes.</p>
<p>Nodes MAY have two modes with which they can send records: <code>BATCH</code> and <code>INTERACTIVE</code> mode. The following rules dictate how nodes construct payloads every epoch for any given peer for both modes.</p>
<blockquote>
<p><em><strong>NOTE:</strong> A node may send messages both in interactive and in batch mode.</em></p>
</blockquote>
<h4id="interactive-mode">
Interactive Mode
<aclass="anchor"href="#interactive-mode">#</a>
</h4>
<ul>
<li>A node initially offers a <code>MESSAGE</code> when attempting to send it to a peer. This means an <code>OFFER</code> is added to the next payload and state for the given peer.</li>
<li>When a node receives an <code>OFFER</code>, a <code>REQUEST</code> is added to the next payload and state for the given peer.</li>
<li>When a node receives a <code>REQUEST</code> for a previously sent <code>OFFER</code>, the <code>OFFER</code> is removed from the state and the corresponding <code>MESSAGE</code> is added to the next payload and state for the given peer.</li>
<li>When a node receives a <code>MESSAGE</code>, the <code>REQUEST</code> is removed from the state and an <code>ACK</code> is added to the next payload for the given peer.</li>
<li>When a node receives an <code>ACK</code>, the <code>MESSAGE</code> is removed from the state for the given peer.</li>
<li>All records that require retransmission are added to the payload, given <code>Send Epoch</code> has been reached.</li>
</ul>
<!-- raw HTML omitted -->
<h4id="batch-mode">
Batch Mode
<aclass="anchor"href="#batch-mode">#</a>
</h4>
<ol>
<li>When a node sends a <code>MESSAGE</code>, it is added to the next payload and the state for the given peer.</li>
<li>When a node receives a <code>MESSAGE</code>, an <code>ACK</code> is added to the next payload for the corresponding peer.</li>
<li>When a node receives an <code>ACK</code>, the <code>MESSAGE</code> is removed from the state for the given peer.</li>
<li>All records that require retransmission are added to the payload, given <code>Send Epoch</code> has been reached.</li>
</ol>
<!-- raw HTML omitted -->
<!-- raw HTML omitted -->
<blockquote>
<p><em><strong>NOTE:</strong> Batch mode is higher bandwidth whereas interactive mode is higher latency.</em></p>
</blockquote>
<!-- raw HTML omitted -->
<h3id="retransmission">
Retransmission
<aclass="anchor"href="#retransmission">#</a>
</h3>
<p>The record of the type <code>Type</code> SHOULD be retransmitted every time <code>Send Epoch</code> is smaller than or equal to the current epoch.</p>
<p><code>Send Epoch</code> and <code>Send Count</code> MUST be increased every time a record is retransmitted. Although no function is defined on how to increase <code>Send Epoch</code>, it SHOULD be exponentially increased until reaching an upper bound where it then goes back to a lower epoch in order to prevent a record’s <code>Send Epoch</code>’s from becoming too large.</p>
<blockquote>
<p><em><strong>NOTE:</strong> We do not retransmission <code>ACK</code>s as we do not know when they have arrived, therefore we simply resend them every time we receive a <code>MESSAGE</code>.</em></p>
<p>MVDS has been formally specified using TLA+: <ahref="https://github.com/vacp2p/formalities/tree/master/MVDS">https://github.com/vacp2p/formalities/tree/master/MVDS</a>.</p>
<h2id="acknowledgments">
Acknowledgments
<aclass="anchor"href="#acknowledgments">#</a>
</h2>
<ul>
<li>Preston van Loon</li>
<li>Greg Markou</li>
<li>Rene Nayman</li>
<li>Jacek Sieka</li>
</ul>
<h2id="copyright">
Copyright
<aclass="anchor"href="#copyright">#</a>
</h2>
<p>Copyright and related rights waived via <ahref="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
<p>akwizgran et al. <ahref="https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md">BSP</a>. Briar. <ahref="#fnref:1"class="footnote-backref"role="doc-backlink">↩︎</a></p>
