Fees, weights, message delivery and dispatch (#339)

* introduce BridgedHeaderChain trait * LaneMessageVerifier + tests * fixed tests * do not expose intenal functions * cargo fmt --all + fix no_std compilation * ByWeightDispatcher * process queued messages from message-lane::on_initialize * scheduled_messages_are_processed_from_on_initialize * flush * deal with fees + weights * drop heavy messages on dispatch * cargo fmt * clippy * fix comment * Update primitives/message-lane/src/source_chain.rs Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com> * removed messages_processed * Update primitives/message-lane/src/source_chain.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> * remove queueing from message-lane * also remove queueing from RPCs * remove by-weight traces * dispatch fee * receiving -> delivery * receival -> delivery * remove extra line * Update primitives/message-lane/src/source_chain.rs Co-authored-by: Hernando Castano <HCastano@users.noreply.github.com> * cargo fmt --all * clippy * let dispatch_weight to be larger than actual_dispatch_weight * post-merge fix Co-authored-by: Tomasz Drwięga <tomusdrw@users.noreply.github.com> Co-authored-by: Hernando Castano <HCastano@users.noreply.github.com>
2026-05-31 16:51:02 +00:00 · 2020-09-25 22:22:44 +03:00
parent 44beb30836
commit 3cd8937b38
13 changed files with 799 additions and 141 deletions
@@ -14,7 +14,7 @@
 // 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.
+//! Primitives of message lane module.

 #![cfg_attr(not(feature = "std"), no_std)]
 // RuntimeApi generated functions
@@ -23,7 +23,12 @@
 #![allow(clippy::unnecessary_mut_passed)]

 use codec::{Decode, Encode};
+use frame_support::RuntimeDebug;
 use sp_api::decl_runtime_apis;
+use sp_std::prelude::*;
+
+pub mod source_chain;
+pub mod target_chain;

 /// Lane identifier.
 pub type LaneId = [u8; 4];
@@ -31,8 +36,11 @@ pub type LaneId = [u8; 4];
 /// Message nonce. Valid messages will never have 0 nonce.
 pub type MessageNonce = u64;

+/// Message id as a tuple.
+pub type MessageId = (LaneId, MessageNonce);
+
 /// Message key (unique message identifier) as it is stored in the storage.
-#[derive(Encode, Decode, Clone)]
+#[derive(Encode, Decode, Clone, PartialEq, Eq, RuntimeDebug)]
 pub struct MessageKey {
 	/// ID of the message lane.
 	pub lane_id: LaneId,
@@ -40,37 +48,33 @@ pub struct MessageKey {
 	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 data as it is stored in the storage.
+#[derive(Encode, Decode, Clone, PartialEq, Eq, RuntimeDebug)]
+pub struct MessageData<Payload, Fee> {
 	/// Message payload.
 	pub payload: Payload,
+	/// Message delivery and dispatch fee, paid by the submitter.
+	pub fee: Fee,
 }

-/// 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.
-	fn on_message_received(message: Message<Payload>);
-}
-
-impl<Payload> OnMessageReceived<Payload> for () {
-	fn on_message_received(_message: Message<Payload>) {}
+/// Message as it is stored in the storage.
+#[derive(Encode, Decode, Clone, PartialEq, Eq, RuntimeDebug)]
+pub struct Message<Payload, Fee> {
+	/// Message key.
+	pub key: MessageKey,
+	/// Message data.
+	pub data: MessageData<Payload, Fee>,
 }

 /// Inbound lane data.
-#[derive(Default, Encode, Decode, Clone)]
+#[derive(Default, Encode, Decode, Clone, RuntimeDebug, PartialEq)]
 pub struct InboundLaneData {
 	/// Nonce of latest message that we have received from bridged chain.
 	pub latest_received_nonce: MessageNonce,
 }

 /// Outbound lane data.
-#[derive(Encode, Decode, Clone)]
+#[derive(Encode, Decode, Clone, RuntimeDebug, PartialEq)]
 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.
@@ -0,0 +1,97 @@
+// 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 of message lane module, that are used on the source chain.
+
+use crate::{LaneId, MessageNonce};
+
+use frame_support::Parameter;
+use sp_std::fmt::Debug;
+
+/// Target chain API. Used by source chain to verify target chain proofs.
+///
+/// All implementations of this trait should only work with finalized data that
+/// can't change. Wrong implementation may lead to invalid lane states (i.e. lane
+/// that's stuck) and/or processing messages without paying fees.
+pub trait TargetHeaderChain<Payload> {
+	/// Error type.
+	type Error: Debug + Into<&'static str>;
+
+	/// Proof that messages have been received by target chain.
+	type MessagesDeliveryProof: Parameter;
+
+	/// Verify message payload before we accept it.
+	///
+	/// **CAUTION**: this is very important function. Incorrect implementation may lead
+	/// to stuck lanes and/or relayers loses.
+	///
+	/// The proper implementation must ensure that the delivery-transaction with this
+	/// payload would (at least) be accepted into target chain transaction pool AND
+	/// eventually will be successfully 'mined'. The most obvious incorrect implementation
+	/// example would be implementation for BTC chain that accepts payloads larger than
+	/// 1MB. BTC nodes aren't accepting transactions that are larger than 1MB, so relayer
+	/// will be unable to craft valid transaction => this (and all subsequent) messages will
+	/// never be delivered.
+	fn verify_message(payload: &Payload) -> Result<(), Self::Error>;
+
+	/// Verify messages delivery proof and return lane && nonce of the latest recevied message.
+	fn verify_messages_delivery_proof(
+		proof: Self::MessagesDeliveryProof,
+	) -> Result<(LaneId, MessageNonce), Self::Error>;
+}
+
+/// Lane message verifier.
+///
+/// Runtime developer may implement any additional validation logic over message-lane mechanism.
+/// E.g. if lanes should have some security (e.g. you can only accept Lane1 messages from
+/// Submitter1, Lane2 messages for those who has submitted first message to this lane, disable
+/// Lane3 until some block, ...), then it may be built using this verifier.
+///
+/// Any fee requirements should also be enforced here.
+pub trait LaneMessageVerifier<Submitter, Payload, Fee> {
+	/// Error type.
+	type Error: Debug + Into<&'static str>;
+
+	/// Verify message payload and return Ok(()) if message is valid and allowed to be sent over the lane.
+	fn verify_message(
+		submitter: &Submitter,
+		delivery_and_dispatch_fee: &Fee,
+		lane: &LaneId,
+		payload: &Payload,
+	) -> Result<(), Self::Error>;
+}
+
+/// Message delivery payment. It is called as a part of submit-message transaction. Transaction
+/// submitter is paying (in source chain tokens/assets) for:
+///
+/// 1) submit-message-transaction-fee itself. This fee is not included in the
+/// `delivery_and_dispatch_fee` and is witheld by the regular transaction payment mechanism;
+/// 2) message-delivery-transaction-fee. It is submitted to the target node by relayer;
+/// 3) message-dispatch fee. It is paid by relayer for processing message by target chain;
+/// 4) message-receiving-delivery-transaction-fee. It is submitted to the source node
+/// by relayer.
+///
+/// So to be sure that any non-altruist relayer would agree to deliver message, submitter
+/// should set `delivery_and_dispatch_fee` to at least (equialent of): sum of fees from (2)
+/// to (4) above, plus some interest for the relayer.
+pub trait MessageDeliveryAndDispatchPayment<AccountId, Balance> {
+	/// Error type.
+	type Error: Debug + Into<&'static str>;
+
+	/// Withhold/write-off delivery_and_dispatch_fee from submitter account to
+	/// some relayers-fund account.
+	fn pay_delivery_and_dispatch_fee(submitter: &AccountId, fee: &Balance) -> Result<(), Self::Error>;
+}
@@ -0,0 +1,56 @@
+// 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 of message lane module, that are used on the target chain.
+
+use crate::Message;
+
+use frame_support::{weights::Weight, Parameter};
+use sp_std::{fmt::Debug, prelude::*};
+
+/// Source chain API. Used by target chain, to verify source chain proofs.
+///
+/// All implementations of this trait should only work with finalized data that
+/// can't change. Wrong implementation may lead to invalid lane states (i.e. lane
+/// that's stuck) and/or processing messages without paying fees.
+pub trait SourceHeaderChain<Payload, Fee> {
+	/// Error type.
+	type Error: Debug + Into<&'static str>;
+
+	/// Proof that messages are sent from source chain.
+	type MessagesProof: Parameter;
+
+	/// Verify messages proof and return proved messages.
+	///
+	/// Messages vector is required to be sorted by nonce within each lane. Out-of-order
+	/// messages will be rejected.
+	fn verify_messages_proof(proof: Self::MessagesProof) -> Result<Vec<Message<Payload, Fee>>, Self::Error>;
+}
+
+/// Called when inbound message is received.
+pub trait MessageDispatch<Payload, Fee> {
+	/// Estimate dispatch weight.
+	///
+	/// This function must: (1) be instant and (2) return correct upper bound
+	/// of dispatch weight.
+	fn dispatch_weight(message: &Message<Payload, Fee>) -> Weight;
+
+	/// 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.
+	fn dispatch(message: Message<Payload, Fee>);
+}