added BEEFY consensus message, networking and gossip messages related…

… to BEEFY

docs/chap-networking.md

@@ -197,6 +197,13 @@ The prefixes on those substreams are known as protocol identifiers and are used
   For backward compatibility reasons, `/paritytech/grandpa/1` is also a valid substream for those messages.
 :::
 
+- `/91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3/beefy/1` - a substream/notification protocol which sends signed BEEFY statements, as described in [Section -sec-num-ref-](sect-finality#sect-grandpa-beefy), to connected peers. This is a *Notification* substream.
+
+  The messages are specified in [Section -sec-num-ref-](chap-networking#sect-msg-grandpa-beefy).
+
+:::info
+  For backwards compatibility reasons, `/paritytech/beefy/1` is also a valid substream for those messages.
+:::
 
 ## -sec-num- Network Messages {#sect-network-messages}
 
@@ -698,3 +705,54 @@ This message is the sub-component of the GRANDPA Gossip message ([Definition -de
 
 
 :::
+### -sec-num- GRANDPA BEEFY {#sect-msg-grandpa-beefy}
+
+This section defines the messages required for the BEEFY protocol ([Section -sec-num-ref-](sect-finality#sect-grandpa-beefy)). Those messages are sent over the `/91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3/beefy/1` substream.
+###### Definition -def-num- Commitment {#defn-grandpa-beefy-commitment}
+:::definition
+A **commitment**, ${C}$, contains the information extracted from the finalized block at height ${H}_{{i}}{\left({B}_{{\text{last}}}\right)}$ as specified in the message body and a datastructure of the following format:
+$$
+{C}={\left({R}_{{h}},{H}_{{i}}{\left({B}_{{\text{last}}}\right)},\text{id}_{{{\mathbb{{V}}}}}\right)}
+$$
+**where**  
+- ${R}_{{h}}$ is the MMR root of all the block header hashes leading up to the latest, finalized block.
+- ${H}_{{i}}{\left({B}_{{\text{last}}}\right)}$ is the block number this commitment is for. Namely the latest, finalized block.
+- $\text{id}_{{{\mathbb{{V}}}}}$ is the current authority set Id ([Definition -def-num-ref-](sect-finality#defn-authority-set-id)).
+:::
+###### Definition -def-num- Vote Message {#defn-msg-beefy-gossip}
+:::definition
+A **vote message**, ${M}_{{v}}$, is direct vote created by the Polkadot Host on every BEEFY round and is gossiped to its peers. The message is a datastructure of the following format:
+$$
+{M}_{{v}}=\text{Enc}_{{\text{SC}}}{\left({C},{{A}_{{\text{id}}}^{{\text{bfy}}}},{A}_{{\text{sig}}}\right)}
+$$
+**where**  
+- ${C}$ is the BEEFY commitment ([Definition -def-num-ref-](chap-networking#defn-grandpa-beefy-commitment)).
+- ${{A}_{{\text{id}}}^{{\text{bfy}}}}$ is the ECDSA public key of the Polkadot Host.
+- ${A}_{{\text{sig}}}$ is the signature created with ${{A}_{{\text{id}}}^{{\text{bfy}}}}$ by signing the statement ${R}_{{h}}$ in ${C}$.
+:::
+###### Definition -def-num- Signed Commitment {#defn-grandpa-beefy-signed-commitment}
+:::definition
+A **signed commitment**, ${M}_{{\text{sc}}}$, is a datastructure of the following format:
+$$
+{M}_{{\text{SC}}}=\text{Enc}_{{\text{SC}}}{\left({C},{S}_{{n}}\right)}
+$$
+$$
+{S}_{{n}}={\left({{A}_{{0}}^{{\text{sig}}}},\ldots{{A}_{{n}}^{{\text{sig}}}}\right)}
+$$
+**where**  
+- ${C}$ is the BEEFY commitment ([Definition -def-num-ref-](chap-networking#defn-grandpa-beefy-commitment)).
+- ${S}_{{n}}$ is an array where its exact size matches the number of validators in the current authority set as specified by $\text{id}_{{{\mathbb{{V}}}}}$ ([Definition -def-num-ref-](sect-finality#defn-authority-set-id)) in ${C}$. Individual items are of the type *Option* ([Definition -def-num-ref-](id-cryptography-encoding#defn-option-type)) which can contain a signature of a validator which signed the same statement (${R}_{{h}}$ in ${C}$) and is active in the current authority set. It’s critical that the signatures are sorted based on their corresponding public key entry in the authority set.
+  For example, the signature of the validator at index 3 in the authority set must be placed at index *3* in ${S}_{{n}}$. If not signature is available for that validator, then the *Option* variant is *None* inserted ([Definition -def-num-ref-](id-cryptography-encoding#defn-option-type)). This sorting allows clients to map public keys to their corresponding signatures.
+:::
+###### Definition -def-num- Signed Commitment Witness {#defn-grandpa-beefy-signed-commitment-witness}
+:::definition
+A **signed commitment witness**, ${{M}_{{\text{SC}}}^{{w}}}$, is a light version of the signed BEEFY commitment ([Definition -def-num-ref-](chap-networking#defn-grandpa-beefy-signed-commitment)). Instead of containing the entire list of signatures, it only claims which validator signed the statement.
+The message is a datastructure of the following format:
+$$
+{{M}_{{\text{SC}}}^{{w}}}=\text{Enc}_{{\text{SC}}}{\left({C},{V}_{{{0},\ldots{n}}},{R}_{{\text{sig}}}\right)}
+$$
+**where**  
+- ${C}$ is the BEEFY commitment ([Definition -def-num-ref-](chap-networking#defn-grandpa-beefy-commitment)).
+- ${V}_{{{0},\ldots{n}}}$ is an array where its exact size matches the number of validators in the current authority set as specified by $\text{id}_{{{\mathbb{{V}}}}}$ in ${C}$. Individual items are booleans which indicate whether the validator has signed the statement (*true*) or not (*false*). It’s critical that the boolean indicators are sorted based on their corresponding public key entry in the authority set.
+  For example, the boolean indicator of the validator at index 3 in the authority set must be placed at index *3* in ${V}_{{n}}$. This sorting allows clients to map public keys to their corresponding boolean indicators.
+- ${R}_{{\text{sig}}}$ is the MMR root of the signatures in the original signed BEEFY commitment ([Definition -def-num-ref-](chap-networking#defn-grandpa-beefy-signed-commitment)).

docs/chap-state.md

@@ -171,6 +171,7 @@ $$
 $t = 4$ **Consensus Message**, contains scale-encoded message $m$ from the Runtime to the consensus engine. The receiving engine is determined by the *id* identifier:
 - *id* = BABE: a message to BABE engine ([Definition -def-num-ref-](sect-block-production#defn-consensus-message-babe))
 - *id* = FRNK: a message to GRANDPA engine ([Definition -def-num-ref-](sect-finality#defn-consensus-message-grandpa))
+- *id* = BEEF: a message to BEEFY engine ([Definition -def-num-ref-](sect-finality#defn-consensus-message-beefy))
 
 
 $t = 5$ **Seal**, is produced by the consensus engine and proves the authorship of the block producer. The engine used for this is provided through *id* (at the moment, `BABE`), while $m$ contains the scale-encoded signature ([Definition -def-num-ref-](sect-block-production#defn-block-signature)) of the block producer. In particular, the Seal digest item must be the last item in the digest array and must be stripped off by the Polkadot Host before the block is submitted to any Runtime function, including for validation. The Seal must be added back to the digest afterward.

docs/sect-finality.md

@@ -652,6 +652,29 @@ A light client ([Definition -def-num-ref-](sect-finality#defn-beefy-light-client
 
 How those signed commitments are requested by the light client and delivered by the relayer varies among networks or implementations.
 
+#### Definition -def-num- BEEFY Consensus Message {#defn-consensus-message-beefy}
+::::definition
+
+:::danger
+The BEEFY protocol is still under construction. The following part will be updated in the future and certain information will be clarified.
+:::
+
+$\text{CM}_{{y}}$, the consensus message for BEEFY ([Section -sec-num-ref-](sect-finality#sect-grandpa-beefy)), is of the following format:
+
+$$
+\text{CM}_{{y}}={\left\lbrace\begin{matrix}{1}&{\left({V}_{{B}},{V}_{{i}}\right)}\\{2}&{A}_{{i}}\\{3}&{R}\end{matrix}\right.}
+$$
+
+**where**
+
+|  |  |
+|--|--|
+| 1   | implies that the remote **authorities have changed**. ${V}_{{B}}$ is the array of the new BEEFY authorities’s public keys and ${V}_{{i}}$ is the identifier of the remote validator set. |
+| 2   | implies **on disabled**: an index to the individual authorty in ${V}_{{B}}$ that should be immediately disabled until the next authority change.                                     |
+| 3   | implies **MMR root**: a 32-byte array containing the MMR root.                                                                                                                   |
+
+::::
+
 
 ### -sec-num- Consensus Mechanism {#id-consensus-mechanism-beefy-1}