cumulus_pallet_parachain_system/
consensus_hook.rs

1// Copyright (C) Parity Technologies (UK) Ltd.
2// This file is part of Cumulus.
3// SPDX-License-Identifier: Apache-2.0
4
5// Licensed under the Apache License, Version 2.0 (the "License");
6// you may not use this file except in compliance with the License.
7// You may obtain a copy of the License at
8//
9// 	http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing, software
12// distributed under the License is distributed on an "AS IS" BASIS,
13// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14// See the License for the specific language governing permissions and
15// limitations under the License.
16
17//! The definition of a [`ConsensusHook`] trait for consensus logic to manage the backlog
18//! of parachain blocks ready to submit to the relay chain, as well as some basic implementations.
19
20use super::relay_state_snapshot::RelayChainStateProof;
21use core::num::NonZeroU32;
22use frame_support::weights::Weight;
23
24/// The possible capacity of the unincluded segment.
25#[derive(Clone, Debug, PartialEq)]
26pub struct UnincludedSegmentCapacity(UnincludedSegmentCapacityInner);
27
28impl UnincludedSegmentCapacity {
29	pub(crate) fn get(&self) -> u32 {
30		match self.0 {
31			UnincludedSegmentCapacityInner::ExpectParentIncluded => 1,
32			UnincludedSegmentCapacityInner::Value(v) => v.get(),
33		}
34	}
35
36	pub(crate) fn is_expecting_included_parent(&self) -> bool {
37		match self.0 {
38			UnincludedSegmentCapacityInner::ExpectParentIncluded => true,
39			UnincludedSegmentCapacityInner::Value(_) => false,
40		}
41	}
42}
43
44#[derive(Clone, Debug, PartialEq)]
45pub(crate) enum UnincludedSegmentCapacityInner {
46	ExpectParentIncluded,
47	Value(NonZeroU32),
48}
49
50impl From<NonZeroU32> for UnincludedSegmentCapacity {
51	fn from(value: NonZeroU32) -> Self {
52		UnincludedSegmentCapacity(UnincludedSegmentCapacityInner::Value(value))
53	}
54}
55
56/// The consensus hook for dealing with the unincluded segment.
57///
58/// Higher-level and user-configurable consensus logic is more informed about the
59/// desired unincluded segment length, as well as any rules for adapting it dynamically
60/// according to the relay-chain state.
61pub trait ConsensusHook {
62	/// This hook is called partway through the `set_validation_data` inherent in parachain-system.
63	///
64	/// The hook is allowed to panic if customized consensus rules aren't met and is required
65	/// to return a maximum capacity for the unincluded segment with weight consumed.
66	fn on_state_proof(state_proof: &RelayChainStateProof) -> (Weight, UnincludedSegmentCapacity);
67}
68
69/// A special consensus hook for handling the migration to asynchronous backing gracefully,
70/// even if collators haven't been updated to provide the last included parent in the state
71/// proof yet.
72///
73/// This behaves as though the parent is included, even if the relay chain state proof doesn't
74/// contain the included para head. If the para head is present in the state proof, this does ensure
75/// the parent is included.
76pub struct ExpectParentIncluded;
77
78impl ConsensusHook for ExpectParentIncluded {
79	fn on_state_proof(_state_proof: &RelayChainStateProof) -> (Weight, UnincludedSegmentCapacity) {
80		(
81			Weight::zero(),
82			UnincludedSegmentCapacity(UnincludedSegmentCapacityInner::ExpectParentIncluded),
83		)
84	}
85}
86
87/// A consensus hook for a fixed unincluded segment length. This hook does nothing but
88/// set the capacity of the unincluded segment to the constant N.
89///
90/// Since it is illegal to provide an unincluded segment length of 0, this sets a minimum of
91/// 1.
92pub struct FixedCapacityUnincludedSegment<const N: u32>;
93
94impl<const N: u32> ConsensusHook for FixedCapacityUnincludedSegment<N> {
95	fn on_state_proof(_state_proof: &RelayChainStateProof) -> (Weight, UnincludedSegmentCapacity) {
96		(
97			Weight::zero(),
98			NonZeroU32::new(core::cmp::max(N, 1))
99				.expect("1 is the minimum value and non-zero; qed")
100				.into(),
101		)
102	}
103}
104
105/// A fixed-capacity unincluded segment hook, which requires that the parent block is
106/// included prior to the current block being authored.
107///
108/// This is a simple type alias around a fixed-capacity unincluded segment with a size of 1.
109pub type RequireParentIncluded = FixedCapacityUnincludedSegment<1>;
cumulus_pallet_parachain_system/consensus_hook.rs

cumulus_pallet_parachain_system/
consensus_hook.rs
