Update docs and enable DOT-over-XCM (#4809)

* Update docs and enable DOT-over-XCM

* Formatting

* Fixes

* Fixes

* Formatting

* Spelling

* add UmpSink config (#5032)

* Update runtime/polkadot/src/xcm_config.rs

Co-authored-by: joe petrowski <25483142+joepetrowski@users.noreply.github.com>
Co-authored-by: Robert Habermeier <rphmeier@gmail.com>

polkadot/runtime/kusama/src/xcm_config.rs

@@ -20,11 +20,7 @@ use super::{
 	parachains_origin, AccountId, Balances, Call, CouncilCollective, Event, Origin, ParaId,
 	Runtime, WeightToFee, XcmPallet,
 };
-use frame_support::{
-	match_types, parameter_types,
-	traits::{Everything, Nothing},
-	weights::Weight,
-};
+use frame_support::{match_types, parameter_types, traits::Everything, weights::Weight};
 use runtime_common::{xcm_sender, ToAuthor};
 use xcm::latest::prelude::*;
 use xcm_builder::{
@@ -169,14 +165,20 @@ pub type LocalOriginToLocation = (
 );
 impl pallet_xcm::Config for Runtime {
 	type Event = Event;
-	type SendXcmOrigin = xcm_builder::EnsureXcmOrigin<Origin, LocalOriginToLocation>;
+	// We don't allow any messages to be sent via the transaction yet. This is basically safe to
+	// enable, (safe the possibility of someone spamming the parachain if they're willing to pay
+	// the DOT to send from the Relay-chain). But it's useless until we bring in XCM v3 which will
+	// make `DescendOrigin` a bit more useful.
+	type SendXcmOrigin = xcm_builder::EnsureXcmOrigin<Origin, ()>;
 	type XcmRouter = XcmRouter;
-	// Anyone can execute XCM messages locally...
+	// Anyone can execute XCM messages locally.
 	type ExecuteXcmOrigin = xcm_builder::EnsureXcmOrigin<Origin, LocalOriginToLocation>;
-	// ...but they must match our filter, which rejects all.
-	type XcmExecuteFilter = Nothing;
+	type XcmExecuteFilter = Everything;
 	type XcmExecutor = xcm_executor::XcmExecutor<XcmConfig>;
+	// Anyone is able to use teleportation regardless of who they are and what they want to teleport.
 	type XcmTeleportFilter = Everything;
+	// Anyone is able to use reserve transfers regardless of who they are and what they want to
+	// transfer.
 	type XcmReserveTransferFilter = Everything;
 	type Weigher = FixedWeightBounds<BaseXcmWeight, Call, MaxInstructions>;
 	type LocationInverter = LocationInverter<Ancestry>;

polkadot/runtime/polkadot/src/lib.rs

@@ -1227,7 +1227,8 @@ parameter_types! {
 
 impl parachains_ump::Config for Runtime {
 	type Event = Event;
-	type UmpSink = ();
+	type UmpSink =
+		crate::parachains_ump::XcmSink<xcm_executor::XcmExecutor<xcm_config::XcmConfig>, Runtime>;
 	type FirstMessageFactorPercent = FirstMessageFactorPercent;
 	type ExecuteOverweightOrigin = EnsureRoot<AccountId>;
 	type WeightInfo = parachains_ump::TestWeightInfo;

polkadot/runtime/polkadot/src/xcm_config.rs

@@ -58,7 +58,7 @@ pub type SovereignAccountOf = (
 	AccountId32Aliases<PolkadotNetwork, AccountId>,
 );
 
-/// Our asset transactor. This is what allows us to interest with the runtime facilities from the point of
+/// Our asset transactor. This is what allows us to interact with the runtime assets from the point of
 /// view of XCM-only concepts like `MultiLocation` and `MultiAsset`.
 ///
 /// Ours is only aware of the Balances pallet, which is mapped to `DotLocation`.
@@ -75,13 +75,18 @@ pub type LocalAssetTransactor = XcmCurrencyAdapter<
 	CheckAccount,
 >;
 
-/// The means that we convert an the XCM message origin location into a local dispatch origin.
+/// The means that we convert an XCM origin `MultiLocation` into the runtime's `Origin` type for
+/// local dispatch. This is a conversion function from an `OriginKind` type along with the
+/// `MultiLocation` value and returns an `Origin` value or an error.
 type LocalOriginConverter = (
-	// A `Signed` origin of the sovereign account that the original location controls.
+	// If the origin kind is `Sovereign`, then return a `Signed` origin with the account determined
+	// by the `SovereignAccountOf` converter.
 	SovereignSignedViaLocation<SovereignAccountOf, Origin>,
-	// A child parachain, natively expressed, has the `Parachain` origin.
+	// If the origin kind is `Native` and the XCM origin is a child parachain, then we can express
+	// it with the special `parachains_origin::Origin` origin variant.
 	ChildParachainAsNative<parachains_origin::Origin, Origin>,
-	// The AccountId32 location type can be expressed natively as a `Signed` origin.
+	// If the origin kind is `Native` and the XCM origin is the `AccountId32` location, then it can
+	// be expressed using the `Signed` origin variant.
 	SignedAccountId32AsNative<PolkadotNetwork, Origin>,
 );
 
@@ -105,6 +110,7 @@ parameter_types! {
 	pub const PolkadotForStatemint: (MultiAssetFilter, MultiLocation) = (Polkadot::get(), Parachain(1000).into());
 }
 
+/// Polkadot Relay recognizes/respects the Statemint chain as a teleporter.
 pub type TrustedTeleporters = (xcm_builder::Case<PolkadotForStatemint>,);
 
 match_types! {
@@ -131,6 +137,7 @@ impl xcm_executor::Config for XcmConfig {
 	type XcmSender = XcmRouter;
 	type AssetTransactor = LocalAssetTransactor;
 	type OriginConverter = LocalOriginConverter;
+	// Polkadot Relay recognises no chains which act as reserves.
 	type IsReserve = ();
 	type IsTeleporter = TrustedTeleporters;
 	type LocationInverter = LocationInverter<Ancestry>;
@@ -166,15 +173,16 @@ pub type LocalOriginToLocation = (
 
 impl pallet_xcm::Config for Runtime {
 	type Event = Event;
-	type SendXcmOrigin = xcm_builder::EnsureXcmOrigin<Origin, LocalOriginToLocation>;
+	// Not much use in sending XCM at this point.
+	type SendXcmOrigin = xcm_builder::EnsureXcmOrigin<Origin, ()>; // == Deny All
 	type XcmRouter = XcmRouter;
 	// Anyone can execute XCM messages locally...
 	type ExecuteXcmOrigin = xcm_builder::EnsureXcmOrigin<Origin, LocalOriginToLocation>;
 	// ...but they must match our filter, which rejects all.
-	type XcmExecuteFilter = Nothing;
+	type XcmExecuteFilter = Nothing; // == Deny All
 	type XcmExecutor = xcm_executor::XcmExecutor<XcmConfig>;
-	type XcmTeleportFilter = Nothing;
-	type XcmReserveTransferFilter = Nothing;
+	type XcmTeleportFilter = Everything; // == Allow All
+	type XcmReserveTransferFilter = Everything; // == Allow All
 	type Weigher = FixedWeightBounds<BaseXcmWeight, Call, MaxInstructions>;
 	type LocationInverter = LocationInverter<Ancestry>;
 	type Origin = Origin;

polkadot/xcm/pallet-xcm/src/lib.rs

@@ -474,9 +474,9 @@ pub mod pallet {
 
 		/// Teleport some assets from the local chain to some destination chain.
 		///
-		/// Fee payment on the destination side is made from the first asset listed in the `assets` vector and
-		/// fee-weight is calculated locally and thus remote weights are assumed to be equal to
-		/// local weights.
+		/// Fee payment on the destination side is made from the asset in the `assets` vector of
+		/// index `fee_asset_item`. The weight limit for fees is not provided and thus is unlimited,
+		/// with all fees taken as needed from the asset.
 		///
 		/// - `origin`: Must be capable of withdrawing the `assets` and executing XCM.
 		/// - `dest`: Destination context for the assets. Will typically be `X2(Parent, Parachain(..))` to send
@@ -512,12 +512,12 @@ pub mod pallet {
 			Self::do_teleport_assets(origin, dest, beneficiary, assets, fee_asset_item, None)
 		}
 
-		/// Transfer some assets from the local chain to the sovereign account of a destination chain and forward
-		/// a notification XCM.
+		/// Transfer some assets from the local chain to the sovereign account of a destination
+		/// chain and forward a notification XCM.
 		///
-		/// Fee payment on the destination side is made from the first asset listed in the `assets` vector and
-		/// fee-weight is calculated locally and thus remote weights are assumed to be equal to
-		/// local weights.
+		/// Fee payment on the destination side is made from the asset in the `assets` vector of
+		/// index `fee_asset_item`. The weight limit for fees is not provided and thus is unlimited,
+		/// with all fees taken as needed from the asset.
 		///
 		/// - `origin`: Must be capable of withdrawing the `assets` and executing XCM.
 		/// - `dest`: Destination context for the assets. Will typically be `X2(Parent, Parachain(..))` to send
@@ -672,10 +672,13 @@ pub mod pallet {
 			})
 		}
 
-		/// Transfer some assets from the local chain to the sovereign account of a destination chain and forward
-		/// a notification XCM.
+		/// Transfer some assets from the local chain to the sovereign account of a destination
+		/// chain and forward a notification XCM.
 		///
-		/// Fee payment on the destination side is made from the first asset listed in the `assets` vector.
+		/// Fee payment on the destination side is made from the asset in the `assets` vector of
+		/// index `fee_asset_item`, up to enough to pay for `weight_limit` of weight. If more weight
+		/// is needed than `weight_limit`, then the operation will fail and the assets send may be
+		/// at risk.
 		///
 		/// - `origin`: Must be capable of withdrawing the `assets` and executing XCM.
 		/// - `dest`: Destination context for the assets. Will typically be `X2(Parent, Parachain(..))` to send
@@ -719,7 +722,10 @@ pub mod pallet {
 
 		/// Teleport some assets from the local chain to some destination chain.
 		///
-		/// Fee payment on the destination side is made from the first asset listed in the `assets` vector.
+		/// Fee payment on the destination side is made from the asset in the `assets` vector of
+		/// index `fee_asset_item`, up to enough to pay for `weight_limit` of weight. If more weight
+		/// is needed than `weight_limit`, then the operation will fail and the assets send may be
+		/// at risk.
 		///
 		/// - `origin`: Must be capable of withdrawing the `assets` and executing XCM.
 		/// - `dest`: Destination context for the assets. Will typically be `X2(Parent, Parachain(..))` to send