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

bp_messages/
source_chain.rs
