Merge pull request #679 from w3f/Noc2-patch-1

Update id-cryptography-encoding.md

docs/id-cryptography-encoding.md

@@ -2,7 +2,7 @@
 title: "Appendix A: Cryptography & Encoding"
 ---
 
-Appendix chapter containing various protocol details
+The appendix chapter contains various protocol details.
 
 ## -sec-num- Cryptographic Algorithms {#chapter-crypto-algos}
 
@@ -12,7 +12,7 @@ Appendix chapter containing various protocol details
 
 BLAKE2 is a collection of cryptographic hash functions known for their high speed. Their design closely resembles BLAKE which has been a finalist in the SHA-3 competition.
 
-Polkadot is using the Blake2b variant which is optimized for 64-bit platforms. Unless otherwise specified, the Blake2b hash function with a 256-bit output is used whenever Blake2b is invoked in this document. The detailed specification and sample implementations of all variants of Blake2 hash functions can be found in RFC 7693 [@saarinen_blake2_2015].
+Polkadot is using the Blake2b variant, which is optimized for 64-bit platforms. Unless otherwise specified, the Blake2b hash function with a 256-bit output is used whenever Blake2b is invoked in this document. The detailed specification and sample implementations of all variants of Blake2 hash functions can be found in RFC 7693 [@saarinen_blake2_2015].
 
 ### -sec-num- Randomness {#sect-randomness}
 
@@ -24,22 +24,22 @@ TBH
 
 A Verifiable Random Function (VRF) is a mathematical operation that takes some input and produces a random number using a secret key along with a proof of authenticity that this random number was generated using the submitter’s secret key and the given input. The proof can be verified by any challenger to ensure the random number generation is valid and has not been tampered with (for example to the benfit of submitter).
 
-In Polkadot, VRFs are used for the BABE block production lottery by [Block-Production-Lottery](sect-block-production#algo-block-production-lottery) and the parachain approval voting mechanism ([Section -sec-num-ref-](chapter-anv#sect-approval-voting)). The VRF uses mechanism similar to algorithms introduced in the following papers:
+In Polkadot, VRFs are used for the BABE block production lottery by [Block-Production-Lottery](sect-block-production#algo-block-production-lottery) and the parachain approval voting mechanism ([Section -sec-num-ref-](chapter-anv#sect-approval-voting)). The VRF uses a mechanism similar to algorithms introduced in the following papers:
 
 - [Making NSEC5 Practical for DNSSEC](https://eprint.iacr.org/2017/099.pdf) [@papadopoulos17]
 
 - [DLEQ Proofs](https://blog.cloudflare.com/privacy-pass-the-math/#dleqproofs)
 
 - [Verifiable Random Functions (VRFs)](https://tools.ietf.org/id/draft-goldbe-vrf-01) [@goldberg17]
 
-It essentially generates a deterministic elliptic curve based Schnorr signature as a verifiable random value. The elliptic curve group used in the VRF function is the Ristretto group specified in:
+It essentially generates a deterministic elliptic curve based on Schnorr signature as a verifiable random value. The elliptic curve group used in the VRF function is the Ristretto group specified in:
 
 - [ristretto.group/](https://ristretto.group/)
 
 ###### Definition -def-num- VRF Proof {#defn-vrf-proof}
 :::definition
 
-The **VRF proof** proves the correctness for an associated VRF output. The VRF proof, ${P}$, is a datastructure of the following format:
+The **VRF proof** proves the correctness of an associated VRF output. The VRF proof, ${P}$, is a data structure of the following format:
 
 $$
 {P}={\left({C},{S}\right)}
@@ -79,7 +79,7 @@ t_8 &= \text{meta-AD}(t_7, e\_(64), \text{more=False}) \\
 \end{aligned}
 $$
 
-where ${w}_{{l}}$ is length of the witness, encoded as a 32-bit little-endian integer. ${r}$ is a 32-byte array containing the secret witness scalar.
+where ${w}_{{l}}$ is the length of the witness, encoded as a 32-bit little-endian integer. ${r}$ is a 32-byte array containing the secret witness scalar.
 
 $$
 \begin{aligned}
@@ -166,10 +166,10 @@ $$
 
 A VRF transcript serves as a domain-specific separator of cryptographic protocols and is represented as a mathematical object, as defined by Merlin, which defines how that object is generated and encoded. The usage of the transcript is implementation specific, such as for certain mechanisms in the Availability & Validity chapter ([Chapter -chap-num-ref-](chapter-anv)), and is therefore described in more detail in those protocols. The input value used to initiate the transcript is referred to as a *context* ([Definition -def-num-ref-](id-cryptography-encoding#defn-vrf-context)).
 
-###### Definition -def-num- VRF Contex {#defn-vrf-context}
+###### Definition -def-num- VRF Context {#defn-vrf-context}
 :::definition
 
-The **VRF context** is a constant byte array used to initiate VRF transcript. The VRF context is constant for all users of the VRF for the specific context for which the VRF function is used. Context prevents VRF values generated by the same nodes for other purposes to be reused for purposes not meant to. For example, the VRF context for BABE Production lottery defined in [Section -sec-num-ref-](sect-block-production#sect-block-production-lottery) is set to be "substrate-babe-vrf".
+The **VRF context** is a constant byte array used to initiate the VRF transcript. The VRF context is constant for all users of the VRF for the specific context for which the VRF function is used. Context prevents VRF values generated by the same nodes for other purposes to be reused for purposes not meant to. For example, the VRF context for the BABE Production lottery defined in [Section -sec-num-ref-](sect-block-production#sect-block-production-lottery) is set to be "substrate-babe-vrf".
 
 :::
 ###### Definition -def-num- VRF Transcript {#defn-vrf-transcript}
@@ -202,7 +202,7 @@ $$
 
 $\text{ctx}$ serves as an arbitrary identifier/separator and its value is defined by the protocol specification individually. This transcript is treated just like a STROBE object, wherein any operations ([Definition -def-num-ref-](id-cryptography-encoding#defn-strobe-operations)) on it modify the values such as $\text{pos}$ and $\text{pos}_{{\text{begin}}}$.
 
-Formally, when creating a transcript we refer to it as $\text{Transcript}{\left({c}{t}{x}\right)}$.
+Formally, when creating a transcript, we refer to it as $\text{Transcript}{\left({c}{t}{x}\right)}$.
 
 :::
 ###### Definition -def-num- STROBE Operations {#defn-strobe-operations}
@@ -227,11 +227,11 @@ $$
 
 where ${T}$ is the transcript ([Definition -def-num-ref-](id-cryptography-encoding#defn-vrf-transcript)), ${l}$ is the given label and ${m}$ the message, respectively ${m}_{{l}}$ representing its size. ${T}_{{2}}$ is the resulting transcript with the appended data. STROBE operations are described in [Definition -def-num-ref-](id-cryptography-encoding#defn-strobe-operations).
 
-Formally, when appending a message we refer to it as $\text{append}{\left({T},{l},{m}\right)}$.
+Formally, when appending a message, we refer to it as $\text{append}{\left({T},{l},{m}\right)}$.
 
 ### -sec-num- Cryptographic Keys {#sect-cryptographic-keys}
 
-Various types of keys are used in Polkadot to prove the identity of the actors involved in the Polkadot Protocols. To improve the security of the users, each key type has its own unique function and must be treated differently, as described by this Section.
+Various types of keys are used in Polkadot to prove the identity of the actors involved in the Polkadot Protocols. To improve the security of the users, each key type has its own unique function and must be treated differently, as described in this Section.
 
 ###### Definition -def-num- Account Key {#defn-account-key}
 :::definition
@@ -243,16 +243,16 @@ Various types of keys are used in Polkadot to prove the identity of the actors i
 | Key Scheme | Description |
 |------------|-------------|
 | sr25519    | Schnorr signature on Ristretto compressed ed25519 points as implemented in TODO|
-| ed25519    | The ed25519 signature complies with [@josefsson_edwards-curve_2017] except for the verification process which adhere to Ed25519 Zebra variant specified in [@devalence_ed25519zebra_2020]. In short, the signature point is not assumed to be on in the prime ordered subgroup group. As such, the verifier must explicitly clear the cofactor during the course of verifying the signature equation. |
+| ed25519    | The ed25519 signature complies with [@josefsson_edwards-curve_2017] except for the verification process which adhere to Ed25519 Zebra variant specified in [@devalence_ed25519zebra_2020]. In short, the signature point is not assumed to be in the prime-ordered subgroup group. As such, the verifier must explicitly clear the cofactor during the course of verifying the signature equation. |
 | secp256k1  | Only for outgoing transfer transactions. |
 
-An account key can be used to sign transactions among other accounts and balance-related functions. There are two prominent subcategories of account keys namely "stash keys" and "controller keys", each being used for a different function. Keys defined in [Definition -def-num-ref-](id-cryptography-encoding#defn-account-key), [Definition -def-num-ref-](id-cryptography-encoding#defn-stash-key) and [Definition -def-num-ref-](id-cryptography-encoding#defn-controller-key) are created and managed by the user independent of the Polkadot implementation. The user notifies the network about the used keys by submitting a transaction, as defined in [Section -sec-num-ref-](id-cryptography-encoding#sect-creating-controller-key) and [Section -sec-num-ref-](id-cryptography-encoding#sect-certifying-keys) respectively.
+An account key can be used to sign transactions among other accounts and balance-related functions. There are two prominent subcategories of account keys, namely "stash keys" and "controller keys", each being used for a different function. Keys defined in [Definition -def-num-ref-](id-cryptography-encoding#defn-account-key), [Definition -def-num-ref-](id-cryptography-encoding#defn-stash-key) and [Definition -def-num-ref-](id-cryptography-encoding#defn-controller-key) are created and managed by the user independent of the Polkadot implementation. The user notifies the network about the used keys by submitting a transaction, as defined in [Section -sec-num-ref-](id-cryptography-encoding#sect-creating-controller-key) and [Section -sec-num-ref-](id-cryptography-encoding#sect-certifying-keys) respectively.
 :::
 
 ###### Definition -def-num- Stash Key {#defn-stash-key}
 :::definition
 
-The **Stash key** is a type of account key that holds funds bonded for staking (described in [Section -sec-num-ref-](id-cryptography-encoding#sect-staking-funds)) to a particular controller key (defined in [Definition -def-num-ref-](id-cryptography-encoding#defn-controller-key)). As a result, one may actively participate with a stash key keeping the stash key offline in a secure location. It can also be used to designate a Proxy account to vote in governance proposals, as described in [Section -sec-num-ref-](id-cryptography-encoding#sect-creating-controller-key). The Stash key holds the majority of the users’ funds and should neither be shared with anyone, saved on an online device, nor used to submit extrinsics.
+The **Stash key** is a type of account key that holds funds bonded for staking (described in [Section -sec-num-ref-](id-cryptography-encoding#sect-staking-funds)) to a particular controller key (defined in [Definition -def-num-ref-](id-cryptography-encoding#defn-controller-key)). As a result, one may actively participate with a stash key, keeping the stash key offline in a secure location. It can also be used to designate a Proxy account to vote in governance proposals, as described in [Section -sec-num-ref-](id-cryptography-encoding#sect-creating-controller-key). The Stash key holds the majority of the users’ funds and should neither be shared with anyone, saved on an online device, nor used to submit extrinsics.
 
 :::
 ###### Definition -def-num- Controller Key {#defn-controller-key}
@@ -304,7 +304,7 @@ TBH
 
 #### -sec-num- Certifying keys {#sect-certifying-keys}
 
-Due to security considerations and Runtime upgrades, the session keys are supposed to  be changed regularly. As such, the new session keys need to be certified by a controller key before putting them in use. The controller only needs to create a certificate by signing a session public key and broadcasting this certificate via an extrinsic. \[TODO: spec the detail of the data structure of the certificate etc.\]
+Due to security considerations and Runtime upgrades, the session keys are supposed to be changed regularly. As such, the new session keys need to be certified by a controller key before putting them into use. The controller only needs to create a certificate by signing a session public key and broadcasting this certificate via an extrinsic. \[TODO: spec the detail of the data structure of the certificate etc.\]
 
 ## -sec-num- Auxiliary Encodings {#chapter-encoding}
 
@@ -391,10 +391,10 @@ The Polkadot Host uses *Simple Concatenated Aggregate Little-Endian” (SCALE) c
 
 $\text{Dec}_{{\text{SC}}}{\left({d}\right)}$ refers to the decoding of a blob of data. Since the SCALE codec is not self-describing, it’s up to the decoder to validate whether the blob of data can be deserialized into the given type or data structure.
 
-It’s accepted behavior for the decoder to partially decode the blob of data. Meaning, any additional data that does not fit into a datastructure can be ignored.
+It’s accepted behavior for the decoder to partially decode the blob of data. Meaning, any additional data that does not fit into a data structure can be ignored.
 
 :::caution
-Considering that the decoded data is never larger than the encoded message, this information can serve as a way to validate values that can vary in sizes, such as sequences ([Definition -def-num-ref-](id-cryptography-encoding#defn-scale-list)). The decoder should strictly use the size of the encoded data as an upper bound when decoding in order to prevent denial of service attacks.
+Considering that the decoded data is never larger than the encoded message, this information can serve as a way to validate values that can vary in size, such as sequences ([Definition -def-num-ref-](id-cryptography-encoding#defn-scale-list)). The decoder should strictly use the size of the encoded data as an upper bound when decoding in order to prevent denial of service attacks.
 :::
 
 ::::
@@ -414,7 +414,7 @@ $$
 $$
 :::
 
-In case of a tuple (or a structure), the knowledge of the shape of data is not encoded even though it is necessary for decoding. The decoder needs to derive that information from the context where the encoding/decoding is happening.
+In the case of a tuple (or a structure), the knowledge of the shape of data is not encoded even though it is necessary for decoding. The decoder needs to derive that information from the context where the encoding/decoding is happening.
 
 ###### Definition -def-num- Varying Data Type {#defn-varrying-data-type}
 :::definition
@@ -716,4 +716,4 @@ The Polkadot genesis header is a data structure conforming to block header forma
 
 :::info
 Erasure Encoding has not been documented yet.
-:::
+:::