More V2 fixes (#1778)

* fix: cover L2→AH path + missing dry-run RefundSurplus + safer envName switch

Three follow-ups to clara/fix-eth-dust-usdt review:

1. transfers/l2ToPolkadot/erc20ToAH.ts: fee() and tx() were untouched in
   the prior PR; the L2 path still trapped USDT. Add the executionFee
   buffer and pass userAssetLocation to sendMessageXCM.

2. xcmbuilders/toPolkadot/pnaToParachain.ts: buildParachainPNAReceivedXcmOnDestination
   (the V4 destination dry-run helper for PNA→parachain) was missing
   RefundSurplus before its DepositAsset, so the dry-run hides BuyExecution
   surplus dust the same way the V5 builders did before fix.

3. xcmBuilder.ts: accountToLocationWithNetwork silently returned undefined
   for unknown envName values (causing decode errors downstream) and was
   missing local_e2e in the AccountKey20 branch. Add default throw and
   the missing case.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fixes

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: claravanstaden

web/packages/api/src/toEthereum_v2.ts

@@ -915,14 +915,20 @@ export async function signAndSendTransfer(
                     console.error(c.toHuman())
                     reject(c.internalError || c.dispatchError || c)
                 }
-                // We have to check for finalization here because re-orgs will produce a different messageId on Asset Hub.
-                // TODO: Change back to isInBlock when we switch to pallet-xcm.execute for Asset Hub and we can generate the messageId offchain.
-                if (c.isFinalized) {
+                // When the messageId is computed off-chain (V2 paths using polkadotXcm.execute
+                // with a SetTopic we control), re-orgs can't change it — resolve on isInBlock to
+                // avoid the ~12–24s finalization wait. The legacy AH path leaves messageId
+                // undefined and must keep waiting for finality to read the event-emitted id.
+                const resolveOnInBlock = transfer.computed.messageId !== undefined
+                if ((resolveOnInBlock && c.isInBlock) || c.isFinalized) {
+                    const blockHash = c.isInBlock
+                        ? c.status.asInBlock.toHex()
+                        : c.status.asFinalized.toHex()
                     const result = {
                         txHash: u8aToHex(c.txHash),
                         txIndex: c.txIndex || 0,
                         blockNumber: Number((c as any).blockNumber),
-                        blockHash: "",
+                        blockHash,
                         events: c.events,
                     }
                     for (const e of c.events) {
@@ -954,7 +960,6 @@ export async function signAndSendTransfer(
         }
     })
 
-    result.blockHash = u8aToHex(await sourceParachain.rpc.chain.getBlockHash(result.blockNumber))
     result.messageId = transfer.computed.messageId ?? result.messageId
 
     return result

web/packages/api/src/transfers/l2ToPolkadot/erc20ToAH.ts

@@ -26,7 +26,11 @@ import {
     buildAssetHubERC20ReceivedXcm,
 } from "../../xcmbuilders/toPolkadot/erc20ToAH"
 import { accountId32Location, erc20Location } from "../../xcmBuilder"
-import { DOT_LOCATION, ETHER_TOKEN_ADDRESS } from "../../assets_v2"
+import {
+    DOT_LOCATION,
+    ETHER_TOKEN_ADDRESS,
+    getAssetHubEtherMinBalance,
+} from "../../assets_v2"
 import { ensureValidationSuccess, padFeeByPercentage } from "../../utils"
 import { resolveBeneficiary } from "../../crypto"
 import { FeeInfo, ValidationLog, ValidationReason } from "../../types/toPolkadot"
@@ -136,6 +140,13 @@ export class ERC20ToAH<T extends EthereumProviderTypes> implements TransferInter
             await assetHubImpl.swapAsset1ForAsset2(DOT_LOCATION, ether, assetHubExecutionFeeDOT),
             feePadPercentage ?? 33n,
         )
+        // For non-ether transfers, oversize executionFee by AH bridged-ether
+        // min_balance: the post-PayFees surplus then naturally lands at the
+        // recipient via RefundSurplus → DepositAsset, satisfying
+        // `Token::BelowMinimum` on a fresh asset account.
+        if (tokenAddress !== ETHER_TOKEN_ADDRESS) {
+            assetHubExecutionFeeEther += getAssetHubEtherMinBalance(registry)
+        }
 
         const { relayerFee, extrinsicFeeDot, extrinsicFeeEther } = await calculateRelayerFee(
             assetHubImpl,
@@ -361,12 +372,18 @@ export class ERC20ToAH<T extends EthereumProviderTypes> implements TransferInter
             accountNonce,
         )
 
+        // For ether transfers there's only one asset in holding so no split is needed.
+        const userAssetLocation =
+            tokenAddress === ETHER_TOKEN_ADDRESS
+                ? undefined
+                : erc20Location(registry.ethChainId, tokenAddress)
         const xcm = hexToU8a(
             sendMessageXCM(
                 assetHub.registry,
                 beneficiaryAddressHex,
                 topic,
                 options?.customXcm,
+                userAssetLocation,
             ).toHex(),
         )
         let claimer = claimerFromBeneficiary(assetHub, beneficiaryAddressHex, registry.environment)

web/packages/api/src/xcmBuilder.ts

@@ -1476,6 +1476,8 @@ export const accountToLocationWithNetwork = (account: string, envName: string) =
                     }
                     break
                 }
+                default:
+                    throw Error(`Unsupported envName: ${envName}`)
             }
             break
         case 2:
@@ -1499,6 +1501,14 @@ export const accountToLocationWithNetwork = (account: string, envName: string) =
                     }
                     break
                 }
+                case "local_e2e": {
+                    beneficiaryLocation = {
+                        accountKey20: { key: hexAddress, network: { Polkadot: { network: null } } },
+                    }
+                    break
+                }
+                default:
+                    throw Error(`Unsupported envName: ${envName}`)
             }
             break
         default:

web/packages/api/src/xcmbuilders/toPolkadot/pnaToParachain.ts

@@ -190,6 +190,10 @@ export function buildParachainPNAReceivedXcmOnDestination(
                 ],
             },
             { clearOrigin: null },
+            // Mirror the user-side `sendMessageXCM` remoteXcm tail: RefundSurplus
+            // returns unused BuyExecution surplus to holding so the dry-run sees
+            // the same dust deposit attempt that production performs.
+            { refundSurplus: null },
             ...(customXcm || []), // Insert custom XCM instructions if provided
             ...buildSplitDepositAsset(beneficiaryLocation, assetLocation, 2),
             { setTopic: topic },

web/packages/operations/package.json

@@ -76,6 +76,8 @@
     "transferWndToPenpalV2": "npx ts-node src/transfer_from_e2p_v2.ts 2000 WND 1000000000",
     "transferUSDCToAHV2": "npx ts-node src/transfer_from_e2p_v2.ts 1000 USDC 100000",
     "transferUSDTToAHV2": "npx ts-node src/transfer_from_e2p_v2.ts 1000 USDT 15000000",
+    "trapUSDTBelowMinBalance": "SKIP_VALIDATION=true npx ts-node src/transfer_from_e2p_v2.ts 1000 USDT 5000",
+    "claimTrap": "npx ts-node src/claim_trap.ts",
     "transferUSDCFromBaseToAH-sepolia": "npx ts-node src/transfer_from_l2_to_polkadot_wrapper.ts 84532 1000 USDC 1000000",
     "transferUSDCFromAHToBase-sepolia": "npx ts-node src/transfer_from_polkadot_to_l2_wrapper.ts 1000 84532 USDC 1000000",
     "transferEtherFromBaseToAH-sepolia": "npx ts-node src/transfer_from_l2_to_polkadot_wrapper.ts 84532 1000 Eth 1000000000000000",

web/packages/operations/src/transfer_to_polkadot_v2.ts

@@ -96,9 +96,15 @@ export const transferToPolkadot = async (
         const validation = await transferImpl.validate(transfer)
         console.log("validation result", validation)
 
-        // Step 4. Check validation logs for errors
+        // Step 4. Check validation logs for errors. SKIP_VALIDATION=true lets
+        // trap-test scripts proceed even when the dry-run correctly fails (e.g.
+        // intentionally sending USDT below min_balance to trigger an asset trap).
         if (!validation.success) {
-            throw Error(`validation has one of more errors.`)
+            if (process.env.SKIP_VALIDATION === "true") {
+                console.warn("validation failed; proceeding anyway (SKIP_VALIDATION=true)")
+            } else {
+                throw Error(`validation has one of more errors.`)
+            }
         }
 
         // Step 5. Estimate the cost of the execution cost of the transaction