Implement Runtime APIs (#1411)

* create a README on Runtime APIs

* add ParaId type

* write up runtime APIs

* more preamble

* rename

* rejig runtime APIs

* add occupied_since to `BlockNumber`

* skeleton crate for runtime API subsystem

* improve group_for_core

* improve docs on availability cores runtime API

* guide: freed -> free

* add primitives for runtime APIs

* create a v1 ParachainHost API trait

* guide: make validation code return `Option`al.

* skeleton runtime API helpers

* make parachain-host runtime-generic

* skeleton for most runtime API implementation functions

* guide: add runtime API helper methods

* implement new helpers of the inclusion module

* guide: remove retries check, as it is unneeded

* implement helpers for scheduler module for Runtime APIs

* clean up `validator_groups` implementation

* implement next_rotation_at and last_rotation_at

* guide: more helpers on GroupRotationInfo

* almost finish implementing runtime APIs

* add explicit block parameter to runtime API fns

* guide: generalize number parameter

* guide: add group_responsible to occupied-core

* update primitives due to guide changes

* finishing touches on runtime API implementation; squash warnings

* break out runtime API impl to separate file

* add tests for next_up logic

* test group rotation info

* point to filed TODO

* remove unused TODO [now]

* indentation

* guide: para -> para_id

* rename para field to para_id for core meta

* remove reference to outdated AvailabilityCores type

* add an event in `inclusion` for candidates being included or timing out

* guide: candidate events

* guide: adjust language

* Candidate events type from guide and adjust inclusion event

* implement `candidate_events` runtime API

* fix runtime test compilation

* max -> min

* fix typos

* guide: add `RuntimeAPIRequest::CandidateEvents`

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

@@ -59,7 +59,19 @@ struct GroupRotationInfo {
 impl GroupRotationInfo {
 	/// Returns the index of the group needed to validate the core at the given index,
 	/// assuming the given amount of cores/groups.
-	fn group_for_core(core_index: usize, cores: usize) -> usize;
+	fn group_for_core(&self, core_index, cores) -> GroupIndex;
+
+	/// Returns the block number of the next rotation after the current block. If the current block
+	/// is 10 and the rotation frequency is 5, this should return 15.
+	///
+	/// If the group rotation frequency is 0, returns 0.
+	fn next_rotation_at(&self) -> BlockNumber;
+
+	/// Returns the block number of the last rotation before or including the current block. If the
+	/// current block is 10 and the rotation frequency is 5, this should return 10.
+	///
+	/// If the group rotation frequency is 0, returns 0.
+	fn last_rotation_at(&self) -> BlockNumber;
 }
 
 /// Returns the validator groups and rotation info localized based on the block whose state
@@ -81,7 +93,7 @@ This is all the information that a validator needs about scheduling for the curr
 ```rust
 struct OccupiedCore {
 	/// The ID of the para occupying the core.
-	para: ParaId,
+	para_id: ParaId,
 	/// If this core is freed by availability, this is the assignment that is next up on this
 	/// core, if any. None if there is nothing queued for this core.
 	next_up_on_available: Option<ScheduledCore>,
@@ -97,11 +109,13 @@ struct OccupiedCore {
 	/// validators has attested to availability on-chain. A 2/3+ majority of `1` bits means that
 	/// this will be available.
 	availability: Bitfield,
+	/// The group assigned to distribute availability pieces of this candidate.
+	group_responsible: GroupIndex,
 }
 
 struct ScheduledCore {
 	/// The ID of a para scheduled.
-	para: ParaId,
+	para_id: ParaId,
 	/// The collator required to author the block, if any.
 	collator: Option<CollatorId>,
 }
@@ -171,7 +185,7 @@ fn session_index_for_child(at: Block) -> SessionIndex;
 Fetch the validation code used by a para, making the given `OccupiedCoreAssumption`.
 
 ```rust
-fn validation_code(at: Block, ParaId, OccupiedCoreAssumption) -> ValidationCode;
+fn validation_code(at: Block, ParaId, OccupiedCoreAssumption) -> Option<ValidationCode>;
 ```
 
 ## Candidate Pending Availability
@@ -181,3 +195,20 @@ Get the receipt of a candidate pending availability. This returns `Some` for any
 ```rust
 fn candidate_pending_availability(at: Block, ParaId) -> Option<CommittedCandidateReceipt>;
 ```
+
+## Candidate Events
+
+Yields a vector of events concerning candidates that occurred within the given block.
+
+```rust
+enum CandidateEvent {
+	/// This candidate receipt was backed in the most recent block.
+	CandidateBacked(CandidateReceipt, HeadData),
+	/// This candidate receipt was included and became a parablock at the most recent block.
+	CandidateIncluded(CandidateReceipt, HeadData),
+	/// This candidate receipt was not made available in time and timed out.
+	CandidateTimedOut(CandidateReceipt, HeadData),
+}
+
+fn candidate_events(at: Block) -> Vec<CandidateEvent>;
+```