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

polkadot_parachain_primitives/
primitives.rs
