Add PVF module documentation (#6293)

* Add PVF module documentation

TODO (once the PRs land):

- [ ] Document executor parametrization.

- [ ] Document CPU time measurement of timeouts.

* Update node/core/pvf/src/lib.rs

Co-authored-by: Andrei Sandu <54316454+sandreim@users.noreply.github.com>

* Clarify meaning of PVF acronym

* Move PVF doc to implementer's guide

* Clean up implementer's guide a bit

* Add page for PVF types

* pvf: Better separation between crate docs and implementer's guide

* ci: Add "prevalidating" to the dictionary

* ig: Remove types/chain.md

The types contained therein did not exist and the file was not referenced
anywhere.

Co-authored-by: Andrei Sandu <54316454+sandreim@users.noreply.github.com>

polkadot/roadmap/implementers-guide/src/SUMMARY.md

@@ -75,7 +75,6 @@
     - [Availability](types/availability.md)
     - [Overseer and Subsystem Protocol](types/overseer-protocol.md)
     - [Runtime](types/runtime.md)
-    - [Chain](types/chain.md)
     - [Messages](types/messages.md)
     - [Network](types/network.md)
     - [Approvals](types/approval.md)

polkadot/roadmap/implementers-guide/src/glossary.md

@@ -48,4 +48,3 @@ exactly one downward message queue.
 Also of use is the [Substrate Glossary](https://substrate.dev/docs/en/knowledgebase/getting-started/glossary).
 
 [0]: https://wiki.polkadot.network/docs/learn-consensus
-[1]: #pvf

polkadot/roadmap/implementers-guide/src/node/utility/candidate-validation.md

@@ -48,4 +48,39 @@ Once we have all parameters, we can spin up a background task to perform the val
 
 If we can assume the presence of the relay-chain state (that is, during processing [`CandidateValidationMessage`][CVM]`::ValidateFromChainState`) we can run all the checks that the relay-chain would run at the inclusion time thus confirming that the candidate will be accepted.
 
+### PVF Host
+
+The PVF host is responsible for handling requests to prepare and execute PVF
+code blobs.
+
+One high-level goal is to make PVF operations as deterministic as possible, to
+reduce the rate of disputes. Disputes can happen due to e.g. a job timing out on
+one machine, but not another. While we do not yet have full determinism, there
+are some dispute reduction mechanisms in place right now.
+
+#### Retrying execution requests
+
+If the execution request fails during **preparation**, we will retry if it is
+possible that the preparation error was transient (e.g. if the error was a panic
+or time out). We will only retry preparation if another request comes in after
+15 minutes, to ensure any potential transient conditions had time to be
+resolved. We will retry up to 5 times.
+
+If the actual **execution** of the artifact fails, we will retry once if it was
+an ambiguous error after a 1 second delay, to allow any potential transient
+conditions to clear.
+
+#### Preparation timeouts
+
+We use timeouts for both preparation and execution jobs to limit the amount of
+time they can take. As the time for a job can vary depending on the machine and
+load on the machine, this can potentially lead to disputes where some validators
+successfuly execute a PVF and others don't.
+
+One mitigation we have in place is a more lenient timeout for preparation during
+execution than during pre-checking. The rationale is that the PVF has already
+passed pre-checking, so we know it should be valid, and we allow it to take
+longer than expected, as this is likely due to an issue with the machine and not
+the PVF.
+
 [CVM]: ../../types/overseer-protocol.md#validationrequesttype

polkadot/roadmap/implementers-guide/src/node/utility/pvf-prechecker.md

@@ -12,11 +12,11 @@ This subsytem does not produce any output messages either. The subsystem will, h
 
 If the node is running in a collator mode, this subsystem will be disabled. The PVF pre-checker subsystem keeps track of the PVFs that are relevant for the subsystem. 
 
-To be relevant for the subsystem, a PVF must be returned by `pvfs_require_precheck` [`pvfs_require_precheck` runtime API][PVF pre-checking runtime API] in any of the active leaves. If the PVF is not present in any of the active leaves, it ceases to be relevant.
+To be relevant for the subsystem, a PVF must be returned by the [`pvfs_require_precheck` runtime API][PVF pre-checking runtime API] in any of the active leaves. If the PVF is not present in any of the active leaves, it ceases to be relevant.
 
 When a PVF just becomes relevant, the subsystem will send a message to the [Candidate Validation] subsystem asking for the pre-check.
 
-Upon receving a message from the candidate-validation subsystem, the pre-checker will note down that the PVF has its judgement and will also sign and submit a [`PvfCheckStatement`] via the [`submit_pvf_check_statement` runtime API][PVF pre-checking runtime API]. In case, a judgement was received for a PVF that is no longer in view it is ignored. It is possible that the candidate validation was not able to check the PVF. In that case, the PVF pre-checker will abstain and won't submit any check statements.
+Upon receving a message from the candidate-validation subsystem, the pre-checker will note down that the PVF has its judgement and will also sign and submit a [`PvfCheckStatement`][PvfCheckStatement] via the [`submit_pvf_check_statement` runtime API][PVF pre-checking runtime API]. In case, a judgement was received for a PVF that is no longer in view it is ignored. It is possible that the candidate validation was not able to check the PVF. In that case, the PVF pre-checker will abstain and won't submit any check statements.
 
 Since a vote only is valid during [one session][overview], the subsystem will have to resign and submit the statements for for the new session. The new session is assumed to be started if at least one of the leaves has a greater session index that was previously observed in any of the leaves.
 
@@ -28,4 +28,4 @@ If the node is not in the active validator set, it will still perform all the ch
 [Runtime API]: runtime-api.md
 [PVF pre-checking runtime API]: ../../runtime-api/pvf-prechecking.md
 [Candidate Validation]: candidate-validation.md
-[`PvfCheckStatement`]: ../../types/pvf-prechecking.md
+[PvfCheckStatement]: ../../types/pvf-prechecking.md#pvfcheckstatement

polkadot/roadmap/implementers-guide/src/types/candidate.md

@@ -92,6 +92,22 @@ struct CandidateDescriptor {
 }
 ```
 
+## `ValidationParams`
+
+```rust
+/// Validation parameters for evaluating the parachain validity function.
+pub struct ValidationParams {
+	/// Previous head-data.
+	pub parent_head: HeadData,
+	/// The collation body.
+	pub block_data: BlockData,
+	/// The current relay-chain block number.
+	pub relay_parent_number: RelayChainBlockNumber,
+	/// The relay-chain block's storage root.
+	pub relay_parent_storage_root: Hash,
+}
+```
+
 ## `PersistedValidationData`
 
 The validation data provides information about how to create the inputs for validation of a candidate. This information is derived from the chain state and will vary from para to para, although some of the fields may be the same for every para.

polkadot/roadmap/implementers-guide/src/types/chain.md

@@ -1,30 +0,0 @@
-# Chain
-
-Types pertaining to the relay-chain - events, structures, etc.
-
-## Block Import Event
-
-```rust
-/// Indicates that a new block has been added to the blockchain.
-struct BlockImportEvent {
-  /// The block header-hash.
-  hash: Hash,
-  /// The header itself.
-  header: Header,
-  /// Whether this block is considered the head of the best chain according to the
-  /// event emitter's fork-choice rule.
-  new_best: bool,
-}
-```
-
-## Block Finalization Event
-
-```rust
-/// Indicates that a new block has been finalized.
-struct BlockFinalizationEvent {
-  /// The block header-hash.
-  hash: Hash,
-  /// The header of the finalized block.
-  header: Header,
-}
-```

polkadot/roadmap/implementers-guide/src/types/overseer-protocol.md

@@ -681,9 +681,7 @@ enum ProvisionerMessage {
 
 The Runtime API subsystem is responsible for providing an interface to the state of the chain's runtime.
 
-This is fueled by an auxiliary type encapsulating all request types defined in the Runtime API section of the guide.
-
-> To do: link to the Runtime API section. Not possible currently because of https://github.com/Michael-F-Bryan/mdbook-linkcheck/issues/25. Once v0.7.1 is released it will work.
+This is fueled by an auxiliary type encapsulating all request types defined in the [Runtime API section](../runtime-api) of the guide.
 
 ```rust
 enum RuntimeApiRequest {

polkadot/roadmap/implementers-guide/src/types/pvf-prechecking.md

@@ -1,5 +1,7 @@
 # PVF Pre-checking types
 
+## `PvfCheckStatement`
+
 > ⚠️ This type was added in v2.
 
 One of the main units of information on which PVF pre-checking voting is build is the `PvfCheckStatement`.