[XCM Precompile] Rename functions and improve docs in the Solidity interface

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

@@ -62,7 +62,7 @@ where
 		};
 
 		match input {
-			IXcmCalls::xcmSend(IXcm::xcmSendCall { destination, message }) => {
+			IXcmCalls::send(IXcm::sendCall { destination, message }) => {
 				let _ = env.charge(<Runtime as Config>::WeightInfo::send())?;
 
 				let final_destination = VersionedLocation::decode_all(&mut &destination[..])
@@ -89,7 +89,7 @@ where
 					)
 				})
 			},
-			IXcmCalls::xcmExecute(IXcm::xcmExecuteCall { message, weight }) => {
+			IXcmCalls::execute(IXcm::executeCall { message, weight }) => {
 				let max_weight = Weight::from_parts(weight.refTime, weight.proofSize);
 				let weight_to_charge =
 					max_weight.saturating_add(<Runtime as Config>::WeightInfo::execute());
@@ -202,11 +202,11 @@ mod test {
 			let versioned_dest: VersionedLocation = RelayLocation::get().into();
 			let versioned_message: VersionedXcm<()> = VersionedXcm::from(message.clone());
 
-			let xcm_send_params = IXcm::xcmSendCall {
+			let xcm_send_params = IXcm::sendCall {
 				destination: versioned_dest.encode().into(),
 				message: versioned_message.encode().into(),
 			};
-			let call = IXcm::IXcmCalls::xcmSend(xcm_send_params);
+			let call = IXcm::IXcmCalls::send(xcm_send_params);
 			let encoded_call = call.abi_encode();
 
 			let result = pallet_revive::Pallet::<Test>::bare_call(
@@ -250,11 +250,11 @@ mod test {
 			let destination: VersionedLocation = Parachain(OTHER_PARA_ID).into();
 			let versioned_message: VersionedXcm<()> = VersionedXcm::from(message.clone());
 
-			let xcm_send_params = IXcm::xcmSendCall {
+			let xcm_send_params = IXcm::sendCall {
 				destination: destination.encode().into(),
 				message: versioned_message.encode().into(),
 			};
-			let call = IXcm::IXcmCalls::xcmSend(xcm_send_params);
+			let call = IXcm::IXcmCalls::send(xcm_send_params);
 			let encoded_call = call.abi_encode();
 
 			let result = pallet_revive::Pallet::<Test>::bare_call(
@@ -298,11 +298,11 @@ mod test {
 			let destination: VersionedLocation = VersionedLocation::from(Location::ancestor(8));
 			let versioned_message: VersionedXcm<RuntimeCall> = VersionedXcm::from(message);
 
-			let xcm_send_params = IXcm::xcmSendCall {
+			let xcm_send_params = IXcm::sendCall {
 				destination: destination.encode().into(),
 				message: versioned_message.encode().into(),
 			};
-			let call = IXcm::IXcmCalls::xcmSend(xcm_send_params);
+			let call = IXcm::IXcmCalls::send(xcm_send_params);
 			let encoded_call = call.abi_encode();
 
 			let result = pallet_revive::Pallet::<Test>::bare_call(
@@ -365,9 +365,8 @@ mod test {
 			let weight: IXcm::Weight = IXcm::Weight::abi_decode(&weight_result.data[..])
 				.expect("XcmExecutePrecompile Failed to decode weight");
 
-			let xcm_execute_params =
-				IXcm::xcmExecuteCall { message: message.encode().into(), weight };
-			let call = IXcm::IXcmCalls::xcmExecute(xcm_execute_params);
+			let xcm_execute_params = IXcm::executeCall { message: message.encode().into(), weight };
+			let call = IXcm::IXcmCalls::execute(xcm_execute_params);
 			let encoded_call = call.abi_encode();
 
 			let result = pallet_revive::Pallet::<Test>::bare_call(
@@ -426,9 +425,8 @@ mod test {
 			let weight: IXcm::Weight = IXcm::Weight::abi_decode(&weight_result.data[..])
 				.expect("XcmExecutePrecompile Failed to decode weight");
 
-			let xcm_execute_params =
-				IXcm::xcmExecuteCall { message: message.encode().into(), weight };
-			let call = IXcm::IXcmCalls::xcmExecute(xcm_execute_params);
+			let xcm_execute_params = IXcm::executeCall { message: message.encode().into(), weight };
+			let call = IXcm::IXcmCalls::execute(xcm_execute_params);
 			let encoded_call = call.abi_encode();
 
 			let result = pallet_revive::Pallet::<Test>::bare_call(
@@ -495,9 +493,8 @@ mod test {
 			let weight: IXcm::Weight = IXcm::Weight::abi_decode(&weight_result.data[..])
 				.expect("XcmExecutePrecompile Failed to decode weight");
 
-			let xcm_execute_params =
-				IXcm::xcmExecuteCall { message: message.encode().into(), weight };
-			let call = IXcm::IXcmCalls::xcmExecute(xcm_execute_params);
+			let xcm_execute_params = IXcm::executeCall { message: message.encode().into(), weight };
+			let call = IXcm::IXcmCalls::execute(xcm_execute_params);
 			let encoded_call = call.abi_encode();
 
 			let result = pallet_revive::Pallet::<Test>::bare_call(

polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol

@@ -1,29 +1,49 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.20;
 
-/// @title Defines all functions that can be used to interact with XCM
-/// @dev Parameters MUST use SCALE codec serialisation
+/// @dev The on-chain address of the XCM (Cross-Consensus Messaging) precompile.
+address constant XCM_PRECOMPILE_ADDRESS = address(0xA0000);
+
+/// @title XCM Precompile Interface
+/// @notice A low-level interface for interacting with `pallet_xcm`.
+/// It forwards calls directly to the corresponding dispatchable functions, 
+/// providing access to XCM execution and message passing.
+/// Learn more about XCM: https://docs.polkadot.com/develop/interoperability
+/// @dev All parameters must be encoded using the SCALE codec. See https://docs.polkadot.com/polkadot-protocol/parachain-basics/data-encoding
 interface IXcm {
-    /// Weight v2
+    /// @notice Weight v2
+    /// @dev See https://docs.polkadot.com/polkadot-protocol/parachain-basics/blocks-transactions-fees/fees/#transactions-weights-and-fees
     struct Weight {
-        /// The computational time used to execute some logic based on reference hardware
+        /// @custom:property The computational time used to execute some logic based on reference hardware.
         uint64 refTime;
-        /// The size of the proof needed to execute some logic
+        /// @custom:property The size of the proof needed to execute some logic.
         uint64 proofSize;
     }
 
-    /// @notice Execute a Versioned XCM message locally with the caller's origin
-    /// @param message The Versioned XCM message to send
-    /// @param weight The maximum amount of weight to be used to execute the message
-    function xcmExecute(bytes calldata message, Weight calldata weight) external;
+    /// @notice Executes an XCM message locally on the current chain with the caller's origin.
+    /// @dev Internally calls `pallet_xcm::execute`.
+    /// @param message A SCALE-encoded Versioned XCM message.
+    /// @param weight The maximum allowed `Weight` for execution.
+    /// @dev Call @custom:function weighMessage(message) to ensure sufficient weight allocation.
+    /// @return Raw SCALE-encoded `DispatchResultWithPostInfo`. See https://paritytech.github.io/polkadot-sdk/master/frame_support/dispatch/type.DispatchResultWithPostInfo
+    function execute(bytes calldata message, Weight calldata weight)
+        external
+        returns (bytes memory);
 
-    /// @notice Send an Versioned XCM message to a destination chain
-    /// @param destination The destination location, encoded according to the XCM format
-    /// @param message The Versioned XCM message to send
-    function xcmSend(bytes calldata destination, bytes calldata message) external;
+    /// @notice Sends an XCM message to another parachain or consensus system.
+    /// @dev Internally calls `pallet_xcm::send`.
+    /// @param destination SCALE-encoded destination MultiLocation.
+    /// @param message SCALE-encoded Versioned XCM message.
+    /// @return Raw SCALE-encoded `DispatchResult`. See https://paritytech.github.io/polkadot-sdk/master/frame_support/dispatch/type.DispatchResult
+    function send(bytes calldata destination, bytes calldata message)
+        external
+        returns (bytes memory);
 
-    /// @notice Given a message estimate the weight cost
-    /// @param message The XCM message to send
-    /// @returns weight estimated for sending the message
-    function weighMessage(bytes calldata message) external view returns (Weight memory weight);
+    /// @notice Estimates the `Weight` required to execute a given XCM message.
+    /// @param message SCALE-encoded Versioned XCM message to analyze.
+    /// @return weight Struct containing estimated `refTime` and `proofSize`.
+    function weighMessage(bytes calldata message)
+        external
+        view
+        returns (Weight memory weight);
 }

prdoc/pr_9023.prdoc

@@ -0,0 +1,18 @@
+title: '[XCM Precompile] Rename functions and improve docs in the Solidity interface'
+doc:
+- audience: Runtime User
+  description: |-
+    This PR changes the function names on the XCM Precompile from `xcmExecute` and `xcmSend` to `execute` and `send`, respectively. This is a breaking change because it modifies the ABI-encoded function selectors, which are calculated using `bytes4(keccak256(FUNCTION_SIGNATURE))`.
+
+    `bytes4(keccak256("xcmSend(bytes,bytes)"))` -> `0xc0addb55`
+    is going to be now
+    `bytes4(keccak256("send(bytes,bytes)"))` -> `0x7f0a3bf9`
+
+    `bytes4(keccak256("xcmExecute(bytes,(uint64,uint64)))"))` => `0x377df829`
+    is going to be  now
+    `bytes4(keccak256("execute(bytes,(uint64,uint64)))"))` => `0xd3b7e04d`
+
+    It also adds new documentation to the precompile, directing developers to the official Polkadot XCM documentation. Additionally, it explicitly sets return values for both functions to clarify that the return value matches what is returned by `pallet_xcm::send()` and `pallet_xcm::execute()`.
+crates:
+- name: pallet-xcm
+  bump: major