cumulus_client_collator/
lib.rs

1// Copyright (C) Parity Technologies (UK) Ltd.
2// This file is part of Cumulus.
3// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
4
5// Cumulus is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9
10// Cumulus is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14
15// You should have received a copy of the GNU General Public License
16// along with Cumulus. If not, see <https://www.gnu.org/licenses/>.
17
18//! Cumulus Collator implementation for Substrate.
19use polkadot_node_primitives::CollationGenerationConfig;
20use polkadot_node_subsystem::messages::{CollationGenerationMessage, CollatorProtocolMessage};
21use polkadot_overseer::Handle as OverseerHandle;
22use polkadot_primitives::{CollatorPair, Id as ParaId};
23pub mod service;
24
25/// Relay-chain-driven collators are those whose block production is driven purely
26/// by new relay chain blocks and the most recently included parachain blocks
27/// within them.
28///
29/// This method of driving collators is not suited to anything but the most simple parachain
30/// consensus mechanisms, and this module may soon be deprecated.
31pub mod relay_chain_driven {
32	use futures::{
33		channel::{mpsc, oneshot},
34		prelude::*,
35	};
36	use polkadot_node_primitives::{CollationGenerationConfig, CollationResult};
37	use polkadot_node_subsystem::messages::{CollationGenerationMessage, CollatorProtocolMessage};
38	use polkadot_overseer::Handle as OverseerHandle;
39	use polkadot_primitives::{CollatorPair, Id as ParaId};
40
41	use cumulus_primitives_core::{relay_chain::Hash as PHash, PersistedValidationData};
42
43	/// A request to author a collation, based on the advancement of the relay chain.
44	///
45	/// See the module docs for more info on relay-chain-driven collators.
46	pub struct CollationRequest {
47		relay_parent: PHash,
48		pvd: PersistedValidationData,
49		sender: oneshot::Sender<Option<CollationResult>>,
50	}
51
52	impl CollationRequest {
53		/// Get the relay parent of the collation request.
54		pub fn relay_parent(&self) -> &PHash {
55			&self.relay_parent
56		}
57
58		/// Get the [`PersistedValidationData`] for the request.
59		pub fn persisted_validation_data(&self) -> &PersistedValidationData {
60			&self.pvd
61		}
62
63		/// Complete the request with a collation, if any.
64		pub fn complete(self, collation: Option<CollationResult>) {
65			let _ = self.sender.send(collation);
66		}
67	}
68
69	/// Initialize the collator with Polkadot's collation-generation
70	/// subsystem, returning a stream of collation requests to handle.
71	pub async fn init(
72		key: CollatorPair,
73		para_id: ParaId,
74		overseer_handle: OverseerHandle,
75	) -> mpsc::Receiver<CollationRequest> {
76		let mut overseer_handle = overseer_handle;
77
78		let (stream_tx, stream_rx) = mpsc::channel(0);
79		let config = CollationGenerationConfig {
80			key,
81			para_id,
82			collator: Some(Box::new(move |relay_parent, validation_data| {
83				// Cloning the channel on each usage effectively makes the channel
84				// unbounded. The channel is actually bounded by the block production
85				// and consensus systems of Polkadot, which limits the amount of possible
86				// blocks.
87				let mut stream_tx = stream_tx.clone();
88				let validation_data = validation_data.clone();
89				Box::pin(async move {
90					let (this_tx, this_rx) = oneshot::channel();
91					let request =
92						CollationRequest { relay_parent, pvd: validation_data, sender: this_tx };
93
94					if stream_tx.send(request).await.is_err() {
95						return None;
96					}
97
98					this_rx.await.ok().flatten()
99				})
100			})),
101		};
102
103		overseer_handle
104			.send_msg(CollationGenerationMessage::Initialize(config), "StartCollator")
105			.await;
106
107		overseer_handle
108			.send_msg(CollatorProtocolMessage::CollateOn(para_id), "StartCollator")
109			.await;
110
111		stream_rx
112	}
113}
114
115/// Initialize the collation-related subsystems on the relay-chain side.
116///
117/// This must be done prior to collation, and does not set up any callback for collation.
118/// For callback-driven collators, use the [`relay_chain_driven`] module.
119pub async fn initialize_collator_subsystems(
120	overseer_handle: &mut OverseerHandle,
121	key: CollatorPair,
122	para_id: ParaId,
123	reinitialize: bool,
124) {
125	let config = CollationGenerationConfig { key, para_id, collator: None };
126
127	if reinitialize {
128		overseer_handle
129			.send_msg(CollationGenerationMessage::Reinitialize(config), "StartCollator")
130			.await;
131	} else {
132		overseer_handle
133			.send_msg(CollationGenerationMessage::Initialize(config), "StartCollator")
134			.await;
135	}
136
137	overseer_handle
138		.send_msg(CollatorProtocolMessage::CollateOn(para_id), "StartCollator")
139		.await;
140}
cumulus_client_collator/lib.rs

cumulus_client_collator/
lib.rs
