Initial version of DummyOrdered pallet (#299)

* initial commit of DummyOrdered (aka message-lane) pallet

* API for relay

* cargo fmt --all

* some clippy + no_std

* more clippy + no_std

* inbound lane tests

* outbound lane tests

* cargo fmt --all

* prune old messages whenever outbound lane is updated

* do not care about MessageNonce overflow

* cargo fmt --all

* update crate docs

* MaxHeadersToPruneAtOnce -> MaxMessagesToPruneAtOnce

* MessageAction -> MessageResult

* cargo fmt --all

* fire MessageAccepted + MessagesDelivered

* confirm message processing

* cargo fmt --all

* clippy

* cargo fmt again

* Update modules/message-lane/src/lib.rs

Co-authored-by: Hernando Castano <HCastano@users.noreply.github.com>

* Update modules/message-lane/src/lib.rs

Co-authored-by: Hernando Castano <HCastano@users.noreply.github.com>

* use crate::*

* cargo fmt --all

* Storage -> S

* Update modules/message-lane/src/outbound_lane.rs

Co-authored-by: Hernando Castano <HCastano@users.noreply.github.com>

* add method doc

* Update modules/message-lane/src/inbound_lane.rs

Co-authored-by: Hernando Castano <HCastano@users.noreply.github.com>

* added detailed module docs

* Update modules/message-lane/src/lib.rs

Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com>

* updated OnMessageReceived docs

* prune only when new message is sent

* removed #![warn(missing_docs)]

* fixed merge with overlapped PR

Co-authored-by: Hernando Castano <HCastano@users.noreply.github.com>
Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com>

bridges/primitives/message-lane/src/lib.rs

@@ -0,0 +1,135 @@
+// Copyright 2019-2020 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Primitives for sending and receiving Substrate <-> Substrate messages.
+
+#![cfg_attr(not(feature = "std"), no_std)]
+// RuntimeApi generated functions
+#![allow(clippy::too_many_arguments)]
+// Generated by `DecodeLimit::decode_with_depth_limit`
+#![allow(clippy::unnecessary_mut_passed)]
+
+use codec::{Decode, Encode};
+use sp_api::decl_runtime_apis;
+
+/// Lane identifier.
+pub type LaneId = [u8; 4];
+
+/// Message nonce. Valid messages will never have 0 nonce.
+pub type MessageNonce = u64;
+
+/// Message key (unique message identifier) as it is stored in the storage.
+#[derive(Encode, Decode, Clone)]
+pub struct MessageKey {
+	/// ID of the message lane.
+	pub lane_id: LaneId,
+	/// Message nonce.
+	pub nonce: MessageNonce,
+}
+
+/// Message as it is stored in the storage.
+#[derive(Encode, Decode, Clone)]
+pub struct Message<Payload> {
+	/// Message key.
+	pub key: MessageKey,
+	/// Message payload.
+	pub payload: Payload,
+}
+
+/// Message processing result.
+pub enum MessageResult<Payload> {
+	/// Message has been processed and should not be queued.
+	Processed,
+	/// Message has NOT been processed and should be queued for processing later.
+	NotProcessed(Message<Payload>),
+}
+
+/// Called when inbound message is received.
+pub trait OnMessageReceived<Payload> {
+	/// Called when inbound message is received.
+	///
+	/// It is up to the implementers of this trait to determine whether the message
+	/// is invalid (i.e. improperly encoded, has too large weight, ...) or not. And,
+	/// if message is invalid, then it should be dropped immediately (by returning
+	/// `MessageResult::Processed`), or it'll block the lane forever.
+	fn on_message_received(&mut self, message: Message<Payload>) -> MessageResult<Payload>;
+}
+
+/// Inbound lane data.
+#[derive(Encode, Decode, Clone)]
+pub struct InboundLaneData {
+	/// Nonce of oldest message that we haven't processed yet. May point to not-yet-received message if
+	/// lane is currently empty.
+	pub oldest_unprocessed_nonce: MessageNonce,
+	/// Nonce of latest message that we have received from bridged chain.
+	pub latest_received_nonce: MessageNonce,
+}
+
+impl Default for InboundLaneData {
+	fn default() -> Self {
+		InboundLaneData {
+			// it is 1 because we're processing everything in [oldest_unprocessed_nonce; latest_received_nonce]
+			oldest_unprocessed_nonce: 1,
+			latest_received_nonce: 0,
+		}
+	}
+}
+
+/// Outbound lane data.
+#[derive(Encode, Decode, Clone)]
+pub struct OutboundLaneData {
+	/// Nonce of oldest message that we haven't yet pruned. May point to not-yet-generated message if
+	/// all sent messages are already pruned.
+	pub oldest_unpruned_nonce: MessageNonce,
+	/// Nonce of latest message, received by bridged chain.
+	pub latest_received_nonce: MessageNonce,
+	/// Nonce of latest message, processed by bridged chain.
+	pub latest_processed_nonce: MessageNonce,
+	/// Nonce of latest message, generated by us.
+	pub latest_generated_nonce: MessageNonce,
+}
+
+impl Default for OutboundLaneData {
+	fn default() -> Self {
+		OutboundLaneData {
+			// it is 1 because we're pruning everything in [oldest_unpruned_nonce; latest_received_nonce]
+			oldest_unpruned_nonce: 1,
+			latest_received_nonce: 0,
+			latest_processed_nonce: 0,
+			latest_generated_nonce: 0,
+		}
+	}
+}
+
+decl_runtime_apis! {
+	/// Outbound message lane API.
+	pub trait OutboundLaneApi<Payload: Decode> {
+		/// Returns nonce of the latest message, received by bridged chain.
+		fn latest_received_nonce(lane: LaneId) -> MessageNonce;
+		/// Returns nonce of the latest message, processed by bridged chain.
+		fn latest_processed_nonce(lane: LaneId) -> MessageNonce;
+		/// Returns nonce of the latest message, generated by given lane.
+		fn latest_generated_nonce(lane: LaneId) -> MessageNonce;
+	}
+
+	/// Inbound message lane API.
+	pub trait InboundLaneApi {
+		/// Returns nonce of the latest message, received by given lane.
+		fn latest_received_nonce(lane: LaneId) -> MessageNonce;
+		/// Returns nonce of the latest message, processed by given lane.
+		fn latest_processed_nonce(lane: LaneId) -> MessageNonce;
+	}
+}