polkadot_parachain_primitives/
primitives.rs

1// Copyright (C) Parity Technologies (UK) Ltd.
2// This file is part of Polkadot.
3
4// Polkadot is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8
9// Polkadot is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12// GNU General Public License for more details.
13
14// You should have received a copy of the GNU General Public License
15// along with Polkadot.  If not, see <http://www.gnu.org/licenses/>.
16
17//! Primitive types which are strictly necessary from a parachain-execution point
18//! of view.
19
20use alloc::vec::Vec;
21
22use bounded_collections::{BoundedVec, ConstU32};
23use codec::{CompactAs, Decode, DecodeWithMemTracking, Encode, MaxEncodedLen};
24use scale_info::TypeInfo;
25use serde::{Deserialize, Serialize};
26use sp_core::{bytes, RuntimeDebug, TypeId};
27use sp_runtime::traits::Hash as _;
28use sp_weights::Weight;
29
30use polkadot_core_primitives::{Hash, OutboundHrmpMessage};
31
32/// Block number type used by the relay chain.
33pub use polkadot_core_primitives::BlockNumber as RelayChainBlockNumber;
34
35/// Parachain head data included in the chain.
36#[derive(
37	PartialEq,
38	Eq,
39	Clone,
40	PartialOrd,
41	Ord,
42	Encode,
43	Decode,
44	DecodeWithMemTracking,
45	RuntimeDebug,
46	derive_more::From,
47	TypeInfo,
48	Serialize,
49	Deserialize,
50)]
51#[cfg_attr(feature = "std", derive(Hash, Default))]
52pub struct HeadData(#[serde(with = "bytes")] pub Vec<u8>);
53
54impl HeadData {
55	/// Returns the hash of this head data.
56	pub fn hash(&self) -> Hash {
57		sp_runtime::traits::BlakeTwo256::hash(&self.0)
58	}
59}
60
61impl codec::EncodeLike<HeadData> for alloc::vec::Vec<u8> {}
62
63/// Parachain validation code.
64#[derive(
65	PartialEq,
66	Eq,
67	Clone,
68	Encode,
69	Decode,
70	DecodeWithMemTracking,
71	RuntimeDebug,
72	derive_more::From,
73	TypeInfo,
74	Serialize,
75	Deserialize,
76)]
77#[cfg_attr(feature = "std", derive(Hash))]
78pub struct ValidationCode(#[serde(with = "bytes")] pub Vec<u8>);
79
80impl ValidationCode {
81	/// Get the blake2-256 hash of the validation code bytes.
82	pub fn hash(&self) -> ValidationCodeHash {
83		ValidationCodeHash(sp_runtime::traits::BlakeTwo256::hash(&self.0[..]))
84	}
85}
86
87/// Unit type wrapper around [`type@Hash`] that represents the blake2-256 hash
88/// of validation code in particular.
89///
90/// This type is produced by [`ValidationCode::hash`].
91///
92/// This type makes it easy to enforce that a hash is a validation code hash on the type level.
93#[derive(
94	Clone,
95	Copy,
96	Encode,
97	Decode,
98	DecodeWithMemTracking,
99	Hash,
100	Eq,
101	PartialEq,
102	PartialOrd,
103	Ord,
104	TypeInfo,
105)]
106pub struct ValidationCodeHash(Hash);
107
108impl core::fmt::Display for ValidationCodeHash {
109	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
110		self.0.fmt(f)
111	}
112}
113
114impl core::fmt::Debug for ValidationCodeHash {
115	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
116		write!(f, "{:?}", self.0)
117	}
118}
119
120impl AsRef<[u8]> for ValidationCodeHash {
121	fn as_ref(&self) -> &[u8] {
122		self.0.as_ref()
123	}
124}
125
126impl From<Hash> for ValidationCodeHash {
127	fn from(hash: Hash) -> ValidationCodeHash {
128		ValidationCodeHash(hash)
129	}
130}
131
132impl From<[u8; 32]> for ValidationCodeHash {
133	fn from(hash: [u8; 32]) -> ValidationCodeHash {
134		ValidationCodeHash(hash.into())
135	}
136}
137
138impl core::fmt::LowerHex for ValidationCodeHash {
139	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
140		core::fmt::LowerHex::fmt(&self.0, f)
141	}
142}
143
144/// Parachain block data.
145///
146/// Contains everything required to validate para-block, may contain block and witness data.
147#[derive(PartialEq, Eq, Clone, Encode, Decode, derive_more::From, TypeInfo, RuntimeDebug)]
148#[cfg_attr(feature = "std", derive(Serialize, Deserialize))]
149pub struct BlockData(#[cfg_attr(feature = "std", serde(with = "bytes"))] pub Vec<u8>);
150
151/// Unique identifier of a parachain.
152#[derive(
153	Clone,
154	CompactAs,
155	Copy,
156	Decode,
157	DecodeWithMemTracking,
158	Default,
159	Encode,
160	Eq,
161	Hash,
162	MaxEncodedLen,
163	Ord,
164	PartialEq,
165	PartialOrd,
166	Debug,
167	serde::Serialize,
168	serde::Deserialize,
169	TypeInfo,
170)]
171#[cfg_attr(feature = "std", derive(derive_more::Display))]
172pub struct Id(u32);
173
174impl codec::EncodeLike<u32> for Id {}
175impl codec::EncodeLike<Id> for u32 {}
176
177impl TypeId for Id {
178	const TYPE_ID: [u8; 4] = *b"para";
179}
180
181impl From<Id> for u32 {
182	fn from(x: Id) -> Self {
183		x.0
184	}
185}
186
187impl From<u32> for Id {
188	fn from(x: u32) -> Self {
189		Id(x)
190	}
191}
192
193impl From<usize> for Id {
194	fn from(x: usize) -> Self {
195		// can't panic, so need to truncate
196		let x = x.try_into().unwrap_or(u32::MAX);
197		Id(x)
198	}
199}
200
201// When we added a second From impl for Id, type inference could no longer
202// determine which impl should apply for things like `5.into()`. It therefore
203// raised a bunch of errors in our test code, scattered throughout the
204// various modules' tests, that there is no impl of `From<i32>` (`i32` being
205// the default numeric type).
206//
207// We can't use `cfg(test)` here, because that configuration directive does not
208// propagate between crates, which would fail to fix tests in crates other than
209// this one.
210//
211// Instead, let's take advantage of the observation that what really matters for a
212// ParaId within a test context is that it is unique and constant. I believe that
213// there is no case where someone does `(-1).into()` anyway, but if they do, it
214// never matters whether the actual contained ID is `-1` or `4294967295`. Nobody
215// does arithmetic on a `ParaId`; doing so would be a bug.
216impl From<i32> for Id {
217	fn from(x: i32) -> Self {
218		Id(x as u32)
219	}
220}
221
222// System parachain ID is considered `< 2000`.
223const SYSTEM_INDEX_END: u32 = 1999;
224const PUBLIC_INDEX_START: u32 = 2000;
225
226/// The ID of the first publicly registrable parachain.
227pub const LOWEST_PUBLIC_ID: Id = Id(PUBLIC_INDEX_START);
228
229impl Id {
230	/// Create an `Id`.
231	pub const fn new(id: u32) -> Self {
232		Self(id)
233	}
234}
235
236/// Determine if a parachain is a system parachain or not.
237pub trait IsSystem {
238	/// Returns `true` if a parachain is a system parachain, `false` otherwise.
239	fn is_system(&self) -> bool;
240}
241
242impl IsSystem for Id {
243	fn is_system(&self) -> bool {
244		self.0 <= SYSTEM_INDEX_END
245	}
246}
247
248impl core::ops::Add<u32> for Id {
249	type Output = Self;
250
251	fn add(self, other: u32) -> Self {
252		Self(self.0 + other)
253	}
254}
255
256impl core::ops::Sub<u32> for Id {
257	type Output = Self;
258
259	fn sub(self, other: u32) -> Self {
260		Self(self.0 - other)
261	}
262}
263
264#[derive(
265	Clone, Copy, Default, Encode, Decode, Eq, PartialEq, Ord, PartialOrd, RuntimeDebug, TypeInfo,
266)]
267pub struct Sibling(pub Id);
268
269impl From<Id> for Sibling {
270	fn from(i: Id) -> Self {
271		Self(i)
272	}
273}
274
275impl From<Sibling> for Id {
276	fn from(i: Sibling) -> Self {
277		i.0
278	}
279}
280
281impl AsRef<Id> for Sibling {
282	fn as_ref(&self) -> &Id {
283		&self.0
284	}
285}
286
287impl TypeId for Sibling {
288	const TYPE_ID: [u8; 4] = *b"sibl";
289}
290
291impl From<Sibling> for u32 {
292	fn from(x: Sibling) -> Self {
293		x.0.into()
294	}
295}
296
297impl From<u32> for Sibling {
298	fn from(x: u32) -> Self {
299		Sibling(x.into())
300	}
301}
302
303impl IsSystem for Sibling {
304	fn is_system(&self) -> bool {
305		IsSystem::is_system(&self.0)
306	}
307}
308
309/// A type that uniquely identifies an HRMP channel. An HRMP channel is established between two
310/// paras. In text, we use the notation `(A, B)` to specify a channel between A and B. The channels
311/// are unidirectional, meaning that `(A, B)` and `(B, A)` refer to different channels. The
312/// convention is that we use the first item tuple for the sender and the second for the recipient.
313/// Only one channel is allowed between two participants in one direction, i.e. there cannot be 2
314/// different channels identified by `(A, B)`. A channel with the same para id in sender and
315/// recipient is invalid. That is, however, not enforced.
316#[derive(
317	Clone,
318	PartialEq,
319	Eq,
320	PartialOrd,
321	Ord,
322	Encode,
323	Decode,
324	DecodeWithMemTracking,
325	RuntimeDebug,
326	TypeInfo,
327)]
328#[cfg_attr(feature = "std", derive(Hash))]
329pub struct HrmpChannelId {
330	/// The para that acts as the sender in this channel.
331	pub sender: Id,
332	/// The para that acts as the recipient in this channel.
333	pub recipient: Id,
334}
335
336impl HrmpChannelId {
337	/// Returns true if the given id corresponds to either the sender or the recipient.
338	pub fn is_participant(&self, id: Id) -> bool {
339		id == self.sender || id == self.recipient
340	}
341}
342
343/// A message from a parachain to its Relay Chain.
344pub type UpwardMessage = Vec<u8>;
345
346/// Something that should be called when a downward message is received.
347pub trait DmpMessageHandler {
348	/// Handle some incoming DMP messages (note these are individual XCM messages).
349	///
350	/// Also, process messages up to some `max_weight`.
351	fn handle_dmp_messages(
352		iter: impl Iterator<Item = (RelayChainBlockNumber, Vec<u8>)>,
353		max_weight: Weight,
354	) -> Weight;
355}
356impl DmpMessageHandler for () {
357	fn handle_dmp_messages(
358		iter: impl Iterator<Item = (RelayChainBlockNumber, Vec<u8>)>,
359		_max_weight: Weight,
360	) -> Weight {
361		iter.for_each(drop);
362		Weight::zero()
363	}
364}
365
366/// The aggregate XCMP message format.
367#[derive(
368	Copy,
369	Clone,
370	Eq,
371	PartialEq,
372	Ord,
373	PartialOrd,
374	Encode,
375	Decode,
376	TypeInfo,
377	RuntimeDebug,
378	MaxEncodedLen,
379)]
380pub enum XcmpMessageFormat {
381	/// Encoded `VersionedXcm` messages, all concatenated.
382	ConcatenatedVersionedXcm,
383	/// Encoded `Vec<u8>` messages, all concatenated.
384	ConcatenatedEncodedBlob,
385	/// One or more channel control signals; these should be interpreted immediately upon receipt
386	/// from the relay-chain.
387	Signals,
388}
389
390/// Something that should be called for each batch of messages received over XCMP.
391pub trait XcmpMessageHandler {
392	/// Handle some incoming XCMP messages (note these are the big one-per-block aggregate
393	/// messages).
394	///
395	/// Also, process messages up to some `max_weight`.
396	fn handle_xcmp_messages<'a, I: Iterator<Item = (Id, RelayChainBlockNumber, &'a [u8])>>(
397		iter: I,
398		max_weight: Weight,
399	) -> Weight;
400}
401impl XcmpMessageHandler for () {
402	fn handle_xcmp_messages<'a, I: Iterator<Item = (Id, RelayChainBlockNumber, &'a [u8])>>(
403		iter: I,
404		_max_weight: Weight,
405	) -> Weight {
406		for _ in iter {}
407		Weight::zero()
408	}
409}
410
411/// Validation parameters for evaluating the parachain validity function.
412// TODO: balance downloads (https://github.com/paritytech/polkadot/issues/220)
413#[derive(PartialEq, Eq, Decode, Clone)]
414#[cfg_attr(feature = "std", derive(Debug, Encode))]
415pub struct ValidationParams {
416	/// Previous head-data.
417	pub parent_head: HeadData,
418	/// The collation body.
419	pub block_data: BlockData,
420	/// The current relay-chain block number.
421	pub relay_parent_number: RelayChainBlockNumber,
422	/// The relay-chain block's storage root.
423	pub relay_parent_storage_root: Hash,
424}
425
426/// Maximum number of HRMP messages allowed per candidate.
427///
428/// We also use this as a generous limit, which still prevents possible memory exhaustion, from
429/// malicious parachains that may otherwise return a huge amount of messages in `ValidationResult`.
430pub const MAX_HORIZONTAL_MESSAGE_NUM: u32 = 16 * 1024;
431/// Maximum number of UMP messages allowed per candidate.
432///
433/// We also use this as a generous limit, which still prevents possible memory exhaustion, from
434/// malicious parachains that may otherwise return a huge amount of messages in `ValidationResult`.
435pub const MAX_UPWARD_MESSAGE_NUM: u32 = 16 * 1024;
436
437pub type UpwardMessages = BoundedVec<UpwardMessage, ConstU32<MAX_UPWARD_MESSAGE_NUM>>;
438
439pub type HorizontalMessages =
440	BoundedVec<OutboundHrmpMessage<Id>, ConstU32<MAX_HORIZONTAL_MESSAGE_NUM>>;
441
442/// The result of parachain validation.
443// TODO: balance uploads (https://github.com/paritytech/polkadot/issues/220)
444#[derive(PartialEq, Eq, Clone, Encode)]
445#[cfg_attr(feature = "std", derive(Debug, Decode))]
446pub struct ValidationResult {
447	/// New head data that should be included in the relay chain state.
448	pub head_data: HeadData,
449	/// An update to the validation code that should be scheduled in the relay chain.
450	pub new_validation_code: Option<ValidationCode>,
451	/// Upward messages send by the Parachain.
452	pub upward_messages: UpwardMessages,
453	/// Outbound horizontal messages sent by the parachain.
454	pub horizontal_messages: HorizontalMessages,
455	/// Number of downward messages that were processed by the Parachain.
456	///
457	/// It is expected that the Parachain processes them from first to last.
458	pub processed_downward_messages: u32,
459	/// The mark which specifies the block number up to which all inbound HRMP messages are
460	/// processed.
461	pub hrmp_watermark: RelayChainBlockNumber,
462}
polkadot_parachain_primitives/primitives.rs

polkadot_parachain_primitives/
primitives.rs
