guide: validation data refactoring (#1576)

* guide: validation data refactoring

* address grumbles from review

* Update roadmap/implementers-guide/src/types/candidate.md

Co-authored-by: Bernhard Schuster <bernhard@ahoi.io>

* last comments from review

Co-authored-by: Sergei Shulepov <sergei@parity.io>
Co-authored-by: Bernhard Schuster <bernhard@ahoi.io>

polkadot/roadmap/implementers-guide/src/runtime-api/README.md

@@ -37,3 +37,19 @@ The next sections will contain information on specific runtime APIs. The format
 /// best for the implementation to return an error indicating the failure mode.
 fn some_runtime_api(at: Block, arg1: Type1, arg2: Type2, ...) -> ReturnValue;
 ```
+
+Certain runtime APIs concerning the state of a para require the caller to provide an `OccupiedCoreAssumption`. This indicates how the result of the runtime API should be computed if there is a candidate from the para occupying an availability core in the [Inclusion Module](../runtime/inclusion.md).
+
+The choices of assumption are whether the candidate occupying that core should be assumed to have been made available and included or timed out and discarded, along with a third option to assert that the core was not occupied. This choice affects everything from the parent head-data, the validation code, and the state of message-queues. Typically, users will take the assumption that either the core was free or that the occupying candidate was included, as timeouts are expected only in adversarial circumstances and even so, only in a small minority of blocks directly following validator set rotations.
+
+```rust
+/// An assumption being made about the state of an occupied core.
+enum OccupiedCoreAssumption {
+    /// The candidate occupying the core was made available and included to free the core.
+    Included,
+    /// The candidate occupying the core timed out and freed the core without advancing the para.
+    TimedOut,
+    /// The core was not occupied to begin with.
+    Free,
+}
+```

polkadot/roadmap/implementers-guide/src/runtime-api/full-validation-data.md

@@ -0,0 +1,7 @@
+# Full Validation Data
+
+Yields the full [`ValidationData`](../types/candidate.md#validationdata) at the state of a given block.
+
+```rust
+fn full_validation_data(at: Block, ParaId, OccupiedCoreAssumption) -> Option<ValidationData>;
+```

polkadot/roadmap/implementers-guide/src/runtime-api/global-validation-data.md

@@ -1,7 +0,0 @@
-# Global Validation Data
-
-Yields the [`GlobalValidationData`](../types/candidate.md#globalvalidationschedule) at the state of a given block. This applies to all para candidates with the relay-parent equal to that block.
-
-```rust
-fn global_validation_data(at: Block) -> GlobalValidationData;
-```

polkadot/roadmap/implementers-guide/src/runtime-api/local-validation-data.md

@@ -1,23 +0,0 @@
-# Local Validation Data
-
-Yields the [`LocalValidationData`](../types/candidate.md#localvalidationdata) for the given [`ParaId`](../types/candidate.md#paraid) along with an assumption that should be used if the para currently occupies a core: whether the candidate occupying that core should be assumed to have been made available and included or timed out and discarded, along with a third option to assert that the core was not occupied. This choice affects everything from the parent head-data, the validation code, and the state of message-queues. Typically, users will take the assumption that either the core was free or that the occupying candidate was included, as timeouts are expected only in adversarial circumstances and even so, only in a small minority of blocks directly following validator set rotations.
-
-The documentation of [`LocalValidationData`](../types/candidate.md#localvalidationdata) has more information on this dichotomy.
-
-```rust
-/// An assumption being made about the state of an occupied core.
-enum OccupiedCoreAssumption {
-    /// The candidate occupying the core was made available and included to free the core.
-    Included,
-    /// The candidate occupying the core timed out and freed the core without advancing the para.
-    TimedOut,
-    /// The core was not occupied to begin with.
-    Free,
-}
-
-/// Returns the local validation data for the given para and occupied core assumption.
-///
-/// Returns `None` if either the para is not registered or the assumption is `Freed`
-/// and the para already occupies a core.
-fn local_validation_data(at: Block, ParaId, OccupiedCoreAssumption) -> Option<LocalValidationData>;
-```

polkadot/roadmap/implementers-guide/src/runtime-api/persisted-validation-data.md

@@ -0,0 +1,11 @@
+# Persisted Validation Data
+
+Yields the [`PersistedValidationData`](../types/candidate.md#persistedvalidationdata) for the given [`ParaId`](../types/candidate.md#paraid) along with an assumption that should be used if the para currently occupies a core:
+
+```rust
+/// Returns the persisted validation data for the given para and occupied core assumption.
+///
+/// Returns `None` if either the para is not registered or the assumption is `Freed`
+/// and the para already occupies a core.
+fn persisted_validation_data(at: Block, ParaId, OccupiedCoreAssumption) -> Option<PersistedValidationData>;
+```