Add HRMP notification handlers to the xcm-executor (#3696)

Currently the xcm-executor returns an `Unimplemented` error if it
receives any HRMP-related instruction.
What I propose here, which is what we are currently doing in our forked
executor at polimec, is to introduce a trait implemented by the executor
which will handle those instructions.

This way, if parachains want to keep the default behavior, they just use
`()` and it will return unimplemented, but they can also implement their
own logic to establish HRMP channels with other chains in an automated
fashion, without requiring to go through governance.

Our implementation is mentioned in the [polkadot HRMP
docs](https://arc.net/l/quote/hduiivbu), and it was suggested to us to
submit a PR to add these changes to polkadot-sdk.

---------

Co-authored-by: Branislav Kontur <bkontur@gmail.com>
Co-authored-by: command-bot <>

cumulus/pallets/xcmp-queue/src/mock.rs

@@ -175,6 +175,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 pub type XcmRouter = (

cumulus/parachains/runtimes/assets/asset-hub-rococo/src/xcm_config.rs

@@ -628,6 +628,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = SafeCallFilter;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 /// Converts a local signed origin into an XCM location.

cumulus/parachains/runtimes/assets/asset-hub-westend/src/xcm_config.rs

@@ -649,6 +649,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = SafeCallFilter;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 /// Local origins on this chain are allowed to dispatch XCM sends/executions.

cumulus/parachains/runtimes/bridge-hubs/bridge-hub-rococo/src/xcm_config.rs

@@ -336,6 +336,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = SafeCallFilter;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 pub type PriceForParentDelivery =

cumulus/parachains/runtimes/bridge-hubs/bridge-hub-westend/src/xcm_config.rs

@@ -264,6 +264,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = SafeCallFilter;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 pub type PriceForParentDelivery =

cumulus/parachains/runtimes/collectives/collectives-westend/src/xcm_config.rs

@@ -288,6 +288,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = SafeCallFilter;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 /// Converts a local signed origin into an XCM location.

cumulus/parachains/runtimes/contracts/contracts-rococo/src/xcm_config.rs

@@ -197,6 +197,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 /// Converts a local signed origin into an XCM location.

cumulus/parachains/runtimes/coretime/coretime-rococo/src/xcm_config.rs

@@ -257,6 +257,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = SafeCallFilter;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 /// Converts a local signed origin into an XCM location. Forms the basis for local origins

cumulus/parachains/runtimes/coretime/coretime-westend/src/xcm_config.rs

@@ -269,6 +269,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = SafeCallFilter;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 /// Converts a local signed origin into an XCM location. Forms the basis for local origins

cumulus/parachains/runtimes/glutton/glutton-westend/src/xcm_config.rs

@@ -88,6 +88,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 impl cumulus_pallet_xcm::Config for Runtime {

cumulus/parachains/runtimes/people/people-rococo/src/xcm_config.rs

@@ -269,6 +269,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = SafeCallFilter;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 /// Converts a local signed origin into an XCM location. Forms the basis for local origins

cumulus/parachains/runtimes/people/people-westend/src/xcm_config.rs

@@ -277,6 +277,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = SafeCallFilter;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 /// Converts a local signed origin into an XCM location. Forms the basis for local origins

cumulus/parachains/runtimes/starters/shell/src/xcm_config.rs

@@ -88,6 +88,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = ();
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 impl cumulus_pallet_xcm::Config for Runtime {

cumulus/parachains/runtimes/testing/penpal/src/xcm_config.rs

@@ -338,6 +338,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 /// Multiplier used for dedicated `TakeFirstAssetTrader` with `ForeignAssets` instance.

cumulus/parachains/runtimes/testing/rococo-parachain/src/lib.rs

@@ -484,6 +484,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 /// Local origins on this chain are allowed to dispatch XCM sends/executions.

polkadot/runtime/rococo/src/xcm_config.rs

@@ -221,6 +221,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 parameter_types! {

polkadot/runtime/test-runtime/src/xcm_config.rs

@@ -153,6 +153,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 impl pallet_xcm::Config for crate::Runtime {

polkadot/runtime/westend/src/xcm_config.rs

@@ -219,6 +219,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 parameter_types! {

polkadot/xcm/pallet-xcm-benchmarks/src/fungible/mock.rs

@@ -145,6 +145,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 impl crate::Config for Test {

polkadot/xcm/pallet-xcm-benchmarks/src/generic/mock.rs

@@ -135,6 +135,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Aliasers;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 parameter_types! {

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

@@ -513,6 +513,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 pub type LocalOriginToLocation = SignedToAccountId32<RuntimeOrigin, AccountId, AnyNetwork>;

polkadot/xcm/xcm-builder/src/tests/mock.rs

@@ -743,6 +743,9 @@ impl Config for TestConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = AliasForeignAccountId32<SiblingPrefix>;
 	type TransactionalProcessor = ();
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 pub fn fungible_multi_asset(location: Location, amount: u128) -> Asset {

polkadot/xcm/xcm-builder/src/tests/pay/mock.rs

@@ -218,6 +218,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = ();
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 parameter_types! {

polkadot/xcm/xcm-builder/tests/mock/mod.rs

@@ -204,6 +204,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = ();
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 pub type LocalOriginToLocation = SignedToAccountId32<RuntimeOrigin, AccountId, KusamaNetwork>;

polkadot/xcm/xcm-executor/src/config.rs

@@ -16,7 +16,8 @@
 
 use crate::traits::{
 	AssetExchange, AssetLock, CallDispatcher, ClaimAssets, ConvertOrigin, DropAssets, ExportXcm,
-	FeeManager, OnResponse, ProcessTransaction, ShouldExecute, TransactAsset,
+	FeeManager, HandleHrmpChannelAccepted, HandleHrmpChannelClosing,
+	HandleHrmpNewChannelOpenRequest, OnResponse, ProcessTransaction, ShouldExecute, TransactAsset,
 	VersionChangeNotifier, WeightBounds, WeightTrader,
 };
 use frame_support::{
@@ -114,4 +115,11 @@ pub trait Config {
 
 	/// Transactional processor for XCM instructions.
 	type TransactionalProcessor: ProcessTransaction;
+
+	/// Allows optional logic execution for the `HrmpNewChannelOpenRequest` XCM notification.
+	type HrmpNewChannelOpenRequestHandler: HandleHrmpNewChannelOpenRequest;
+	/// Allows optional logic execution for the `HrmpChannelAccepted` XCM notification.
+	type HrmpChannelAcceptedHandler: HandleHrmpChannelAccepted;
+	/// Allows optional logic execution for the `HrmpChannelClosing` XCM notification.
+	type HrmpChannelClosingHandler: HandleHrmpChannelClosing;
 }

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

@@ -31,7 +31,8 @@ use xcm::latest::prelude::*;
 pub mod traits;
 use traits::{
 	validate_export, AssetExchange, AssetLock, CallDispatcher, ClaimAssets, ConvertOrigin,
-	DropAssets, Enact, ExportXcm, FeeManager, FeeReason, OnResponse, ProcessTransaction,
+	DropAssets, Enact, ExportXcm, FeeManager, FeeReason, HandleHrmpChannelAccepted,
+	HandleHrmpChannelClosing, HandleHrmpNewChannelOpenRequest, OnResponse, ProcessTransaction,
 	Properties, ShouldExecute, TransactAsset, VersionChangeNotifier, WeightBounds, WeightTrader,
 	XcmAssetTransfers,
 };
@@ -1212,9 +1213,21 @@ impl<Config: config::Config> XcmExecutor<Config> {
 				);
 				Ok(())
 			},
-			HrmpNewChannelOpenRequest { .. } => Err(XcmError::Unimplemented),
-			HrmpChannelAccepted { .. } => Err(XcmError::Unimplemented),
-			HrmpChannelClosing { .. } => Err(XcmError::Unimplemented),
+			HrmpNewChannelOpenRequest { sender, max_message_size, max_capacity } =>
+				Config::TransactionalProcessor::process(|| {
+					Config::HrmpNewChannelOpenRequestHandler::handle(
+						sender,
+						max_message_size,
+						max_capacity,
+					)
+				}),
+			HrmpChannelAccepted { recipient } => Config::TransactionalProcessor::process(|| {
+				Config::HrmpChannelAcceptedHandler::handle(recipient)
+			}),
+			HrmpChannelClosing { initiator, sender, recipient } =>
+				Config::TransactionalProcessor::process(|| {
+					Config::HrmpChannelClosingHandler::handle(initiator, sender, recipient)
+				}),
 		}
 	}
 }

polkadot/xcm/xcm-executor/src/traits/hrmp.rs

@@ -0,0 +1,56 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// This file is part of Polkadot.
+
+// Polkadot 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.
+
+// Polkadot 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 Polkadot.  If not, see <http://www.gnu.org/licenses/>.
+
+use xcm::latest::Result as XcmResult;
+
+/// Executes logic when a `HrmpNewChannelOpenRequest` XCM notification is received.
+pub trait HandleHrmpNewChannelOpenRequest {
+	fn handle(sender: u32, max_message_size: u32, max_capacity: u32) -> XcmResult;
+}
+
+/// Executes optional logic when a `HrmpChannelAccepted` XCM notification is received.
+pub trait HandleHrmpChannelAccepted {
+	fn handle(recipient: u32) -> XcmResult;
+}
+
+/// Executes optional logic when a `HrmpChannelClosing` XCM notification is received.
+pub trait HandleHrmpChannelClosing {
+	fn handle(initiator: u32, sender: u32, recipient: u32) -> XcmResult;
+}
+
+#[impl_trait_for_tuples::impl_for_tuples(30)]
+impl HandleHrmpNewChannelOpenRequest for Tuple {
+	fn handle(sender: u32, max_message_size: u32, max_capacity: u32) -> XcmResult {
+		for_tuples!( #( Tuple::handle(sender, max_message_size, max_capacity)?; )* );
+		Ok(())
+	}
+}
+
+#[impl_trait_for_tuples::impl_for_tuples(30)]
+impl HandleHrmpChannelAccepted for Tuple {
+	fn handle(recipient: u32) -> XcmResult {
+		for_tuples!( #( Tuple::handle(recipient)?; )* );
+		Ok(())
+	}
+}
+
+#[impl_trait_for_tuples::impl_for_tuples(30)]
+impl HandleHrmpChannelClosing for Tuple {
+	fn handle(initiator: u32, sender: u32, recipient: u32) -> XcmResult {
+		for_tuples!( #( Tuple::handle(initiator, sender, recipient)?; )* );
+		Ok(())
+	}
+}

polkadot/xcm/xcm-executor/src/traits/mod.rs

@@ -45,6 +45,10 @@ mod should_execute;
 pub use should_execute::{CheckSuspension, Properties, ShouldExecute};
 mod transact_asset;
 pub use transact_asset::TransactAsset;
+mod hrmp;
+pub use hrmp::{
+	HandleHrmpChannelAccepted, HandleHrmpChannelClosing, HandleHrmpNewChannelOpenRequest,
+};
 mod weight;
 #[deprecated = "Use `sp_runtime::traits::` instead"]
 pub use sp_runtime::traits::{Identity, TryConvertInto as JustTry};

polkadot/xcm/xcm-simulator/example/src/parachain.rs

@@ -251,6 +251,9 @@ impl Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 #[frame_support::pallet]

polkadot/xcm/xcm-simulator/example/src/relay_chain.rs

@@ -198,6 +198,9 @@ impl Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 pub type LocalOriginToLocation = SignedToAccountId32<RuntimeOrigin, AccountId, RelayNetwork>;

polkadot/xcm/xcm-simulator/fuzzer/src/parachain.rs

@@ -156,6 +156,9 @@ impl Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 #[frame_support::pallet]

polkadot/xcm/xcm-simulator/fuzzer/src/relay_chain.rs

@@ -157,6 +157,9 @@ impl Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 pub type LocalOriginToLocation = SignedToAccountId32<RuntimeOrigin, AccountId, ThisNetwork>;

prdoc/pr_3696.prdoc

@@ -0,0 +1,17 @@
+# Schema: Polkadot SDK PRDoc Schema (prdoc) v1.0.0
+# See doc at https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/prdoc/schema_user.json
+
+title: Add HRMP notification handlers to the xcm-executor
+
+doc:
+  - audience: Runtime Dev
+    description: |
+      Adds optional HRMP notification handlers to the xcm-executor. These handlers are 3 new config types on the xcm-executor `Config` trait:
+      - `HrmpNewChannelOpenRequestHandler`
+      - `HrmpChannelAcceptedHandler`
+      - `HrmpChannelClosingHandler`
+
+      The traits of these config types are implemented on tuples, and on `()` for the default case.
+
+crates:
+    - name: staging-xcm-executor

substrate/frame/contracts/mock-network/src/parachain.rs

@@ -282,6 +282,9 @@ impl Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 impl mock_msg_queue::Config for Runtime {

substrate/frame/contracts/mock-network/src/relay_chain.rs

@@ -182,6 +182,9 @@ impl Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 pub type LocalOriginToLocation = SignedToAccountId32<RuntimeOrigin, AccountId, RelayNetwork>;

templates/parachain/runtime/src/xcm_config.rs

@@ -137,6 +137,9 @@ impl xcm_executor::Config for XcmConfig {
 	type SafeCallFilter = Everything;
 	type Aliasers = Nothing;
 	type TransactionalProcessor = FrameTransactionalProcessor;
+	type HrmpNewChannelOpenRequestHandler = ();
+	type HrmpChannelAcceptedHandler = ();
+	type HrmpChannelClosingHandler = ();
 }
 
 /// No local origins on this chain are allowed to dispatch XCM sends/executions.