Implement HRMP (#1900)

* HRMP: Update the impl guide

* HRMP: Incorporate the channel notifications into the guide

* HRMP: Renaming in the impl guide

* HRMP: Constrain the maximum number of HRMP messages per candidate

This commit addresses the HRMP part of https://github.com/paritytech/polkadot/issues/1869

* XCM: Introduce HRMP related message types

* HRMP: Data structures and plumbing

* HRMP: Configuration

* HRMP: Data layout

* HRMP: Acceptance & Enactment

* HRMP: Test base logic

* Update adder collator

* HRMP: Runtime API for accessing inbound messages

Also, removing some redundant fully-qualified names.

* HRMP: Add diagnostic logging in acceptance criteria

* HRMP: Additional tests

* Self-review fixes

* save test refactorings for the next time

* Missed a return statement.

* a formatting blip

* Add missing logic for appending HRMP digests

* Remove the channel contents vectors which became empty

* Tighten HRMP channel digests invariants.

* Apply suggestions from code review

Co-authored-by: Peter Goodspeed-Niklaus <coriolinus@users.noreply.github.com>

* Remove a note about sorting for channel id

* Add missing rustdocs to the configuration

* Clarify and update the invariant for HrmpChannelDigests

* Make the onboarding invariant less sloppy

Namely, introduce `Paras::is_valid_para` (in fact, it already is present
in the implementation) and hook up the invariant to that.

Note that this says "within a session" because I don't want to make it
super strict on the session boundary. The logic on the session boundary
should be extremely careful.

* Make `CandidateCheckContext` use T::BlockNumber for hrmp_watermark

Co-authored-by: Peter Goodspeed-Niklaus <coriolinus@users.noreply.github.com>

polkadot/parachain/src/primitives.rs

@@ -28,7 +28,7 @@ use serde::{Serialize, Deserialize};
 #[cfg(feature = "std")]
 use sp_core::bytes;
 
-use polkadot_core_primitives::Hash;
+use polkadot_core_primitives::{Hash, OutboundHrmpMessage};
 
 /// Block number type used by the relay chain.
 pub use polkadot_core_primitives::BlockNumber as RelayChainBlockNumber;
@@ -186,6 +186,21 @@ impl<T: Encode + Decode + Default> AccountIdConversion<T> for Id {
 	}
 }
 
+/// A type that uniquely identifies an HRMP channel. An HRMP channel is established between two paras.
+/// In text, we use the notation `(A, B)` to specify a channel between A and B. The channels are
+/// unidirectional, meaning that `(A, B)` and `(B, A)` refer to different channels. The convention is
+/// that we use the first item tuple for the sender and the second for the recipient. Only one channel
+/// is allowed between two participants in one direction, i.e. there cannot be 2 different channels
+/// identified by `(A, B)`.
+#[derive(Clone, PartialEq, Eq, Encode, Decode, RuntimeDebug)]
+#[cfg_attr(feature = "std", derive(Hash))]
+pub struct HrmpChannelId {
+	/// The para that acts as the sender in this channel.
+	pub sender: Id,
+	/// The para that acts as the recipient in this channel.
+	pub recipient: Id,
+}
+
 /// A message from a parachain to its Relay Chain.
 pub type UpwardMessage = Vec<u8>;
 
@@ -212,7 +227,7 @@ pub struct ValidationParams {
 }
 
 /// The result of parachain validation.
-// TODO: egress and balance uploads (https://github.com/paritytech/polkadot/issues/220)
+// TODO: balance uploads (https://github.com/paritytech/polkadot/issues/220)
 #[derive(PartialEq, Eq, Encode)]
 #[cfg_attr(feature = "std", derive(Debug, Decode))]
 pub struct ValidationResult {
@@ -222,8 +237,12 @@ pub struct ValidationResult {
 	pub new_validation_code: Option<ValidationCode>,
 	/// Upward messages send by the Parachain.
 	pub upward_messages: Vec<UpwardMessage>,
+	/// Outbound horizontal messages sent by the parachain.
+	pub horizontal_messages: Vec<OutboundHrmpMessage<Id>>,
 	/// Number of downward messages that were processed by the Parachain.
 	///
 	/// It is expected that the Parachain processes them from first to last.
 	pub processed_downward_messages: u32,
+	/// The mark which specifies the block number up to which all inbound HRMP messages are processed.
+	pub hrmp_watermark: RelayChainBlockNumber,
 }

polkadot/parachain/test-parachains/adder/collator/src/lib.rs

@@ -114,10 +114,12 @@ impl Collator {
 
 			let collation = Collation {
 				upward_messages: Vec::new(),
+				horizontal_messages: Vec::new(),
 				new_validation_code: None,
 				head_data: head_data.encode().into(),
 				proof_of_validity: PoV { block_data: block_data.encode().into() },
 				processed_downward_messages: 0,
+				hrmp_watermark: validation_data.persisted.block_number,
 			};
 
 			async move { Some(collation) }.boxed()

polkadot/parachain/test-parachains/adder/src/wasm_validation.rs

@@ -17,12 +17,13 @@
 //! WASM validation for adder parachain.
 
 use crate::{HeadData, BlockData};
-use core::{intrinsics, panic};
+use core::panic;
+use sp_std::vec::Vec;
 use parachain::primitives::{ValidationResult, HeadData as GenericHeadData};
 use codec::{Encode, Decode};
 
 #[no_mangle]
-pub extern fn validate_block(params: *const u8, len: usize) -> u64 {
+pub extern "C" fn validate_block(params: *const u8, len: usize) -> u64 {
 	let params = unsafe { parachain::load_params(params, len) };
 	let parent_head = HeadData::decode(&mut &params.parent_head.0[..])
 		.expect("invalid parent head format.");
@@ -38,7 +39,9 @@ pub extern fn validate_block(params: *const u8, len: usize) -> u64 {
 			head_data: GenericHeadData(new_head.encode()),
 			new_validation_code: None,
 			upward_messages: sp_std::vec::Vec::new(),
+			horizontal_messages: sp_std::vec::Vec::new(),
 			processed_downward_messages: 0,
+			hrmp_watermark: params.relay_chain_height,
 		}
 	)
 }