@pushchain/core 5.1.15 → 5.1.16

package/src/lib/orchestrator/internals/push-chain-tx.js

@@ -17,28 +17,9 @@ const chain_1 = require("../../constants/chain");
 const enums_1 = require("../../constants/enums");
 const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
 const context_1 = require("./context");
-// ============================================================================
-// PushChainExecutionError
-// ============================================================================
-/**
- * Typed error for Route 1 Push Chain tx failures. Thrown by
- * `extractPcTxAndTransform` when the final pcTx commits with `status === 'FAILED'`,
- * and surfaced as `SEND_TX_199_02` on the live stream. The readonly `code`
- * discriminator lets callers classify via `instanceof PushChainExecutionError`
- * instead of sniffing error messages.
- *
- * Carries the origin-chain gateway tx hash. There is no successful Push Chain
- * tx to reference on this path — by definition the pcTx committed `FAILED`.
- */
-class PushChainExecutionError extends Error {
-    constructor(message, opts = {}) {
-        super(message);
-        this.code = 'PUSH_CHAIN_EXECUTION_FAILED';
-        this.name = 'PushChainExecutionError';
-        this.gatewayTxHash = opts.gatewayTxHash;
-    }
-}
-exports.PushChainExecutionError = PushChainExecutionError;
+const error_decoder_1 = require("./error-decoder");
+const errors_1 = require("./errors");
+Object.defineProperty(exports, "PushChainExecutionError", { enumerable: true, get: function () { return errors_1.PushChainExecutionError; } });
 // ============================================================================
 // sendPushTx
 // ============================================================================
@@ -167,7 +148,7 @@ const SEQ_RETRY_BASE_DELAY_MS = 400;
  */
 function sendUniversalTx(ctx, isUEADeployed, feeLockTxHash, universalPayload, verificationData, eventBuffer, transformFn, resignFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e;
         const { chain, address } = ctx.universalSigner.account;
         const { vm, chainId } = chain_1.CHAIN_INFO[chain];
         const universalAccountId = {
@@ -241,24 +222,55 @@ function sendUniversalTx(ctx, isUEADeployed, feeLockTxHash, universalPayload, ve
                 var _a;
                 return (_a = e.attributes) === null || _a === void 0 ? void 0 : _a.filter((attr) => attr.key === 'ethereumTxHash').map((attr) => attr.value);
             })) !== null && _b !== void 0 ? _b : [];
+            // Decode known revert selectors (e.g. `ret 0xacfdb444`) from the cosmos
+            // rawLog so the consumer-facing error AND the diagnostic failureSummary
+            // log carry an actionable hint instead of raw 4-byte hex. Mirrors the
+            // wiring in `extractPcTxAndTransform` for the post-success `pcTx FAILED`
+            // path. Also feeds the structured `decodedError` payload through to the
+            // terminal hook (199-02 / 299-02 / 399-02 / 999-02).
+            let augmentedMessage = (_c = tx.rawLog) !== null && _c !== void 0 ? _c : '';
+            let decodedForPayload;
+            const decoded = (0, error_decoder_1.decodeRevert)(augmentedMessage);
+            if ((decoded === null || decoded === void 0 ? void 0 : decoded.kind) === 'custom') {
+                augmentedMessage = `${augmentedMessage} [${decoded.name}: ${decoded.hint}]`;
+                decodedForPayload = {
+                    name: decoded.name,
+                    hint: decoded.hint,
+                    selector: decoded.selector,
+                };
+            }
+            else if ((decoded === null || decoded === void 0 ? void 0 : decoded.kind) === 'string') {
+                augmentedMessage = `${augmentedMessage} [Error(string): "${decoded.decoded}"]`;
+                decodedForPayload = {
+                    decoded: decoded.decoded,
+                    selector: decoded.selector,
+                };
+            }
+            else if ((decoded === null || decoded === void 0 ? void 0 : decoded.kind) === 'unknown') {
+                (0, context_1.printLog)(ctx, `[error-decoder] unknown selector ${decoded.selector} — consider adding to KNOWN_ERROR_SELECTORS`);
+            }
             const failureSummary = [
                 `PUSH CHAIN TRANSACTION FAILED`,
                 `Cosmos TX Hash: ${tx.transactionHash}`,
                 `Block Height: ${tx.height}, TX Code: ${tx.code} (error)`,
                 `Gas Used: ${tx.gasUsed}, Gas Wanted: ${tx.gasWanted}`,
                 ...(failedEthTxHashes.length > 0 ? [`Ethereum TX Hash(es): ${failedEthTxHashes.join(', ')}`] : []),
-                `Error: ${tx.rawLog}`,
+                `Error: ${augmentedMessage}`,
             ].join(' | ');
             (0, context_1.printLog)(ctx, failureSummary);
-            throw new Error(tx.rawLog);
+            // Throw a typed error so the orchestrator's outer catch can lift the
+            // structured `decodedError` straight onto the terminal-hook payload.
+            throw new errors_1.PushChainExecutionError(augmentedMessage, {
+                decodedError: decodedForPayload,
+            });
         }
         if (!tx || tx.code !== 0) {
             throw new Error(`sendUniversalTx — unreachable: loop exited without success or throw`);
         }
-        const ethTxHashes = (_d = (_c = tx.events) === null || _c === void 0 ? void 0 : _c.filter((e) => e.type === 'ethereum_tx').flatMap((e) => {
+        const ethTxHashes = (_e = (_d = tx.events) === null || _d === void 0 ? void 0 : _d.filter((e) => e.type === 'ethereum_tx').flatMap((e) => {
             var _a;
             return (_a = e.attributes) === null || _a === void 0 ? void 0 : _a.filter((attr) => attr.key === 'ethereumTxHash').map((attr) => attr.value);
-        })) !== null && _d !== void 0 ? _d : [];
+        })) !== null && _e !== void 0 ? _e : [];
         if (ethTxHashes.length === 0) {
             throw new Error('No ethereumTxHash found in transaction events');
         }
@@ -278,7 +290,7 @@ function sendUniversalTx(ctx, isUEADeployed, feeLockTxHash, universalPayload, ve
  */
 function extractPcTxAndTransform(ctx, pushChainUniversalTx, gatewayTxHash, eventBuffer, label, transformFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a;
+        var _a, _b;
         if (!((_a = pushChainUniversalTx === null || pushChainUniversalTx === void 0 ? void 0 : pushChainUniversalTx.pcTx) === null || _a === void 0 ? void 0 : _a.length)) {
             throw new Error(`Failed to retrieve Push Chain transaction status for gateway tx: ${gatewayTxHash}. ` +
                 `The transaction may have failed on Push Chain or not been indexed yet.`);
@@ -291,24 +303,39 @@ function extractPcTxAndTransform(ctx, pushChainUniversalTx, gatewayTxHash, event
                 ? lastPcTransaction
                 : pushChainUniversalTx.pcTx.find((pcTx) => pcTx.status === 'FAILED' && pcTx.errorMsg);
             const errorDetails = (failedPcTx === null || failedPcTx === void 0 ? void 0 : failedPcTx.errorMsg) ? `: ${failedPcTx.errorMsg}` : '';
-            // Parse known UEA error selectors for actionable hints
+            // Decode known revert selectors and ABI-encoded `Error(string)` reverts
+            // into actionable hints. Unknown selectors are logged at INFO so the
+            // table can grow from real reverts.
             let hint = '';
-            if (failedPcTx === null || failedPcTx === void 0 ? void 0 : failedPcTx.errorMsg) {
-                if (failedPcTx.errorMsg.includes('0xacfdb444')) {
-                    hint = ' [ExecutionFailed: the subcall to the target contract reverted. ' +
-                        'Check that the target address can receive native tokens (has receive/fallback) ' +
-                        'and that calldata matches a valid function signature.]';
-                }
-                else if (failedPcTx.errorMsg.includes('0x179a867c')) {
-                    hint = ' [ExpiredDeadline: the transaction deadline has passed.]';
-                }
+            let decodedForPayload;
+            const decoded = (0, error_decoder_1.decodeRevert)((_b = failedPcTx === null || failedPcTx === void 0 ? void 0 : failedPcTx.errorMsg) !== null && _b !== void 0 ? _b : '');
+            if ((decoded === null || decoded === void 0 ? void 0 : decoded.kind) === 'custom') {
+                hint = ` [${decoded.name}: ${decoded.hint}]`;
+                decodedForPayload = {
+                    name: decoded.name,
+                    hint: decoded.hint,
+                    selector: decoded.selector,
+                };
+            }
+            else if ((decoded === null || decoded === void 0 ? void 0 : decoded.kind) === 'string') {
+                hint = ` [Error(string): "${decoded.decoded}"]`;
+                decodedForPayload = {
+                    decoded: decoded.decoded,
+                    selector: decoded.selector,
+                };
+            }
+            else if ((decoded === null || decoded === void 0 ? void 0 : decoded.kind) === 'unknown') {
+                (0, context_1.printLog)(ctx, `[error-decoder] unknown selector ${decoded.selector} — consider adding to KNOWN_ERROR_SELECTORS`);
             }
             const fullMessage = `Push Chain transaction failed for gateway tx: ${gatewayTxHash}${errorDetails}${hint}`;
             // Live-emit 199-02 before throwing so the terminal failure hook reaches
             // any caller-registered progress stream (parity with reconstructProgressEvents
             // which emits 199-02 on replay).
-            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, fullMessage);
-            throw new PushChainExecutionError(fullMessage, { gatewayTxHash });
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, fullMessage, decodedForPayload);
+            throw new errors_1.PushChainExecutionError(fullMessage, {
+                gatewayTxHash,
+                decodedError: decodedForPayload,
+            });
         }
         const tx = yield ctx.pushClient.getTransaction(lastPcTransaction.txHash);
         return transformFn(tx, eventBuffer);

package/src/lib/orchestrator/internals/route-handlers.js

@@ -31,6 +31,8 @@ const helpers_1 = require("./helpers");
 const payload_builder_1 = require("./payload-builder");
 const uea_manager_1 = require("./uea-manager");
 const gas_calculator_1 = require("./gas-calculator");
+const preflight_1 = require("./preflight");
+const svm_rent_1 = require("./svm-rent");
 const chain_1 = require("../../constants/chain");
 const utils_1 = require("../../utils");
 const price_fetch_1 = require("../../price-fetch/price-fetch");
@@ -279,7 +281,7 @@ function executeMultiChain(ctx, params, executeFn) {
  */
 function executeUoaToCea(ctx, params, executeFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         const target = params.to;
         const targetChain = target.chain;
         const targetAddress = target.address;
@@ -440,29 +442,39 @@ function executeUoaToCea(ctx, params, executeFn) {
             (0, context_1.printLog)(ctx, `executeUoaToCea — capping nativeValueForGas at 200 UPC ceiling (was ${nativeValueForGas.toString()})`);
             nativeValueForGas = EVM_NATIVE_VALUE_SAFETY_CAP;
         }
-        let adjustedValue;
-        if (effectiveBalance >= nativeValueForGas + EVM_GAS_RESERVE) {
-            adjustedValue = nativeValueForGas;
-        }
-        else if (effectiveBalance > EVM_GAS_RESERVE) {
-            // Balance-starved: send everything we can afford. swapAndBurnGas
-            // refunds unused; undershoot will revert with a concrete error.
-            adjustedValue = effectiveBalance - EVM_GAS_RESERVE;
-        }
-        else if (effectiveBalance > BigInt(0)) {
-            // Drained UEA: overshoot would return (false, "") and surface as an
-            // opaque ExecutionFailed() — clamp to what we have.
-            adjustedValue = effectiveBalance < nativeValueForGas ? effectiveBalance : nativeValueForGas;
-        }
-        else {
-            throw new Error(`UEA ${ueaAddress} has zero UPC balance; cannot fund outbound gas swap. ` +
-                `Bridge UPC to the UEA before retrying.`);
+        // Pre-flight: throws InsufficientUEABalanceError when UEA cannot cover
+        // (nativeValueForGas + gasReserve) or the PRC-20 burn amount. Replaces the
+        // legacy silent-clamp that previously submitted under-funded swaps and
+        // bubbled up as Uniswap STF reverts. PRC-20 check fires whenever
+        // burnAmount > 0 — user must pre-hold the burn token, even when it equals
+        // the gas token (the gateway does transferFrom BEFORE the gas swap).
+        let prc20BalanceR2Evm;
+        if (burnAmount > BigInt(0)) {
+            prc20BalanceR2Evm = yield ctx.pushClient.readContract({
+                address: prc20Token,
+                abi: erc20_evm_1.ERC20_EVM,
+                functionName: 'balanceOf',
+                args: [ueaAddress],
+            });
         }
-        if (adjustedValue !== nativeValueForGas) {
-            (0, context_1.printLog)(ctx, `executeUoaToCea — adjusting nativeValueForGas from ${nativeValueForGas.toString()} ` +
-                `to ${adjustedValue.toString()} (effective balance: ${effectiveBalance.toString()})`);
-            nativeValueForGas = adjustedValue;
+        const allowUnderfundedR2Evm = ((_d = params.options) === null || _d === void 0 ? void 0 : _d.allowUnderfundedSwap) === true;
+        const preflightR2Evm = (0, preflight_1.runPreflight)({
+            ctx,
+            ueaAddress,
+            ueaBalance: effectiveBalance,
+            requiredValue: nativeValueForGas,
+            gasReserve: EVM_GAS_RESERVE,
+            pathTag: 'R2_EVM',
+            burnToken: prc20Token,
+            burnAmount,
+            prc20Balance: prc20BalanceR2Evm,
+            allowUnderfundedSwap: allowUnderfundedR2Evm,
+        });
+        if (!preflightR2Evm.ok) {
+            nativeValueForGas = preflightR2Evm.legacyClampedValue;
+            (0, context_1.printLog)(ctx, `executeUoaToCea — allowUnderfundedSwap=true; using legacy clamped value ${nativeValueForGas.toString()}`);
         }
+        // ok=true → nativeValueForGas already covers required + reserve; no adjust needed.
         // Build outbound multicalls (approve burn + sendUniversalTxOutbound with native value)
         const outboundMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
             prc20Token,
@@ -475,31 +487,6 @@ function executeUoaToCea(ctx, params, executeFn) {
         });
         pushChainMulticalls.push(...outboundMulticalls);
         (0, context_1.printLog)(ctx, `executeUoaToCea — Push Chain multicall has ${pushChainMulticalls.length} operations`);
-        // TODO: Enable pre-flight balance checks once outbound flow is stable
-        // if (burnAmount > BigInt(0)) {
-        //   const prc20Balance = await ctx.pushClient.publicClient.readContract({
-        //     address: prc20Token,
-        //     abi: [{ name: 'balanceOf', type: 'function', stateMutability: 'view', inputs: [{ name: 'account', type: 'address' }], outputs: [{ name: '', type: 'uint256' }] }],
-        //     functionName: 'balanceOf',
-        //     args: [ueaAddress],
-        //   }) as bigint;
-        //   if (prc20Balance < burnAmount) {
-        //     throw new Error(
-        //       `Insufficient PRC-20 token balance on UEA. ` +
-        //       `Required: ${burnAmount.toString()}, Available: ${prc20Balance.toString()}, ` +
-        //       `Token: ${prc20Token}, UEA: ${ueaAddress}. ` +
-        //       `Please bridge tokens to Push Chain first.`
-        //     );
-        //   }
-        // }
-        // const currentUeaBalance = await ctx.pushClient.getBalance(ueaAddress);
-        // if (currentUeaBalance < nativeValueForGas) {
-        //   throw new Error(
-        //     `Insufficient native balance on UEA for outbound gas. ` +
-        //     `Required: ${nativeValueForGas.toString()} wei, Available: ${currentUeaBalance.toString()} wei, ` +
-        //     `UEA: ${ueaAddress}. Please send UPC to your UEA first.`
-        //   );
-        // }
         // Execute through the normal execute() flow
         // This handles fee-locking on origin chain and executes the multicall from UEA context
         // Sum native values from multicall entries for proper fee calculation
@@ -549,7 +536,7 @@ function executeUoaToCea(ctx, params, executeFn) {
  */
 function executeUoaToCeaSvm(ctx, params, target, executeFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         const targetChain = target.chain;
         const targetAddress = target.address; // 0x-prefixed, 32 bytes
         const ueaAddress = (0, uea_manager_1.computeUEAOffchain)(ctx);
@@ -582,6 +569,22 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
         // gasLimit, it'll be derived from the gasFee/gasPrice response so the
         // on-chain record carries a non-zero compute budget the relay can use.
         let effectiveGasLimit = (_d = params.gasLimit) !== null && _d !== void 0 ? _d : BigInt(0);
+        // Conditional CEA-ATA rent bump: when the SPL outbound's destination ATA
+        // does not yet exist on Solana, the gateway needs an extra ~2.04M lamports
+        // for ATA-create rent. The on-chain quote does NOT include this, so bump
+        // effectiveGasLimit BEFORE queryOutboundGasFee so the returned gasFee
+        // already covers the rent.
+        const splMintBase58 = burnAmount > BigInt(0)
+            ? (_f = (_e = params.funds) === null || _e === void 0 ? void 0 : _e.token) === null || _f === void 0 ? void 0 : _f.address
+            : undefined;
+        effectiveGasLimit = yield (0, svm_rent_1.maybeBumpForCeaAtaRent)({
+            ctx,
+            ueaAddress,
+            targetChain,
+            splMintBase58,
+            burnAmount,
+            effectiveGasLimit,
+        });
         if (prc20Token !== selectors_1.ZERO_ADDRESS) {
             (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_202_01, targetChain);
             try {
@@ -628,7 +631,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
         const signerChainSvm = ctx.universalSigner.account.chain;
         const isNativePushEOASvm = (0, helpers_1.isPushChain)(signerChainSvm);
         // Skip getCode if accountStatusCache already confirmed deployment
-        const deployedHintSvm = (_f = (_e = ctx.accountStatusCache) === null || _e === void 0 ? void 0 : _e.uea) === null || _f === void 0 ? void 0 : _f.deployed;
+        const deployedHintSvm = (_h = (_g = ctx.accountStatusCache) === null || _g === void 0 ? void 0 : _g.uea) === null || _h === void 0 ? void 0 : _h.deployed;
         let ueaBalance;
         let isUEADeployed;
         if (deployedHintSvm || isNativePushEOASvm) {
@@ -650,37 +653,57 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
         // refundUnusedGas.
         //
         // SVM pools (WPC/pSOL) are thinner than EVM pools so the pool-quote can
-        // easily exceed the UEA's balance. Apply a balance-aware clamp so the
-        // outer tx doesn't fail with InsufficientFunds before the swap runs.
-        // No hard safety cap here — pSOL pool skew means even legitimate swaps
-        // can need hundreds of PC; capping would trigger Uniswap STF reverts.
+        // easily exceed the UEA's balance. Pre-flight (`runPreflight`) handles
+        // drain protection: an under-funded quote throws cleanly with
+        // `InsufficientUEABalanceError` and no cosmos tx is submitted. The
+        // SVM_NATIVE_VALUE_WARN_THRESHOLD below is telemetry-only; it does NOT
+        // truncate `nativeValueForGas`. v2 may add a hard cap once telemetry
+        // justifies a number — until then the original engineer's pool-skew
+        // warning still applies (capping risks false-positive truncation of
+        // legitimate quotes).
         const SVM_GAS_RESERVE = BigInt(3e18); // 3 UPC for outer-tx gas
         let nativeValueForGas = BigInt(0);
         if (universalCoreAddress && gasFee > BigInt(0)) {
             const estimated = yield (0, gas_calculator_1.estimateNativeValueForSwap)(ctx, universalCoreAddress, gasToken, gasFee, ueaBalance);
             nativeValueForGas = (estimated * BigInt(110)) / BigInt(100);
             (0, context_1.printLog)(ctx, `executeUoaToCeaSvm — nativeValueForGas: pool-quote=${estimated.toString()}, with 10% buffer=${nativeValueForGas.toString()}`);
+            (0, preflight_1.maybeFireSvmWarnThreshold)(ctx, nativeValueForGas, gasToken, 'R2_SVM');
+        }
+        // Pre-flight: throws InsufficientUEABalanceError when UEA cannot cover
+        // (nativeValueForGas + SVM_GAS_RESERVE) or the PRC-20 burn amount.
+        // Replaces the legacy silent-clamp that previously submitted under-funded
+        // swaps and bubbled up as Uniswap STF reverts.
+        // PRC-20 burn-balance pre-check fires whenever `burnAmount > 0`, regardless
+        // of whether `prc20Token` happens to equal `gasToken`. The gateway's
+        // `sendUniversalTxOutbound` does `transferFrom(user, gateway, burnAmount)`
+        // BEFORE the gas swap, so user must pre-hold `burnAmount` of `prc20Token`
+        // even when it's the same asset as the gas token (verified empirically:
+        // EOA with 77k units of pSOL reverted on-chain when trying to burn 10M).
+        let prc20BalanceR2Svm;
+        if (burnAmount > BigInt(0)) {
+            prc20BalanceR2Svm = yield ctx.pushClient.readContract({
+                address: prc20Token,
+                abi: erc20_evm_1.ERC20_EVM,
+                functionName: 'balanceOf',
+                args: [ueaAddress],
+            });
         }
-        // Balance-aware clamp: if UEA balance can't cover target + gas reserve,
-        // send only what we can afford. swapAndBurnGas refunds any excess.
-        let adjustedValueSvm;
-        if (ueaBalance >= nativeValueForGas + SVM_GAS_RESERVE) {
-            adjustedValueSvm = nativeValueForGas;
-        }
-        else if (ueaBalance > SVM_GAS_RESERVE) {
-            adjustedValueSvm = ueaBalance - SVM_GAS_RESERVE;
-        }
-        else if (ueaBalance > BigInt(0)) {
-            adjustedValueSvm = ueaBalance < nativeValueForGas ? ueaBalance : nativeValueForGas;
-        }
-        else {
-            throw new Error(`UEA ${ueaAddress} has zero UPC balance; cannot fund outbound gas swap. ` +
-                `Bridge UPC to the UEA before retrying.`);
-        }
-        if (adjustedValueSvm !== nativeValueForGas) {
-            (0, context_1.printLog)(ctx, `executeUoaToCeaSvm — adjusting nativeValueForGas from ${nativeValueForGas.toString()} ` +
-                `to ${adjustedValueSvm.toString()} (UEA balance: ${ueaBalance.toString()})`);
-            nativeValueForGas = adjustedValueSvm;
+        const allowUnderfundedR2Svm = ((_j = params.options) === null || _j === void 0 ? void 0 : _j.allowUnderfundedSwap) === true;
+        const preflightR2Svm = (0, preflight_1.runPreflight)({
+            ctx,
+            ueaAddress,
+            ueaBalance,
+            requiredValue: nativeValueForGas,
+            gasReserve: SVM_GAS_RESERVE,
+            pathTag: 'R2_SVM',
+            burnToken: prc20Token,
+            burnAmount,
+            prc20Balance: prc20BalanceR2Svm,
+            allowUnderfundedSwap: allowUnderfundedR2Svm,
+        });
+        if (!preflightR2Svm.ok) {
+            nativeValueForGas = preflightR2Svm.legacyClampedValue;
+            (0, context_1.printLog)(ctx, `executeUoaToCeaSvm — allowUnderfundedSwap=true; using legacy clamped value ${nativeValueForGas.toString()}`);
         }
         // --- Build Push Chain multicalls (approve + sendUniversalTxOutbound) ---
         // Reuse the same builder as EVM — this part is identical
@@ -746,7 +769,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
  */
 function executeCeaToPush(ctx, params, executeFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         // 1. Validate and extract source chain
         if (!((_a = params.from) === null || _a === void 0 ? void 0 : _a.chain)) {
             throw new Error('Route 3 (CEA -> Push) requires from.chain to specify the source CEA chain');
@@ -994,31 +1017,42 @@ function executeCeaToPush(ctx, params, executeFn) {
                 }
             }
         }
-        // Balance-aware adjustment matching Route 2 logic:
-        // - If balance exceeds target + reserve: use target (200 UPC)
-        // - If balance exceeds reserve: use balance - reserve (maximize within budget)
-        // - Otherwise: keep original nativeValueForGas (fallback)
-        const EVM_NATIVE_VALUE_TARGET_R3 = BigInt(200e18); // 200 UPC
-        let adjustedValue;
+        // Balance-aware *upward* allocation. The previous behaviour silently
+        // clamped to a 200 PC target whenever balance had headroom — which was
+        // a downward clamp when the calibrated value already exceeded 200 PC,
+        // masking under-funded swaps with opaque ExecutionFailed reverts. The
+        // new logic preserves the "consume extra to reduce STF risk" intent for
+        // small calibrated values while never reducing a calibrated value that
+        // happened to land above 200 PC. Down-clamp + zero-balance throws live
+        // in `runPreflight` below.
+        const EVM_NATIVE_VALUE_TARGET_R3 = BigInt(200e18); // 200 UPC target floor
         if (effectiveBalance > EVM_NATIVE_VALUE_TARGET_R3 + OUTBOUND_GAS_RESERVE_R3) {
-            adjustedValue = EVM_NATIVE_VALUE_TARGET_R3;
-        }
-        else if (effectiveBalance > OUTBOUND_GAS_RESERVE_R3) {
-            adjustedValue = effectiveBalance - OUTBOUND_GAS_RESERVE_R3;
-        }
-        else if (effectiveBalance > BigInt(0)) {
-            // Drained UEA: overshoot would make the inner .call{value:...} return (false, "")
-            // and the UEA reverts with opaque ExecutionFailed(). Clamp to whatever we have so
-            // the gateway swap either succeeds or surfaces a concrete revert reason.
-            adjustedValue = effectiveBalance < nativeValueForGas ? effectiveBalance : nativeValueForGas;
-        }
-        else {
-            throw new Error(`UEA ${ueaAddress} has zero UPC balance; cannot fund outbound gas swap. ` +
-                `Bridge UPC to the UEA before retrying.`);
+            // Balance can cover the target. Bump nativeValueForGas UP to 200 PC,
+            // but never reduce a calibrated value already above 200.
+            const newValue = nativeValueForGas > EVM_NATIVE_VALUE_TARGET_R3
+                ? nativeValueForGas
+                : EVM_NATIVE_VALUE_TARGET_R3;
+            if (newValue !== nativeValueForGas) {
+                (0, context_1.printLog)(ctx, `executeCeaToPush — adjusting nativeValueForGas UP from ${nativeValueForGas.toString()} to ${newValue.toString()} (EVM_NATIVE_VALUE_TARGET_R3 floor)`);
+                nativeValueForGas = newValue;
+            }
         }
-        if (adjustedValue !== nativeValueForGas) {
-            (0, context_1.printLog)(ctx, `executeCeaToPush — adjusting nativeValueForGas from ${nativeValueForGas.toString()} to ${adjustedValue.toString()} (effective balance: ${effectiveBalance.toString()})`);
-            nativeValueForGas = adjustedValue;
+        // Pre-flight (R3 EVM): no PRC-20 burn check — `burnAmount = 0` makes this
+        // payload-only (UEA never holds the source-chain PRC-20; see plan §9 #4).
+        // Native UPC check still applies for the gas swap.
+        const allowUnderfundedR3Evm = ((_j = params.options) === null || _j === void 0 ? void 0 : _j.allowUnderfundedSwap) === true;
+        const preflightR3Evm = (0, preflight_1.runPreflight)({
+            ctx,
+            ueaAddress,
+            ueaBalance: effectiveBalance,
+            requiredValue: nativeValueForGas,
+            gasReserve: OUTBOUND_GAS_RESERVE_R3,
+            pathTag: 'R3_EVM',
+            allowUnderfundedSwap: allowUnderfundedR3Evm,
+        });
+        if (!preflightR3Evm.ok) {
+            nativeValueForGas = preflightR3Evm.legacyClampedValue;
+            (0, context_1.printLog)(ctx, `executeCeaToPush — allowUnderfundedSwap=true; using legacy clamped value ${nativeValueForGas.toString()}`);
         }
         // 12. Build Push Chain multicalls (approvals + sendUniversalTxOutbound)
         const pushChainMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
@@ -1084,7 +1118,7 @@ function executeCeaToPush(ctx, params, executeFn) {
  */
 function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e;
         if (typeof params.to !== 'string') {
             throw new Error('Route 3 SVM (CEA -> Push): to must be a Push Chain address (string), not a ChainTarget');
         }
@@ -1136,9 +1170,13 @@ function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
             revertRecipientHex: ceaPdaHex,
         });
         (0, context_1.printLog)(ctx, `executeCeaToPushSvm — drainAmount: ${drainAmount.toString()}, payload length: ${(svmPayload.length - 2) / 2} bytes`);
-        // burnAmount = 1 (minimum for precompile; drain amount lives inside the ixData)
-        // The precompile rejects amount=0, so we use BigInt(1) as a workaround.
-        const burnAmount = BigInt(1);
+        // burnAmount = 0 (payload-only outbound — drain amount lives inside ixData).
+        // Mirrors the 2026-03-19 cascade fix that removed the 1-wei workaround for
+        // SVM payload-only hops because it caused `InsufficientBalance (0xf4d678b8)`
+        // reverts on fresh UEAs that don't hold the source-chain native PRC-20
+        // (e.g. pSOL). The UGPC upgrade post-2026-03-19 already accepts amount = 0
+        // on the cascade path, and the same precompile is used here.
+        const burnAmount = BigInt(0);
         // Build outbound request: target = gateway program (self-call)
         const outboundReq = (0, payload_builders_1.buildOutboundRequest)(gatewayProgramHex, prc20Token, burnAmount, (_b = params.gasLimit) !== null && _b !== void 0 ? _b : BigInt(0), svmPayload, ueaAddress);
         (0, context_1.printLog)(ctx, `executeCeaToPushSvm — outbound request: target=${outboundReq.target.slice(0, 20)}..., token=${outboundReq.token}`);
@@ -1189,15 +1227,58 @@ function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
             (0, context_1.printLog)(ctx, `executeCeaToPushSvm — Case C: bumping nativeValueForGas from ${nativeValueForGas} to ${bumped} (overflow=${sizingDecisionR3Svm.overflowNativePc})`);
             nativeValueForGas = bumped;
         }
-        // Adjust nativeValueForGas using UEA balance (contract refunds excess)
-        // Re-fetch balance to minimize staleness from gas fee query RPC roundtrips
+        // Re-fetch balance to minimize staleness from gas fee query RPC roundtrips.
         const currentBalance = yield ctx.pushClient.getBalance(ueaAddress);
         // Cosmos-EVM tx overhead costs ~1 PC per operation; 3 PC covers approve(s) + buffer.
         const OUTBOUND_GAS_RESERVE_R3_SVM = BigInt(3e18);
-        if (currentBalance > OUTBOUND_GAS_RESERVE_R3_SVM && currentBalance - OUTBOUND_GAS_RESERVE_R3_SVM > nativeValueForGas) {
-            const adjustedValue = currentBalance - OUTBOUND_GAS_RESERVE_R3_SVM;
-            (0, context_1.printLog)(ctx, `executeCeaToPushSvm — adjusting nativeValueForGas from ${nativeValueForGas.toString()} to ${adjustedValue.toString()} (UEA balance: ${currentBalance.toString()})`);
-            nativeValueForGas = adjustedValue;
+        // Upward-allocation ceiling: cap the upward adjust at max(200 PC, 5x calibrated)
+        // so a UEA with a giant balance doesn't submit msg.value=balance for a small
+        // gas swap. The contract refunds excess via swapAndBurnGas, but pushing
+        // hundreds of thousands of PC into a Uniswap pool moves the price for other
+        // users. 200 PC mirrors EVM's safety cap; 5x calibrated covers pool-skew
+        // scenarios where the calibrated value itself is > 40 PC (5x40 = 200).
+        const UPWARD_BASE_CEILING_R3_SVM = BigInt(200) * BigInt(1e18);
+        const calibratedCeiling = nativeValueForGas * BigInt(5);
+        const upwardCeiling = calibratedCeiling > UPWARD_BASE_CEILING_R3_SVM
+            ? calibratedCeiling
+            : UPWARD_BASE_CEILING_R3_SVM;
+        // Upward-only allocation: when balance has headroom over the calibrated
+        // value, consume more of it (up to the ceiling above). Down-clamp +
+        // zero-balance throws live in pre-flight.
+        // Ordering note: pre-flight runs AFTER the upward adjust below; the
+        // semantics are equivalent to running it before — when upward adjust
+        // applies it sets nativeValueForGas to balance-reserve (capped), and the
+        // post-adjust pre-flight check is always satisfied. When upward adjust is
+        // skipped (balance too low), pre-flight runs against the calibrated value
+        // and throws cleanly on shortfall.
+        if (currentBalance > OUTBOUND_GAS_RESERVE_R3_SVM &&
+            currentBalance - OUTBOUND_GAS_RESERVE_R3_SVM > nativeValueForGas) {
+            const balanceDriven = currentBalance - OUTBOUND_GAS_RESERVE_R3_SVM;
+            const adjustedValue = balanceDriven > upwardCeiling ? upwardCeiling : balanceDriven;
+            if (adjustedValue !== nativeValueForGas) {
+                (0, context_1.printLog)(ctx, `executeCeaToPushSvm — adjusting nativeValueForGas from ${nativeValueForGas.toString()} to ${adjustedValue.toString()} ` +
+                    `(UEA balance: ${currentBalance.toString()}, upwardCeiling: ${upwardCeiling.toString()})`);
+                nativeValueForGas = adjustedValue;
+            }
+        }
+        // SVM warn-threshold telemetry (no truncation — pre-flight handles drain protection).
+        (0, preflight_1.maybeFireSvmWarnThreshold)(ctx, nativeValueForGas, gasToken, 'R3_SVM');
+        // Pre-flight (R3 SVM): no PRC-20 burn check — `burnAmount = 1` is a legacy
+        // precompile-validation shim against a token UEAs structurally don't hold
+        // (see plan §9 #4 / §10.2 latent-bug ticket). Native UPC check still applies.
+        const allowUnderfundedR3Svm = ((_e = params.options) === null || _e === void 0 ? void 0 : _e.allowUnderfundedSwap) === true;
+        const preflightR3Svm = (0, preflight_1.runPreflight)({
+            ctx,
+            ueaAddress,
+            ueaBalance: currentBalance,
+            requiredValue: nativeValueForGas,
+            gasReserve: OUTBOUND_GAS_RESERVE_R3_SVM,
+            pathTag: 'R3_SVM',
+            allowUnderfundedSwap: allowUnderfundedR3Svm,
+        });
+        if (!preflightR3Svm.ok) {
+            nativeValueForGas = preflightR3Svm.legacyClampedValue;
+            (0, context_1.printLog)(ctx, `executeCeaToPushSvm — allowUnderfundedSwap=true; using legacy clamped value ${nativeValueForGas.toString()}`);
         }
         // Build Push Chain multicalls (approvals + sendUniversalTxOutbound)
         const pushChainMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({

package/src/lib/orchestrator/internals/svm-rent.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Conditional CEA-ATA rent bump for SVM SPL outbounds.
+ *
+ * The gateway program (svm-gateway) computes per-tx fees with a conditional
+ * rent for first-time SPL transfers — see `calculateSplExecuteFees` in
+ * `push-chain-gateway-contracts/contracts/svm-gateway/tests/helpers/test-utils.ts`:
+ *
+ *   const ataExists = await ceaAtaExists(connection, ceaAta);
+ *   const ceaAtaRent = ataExists ? 0n : BigInt(getMinimumBalanceForRentExemption(165));
+ *   gasFee = executedTxRent + ceaAtaRent + COMPUTE_BUFFER;
+ *
+ * The gateway's on-chain `getOutboundTxGasAndFees` quote does NOT factor in
+ * the ATA rent today, so the SDK has to bump `effectiveGasLimit` itself
+ * before calling that quote. Native-SOL outbounds use `calculateSolExecuteFees`
+ * which has no conditional rent, so no SDK bump is needed there.
+ */
+import { PublicKey } from '@solana/web3.js';
+import type { OrchestratorContext } from './context';
+import type { CHAIN as ChainType } from '../../constants/enums';
+/** ATA rent (165-byte SPL token account) + executed-tx rent (8-byte) + compute buffer.
+ *  Mirrors getMinimumBalanceForRentExemption(165) ≈ 2_039_280
+ *       + getMinimumBalanceForRentExemption(8) ≈ 9_200
+ *       + COMPUTE_BUFFER 100_000.
+ *  Signature fee (5_000) is already included in the gateway's base quote. */
+export declare const CEA_ATA_RENT_LAMPORTS_BUMP: bigint;
+/** Derive CEA PDA from a 20-byte EVM address. Seeds: ["push_identity", evmBytes]. */
+export declare function deriveSvmCeaPda(evmAddress: `0x${string}`): PublicKey;
+/** Derive a standard SPL Associated Token Account address. */
+export declare function deriveAtaPubkey(owner: PublicKey, mint: PublicKey): PublicKey;
+export interface MaybeBumpInput {
+    ctx: OrchestratorContext;
+    ueaAddress: `0x${string}`;
+    targetChain: ChainType;
+    /** SPL mint as base58 (from MoveableToken.address for SVM tokens). undefined ⇒ no SPL. */
+    splMintBase58: string | undefined;
+    /** Burn amount in token units. 0 ⇒ no SPL transferFrom ⇒ no ATA needed. */
+    burnAmount: bigint;
+    effectiveGasLimit: bigint;
+}
+/**
+ * Returns the (possibly bumped) effectiveGasLimit. Logs the decision via
+ * printLog. On any RPC failure or invalid input, logs a warning and returns
+ * the input unchanged — better to risk one underflow than to block all SPL
+ * outbounds on RPC flake; pre-flight will surface insufficient gas anyway.
+ */
+export declare function maybeBumpForCeaAtaRent(input: MaybeBumpInput): Promise<bigint>;