V0.14.0 Guide - LLMQs (#122)

* Guide - Start adding LLMQ DKG data flow details

* Guide - Add Quorum description

* Content - Add descriptions for LLMQ messages

* Content - Add qjustify description

* Formatting fix

* Guide - placeholder for LLMQ signing session details

* Guide - Add LLMQ signing session data flow draft

* Guide - Minor quorum adjustments

* Guide - cross ref fixes

* Guide - Add ChainLocks info

* Content - Add DIP8 references

* Content - DIP Table update

_autocrossref.yaml

@@ -290,6 +290,13 @@ CVE-2012-2459:
 
 ## DIPs in numerical order; don't use padding zeros (e.g. DIP1 not DIP0001)
 DIP1:
+DIP2:
+DIP3:
+DIP4:
+DIP5:
+DIP6:
+DIP7:
+DIP8:
 
 ## RPCs
 '`abandontransaction`': rpc abandontransaction

_config.yml

@@ -517,6 +517,7 @@ devsearches:
     - "DIP5: Blockchain Users": "https://github.com/dashpay/dips/blob/master/dip-0005.md"
     - "DIP6: Long-Living Masternode Quorums": "https://github.com/dashpay/dips/blob/master/dip-0006.md"
     - "DIP7: LLMQ Signing Requests / Sessions": "https://github.com/dashpay/dips/blob/master/dip-0007.md"
+    - "DIP8: ChainLocks": "https://github.com/dashpay/dips/blob/master/dip-0008.md"
 
   ## Bitcoin P2P Protocol messages documented on Bitcoin.org
   "P2P Messages":

_includes/devdoc/guide_dash_features.md

@@ -295,6 +295,33 @@ value of only 0.00000546 DASH as shown by the calculation below.
 [Example Testnet PrivateSend transaction spending 546 duffs](https://testnet-insight.dashevo.org/insight/address/yWWNYVEQ84RM1xXJekj62wJPF3h1TKh9fS)
 
 
+### ChainLocks
+{% include helpers/subhead-links.md %}
+
+{% autocrossref %}
+
+Dash's ChainLock feature leverages [LLMQ Signing Requests/Sessions](#llmq-signing-session)
+to reduce uncertainty when receiving funds and remove the possibility of 51%
+mining attacks.
+
+For each block, an LLMQ of a few hundred masternodes is selected and each
+participating member signs the first block that it sees extending the active
+chain at the current height. If enough members (e.g. >= 60%) see the same block
+as the first block, they will be able to create a `clsig` message and propagate
+it to all nodes in the network.
+
+If a valid `clsig` message is received by a node, it must reject all blocks (and
+any descendants) at the same height that do not match the block specified in the
+`clsig` message. This makes the decision on the active chain quick, easy and
+unambiguous. It also makes reorganizations below this block impossible.
+
+Please read [DIP8 ChainLocks](https://github.com/dashpay/dips/blob/master/dip-0008.md)
+for additional details.
+
+
+{% endautocrossref %}
+
+
 ### Masternode Payment
 {% include helpers/subhead-links.md %}
 
@@ -651,18 +678,101 @@ to update the masternode info and prevent it from entering a `MASTERNODE_WATCHDO
 {% endautocrossref %}
 
 
-### Quorum Selection
+### Masternode Quorums
+{% include helpers/subhead-links.md %}
+
+Dash's masternode quorums are used to facilitate the operation of masternode provided
+features in a decentralized, deterministic way. The original quorums (used
+largely for InstantSend and masternode payments) were ephemeral and used for a
+single purpose (e.g. voting on one specific InstantSend transaction).
+
+Dash Core 0.14 (protocol version 70214) introduced the Long Living Masternode
+Quorums (LLMQ) that are described in detail by [DIP6](https://github.com/dashpay/dips/blob/master/dip-0006.md).
+These LLMQs are deterministic subsets of the global deterministic masternode
+list that are formed via a distributed key generation (DKG) protocol and remain
+active for a long periods of time (e.g. hours to days).
+
+The main task of LLMQs is to perform threshold signing of consensus-related
+messages (e.g. ChainLocks).
+
+##### LLMQ Creation (DKG)
+<!-- no subhead-links here -->
+
+{% autocrossref %}
+
+The following table details the data flow of P2P messages exchanged during
+the distributed key generation (DKG) protocol used to establish an LLMQ.
+
+NOTE: With the exception of the final step (`qfcommit` message broadcast), the message
+exchanges happen only between masternodes participating in the DKG process via
+the Intra-Quorum communication process described in the DIP.
+
+*Quorum DKG Data Flow*
+
+| **Masternode** | **Direction**  | **Peers**   | **Description** |
+| **[Initialization Phase](https://github.com/dashpay/dips/blob/master/dip-0006.md#1-initialization-phase)**| | | **Deterministically evaluate if quorum participation necessary** |
+| | | | Each quorum participant establishes connections to a set of quorum participants [as described in DIP6](https://github.com/dashpay/dips/blob/master/dip-0006.md#building-the-set-of-deterministic-connections) |
+| **[Contribution Phase](https://github.com/dashpay/dips/blob/master/dip-0006.md#2-contribution-phase)** | | | **Send quorum contributions (intra-quorum communication)** |
+|`inv` message (qcontrib)                        | → |                              | Masternode sends inventory for its quorum contribution _to other masternodes in the quorum_
+|                                                | ← | `getdata` message (qcontrib) | Peer(s) respond with request for quorum contribution
+| `qcontrib` message                             | → |                              | Masternode sends the requested quorum contribution
+| **[Complaining Phase](https://github.com/dashpay/dips/blob/master/dip-0006.md#3-complaining-phase)** | | | **Send complaints for any peers with invalid or missing contributions (intra-quorum communication)** |
+|`inv` message (qcomplaint)                      | → |                              | Masternode sends inventory for any complaints _to other masternodes in the quorum_
+|                                                | ← | `getdata` message (qcomplaint) | Peer(s) respond with request for quorum complaints
+| `qcomplaint` message                           | → |                              | Masternode sends the requested complaints
+| **[Justification Phase](https://github.com/dashpay/dips/blob/master/dip-0006.md#4-justification-phase)** | | | **Send justification responses for any complaints against own contributions (intra-quorum communication)** |
+|`inv` message (qjustify)                        | → |                              | Masternode sends inventory for any justifications _to other masternodes in the quorum_
+|                                                | ← | `getdata` message (qjustify) | Peer(s) respond with request for quorum justifications
+| `qjustify` message                             | → |                              | Masternode sends the requested justifications
+| **[Commitment Phase](https://github.com/dashpay/dips/blob/master/dip-0006.md#5-commitment-phase)** | | | **Send premature commitment containing the quorum public key (intra-quorum communication)** |
+|`inv` message (qpcommit)                        | → |                              | Masternode sends inventory for its premature commitment _to other masternodes in the quorum_
+|                                                | ← | `getdata` message (qpcommit) | Peer(s) respond with request for quorum premature commitment
+| `qpcommit` message                             | → |                              | Masternode sends the requested premature commitment
+| **[Finalization Phase](https://github.com/dashpay/dips/blob/master/dip-0006.md#6-finalization-phase)** | | | **Send final commitment containing the quorum public key** |
+|`inv` message (qfcommit)                        | → |                              | Masternode sends inventory for its premature commitment **to all peers**
+|                                                | ← | `getdata` message (qfcommit) | Peer(s) respond with request for quorum final commitment
+| `qfcommit` message                             | → |                              | Masternode sends the requested final commitment
+
+{% endautocrossref %}
+
+
+##### LLMQ Signing Session
+<!-- no subhead-links here -->
+
+{% autocrossref %}
+
+The following table details the data flow of P2P messages exchanged during
+an LLMQ signing session. These sessions take advantage of BLS threshold signatures
+to enable quorums to sign arbitrary messages. For example, Dash Core 0.14 uses
+this capability to create the quorum signature found in the `clsig` message that
+enables ChainLocks.
+
+Please read [DIP7 LLMQ Signing Requests / Sessions](https://github.com/dashpay/dips/blob/master/dip-0007.md)
+for additional details.
+
+*LLMQ Signing Session Data Flow*
+
+| **Masternode** | **Direction**  | **Peers**   | **Description** |
+| **[Siging Request Phase](https://github.com/dashpay/dips/blob/master/dip-0007.md#signing-request)** | | | Request quorum signing of a message (e.g. InstantSend transaction input) (intra-quorum communication) |
+| `qsigsesann` message                             | → |                              | Masternode sends a signing session announcement _to other masternodes in the quorum_
+| **[Share Propagation Phase](https://github.com/dashpay/dips/blob/master/dip-0007.md#propagating-signature<!--noref-->-shares)** | | | Members exchange signature shares within the quorum (intra-quorum communication) |
+| `qsigsinv` message                             | → |                              | Masternode sends one or more quorum signature share inventories _to other masternodes in the quorum_<br>_May occur multiple times in this phase_
+|                                                | ← | `qgetsigs` message (qcontrib) | Peer(s) respond with request for signature shares<br>_May occur multiple times in this phase_
+| `qbsigs` message                             | → |                              | Masternode sends the requested batched signature share(s)<br>_May occur multiple times in this phase_
+| **[Threshold Signature Recovery Phase](https://github.com/dashpay/dips/blob/master/dip-0007.md#recovered-threshold-signatures<!--noref-->)** | | | A recovered signature is created by a quorum member once valid signature shares from at least the threshold number of members have been received |
+| `qsigrec` message                             | → |                              | Masternode sends the quorum recovered signature **to all peers** (except those that have asked to be excluded via a `qsendrecsigs` message)
+
+{% endautocrossref %}
+
+#### Quorum Selection
 {% include helpers/subhead-links.md %}
 
 {% autocrossref %}
 
-Dash quorums are used to facilitate the operation of masternode provided
-features in a decentralized, deterministic way.
-
 | Quorum Type | Members | Consensus | Description |
 | ----------- | ------- | --------- | ----------- |
-| InstantSend | 10      | Majority  | A set of 10 masternodes are selected for _each_ input of the InstantSend transaction. A majority (6+) of them must agree to lock the input. If all inputs in the transaction can be locked, it becomes a successful InstantSend.
+| Classic<br>(non-LLMQ) InstantSend | 10      | Majority  | A set of 10 masternodes are selected for _each_ input of the InstantSend transaction. A majority (6+) of them must agree to lock the input. If all inputs in the transaction can be locked, it becomes a successful InstantSend.
 | MN Payments | 10      | Majority | A set of 10 masternodes are selected for each block. A majority (6+) of them must agree on the masternode payee for the next block.
-| MN Broadcast | 10      | Majority | If a majority (6+) of nodes agree, a new `mnb` message is not required.
+| MN Broadcast | 10      | Majority | _Deprecated by DIP3 (deterministic masternode list) in Dash Core 0.13._<br><br>If a majority (6+) of nodes agree, a new `mnb` message is not required.
 
 {% endautocrossref %}

_includes/devdoc/ref_p2p_networking.md

@@ -3115,7 +3115,11 @@ e9015178f6d642b7b25c4fd7c4ef3030 ........... BLS signature (Operator Key)
 intra-quorum communication and is only sent to the masternodes in the LLMQ and
 nodes that are monitoring in Watch Mode for auditing/debugging purposes.
 
-The `qjustify` message is used to...
+The `qjustify` message is used to respond to complaints. This provides a way for
+nodes that have been complained about to offer proof of correct behavior. If
+a valid justification is not provided, all other nodes mark it as a bad. If a
+valid justification is provided, the complaining node is marked as bad instead
+(since it submitted a bad complaint).
 
 | Bytes | Name | Data type | Description |
 | --- | --- | --- | --- |

_includes/layout/base/dip-table.html

@@ -35,21 +35,21 @@ th.tg-sort-header::-moz-selection { background:transparent; }th.tg-sort-header::
     <td class="tg-b7b8">Consensus</td>
     <td class="tg-b7b8"><a href="https://github.com/dashpay/dips/blob/master/dip-0002.md">Special Transactions</a></td>
     <td class="tg-b7b8">Standard</td>
-    <td class="tg-b7b8">Proposed</td>
+    <td class="tg-b7b8">Active</td>
   </tr>
   <tr>
     <td class="tg-jo0b">3</td>
     <td class="tg-b7b8">Consensus</td>
     <td class="tg-b7b8"><a href="https://github.com/dashpay/dips/blob/master/dip-0003.md">Deterministic Masternode Lists</a></td>
     <td class="tg-b7b8">Standard</td>
-    <td class="tg-b7b8">Proposed</td>
+    <td class="tg-b7b8">Active</td>
   </tr>
   <tr>
     <td class="tg-jo0b">4</td>
     <td class="tg-b7b8">Consensus</td>
     <td class="tg-b7b8"><a href="https://github.com/dashpay/dips/blob/master/dip-0004.md">Simplified Verification of Deterministic Masternode Lists</a></td>
     <td class="tg-b7b8">Standard</td>
-    <td class="tg-b7b8">Proposed</td>
+    <td class="tg-b7b8">Active</td>
   </tr>
   <tr>
     <td class="tg-jo0b">5</td>
@@ -72,6 +72,13 @@ th.tg-sort-header::-moz-selection { background:transparent; }th.tg-sort-header::
     <td class="tg-b7b8">Standard</td>
     <td class="tg-b7b8">Proposed</td>
   </tr>
+  <tr>
+    <td class="tg-jo0b">8</td>
+    <td class="tg-b7b8">Consensus</td>
+    <td class="tg-b7b8"><a href="https://github.com/dashpay/dips/blob/master/dip-0008.md">ChainLocks</a></td>
+    <td class="tg-b7b8">Standard</td>
+    <td class="tg-b7b8">Proposed</td>
+  </tr>
 </table></div>
 
 <script type="text/javascript" charset="utf-8">var TgTableSort=window.TgTableSort||function(n,t){"use strict";function r(n,t){for(var e=[],o=n.childNodes,i=0;i<o.length;++i){var u=o[i];if("."==t.substring(0,1)){var a=t.substring(1);f(u,a)&&e.push(u)}else u.nodeName.toLowerCase()==t&&e.push(u);var c=r(u,t);e=e.concat(c)}return e}function e(n,t){var e=[],o=r(n,"tr");return o.forEach(function(n){var o=r(n,"td");t>=0&&t<o.length&&e.push(o[t])}),e}function o(n){return n.textContent||n.innerText||""}function i(n){return n.innerHTML||""}function u(n,t){var r=e(n,t);return r.map(o)}function a(n,t){var r=e(n,t);return r.map(i)}function c(n){var t=n.className||"";return t.match(/\S+/g)||[]}function f(n,t){return-1!=c(n).indexOf(t)}function s(n,t){f(n,t)||(n.className+=" "+t)}function d(n,t){if(f(n,t)){var r=c(n),e=r.indexOf(t);r.splice(e,1),n.className=r.join(" ")}}function v(n){d(n,L),d(n,E)}function l(n,t,e){r(n,"."+E).map(v),r(n,"."+L).map(v),e==T?s(t,E):s(t,L)}function g(n){return function(t,r){var e=n*t.str.localeCompare(r.str);return 0==e&&(e=t.index-r.index),e}}function h(n){return function(t,r){var e=+t.str,o=+r.str;return e==o?t.index-r.index:n*(e-o)}}function m(n,t,r){var e=u(n,t),o=e.map(function(n,t){return{str:n,index:t}}),i=e&&-1==e.map(isNaN).indexOf(!0),a=i?h(r):g(r);return o.sort(a),o.map(function(n){return n.index})}function p(n,t,r,o){for(var i=f(o,E)?N:T,u=m(n,r,i),c=0;t>c;++c){var s=e(n,c),d=a(n,c);s.forEach(function(n,t){n.innerHTML=d[u[t]]})}l(n,o,i)}function x(n,t){var r=t.length;t.forEach(function(t,e){t.addEventListener("click",function(){p(n,r,e,t)}),s(t,"tg-sort-header")})}var T=1,N=-1,E="tg-sort-asc",L="tg-sort-desc";return function(t){var e=n.getElementById(t),o=r(e,"tr"),i=o.length>0?r(o[0],"td"):[];0==i.length&&(i=r(o[0],"th"));for(var u=1;u<o.length;++u){var a=r(o[u],"td");if(a.length!=i.length)return}x(e,i)}}(document);document.addEventListener("DOMContentLoaded",function(n){TgTableSort("tg-3Vxlz")});</script>

_includes/references.md

@@ -266,18 +266,18 @@ http://opensource.org/licenses/MIT.
 [notfound message]: /en/developer-reference#notfound "A P2P protocol message sent to indicate that the requested data was not available"
 [ping message]: /en/developer-reference#ping "A P2P network message used to see if the remote host is still connected"
 [pong message]: /en/developer-reference#pong "A P2P network message used to reply to a P2P network ping message"
-[qbsigs message]: /en/developer-reference#qbsigs "A P2P network message used to ..."
+[qbsigs message]: /en/developer-reference#qbsigs "A P2P network message used to to send batched LLMQ signature shares"
-[qcomplaint message]: /en/developer-reference#qcomplaint "A P2P network message used to ..."
+[qcomplaint message]: /en/developer-reference#qcomplaint "A P2P network message used to send a complaint about another masternodes DKG contribution"
-[qcontrib message]: /en/developer-reference#qcontrib "A P2P network message used to ..."
+[qcontrib message]: /en/developer-reference#qcontrib "A P2P network message used to send LLMQ DKG contributions"
-[qdebugstatus message]: /en/developer-reference#qdebugstatus "A P2P network message used to ..."
+[qdebugstatus message]: /en/developer-reference#qdebugstatus "A P2P network message used to debug quorums"
 [qfcommit message]: /en/developer-reference#qfcommit "A P2P network message used to finalize the members of a long-living masternode quorum (LLMQ)"
-[qgetsigs message]: /en/developer-reference#qgetsigs "A P2P network message used to ..."
+[qgetsigs message]: /en/developer-reference#qgetsigs "A P2P network message used to request signature shares"
-[qjustify message]: /en/developer-reference#qjustify "A P2P network message used to ..."
+[qjustify message]: /en/developer-reference#qjustify "A P2P network message used to respond to another masternodes DKG complaint"
-[qpcommit message]: /en/developer-reference#qpcommit "A P2P network message used to ..."
+[qpcommit message]: /en/developer-reference#qpcommit "A P2P network message used to send an LLMQ premature commitment"
-[qsigrec message]: /en/developer-reference#qsigrec "A P2P network message used to ..."
+[qsigrec message]: /en/developer-reference#qsigrec "A P2P network message used to send recovered quorum signatures"
-[qsigsesann message]: /en/developer-reference#qsigsesann "A P2P network message used to ..."
+[qsigsesann message]: /en/developer-reference#qsigsesann "A P2P network message used to announce signing session details"
-[qsigsinv message]: /en/developer-reference#qsigsinv "A P2P network message used to ..."
+[qsigsinv message]: /en/developer-reference#qsigsinv "A P2P network message used to announce quorum signature share inventories"
-[qwatch message]: /en/developer-reference#qwatch "A P2P network message used to ..."
+[qwatch message]: /en/developer-reference#qwatch "A P2P network message used to ask a peer to relay LLMQ DKG messages"
 [reject message]: /en/developer-reference#reject "A P2P network message used to indicate a previously-received message was rejected for some reason"
 [sendcmpct message]: /en/developer-reference#sendcmpct "A P2P network message used to request new blocks be announced as compact blocks"
 [senddsq message]: /en/developer-reference#senddsq "A P2P network message used to request that DSQ mixing messages be provided"
@@ -381,6 +381,7 @@ http://opensource.org/licenses/MIT.
 [DIP5]: https://github.com/dashpay/dips/blob/master/dip-0005.md
 [DIP6]: https://github.com/dashpay/dips/blob/master/dip-0006.md
 [DIP7]: https://github.com/dashpay/dips/blob/master/dip-0007.md
+[DIP8]: https://github.com/dashpay/dips/blob/master/dip-0008.md
 
 {% comment %}<!-- Other external site links; alphabetical order -->{% endcomment %}
 [#bitcoin]: https://webchat.freenode.net/?channels=bitcoin&uio=d4