referrerpolicy=no-referrer-when-downgrade

sc_consensus_aura/
import_queue.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
5
6// This program is free software: you can redistribute it and/or modify
7// it under the terms of the GNU General Public License as published by
8// the Free Software Foundation, either version 3 of the License, or
9// (at your option) any later version.
10
11// This program is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// You should have received a copy of the GNU General Public License
17// along with this program. If not, see <https://www.gnu.org/licenses/>.
18
19//! Module implementing the logic for verifying and importing AuRa blocks.
20
21use crate::{
22	standalone::SealVerificationError, AuthoritiesTracker, AuthorityId, CompatibilityMode, Error,
23	LOG_TARGET,
24};
25use codec::Codec;
26use log::{debug, info, trace};
27use prometheus_endpoint::Registry;
28use sc_client_api::{backend::AuxStore, BlockOf, UsageProvider};
29use sc_consensus::{
30	block_import::{BlockImport, BlockImportParams, ForkChoiceStrategy},
31	import_queue::{BasicQueue, BoxJustificationImport, DefaultImportQueue, Verifier},
32};
33use sc_consensus_slots::{check_equivocation, CheckedHeader, InherentDataProviderExt};
34use sc_telemetry::{telemetry, TelemetryHandle, CONSENSUS_DEBUG, CONSENSUS_TRACE};
35use sp_api::{ApiExt, ProvideRuntimeApi};
36use sp_block_builder::BlockBuilder as BlockBuilderApi;
37use sp_blockchain::{HeaderBackend, HeaderMetadata};
38use sp_consensus::Error as ConsensusError;
39use sp_consensus_aura::{inherents::AuraInherentData, AuraApi};
40use sp_consensus_slots::Slot;
41use sp_core::crypto::Pair;
42use sp_inherents::{CreateInherentDataProviders, InherentDataProvider as _};
43use sp_runtime::{
44	traits::{Block as BlockT, Header, NumberFor},
45	DigestItem,
46};
47use std::{fmt::Debug, sync::Arc};
48
49/// check a header has been signed by the right key. If the slot is too far in the future, an error
50/// will be returned. If it's successful, returns the pre-header and the digest item
51/// containing the seal.
52///
53/// This digest item will always return `Some` when used with `as_aura_seal`.
54fn check_header<C, B: BlockT, P: Pair>(
55	client: &C,
56	slot_now: Slot,
57	header: B::Header,
58	hash: B::Hash,
59	authorities: &[AuthorityId<P>],
60	check_for_equivocation: CheckForEquivocation,
61) -> Result<CheckedHeader<B::Header, (Slot, DigestItem)>, Error<B>>
62where
63	P::Public: Codec,
64	P::Signature: Codec,
65	C: sc_client_api::backend::AuxStore,
66{
67	let check_result =
68		crate::standalone::check_header_slot_and_seal::<B, P>(slot_now, header, authorities);
69
70	match check_result {
71		Ok((header, slot, seal)) => {
72			let expected_author = crate::standalone::slot_author::<P>(slot, &authorities);
73			let should_equiv_check = check_for_equivocation.check_for_equivocation();
74			if let (true, Some(expected)) = (should_equiv_check, expected_author) {
75				if let Some(equivocation_proof) =
76					check_equivocation(client, slot_now, slot, &header, expected)
77						.map_err(Error::Client)?
78				{
79					info!(
80						target: LOG_TARGET,
81						"Slot author is equivocating at slot {} with headers {:?} and {:?}",
82						slot,
83						equivocation_proof.first_header.hash(),
84						equivocation_proof.second_header.hash(),
85					);
86				}
87			}
88
89			Ok(CheckedHeader::Checked(header, (slot, seal)))
90		},
91		Err(SealVerificationError::Deferred(header, slot)) =>
92			Ok(CheckedHeader::Deferred(header, slot)),
93		Err(SealVerificationError::Unsealed) => Err(Error::HeaderUnsealed(hash)),
94		Err(SealVerificationError::BadSeal) => Err(Error::HeaderBadSeal(hash)),
95		Err(SealVerificationError::BadSignature) => Err(Error::BadSignature(hash)),
96		Err(SealVerificationError::SlotAuthorNotFound) => Err(Error::SlotAuthorNotFound),
97		Err(SealVerificationError::InvalidPreDigest(e)) => Err(Error::from(e)),
98	}
99}
100
101/// A verifier for Aura blocks.
102pub struct AuraVerifier<C, P: Pair, CIDP, B: BlockT> {
103	client: Arc<C>,
104	create_inherent_data_providers: CIDP,
105	check_for_equivocation: CheckForEquivocation,
106	telemetry: Option<TelemetryHandle>,
107	compatibility_mode: CompatibilityMode<NumberFor<B>>,
108	authorities_tracker: AuthoritiesTracker<P, B, C>,
109}
110
111impl<C, P: Pair, CIDP, B: BlockT> AuraVerifier<C, P, CIDP, B> {
112	pub(crate) fn new(
113		client: Arc<C>,
114		create_inherent_data_providers: CIDP,
115		check_for_equivocation: CheckForEquivocation,
116		telemetry: Option<TelemetryHandle>,
117		compatibility_mode: CompatibilityMode<NumberFor<B>>,
118	) -> Self {
119		Self {
120			client: client.clone(),
121			create_inherent_data_providers,
122			check_for_equivocation,
123			telemetry,
124			compatibility_mode,
125			authorities_tracker: AuthoritiesTracker::new(client),
126		}
127	}
128}
129
130#[async_trait::async_trait]
131impl<B, C, P, CIDP> Verifier<B> for AuraVerifier<C, P, CIDP, B>
132where
133	B: BlockT,
134	C: HeaderBackend<B>
135		+ HeaderMetadata<B, Error = sp_blockchain::Error>
136		+ ProvideRuntimeApi<B>
137		+ Send
138		+ Sync
139		+ sc_client_api::backend::AuxStore,
140	C::Api: BlockBuilderApi<B> + AuraApi<B, AuthorityId<P>> + ApiExt<B>,
141	P: Pair,
142	P::Public: Codec + Debug,
143	P::Signature: Codec,
144	CIDP: CreateInherentDataProviders<B, ()> + Send + Sync,
145	CIDP::InherentDataProviders: InherentDataProviderExt + Send + Sync,
146{
147	async fn verify(
148		&self,
149		mut block: BlockImportParams<B>,
150	) -> Result<BlockImportParams<B>, String> {
151		// Skip checks that include execution, if being told so or when importing only state.
152		//
153		// This is done for example when gap syncing and it is expected that the block after the gap
154		// was checked/chosen properly, e.g. by warp syncing to this block using a finality proof.
155		// Or when we are importing state only and can not verify the seal.
156		if block.with_state() || block.state_action.skip_execution_checks() {
157			// When we are importing only the state of a block, it will be the best block.
158			block.fork_choice = Some(ForkChoiceStrategy::Custom(block.with_state()));
159
160			return Ok(block)
161		}
162
163		let hash = block.header.hash();
164		let number = *block.header.number();
165		let parent_hash = *block.header.parent_hash();
166		let post_header = block.post_header();
167
168		let authorities = self
169			.authorities_tracker
170			.fetch_or_update(&block.header, &self.compatibility_mode)
171			.map_err(|e| {
172				format!("Could not fetch authorities for block {hash:?} at number {number}: {e}")
173			})?;
174
175		let create_inherent_data_providers = self
176			.create_inherent_data_providers
177			.create_inherent_data_providers(parent_hash, ())
178			.await
179			.map_err(|e| Error::<B>::Client(sp_blockchain::Error::Application(e)))?;
180
181		let mut inherent_data = create_inherent_data_providers
182			.create_inherent_data()
183			.await
184			.map_err(Error::<B>::Inherent)?;
185
186		let slot_now = create_inherent_data_providers.slot();
187
188		// we add one to allow for some small drift.
189		// FIXME #1019 in the future, alter this queue to allow deferring of
190		// headers
191		let checked_header = check_header::<C, B, P>(
192			&self.client,
193			slot_now + 1,
194			block.header,
195			hash,
196			&authorities[..],
197			self.check_for_equivocation,
198		)
199		.map_err(|e| e.to_string())?;
200		match checked_header {
201			CheckedHeader::Checked(pre_header, (slot, seal)) => {
202				// if the body is passed through, we need to use the runtime
203				// to check that the internally-set timestamp in the inherents
204				// actually matches the slot set in the seal.
205				if let Some(inner_body) = block.body.take() {
206					let new_block = B::new(pre_header.clone(), inner_body);
207
208					inherent_data.aura_replace_inherent_data(slot);
209
210					// skip the inherents verification if the runtime API is old or not expected to
211					// exist.
212					if self
213						.client
214						.runtime_api()
215						.has_api_with::<dyn BlockBuilderApi<B>, _>(parent_hash, |v| v >= 2)
216						.map_err(|e| e.to_string())?
217					{
218						sp_block_builder::check_inherents_with_data(
219							self.client.clone(),
220							parent_hash,
221							new_block.clone(),
222							&create_inherent_data_providers,
223							inherent_data,
224						)
225						.await
226						.map_err(|e| format!("Error checking block inherents {:?}", e))?;
227					}
228
229					let (_, inner_body) = new_block.deconstruct();
230					block.body = Some(inner_body);
231				}
232
233				self.authorities_tracker.import(&post_header).map_err(|e| {
234					format!(
235						"Could not import authorities for block {hash:?} at number {number}: {e}"
236					)
237				})?;
238
239				trace!(target: LOG_TARGET, "Checked {:?}; importing.", pre_header);
240				telemetry!(
241					self.telemetry;
242					CONSENSUS_TRACE;
243					"aura.checked_and_importing";
244					"pre_header" => ?pre_header,
245				);
246
247				block.header = pre_header;
248				block.post_digests.push(seal);
249				block.fork_choice = Some(ForkChoiceStrategy::LongestChain);
250				block.post_hash = Some(hash);
251
252				Ok(block)
253			},
254			CheckedHeader::Deferred(a, b) => {
255				debug!(target: LOG_TARGET, "Checking {:?} failed; {:?}, {:?}.", hash, a, b);
256				telemetry!(
257					self.telemetry;
258					CONSENSUS_DEBUG;
259					"aura.header_too_far_in_future";
260					"hash" => ?hash,
261					"a" => ?a,
262					"b" => ?b,
263				);
264				Err(format!("Header {:?} rejected: too far in the future", hash))
265			},
266		}
267	}
268}
269
270/// Should we check for equivocation of a block author?
271#[derive(Debug, Clone, Copy)]
272pub enum CheckForEquivocation {
273	/// Yes, check for equivocation.
274	///
275	/// This is the default setting for this.
276	Yes,
277	/// No, don't check for equivocation.
278	No,
279}
280
281impl CheckForEquivocation {
282	/// Should we check for equivocation?
283	fn check_for_equivocation(self) -> bool {
284		matches!(self, Self::Yes)
285	}
286}
287
288impl Default for CheckForEquivocation {
289	fn default() -> Self {
290		Self::Yes
291	}
292}
293
294/// Parameters of [`import_queue`].
295pub struct ImportQueueParams<'a, Block: BlockT, I, C, S, CIDP> {
296	/// The block import to use.
297	pub block_import: I,
298	/// The justification import.
299	pub justification_import: Option<BoxJustificationImport<Block>>,
300	/// The client to interact with the chain.
301	pub client: Arc<C>,
302	/// Something that can create the inherent data providers.
303	pub create_inherent_data_providers: CIDP,
304	/// The spawner to spawn background tasks.
305	pub spawner: &'a S,
306	/// The prometheus registry.
307	pub registry: Option<&'a Registry>,
308	/// Should we check for equivocation?
309	pub check_for_equivocation: CheckForEquivocation,
310	/// Telemetry instance used to report telemetry metrics.
311	pub telemetry: Option<TelemetryHandle>,
312	/// Compatibility mode that should be used.
313	///
314	/// If in doubt, use `Default::default()`.
315	pub compatibility_mode: CompatibilityMode<NumberFor<Block>>,
316}
317
318/// Start an import queue for the Aura consensus algorithm.
319pub fn import_queue<P, Block, I, C, S, CIDP>(
320	ImportQueueParams {
321		block_import,
322		justification_import,
323		client,
324		create_inherent_data_providers,
325		spawner,
326		registry,
327		check_for_equivocation,
328		telemetry,
329		compatibility_mode,
330	}: ImportQueueParams<Block, I, C, S, CIDP>,
331) -> Result<DefaultImportQueue<Block>, sp_consensus::Error>
332where
333	Block: BlockT,
334	C::Api: BlockBuilderApi<Block> + AuraApi<Block, AuthorityId<P>> + ApiExt<Block>,
335	C: 'static
336		+ ProvideRuntimeApi<Block>
337		+ BlockOf
338		+ Send
339		+ Sync
340		+ AuxStore
341		+ UsageProvider<Block>
342		+ HeaderBackend<Block>
343		+ HeaderMetadata<Block, Error = sp_blockchain::Error>,
344	I: BlockImport<Block, Error = ConsensusError> + Send + Sync + 'static,
345	P: Pair + 'static,
346	P::Public: Codec + Debug,
347	P::Signature: Codec,
348	S: sp_core::traits::SpawnEssentialNamed,
349	CIDP: CreateInherentDataProviders<Block, ()> + Sync + Send + 'static,
350	CIDP::InherentDataProviders: InherentDataProviderExt + Send + Sync,
351{
352	let verifier = build_verifier::<P, _, _, _>(BuildVerifierParams {
353		client,
354		create_inherent_data_providers,
355		check_for_equivocation,
356		telemetry,
357		compatibility_mode,
358	});
359
360	Ok(BasicQueue::new(verifier, Box::new(block_import), justification_import, spawner, registry))
361}
362
363/// Parameters of [`build_verifier`].
364pub struct BuildVerifierParams<C, CIDP, N> {
365	/// The client to interact with the chain.
366	pub client: Arc<C>,
367	/// Something that can create the inherent data providers.
368	pub create_inherent_data_providers: CIDP,
369	/// Should we check for equivocation?
370	pub check_for_equivocation: CheckForEquivocation,
371	/// Telemetry instance used to report telemetry metrics.
372	pub telemetry: Option<TelemetryHandle>,
373	/// Compatibility mode that should be used.
374	///
375	/// If in doubt, use `Default::default()`.
376	pub compatibility_mode: CompatibilityMode<N>,
377}
378
379/// Build the [`AuraVerifier`]
380pub fn build_verifier<P: Pair, C, CIDP, B: BlockT>(
381	BuildVerifierParams {
382		client,
383		create_inherent_data_providers,
384		check_for_equivocation,
385		telemetry,
386		compatibility_mode,
387	}: BuildVerifierParams<C, CIDP, NumberFor<B>>,
388) -> AuraVerifier<C, P, CIDP, B> {
389	AuraVerifier::<_, P, _, _>::new(
390		client,
391		create_inherent_data_providers,
392		check_for_equivocation,
393		telemetry,
394		compatibility_mode,
395	)
396}