expand validity subsystems descriptions independent of subsystems overview

[coriolinus]

Expand the descriptions of the validity module subsystems to clarify their interactions.

Only the Candidate Backing subsystem fully explores its internal job protocol. It is intended that other subsystems will have similar job protocols, but they are not fully specified, as the descriptions would largely be redundant.

[parity-cla-bot]

It looks like @coriolinus signed our Contributor License Agreement. 👍

Many thanks,

Parity Technologies CLA Bot

[rphmeier]

I'd suggest to leave Misbehavior Arbitration off the table for the same reasons described in #1161 (comment), although I wouldn't mind a double-vote reporting subsystem as part of this.

[rphmeier]

to avoid having an instantiation of the overseer signal variant in every subsystem message, I'd suggest omitting it here and having the subsystems accept an FromOverseer<T> { Signal(OverseerSignal), Communication(T) }. instead. This is what is done in the overseer implementation by @montekki as well

[coriolinus]

That's reasonable.

[coriolinus]

Alternately, we could remove an indirection layer by rewriting OverseerSignal:

enum OverseerSignal<T> {
  StartWork(Hash),
  StopWork(Hash),
  Message(T),
}

[rphmeier]

I'd suggest shortening to peers as opposed to peer validators, as we don't know that any of our peers are validators and for the purposes of gossip, only assume that validators are transitively connected via a largely full-node graph.

[coriolinus]

OK. I'd assumed that messages from non-validator peers just got dumped regardless as irrelevant; the whole point of separating out validators is that they're the ones who get to vote.

[rphmeier]

Yeah, I see where you're coming from. Regular peers can't issue their own messages but they can safely relay messages signed by validators, so I think it still fits that worldview just with better propagation. And then we don't need to worry about peer authentication.

[rphmeier]

It should be fine to receive a Valid(X) signed by A before a Seconded(Y). I can see the justification for not allowing it, but it does not seem to get us much of a win. Requiring that we know Seconded(Y) before Valid(Y) already restricts us to a bounded set of messages, and is simpler to implement (as it is a more focused condition).

[coriolinus]

Yes, I'll add that this state machine applies for each individual parablock candidate, not for all candidates from a particular validator.

[rphmeier]

And then there should be a small note in there about knowledge tracking for our peers, so we know who knows which candidates based on what they've sent or what we've sent them (this needs to be scoped to active relay-parent set)