bp_messages/
source_chain.rs

1// Copyright (C) Parity Technologies (UK) Ltd.
2// This file is part of Parity Bridges Common.
3
4// Parity Bridges Common 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// Parity Bridges Common 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 Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
16
17//! Primitives of messages module, that are used on the source chain.
18
19use crate::{MessageNonce, UnrewardedRelayer};
20
21use bp_runtime::{raw_storage_proof_size, RawStorageProof, Size};
22use codec::{Decode, DecodeWithMemTracking, Encode};
23use scale_info::TypeInfo;
24use sp_std::{
25	collections::{btree_map::BTreeMap, vec_deque::VecDeque},
26	fmt::Debug,
27	ops::RangeInclusive,
28};
29
30/// Messages delivery proof from the bridged chain.
31///
32/// It contains everything required to prove that our (this chain) messages have been
33/// delivered to the bridged (target) chain:
34///
35/// - hash of finalized header;
36///
37/// - storage proof of the inbound lane state;
38///
39/// - lane id.
40#[derive(Clone, Decode, DecodeWithMemTracking, Encode, Eq, PartialEq, Debug, TypeInfo)]
41pub struct FromBridgedChainMessagesDeliveryProof<BridgedHeaderHash, LaneId> {
42	/// Hash of the bridge header the proof is for.
43	pub bridged_header_hash: BridgedHeaderHash,
44	/// Storage trie proof generated for [`Self::bridged_header_hash`].
45	pub storage_proof: RawStorageProof,
46	/// Lane id of which messages were delivered and the proof is for.
47	pub lane: LaneId,
48}
49
50impl<BridgedHeaderHash, LaneId> Size
51	for FromBridgedChainMessagesDeliveryProof<BridgedHeaderHash, LaneId>
52{
53	fn size(&self) -> u32 {
54		use frame_support::sp_runtime::SaturatedConversion;
55		raw_storage_proof_size(&self.storage_proof).saturated_into()
56	}
57}
58
59/// Number of messages, delivered by relayers.
60pub type RelayersRewards<AccountId> = BTreeMap<AccountId, MessageNonce>;
61
62/// Manages payments that are happening at the source chain during delivery confirmation
63/// transaction.
64pub trait DeliveryConfirmationPayments<AccountId, LaneId> {
65	/// Error type.
66	type Error: Debug + Into<&'static str>;
67
68	/// Pay rewards for delivering messages to the given relayers.
69	///
70	/// The implementation may also choose to pay reward to the `confirmation_relayer`, which is
71	/// a relayer that has submitted delivery confirmation transaction.
72	///
73	/// Returns number of actually rewarded relayers.
74	fn pay_reward(
75		lane_id: LaneId,
76		messages_relayers: VecDeque<UnrewardedRelayer<AccountId>>,
77		confirmation_relayer: &AccountId,
78		received_range: &RangeInclusive<MessageNonce>,
79	) -> MessageNonce;
80}
81
82impl<AccountId, LaneId> DeliveryConfirmationPayments<AccountId, LaneId> for () {
83	type Error = &'static str;
84
85	fn pay_reward(
86		_lane_id: LaneId,
87		_messages_relayers: VecDeque<UnrewardedRelayer<AccountId>>,
88		_confirmation_relayer: &AccountId,
89		_received_range: &RangeInclusive<MessageNonce>,
90	) -> MessageNonce {
91		// this implementation is not rewarding relayers at all
92		0
93	}
94}
95
96/// Callback that is called at the source chain (bridge hub) when we get delivery confirmation
97/// for new messages.
98pub trait OnMessagesDelivered<LaneId> {
99	/// New messages delivery has been confirmed.
100	///
101	/// The only argument of the function is the number of yet undelivered messages
102	fn on_messages_delivered(lane: LaneId, enqueued_messages: MessageNonce);
103}
104
105impl<LaneId> OnMessagesDelivered<LaneId> for () {
106	fn on_messages_delivered(_lane: LaneId, _enqueued_messages: MessageNonce) {}
107}
108
109/// Send message artifacts.
110#[derive(Eq, Debug, PartialEq)]
111pub struct SendMessageArtifacts {
112	/// Nonce of the message.
113	pub nonce: MessageNonce,
114	/// Number of enqueued messages at the lane, after the message is sent.
115	pub enqueued_messages: MessageNonce,
116}
117
118/// Messages bridge API to be used from other pallets.
119pub trait MessagesBridge<Payload, LaneId> {
120	/// Error type.
121	type Error: Debug;
122
123	/// Intermediary structure returned by `validate_message()`.
124	///
125	/// It can than be passed to `send_message()` in order to actually send the message
126	/// on the bridge.
127	type SendMessageArgs;
128
129	/// Check if the message can be sent over the bridge.
130	fn validate_message(
131		lane: LaneId,
132		message: &Payload,
133	) -> Result<Self::SendMessageArgs, Self::Error>;
134
135	/// Send message over the bridge.
136	///
137	/// Returns unique message nonce or error if send has failed.
138	fn send_message(message: Self::SendMessageArgs) -> SendMessageArtifacts;
139}
140
141/// Structure that may be used in place `MessageDeliveryAndDispatchPayment` on chains,
142/// where outbound messages are forbidden.
143pub struct ForbidOutboundMessages;
144
145impl<AccountId, LaneId> DeliveryConfirmationPayments<AccountId, LaneId> for ForbidOutboundMessages {
146	type Error = &'static str;
147
148	fn pay_reward(
149		_lane_id: LaneId,
150		_messages_relayers: VecDeque<UnrewardedRelayer<AccountId>>,
151		_confirmation_relayer: &AccountId,
152		_received_range: &RangeInclusive<MessageNonce>,
153	) -> MessageNonce {
154		0
155	}
156}
bp_messages/source_chain.rs

bp_messages/
source_chain.rs
