mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-06-13 15:11:03 +00:00
Markdown linter (#1309)
* Add markdown linting - add linter default rules - adapt rules to current code - fix the code for linting to pass - add CI check fix #1243 * Fix markdown for Substrate * Fix tooling install * Fix workflow * Add documentation * Remove trailing spaces * Update .github/.markdownlint.yaml Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> * Fix mangled markdown/lists * Fix captalization issues on known words
This commit is contained in:
Chevdor
@@ -1,30 +1,43 @@
|
||||
# Network Bridge
|
||||
|
||||
One of the main features of the overseer/subsystem duality is to avoid shared ownership of resources and to communicate via message-passing. However, implementing each networking subsystem as its own network protocol brings a fair share of challenges.
|
||||
One of the main features of the overseer/subsystem duality is to avoid shared ownership of resources and to communicate
|
||||
via message-passing. However, implementing each networking subsystem as its own network protocol brings a fair share of
|
||||
challenges.
|
||||
|
||||
The most notable challenge is coordinating and eliminating race conditions of peer connection and disconnection events. If we have many network protocols that peers are supposed to be connected on, it is difficult to enforce that a peer is indeed connected on all of them or the order in which those protocols receive notifications that peers have connected. This becomes especially difficult when attempting to share peer state across protocols. All of the Parachain-Host's gossip protocols eliminate DoS with a data-dependency on current chain heads. However, it is inefficient and confusing to implement the logic for tracking our current chain heads as well as our peers' on each of those subsystems. Having one subsystem for tracking this shared state and distributing it to the others is an improvement in architecture and efficiency.
|
||||
The most notable challenge is coordinating and eliminating race conditions of peer connection and disconnection events.
|
||||
If we have many network protocols that peers are supposed to be connected on, it is difficult to enforce that a peer is
|
||||
indeed connected on all of them or the order in which those protocols receive notifications that peers have connected.
|
||||
This becomes especially difficult when attempting to share peer state across protocols. All of the Parachain-Host's
|
||||
gossip protocols eliminate DoS with a data-dependency on current chain heads. However, it is inefficient and confusing
|
||||
to implement the logic for tracking our current chain heads as well as our peers' on each of those subsystems. Having
|
||||
one subsystem for tracking this shared state and distributing it to the others is an improvement in architecture and
|
||||
efficiency.
|
||||
|
||||
One other piece of shared state to track is peer reputation. When peers are found to have provided value or cost, we adjust their reputation accordingly.
|
||||
One other piece of shared state to track is peer reputation. When peers are found to have provided value or cost, we
|
||||
adjust their reputation accordingly.
|
||||
|
||||
So in short, this Subsystem acts as a bridge between an actual network component and a subsystem's protocol. The implementation of the underlying network component is beyond the scope of this module. We make certain assumptions about the network component:
|
||||
* The network allows registering of protocols and multiple versions of each protocol.
|
||||
* The network handles version negotiation of protocols with peers and only connects the peer on the highest version of the protocol.
|
||||
* Each protocol has its own peer-set, although there may be some overlap.
|
||||
* The network provides peer-set management utilities for discovering the peer-IDs of validators and a means of dialing peers with given IDs.
|
||||
So in short, this Subsystem acts as a bridge between an actual network component and a subsystem's protocol. The
|
||||
implementation of the underlying network component is beyond the scope of this module. We make certain assumptions about
|
||||
the network component:
|
||||
- The network allows registering of protocols and multiple versions of each protocol.
|
||||
- The network handles version negotiation of protocols with peers and only connects the peer on the highest version of
|
||||
the protocol.
|
||||
- Each protocol has its own peer-set, although there may be some overlap.
|
||||
- The network provides peer-set management utilities for discovering the peer-IDs of validators and a means of dialing
|
||||
peers with given IDs.
|
||||
|
||||
|
||||
The network bridge makes use of the peer-set feature, but is not generic over peer-set. Instead, it exposes two peer-sets that event producers can attach to: `Validation` and `Collation`. More information can be found on the documentation of the [`NetworkBridgeMessage`][NBM].
|
||||
The network bridge makes use of the peer-set feature, but is not generic over peer-set. Instead, it exposes two
|
||||
peer-sets that event producers can attach to: `Validation` and `Collation`. More information can be found on the
|
||||
documentation of the [`NetworkBridgeMessage`][NBM].
|
||||
|
||||
## Protocol
|
||||
|
||||
Input: [`NetworkBridgeMessage`][NBM]
|
||||
|
||||
|
||||
Output:
|
||||
- [`ApprovalDistributionMessage`][AppD]`::NetworkBridgeUpdate`
|
||||
- [`BitfieldDistributionMessage`][BitD]`::NetworkBridgeUpdate`
|
||||
- [`CollatorProtocolMessage`][CollP]`::NetworkBridgeUpdate`
|
||||
- [`StatementDistributionMessage`][StmtD]`::NetworkBridgeUpdate`
|
||||
Output: - [`ApprovalDistributionMessage`][AppD]`::NetworkBridgeUpdate` -
|
||||
[`BitfieldDistributionMessage`][BitD]`::NetworkBridgeUpdate` -
|
||||
[`CollatorProtocolMessage`][CollP]`::NetworkBridgeUpdate` -
|
||||
[`StatementDistributionMessage`][StmtD]`::NetworkBridgeUpdate`
|
||||
|
||||
## Functionality
|
||||
|
||||
@@ -37,7 +50,8 @@ enum WireMessage<M> {
|
||||
}
|
||||
```
|
||||
|
||||
and instantiates this type twice, once using the [`ValidationProtocolV1`][VP1] message type, and once with the [`CollationProtocolV1`][CP1] message type.
|
||||
and instantiates this type twice, once using the [`ValidationProtocolV1`][VP1] message type, and once with the
|
||||
[`CollationProtocolV1`][CP1] message type.
|
||||
|
||||
```rust
|
||||
type ValidationV1Message = WireMessage<ValidationProtocolV1>;
|
||||
@@ -46,17 +60,21 @@ type CollationV1Message = WireMessage<CollationProtocolV1>;
|
||||
|
||||
### Startup
|
||||
|
||||
On startup, we register two protocols with the underlying network utility. One for validation and one for collation. We register only version 1 of each of these protocols.
|
||||
On startup, we register two protocols with the underlying network utility. One for validation and one for collation. We
|
||||
register only version 1 of each of these protocols.
|
||||
|
||||
### Main Loop
|
||||
|
||||
The bulk of the work done by this subsystem is in responding to network events, signals from the overseer, and messages from other subsystems.
|
||||
The bulk of the work done by this subsystem is in responding to network events, signals from the overseer, and messages
|
||||
from other subsystems.
|
||||
|
||||
Each network event is associated with a particular peer-set.
|
||||
|
||||
### Overseer Signal: `ActiveLeavesUpdate`
|
||||
|
||||
The `activated` and `deactivated` lists determine the evolution of our local view over time. A `ProtocolMessage::ViewUpdate` is issued to each connected peer on each peer-set, and a `NetworkBridgeEvent::OurViewChange` is issued to each event handler for each protocol.
|
||||
The `activated` and `deactivated` lists determine the evolution of our local view over time. A
|
||||
`ProtocolMessage::ViewUpdate` is issued to each connected peer on each peer-set, and a
|
||||
`NetworkBridgeEvent::OurViewChange` is issued to each event handler for each protocol.
|
||||
|
||||
We only send view updates if the node has indicated that it has finished major blockchain synchronization.
|
||||
|
||||
@@ -64,24 +82,31 @@ If we are connected to the same peer on both peer-sets, we will send the peer tw
|
||||
|
||||
### Overseer Signal: `BlockFinalized`
|
||||
|
||||
We update our view's `finalized_number` to the provided one and delay `ProtocolMessage::ViewUpdate` and `NetworkBridgeEvent::OurViewChange` till the next `ActiveLeavesUpdate`.
|
||||
We update our view's `finalized_number` to the provided one and delay `ProtocolMessage::ViewUpdate` and
|
||||
`NetworkBridgeEvent::OurViewChange` till the next `ActiveLeavesUpdate`.
|
||||
|
||||
### Network Event: `PeerConnected`
|
||||
|
||||
Issue a `NetworkBridgeEvent::PeerConnected` for each [Event Handler](#event-handlers) of the peer-set and negotiated protocol version of the peer. Also issue a `NetworkBridgeEvent::PeerViewChange` and send the peer our current view, but only if the node has indicated that it has finished major blockchain synchronization. Otherwise, we only send the peer an empty view.
|
||||
Issue a `NetworkBridgeEvent::PeerConnected` for each [Event Handler](#event-handlers) of the peer-set and negotiated
|
||||
protocol version of the peer. Also issue a `NetworkBridgeEvent::PeerViewChange` and send the peer our current view, but
|
||||
only if the node has indicated that it has finished major blockchain synchronization. Otherwise, we only send the peer
|
||||
an empty view.
|
||||
|
||||
### Network Event: `PeerDisconnected`
|
||||
|
||||
Issue a `NetworkBridgeEvent::PeerDisconnected` for each [Event Handler](#event-handlers) of the peer-set and negotiated protocol version of the peer.
|
||||
Issue a `NetworkBridgeEvent::PeerDisconnected` for each [Event Handler](#event-handlers) of the peer-set and negotiated
|
||||
protocol version of the peer.
|
||||
|
||||
### Network Event: `ProtocolMessage`
|
||||
|
||||
Map the message onto the corresponding [Event Handler](#event-handlers) based on the peer-set this message was received on and dispatch via overseer.
|
||||
Map the message onto the corresponding [Event Handler](#event-handlers) based on the peer-set this message was received
|
||||
on and dispatch via overseer.
|
||||
|
||||
### Network Event: `ViewUpdate`
|
||||
|
||||
- Check that the new view is valid and note it as the most recent view update of the peer on this peer-set.
|
||||
- Map a `NetworkBridgeEvent::PeerViewChange` onto the corresponding [Event Handler](#event-handlers) based on the peer-set this message was received on and dispatch via overseer.
|
||||
- Map a `NetworkBridgeEvent::PeerViewChange` onto the corresponding [Event Handler](#event-handlers) based on the
|
||||
peer-set this message was received on and dispatch via overseer.
|
||||
|
||||
### `ReportPeer`
|
||||
|
||||
@@ -108,22 +133,23 @@ Map the message onto the corresponding [Event Handler](#event-handlers) based on
|
||||
|
||||
### `NewGossipTopology`
|
||||
|
||||
- Map all `AuthorityDiscoveryId`s to `PeerId`s and issue a corresponding `NetworkBridgeUpdate`
|
||||
to all validation subsystems.
|
||||
- Map all `AuthorityDiscoveryId`s to `PeerId`s and issue a corresponding `NetworkBridgeUpdate` to all validation
|
||||
subsystems.
|
||||
|
||||
## Event Handlers
|
||||
|
||||
Network bridge event handlers are the intended recipients of particular network protocol messages. These are each a variant of a message to be sent via the overseer.
|
||||
Network bridge event handlers are the intended recipients of particular network protocol messages. These are each a
|
||||
variant of a message to be sent via the overseer.
|
||||
|
||||
### Validation V1
|
||||
|
||||
* `ApprovalDistributionV1Message -> ApprovalDistributionMessage::NetworkBridgeUpdate`
|
||||
* `BitfieldDistributionV1Message -> BitfieldDistributionMessage::NetworkBridgeUpdate`
|
||||
* `StatementDistributionV1Message -> StatementDistributionMessage::NetworkBridgeUpdate`
|
||||
- `ApprovalDistributionV1Message -> ApprovalDistributionMessage::NetworkBridgeUpdate`
|
||||
- `BitfieldDistributionV1Message -> BitfieldDistributionMessage::NetworkBridgeUpdate`
|
||||
- `StatementDistributionV1Message -> StatementDistributionMessage::NetworkBridgeUpdate`
|
||||
|
||||
### Collation V1
|
||||
|
||||
* `CollatorProtocolV1Message -> CollatorProtocolMessage::NetworkBridgeUpdate`
|
||||
- `CollatorProtocolV1Message -> CollatorProtocolMessage::NetworkBridgeUpdate`
|
||||
|
||||
[NBM]: ../../types/overseer-protocol.md#network-bridge-message
|
||||
[AppD]: ../../types/overseer-protocol.md#approval-distribution-message
|
||||
|
||||
Reference in New Issue
Block a user