diff --git a/src/docs/chap-networking.md b/src/docs/chap-networking.md index 24883d660..d828dba51 100644 --- a/src/docs/chap-networking.md +++ b/src/docs/chap-networking.md @@ -655,3 +655,334 @@ $$ 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)). +::: + +### -sec-num- Notification Messages {#id-notification-messges} + +The notification messages are exchanged between validators, including messages sent by collators to validators. The protocol messages are exchanged based on a streaming notification substream ([Section -sec-num-ref-](chap-networking#sect-connection-establishment)). The messages are SCALE encoded ([Section -sec-num-ref-](id-cryptography-encoding#sect-scale-codec)). + +###### Definition -def-num- Validator Protocol Message {#net-msg-validator-protocol-message} +:::definition + +The validator protocol message is a varying datatype used by validators to broadcast relevant information about certain steps in the A&V process. Specifically, this includes the backing process ([Section -sec-num-ref-](chapter-anv#sect-candidate-backing)) and the approval process ([Section -sec-num-ref-](chapter-anv#sect-approval-voting)). The validator protocol message, ${M}$, is a varying datatype of the following format: + +$$ +{M}={\left\lbrace\begin{matrix}{1}&\rightarrow&{M}_{{f}}\\{3}&\rightarrow&{M}_{{s}}\\{4}&\rightarrow&{M}_{{a}}\end{matrix}\right.} +$$ + +**where** +- ${M}_{{f}}$ is a bitfield distribution message ([Definition -def-num-ref-](chapter-anv#net-msg-bitfield-dist-msg)). + +- ${M}_{{s}}$ is a statement distribution message ([Definition -def-num-ref-](chapter-anv#net-msg-statement-distribution)). + +- ${M}_{{a}}$ is a approval distribution message ([Definition -def-num-ref-](chapter-anv#net-msg-approval-distribution)). + +::: +###### Definition -def-num- Collation Protocol Message {#net-msg-collator-protocol-message} +:::definition + +The collation protocol message, M, is a varying datatype of the following format: + +$$ +{M}={\left\lbrace\begin{matrix}{0}&\rightarrow&{M}_{{c}}\end{matrix}\right.} +$$ + +where ${M}_{{c}}$ is the collator message ([Definition -def-num-ref-](chapter-anv#net-msg-collator-message)). + +::: +###### Definition -def-num- Collator Message {#net-msg-collator-message} +:::definition + +The collator message is sent as part of the collator protocol message ([Definition -def-num-ref-](chapter-anv#net-msg-collator-protocol-message)). The collator message, ${M}$, is a varying datatype of the following format: + +$$ +{M}={\left\lbrace\begin{matrix}{0}&\rightarrow&{\left({C}_{{i}},{P}_{{i}},{C}_{{s}}\right)}\\{1}&\rightarrow&{H}\\{4}&\rightarrow&{\left({B}_{{h}},{S}\right)}\end{matrix}\right.} +$$ + +**where** +- ${M}$ is a varying datatype where *0* indicates the intent to advertise a collation and *1* indicates the advertisement of a collation to a validator. *4* indicates that a collation sent to a validator was seconded. + +- ${C}_{{i}}$ is the public key of the collator. + +- ${P}_{{i}}$ is the parachain Id ([Definition -def-num-ref-](chapter-anv#defn-para-id)). + +- ${C}_{{s}}$ is the signature of the collator using the *PeerId* of the collators node. + +- ${H}$ is the hash of the parachain block ([Definition -def-num-ref-](chapter-anv#defn-para-block)). + +- ${S}$ is a full statement ([Definition -def-num-ref-](chapter-anv#defn-statement)). + +::: +###### Definition -def-num- Statement Distribution Message {#net-msg-statement-distribution} +:::definition + +The statement distribution message is sent as part of the validator protocol message ([Definition -def-num-ref-](chapter-anv#net-msg-collator-protocol-message)) indicates the validity vote of a validator for a given candidate, described further in [Section -sec-num-ref-](chapter-anv#sect-candidate-statements). The statement distribution message, ${M}$, is of varying type of the following format: + +$$ +{M}={\left\lbrace\begin{matrix}{0}&\rightarrow&{\left({B}_{{h}},{S}\right)}\\{1}&\rightarrow&{S}_{{m}}\end{matrix}\right.} +$$ +$$ +{S}_{{m}}={\left({B}_{{h}},{C}_{{h}},{A}_{{i}},{A}_{{s}}\right)} +$$ + +**where** +- ${M}$ is a varying datatype where *0* indicates a signed statement and *1* contains metadata about a seconded statement with a larger payload, such as a runtime upgrade. The candidate itself can be fetched via the request/response message ([Definition -def-num-ref-](chapter-anv#net-msg-statement-fetching-request)). + +- ${B}_{{h}}$ is the hash of the relay chain parent, indicating the state this message is for. + +- ${S}$ is a full statement ([Definition -def-num-ref-](chapter-anv#defn-statement)). + +- ${A}_{{i}}$ is the validator index in the authority set ([Definition -def-num-ref-](chap-sync#defn-authority-list)) that signed this message. + +- ${A}_{{s}}$ is the signature of the validator. + +::: +###### Definition -def-num- Bitfield Distribution Message {#net-msg-bitfield-dist-msg} +:::definition + +The bitfield distribution message is sent as part of the validator protocol message ([Definition -def-num-ref-](chapter-anv#net-msg-validator-protocol-message)) and indicates the availability vote of a validator for a given candidate, described further in [Section -sec-num-ref-](chapter-anv#sect-availability-votes). This message is sent in form of a validator protocol message ([Definition -def-num-ref-](chapter-anv#net-msg-validator-protocol-message)). The bitfield distribution message, ${M}$, is a datastructure of the following format: + +$$ +{M}={\left\lbrace\begin{matrix}{0}&\rightarrow&{\left({B}_{{h}},{P}\right)}\end{matrix}\right.} +$$ +$$ +{P}={\left({d},{A}_{{i}},{A}_{{s}}\right)} +$$ + +**where** +- ${B}_{{h}}$ is the hash of the relay chain parent, indicating the state this message is for. + +- ${d}$ is the bitfield array ([Definition -def-num-ref-](chapter-anv#defn-bitfield-array)). + +- ${A}_{{i}}$ is the validator index in the authority set ([Definition -def-num-ref-](chap-sync#defn-authority-list)) that signed this message. + +- ${A}_{{s}}$ is the signature of the validator. + +::: +###### Definition -def-num- Approval Distribution Message {#net-msg-approval-distribution} +:::definition + +The approval distribution message is sent as part of the validator protocol message ([Definition -def-num-ref-](chapter-anv#net-msg-validator-protocol-message)) and indicates the approval vote of a validator for a given candidate, described further in [Section -sec-num-ref-](chapter-anv#sect-availability-assignment-criteria). The approval distribution message, ${M}$, is a varying datatype of the following format: + +$$ +{M}={\left\lbrace\begin{matrix}{0}&\rightarrow&{\left({\left({C}_{,}{I}_{{}}\right)}_{{0}}…{\left({C},{I}\right)}_{{n}}\right)}\\{1}&\rightarrow&{\left({V}_{{0}},…{V}_{{n}}\right)}\end{matrix}\right.} +$$ +$$ +{C}={\left({B}_{{h}},{A}_{{i}},{c}_{{a}}\right)} +$$ +$$ +{c}_{{a}}={\left({c}_{{k}},{P}_{{o}},{P}_{{p}}\right)} +$$ +$$ +{c}_{{k}}={\left\lbrace\begin{matrix}{0}→{s}\\{1}→{i}\end{matrix}\right.} +$$ +$$ +{V}={\left({B}_{{h}},{I},{A}_{{i}},{A}_{{s}}\right)} +$$ + +**where** +- ${M}$ is a varying datatype where *0* indicates assignments for candidates in recent, unfinalized blocks and *1* indicates approvals for candidates in some recent, unfinalized block. + +- ${C}$ is an assignment criterion which refers to the candidate under which the assignment is relevant by the block hash. + +- ${I}$ is an unsigned 32-bit integer indicating the index of the candidate, corresponding the the order of the availability cores ([Section -sec-num-ref-](chap-runtime-api#sect-rt-api-availability-cores)). + +- ${B}_{{h}}$ is the relay chain block hash where the candidate appears. + +- ${A}_{{i}}$ is the authority set Id ([Definition -def-num-ref-](sect-finality#defn-authority-set-id)) of the validator that created this message. + +- ${A}_{{s}}$ is the signature of the validator issuing this message. + +- ${c}_{{a}}$ is the certification of the assignment. + +- ${c}_{{k}}$ is a varying datatype where *0* indicates an assignment based on the VRF that authorized the relay chain block where the candidate was included, followed by a sample number, ${s}$. *1* indicates an assignment story based on the VRF that authorized the relay chain block where the candidate was included combined with the index of a particular core. This is described further in [Section -sec-num-ref-](chapter-anv#sect-approval-voting). + +- ${P}_{{o}}$ is a VRF output and ${P}_{{p}}$ its corresponding proof. + +::: +### -sec-num- Request & Response {#id-request-response} + +The request & response network messages are sent and received between peers in the Polkadot network, including collators and non-validator nodes. Those messages are conducted on the request-response substreams ([Section -sec-num-ref-](chap-networking#sect-connection-establishment)). The network messages are SCALE encoded as described in Section ?. + +###### Definition -def-num- PoV Fetching Request {#net-msg-pov-fetching-request} +:::definition + +The PoV fetching request is sent by clients who want to retrieve a PoV block from a node. The request is a datastructure of the following format: + +$$ +{C}_{{h}} +$$ + +where ${C}_{{h}}$ is the 256-bit hash of the PoV block. The response message is defined in [Definition -def-num-ref-](chapter-anv#net-msg-pov-fetching-response). + +::: +###### Definition -def-num- PoV Fetching Response {#net-msg-pov-fetching-response} +:::definition + +The PoV fetching response is sent by nodes to the clients who issued a PoV fetching request ([Definition -def-num-ref-](chapter-anv#net-msg-pov-fetching-request)). The response, ${R}$, is a varying datatype of the following format: + +$$ +{R}={\left\lbrace\begin{matrix}{0}&\rightarrow&{B}\\{1}&\rightarrow&\phi\end{matrix}\right.} +$$ + +where *0* is followed by the PoV block and *1* indicates that the PoV block was not found. + +::: +###### Definition -def-num- Chunk Fetching Request {#net-msg-chunk-fetching-request} +:::definition + +The chunk fetching request is sent by clients who want to retrieve chunks of a parachain candidate. The request is a datastructure of the following format: + +$$ +{\left({C}_{{h}},{i}\right)} +$$ + +where ${C}_{{h}}$ is the 256-bit hash of the parachain candidate and ${i}$ is a 32-bit unsigned integer indicating the index of the chunk to fetch. The response message is defined in [Definition -def-num-ref-](chapter-anv#net-msg-chunk-fetching-response). + +::: +###### Definition -def-num- Chunk Fetching Response {#net-msg-chunk-fetching-response} +:::definition + +The chunk fetching response is sent by nodes to the clients who issued a chunk fetching request ([Definition -def-num-ref-](chapter-anv#net-msg-chunk-fetching-request)). The response, ${R}$, is a varying datatype of the following format: + +$$ +{R}={\left\lbrace\begin{matrix}{0}&\rightarrow&{C}_{{r}}\\{1}&\rightarrow&\phi\end{matrix}\right.} +$$ +$$ +{C}_{{r}}={\left({c},{c}_{{p}}\right)} +$$ + +where *0* is followed by the chunk response, ${C}_{{r}}$ and *1* indicates that the requested chunk was not found. ${C}_{{r}}$ contains the erasure-encoded chunk of data belonging to the candidate block, ${c}$, and ${c}_{{p}}$ is that chunks proof in the Merkle tree. Both ${c}$ and ${c}_{{p}}$ are byte arrays of type ${\left({b}_{{n}}…{b}_{{m}}\right)}$. + +::: +###### Definition -def-num- Available Data Request {#net-msg-available-data-request} +:::definition + +The available data request is sent by clients who want to retrieve the PoV block of a parachain candidate. The request is a datastructure of the following format: + +$$ +{C}_{{h}} +$$ + +where ${C}_{{h}}$ is the 256-bit candidate hash to get the available data for. The response message is defined in [Definition -def-num-ref-](chapter-anv#net-msg-available-data-response). + +::: +###### Definition -def-num- Available Data Response {#net-msg-available-data-response} +:::definition + +The available data response is sent by nodes to the clients who issued a available data request ([Definition -def-num-ref-](chapter-anv#net-msg-available-data-request)). The response, ${R}$, is a varying datatype of the following format: + +$$ +{R}={\left\lbrace\begin{matrix}{0}&\rightarrow&{A}\\{1}&\rightarrow&\phi\end{matrix}\right.} +$$ +$$ +{A}={\left({P}_{{{ov}}},{D}_{{{pv}}}\right)} +$$ + +where *0* is followed by the available data, ${A}$, and *1* indicates the the requested candidate hash was not found. ${P}_{{{o}{v}}}$ is the PoV block ([Definition -def-num-ref-](chapter-anv#defn-para-block)) and ${D}_{{{p}{v}}}$ is the persisted validation data ([Definition -def-num-ref-](chap-runtime-api#defn-persisted-validation-data)). + +::: +###### Definition -def-num- Collation Fetching Request {#net-msg-collation-fetching-request} +:::definition + +The collation fetching request is sent by clients who want to retrieve the advertised collation at the specified relay chain block. The request is a datastructure of the following format: + +$$ +{\left({B}_{{h}},{P}_{{{id}}}\right)} +$$ + +where ${B}_{{h}}$ is the hash of the relay chain block and ${P}_{{{i}{d}}}$ is the parachain Id ([Definition -def-num-ref-](chapter-anv#defn-para-id)). The response message is defined in [Definition -def-num-ref-](chapter-anv#net-msg-collation-fetching-response). + +::: +###### Definition -def-num- Collation Fetching Response {#net-msg-collation-fetching-response} +:::definition + +The collation fetching response is sent by nodes to the clients who issued a collation fetching request ([Definition -def-num-ref-](chapter-anv#net-msg-collation-fetching-request)). The response, ${R}$, is a varying datatype of the following format: + +$$ +{R}={\left\lbrace\begin{matrix}{0}&\rightarrow&{\left({C}_{{r}},{B}\right)}\end{matrix}\right.} +$$ + +where ${0}$ is followed by the candidate receipt ([Definition -def-num-ref-](chapter-anv#defn-candidate-receipt)), ${C}_{{r}}$, as and the PoV block ([Definition -def-num-ref-](chapter-anv#defn-para-block)), ${B}$. This type does not notify the client about a statement that was not found. + +::: +###### Definition -def-num- Statement Fetching Request {#net-msg-statement-fetching-request} +:::definition + +The statement fetching request is sent by clients who want to retrieve statements about a given candidate. The request is a datastructure of the following format: + +$$ +{\left({B}_{{h}},{C}_{{h}}\right)} +$$ + +where ${B}_{{h}}$ is the hash of the relay chain parent and ${C}_{{h}}$ is the candidate hash that was used to create a committed candidate receipt ([Definition -def-num-ref-](chapter-anv#defn-committed-candidate-receipt)). The response message is defined in [Definition -def-num-ref-](chapter-anv#net-msg-statement-fetching-response). + +::: +###### Definition -def-num- Statement Fetching Response {#net-msg-statement-fetching-response} +:::definition + +The statement fetching response is sent by nodes to the clients who issued a collation fetching request ([Definition -def-num-ref-](chapter-anv#net-msg-statement-fetching-request)). The response, ${R}$, is a varying datatype of the following format: + +$$ +{R}={\left\lbrace\begin{matrix}{0}&\rightarrow&{C}_{{r}}\end{matrix}\right.} +$$ + +where ${C}_{{r}}$ is the committed candidate receipt ([Definition -def-num-ref-](chapter-anv#defn-committed-candidate-receipt)). No response is returned if no statement is found. + +::: +#### -sec-num- Dispute Request {#net-msg-dispute-request} + +The dispute request is sent by clients who want to issue a dispute about a candidate. The request, ${D}_{{r}}$, is a datastructure of the following format: + +$$ +{D}_{{r}}={\left({C}_{{r}},{S}_{{i}},{I}_{{v}},{V}_{{v}}\right)} +$$ +$$ +{I}_{{v}}={\left({A}_{{i}},{A}_{{s}},{k}_{{i}}\right)} +$$ +$$ +{V}_{{v}}={\left({A}_{{i}},{A}_{{s}},{k}_{{v}}\right)} +$$ +$$ +{k}_{{i}}={\left\lbrace\begin{matrix}{0}&\rightarrow&\phi\end{matrix}\right.} +$$ +$$ +{k}_{{v}}={\left\lbrace\begin{matrix}{0}&\rightarrow&\phi\\{1}&\rightarrow&{C}_{{h}}\\{2}&\rightarrow&{C}_{{h}}\\{3}&\rightarrow&\phi\end{matrix}\right.} +$$ + +**where** +- ${C}_{{r}}$ is the candidate that is being disputed. The structure is a candidate receipt ([Definition -def-num-ref-](chapter-anv#defn-candidate-receipt)). + +- ${S}_{{i}}$ is an unsigned 32-bit integer indicating the session index the candidate appears in. + +- ${I}_{{v}}$ is the invalid vote that makes up the request. + +- ${V}_{{v}}$ is the valid vote that makes this dispute request valid. + +- ${A}_{{i}}$ is an unsigned 32-bit integer indicating the validator index in the authority set ([Definition -def-num-ref-](chap-sync#defn-authority-list)). + +- ${A}_{{s}}$ is the signature of the validator. + +- ${k}_{{i}}$ is a varying datatype and implies the dispute statement. *0* indicates an explicit statement. + +- ${k}_{{v}}$ is a varying datatype and implies the dispute statement. + + - ${0}$ indicates an explicit statement. + + - ${1}$ indicates a seconded statement on a candidate, ${C}_{{h}}$, from the backing phase. ${C}_{{h}}$ is the hash of the candidate. + + - ${2}$ indicates a valid statement on a candidate, ${C}_{{h}}$, from the backing phase. ${C}_{{h}}$ is the hash of the candidate. + + - ${3}$ indicates an approval vote from the approval checking phase. + +The response message is defined in [Section -sec-num-ref-](chapter-anv#net-msg-dispute-response). + +#### -sec-num- Dispute Response {#net-msg-dispute-response} + +The dispute response is sent by nodes to the clients who who issued a dispute request ([Section -sec-num-ref-](chapter-anv#net-msg-dispute-request)). The response, ${R}$, is a varying type of the following format: + +$$ +{R}={\left\lbrace\begin{matrix}{0}&\rightarrow&\phi\end{matrix}\right.} +$$ + +where ${0}$ indicates that the dispute was successfully processed. \ No newline at end of file diff --git a/src/docs/chapter-anv.md b/src/docs/chapter-anv.md index 7e50057c9..8553147cb 100644 --- a/src/docs/chapter-anv.md +++ b/src/docs/chapter-anv.md @@ -519,340 +519,6 @@ where ${k}$ indicates the kind of the certificate, respectively the value *0* pr Disputes are not documented yet. ::: -## -sec-num- Network Messages {#sect-anv-network-messages} - -The availability and validity process requires certain network messages to be exchanged between validators and collators. - -### -sec-num- Notification Messges {#id-notification-messges} - -The notification messages are exchanged between validators, including messages sent by collators to validators. The protocol messages are exchanged based on a streaming notification substream ([Section -sec-num-ref-](chap-networking#sect-connection-establishment)). The messages are SCALE encoded ([Section -sec-num-ref-](id-cryptography-encoding#sect-scale-codec)). - -###### Definition -def-num- Validator Protocol Message {#net-msg-validator-protocol-message} -:::definition - -The validator protocol message is a varying datatype used by validators to broadcast relevant information about certain steps in the A&V process. Specifically, this includes the backing process ([Section -sec-num-ref-](chapter-anv#sect-candidate-backing)) and the approval process ([Section -sec-num-ref-](chapter-anv#sect-approval-voting)). The validator protocol message, ${M}$, is a varying datatype of the following format: - -$$ -{M}={\left\lbrace\begin{matrix}{1}&\rightarrow&{M}_{{f}}\\{3}&\rightarrow&{M}_{{s}}\\{4}&\rightarrow&{M}_{{a}}\end{matrix}\right.} -$$ - -**where** -- ${M}_{{f}}$ is a bitfield distribution message ([Definition -def-num-ref-](chapter-anv#net-msg-bitfield-dist-msg)). - -- ${M}_{{s}}$ is a statement distribution message ([Definition -def-num-ref-](chapter-anv#net-msg-statement-distribution)). - -- ${M}_{{a}}$ is a approval distribution message ([Definition -def-num-ref-](chapter-anv#net-msg-approval-distribution)). - -::: -###### Definition -def-num- Collation Protocol Message {#net-msg-collator-protocol-message} -:::definition - -The collation protocol message, M, is a varying datatype of the following format: - -$$ -{M}={\left\lbrace\begin{matrix}{0}&\rightarrow&{M}_{{c}}\end{matrix}\right.} -$$ - -where ${M}_{{c}}$ is the collator message ([Definition -def-num-ref-](chapter-anv#net-msg-collator-message)). - -::: -###### Definition -def-num- Collator Message {#net-msg-collator-message} -:::definition - -The collator message is sent as part of the collator protocol message ([Definition -def-num-ref-](chapter-anv#net-msg-collator-protocol-message)). The collator message, ${M}$, is a varying datatype of the following format: - -$$ -{M}={\left\lbrace\begin{matrix}{0}&\rightarrow&{\left({C}_{{i}},{P}_{{i}},{C}_{{s}}\right)}\\{1}&\rightarrow&{H}\\{4}&\rightarrow&{\left({B}_{{h}},{S}\right)}\end{matrix}\right.} -$$ - -**where** -- ${M}$ is a varying datatype where *0* indicates the intent to advertise a collation and *1* indicates the advertisement of a collation to a validator. *4* indicates that a collation sent to a validator was seconded. - -- ${C}_{{i}}$ is the public key of the collator. - -- ${P}_{{i}}$ is the parachain Id ([Definition -def-num-ref-](chapter-anv#defn-para-id)). - -- ${C}_{{s}}$ is the signature of the collator using the *PeerId* of the collators node. - -- ${H}$ is the hash of the parachain block ([Definition -def-num-ref-](chapter-anv#defn-para-block)). - -- ${S}$ is a full statement ([Definition -def-num-ref-](chapter-anv#defn-statement)). - -::: -###### Definition -def-num- Statement Distribution Message {#net-msg-statement-distribution} -:::definition - -The statement distribution message is sent as part of the validator protocol message ([Definition -def-num-ref-](chapter-anv#net-msg-collator-protocol-message)) indicates the validity vote of a validator for a given candidate, described further in [Section -sec-num-ref-](chapter-anv#sect-candidate-statements). The statement distribution message, ${M}$, is of varying type of the following format: - -$$ -{M}={\left\lbrace\begin{matrix}{0}&\rightarrow&{\left({B}_{{h}},{S}\right)}\\{1}&\rightarrow&{S}_{{m}}\end{matrix}\right.} -$$ -$$ -{S}_{{m}}={\left({B}_{{h}},{C}_{{h}},{A}_{{i}},{A}_{{s}}\right)} -$$ - -**where** -- ${M}$ is a varying datatype where *0* indicates a signed statement and *1* contains metadata about a seconded statement with a larger payload, such as a runtime upgrade. The candidate itself can be fetched via the request/response message ([Definition -def-num-ref-](chapter-anv#net-msg-statement-fetching-request)). - -- ${B}_{{h}}$ is the hash of the relay chain parent, indicating the state this message is for. - -- ${S}$ is a full statement ([Definition -def-num-ref-](chapter-anv#defn-statement)). - -- ${A}_{{i}}$ is the validator index in the authority set ([Definition -def-num-ref-](chap-sync#defn-authority-list)) that signed this message. - -- ${A}_{{s}}$ is the signature of the validator. - -::: -###### Definition -def-num- Bitfield Distribution Message {#net-msg-bitfield-dist-msg} -:::definition - -The bitfield distribution message is sent as part of the validator protocol message ([Definition -def-num-ref-](chapter-anv#net-msg-validator-protocol-message)) and indicates the availability vote of a validator for a given candidate, described further in [Section -sec-num-ref-](chapter-anv#sect-availability-votes). This message is sent in form of a validator protocol message ([Definition -def-num-ref-](chapter-anv#net-msg-validator-protocol-message)). The bitfield distribution message, ${M}$, is a datastructure of the following format: - -$$ -{M}={\left\lbrace\begin{matrix}{0}&\rightarrow&{\left({B}_{{h}},{P}\right)}\end{matrix}\right.} -$$ -$$ -{P}={\left({d},{A}_{{i}},{A}_{{s}}\right)} -$$ - -**where** -- ${B}_{{h}}$ is the hash of the relay chain parent, indicating the state this message is for. - -- ${d}$ is the bitfield array ([Definition -def-num-ref-](chapter-anv#defn-bitfield-array)). - -- ${A}_{{i}}$ is the validator index in the authority set ([Definition -def-num-ref-](chap-sync#defn-authority-list)) that signed this message. - -- ${A}_{{s}}$ is the signature of the validator. - -::: -###### Definition -def-num- Approval Distribution Message {#net-msg-approval-distribution} -:::definition - -The approval distribution message is sent as part of the validator protocol message ([Definition -def-num-ref-](chapter-anv#net-msg-validator-protocol-message)) and indicates the approval vote of a validator for a given candidate, described further in [Section -sec-num-ref-](chapter-anv#sect-availability-assignment-criteria). The approval distribution message, ${M}$, is a varying datatype of the following format: - -$$ -{M}={\left\lbrace\begin{matrix}{0}&\rightarrow&{\left({\left({C}_{,}{I}_{{}}\right)}_{{0}}…{\left({C},{I}\right)}_{{n}}\right)}\\{1}&\rightarrow&{\left({V}_{{0}},…{V}_{{n}}\right)}\end{matrix}\right.} -$$ -$$ -{C}={\left({B}_{{h}},{A}_{{i}},{c}_{{a}}\right)} -$$ -$$ -{c}_{{a}}={\left({c}_{{k}},{P}_{{o}},{P}_{{p}}\right)} -$$ -$$ -{c}_{{k}}={\left\lbrace\begin{matrix}{0}→{s}\\{1}→{i}\end{matrix}\right.} -$$ -$$ -{V}={\left({B}_{{h}},{I},{A}_{{i}},{A}_{{s}}\right)} -$$ - -**where** -- ${M}$ is a varying datatype where *0* indicates assignments for candidates in recent, unfinalized blocks and *1* indicates approvals for candidates in some recent, unfinalized block. - -- ${C}$ is an assignment criterion which refers to the candidate under which the assignment is relevant by the block hash. - -- ${I}$ is an unsigned 32-bit integer indicating the index of the candidate, corresponding the the order of the availability cores ([Section -sec-num-ref-](chap-runtime-api#sect-rt-api-availability-cores)). - -- ${B}_{{h}}$ is the relay chain block hash where the candidate appears. - -- ${A}_{{i}}$ is the authority set Id ([Definition -def-num-ref-](sect-finality#defn-authority-set-id)) of the validator that created this message. - -- ${A}_{{s}}$ is the signature of the validator issuing this message. - -- ${c}_{{a}}$ is the certification of the assignment. - -- ${c}_{{k}}$ is a varying datatype where *0* indicates an assignment based on the VRF that authorized the relay chain block where the candidate was included, followed by a sample number, ${s}$. *1* indicates an assignment story based on the VRF that authorized the relay chain block where the candidate was included combined with the index of a particular core. This is described further in [Section -sec-num-ref-](chapter-anv#sect-approval-voting). - -- ${P}_{{o}}$ is a VRF output and ${P}_{{p}}$ its corresponding proof. - -::: -### -sec-num- Request & Response {#id-request-response} - -The request & response network messages are sent and received between peers in the Polkadot network, including collators and non-validator nodes. Those messages are conducted on the request-response substreams ([Section -sec-num-ref-](chap-networking#sect-connection-establishment)). The network messages are SCALE encoded as described in Section ?. - -###### Definition -def-num- PoV Fetching Request {#net-msg-pov-fetching-request} -:::definition - -The PoV fetching request is sent by clients who want to retrieve a PoV block from a node. The request is a datastructure of the following format: - -$$ -{C}_{{h}} -$$ - -where ${C}_{{h}}$ is the 256-bit hash of the PoV block. The response message is defined in [Definition -def-num-ref-](chapter-anv#net-msg-pov-fetching-response). - -::: -###### Definition -def-num- PoV Fetching Response {#net-msg-pov-fetching-response} -:::definition - -The PoV fetching response is sent by nodes to the clients who issued a PoV fetching request ([Definition -def-num-ref-](chapter-anv#net-msg-pov-fetching-request)). The response, ${R}$, is a varying datatype of the following format: - -$$ -{R}={\left\lbrace\begin{matrix}{0}&\rightarrow&{B}\\{1}&\rightarrow&\phi\end{matrix}\right.} -$$ - -where *0* is followed by the PoV block and *1* indicates that the PoV block was not found. - -::: -###### Definition -def-num- Chunk Fetching Request {#net-msg-chunk-fetching-request} -:::definition - -The chunk fetching request is sent by clients who want to retrieve chunks of a parachain candidate. The request is a datastructure of the following format: - -$$ -{\left({C}_{{h}},{i}\right)} -$$ - -where ${C}_{{h}}$ is the 256-bit hash of the parachain candidate and ${i}$ is a 32-bit unsigned integer indicating the index of the chunk to fetch. The response message is defined in [Definition -def-num-ref-](chapter-anv#net-msg-chunk-fetching-response). - -::: -###### Definition -def-num- Chunk Fetching Response {#net-msg-chunk-fetching-response} -:::definition - -The chunk fetching response is sent by nodes to the clients who issued a chunk fetching request ([Definition -def-num-ref-](chapter-anv#net-msg-chunk-fetching-request)). The response, ${R}$, is a varying datatype of the following format: - -$$ -{R}={\left\lbrace\begin{matrix}{0}&\rightarrow&{C}_{{r}}\\{1}&\rightarrow&\phi\end{matrix}\right.} -$$ -$$ -{C}_{{r}}={\left({c},{c}_{{p}}\right)} -$$ - -where *0* is followed by the chunk response, ${C}_{{r}}$ and *1* indicates that the requested chunk was not found. ${C}_{{r}}$ contains the erasure-encoded chunk of data belonging to the candidate block, ${c}$, and ${c}_{{p}}$ is that chunks proof in the Merkle tree. Both ${c}$ and ${c}_{{p}}$ are byte arrays of type ${\left({b}_{{n}}…{b}_{{m}}\right)}$. - -::: -###### Definition -def-num- Available Data Request {#net-msg-available-data-request} -:::definition - -The available data request is sent by clients who want to retrieve the PoV block of a parachain candidate. The request is a datastructure of the following format: - -$$ -{C}_{{h}} -$$ - -where ${C}_{{h}}$ is the 256-bit candidate hash to get the available data for. The response message is defined in [Definition -def-num-ref-](chapter-anv#net-msg-available-data-response). - -::: -###### Definition -def-num- Available Data Response {#net-msg-available-data-response} -:::definition - -The available data response is sent by nodes to the clients who issued a available data request ([Definition -def-num-ref-](chapter-anv#net-msg-available-data-request)). The response, ${R}$, is a varying datatype of the following format: - -$$ -{R}={\left\lbrace\begin{matrix}{0}&\rightarrow&{A}\\{1}&\rightarrow&\phi\end{matrix}\right.} -$$ -$$ -{A}={\left({P}_{{{ov}}},{D}_{{{pv}}}\right)} -$$ - -where *0* is followed by the available data, ${A}$, and *1* indicates the the requested candidate hash was not found. ${P}_{{{o}{v}}}$ is the PoV block ([Definition -def-num-ref-](chapter-anv#defn-para-block)) and ${D}_{{{p}{v}}}$ is the persisted validation data ([Definition -def-num-ref-](chap-runtime-api#defn-persisted-validation-data)). - -::: -###### Definition -def-num- Collation Fetching Request {#net-msg-collation-fetching-request} -:::definition - -The collation fetching request is sent by clients who want to retrieve the advertised collation at the specified relay chain block. The request is a datastructure of the following format: - -$$ -{\left({B}_{{h}},{P}_{{{id}}}\right)} -$$ - -where ${B}_{{h}}$ is the hash of the relay chain block and ${P}_{{{i}{d}}}$ is the parachain Id ([Definition -def-num-ref-](chapter-anv#defn-para-id)). The response message is defined in [Definition -def-num-ref-](chapter-anv#net-msg-collation-fetching-response). - -::: -###### Definition -def-num- Collation Fetching Response {#net-msg-collation-fetching-response} -:::definition - -The collation fetching response is sent by nodes to the clients who issued a collation fetching request ([Definition -def-num-ref-](chapter-anv#net-msg-collation-fetching-request)). The response, ${R}$, is a varying datatype of the following format: - -$$ -{R}={\left\lbrace\begin{matrix}{0}&\rightarrow&{\left({C}_{{r}},{B}\right)}\end{matrix}\right.} -$$ - -where ${0}$ is followed by the candidate receipt ([Definition -def-num-ref-](chapter-anv#defn-candidate-receipt)), ${C}_{{r}}$, as and the PoV block ([Definition -def-num-ref-](chapter-anv#defn-para-block)), ${B}$. This type does not notify the client about a statement that was not found. - -::: -###### Definition -def-num- Statement Fetching Request {#net-msg-statement-fetching-request} -:::definition - -The statement fetching request is sent by clients who want to retrieve statements about a given candidate. The request is a datastructure of the following format: - -$$ -{\left({B}_{{h}},{C}_{{h}}\right)} -$$ - -where ${B}_{{h}}$ is the hash of the relay chain parent and ${C}_{{h}}$ is the candidate hash that was used to create a committed candidate receipt ([Definition -def-num-ref-](chapter-anv#defn-committed-candidate-receipt)). The response message is defined in [Definition -def-num-ref-](chapter-anv#net-msg-statement-fetching-response). - -::: -###### Definition -def-num- Statement Fetching Response {#net-msg-statement-fetching-response} -:::definition - -The statement fetching response is sent by nodes to the clients who issued a collation fetching request ([Definition -def-num-ref-](chapter-anv#net-msg-statement-fetching-request)). The response, ${R}$, is a varying datatype of the following format: - -$$ -{R}={\left\lbrace\begin{matrix}{0}&\rightarrow&{C}_{{r}}\end{matrix}\right.} -$$ - -where ${C}_{{r}}$ is the committed candidate receipt ([Definition -def-num-ref-](chapter-anv#defn-committed-candidate-receipt)). No response is returned if no statement is found. - -::: -#### -sec-num- Dispute Request {#net-msg-dispute-request} - -The dispute request is sent by clients who want to issue a dispute about a candidate. The request, ${D}_{{r}}$, is a datastructure of the following format: - -$$ -{D}_{{r}}={\left({C}_{{r}},{S}_{{i}},{I}_{{v}},{V}_{{v}}\right)} -$$ -$$ -{I}_{{v}}={\left({A}_{{i}},{A}_{{s}},{k}_{{i}}\right)} -$$ -$$ -{V}_{{v}}={\left({A}_{{i}},{A}_{{s}},{k}_{{v}}\right)} -$$ -$$ -{k}_{{i}}={\left\lbrace\begin{matrix}{0}&\rightarrow&\phi\end{matrix}\right.} -$$ -$$ -{k}_{{v}}={\left\lbrace\begin{matrix}{0}&\rightarrow&\phi\\{1}&\rightarrow&{C}_{{h}}\\{2}&\rightarrow&{C}_{{h}}\\{3}&\rightarrow&\phi\end{matrix}\right.} -$$ - -**where** -- ${C}_{{r}}$ is the candidate that is being disputed. The structure is a candidate receipt ([Definition -def-num-ref-](chapter-anv#defn-candidate-receipt)). - -- ${S}_{{i}}$ is an unsigned 32-bit integer indicating the session index the candidate appears in. - -- ${I}_{{v}}$ is the invalid vote that makes up the request. - -- ${V}_{{v}}$ is the valid vote that makes this dispute request valid. - -- ${A}_{{i}}$ is an unsigned 32-bit integer indicating the validator index in the authority set ([Definition -def-num-ref-](chap-sync#defn-authority-list)). - -- ${A}_{{s}}$ is the signature of the validator. - -- ${k}_{{i}}$ is a varying datatype and implies the dispute statement. *0* indicates an explicit statement. - -- ${k}_{{v}}$ is a varying datatype and implies the dispute statement. - - - ${0}$ indicates an explicit statement. - - - ${1}$ indicates a seconded statement on a candidate, ${C}_{{h}}$, from the backing phase. ${C}_{{h}}$ is the hash of the candidate. - - - ${2}$ indicates a valid statement on a candidate, ${C}_{{h}}$, from the backing phase. ${C}_{{h}}$ is the hash of the candidate. - - - ${3}$ indicates an approval vote from the approval checking phase. - -The response message is defined in [Section -sec-num-ref-](chapter-anv#net-msg-dispute-response). - -#### -sec-num- Dispute Response {#net-msg-dispute-response} - -The dispute response is sent by nodes to the clients who who issued a dispute request ([Section -sec-num-ref-](chapter-anv#net-msg-dispute-request)). The response, ${R}$, is a varying type of the following format: - -$$ -{R}={\left\lbrace\begin{matrix}{0}&\rightarrow&\phi\end{matrix}\right.} -$$ - -where ${0}$ indicates that the dispute was successfully processed. - ## -sec-num- Definitions {#sect-anv-definitions} ###### Definition -def-num- Collator {#defn-collator}