sc_subspace_block_relay/
protocol.rs

1//! Relay protocol defines.
2
3//!
4//! The components in the system:
5//! 1. Relay users like consensus, execution. They implement the use case
6//!    specific logic that drives the relay protocol. This has a client
7//!    side stub, and a server side task to process incoming requests.
8//! 2. Relay protocol that is agnostic to the relay user. The protocol
9//!    is abstracted to be reused for different use cases. The protocol
10//!    also has corresponding client/server side components.
11//! 3. Protocol backend: relay user specific abstraction used by the relay
12//!    protocol to populate the protocol messages
13//!
14//! Nodes advertise/exchange DownloadUnits with each other. DownloadUnit has
15//! two parts:
16//! - ProtocolUnits: the part fetched by the relay protocol. This is bulk of
17//!   the data transfer that we would like to optimize
18//! - Rest of the download unit, handled directly by the relay user
19//!
20//! Examples:
21//! 1. Consensus
22//!    DownloadUnit = Block, ProtocolUnit = extrinsics
23//!    The extrinsics are handled by the protocol, remaining block
24//!    fields are directly filled by the caller. The protocol backend
25//!    helps fetch blocks/transactions from the substrate backend
26//! 2. Execution
27//!    TODO
28//! 3. Other possible use cases (e.g) reconcile/sync the transaction pool
29//!    between two nodes. In this case, DownloadUnit = transaction pool,
30//!    ProtocolUnit = transaction
31//!
32//! The download has two phases:
33//! -  Initial request/response
34//!    Ideally, download of all the protocol units in the download unit should
35//!    be completed during this phase
36//! -  Reconcile phase
37//!    If the initial phase could not complete the download, additional
38//!    request/response messages are initiated by the protocol to fetch the
39//!    protocol units
40//!
41
42pub(crate) mod compact_block;
43
44use crate::types::RelayError;
45use parity_scale_codec::{Decode, Encode};
46
47/// The resolved protocol unit related info
48pub(crate) struct Resolved<ProtocolUnitId, ProtocolUnit> {
49    /// The protocol unit Id.
50    pub(crate) protocol_unit_id: ProtocolUnitId,
51
52    /// The protocol unit
53    pub(crate) protocol_unit: ProtocolUnit,
54
55    /// If it was resolved locally, or if it had to be
56    /// fetched from the server (local miss)
57    pub(crate) locally_resolved: bool,
58}
59
60/// The relay user specific backend for the client side
61pub(crate) trait ClientBackend<ProtocolUnitId, ProtocolUnit>: Send + Sync {
62    /// Returns the protocol unit for the protocol unit id.
63    fn protocol_unit(&self, protocol_unit_id: &ProtocolUnitId) -> Option<ProtocolUnit>;
64}
65
66/// The relay user specific backend for the server side
67pub(crate) trait ServerBackend<DownloadUnitId, ProtocolUnitId, ProtocolUnit>:
68    Send + Sync
69{
70    /// Returns the protocol units for the given download unit, to be returned
71    /// with the initial response. Some of the items may have the full entry
72    /// along with the Id (e.g) consensus may choose to return the full
73    /// transaction for inherents/small transactions in the block. And return
74    /// only the Tx hash for the remaining extrinsics. Further protocol
75    /// handshake would be used only for resolving these remaining items.
76    fn download_unit_members(
77        &self,
78        id: &DownloadUnitId,
79    ) -> Result<Vec<ProtocolUnitInfo<ProtocolUnitId, ProtocolUnit>>, RelayError>;
80
81    /// Returns the protocol unit for the given download/protocol unit.
82    fn protocol_unit(
83        &self,
84        download_unit_id: &DownloadUnitId,
85        protocol_unit_id: &ProtocolUnitId,
86    ) -> Option<ProtocolUnit>;
87}
88
89/// The protocol unit info carried in the initial response
90#[derive(Encode, Decode)]
91pub(crate) struct ProtocolUnitInfo<ProtocolUnitId, ProtocolUnit> {
92    /// The protocol unit Id
93    pub(crate) id: ProtocolUnitId,
94
95    /// The server can optionally return the protocol unit
96    /// as part of the initial response. No further
97    /// action is needed on client side to resolve it
98    pub(crate) unit: Option<ProtocolUnit>,
99}
sc_subspace_block_relay/protocol.rs

sc_subspace_block_relay/
protocol.rs
