Update Substrate PalletXCM and Send XC-20s Overview

.snippets/code/builders/interoperability/xcm/core-concepts/sovereign-accounts/terminal/calculate.md

@@ -0,0 +1,8 @@
+<div id="termynal" data-termynal>
+<span data-ty="input"><span class="file-path">yarn calculate-sovereign-account --p 1000 --r moonbase</span>
+<span data-ty>yarn run v1.22.22</span>
+<span data-ty>$ ts-node 'scripts/calculate-sovereign-account.ts' --p 1000 --r moonbase</span>
+<span data-ty>Sovereign Account Address on Relay: 0x70617261e8030000000000000000000000000000000000000000000000000000</span>
+<span data-ty>Sovereign Account Address on other Parachains (Generic): 0x7369626ce8030000000000000000000000000000000000000000000000000000</span>
+<span data-ty>Sovereign Account Address on Moonbase Alpha: 0x7369626ce8030000000000000000000000000000</span>
+</div>

.snippets/code/builders/interoperability/xcm/xc20/send-xc20s/polkadot-xcm/destination-beneficiary-fee.js

@@ -1,40 +1,44 @@
-      // dest
+ // dest
       {
-        V3: {
+        V4: {
           parents: 1,
-          interior: 'Here'
+          interior: {
+            Here: null
+          }
         }
       },
       // beneficiary
       {
-        V3: {
-          parents: 0,
+        V4: {
+          parents: 1,                   
           interior: {
-            X1: {
-              AccountId32: {
-                id: Array.from(beneficiaryRaw),
-                network: null
+            X1: [                        
+              {
+                AccountId32: {
+                  id: Array.from(beneficiaryRaw),
+                  network: null
+                }
               }
-            }
+            ]
           }
         }
       },
       // assets
       {
-        V3: [
+        V4: [                           
           {
-            id: {
-              Concrete: {
-                parents: 1,
-                interior: 'Here'
-              }
+            fun: {                      
+              Fungible: 1000000000000n 
             },
-            fun: {
-              Fungible: '1000000000000'
+            id: {                       
+              parents: 1,
+              interior: {
+                Here: null              
+              }
             }
           }
         ]
       },
-      0, // feeAssetItem
-      'Unlimited' // weightLimit
+      0,           // feeAssetItem
+      'Unlimited'  // weightLimit
     );

.snippets/code/builders/interoperability/xcm/xc20/send-xc20s/polkadot-xcm/send-xcm.js

@@ -1,5 +1,4 @@
 import { ApiPromise, WsProvider, Keyring } from '@polkadot/api';
-import { BN } from '@polkadot/util';
 import { decodeAddress } from '@polkadot/util-crypto';
 
 const main = async () => {
@@ -15,51 +14,55 @@ const main = async () => {
   const beneficiaryRaw = decodeAddress('INSERT_DESTINATION_ADDRESS');
 
   try {
-    // Create the transaction
+    // Create the transaction (XCM v4)
     const tx = api.tx.polkadotXcm.transferAssets(
-      // dest
+      // Destination (V4)
       {
-        V3: {
+        V4: {
           parents: 1,
-          interior: 'Here',
-        },
+          interior: {
+            Here: null
+          }
+        }
       },
-      // beneficiary
+      // Beneficiary (V4)
       {
-        V3: {
-          parents: 0,
+        V4: {
+          parents: 1,
           interior: {
-            X1: {
-              AccountId32: {
-                id: Array.from(beneficiaryRaw),
-                network: null,
-              },
-            },
-          },
-        },
+            X1: [
+              {
+                AccountId32: {
+                  network: null,
+                  id: beneficiaryRaw
+                }
+              }
+            ]
+          }
+        }
       },
-      // assets
+      // Assets (V4)
       {
-        V3: [
+        V4: [
           {
-            id: {
-              Concrete: {
-                parents: 1,
-                interior: 'Here',
-              },
-            },
             fun: {
-              Fungible: '1000000000000',
+              Fungible: 1000000000000n
             },
-          },
-        ],
+            id: {
+              parents: 1,
+              interior: {
+                Here: null
+              }
+            }
+          }
+        ]
       },
-      0, // feeAssetItem
-      'Unlimited' // weightLimit
+      0,           // feeAssetItem
+      'Unlimited'  // weightLimit
     );
 
-    // Sign and send the transaction, displaying the transaction hash
-    const unsub = await tx.signAndSend(account, ({ status, events }) => {
+    // Sign and send the transaction
+    const unsub = await tx.signAndSend(account, ({ status }) => {
       if (status.isInBlock) {
         console.log(`Transaction included in blockHash ${status.asInBlock}`);
       } else if (status.isFinalized) {

.snippets/text/builders/interoperability/xcm/xc20/send-xc20s/overview/DOT-to-xcDOT-instructions.md

@@ -1,7 +1,11 @@
-For example, to move DOT to Moonbeam, the following XCM instructions are used:
+When DOT is transferred from Polkadot to Moonbeam, the following XCM instructions are executed in sequence:
 
-1. [`TransferReserveAsset`](/builders/interoperability/xcm/core-concepts/instructions/#transfer-reserve-asset){target=\_blank} - gets executed in Polkadot. Assets are transferred from the origin account and deposited into Moonbeam's Sovereign account on Polkadot
-2. [`ReserveAssetDeposited`](/builders/interoperability/xcm/core-concepts/instructions/#reserve-asset-deposited){target=\_blank} - gets executed in Moonbeam. Mints the DOT representation on Moonbeam, called xcDOT
-3. [`ClearOrigin`](/builders/interoperability/xcm/core-concepts/instructions/#clear-origin){target=\_blank} - gets executed in Moonbeam. Clears origin information, which was Polkadot's Sovereign account on Moonbeam
-4. [`BuyExecution`](/builders/interoperability/xcm/core-concepts/instructions/#buy-execution){target=\_blank} - gets executed in Moonbeam. As such, execution fees are determined by Moonbeam. In this particular scenario, part of the minted xcDOT is used to pay for XCM execution
-5. [`DepositAsset`](/builders/interoperability/xcm/core-concepts/instructions/#deposit-asset){target=\_blank} - gets executed in Moonbeam. Ultimately, it sends assets to a destination account on Moonbeam
+1. [`TransferReserveAsset`](/builders/interoperability/xcm/core-concepts/instructions/#transfer-reserve-asset){target=_blank} - executes on Polkadot, moving the DOT from the sender and depositing it into Moonbeam’s Sovereign account on Polkadot
+
+2. [`ReserveAssetDeposited`](/builders/interoperability/xcm/core-concepts/instructions/#reserve-asset-deposited){target=_blank} - executes on Moonbeam, minting the corresponding ERC-20 representation of DOT (xcDOT) on Moonbeam
+
+3. [`ClearOrigin`](/builders/interoperability/xcm/core-concepts/instructions/#clear-origin){target=_blank} - executes on Moonbeam, clearing any origin data—previously set to Polkadot’s Sovereign account
+
+4. [`BuyExecution`](/builders/interoperability/xcm/core-concepts/instructions/#buy-execution){target=_blank} - executes on Moonbeam, determining the execution fees. Here, a portion of the newly minted xcDOT is used to pay the cost of XCM
+
+5. [`DepositAsset`](/builders/interoperability/xcm/core-concepts/instructions/#deposit-asset){target=_blank} - executes on Moonbeam, delivering the xcDOT to the intended recipient’s account on Moonbeam

.snippets/text/builders/interoperability/xcm/xc20/send-xc20s/overview/xcDOT-to-DOT-instructions.md

@@ -1,8 +1,13 @@
-To move xcDOT from Moonbeam back to Polkadot, the instructions that are used are:
-
-1. [`WithdrawAsset`](/builders/interoperability/xcm/core-concepts/instructions/#withdraw-asset){target=\_blank} - gets executed in Moonbeam. Takes the funds from the sender
-2. [`InitiateReserveWithdraw`](/builders/interoperability/xcm/core-concepts/instructions/#initiate-reserve-withdraw){target=\_blank} - gets executed in Moonbeam. Burns the funds while sending an XCM message to the destination chain to execute the remainder of the token transfer
-3. [`WithdrawAsset`](/builders/interoperability/xcm/core-concepts/instructions/#withdraw-asset){target=\_blank} - gets executed in Polkadot. Takes the funds from Moonbeam's Sovereign account on Polkadot
-4. [`ClearOrigin`](/builders/interoperability/xcm/core-concepts/instructions/#clear-origin){target=\_blank} - gets executed in Polkadot. Clears origin information, which was Moonbeam's Sovereign account on Moonbeam
-5. [`BuyExecution`](/builders/interoperability/xcm/core-concepts/instructions/#buy-execution){target=\_blank} - gets executed in Polkadot. As such, Polkadot determines the execution fees. In this scenario, part of the DOTs being sent are used to pay for the execution of the XCM
-6. [`DepositAsset`](/builders/interoperability/xcm/core-concepts/instructions/#deposit-asset){target=\_blank} - gets executed in Polkadot. Ultimately, it sends assets to a destination account on Polkadot
+In scenarios where you want to move an asset back to its reserve chain, such as sending xcDOT from Moonbeam to Polkadot, Moonbeam uses the following set of XCM instructions:
+
+1. [`WithdrawAsset`](/builders/interoperability/xcm/core-concepts/instructions/#withdraw-asset){target=_blank} – executes on Moonbeam, taking the specified token (xcDOT) from the sender
+
+2. [`InitiateReserveWithdraw`](/builders/interoperability/xcm/core-concepts/instructions/#initiate-reserve-withdraw){target=_blank} – executes on Moonbeam, which, burns the token on Moonbeam (removing the wrapped representation), and sends an XCM message to Polkadot, indicating the tokens should be released there 
+
+3. [`WithdrawAsset`](/builders/interoperability/xcm/core-concepts/instructions/#withdraw-asset){target=_blank} – executes on Polkadot, removing the tokens from Moonbeam’s Sovereign account on Polkadot
+
+4. [`ClearOrigin`](/builders/interoperability/xcm/core-concepts/instructions/#clear-origin){target=_blank} – gets executed on Polkadot. Clears any origin data (e.g., the Sovereign account on Moonbeam)
+
+5. [`BuyExecution`](/builders/interoperability/xcm/core-concepts/instructions/#buy-execution){target=_blank} – Polkadot determines the execution fees and uses part of the DOT being transferred to pay for them
+
+6. [`DepositAsset`](/builders/interoperability/xcm/core-concepts/instructions/#deposit-asset){target=_blank} – finally, the native DOT tokens are deposited into the specified Polkadot account

builders/interoperability/xcm/core-concepts/.pages

@@ -4,3 +4,4 @@ nav:
   - 'XCM Instructions': 'instructions.md'
   - 'Multilocations': 'multilocations.md'
   - 'Weights and Fees': 'weights-fees.md'
+  - 'Sovereign Accounts': 'sovereign-accounts.md'

builders/interoperability/xcm/core-concepts/sovereign-accounts.md

@@ -0,0 +1,37 @@
+---
+title: Sovereign Accounts and Reserve-Backed Transfers
+description: Discover how sovereign accounts work on Moonbeam, how to calculate them, and their role in cross-chain asset transfers.
+---
+
+# Overview of Sovereign Accounts
+
+## Introduction {: #introduction }
+
+In Polkadot-based ecosystems, a sovereign account is a unique, keyless account controlled by a blockchain’s runtime through XCM rather than an individual or organization. These accounts are used to store assets when transferring tokens cross-chain. For example, if you send a reserve tokens transfer from a parachain to Moonbeam, the originating parachain locks those tokens in Moonbeam’s sovereign account on the source chain, while a wrapped representation of those tokens is minted on Moonbeam.
+
+Sovereign accounts play a central role in [reserve-backed transfers](https://wiki.polkadot.network/docs/learn/xcm/journey/transfers-reserve){target=\_blank}, where one chain (the “reserve”) holds the real assets and other chains hold derivative tokens. When tokens move across chains, the reserve (or origin) chain locks or unlocks the underlying asset, and derivative tokens are minted or burned on the destination chain.
+
+## Calculating a Parachain Sovereign Account {: #calculating-sovereign }
+
+You can calculate a parachain’s sovereign account on a given relay chain using the [xcm-tools](https://github.com/Moonsong-Labs/xcm-tools){target=\_blank} repository. This is especially useful when you need to verify where underlying tokens are locked or to fund a parachain’s sovereign account directly.
+
+1. Clone or navigate to the [xcm-tools repository](https://github.com/Moonsong-Labs/xcm-tools){target=\_blank}
+2. Use the `calculate-sovereign-account` script, specifying the - **Parachain ID** with the `--p` flag and the relay chain with the `--r` flag (default is `polkadot`; other accepted values are `kusama` or `moonbase`)
+
+The parachain ID you need can be found on the respective relay chain’s [Polkadot.js Apps Parachains page](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frelay.api.moonbase.moonbeam.network#/parachains){target=\_blank}. The Parachains page can be accessed under the **Network** dropdown.
+
+For example, to calculate the sovereign account address for parachain `1000` on the Moonbase Alpha testnet:
+
+```bash
+yarn calculate-sovereign-account --p 1000 --r moonbase
+```
+
+Running the script will generate output like the following:
+
+--8<-- 'code/builders/interoperability/xcm/core-concepts/sovereign-accounts/terminal/calculate.md'
+
+The relay address is how the Polkadot or Kusama relay chain references the sovereign account. Generic parachain address is typically used for referencing this parachain’s sovereign account from other parachains. The Moonbase Alpha address is the corresponding sovereign account in the H160 EVM address format used by Moonbase Alpha.
+
+## Learn More {: #learn-more }
+
+Sovereign accounts form the backbone of reserve-backed transfers, enabling safe custody of assets for minting wrapped tokens across Polkadot’s ecosystem. By combining sovereign accounts with the XCM framework, parachains can interoperate seamlessly—locking and unlocking assets in a transparent, trust-minimized way. For more information about how sovereign accounts facilitate cross-chain transfers with XCM, be sure to check out the [Send XC-20s section](/builders/interoperability/xcm/xc20/send-xc20s/overview/){target=\_blank}.