update provisioner subsystem

roadmap/implementors-guide/src/node/backing/candidate-backing.md

@@ -6,7 +6,7 @@ Its role is to produce backable candidates for inclusion in new relay-chain bloc
 
 Note that though the candidate backing subsystem attempts to produce as many backable candidates as possible, it does _not_ attempt to choose a single authoritative one. The choice of which actually gets included is ultimately up to the block author, by whatever metrics it may use; those are opaque to this subsystem.
 
-Once a sufficient quorum has agreed that a candidate is valid, this subsystem notifies the [Overseer](/node/overseer.html), which in turn engages block production mechanisms to include the parablock.
+Once a sufficient quorum has agreed that a candidate is valid, this subsystem notifies the [Provisioner](/node/utility/provisioner.html), which in turn engages block production mechanisms to include the parablock.
 
 ## Protocol
 

roadmap/implementors-guide/src/node/utility/provisioner.md

@@ -1,30 +1,42 @@
 # Provisioner
 
-This subsystem is responsible for providing data to an external block authorship service beyond the scope of the [Overseer](/node/overseer.html) so that the block authorship service can author blocks containing data produced by various subsystems.
+Relay chain block authorship authority is governed by BABE and is beyond the scope of the Overseer and the rest of the subsystems. That said, ultimately the block author needs to select a set of backable parachain candidates and other consensus data, and assemble a block from them. This subsystem is responsible for providing the necessary data to all potential block authors.
 
-In particular, the data to provide:
+A major feature of the provisioner: this subsystem is responsible for ensuring that parachain block candidates are sufficiently available before sending them to potential block authors.
 
-- backable candidates and their backings
-- signed bitfields
-- misbehavior reports
-- dispute inherent
-    > TODO: needs fleshing out in validity module, related to blacklisting
+## Provisionable Data
 
-## Protocol
+### Backable Candidates
+
+The block author can choose 0 or 1 backable parachain candidates per parachain; the only constraint is that each backable candidate has the appropriate relay parent. However, the choice of a backable candidate must be the block author's; the provisioner must ensure that block authors are aware of all available backable candidates.
+
+> TODO: "and their backings": why?
+
+### Signed Bitfields
+
+Signed bitfields are attestations from a particular validator about which candidates it believes are available.
+
+> TODO: Are these actually included in the relay chain block, or just used to help decide whether a block is available and therefore a backable candidate?
+
+### Misbehavior Reports
 
-Input:
+Misbehavior reports contain proof that a validator or set of validators has misbehaved; they consist of a proof of some kind of misbehavior: double-voting, being the minority vote in a disputed block's vote, etc. These cause dots to be slashed and must be included in the block.
 
-- Bitfield(relay_parent, signed_bitfield)
-- BackableCandidate(relay_parent, candidate_receipt, backing)
-- RequestBlockAuthorshipData(relay_parent, response_channel)
+> TODO: This problem is mentioned elsewhere, but how do we force the block author to include a misbehavior report if they don't like its effects, i.e. they are among the nodes which get slashed?
+
+### Dispute Inherent
+
+> TODO: Is this different from a misbehavior report? How?
+
+## Protocol
+
+Input: [`ProvisionerMessage`](/type-definitions.html#provisioner-message)
 
 ## Functionality
 
 Use `StartWork` and `StopWork` to manage a set of jobs for relay-parents we might be building upon.
-Forward all messages to corresponding job, if any.
+Forward all messages to corresponding job.
 
 ## Block Authorship Provisioning Job
 
-Track all signed bitfields, all backable candidates received. Provide them to the `RequestBlockAuthorshipData` requester via the `response_channel`. If more than one backable candidate exists for a given `Para`, provide the first one received.
-
-> TODO: better candidate-choice rules.
+Track all signed bitfields, all backable candidates received. Provide them to the `RequestBlockAuthorshipData` requester via the `response_channel`.

roadmap/implementors-guide/src/type-definitions.md

@@ -173,6 +173,24 @@ enum MisbehaviorArbitrationMessage {
 }
 ```
 
+## Provisioner Message
+
+```rust
+/// Message to the Provisioner.
+///
+/// In all cases, the Hash is that of the relay parent.
+enum ProvisionerMessage {
+  /// This bitfield indicates the availability of various candidate blocks.
+  Bitfield(Hash, SignedAvailabilityBitfield),
+  /// The Candidate Backing subsystem believes that this candidate is backable, pending availability.
+  /// TODO: do we need any more data than this?
+  BackableCandidate(Hash, CandidateReceipt),
+  /// This message allows potential block authors to be kept updated with all new authorship data
+  /// as it becomes available.
+  RequestBlockAuthorshipData(Hash, Sender<CandidateReceipt>),
+}
+```
+
 ## Host Configuration
 
 The internal-to-runtime configuration of the parachain host. This is expected to be altered only by governance procedures.