Newer
Older
# Overseer Protocol
This chapter contains message types sent to and from the overseer, and the underlying subsystem message types that are transmitted using these.
## Overseer Signal
Signals from the overseer to a subsystem to request change in execution that has to be obeyed by the subsystem.
```rust
enum OverseerSignal {
/// Signal to start work localized to the relay-parent hash.
StartWork(Hash),
/// Signal to stop (or phase down) work localized to the relay-parent hash.
StopWork(Hash),
}
```
All subsystems have their own message types; all of them need to be able to listen for overseer signals as well. There are currently two proposals for how to handle that with unified communication channels:
1. Retaining the `OverseerSignal` definition above, add `enum FromOverseer<T> {Signal(OverseerSignal), Message(T)}`.
1. Add a generic varint to `OverseerSignal`: `Message(T)`.
Either way, there will be some top-level type encapsulating messages from the overseer to each subsystem.
## All Messages
## Availability Distribution Message
Messages received by the availability distribution subsystem.
```rust
enum AvailabilityDistributionMessage {
/// Distribute an availability chunk to other validators.
DistributeChunk(Hash, ErasureChunk),
/// Fetch an erasure chunk from network by candidate hash and chunk index.
FetchChunk(Hash, u32),
/// Event from the network.
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
/// An update on network state from the network bridge.
NetworkBridgeUpdate(NetworkBridgeEvent),
}
```
## Availability Store Message
Messages to and from the availability store.
```rust
enum AvailabilityStoreMessage {
/// Query the PoV of a candidate by hash.
QueryPoV(Hash, ResponseChannel<PoV>),
/// Query a specific availability chunk of the candidate's erasure-coding by validator index.
/// Returns the chunk and its inclusion proof against the candidate's erasure-root.
QueryChunk(Hash, ValidatorIndex, ResponseChannel<AvailabilityChunkAndProof>),
/// Store a specific chunk of the candidate's erasure-coding by validator index, with an
/// accompanying proof.
StoreChunk(Hash, ValidatorIndex, AvailabilityChunkAndProof),
}
```
## Bitfield Distribution Message
Messages received by the bitfield distribution subsystem.
```rust
enum BitfieldDistributionMessage {
/// Distribute a bitfield signed by a validator to other validators.
/// The bitfield distribution subsystem will assume this is indeed correctly signed.
DistributeBitfield(relay_parent, SignedAvailabilityBitfield),
/// Receive a network bridge update.
NetworkBridgeUpdate(NetworkBridgeEvent),
}
```
## Bitfield Signing Message
Currently, the bitfield signing subsystem receives no specific messages.
```rust
/// Non-instantiable message type
enum BitfieldSigningMessage { }
```
## Candidate Backing Message
```rust
enum CandidateBackingMessage {
/// Registers a stream listener for updates to the set of backable candidates that could be backed
/// in a child of the given relay-parent, referenced by its hash.
RegisterBackingWatcher(Hash, TODO),
/// Note that the Candidate Backing subsystem should second the given candidate in the context of the
/// given relay-parent (ref. by hash). This candidate must be validated using the provided PoV.
Second(Hash, CandidateReceipt, PoV),
/// Note a peer validator's statement about a particular candidate. Disagreements about validity must be escalated
/// to a broader check by Misbehavior Arbitration. Agreements are simply tallied until a quorum is reached.
Statement(Statement),
}
```
## Candidate Selection Message
These messages are sent to the [Candidate Selection subsystem](../node/backing/candidate-selection.md) as a means of providing feedback on its outputs.
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
```rust
enum CandidateSelectionMessage {
/// We recommended a particular candidate to be seconded, but it was invalid; penalize the collator.
Invalid(CandidateReceipt),
}
```
## Network Bridge Message
Messages received by the network bridge. This subsystem is invoked by others to manipulate access
to the low-level networking code.
```rust
enum NetworkBridgeMessage {
/// Register an event producer with the network bridge. This should be done early and cannot
/// be de-registered.
RegisterEventProducer(ProtocolId, Fn(NetworkBridgeEvent) -> AllMessages),
/// Report a cost or benefit of a peer. Negative values are costs, positive are benefits.
ReportPeer(PeerId, cost_benefit: i32),
/// Send a message to one or more peers on the given protocol ID.
SendMessage([PeerId], ProtocolId, Bytes),
}
```
## Network Bridge Update
These updates are posted from the [Network Bridge Subsystem](../node/utility/network-bridge.md) to other subsystems based on registered listeners.
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
```rust
struct View(Vec<Hash>); // Up to `N` (5?) chain heads.
enum NetworkBridgeEvent {
/// A peer with given ID is now connected.
PeerConnected(PeerId, ObservedRole), // role is one of Full, Light, OurGuardedAuthority, OurSentry
/// A peer with given ID is now disconnected.
PeerDisconnected(PeerId),
/// We received a message from the given peer. Protocol ID should be apparent from context.
PeerMessage(PeerId, Bytes),
/// The given peer has updated its description of its view.
PeerViewChange(PeerId, View), // guaranteed to come after peer connected event.
/// We have posted the given view update to all connected peers.
OurViewChange(View),
}
```
```rust
enum MisbehaviorReport {
/// These validator nodes disagree on this candidate's validity, please figure it out
///
/// Most likely, the list of statments all agree except for the final one. That's not
/// guaranteed, though; if somehow we become aware of lots of
/// statements disagreeing about the validity of a candidate before taking action,
/// this message should be dispatched with all of them, in arbitrary order.
///
/// This variant is also used when our own validity checks disagree with others'.
CandidateValidityDisagreement(CandidateReceipt, Vec<SignedFullStatement>),
/// I've noticed a peer contradicting itself about a particular candidate
SelfContradiction(CandidateReceipt, SignedFullStatement, SignedFullStatement),
/// This peer has seconded more than one parachain candidate for this relay parent head
DoubleVote(CandidateReceipt, SignedFullStatement, SignedFullStatement),
}
```
If this subsystem chooses to second a parachain block, it dispatches a `CandidateBackingSubsystemMessage`.
## PoV Distribution Message
```rust
enum PoVDistributionMessage {
/// Fetch a PoV from the network.
///
/// This `CandidateDescriptor` should correspond to a candidate seconded under the provided
/// relay-parent hash.
FetchPoV(Hash, CandidateDescriptor, ResponseChannel<PoV>),
/// Distribute a PoV for the given relay-parent and CandidateDescriptor.
/// The PoV should correctly hash to the PoV hash mentioned in the CandidateDescriptor
DistributePoV(Hash, CandidateDescriptor, PoV),
/// An update from the network bridge.
NetworkBridgeUpdate(NetworkBridgeEvent),
}
```
## Provisioner Message
```rust
/// This data becomes intrinsics or extrinsics which should be included in a future relay chain block.
enum ProvisionableData {
/// This bitfield indicates the availability of various candidate blocks.
Bitfield(Hash, SignedAvailabilityBitfield),
/// The Candidate Backing subsystem believes that this candidate is valid, pending availability.
BackedCandidate(BackedCandidate),
/// Misbehavior reports are self-contained proofs of validator misbehavior.
MisbehaviorReport(Hash, MisbehaviorReport),
/// Disputes trigger a broad dispute resolution process.
Dispute(Hash, Signature),
}
/// This data needs to make its way from the provisioner into the InherentData.
///
/// There, it is used to construct the InclusionInherent.
type ProvisionerInherentData = (SignedAvailabilityBitfields, Vec<BackedCandidate>);
/// Message to the Provisioner.
///
/// In all cases, the Hash is that of the relay parent.
enum ProvisionerMessage {
/// This message allows potential block authors to be kept updated with all new authorship data
/// as it becomes available.
RequestBlockAuthorshipData(Hash, Sender<ProvisionableData>),
/// This message allows external subsystems to request the set of bitfields and backed candidates
/// associated with a particular potential block hash.
///
/// This is expected to be used by a proposer, to inject that information into the InherentData
/// where it can be assembled into the InclusionInherent.
RequestInherentData(Hash, oneshot::Sender<ProvisionerInherentData>),
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
/// This data should become part of a relay chain block
ProvisionableData(ProvisionableData),
}
```
## Runtime API Message
The Runtime API subsystem is responsible for providing an interface to the state of the chain's runtime.
Other subsystems query this data by sending these messages.
```rust
enum RuntimeApiRequest {
/// Get the current validator set.
Validators(ResponseChannel<Vec<ValidatorId>>),
/// Get a signing context for bitfields and statements.
SigningContext(ResponseChannel<SigningContext>),
/// Get the validation code for a specific para, assuming execution under given block number, and
/// an optional block number representing an intermediate parablock executed in the context of
/// that block.
ValidationCode(ParaId, BlockNumber, Option<BlockNumber>, ResponseChannel<ValidationCode>),
}
enum RuntimeApiMessage {
/// Make a request of the runtime API against the post-state of the given relay-parent.
Request(Hash, RuntimeApiRequest),
}
```
## Statement Distribution Message
The Statement Distribution subsystem distributes signed statements and candidates from validators to other validators. It does this by distributing full statements, which embed the candidate receipt, as opposed to compact statements which don't.
It receives updates from the network bridge and signed statements to share with other validators.
```rust
enum StatementDistributionMessage {
/// An update from the network bridge.
NetworkBridgeUpdate(NetworkBridgeEvent),
/// We have validated a candidate and want to share our judgment with our peers.
/// The hash is the relay parent.
///
/// The statement distribution subsystem assumes that the statement should be correctly
/// signed.
}
```
## Validation Request Type
Various modules request that the [Candidate Validation subsystem](../node/utility/candidate-validation.md) validate a block with this message
```rust
enum CandidateValidationMessage {
/// Validate a candidate with provided parameters. Returns `Err` if an only if an internal
/// error is encountered. A bad candidate will return `Ok(false)`, while a good one will
/// return `Ok(true)`.
Validate(ValidationCode, CandidateReceipt, PoV, ResponseChannel<Result<bool>>),
}
```