sp_consensus_babe/
digests.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// 	http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18//! Private implementation details of BABE digests.
19
20use super::{
21	AllowedSlots, AuthorityId, AuthorityIndex, AuthoritySignature, BabeAuthorityWeight,
22	BabeEpochConfiguration, Randomness, Slot, BABE_ENGINE_ID,
23};
24
25#[cfg(not(feature = "std"))]
26use alloc::vec::Vec;
27use sp_core::sr25519::vrf::VrfSignature;
28use sp_runtime::{DigestItem, RuntimeDebug};
29
30use codec::{Decode, Encode, MaxEncodedLen};
31use scale_info::TypeInfo;
32
33/// Raw BABE primary slot assignment pre-digest.
34#[derive(Clone, RuntimeDebug, Encode, Decode, MaxEncodedLen, TypeInfo)]
35pub struct PrimaryPreDigest {
36	/// Authority index
37	pub authority_index: super::AuthorityIndex,
38	/// Slot
39	pub slot: Slot,
40	/// VRF signature
41	pub vrf_signature: VrfSignature,
42}
43
44/// BABE secondary slot assignment pre-digest.
45#[derive(Clone, RuntimeDebug, Encode, Decode, MaxEncodedLen, TypeInfo)]
46pub struct SecondaryPlainPreDigest {
47	/// Authority index
48	///
49	/// This is not strictly-speaking necessary, since the secondary slots
50	/// are assigned based on slot number and epoch randomness. But including
51	/// it makes things easier for higher-level users of the chain data to
52	/// be aware of the author of a secondary-slot block.
53	pub authority_index: super::AuthorityIndex,
54	/// Slot
55	pub slot: Slot,
56}
57
58/// BABE secondary deterministic slot assignment with VRF outputs.
59#[derive(Clone, RuntimeDebug, Encode, Decode, MaxEncodedLen, TypeInfo)]
60pub struct SecondaryVRFPreDigest {
61	/// Authority index
62	pub authority_index: super::AuthorityIndex,
63	/// Slot
64	pub slot: Slot,
65	/// VRF signature
66	pub vrf_signature: VrfSignature,
67}
68
69/// A BABE pre-runtime digest. This contains all data required to validate a
70/// block and for the BABE runtime module. Slots can be assigned to a primary
71/// (VRF based) and to a secondary (slot number based).
72#[derive(Clone, RuntimeDebug, Encode, Decode, MaxEncodedLen, TypeInfo)]
73pub enum PreDigest {
74	/// A primary VRF-based slot assignment.
75	#[codec(index = 1)]
76	Primary(PrimaryPreDigest),
77	/// A secondary deterministic slot assignment.
78	#[codec(index = 2)]
79	SecondaryPlain(SecondaryPlainPreDigest),
80	/// A secondary deterministic slot assignment with VRF outputs.
81	#[codec(index = 3)]
82	SecondaryVRF(SecondaryVRFPreDigest),
83}
84
85impl PreDigest {
86	/// Returns the slot number of the pre digest.
87	pub fn authority_index(&self) -> AuthorityIndex {
88		match self {
89			PreDigest::Primary(primary) => primary.authority_index,
90			PreDigest::SecondaryPlain(secondary) => secondary.authority_index,
91			PreDigest::SecondaryVRF(secondary) => secondary.authority_index,
92		}
93	}
94
95	/// Returns the slot of the pre digest.
96	pub fn slot(&self) -> Slot {
97		match self {
98			PreDigest::Primary(primary) => primary.slot,
99			PreDigest::SecondaryPlain(secondary) => secondary.slot,
100			PreDigest::SecondaryVRF(secondary) => secondary.slot,
101		}
102	}
103
104	/// Returns true if this pre-digest is for a primary slot assignment.
105	pub fn is_primary(&self) -> bool {
106		matches!(self, PreDigest::Primary(..))
107	}
108
109	/// Returns the weight _added_ by this digest, not the cumulative weight
110	/// of the chain.
111	pub fn added_weight(&self) -> crate::BabeBlockWeight {
112		match self {
113			PreDigest::Primary(_) => 1,
114			PreDigest::SecondaryPlain(_) | PreDigest::SecondaryVRF(_) => 0,
115		}
116	}
117
118	/// Returns the VRF output and proof, if they exist.
119	pub fn vrf_signature(&self) -> Option<&VrfSignature> {
120		match self {
121			PreDigest::Primary(primary) => Some(&primary.vrf_signature),
122			PreDigest::SecondaryVRF(secondary) => Some(&secondary.vrf_signature),
123			PreDigest::SecondaryPlain(_) => None,
124		}
125	}
126}
127
128/// Information about the next epoch. This is broadcast in the first block
129/// of the epoch.
130#[derive(Decode, Encode, PartialEq, Eq, Clone, RuntimeDebug)]
131pub struct NextEpochDescriptor {
132	/// The authorities.
133	pub authorities: Vec<(AuthorityId, BabeAuthorityWeight)>,
134
135	/// The value of randomness to use for the slot-assignment.
136	pub randomness: Randomness,
137}
138
139/// Information about the next epoch config, if changed. This is broadcast in the first
140/// block of the epoch, and applies using the same rules as `NextEpochDescriptor`.
141#[derive(
142	Decode, Encode, PartialEq, Eq, Clone, RuntimeDebug, MaxEncodedLen, scale_info::TypeInfo,
143)]
144pub enum NextConfigDescriptor {
145	/// Version 1.
146	#[codec(index = 1)]
147	V1 {
148		/// Value of `c` in `BabeEpochConfiguration`.
149		c: (u64, u64),
150		/// Value of `allowed_slots` in `BabeEpochConfiguration`.
151		allowed_slots: AllowedSlots,
152	},
153}
154
155impl From<NextConfigDescriptor> for BabeEpochConfiguration {
156	fn from(desc: NextConfigDescriptor) -> Self {
157		match desc {
158			NextConfigDescriptor::V1 { c, allowed_slots } => Self { c, allowed_slots },
159		}
160	}
161}
162
163/// A digest item which is usable with BABE consensus.
164pub trait CompatibleDigestItem: Sized {
165	/// Construct a digest item which contains a BABE pre-digest.
166	fn babe_pre_digest(seal: PreDigest) -> Self;
167
168	/// If this item is an BABE pre-digest, return it.
169	fn as_babe_pre_digest(&self) -> Option<PreDigest>;
170
171	/// Construct a digest item which contains a BABE seal.
172	fn babe_seal(signature: AuthoritySignature) -> Self;
173
174	/// If this item is a BABE signature, return the signature.
175	fn as_babe_seal(&self) -> Option<AuthoritySignature>;
176
177	/// If this item is a BABE epoch descriptor, return it.
178	fn as_next_epoch_descriptor(&self) -> Option<NextEpochDescriptor>;
179
180	/// If this item is a BABE config descriptor, return it.
181	fn as_next_config_descriptor(&self) -> Option<NextConfigDescriptor>;
182}
183
184impl CompatibleDigestItem for DigestItem {
185	fn babe_pre_digest(digest: PreDigest) -> Self {
186		DigestItem::PreRuntime(BABE_ENGINE_ID, digest.encode())
187	}
188
189	fn as_babe_pre_digest(&self) -> Option<PreDigest> {
190		self.pre_runtime_try_to(&BABE_ENGINE_ID)
191	}
192
193	fn babe_seal(signature: AuthoritySignature) -> Self {
194		DigestItem::Seal(BABE_ENGINE_ID, signature.encode())
195	}
196
197	fn as_babe_seal(&self) -> Option<AuthoritySignature> {
198		self.seal_try_to(&BABE_ENGINE_ID)
199	}
200
201	fn as_next_epoch_descriptor(&self) -> Option<NextEpochDescriptor> {
202		self.consensus_try_to(&BABE_ENGINE_ID)
203			.and_then(|x: super::ConsensusLog| match x {
204				super::ConsensusLog::NextEpochData(n) => Some(n),
205				_ => None,
206			})
207	}
208
209	fn as_next_config_descriptor(&self) -> Option<NextConfigDescriptor> {
210		self.consensus_try_to(&BABE_ENGINE_ID)
211			.and_then(|x: super::ConsensusLog| match x {
212				super::ConsensusLog::NextConfigData(n) => Some(n),
213				_ => None,
214			})
215	}
216}
sp_consensus_babe/digests.rs

sp_consensus_babe/
digests.rs
