address feedback

Author: franciscoaguirre

.snippets/code/develop/interoperability/versions/v5/teleport-and-transact.ts

@@ -1,4 +1,4 @@
-// `ahp` is the name we gave to `npx papi add`
+// `ahp` is the name given to `npx papi add`
 import {
   ahp,
   people,
@@ -15,7 +15,7 @@ import {
 } from "@polkadot-api/descriptors";
 import { Binary, createClient, Enum, FixedSizeBinary } from "polkadot-api";
 // import from "polkadot-api/ws-provider/node"
-// if you are running in a NodeJS environment
+// if running in a NodeJS environment
 import { getWsProvider } from "polkadot-api/ws-provider/web";
 import { withPolkadotSdkCompat } from "polkadot-api/polkadot-sdk-compat";
 import { sr25519CreateDerive } from "@polkadot-labs/hdkd";
@@ -39,12 +39,12 @@ const polkadotSigner = getPolkadotSigner(
 );
 
 // Connect to Polkadot Asset Hub.
-// Pointing to localhost since we're using chopsticks in this example.
+// Pointing to localhost since this example uses chopsticks.
 const client = createClient(
   withPolkadotSdkCompat(getWsProvider("ws://localhost:8000")),
 );
 
-// We get the typed api, a typesafe API for interacting with the chain.
+// Get the typed API, a typesafe API for interacting with the chain.
 const ahpApi = client.getTypedApi(ahp);
 
 const PEOPLE_PARA_ID = 1004;
@@ -57,12 +57,12 @@ const DOT = {
 // DOT has 10 decimals.
 const DOT_UNITS = 10_000_000_000n;
 
-// This is the DOT we withdraw to both pay for fees and send.
+// The DOT to withdraw for both fees and transfer.
 const dotToWithdraw = {
   id: DOT,
   fun: XcmV3MultiassetFungibility.Fungible(10n * DOT_UNITS),
 };
-// This is the DOT we use to pay for fees locally.
+// The DOT to use for local fee payment.
 const dotToPayFees = {
   id: DOT,
   fun: XcmV3MultiassetFungibility.Fungible(1n * DOT_UNITS),
@@ -72,10 +72,10 @@ const destination = {
   parents: 1,
   interior: XcmV3Junctions.X1(XcmV3Junction.Parachain(PEOPLE_PARA_ID)),
 };
-// We'll pay for fees in the People Chain with teleported DOT.
+// Pay for fees on the People Chain with teleported DOT.
 // This is specified independently of the transferred assets since they're used
-// exclusively for fees. Also because we can decide to pay fees in a different
-// asset from all that we're transferring.
+// exclusively for fees. Also because fees can be paid in a different
+// asset from the transferred assets.
 const remoteFees = Enum(
   "Teleport",
   XcmV5AssetFilter.Definite([
@@ -87,9 +87,9 @@ const remoteFees = Enum(
 );
 // No need to preserve origin for this example.
 const preserveOrigin = false;
-// The assets we want to transfer are whatever's left in the
+// The assets to transfer are whatever remains in the
 // holding register at the time of executing the `InitiateTransfer`
-// instruction. DOT in this case. We teleport it.
+// instruction. DOT in this case, teleported.
 const assets = [
   Enum("Teleport", XcmV5AssetFilter.Wild(XcmV5WildAsset.AllCounted(1))),
 ];
@@ -99,8 +99,8 @@ const assets = [
 const beneficiary = FixedSizeBinary.fromBytes(keyPair.publicKey);
 // The call to be executed on the destination chain.
 // It's a simple remark with an event.
-// We create the call on Asset Hub since the system pallet is present in
-// every runtime, but if using any other pallet, you should connect to
+// Create the call on Asset Hub since the system pallet is present in
+// every runtime, but if using any other pallet, connect to
 // the destination chain and create the call there.
 const remark = Binary.fromText("Hello, cross-chain!");
 const call = await ahpApi.tx.System.remark_with_event({ remark }).getEncodedData();
@@ -127,7 +127,7 @@ const remoteXcm = [
   }),
 ];
 
-// The message is just assembling all of these parameters we've defined before.
+// The message assembles all the previously defined parameters.
 const xcm = XcmVersionedXcm.V5([
   XcmV5Instruction.WithdrawAsset([dotToWithdraw]),
   XcmV5Instruction.PayFees({ asset: dotToPayFees }),
@@ -138,9 +138,25 @@ const xcm = XcmVersionedXcm.V5([
     assets,
     remote_xcm: remoteXcm,
   }),
+  // Return any leftover fees from the fees register back to holding.
+  XcmV5Instruction.RefundSurplus(),
+  // Deposit remaining assets (refunded fees) to the originating account.
+  // Using AllCounted(1) since only one asset type (DOT) remains - a minor optimization.
+  XcmV5Instruction.DepositAsset({
+    assets: XcmV5AssetFilter.Wild(XcmV5WildAsset.AllCounted(1)),
+    beneficiary: {
+      parents: 0,
+      interior: XcmV5Junctions.X1(
+        XcmV5Junction.AccountId32({
+          id: beneficiary, // The originating account.
+          network: undefined,
+        }),
+      ),
+    },
+  }),
 ]);
 
-// We need to know the weight of the XCM to set the `max_weight` parameter
+// The XCM weight is needed to set the `max_weight` parameter
 // on the actual `PolkadotXcm.execute()` call.
 const weightResult = await ahpApi.apis.XcmPaymentApi.query_xcm_weight(xcm);
 
@@ -151,14 +167,14 @@ if (weightResult.success) {
 
   console.dir(weight);
 
-  // The actual transaction we will submit.
+  // The actual transaction to submit.
   // This tells Asset Hub to execute the XCM.
   const tx = ahpApi.tx.PolkadotXcm.execute({
     message: xcm,
     max_weight: weight,
   });
 
-  // We sign it and propagate it to the network.
+  // Sign and propagate to the network.
   const result = await tx.signAndSubmit(polkadotSigner);
   console.log(stringify(result));
 }

.snippets/code/develop/interoperability/versions/v5/teleport.ts

@@ -1,4 +1,4 @@
-// `ahp` is the name we gave to `npx papi add`
+// `ahp` is the name given to `npx papi add`
 import {
   ahp,
   XcmV3Junction,
@@ -13,7 +13,7 @@ import {
 } from "@polkadot-api/descriptors";
 import { createClient, Enum, FixedSizeBinary } from "polkadot-api";
 // import from "polkadot-api/ws-provider/node"
-// if you are running in a NodeJS environment
+// if running in a NodeJS environment
 import { getWsProvider } from "polkadot-api/ws-provider/web";
 import { withPolkadotSdkCompat } from "polkadot-api/polkadot-sdk-compat";
 import { sr25519CreateDerive } from "@polkadot-labs/hdkd";
@@ -36,12 +36,12 @@ const polkadotSigner = getPolkadotSigner(
 );
 
 // Connect to Polkadot Asset Hub.
-// Pointing to localhost since we're using chopsticks in this example.
+// Pointing to localhost since this example uses chopsticks.
 const client = createClient(
   withPolkadotSdkCompat(getWsProvider("ws://localhost:8000")),
 );
 
-// We get the typed api, a typesafe API for interacting with the chain.
+// Get the typed API, a typesafe API for interacting with the chain.
 const ahpApi = client.getTypedApi(ahp);
 
 const PEOPLE_PARA_ID = 1004;
@@ -54,12 +54,12 @@ const DOT = {
 // DOT has 10 decimals.
 const DOT_UNITS = 10_000_000_000n;
 
-// This is the DOT we withdraw to both pay for fees and send.
+// The DOT to withdraw for both fees and transfer.
 const dotToWithdraw = {
   id: DOT,
   fun: XcmV3MultiassetFungibility.Fungible(10n * DOT_UNITS),
 };
-// This is the DOT we use to pay for fees locally.
+// The DOT to use for local fee payment.
 const dotToPayFees = {
   id: DOT,
   fun: XcmV3MultiassetFungibility.Fungible(1n * DOT_UNITS),
@@ -69,10 +69,10 @@ const destination = {
   parents: 1,
   interior: XcmV3Junctions.X1(XcmV3Junction.Parachain(PEOPLE_PARA_ID)),
 };
-// We'll pay for fees in the People Chain with teleported DOT.
+// Pay for fees on the People Chain with teleported DOT.
 // This is specified independently of the transferred assets since they're used
-// exclusively for fees. Also because we can decide to pay fees in a different
-// asset from all that we're transferring.
+// exclusively for fees. Also because fees can be paid in a different
+// asset from the transferred assets.
 const remoteFees = Enum(
   "Teleport",
   XcmV5AssetFilter.Definite([
@@ -84,9 +84,9 @@ const remoteFees = Enum(
 );
 // No need to preserve origin for this example.
 const preserveOrigin = false;
-// The assets we want to transfer are whatever's left in the
+// The assets to transfer are whatever remains in the
 // holding register at the time of executing the `InitiateTransfer`
-// instruction. DOT in this case. We teleport it.
+// instruction. DOT in this case, teleported.
 const assets = [
   Enum("Teleport", XcmV5AssetFilter.Wild(XcmV5WildAsset.AllCounted(1))),
 ];
@@ -111,7 +111,7 @@ const remoteXcm = [
   }),
 ];
 
-// The message is just assembling all of these parameters we've defined before.
+// The message assembles all the previously defined parameters.
 const xcm = XcmVersionedXcm.V5([
   XcmV5Instruction.WithdrawAsset([dotToWithdraw]),
   XcmV5Instruction.PayFees({ asset: dotToPayFees }),
@@ -122,9 +122,25 @@ const xcm = XcmVersionedXcm.V5([
     assets,
     remote_xcm: remoteXcm,
   }),
+  // Return any leftover fees from the fees register back to holding.
+  XcmV5Instruction.RefundSurplus(),
+  // Deposit remaining assets (refunded fees) to the originating account.
+  // Using AllCounted(1) since only one asset type (DOT) remains - a minor optimization.
+  XcmV5Instruction.DepositAsset({
+    assets: XcmV5AssetFilter.Wild(XcmV5WildAsset.AllCounted(1)),
+    beneficiary: {
+      parents: 0,
+      interior: XcmV5Junctions.X1(
+        XcmV5Junction.AccountId32({
+          id: beneficiary, // The originating account.
+          network: undefined,
+        }),
+      ),
+    },
+  }),
 ]);
 
-// We need to know the weight of the XCM to set the `max_weight` parameter
+// The XCM weight is needed to set the `max_weight` parameter
 // on the actual `PolkadotXcm.execute()` call.
 const weightResult = await ahpApi.apis.XcmPaymentApi.query_xcm_weight(xcm);
 
@@ -135,14 +151,14 @@ if (weightResult.success) {
 
   console.dir(weight);
 
-  // The actual transaction we will submit.
+  // The actual transaction to submit.
   // This tells Asset Hub to execute the XCM.
   const tx = ahpApi.tx.PolkadotXcm.execute({
     message: xcm,
     max_weight: weight,
   });
 
-  // We sign it and propagate it to the network.
+  // Sign and propagate to the network.
   const result = await tx.signAndSubmit(polkadotSigner);
   console.log(stringify(result));
 }

develop/interoperability/fundamentals/.pages

@@ -0,0 +1,3 @@
+title: Fundamentals
+nav:
+  - index.md

develop/interoperability/fundamentals/index.md

@@ -0,0 +1,3 @@
+# Fundamentals
+
+This section covers the fundamentals of XCM.

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

@@ -15,18 +15,18 @@ 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
-  - `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
-  - or others...
+    - `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
-  - `Transact` overestimated the weight and `RefundSurplus` got some funds into holding that were never deposited
-  - Fees in `PayFees` were overestimated and some were kept there until the end
+    - Funds were withdrawn but some were not deposited
+    - `Transact` overestimated the weight and `RefundSurplus` got some funds into holding that were never deposited
+    - Fees in `PayFees` were overestimated and some were kept there until the end
 
 ## The ClaimAsset instruction
 
-The `ClaimAsset` instruction allows retriving assets trapped on a chain:
+The [`ClaimAsset`](https://paritytech.github.io/polkadot-sdk/master/xcm/v5/instruction/enum.Instruction.html#variant.ClaimAsset){target=\_blank} instruction allows retrieving assets trapped on a chain:
 
 ```typescript
 XcmV5Instruction.ClaimAsset({
@@ -48,7 +48,7 @@ in the `AssetsTrapped` event.
 
 When assets are trapped you'll see the `AssetsTrapped` event:
 
-![AssetsTrapped event on Subscan](../../../images/develop/interoperability/assets-trapped-event.png)
+![AssetsTrapped event on Subscan](/images/develop/interoperability/assets-trapped-event.png)
 
 To claim these assets, a message like the following needs to be sent from the origin:
 
@@ -75,6 +75,8 @@ const claimAssetsXcm = XcmVersionedXcm.V5([
 ]);
 ```
 
+Note that this example uses the claimed USDC assets to pay for the execution fees of the claiming message. If the trapped asset cannot be used for fee payment on the destination chain, you need a different approach: first `WithdrawAsset` (with fee-eligible assets), then `PayFees`, then `ClaimAsset`, and finally `DepositAsset`.
+
 In this case, the origin is a local account so the `execute()` transaction needs to be submitted by that same account.
 The origin could be another chain, in which case the governance of that chain would need to get involved, or an account on another chain,
 in which case the `execute()` transaction would need to be submitted on that other chain and a message sent to the chain with trapped funds.
@@ -131,7 +133,7 @@ const failingXcm = XcmVersionedXcm.V5([
       fun: XcmV3MultiassetFungibility.Fungible(1_000_000_000n),
     },
   }),
-  // Explicitly trap. We could also not do anything and the assets would still get trapped.
+  // Explicitly trap. Alternatively, doing nothing would still result in the assets getting trapped.
   XcmV5Instruction.Trap(0n),
 ]);
 ```

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

@@ -8,6 +8,9 @@ description: How to handle fees in XCM.
 In blockchain systems, fees are crucial.
 They prevent malicious actors from exhausting the results of the network, making such attacks expensive.
 The XCM subsystem has its own way of dealing with fees, flexible enough to allow feeless execution in situations that warrant it.
+
+It's important to distinguish between **transaction fees** and **XCM fees**. Transaction fees are paid when submitting extrinsics to a blockchain. XCM fees, on the other hand, are charged for processing XCM instructions and consist of execution fees (computational costs) and delivery fees (message transport costs). While a transaction can include XCM fees, as happens with `palletXcm.execute()`, they are separate fee systems. When a chain receives and processes an XCM message, it charges XCM fees but no transaction fees, since no extrinsic is being submitted.
+
 There are two main types of fees in XCM: **execution** and **delivery**.
 
 ## Execution
@@ -38,7 +41,7 @@ The amount is specified using the `PayFees` instruction:
 XcmV5Instruction.PayFees({
   asset: {
     id: // Asset id.
-    fun: // Fungibility. You specify the amount if it's fungible or the instance if it's an NFT.
+    fun: // Fungibility. Specify the amount if fungible or the instance if NFT.
   },
 })
 ```
@@ -47,13 +50,19 @@ This mechanism is simple and flexible.
 The user requires no knowledge of the different types of fees.
 New fees might arise in the future and they'll be taken using this same mechanism, without the need for any modification.
 
+Which assets can be used for fee payment depends on the destination chain's configuration. For example, on Asset Hub, fees can be paid with any asset that has a liquidity pool with DOT, allowing the chain to automatically convert the fee asset to DOT for actual fee payment. Other chains may have different fee payment policies, so it's important to understand the specific requirements of the destination chain before selecting fee assets.
+
+??? note "Sufficient assets vs fee payment assets"
+
+    It's important to distinguish between "sufficient" assets and assets eligible for fee payment. Sufficient assets can be used to satisfy the Existential Deposit requirement for account creation and maintenance, but this doesn't automatically make them eligible for fee payment. While sufficient assets are generally also usable for fee payment, this isn't guaranteed and depends on the chain's specific configuration. The terms are related but serve different purposes in system.
+
 ## Estimations
 
 The entirety of the asset passed to `PayFees` will be taken from the effective assets and used only for fees.
 This means if you overestimate the fees required, you'll be losing efficiency.
 
 It's necessary to have a mechanism to accurately estimate the fee needed so it can be put into `PayFees`.
-This is more complicated than it sounds since we're dealing with execution and delivery fees, potentially in multiple hops.
+This is more complicated than it sounds since the process involves execution and delivery fees, potentially in multiple hops.
 
 Imagine a scenario where parachain A sends a message to B which forwards another message to C.
 
@@ -90,8 +99,7 @@ const xcm = XcmVersionedXcm.V5([
 ])
 ```
 
-NOTE: paying fees on a remote system is so common that the `InitiateTransfer` instruction doesn't
-require putting the instruction in `remote_xcm`, you only need to put them in `remote_fees`.
+Paying fees on a remote system is so common that the `InitiateTransfer` instruction provides the `remote_fees` parameter for this purpose. When `remote_fees` is specified, it automatically generates a `PayFees` instruction on the destination chain using the specified fees, eliminating the need to manually add `PayFees` to the `remote_xcm` parameter.
 
 <!-- TODO: Fee estimation tutorial? -->
-The solution is to use the [runtime APIs](/develop/interoperability/xcm-runtime-apis/) as shown in [the fee estimation tutorial]().
+The solution is to use the [runtime APIs](/develop/interoperability/xcm-runtime-apis/) as shown in [the fee estimation tutorial]().

develop/interoperability/guides/from-apps/papi/transact.md

@@ -25,9 +25,9 @@ XcmV5Instruction.Transact({
 
 - **`origin_kind`**: Specifies how the origin should be interpreted on the destination chain:
 
-  - `SovereignAccount`: Execute as the sovereign account of the origin
-  - `Superuser`: Execute with root privileges (requires special configuration)
-  - `Xcm`: Execute as a generic XCM origin
+  - [`SovereignAccount`](https://paritytech.github.io/polkadot-sdk/master/xcm/v2/enum.OriginKind.html#variant.SovereignAccount){target=\_blank}: Execute as the sovereign account of the origin
+  - [`Superuser`](https://paritytech.github.io/polkadot-sdk/master/xcm/v2/enum.OriginKind.html#variant.Superuser){target=\_blank}: Execute with root privileges (requires special configuration)
+  - [`Xcm`](https://paritytech.github.io/polkadot-sdk/master/xcm/v2/enum.OriginKind.html#variant.Xcm){target=\_blank}: Execute as a generic XCM origin
 
 - **`fallback_max_weight`**: Optional weight limit for execution:
 
@@ -38,7 +38,7 @@ XcmV5Instruction.Transact({
 
 Unlike other XCM instructions like `DepositAsset` or `WithdrawAsset` which are generic, `Transact` requires detailed knowledge of the destination chain:
 
-### What you need to know
+### Required Knowledge
 
 1. **Runtime metadata**: The specific pallets, calls, and their parameters available on the destination chain
 2. **Call encoding**: How to properly encode the call data for the destination runtime