From e8afcebaa505f5a9102ea338b55ebbe3e0a0b220 Mon Sep 17 00:00:00 2001 From: Tiago Bandeira Date: Wed, 25 Jun 2025 13:37:39 +0100 Subject: [PATCH 01/10] refactor: rename functions and improve docs in the Solidity interface --- polkadot/xcm/pallet-xcm/src/precompiles.rs | 28 +++++++------- .../xcm/pallet-xcm/src/precompiles/IXcm.sol | 38 +++++++++++-------- 2 files changed, 36 insertions(+), 30 deletions(-) diff --git a/polkadot/xcm/pallet-xcm/src/precompiles.rs b/polkadot/xcm/pallet-xcm/src/precompiles.rs index 415fd1afaed93..07bfc19419cb7 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( @@ -366,8 +366,8 @@ mod test { .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); + 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( @@ -427,8 +427,8 @@ mod test { .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); + 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( @@ -496,8 +496,8 @@ mod test { .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); + 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..b0c08c12f6fb5 100644 --- a/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol +++ b/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol @@ -1,29 +1,35 @@ // 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 +/// @title An interface for interacting with `pallet_xcm` +/// @notice Provides functions for executing and sending XCM messages. +/// Learn more about XCM: https://docs.polkadot.com/develop/interoperability/ +/// @dev All parameters must be encoded using the SCALE codec. interface IXcm { - /// Weight v2 + /// @notice Weight v2 struct Weight { - /// The computational time used to execute some logic based on reference hardware + /// The computational time used to execute some logic based on reference hardware. uint64 refTime; - /// The size of the proof needed to execute some logic + /// 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. + /// @return Raw SCALE-encoded `DispatchResultWithPostInfo`. See more: 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 more: 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 + /// @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); } From 4bc464481c663653a8b67fcdcd0dec5602120db5 Mon Sep 17 00:00:00 2001 From: Tiago Bandeira Date: Sat, 28 Jun 2025 11:27:31 +0100 Subject: [PATCH 02/10] chore: format the Solidity interface and add the XCM precompile address --- .../xcm/pallet-xcm/src/precompiles/IXcm.sol | 22 ++++++++++++++----- 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol b/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol index b0c08c12f6fb5..05d3d025dcfbc 100644 --- a/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol +++ b/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol @@ -1,6 +1,9 @@ // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; +/// @dev The XCM Precompile contract address. +address constant XCM_PRECOMPILE_ADDRESS = address(0xA0000); + /// @title An interface for interacting with `pallet_xcm` /// @notice Provides functions for executing and sending XCM messages. /// Learn more about XCM: https://docs.polkadot.com/develop/interoperability/ @@ -18,18 +21,25 @@ interface IXcm { /// @dev Internally calls `pallet_xcm::execute`. /// @param message A SCALE-encoded Versioned XCM message. /// @param weight The maximum allowed `Weight` for execution. - /// @return Raw SCALE-encoded `DispatchResultWithPostInfo`. See more: https://paritytech.github.io/polkadot-sdk/master/frame_support/dispatch/type.DispatchResultWithPostInfo - function execute(bytes calldata message, Weight calldata weight) external returns (bytes memory); + /// @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 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 more: https://paritytech.github.io/polkadot-sdk/master/frame_support/dispatch/type.DispatchResult - function send(bytes calldata destination, bytes calldata message) external returns (bytes memory); + /// @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 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); -} + function weighMessage(bytes calldata message) + external + view + returns (Weight memory weight); +} \ No newline at end of file From a08114a81424a2f1854098e7e201d03acedb057d Mon Sep 17 00:00:00 2001 From: Tiago Bandeira Date: Sat, 28 Jun 2025 11:35:18 +0100 Subject: [PATCH 03/10] doc: add prdoc --- prdoc/pr_9023.prdoc | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 prdoc/pr_9023.prdoc diff --git a/prdoc/pr_9023.prdoc b/prdoc/pr_9023.prdoc new file mode 100644 index 0000000000000..81d216eb3ee0f --- /dev/null +++ b/prdoc/pr_9023.prdoc @@ -0,0 +1,16 @@ +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))`. + + 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: minor \ No newline at end of file From 0a4fb3e476d3983d493005c4f4ad78d05f874b69 Mon Sep 17 00:00:00 2001 From: "cmd[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 28 Jun 2025 10:38:15 +0000 Subject: [PATCH 04/10] Update from github-actions[bot] running command 'fmt' --- polkadot/xcm/pallet-xcm/src/precompiles.rs | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/polkadot/xcm/pallet-xcm/src/precompiles.rs b/polkadot/xcm/pallet-xcm/src/precompiles.rs index 07bfc19419cb7..91a624006ae0d 100644 --- a/polkadot/xcm/pallet-xcm/src/precompiles.rs +++ b/polkadot/xcm/pallet-xcm/src/precompiles.rs @@ -365,8 +365,7 @@ mod test { let weight: IXcm::Weight = IXcm::Weight::abi_decode(&weight_result.data[..]) .expect("XcmExecutePrecompile Failed to decode weight"); - let xcm_execute_params = - IXcm::executeCall { message: message.encode().into(), weight }; + 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(); @@ -426,8 +425,7 @@ mod test { let weight: IXcm::Weight = IXcm::Weight::abi_decode(&weight_result.data[..]) .expect("XcmExecutePrecompile Failed to decode weight"); - let xcm_execute_params = - IXcm::executeCall { message: message.encode().into(), weight }; + 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(); @@ -495,8 +493,7 @@ mod test { let weight: IXcm::Weight = IXcm::Weight::abi_decode(&weight_result.data[..]) .expect("XcmExecutePrecompile Failed to decode weight"); - let xcm_execute_params = - IXcm::executeCall { message: message.encode().into(), weight }; + 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(); From 45b9b26a0db529202795fc2d68e3933bfd152b36 Mon Sep 17 00:00:00 2001 From: Tiago Bandeira Date: Sat, 28 Jun 2025 11:51:46 +0100 Subject: [PATCH 05/10] fmt --- prdoc/pr_9023.prdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/prdoc/pr_9023.prdoc b/prdoc/pr_9023.prdoc index 81d216eb3ee0f..c55a7d0f1e289 100644 --- a/prdoc/pr_9023.prdoc +++ b/prdoc/pr_9023.prdoc @@ -13,4 +13,4 @@ doc: crates: - name: pallet-xcm - bump: minor \ No newline at end of file + bump: minor From a6c8ef20fe812d8c7696a87b52fb1b10029d3e98 Mon Sep 17 00:00:00 2001 From: Tiago Bandeira Date: Sat, 28 Jun 2025 12:04:00 +0100 Subject: [PATCH 06/10] doc: rm prdoc --- prdoc/pr_9023.prdoc | 16 ---------------- 1 file changed, 16 deletions(-) delete mode 100644 prdoc/pr_9023.prdoc diff --git a/prdoc/pr_9023.prdoc b/prdoc/pr_9023.prdoc deleted file mode 100644 index c55a7d0f1e289..0000000000000 --- a/prdoc/pr_9023.prdoc +++ /dev/null @@ -1,16 +0,0 @@ -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))`. - - 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: minor From 3d35356eb53b579db10085979222ba4ec1283bca Mon Sep 17 00:00:00 2001 From: "cmd[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 28 Jun 2025 11:06:43 +0000 Subject: [PATCH 07/10] Update from github-actions[bot] running command 'prdoc --audience runtime_user --bump minor' --- prdoc/pr_9023.prdoc | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 prdoc/pr_9023.prdoc diff --git a/prdoc/pr_9023.prdoc b/prdoc/pr_9023.prdoc new file mode 100644 index 0000000000000..85806dbf7c0a2 --- /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: minor From 659fcfb615f120e42f59edf651b597ed6faf489f Mon Sep 17 00:00:00 2001 From: Tiago Bandeira Date: Tue, 1 Jul 2025 18:33:04 +0100 Subject: [PATCH 08/10] doc(interface): improve docs --- .../xcm/pallet-xcm/src/precompiles/IXcm.sol | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol b/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol index 05d3d025dcfbc..46ea364e00d4d 100644 --- a/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol +++ b/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol @@ -1,19 +1,20 @@ // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; -/// @dev The XCM Precompile contract address. +/// @dev The on-chain address of the XCM (Cross-Consensus Messaging) precompile. address constant XCM_PRECOMPILE_ADDRESS = address(0xA0000); -/// @title An interface for interacting with `pallet_xcm` -/// @notice Provides functions for executing and sending XCM messages. -/// Learn more about XCM: https://docs.polkadot.com/develop/interoperability/ -/// @dev All parameters must be encoded using the SCALE codec. +/// @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 { - /// @notice Weight v2 + /// @notice Weight v2. 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; } @@ -21,6 +22,7 @@ interface IXcm { /// @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 @@ -42,4 +44,4 @@ interface IXcm { external view returns (Weight memory weight); -} \ No newline at end of file +} From 03d69c151af01035631a883f84dacb9bcfd58c80 Mon Sep 17 00:00:00 2001 From: Tiago Bandeira Date: Tue, 1 Jul 2025 19:10:15 +0100 Subject: [PATCH 09/10] doc: update prdoc --- prdoc/pr_9023.prdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/prdoc/pr_9023.prdoc b/prdoc/pr_9023.prdoc index 85806dbf7c0a2..6ae154ca52635 100644 --- a/prdoc/pr_9023.prdoc +++ b/prdoc/pr_9023.prdoc @@ -15,4 +15,4 @@ doc: 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: minor + bump: major From 04b699ac0969677c1504ee2f1b277f94773fad3d Mon Sep 17 00:00:00 2001 From: Tiago Bandeira Date: Wed, 2 Jul 2025 09:01:55 +0100 Subject: [PATCH 10/10] doc: fix natspec format --- polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol b/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol index 46ea364e00d4d..312e742b9232f 100644 --- a/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol +++ b/polkadot/xcm/pallet-xcm/src/precompiles/IXcm.sol @@ -6,11 +6,13 @@ 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. +/// 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 { - /// @notice Weight v2. See https://docs.polkadot.com/polkadot-protocol/parachain-basics/blocks-transactions-fees/fees/#transactions-weights-and-fees + /// @notice Weight v2 + /// @dev See https://docs.polkadot.com/polkadot-protocol/parachain-basics/blocks-transactions-fees/fees/#transactions-weights-and-fees struct Weight { /// @custom:property The computational time used to execute some logic based on reference hardware. uint64 refTime;