From 1e6b6814d0cb627e2ca89d1b9b90f1aace5383a3 Mon Sep 17 00:00:00 2001 From: Agusrodri Date: Thu, 12 Dec 2024 08:41:21 -0800 Subject: [PATCH 1/2] improve pallet-xcm precompile docs --- precompiles/pallet-xcm/XcmInterface.sol | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/precompiles/pallet-xcm/XcmInterface.sol b/precompiles/pallet-xcm/XcmInterface.sol index d657a2b9..4daa9e8b 100644 --- a/precompiles/pallet-xcm/XcmInterface.sol +++ b/precompiles/pallet-xcm/XcmInterface.sol @@ -41,6 +41,7 @@ interface XCM { /// @param dest The destination chain. /// @param beneficiary The actual account that will receive the tokens on dest. /// @param assets The combination (array) of assets to send in Location format. + /// Assets MUST be sorted, otherwise there may be discrepancies with the feeAssetItem. /// @param feeAssetItem The index of the asset that will be used to pay for fees. function transferAssetsLocation( Location memory dest, @@ -55,6 +56,7 @@ interface XCM { /// @param paraId The para-id of the destination chain. /// @param beneficiary The actual account that will receive the tokens on paraId destination. /// @param assets The combination (array) of assets to send in Address format. + /// Assets MUST be sorted, otherwise there may be discrepancies with the feeAssetItem. /// @param feeAssetItem The index of the asset that will be used to pay for fees. function transferAssetsToPara20( uint32 paraId, @@ -69,6 +71,7 @@ interface XCM { /// @param paraId The para-id of the destination chain. /// @param beneficiary The actual account that will receive the tokens on paraId destination. /// @param assets The combination (array) of assets to send in Address format. + /// Assets MUST be sorted, otherwise there may be discrepancies with the feeAssetItem. /// @param feeAssetItem The index of the asset that will be used to pay for fees. function transferAssetsToPara32( uint32 paraId, @@ -82,6 +85,7 @@ interface XCM { /// @custom:selector 6521cc2c /// @param beneficiary The actual account that will receive the tokens on the relay chain. /// @param assets The combination (array) of assets to send in Address format. + /// Assets MUST be sorted, otherwise there may be discrepancies with the feeAssetItem. /// @param feeAssetItem The index of the asset that will be used to pay for fees. function transferAssetsToRelay( bytes32 beneficiary, @@ -97,6 +101,7 @@ interface XCM { /// @custom:selector 8425d893 /// @param dest The destination chain. /// @param assets The combination (array) of assets to send in Location format. + /// Assets MUST be sorted, otherwise there may be discrepancies with the remoteFeesIdIndex. /// @param assetsTransferType The TransferType corresponding to assets being sent. /// @param remoteFeesIdIndex The index of the asset (inside assets array) to use as fees. /// @param feesTransferType The TransferType corresponding to the asset used as fees. @@ -115,6 +120,7 @@ interface XCM { /// @custom:selector fc19376c /// @param dest The destination chain. /// @param assets The combination (array) of assets to send in Location format. + /// Assets MUST be sorted, otherwise there may be discrepancies with the remoteFeesIdIndex. /// @param remoteFeesIdIndex The index of the asset (inside assets array) to use as fees. /// @param customXcmOnDest The XCM message to execute on destination chain (SCALE encoded). /// @param remoteReserve The remote reserve corresponding for assets and fees. They MUST @@ -135,6 +141,7 @@ interface XCM { /// @custom:selector 998093ee /// @param dest The destination chain. /// @param assets The combination (array) of assets to send in Address format. + /// Assets MUST be sorted, otherwise there may be discrepancies with the remoteFeesIdIndex. /// @param assetsTransferType The TransferType corresponding to assets being sent. /// @param remoteFeesIdIndex The index of the asset (inside assets array) to use as fees. /// @param feesTransferType The TransferType corresponding to the asset used as fees. @@ -153,6 +160,7 @@ interface XCM { /// @custom:selector aaecfc62 /// @param dest The destination chain. /// @param assets The combination (array) of assets to send in Address format. + /// Assets MUST be sorted, otherwise there may be discrepancies with the remoteFeesIdIndex. /// @param remoteFeesIdIndex The index of the asset (inside assets array) to use as fees. /// @param customXcmOnDest The XCM message to execute on destination chain (SCALE encoded). /// @param remoteReserve The remote reserve corresponding for assets and fees. They MUST From b09ebf94b7dcf3beee578cb9edd5df1a4db01ea7 Mon Sep 17 00:00:00 2001 From: Agusrodri Date: Mon, 16 Dec 2024 12:40:55 -0800 Subject: [PATCH 2/2] add examples for assets ordering --- precompiles/pallet-xcm/XcmInterface.sol | 104 ++++++++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/precompiles/pallet-xcm/XcmInterface.sol b/precompiles/pallet-xcm/XcmInterface.sol index 4daa9e8b..96638aae 100644 --- a/precompiles/pallet-xcm/XcmInterface.sol +++ b/precompiles/pallet-xcm/XcmInterface.sol @@ -42,6 +42,19 @@ interface XCM { /// @param beneficiary The actual account that will receive the tokens on dest. /// @param assets The combination (array) of assets to send in Location format. /// Assets MUST be sorted, otherwise there may be discrepancies with the feeAssetItem. + /// + /// Example a) of sorted assets (native asset and para 1000 asset): + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// + /// Example b) of sorted assets: (native asset and relay asset) + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: Here} + /// + /// Example c) of sorted assets: (relay asset and para 1000 asset) + /// 1st - Location { parents: 1, interior: Here} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// /// @param feeAssetItem The index of the asset that will be used to pay for fees. function transferAssetsLocation( Location memory dest, @@ -57,6 +70,19 @@ interface XCM { /// @param beneficiary The actual account that will receive the tokens on paraId destination. /// @param assets The combination (array) of assets to send in Address format. /// Assets MUST be sorted, otherwise there may be discrepancies with the feeAssetItem. + /// + /// Example a) of sorted assets (native asset and para 1000 asset): + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// + /// Example b) of sorted assets: (native asset and relay asset) + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: Here} + /// + /// Example c) of sorted assets: (relay asset and para 1000 asset) + /// 1st - Location { parents: 1, interior: Here} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// /// @param feeAssetItem The index of the asset that will be used to pay for fees. function transferAssetsToPara20( uint32 paraId, @@ -72,6 +98,19 @@ interface XCM { /// @param beneficiary The actual account that will receive the tokens on paraId destination. /// @param assets The combination (array) of assets to send in Address format. /// Assets MUST be sorted, otherwise there may be discrepancies with the feeAssetItem. + /// + /// Example a) of sorted assets (native asset and para 1000 asset): + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// + /// Example b) of sorted assets: (native asset and relay asset) + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: Here} + /// + /// Example c) of sorted assets: (relay asset and para 1000 asset) + /// 1st - Location { parents: 1, interior: Here} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// /// @param feeAssetItem The index of the asset that will be used to pay for fees. function transferAssetsToPara32( uint32 paraId, @@ -86,6 +125,19 @@ interface XCM { /// @param beneficiary The actual account that will receive the tokens on the relay chain. /// @param assets The combination (array) of assets to send in Address format. /// Assets MUST be sorted, otherwise there may be discrepancies with the feeAssetItem. + /// + /// Example a) of sorted assets (native asset and para 1000 asset): + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// + /// Example b) of sorted assets: (native asset and relay asset) + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: Here} + /// + /// Example c) of sorted assets: (relay asset and para 1000 asset) + /// 1st - Location { parents: 1, interior: Here} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// /// @param feeAssetItem The index of the asset that will be used to pay for fees. function transferAssetsToRelay( bytes32 beneficiary, @@ -102,6 +154,19 @@ interface XCM { /// @param dest The destination chain. /// @param assets The combination (array) of assets to send in Location format. /// Assets MUST be sorted, otherwise there may be discrepancies with the remoteFeesIdIndex. + /// + /// Example a) of sorted assets (native asset and para 1000 asset): + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// + /// Example b) of sorted assets: (native asset and relay asset) + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: Here} + /// + /// Example c) of sorted assets: (relay asset and para 1000 asset) + /// 1st - Location { parents: 1, interior: Here} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// /// @param assetsTransferType The TransferType corresponding to assets being sent. /// @param remoteFeesIdIndex The index of the asset (inside assets array) to use as fees. /// @param feesTransferType The TransferType corresponding to the asset used as fees. @@ -121,6 +186,19 @@ interface XCM { /// @param dest The destination chain. /// @param assets The combination (array) of assets to send in Location format. /// Assets MUST be sorted, otherwise there may be discrepancies with the remoteFeesIdIndex. + /// + /// Example a) of sorted assets (native asset and para 1000 asset): + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// + /// Example b) of sorted assets: (native asset and relay asset) + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: Here} + /// + /// Example c) of sorted assets: (relay asset and para 1000 asset) + /// 1st - Location { parents: 1, interior: Here} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// /// @param remoteFeesIdIndex The index of the asset (inside assets array) to use as fees. /// @param customXcmOnDest The XCM message to execute on destination chain (SCALE encoded). /// @param remoteReserve The remote reserve corresponding for assets and fees. They MUST @@ -142,6 +220,19 @@ interface XCM { /// @param dest The destination chain. /// @param assets The combination (array) of assets to send in Address format. /// Assets MUST be sorted, otherwise there may be discrepancies with the remoteFeesIdIndex. + /// + /// Example a) of sorted assets (native asset and para 1000 asset): + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// + /// Example b) of sorted assets: (native asset and relay asset) + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: Here} + /// + /// Example c) of sorted assets: (relay asset and para 1000 asset) + /// 1st - Location { parents: 1, interior: Here} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// /// @param assetsTransferType The TransferType corresponding to assets being sent. /// @param remoteFeesIdIndex The index of the asset (inside assets array) to use as fees. /// @param feesTransferType The TransferType corresponding to the asset used as fees. @@ -161,6 +252,19 @@ interface XCM { /// @param dest The destination chain. /// @param assets The combination (array) of assets to send in Address format. /// Assets MUST be sorted, otherwise there may be discrepancies with the remoteFeesIdIndex. + /// + /// Example a) of sorted assets (native asset and para 1000 asset): + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// + /// Example b) of sorted assets: (native asset and relay asset) + /// 1st - Location { parents: 0, interior: [PalletInstance(3)]} + /// 2nd - Location { parents: 1, interior: Here} + /// + /// Example c) of sorted assets: (relay asset and para 1000 asset) + /// 1st - Location { parents: 1, interior: Here} + /// 2nd - Location { parents: 1, interior: [Parachain(1000), PalletInstance(3)]} + /// /// @param remoteFeesIdIndex The index of the asset (inside assets array) to use as fees. /// @param customXcmOnDest The XCM message to execute on destination chain (SCALE encoded). /// @param remoteReserve The remote reserve corresponding for assets and fees. They MUST