Apply suggestions from code review

Co-authored-by: Taylor Lucero <[email protected]>

Author: nhussein11

develop/interoperability/versions/index.md

@@ -8,7 +8,7 @@ template: index-page.html
 
 XCM is a versioned language that evolves to meet the growing needs of cross-chain communication in the Polkadot ecosystem. Understanding XCM versioning is essential for developers building interoperable applications to keep up with the latest improvements.
 
-New versions are defined via [Polkadot Fellowship RFCs](https://github.com/polkadot-fellows/rfcs){target=\_blank}, ensuring each iteration is thoroughly reviewed. The whole of this documentation uses _XCM V5_ as the primary reference, which is the current stable version.
+New versions are defined via [Polkadot Fellowship RFCs](https://github.com/polkadot-fellows/rfcs){target=\_blank}, ensuring each iteration is thoroughly reviewed. This entire documentation uses _XCM V5_ as the primary reference, which is the current stable version.
 
 Each new version introduces new functionality while maintaining backward compatibility where possible. By understanding version differences, you can make informed decisions about which features to use and how to future-proof your applications.
 

develop/interoperability/versions/v5/asset-claimer.md

@@ -11,7 +11,7 @@ XCMv5 introduces the [`AssetClaimer`](https://paritytech.github.io/polkadot-sdk/
 
 When XCM execution failed and assets became trapped:
 
-- **Governance dependency**: Most trapped asset recovery required governance proposals.
+- **Governance dependency**: Most trapped asset recovery requires governance proposals.
 - **Complex procedures**: Manual intervention through referendum processes.
 - **Long delays**: Recovery could take weeks or months through governance.
 - **Risk of loss**: Assets could remain permanently trapped if governance didn't act.
@@ -71,17 +71,17 @@ The `AssetClaimer` hint addresses several critical pain points in trapped asset
 | Feature | Before XCM V5 | After XCM V5 |
 | :-----: | :-----------: | :----------: |
 | **Recovery Speed** | Wait for governance process (weeks/months) | Designated claimer can act immediately |
-| **Governance Burden** | Every trapped asset required a governance proposal | Only complex cases need governance intervention |
+| **Governance Burden** | Every trapped asset requires a governance proposal | Only complex cases need governance intervention |
 | **Recovery Predictability** | Uncertain if governance would approve recovery | Predetermined claimer provides certainty |
-| **Accessibility** | Small amounts often not worth governance overhead | Any amount can be efficiently recovered |
+| **Accessibility** | Small amounts are often not worth governance overhead | Any amount can be efficiently recovered |
 
 ## Best Practices
 
 Following these best practices ensures effective use of the `AssetClaimer` hint and maximizes the benefits of automated asset recovery.
 
 ### Set Hint Early
 
-Always set the asset claimer hint before any operations that might fail, ensuring trapped assets can be recovered immediately without governance intervention.
+Always set the `AssetClaimer` hint before any operations that might fail, ensuring trapped assets can be recovered immediately without governance intervention.
 
 ```typescript
 // Set claimer hint before any risky operations

develop/interoperability/versions/v5/fees.md

@@ -5,7 +5,7 @@ description: Explore the key differences in fee handling between XCM V4 and V5,
 
 # Fees (XCM V4 → XCM V5)
 
-XCM V5 introduces a new fee payment mechanism that simplifies and unifies how fees are handled across different types of XCM operations.
+XCM V5 introduces a new fee payment mechanism that simplifies and unifies the handling of fees across various XCM operations.
 
 ## Key Changes from V4
 
@@ -18,12 +18,12 @@ XCM V5 replaces the [`BuyExecution`](https://paritytech.github.io/polkadot-sdk/m
     - Used `BuyExecution` instruction that handles only execution fees.
     - Leftover assets after buying execution are returned to holding.
     - Required explicit specification of execution weight limits.
-    - Delivery fees might not be found and error out.
+    - Delivery fees may not be found, and an error may occur.
 
 - **XCM V5 Approach:**
 
     - Introduces `PayFees` instruction for unified fee handling.
-    - All assets passed to `PayFees` are kept in a special `fees` register, they are _NOT_ returned to holding.
+    - All assets passed to `PayFees` are kept in a special `fees` register; they are _NOT_ returned to holding.
     - No need to specify weights, only assets.
     - More predictable.
 
@@ -58,8 +58,8 @@ XcmV4Instruction.BuyExecution({
 
 XCM V5 maintains backward compatibility with `BuyExecution` for existing implementations. Both instructions are supported, allowing gradual migration:
 
-- **BuyExecution**: Still supported for compatibility with existing XCM programs
-- **PayFees**: Recommended for new development and simplified fee management
+- **BuyExecution**: Still supported for compatibility with existing XCM programs.
+- **PayFees**: Recommended for new development and simplified fee management.
 
 ## Migration Considerations
 
@@ -71,13 +71,13 @@ When migrating from XCM V4 to XCM V5:
 - No breaking changes to existing functionality.
 
 When using `PayFees`, keep in mind that _ALL_ assets passed to the instruction will be entirely dedicated to fees, not returned to holding.
-That's why it's more important than before to [properly estimate XCM fees](/develop/interoperability/xcm-runtime-apis/){target=\_blank}.
+That's why it's more important than before to [to estimate XCM fees properly](/develop/interoperability/xcm-runtime-apis/){target=\_blank}.
 
 ## `RefundSurplus` Instruction
 
 When you overestimate fees with [`PayFees`](https://paritytech.github.io/polkadot-sdk/master/staging_xcm/v5/enum.Instruction.html#variant.PayFees){target=\_blank}, you can recover unused funds using the [`RefundSurplus`](https://paritytech.github.io/polkadot-sdk/master/staging_xcm/v5/enum.Instruction.html#variant.RefundSurplus){target=\_blank} instruction.
 
-You can use `RefundSurplus` to put the leftover fees back into holding. This is useful when you've overestimated the fees needed for your XCM program. You can then deposit them to some account with [`DepositAsset`](https://paritytech.github.io/polkadot-sdk/master/staging_xcm/v5/enum.Instruction.html#variant.DepositAsset){target=\_blank}.
+You can use `RefundSurplus` to put the leftover fees back into holding. This is useful when you've overestimated the fees needed for your XCM program. You can then deposit them into some account with [`DepositAsset`](https://paritytech.github.io/polkadot-sdk/master/staging_xcm/v5/enum.Instruction.html#variant.DepositAsset){target=\_blank}.
 
 ```typescript
 // After all instructions that send messages.

develop/interoperability/versions/v5/index.md

@@ -26,9 +26,9 @@ Version 5 addresses key pain points that developers faced in previous versions:
 - **Before XCM V5**
     - Cross-chain transfers were limited to only one transfer type, requiring multiple different XCMs to send the entirety of the tokens.
     - Fee management across multiple hops was extremely complicated to get right, particularly because of delivery fees.
-    - Cross-chain transfers cleared the origin, making it impossible to [`Transact`](https://paritytech.github.io/polkadot-sdk/master/staging_xcm/v4/enum.Instruction.html#variant.Transact) in the same XCM as a transfer.
+    - Cross-chain transfers cleared the origin, making it impossible to [`Transact`](https://paritytech.github.io/polkadot-sdk/master/staging_xcm/v4/enum.Instruction.html#variant.Transact){target=\_blank} in the same XCM as a transfer.
     - Claiming trapped assets when transfers failed was troublesome, most of the time requiring governance to intervene.
-    - Having to specify the weight for `Transact` was really brittle.
+    - Having to specify the weight for `Transact` was brittle.
 - **After XCM V5**
     - A unified cross-chain transfer instruction handles all possible transfer types and allows multiple ones in the same XCM.
     - The fee payment mechanism has been standardized to handle multiple types of fees, making fees much more predictable.

develop/interoperability/versions/v5/migration-guide.md

@@ -15,9 +15,9 @@ Whether migration is possible depends mainly on if the target chains have alread
 
 To determine whether a chain supports XCM V5:
 
-- Read the changelog
-- Explore the metadata with PAPI's descriptors
-- Explore the metadata with a tool like [subwasm](https://github.com/chevdor/subwasm){target=\_blank}
+- Read the changelog.
+- Explore the metadata with PAPI's descriptors.
+- Explore the metadata with a tool like [subwasm](https://github.com/chevdor/subwasm){target=\_blank}.
 
 For example, when generating PAPI descriptors for a chain, you can check if the `XcmVersionedXcm` known type has the V5 variant.
 
@@ -27,7 +27,7 @@ npx papi add myChain -w <INSERT_RPC_WEB_SOCKET_ENDPOINT>
 
 Ensure to replace the `<INSERT_RPC_WEB_SOCKET_ENDPOINT>` with the actual RPC web socket endpoint of the chain.
 
-Alternatively, you can navigate to the [PAPI developer console](https://dev.papi.how/extrinsics){target=\_blank}, connect to the chain and under extrinsics choose `PolkadotXcm -> execute` and check for the V5 variant:
+Alternatively, you can navigate to the [PAPI developer console](https://dev.papi.how/extrinsics){target=\_blank}, connect to the chain, and under extrinsics choose `PolkadotXcm -> execute` and check for the V5 variant:
 
 ![](/images/develop/interoperability/versions/v5/migration-guide/check-xcm-version.webp)
 
@@ -65,9 +65,9 @@ With XCM V5, the ecosystem is shifting toward writing XCM programs directly inst
 
 Migration Impact:
 
-- More verbose but significantly more flexible
-- Need to calculate weights using runtime APIs
-- Better control over execution flow
+- More verbose but significantly more flexible.
+- Need to calculate weights using runtime APIs.
+- Better control over execution flow.
 
 !!! note "Is this `execute` new?"
 
@@ -93,8 +93,8 @@ const result = await tx.signAndSubmit(signer);
 
 !!! note "Are the extrinsics going away?"
 
-    No! The extrinsics will continue to be supported in the XCM pallet for an undefined period of time. Although, it is expected that as more chains support XCM V5 and more dApp developers use [execute](https://paritytech.github.io/polkadot-sdk/master/pallet_xcm/pallet/struct.Pallet.html#method.execute){target=\_blank},
-    they'll reap the benefits and not require the extrinsics anymore.
+    No! The extrinsics will continue to be supported in the XCM pallet for an undefined period of time. Although it is expected that as more chains support XCM V5 and more dApp developers use [execute](https://paritytech.github.io/polkadot-sdk/master/pallet_xcm/pallet/struct.Pallet.html#method.execute){target=\_blank},
+    they'll reap the benefits and no longer require extrinsics.
 
 ### Unified Transfer Instructions
 
@@ -135,7 +135,7 @@ Beyond the shift to direct XCM execution, XCM V5 also consolidates transfer oper
 
 Migration Benefits:
 
-- Mix different transfer types in single operation
+- Different transfer types in single operation
 - Clearer fee handling
 - Origin preservation option
 
@@ -191,16 +191,16 @@ XcmV4Instruction.BuyExecution({
 });
 ```
 
-The new `PayFees` instruction just has the asset for fee payment. The `weight_limit` parameter has historically mostly been set to `Unlimited` because of the difficulty to estimate weight and the fees being sufficient for limiting the max execution cost.
+The new `PayFees` instruction just has the asset for fee payment. The `weight_limit` parameter has historically been set to `Unlimited` due to the difficulty in estimating weight and the fees being sufficient to limit the maximum execution cost.
 
 There is another key difference between `PayFees` and `BuyExecution`:
 
 - With `BuyExecution`, if too much was supplied for fees, the leftover after paying for execution would be returned to the [holding register](https://paritytech.github.io/polkadot-sdk/master/staging_xcm_executor/struct.XcmExecutor.html#method.holding) to be used in the rest of the XCM.
-- With `PayFees`, the full amount put into `assets` is stored in the fees register, nothing is returned to the holding register.
+- With `PayFees`, the full amount put into `assets` is stored in the fees register; nothing is returned to the holding register.
 
 This means the full amount intended for fee payment must be specified. It makes it much more predictable. For example, withdrawing 11 DOT with 1 DOT in `PayFees` ensures exactly 10 DOT is sent.
 
-The reason for this is the introduction of **delivery fees**, which are charged in addition to **execution fees**. Delivery fees are charged the moment an instruction is encountered which results in sending a new XCM. That's why fees can't be returned to the holding register as before; they need to be kept in the new fees register.
+The reason for this is the introduction of **delivery fees**, which are charged in addition to **execution fees**. Delivery fees are charged the moment an instruction is encountered that results in sending a new XCM. That's why fees can't be returned to the holding register as before; they need to be kept in the new fees register.
 
 !!! note "Is BuyExecution going away?"
 
@@ -307,7 +307,7 @@ This example shows how XCM V5 enables combining multiple asset transfers with di
 
 ### `fallback_max_weight` in `Transact`
 
-The `Transact` instruction has changed in XCM V5 to reduce chances of bugs when executing calls on remote chains.
+The `Transact` instruction has been updated in XCM V5 to reduce the likelihood of bugs when executing calls on remote chains.
 
 The `Transact` instruction looked like this in XCM V4:
 
@@ -349,7 +349,7 @@ This change makes `Transact` more reliable and reduces the maintenance burden of
 
 This change affects how testnet networks are referenced in XCM.
 
-The network IDs, used in the `GlobalConsensus` junction, for `Rococo` and `Westend` were removed. Instead, the generic `ByGenesis` network ID should be used for referencing testnets. This change was made because testnets come and go, as was shown by the [removal of Rococo](https://forum.polkadot.network/t/rococo-to-be-deprecated-in-october/8702) and [appearance of Paseo](https://forum.polkadot.network/t/the-new-polkadot-community-testnet/4956). From now on, only mainnets will have an explicit network ID, testnets should always be referenced with `ByGenesis`.
+The network IDs, used in the `GlobalConsensus` junction, for `Rococo` and `Westend` were removed. Instead, the generic `ByGenesis` network ID should be used for referencing testnets. This change was made because testnets come and go, as was shown by the [removal of Rococo](https://forum.polkadot.network/t/rococo-to-be-deprecated-in-october/8702) and [appearance of Paseo](https://forum.polkadot.network/t/the-new-polkadot-community-testnet/4956). From now on, only mainnets will have an explicit network ID; testnets should always be referenced with `ByGenesis`.
 
 If storing these network IDs, they must be migrated to `ByGenesis`. These are the genesis hashes for the migration:
 

develop/interoperability/versions/v5/transact.md

@@ -84,7 +84,7 @@ Use `fallback_max_weight: { ref_time: ..., proof_size: ... }` when:
 The previous mandatory weight specification created:
 
 - **Brittle implementations**: Weight requirements changed with runtime upgrades.
-- **Over/under-estimation**: Incorrect weight estimates led to failures or waste.
+- **Over/under-estimation**: Incorrect weight estimates that led to failures or waste.
 - **Maintenance overhead**: Constant monitoring and updates required.
 
 ### XCM V5 Improvements

develop/interoperability/versions/v5/transfers.md

@@ -70,9 +70,9 @@ The new `preserve_origin` parameter enables:
 
 !!! note "Important"
 
-    Origin preservation requires specific configuration on the destination chain.
+    Origin preservation requires a specific configuration on the destination chain.
     If the destination chain doesn't support it, transfers with `preserve_origin: true` will fail.
-    Setting `preserve_origin: false` will work as before, regardless of destination chain configuration.
+    Setting `preserve_origin: false` will continue to work as before, regardless of the destination chain configuration.
 
 ### Integrated Fee Handling
 

develop/interoperability/versions/v5/writing-xcm-programs.md

@@ -61,4 +61,4 @@ api.tx.PolkadotXcm.claimAssets(...)
 - Existing dedicated extrinsics continue to work.
 - No breaking changes to existing programs.
 - New development should prefer `execute()` for better flexibility.
-- Gradual migration path available for existing applications.
+- A gradual migration path is available for existing applications.

develop/interoperability/xcm-guides/from-apps/claiming-trapped-assets.md

@@ -7,18 +7,17 @@ description: How to claim assets that become trapped on-chain due to an XCM exec
 
 ## Introduction
 
-When XCM execution fails or succeeds, leftover assets can become "trapped" on the destination chain. These assets are held by the system but not accessible through normal means. XCM provides mechanisms to claim these trapped assets and recover them.
+When XCM execution fails or succeeds, leftover assets can become "trapped" on the destination chain. These assets are held by the system but are not accessible through normal means. XCM provides mechanisms to claim these trapped assets and recover them.
 This guide details the process and required steps to claim trapped assets.
 
 ## Trapped Assets Causes
 
 Assets become trapped whenever execution halts and there are leftover assets. This can happen for example if:
 
-- An XCM execution throws an error in any instruction when assets are in holding:
+- An XCM execution throws an error in any instruction when assets are in holding such as:
     - `DepositAsset` can't deposit because the account doesn't exist.
     - `Transact` can't execute the call because it doesn't exist.
     - `PayFees` not enough funds or not paying enough for execution.
-    - and others.
 
 - XCM execution finishes successfully but not all assets were deposited:
     - Funds were withdrawn but some were not deposited.
@@ -216,10 +215,10 @@ This allows this other `SS58_ACCOUNT` to claim the trapped assets. This could al
 
 ## Best practices
 
-1. **Always set a claimer**: Include `SetAssetClaimer` in XCMs with valuable assets
-2. **Use accessible locations**: Ensure the claimer location is controlled by someone who can act
-3. **Monitor for failures**: Track XCM execution to detect when claiming is needed
-4. **Test claiming flows**: Verify your claiming logic works in test environments
-5. **Document recovery procedures**: Maintain clear instructions for asset recovery
+1. **Always set a claimer**: Include `SetAssetClaimer` in XCMs with valuable assets.
+2. **Use accessible locations**: Ensure the claimer location is controlled by someone who can act.
+3. **Monitor for failures**: Track XCM execution to detect when claiming is needed.
+4. **Test claiming flows**: Verify your claiming logic works in test environments.
+5. **Document recovery procedures**: Maintain clear instructions for asset recovery.
 
 Setting a custom asset claimer is a good practice for recovering trapped assets without the need for governance intervention.

develop/interoperability/xcm-guides/from-apps/fees.md

@@ -15,7 +15,7 @@ There are two main types of fees in XCM: [execution](#execution) and [delivery](
 
 ## Execution
 
-All XCMs have a weight associated to them. Each XCM instruction is benchmarked for a particular system (blockchain), which assigns them a weight. The weight of an XCM is the sum of the weight of all instructions. It's important to correctly benchmark this with the worst case so that your system is safe from [Denial-of-Service (DoS)](https://en.wikipedia.org/wiki/Denial-of-service_attack){target=\_blank} attacks.
+All XCMs have a weight associated with them. Each XCM instruction is benchmarked for a particular system (blockchain), which assigns them a weight. The weight of an XCM is the sum of the weight of all instructions. It's important to correctly benchmark this with the worst case so that your system is safe from [Denial-of-Service (DoS)](https://en.wikipedia.org/wiki/Denial-of-service_attack){target=\_blank} attacks.
 
 This generated weight represents how much time, and space, is needed for executing the XCM. It directly translates to _execution fees_.
 
@@ -62,10 +62,10 @@ flowchart LR
 ```
 
 - Execution fees need to be paid on A.
-- Delivery fees from A to B.
-- Execution on B.
+- Delivery fees need to be paid from A to B.
+- Execution occurs on B.
 - Delivery from B to C.
-- Finally, execution on C.
+- Execution occurs on C.
 
 An XCM that does this might look like so: