sc_network_common/sync/
message.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//! Network packet message types. These get serialized and put into the lower level protocol
20//! payload.
21
22use crate::role::Roles;
23
24use bitflags::bitflags;
25use codec::{Decode, Encode, Error, Input, Output};
26pub use generic::{BlockAnnounce, FromBlock};
27use sp_runtime::traits::{Block as BlockT, Header as HeaderT, NumberFor};
28
29/// Type alias for using the block request type using block type parameters.
30pub type BlockRequest<B> =
31	generic::BlockRequest<<B as BlockT>::Hash, <<B as BlockT>::Header as HeaderT>::Number>;
32
33/// Type alias for using the BlockData type using block type parameters.
34pub type BlockData<B> =
35	generic::BlockData<<B as BlockT>::Header, <B as BlockT>::Hash, <B as BlockT>::Extrinsic>;
36
37/// Type alias for using the BlockResponse type using block type parameters.
38pub type BlockResponse<B> =
39	generic::BlockResponse<<B as BlockT>::Header, <B as BlockT>::Hash, <B as BlockT>::Extrinsic>;
40
41// Bits of block data and associated artifacts to request.
42bitflags! {
43	/// Node roles bitmask.
44	pub struct BlockAttributes: u8 {
45		/// Include block header.
46		const HEADER = 0b00000001;
47		/// Include block body.
48		const BODY = 0b00000010;
49		/// Include block receipt.
50		const RECEIPT = 0b00000100;
51		/// Include block message queue.
52		const MESSAGE_QUEUE = 0b00001000;
53		/// Include a justification for the block.
54		const JUSTIFICATION = 0b00010000;
55		/// Include indexed transactions for a block.
56		const INDEXED_BODY = 0b00100000;
57	}
58}
59
60impl BlockAttributes {
61	/// Encodes attributes as big endian u32, compatible with SCALE-encoding (i.e the
62	/// significant byte has zero index).
63	pub fn to_be_u32(&self) -> u32 {
64		u32::from_be_bytes([self.bits(), 0, 0, 0])
65	}
66
67	/// Decodes attributes, encoded with the `encode_to_be_u32()` call.
68	pub fn from_be_u32(encoded: u32) -> Result<Self, Error> {
69		Self::from_bits(encoded.to_be_bytes()[0])
70			.ok_or_else(|| Error::from("Invalid BlockAttributes"))
71	}
72}
73
74impl Encode for BlockAttributes {
75	fn encode_to<T: Output + ?Sized>(&self, dest: &mut T) {
76		dest.push_byte(self.bits())
77	}
78}
79
80impl codec::EncodeLike for BlockAttributes {}
81
82impl Decode for BlockAttributes {
83	fn decode<I: Input>(input: &mut I) -> Result<Self, Error> {
84		Self::from_bits(input.read_byte()?).ok_or_else(|| Error::from("Invalid bytes"))
85	}
86}
87
88#[derive(Debug, PartialEq, Eq, Clone, Copy, Encode, Decode)]
89/// Block enumeration direction.
90pub enum Direction {
91	/// Enumerate in ascending order (from child to parent).
92	Ascending = 0,
93	/// Enumerate in descending order (from parent to canonical child).
94	Descending = 1,
95}
96
97/// Block state in the chain.
98#[derive(Debug, PartialEq, Eq, Clone, Copy, Encode, Decode)]
99pub enum BlockState {
100	/// Block is not part of the best chain.
101	Normal,
102	/// Latest best block.
103	Best,
104}
105
106/// Announcement summary used for debug logging.
107#[derive(Debug)]
108pub struct AnnouncementSummary<H: HeaderT> {
109	pub block_hash: H::Hash,
110	pub number: H::Number,
111	pub parent_hash: H::Hash,
112	pub state: Option<BlockState>,
113}
114
115impl<H: HeaderT> BlockAnnounce<H> {
116	pub fn summary(&self) -> AnnouncementSummary<H> {
117		AnnouncementSummary {
118			block_hash: self.header.hash(),
119			number: *self.header.number(),
120			parent_hash: *self.header.parent_hash(),
121			state: self.state,
122		}
123	}
124}
125
126/// Generic types.
127pub mod generic {
128	use super::{BlockAttributes, BlockState, Direction};
129	use crate::message::RequestId;
130	use codec::{Decode, Encode, Input, Output};
131	use sp_runtime::{EncodedJustification, Justifications};
132
133	/// Block data sent in the response.
134	#[derive(Debug, PartialEq, Eq, Clone, Encode, Decode)]
135	pub struct BlockData<Header, Hash, Extrinsic> {
136		/// Block header hash.
137		pub hash: Hash,
138		/// Block header if requested.
139		pub header: Option<Header>,
140		/// Block body if requested.
141		pub body: Option<Vec<Extrinsic>>,
142		/// Block body indexed transactions if requested.
143		pub indexed_body: Option<Vec<Vec<u8>>>,
144		/// Block receipt if requested.
145		pub receipt: Option<Vec<u8>>,
146		/// Block message queue if requested.
147		pub message_queue: Option<Vec<u8>>,
148		/// Justification if requested.
149		pub justification: Option<EncodedJustification>,
150		/// Justifications if requested.
151		pub justifications: Option<Justifications>,
152	}
153
154	/// Request block data from a peer.
155	#[derive(Debug, PartialEq, Eq, Clone, Encode, Decode)]
156	pub struct BlockRequest<Hash, Number> {
157		/// Unique request id.
158		pub id: RequestId,
159		/// Bits of block data to request.
160		pub fields: BlockAttributes,
161		/// Start from this block.
162		pub from: FromBlock<Hash, Number>,
163		/// Sequence direction.
164		pub direction: Direction,
165		/// Maximum number of blocks to return. An implementation defined maximum is used when
166		/// unspecified.
167		pub max: Option<u32>,
168	}
169
170	/// Identifies starting point of a block sequence.
171	#[derive(Debug, PartialEq, Eq, Clone, Encode, Decode)]
172	pub enum FromBlock<Hash, Number> {
173		/// Start with given hash.
174		Hash(Hash),
175		/// Start with given block number.
176		Number(Number),
177	}
178
179	/// Response to `BlockRequest`
180	#[derive(Debug, PartialEq, Eq, Clone, Encode, Decode)]
181	pub struct BlockResponse<Header, Hash, Extrinsic> {
182		/// Id of a request this response was made for.
183		pub id: RequestId,
184		/// Block data for the requested sequence.
185		pub blocks: Vec<BlockData<Header, Hash, Extrinsic>>,
186	}
187
188	/// Announce a new complete block on the network.
189	#[derive(Debug, PartialEq, Eq, Clone)]
190	pub struct BlockAnnounce<H> {
191		/// New block header.
192		pub header: H,
193		/// Block state. TODO: Remove `Option` and custom encoding when v4 becomes common.
194		pub state: Option<BlockState>,
195		/// Data associated with this block announcement, e.g. a candidate message.
196		pub data: Option<Vec<u8>>,
197	}
198
199	// Custom Encode/Decode impl to maintain backwards compatibility with v3.
200	// This assumes that the packet contains nothing but the announcement message.
201	// TODO: Get rid of it once protocol v4 is common.
202	impl<H: Encode> Encode for BlockAnnounce<H> {
203		fn encode_to<T: Output + ?Sized>(&self, dest: &mut T) {
204			self.header.encode_to(dest);
205			if let Some(state) = &self.state {
206				state.encode_to(dest);
207			}
208			if let Some(data) = &self.data {
209				data.encode_to(dest)
210			}
211		}
212	}
213
214	impl<H: Decode> Decode for BlockAnnounce<H> {
215		fn decode<I: Input>(input: &mut I) -> Result<Self, codec::Error> {
216			let header = H::decode(input)?;
217			let state = BlockState::decode(input).ok();
218			let data = Vec::decode(input).ok();
219			Ok(Self { header, state, data })
220		}
221	}
222}
223
224/// Handshake sent when we open a block announces substream.
225#[derive(Debug, PartialEq, Eq, Clone, Encode, Decode)]
226pub struct BlockAnnouncesHandshake<B: BlockT> {
227	/// Roles of the node.
228	pub roles: Roles,
229	/// Best block number.
230	pub best_number: NumberFor<B>,
231	/// Best block hash.
232	pub best_hash: B::Hash,
233	/// Genesis block hash.
234	pub genesis_hash: B::Hash,
235}
236
237impl<B: BlockT> BlockAnnouncesHandshake<B> {
238	pub fn build(
239		roles: Roles,
240		best_number: NumberFor<B>,
241		best_hash: B::Hash,
242		genesis_hash: B::Hash,
243	) -> Self {
244		Self { genesis_hash, roles, best_number, best_hash }
245	}
246}
sc_network_common/sync/message.rs

sc_network_common/sync/
message.rs
