specs/draft/7.html

35 lines
24 KiB
HTML
Raw Normal View History

2021-11-16 14:54:10 +00:00
<!DOCTYPE html> <html lang="en-US"> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=Edge"> <title>7/GROUP-CHAT - Status Specification</title> <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon"> <link rel="stylesheet" href="/assets/css/just-the-docs-default.css"> <script type="text/javascript" src="/assets/js/vendor/lunr.min.js"></script> <script type="text/javascript" src="/assets/js/just-the-docs.js"></script> <meta name="viewport" content="width=device-width, initial-scale=1"> <!-- Begin Jekyll SEO tag v2.7.1 --> <title>7/GROUP-CHAT | Status Specification</title> <meta name="generator" content="Jekyll v4.2.1" /> <meta property="og:title" content="7/GROUP-CHAT" /> <meta property="og:locale" content="en_US" /> <link rel="canonical" href="https://specs.status.im/draft/7" /> <meta property="og:url" content="https://specs.status.im/draft/7" /> <meta property="og:site_name" content="Status Specification" /> <meta name="twitter:card" content="summary" /> <meta property="twitter:title" content="7/GROUP-CHAT" /> <script type="application/ld+json"> {"@type":"WebPage","url":"https://specs.status.im/draft/7","headline":"7/GROUP-CHAT","@context":"https://schema.org"}</script> <!-- End Jekyll SEO tag --> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-link" viewBox="0 0 24 24"> <title>Link</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"> <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path> </svg> </symbol> <symbol id="svg-search" viewBox="0 0 24 24"> <title>Search</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search"> <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-doc" viewBox="0 0 24 24"> <title>Document</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file"> <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline> </svg> </symbol> </svg> <div class="side-bar"> <div class="site-header"> <a href="https://specs.status.im/" class="site-title lh-tight"> Status Specification </a> <a href="#" id="menu-button" class="site-button"> <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg> </a> </div> <nav role="navigation" aria-label="Main" id="site-nav" class="site-nav"> <ul class="nav-list"><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="https://specs.status.im/stable/" class="nav-list-link">Stable specs</a><ul class="nav-list "><li class="nav-list-item "><a href="https://specs.status.im/stable/1" class="nav-list-link">1/CLIENT</a></li>
<span class="c1">// about group membership changes.</span>
<span class="kd">message</span> <span class="nc">MembershipUpdateMessage</span> <span class="p">{</span>
<span class="c1">// The chat id of the private group chat</span>
<span class="kt">string</span> <span class="na">chat_id</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
<span class="c1">// A list of events for this group chat, first 65 bytes are the signature, then is a </span>
<span class="c1">// protobuf encoded MembershipUpdateEvent</span>
<span class="k">repeated</span> <span class="kt">bytes</span> <span class="na">events</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
<span class="c1">// An optional chat message</span>
<span class="n">ChatMessage</span> <span class="kd">message</span> <span class="o">=</span> <span class="mi">3</span><span class="p">;</span>
<span class="p">}</span>
<span class="kd">message</span> <span class="nc">MembershipUpdateEvent</span> <span class="p">{</span>
<span class="c1">// Lamport timestamp of the event as described in [Status Payload Specs](status-payload-specs.md#clock-vs-timestamp-and-message-ordering)</span>
<span class="kt">uint64</span> <span class="na">clock</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
<span class="c1">// List of public keys of the targets of the action</span>
<span class="k">repeated</span> <span class="kt">string</span> <span class="na">members</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
<span class="c1">// Name of the chat for the CHAT_CREATED/NAME_CHANGED event types</span>
<span class="kt">string</span> <span class="na">name</span> <span class="o">=</span> <span class="mi">3</span><span class="p">;</span>
<span class="c1">// The type of the event</span>
<span class="n">EventType</span> <span class="na">type</span> <span class="o">=</span> <span class="mi">4</span><span class="p">;</span>
<span class="kd">enum</span> <span class="n">EventType</span> <span class="p">{</span>
<span class="na">UNKNOWN</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="na">CHAT_CREATED</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="c1">// See [CHAT_CREATED](#chat-created)</span>
<span class="na">NAME_CHANGED</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span> <span class="c1">// See [NAME_CHANGED](#name-changed)</span>
<span class="na">MEMBERS_ADDED</span> <span class="o">=</span> <span class="mi">3</span><span class="p">;</span> <span class="c1">// See [MEMBERS_ADDED](#members-added)</span>
<span class="na">MEMBER_JOINED</span> <span class="o">=</span> <span class="mi">4</span><span class="p">;</span> <span class="c1">// See [MEMBER_JOINED](#member-joined)</span>
<span class="na">MEMBER_REMOVED</span> <span class="o">=</span> <span class="mi">5</span><span class="p">;</span> <span class="c1">// See [MEMBER_REMOVED](#member-removed)</span>
<span class="na">ADMINS_ADDED</span> <span class="o">=</span> <span class="mi">6</span><span class="p">;</span> <span class="c1">// See [ADMINS_ADDED](#admins-added)</span>
<span class="na">ADMIN_REMOVED</span> <span class="o">=</span> <span class="mi">7</span><span class="p">;</span> <span class="c1">// See [ADMIN_REMOVED](#admin-removed)</span>
<span class="p">}</span>
<span class="p">}</span>
2021-11-16 15:16:16 +00:00
</code></pre></div></div> <h3 id="payload"> <a href="#payload" class="anchor-heading" aria-labelledby="payload"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Payload </h3> <p><code class="language-plaintext highlighter-rouge">MembershipUpdateMessage</code>:</p> <div class="table-wrapper"><table> <thead> <tr> <th>Field</th> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>1</td> <td>chat-id</td> <td><code class="language-plaintext highlighter-rouge">string</code></td> <td>The chat id of the chat where the change is to take place</td> </tr> <tr> <td>2</td> <td>events</td> <td>See details</td> <td>A list of events that describe the membership changes, in their encoded protobuf form</td> </tr> <tr> <td>3</td> <td>message</td> <td><code class="language-plaintext highlighter-rouge">ChatMessage</code></td> <td>An optional message, described in <a href="./6-payloads.md#message">Message</a></td> </tr> </tbody> </table></div> <p><code class="language-plaintext highlighter-rouge">MembershipUpdateEvent</code>:</p> <div class="table-wrapper"><table> <thead> <tr> <th>Field</th> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>1</td> <td>clock</td> <td><code class="language-plaintext highlighter-rouge">uint64</code></td> <td>The clock value of the event</td> </tr> <tr> <td>2</td> <td>members</td> <td><code class="language-plaintext highlighter-rouge">[]string</code></td> <td>An optional list of hex encoded (prefixed with <code class="language-plaintext highlighter-rouge">0x</code>) public keys, the targets of the action</td> </tr> <tr> <td>3</td> <td>name</td> <td><code class="language-plaintext highlighter-rouge">name</code></td> <td>An optional name, for those events that make use of it</td> </tr> <tr> <td>4</td> <td>type</td> <td><code class="language-plaintext highlighter-rouge">EventType</code></td> <td>The type of event sent, described below</td> </tr> </tbody> </table></div> <h3 id="chat-id"> <a href="#chat-id" class="anchor-heading" aria-labelledby="chat-id"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Chat ID </h3> <p>Each membership update MUST be sent with a corresponding <code class="language-plaintext highlighter-rouge">chatId</code>. The format of this chat ID MUST be a string of <a href="https://tools.ietf.org/html/rfc4122">UUID</a>, concatenated with the hex-encoded public key of the creator of the chat, joined by <code class="language-plaintext highlighter-rouge">-</code>. This chatId MUST be validated by all clients, and MUST be discarded if it does not follow these rules.</p> <h3 id="signature"> <a href="#signature" class="anchor-heading" aria-labelledby="signature"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Signature </h3> <p>The node calculates the signature for each event by encoding each <code class="language-plaintext highlighter-rouge">MembershipUpdateEvent</code> in its protobuf representation and prepending the bytes of the chatID, lastly the node signs the <code class="language-plaintext highlighter-rouge">Keccak256</code> of the bytes using the private key by the author and added to the <code class="language-plaintext highlighter-rouge">events</code> field of MembershipUpdateMessage.</p> <h3 id="group-membership-event"> <a href="#group-membership-event" class="anchor-heading" aria-labelledby="group-membership-event"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Group membership event </h3> <p>Any <code class="language-plaintext highlighter-rouge">group membership</code> event received MUST be verified by calculating the signature as per the method described above. The author MUST be extracted from it, if the verification fails the event MUST be discarded.</p> <h4 id="chat_created"> <a href="#chat_created" class="anchor-heading" aria-labelledby="chat_created"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> CHAT_CREATED </h4> <p>Cha