diff --git a/roadmap/implementors-guide/src/node/backing/candidate-backing.md b/roadmap/implementors-guide/src/node/backing/candidate-backing.md index 697db2381ebb..c4737f75e01e 100644 --- a/roadmap/implementors-guide/src/node/backing/candidate-backing.md +++ b/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 diff --git a/roadmap/implementors-guide/src/node/utility/provisioner.md b/roadmap/implementors-guide/src/node/utility/provisioner.md index 6c6c3c17cd3b..190f9cb7ae73 100644 --- a/roadmap/implementors-guide/src/node/utility/provisioner.md +++ b/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`. diff --git a/roadmap/implementors-guide/src/type-definitions.md b/roadmap/implementors-guide/src/type-definitions.md index 793078610818..7843fbddfef9 100644 --- a/roadmap/implementors-guide/src/type-definitions.md +++ b/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), +} +``` + ## Host Configuration The internal-to-runtime configuration of the parachain host. This is expected to be altered only by governance procedures.