diff --git a/polkadot/xcm/pallet-xcm/src/precompiles.rs b/polkadot/xcm/pallet-xcm/src/precompiles.rs index 415fd1afaed93..91a624006ae0d 100644 --- a/polkadot/xcm/pallet-xcm/src/precompiles.rs +++ b/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(::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(::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::::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::::bare_call( @@ -298,11 +298,11 @@ mod test { let destination: VersionedLocation = VersionedLocation::from(Location::ancestor(8)); let versioned_message: VersionedXcm = 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::::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::::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::::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::::bare_call( diff --git a/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol b/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol index 8e7dab377499a..312e742b9232f 100644 --- a/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol +++ b/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); } diff --git a/prdoc/pr_9023.prdoc b/prdoc/pr_9023.prdoc new file mode 100644 index 0000000000000..6ae154ca52635 --- /dev/null +++ b/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