Merge pull request #4 from yrong/ron/improve-comments

Improve comments

Author: vgeddes

Diff for: bridges/snowbridge/pallets/outbound-queue-v2/README.md

@@ -1,10 +1,15 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023 Snowfork <[email protected]>
-#![cfg_attr(not(feature = "std"), no_std)]
 
+//! Ethereum Outbound Queue V2 Runtime API
+//!
+//! * `prove_message`: Generate a merkle proof for a committed message
+//! * `dry_run`: dry run the xcm to get a message structure to execute on Ethereum
+
+#![cfg_attr(not(feature = "std"), no_std)]
 use frame_support::traits::tokens::Balance as BalanceT;
 use snowbridge_merkle_tree::MerkleProof;
-use snowbridge_outbound_queue_primitives::v2::{OutboundMessage, DryRunError};
+use snowbridge_outbound_queue_primitives::v2::{DryRunError, OutboundMessage};
 use xcm::prelude::Xcm;
 
 sp_api::decl_runtime_apis! {
@@ -15,6 +20,8 @@ sp_api::decl_runtime_apis! {
 		/// `sp_runtime::generic::DigestItem::Other`
 		fn prove_message(leaf_index: u64) -> Option<MerkleProof>;
 
+		/// Dry run the xcm to get the OutboundMessage
+		/// which can be used to estimate the execution cost on Ethereum
 		fn dry_run(xcm: Xcm<()>) -> Result<(OutboundMessage,Balance),DryRunError>;
 	}
 }

Diff for: bridges/snowbridge/pallets/outbound-queue-v2/runtime-api/README.md

@@ -5,29 +5,38 @@
 //! # Overview
 //!
 //! Messages come either from sibling parachains via XCM, or BridgeHub itself
-//! via the `snowbridge-pallet-system`:
+//! via the `snowbridge-pallet-system-v2`:
 //!
 //! 1. `snowbridge_outbound_queue_primitives::v2::EthereumBlobExporter::deliver`
-//! 2. `snowbridge_pallet_system::Pallet::send_v2`
+//! 2. `snowbridge_pallet_system_v2::Pallet::send`
 //!
 //! The message submission pipeline works like this:
 //! 1. The message is first validated via the implementation for
 //!    [`snowbridge_outbound_queue_primitives::v2::SendMessage::validate`]
 //! 2. The message is then enqueued for later processing via the implementation for
 //!    [`snowbridge_outbound_queue_primitives::v2::SendMessage::deliver`]
 //! 3. The underlying message queue is implemented by [`Config::MessageQueue`]
-//! 4. The message queue delivers messages back to this pallet via the implementation for
+//! 4. The message queue delivers messages to this pallet via the implementation for
 //!    [`frame_support::traits::ProcessMessage::process_message`]
-//! 5. The message is processed in `Pallet::do_process_message`: a. Assigned a nonce b. ABI-encoded,
-//!    hashed, and stored in the `MessageLeaves` vector
-//! 6. At the end of the block, a merkle root is constructed from all the leaves in `MessageLeaves`.
+//! 5. The message is processed in `Pallet::do_process_message`:
+//! 	a. Convert to `OutboundMessage`, and stored into the `Messages` vector storage
+//! 	b. ABI-encoded the OutboundMessage, with commited hash stored into the `MessageLeaves` storage
+//! 	c. Generate `PendingOrder` with assigned nonce and fee attach, stored into the `PendingOrders`
+//! 	   map storage, with nonce as the key
+//! 	d. Increment nonce and update the `Nonce` storage
+//! 6. At the end of the block, a merkle root is constructed from all the leaves in `MessageLeaves`,
+//!    then `MessageLeaves` is dropped so that it is never committed to storage or included in PoV.
 //! 7. This merkle root is inserted into the parachain header as a digest item
-//! 8. Offchain relayers are able to relay the message to Ethereum after: a. Generating a merkle
-//!    proof for the committed message using the `prove_message` runtime API b. Reading the actual
-//!    message content from the `Messages` vector in storage
-//!
-//! On the Ethereum side, the message root is ultimately the thing being
-//! verified by the Polkadot light client.
+//! 8. Offchain relayers are able to relay the message to Ethereum after:
+//! 	a. Generating a merkle proof for the committed message using the `prove_message` runtime API
+//! 	b. Reading the actual message content from the `Messages` vector in storage
+//! 9. On the Ethereum side, the message root is ultimately the thing being verified by the Beefy
+//!    light client. When the message has been verified and executed, the relayer will call the
+//!    extrinsic `submit_delivery_proof` work the way as follows:
+//! 	a. Verify the message with proof for a transaction receipt containing the event log,
+//! 	   same as the inbound queue verification flow
+//! 	b. Fetch the pending order by nonce of the message, pay reward with fee attached in the order
+//!		c. Remove the order from `PendingOrders` map storage by nonce
 //!
 //! # Message Priorities
 //!
@@ -38,6 +47,7 @@
 //! # Extrinsics
 //!
 //! * [`Call::set_operating_mode`]: Set the operating mode
+//! * [`Call::submit_delivery_proof`]: Submit delivery proof
 //!
 //! # Runtime API
 //!
@@ -334,7 +344,7 @@ pub mod pallet {
 			let nonce = Nonce::<T>::get();
 
 			// Decode bytes into Message and
-			// a. Convert to InboundMessage and save into Messages
+			// a. Convert to OutboundMessage and save into Messages
 			// b. Convert to committed hash and save into MessageLeaves
 			// c. Save nonce&fee into PendingOrders
 			let message: Message = Message::decode(&mut message).map_err(|_| Corrupt)?;
@@ -367,12 +377,12 @@ pub mod pallet {
 				<T as Config>::Hashing::hash(&committed_message.abi_encode());
 			MessageLeaves::<T>::append(message_abi_encoded_hash);
 
-			let inbound_message = OutboundMessage {
+			let outbound_message = OutboundMessage {
 				origin: message.origin,
 				nonce,
 				commands: commands.try_into().map_err(|_| Corrupt)?,
 			};
-			Messages::<T>::append(Box::new(inbound_message));
+			Messages::<T>::append(Box::new(outbound_message));
 
 			let order = PendingOrder {
 				nonce,

Diff for: bridges/snowbridge/pallets/outbound-queue-v2/runtime-api/src/lib.rs

@@ -1,11 +1,12 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023 Snowfork <[email protected]>
-//! Frontend for calling Snowbridge System Pallet on BridgeHub
+//! Frontend which will be deployed on AssetHub for calling the V2 system pallet
+//! on BridgeHub.
 //!
 //! # Extrinsics
 //!
-//! * [`Call::create_agent`]: Create agent for any sovereign location from non-system parachain
-//! * [`Call::register_token`]: Register a foreign token location from non-system parachain
+//! * [`Call::create_agent`]: Create agent for any kind of sovereign location on Polkadot network.
+//! * [`Call::register_token`]: Register Polkadot native asset as a wrapped ERC20 token on Ethereum.
 #![cfg_attr(not(feature = "std"), no_std)]
 #[cfg(test)]
 mod mock;
@@ -113,10 +114,9 @@ pub mod pallet {
 
 	#[pallet::call]
 	impl<T: Config> Pallet<T> {
-		/// Call `create_agent` on Bridge Hub to instantiate a new agent contract representing
-		/// `origin`.
-		/// - `origin`: Must be `Location` from a sibling parachain
-		/// - `fee`: Fee in Ether
+		/// Call `create_agent` to instantiate a new agent contract representing `origin`.
+		/// - `origin`: Can be any sovereign `Location`
+		/// - `fee`: Fee in Ether paying for the execution cost on Ethreum
 		#[pallet::call_index(1)]
 		#[pallet::weight(T::WeightInfo::create_agent())]
 		pub fn create_agent(origin: OriginFor<T>, fee: u128) -> DispatchResult {
@@ -150,6 +150,7 @@ pub mod pallet {
 		/// - `origin`: Must be `Location` from a sibling parachain
 		/// - `asset_id`: Location of the asset (should starts from the dispatch origin)
 		/// - `metadata`: Metadata to include in the instantiated ERC20 contract on Ethereum
+		/// - `fee`: Fee in Ether paying for the execution cost on Ethreum
 		#[pallet::call_index(2)]
 		#[pallet::weight(T::WeightInfo::register_token())]
 		pub fn register_token(

Diff for: bridges/snowbridge/pallets/outbound-queue-v2/src/lib.rs

@@ -9,7 +9,9 @@
 //! Agents are smart contracts on Ethereum that act as proxies for consensus systems on Polkadot
 //! networks.
 //!
-//! * [`Call::create_agent`]: Create agent for a sibling parachain
+//! * [`Call::create_agent`]: Create agent for any kind of sovereign location on Polkadot network,
+//!   can be a sibling parachain, pallet or smart contract or signed account in that parachain, etc
+
 //! ## Polkadot-native tokens on Ethereum
 //!
 //! Tokens deposited on AssetHub pallet can be bridged to Ethereum as wrapped ERC20 tokens. As a

Diff for: bridges/snowbridge/pallets/system-frontend/README.md

@@ -1,23 +1,21 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023 Snowfork <[email protected]>
 use crate::Log;
-
-use sp_core::{RuntimeDebug, H160};
-use sp_std::prelude::*;
-
 use alloy_core::{primitives::B256, sol, sol_types::SolEvent};
 use codec::Decode;
 use frame_support::pallet_prelude::{Encode, TypeInfo};
+use sp_core::{RuntimeDebug, H160};
+use sp_std::prelude::*;
 
 sol! {
 	event InboundMessageDispatched(uint64 indexed nonce, bool success, bytes32 reward_address);
 }
 
-/// An inbound message that has had its outer envelope decoded.
+/// Envelope of the delivery proof
 #[derive(Clone, RuntimeDebug)]
 pub struct MessageReceipt<AccountId>
 where
-	AccountId: From<[u8; 32]> + Clone
+	AccountId: From<[u8; 32]> + Clone,
 {
 	/// The address of the outbound queue on Ethereum that emitted this message as an event log
 	pub gateway: H160,
@@ -37,7 +35,7 @@ pub enum MessageReceiptDecodeError {
 
 impl<AccountId> TryFrom<&Log> for MessageReceipt<AccountId>
 where
-	AccountId: From<[u8; 32]> + Clone
+	AccountId: From<[u8; 32]> + Clone,
 {
 	type Error = MessageReceiptDecodeError;