@pushchain/core 5.1.4-alpha.8 → 5.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushchain/core",
-  "version": "5.1.4-alpha.8",
+  "version": "5.1.4",
   "homepage": "https://push.org",
   "keywords": [
     "pushchain",

package/src/lib/orchestrator/internals/execute-standard.js

@@ -28,6 +28,9 @@ const confirmation_1 = require("./confirmation");
 const gateway_client_1 = require("./gateway-client");
 const response_builder_1 = require("./response-builder");
 const push_chain_tx_1 = require("./push-chain-tx");
+const gas_calculator_1 = require("./gas-calculator");
+const helpers_2 = require("./helpers");
+const price_fetch_1 = require("../../price-fetch/price-fetch");
 function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
         var _a, _b;
@@ -198,7 +201,57 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             const fixedPushAmount = utils_1.Utils.helpers.parseUnits('0.001', 18);
             const lockAmount = funds < requiredFunds ? fundDifference : fixedPushAmount;
             const lockAmountInUSD = ctx.pushClient.pushToUSDC(lockAmount);
-            const feeLockTxHashBytes = yield (0, gateway_client_1.lockFee)(ctx, lockAmountInUSD, universalPayload, req);
+            // Apply minimum deposit override (e.g., Route 2 needs enough UPC for outbound swap)
+            const effectiveLockAmountInUSD = execute._minimumDepositUsd && execute._minimumDepositUsd > lockAmountInUSD
+                ? execute._minimumDepositUsd
+                : lockAmountInUSD;
+            // Pre-flight: predict the actual $PC the UEA will receive after the
+            // on-chain pETH → WPC swap and validate it covers requiredFunds.
+            // Uses the same Uniswap V3 quoter the chain uses (execute_inbound_gas.go).
+            // Mirrors the pattern in route-handlers.ts (Route 2/3).
+            const { vm: originVm } = chain_1.CHAIN_INFO[chain];
+            if (originVm === enums_1.VM.EVM) {
+                try {
+                    // Replicate lockFee's USD → native conversion (with its $1–$10 clamp)
+                    const oneUsd = utils_1.Utils.helpers.parseUnits('1', 8);
+                    const tenUsd = utils_1.Utils.helpers.parseUnits('10', 8);
+                    let depositUsd = effectiveLockAmountInUSD < oneUsd ? oneUsd : effectiveLockAmountInUSD;
+                    if (depositUsd > tenUsd)
+                        depositUsd = tenUsd;
+                    const ethPrice = yield new price_fetch_1.PriceFetch(ctx.rpcUrls).getPrice(chain);
+                    if (ethPrice > BigInt(0)) {
+                        const nativeAmountETH = (depositUsd * BigInt(1e18) + (ethPrice - BigInt(1))) / ethPrice + BigInt(1);
+                        const originPrc20 = (0, helpers_2.getNativePRC20ForChain)(chain, ctx.pushNetwork);
+                        const predictedUPC = yield (0, gas_calculator_1.estimateDepositFromLockedNative)(ctx, nativeAmountETH, originPrc20);
+                        if (predictedUPC > BigInt(0)) {
+                            // 10% slippage margin (same as route-handlers.ts)
+                            const safeUPC = (predictedUPC * BigInt(90)) / BigInt(100);
+                            const totalAvailable = safeUPC + funds;
+                            (0, context_1.printLog)(ctx, `Fee-lock pre-flight: deposit ${depositUsd.toString()} USD → ` +
+                                `~${nativeAmountETH.toString()} wei ETH → ~${predictedUPC.toString()} UPC ` +
+                                `(safe: ${safeUPC.toString()}), existing: ${funds.toString()}, ` +
+                                `total: ${totalAvailable.toString()}, required: ${requiredFunds.toString()}`);
+                            if (totalAvailable < requiredFunds) {
+                                const shortfall = requiredFunds - totalAvailable;
+                                throw new Error(`Insufficient deposit: the fee-lock will deposit ~${(Number(safeUPC) / 1e18).toFixed(4)} $PC ` +
+                                    `but the transaction requires ~${(Number(requiredFunds) / 1e18).toFixed(4)} $PC ` +
+                                    `(shortfall: ~${(Number(shortfall) / 1e18).toFixed(4)} $PC). ` +
+                                    `The fee-lock deposit is capped at $10 USD. Reduce the transfer value or ` +
+                                    `pre-fund the UEA (${UEA}) on Push Chain.`);
+                            }
+                        }
+                    }
+                }
+                catch (err) {
+                    // If the error is our own insufficient-deposit error, rethrow it
+                    if (err instanceof Error && err.message.startsWith('Insufficient deposit')) {
+                        throw err;
+                    }
+                    // Otherwise quoter failed — log and continue (same fallback as route-handlers)
+                    (0, context_1.printLog)(ctx, `Fee-lock pre-flight quote failed, proceeding without validation: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            const feeLockTxHashBytes = yield (0, gateway_client_1.lockFee)(ctx, effectiveLockAmountInUSD, universalPayload, req);
             feeLockTxHash = (0, viem_1.bytesToHex)(feeLockTxHashBytes);
             verificationData = (0, viem_1.bytesToHex)(feeLockTxHashBytes);
             const { vm } = chain_1.CHAIN_INFO[chain];

package/src/lib/orchestrator/internals/gas-calculator.d.ts

@@ -36,3 +36,12 @@ export declare function calculateGasAmountFromAmountOutMinETH(ctx: OrchestratorC
 }) => Promise<ConversionQuote>): Promise<{
     gasAmount: bigint;
 }>;
+/**
+ * Predicts how much UPC (WPC) the chain will deposit to the UEA from a given
+ * amount of locked native token (e.g., ETH on Sepolia). The chain converts
+ * locked ETH → pETH (PRC-20) → WPC via Uniswap V3 swap on Push Chain.
+ *
+ * Queries the same Uniswap V3 QuoterV2 the chain uses in execute_inbound_gas.go.
+ * Returns 0 on any failure (caller should fall back to other logic).
+ */
+export declare function estimateDepositFromLockedNative(ctx: OrchestratorContext, nativeAmountForLocker: bigint, prc20Token: `0x${string}`): Promise<bigint>;

package/src/lib/orchestrator/internals/gas-calculator.js

@@ -10,6 +10,7 @@ exports.estimateNativeValueForSwap = estimateNativeValueForSwap;
 exports.queryRescueGasFee = queryRescueGasFee;
 exports.calculateNativeAmountForDeposit = calculateNativeAmountForDeposit;
 exports.calculateGasAmountFromAmountOutMinETH = calculateGasAmountFromAmountOutMinETH;
+exports.estimateDepositFromLockedNative = estimateDepositFromLockedNative;
 const tslib_1 = require("tslib");
 const web3_js_1 = require("@solana/web3.js");
 const viem_1 = require("viem");
@@ -421,4 +422,97 @@ function calculateGasAmountFromAmountOutMinETH(ctx, gasTokenAddress, amountOutMi
         return { gasAmount };
     });
 }
+// ============================================================================
+// Estimate UPC deposit from locked ETH via Uniswap V3 quote
+// ============================================================================
+/**
+ * Predicts how much UPC (WPC) the chain will deposit to the UEA from a given
+ * amount of locked native token (e.g., ETH on Sepolia). The chain converts
+ * locked ETH → pETH (PRC-20) → WPC via Uniswap V3 swap on Push Chain.
+ *
+ * Queries the same Uniswap V3 QuoterV2 the chain uses in execute_inbound_gas.go.
+ * Returns 0 on any failure (caller should fall back to other logic).
+ */
+function estimateDepositFromLockedNative(ctx, nativeAmountForLocker, prc20Token) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        try {
+            const pushChain = (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork);
+            const quoterAddress = (_b = (_a = chain_1.CHAIN_INFO[pushChain]) === null || _a === void 0 ? void 0 : _a.dex) === null || _b === void 0 ? void 0 : _b.uniV3QuoterV2;
+            if (!quoterAddress || quoterAddress.startsWith('0xTBD'))
+                return BigInt(0);
+            // Get UniversalCore → WPC address + fee tier (reuses existing ABI)
+            const gatewayPcAddress = (0, helpers_1.getUniversalGatewayPCAddress)();
+            const universalCoreAddress = yield ctx.pushClient.readContract({
+                address: gatewayPcAddress,
+                abi: abi_1.UNIVERSAL_GATEWAY_PC,
+                functionName: 'UNIVERSAL_CORE',
+                args: [],
+            });
+            const [wpcAddress, feeTier] = yield Promise.all([
+                ctx.pushClient.readContract({
+                    address: universalCoreAddress,
+                    abi: UNIVERSAL_CORE_SWAP_HELPERS_ABI,
+                    functionName: 'WPC',
+                    args: [],
+                }),
+                ctx.pushClient.readContract({
+                    address: universalCoreAddress,
+                    abi: UNIVERSAL_CORE_SWAP_HELPERS_ABI,
+                    functionName: 'defaultFeeTier',
+                    args: [prc20Token],
+                }),
+            ]);
+            if (!feeTier || !wpcAddress)
+                return BigInt(0);
+            // QuoterV2.quoteExactInputSingle — same call the chain relay makes
+            const QUOTER_ABI = [
+                {
+                    type: 'function',
+                    name: 'quoteExactInputSingle',
+                    inputs: [
+                        {
+                            type: 'tuple',
+                            components: [
+                                { name: 'tokenIn', type: 'address' },
+                                { name: 'tokenOut', type: 'address' },
+                                { name: 'amountIn', type: 'uint256' },
+                                { name: 'fee', type: 'uint24' },
+                                { name: 'sqrtPriceLimitX96', type: 'uint160' },
+                            ],
+                        },
+                    ],
+                    outputs: [
+                        { name: 'amountOut', type: 'uint256' },
+                        { name: 'sqrtPriceX96After', type: 'uint160' },
+                        { name: 'initializedTicksCrossed', type: 'uint32' },
+                        { name: 'gasEstimate', type: 'uint256' },
+                    ],
+                    stateMutability: 'view',
+                },
+            ];
+            const result = yield ctx.pushClient.readContract({
+                address: quoterAddress,
+                abi: QUOTER_ABI,
+                functionName: 'quoteExactInputSingle',
+                args: [
+                    {
+                        tokenIn: prc20Token,
+                        tokenOut: wpcAddress,
+                        amountIn: nativeAmountForLocker,
+                        fee: feeTier,
+                        sqrtPriceLimitX96: BigInt(0),
+                    },
+                ],
+            });
+            const amountOut = result[0];
+            (0, context_1.printLog)(ctx, `estimateDepositFromLockedNative — quote: ${nativeAmountForLocker.toString()} pETH → ${amountOut.toString()} WPC (fee tier: ${feeTier})`);
+            return amountOut;
+        }
+        catch (err) {
+            (0, context_1.printLog)(ctx, `estimateDepositFromLockedNative — failed: ${err instanceof Error ? err.message : String(err)}`);
+            return BigInt(0);
+        }
+    });
+}
 //# sourceMappingURL=gas-calculator.js.map

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

@@ -195,10 +195,24 @@ function extractPcTxAndTransform(ctx, pushChainUniversalTx, gatewayTxHash, event
         const lastPcTransaction = pushChainUniversalTx.pcTx.at(-1);
         (0, context_1.printLog)(ctx, `${label} — pcTx: ` + JSON.stringify(pushChainUniversalTx.pcTx.map((p) => ({ txHash: p.txHash, status: p.status, errorMsg: p.errorMsg })), null, 2));
         (0, context_1.printLog)(ctx, `${label} — using lastPcTransaction: ` + JSON.stringify(lastPcTransaction, null, 2));
-        if (!(lastPcTransaction === null || lastPcTransaction === void 0 ? void 0 : lastPcTransaction.txHash)) {
-            const failedPcTx = pushChainUniversalTx.pcTx.find((pcTx) => pcTx.status === 'FAILED' && pcTx.errorMsg);
+        if (!(lastPcTransaction === null || lastPcTransaction === void 0 ? void 0 : lastPcTransaction.txHash) || lastPcTransaction.status === 'FAILED') {
+            const failedPcTx = (lastPcTransaction === null || lastPcTransaction === void 0 ? void 0 : lastPcTransaction.status) === 'FAILED'
+                ? lastPcTransaction
+                : pushChainUniversalTx.pcTx.find((pcTx) => pcTx.status === 'FAILED' && pcTx.errorMsg);
             const errorDetails = (failedPcTx === null || failedPcTx === void 0 ? void 0 : failedPcTx.errorMsg) ? `: ${failedPcTx.errorMsg}` : '';
-            throw new Error(`No transaction hash found in Push Chain response for gateway tx: ${gatewayTxHash}${errorDetails}`);
+            // Parse known UEA error selectors for actionable hints
+            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.]';
+                }
+            }
+            throw new Error(`Push Chain transaction failed for gateway tx: ${gatewayTxHash}${errorDetails}${hint}`);
         }
         const tx = yield ctx.pushClient.getTransaction(lastPcTransaction.txHash);
         return transformFn(tx, eventBuffer);

package/src/lib/orchestrator/internals/response-builder.js

@@ -150,7 +150,7 @@ function trackTransaction(ctx, txHash, options, callbacks) {
             throw new Error('trackTransaction requires ResponseBuilderCallbacks');
         }
         const { chain = (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork), progressHook, waitForCompletion = true, advanced = {}, } = options !== null && options !== void 0 ? options : {};
-        const { timeout = 300000, rpcUrls = {} } = advanced;
+        const { timeout = 300000, pollingIntervalMs = 1000, rpcUrls = {} } = advanced;
         // Event buffer for replay via response.progressHook()
         const eventBuffer = [];
         // Helper to emit progress events
@@ -190,7 +190,7 @@ function trackTransaction(ctx, txHash, options, callbacks) {
                     throw new Error(`Timeout: transaction ${txHash} not confirmed within ${timeout}ms`);
                 }
                 // Brief delay before retry
-                yield new Promise((r) => setTimeout(r, 1000));
+                yield new Promise((r) => setTimeout(r, pollingIntervalMs));
             }
         }
         // Try to get UniversalTx data for richer progress reconstruction
@@ -256,7 +256,7 @@ function trackTransaction(ctx, txHash, options, callbacks) {
 function transformToUniversalTxResponse(ctx_1, tx_1) {
     return tslib_1.__awaiter(this, arguments, void 0, function* (ctx, tx, eventBuffer = [], callbacks) {
         const chain = ctx.universalSigner.account.chain;
-        const { vm, chainId } = chain_1.CHAIN_INFO[chain];
+        let { vm, chainId } = chain_1.CHAIN_INFO[chain];
         let from;
         let to;
         let value;
@@ -269,6 +269,13 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                 throw new Error('UEA origin account is null');
             }
             originAddress = ueaOrigin.account.address;
+            // Use the resolved origin chain for vm/chainId so that the `origin`
+            // field reflects the transaction's actual origin, not the tracker's.
+            const resolvedChainInfo = chain_1.CHAIN_INFO[ueaOrigin.account.chain];
+            if (resolvedChainInfo) {
+                vm = resolvedChainInfo.vm;
+                chainId = resolvedChainInfo.chainId;
+            }
             from = (0, viem_1.getAddress)(tx.to);
             let decoded;
             if (tx.input !== '0x') {

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

@@ -31,6 +31,8 @@ const payload_builder_1 = require("./payload-builder");
 const uea_manager_1 = require("./uea-manager");
 const gas_calculator_1 = require("./gas-calculator");
 const chain_1 = require("../../constants/chain");
+const utils_1 = require("../../utils");
+const price_fetch_1 = require("../../price-fetch/price-fetch");
 const route_detector_1 = require("../route-detector");
 const cea_utils_1 = require("../cea-utils");
 const payload_builders_1 = require("../payload-builders");
@@ -277,46 +279,48 @@ function executeUoaToCea(ctx, params, executeFn) {
                 throw new Error(`Failed to query outbound gas fee: ${err}`);
             }
         }
-        // Estimate the actual WPC needed for the swap using on-chain pool price.
-        // The static 1Mx multiplier from queryOutboundGasFee doesn't reflect the real
-        // WPC/gasToken exchange rate. estimateNativeValueForSwap reads the Uniswap V3
-        // pool's slot0, computes the true cost, and adds a 2x buffer.
-        // This matches the SVM path (executeUoaToCeaSvm) which already uses this.
-        // Excess msg.value is refunded by the contract's swapAndBurnGas.
-        if (universalCoreAddress && gasFee > BigInt(0)) {
-            const estimated = yield (0, gas_calculator_1.estimateNativeValueForSwap)(ctx, universalCoreAddress, gasToken, gasFee, ueaBalance);
-            if (estimated > nativeValueForGas) {
-                (0, context_1.printLog)(ctx, `executeUoaToCea — pool-price estimate: ${estimated.toString()} ` +
-                    `(was ${nativeValueForGas.toString()}), UEA balance: ${ueaBalance.toString()}`);
-                nativeValueForGas = estimated;
-            }
-        }
-        // Balance-aware cap: avoid draining the entire UEA balance for gas.
+        // Balance-aware adjustment: MAXIMIZE nativeValueForGas within available balance.
         // The contract's swapAndBurnGas does exactOutputSingle and refunds excess PC,
-        // so overshooting within balance is safe.
+        // so overshooting within balance is safe. Undershooting causes the swap to revert.
         const EVM_NATIVE_VALUE_TARGET = BigInt(200e18); // 200 UPC
         const EVM_GAS_RESERVE = BigInt(3e18); // 3 UPC for tx overhead
-        const currentBalance = ueaBalance;
+        const ROUTE2_MINIMUM_DEPOSIT_USD = utils_1.Utils.helpers.parseUnits('10', 8); // $10
+        // Determine effective balance for the adjustment.
+        // For deployed UEAs: use real balance.
+        // For fresh wallets: predict the post-fee-locking balance by querying the same
+        // Uniswap V3 quoter the chain uses (pETH → WPC swap in execute_inbound_gas.go).
+        let effectiveBalance = ueaBalance;
+        if (!isUEADeployed && effectiveBalance <= EVM_GAS_RESERVE) {
+            // Calculate the ETH amount lockFee will send (same formula as lockFee)
+            const ethPrice = yield new price_fetch_1.PriceFetch(ctx.rpcUrls).getPrice(signerChain);
+            const nativeAmountETH = ethPrice > BigInt(0)
+                ? (ROUTE2_MINIMUM_DEPOSIT_USD * BigInt(1e18) + (ethPrice - BigInt(1))) / ethPrice + BigInt(1)
+                : BigInt(0);
+            if (nativeAmountETH > BigInt(0)) {
+                // Query the real swap quote: how much WPC (UPC) for this pETH amount?
+                const originPrc20 = (0, helpers_1.getNativePRC20ForChain)(signerChain, ctx.pushNetwork);
+                const predictedUPC = yield (0, gas_calculator_1.estimateDepositFromLockedNative)(ctx, nativeAmountETH, originPrc20);
+                if (predictedUPC > BigInt(0)) {
+                    // 10% safety margin for slippage between quote and actual execution
+                    effectiveBalance = (predictedUPC * BigInt(90)) / BigInt(100);
+                    (0, context_1.printLog)(ctx, `executeUoaToCea — fresh wallet: Uniswap quote predicts ${predictedUPC.toString()} UPC ` +
+                        `from ${nativeAmountETH.toString()} wei pETH, using ${effectiveBalance.toString()} (90%)`);
+                }
+            }
+        }
         let adjustedValue;
-        if (currentBalance > EVM_NATIVE_VALUE_TARGET + EVM_GAS_RESERVE) {
-            // Enough balance: cap at 200 UPC (pool estimate may be lower)
-            adjustedValue = nativeValueForGas < EVM_NATIVE_VALUE_TARGET
-                ? nativeValueForGas
-                : EVM_NATIVE_VALUE_TARGET;
+        if (effectiveBalance > EVM_NATIVE_VALUE_TARGET + EVM_GAS_RESERVE) {
+            adjustedValue = EVM_NATIVE_VALUE_TARGET;
         }
-        else if (currentBalance > EVM_GAS_RESERVE) {
-            // Low balance: use what's available minus reserve
-            const available = currentBalance - EVM_GAS_RESERVE;
-            adjustedValue = nativeValueForGas < available ? nativeValueForGas : available;
+        else if (effectiveBalance > EVM_GAS_RESERVE) {
+            adjustedValue = effectiveBalance - EVM_GAS_RESERVE;
         }
         else {
-            // Very low/zero balance (fresh wallet). The pool-price estimate (now in
-            // nativeValueForGas) is accurate. Fee-locking will deposit enough UPC
-            // because requiredFunds includes this value, and lockFee floors at $1.
             adjustedValue = nativeValueForGas;
         }
         if (adjustedValue !== nativeValueForGas) {
-            (0, context_1.printLog)(ctx, `executeUoaToCea — adjusting nativeValueForGas from ${nativeValueForGas.toString()} to ${adjustedValue.toString()} (UEA balance: ${currentBalance.toString()})`);
+            (0, context_1.printLog)(ctx, `executeUoaToCea — adjusting nativeValueForGas from ${nativeValueForGas.toString()} ` +
+                `to ${adjustedValue.toString()} (effective balance: ${effectiveBalance.toString()})`);
             nativeValueForGas = adjustedValue;
         }
         // Build outbound multicalls (approve burn + sendUniversalTxOutbound with native value)
@@ -360,17 +364,11 @@ function executeUoaToCea(ctx, params, executeFn) {
         // This handles fee-locking on origin chain and executes the multicall from UEA context
         // Sum native values from multicall entries for proper fee calculation
         const multicallNativeValue = pushChainMulticalls.reduce((sum, mc) => { var _a; return sum + ((_a = mc.value) !== null && _a !== void 0 ? _a : BigInt(0)); }, BigInt(0));
-        const executeParams = {
-            to: ueaAddress, // multicall executes from UEA
-            value: multicallNativeValue, // ensures correct requiredFunds calculation
-            data: pushChainMulticalls, // array triggers multicall mode
-            _ueaStatus: {
+        const executeParams = Object.assign({ to: ueaAddress, value: multicallNativeValue, data: pushChainMulticalls, _ueaStatus: {
                 isDeployed: isUEADeployed,
                 nonce: ueaNonce,
                 balance: ueaBalance,
-            },
-            _skipFeeLocking: isUEADeployed, // skip fee-locking only if UEA is already deployed
-        };
+            }, _skipFeeLocking: isUEADeployed }, (!isUEADeployed ? { _minimumDepositUsd: ROUTE2_MINIMUM_DEPOSIT_USD } : {}));
         const response = yield executeFn(executeParams);
         // Add chain info to response
         response.chain = targetChain;
@@ -567,7 +565,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;
+        var _a, _b, _c, _d, _e, _f;
         // 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');
@@ -702,27 +700,24 @@ function executeCeaToPush(ctx, params, executeFn) {
         // CEA will self-execute this multicall (to=CEA, value=0)
         const ceaPayload = (0, payload_builders_1.buildCeaMulticallPayload)(ceaMulticalls);
         (0, context_1.printLog)(ctx, `executeCeaToPush — CEA payload (first 100 chars): ${ceaPayload.slice(0, 100)}...`);
-        // 8. Determine PRC-20 token for the outbound burn on Push Chain.
-        // For ERC20 flows (params.funds with token), use the token's PRC-20 (e.g. pUSDT)
-        // so the Vault deposits ERC20 to CEA. For native flows, use the chain's native PRC-20 (e.g. pBNB).
-        let prc20Token;
-        if (((_f = params.funds) === null || _f === void 0 ? void 0 : _f.amount) && params.funds.token) {
-            const token = params.funds.token;
-            prc20Token = push_chain_1.PushChain.utils.tokens.getPRC20Address(token);
-        }
-        else {
-            prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
-        }
-        // burnAmount = PRC20 to burn on Push Chain (NOT the bridge amount).
-        // Vault deposits burnAmount to CEA. CEA uses burnAmount + pre-existing balance for the bridge.
-        const burnAmount = amount;
+        // 8. Determine PRC-20 token for the outbound relay.
+        // Route 3: ALWAYS use native PRC-20 for chain namespace lookup + gas fees.
+        // The CEA uses its OWN pre-existing balance on the external chain to bridge
+        // tokens back — no PRC-20 burn is needed on Push Chain.
+        // burnAmount = 0 makes this a payload-only outbound relay.
+        //
+        // Previously this burned pUSDT/pToken equal to the bridge amount, which failed
+        // because the UEA never holds pUSDT — the whole point of Route 3 is to get
+        // tokens FROM the CEA back to Push Chain, not to round-trip them.
+        const prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
+        const burnAmount = BigInt(0);
         (0, context_1.printLog)(ctx, `executeCeaToPush — prc20Token: ${prc20Token}, burnAmount: ${burnAmount.toString()}`);
         // 9. Build outbound request (same structure as Route 2)
         // target = CEA address (for self-execution), value = 0 in payload
         const outboundReq = (0, payload_builders_1.buildOutboundRequest)(ceaAddress, // target: CEA address (to=CEA for self-execution)
         prc20Token, // token: native PRC-20 for source chain (for namespace lookup)
-        burnAmount, // amount: 1 wei (precompile workaround)
-        (_g = params.gasLimit) !== null && _g !== void 0 ? _g : BigInt(0), ceaPayload, // payload: ABI-encoded CEA multicall
+        burnAmount, // amount: 0 (payload-only, CEA uses its own balance)
+        (_f = params.gasLimit) !== null && _f !== void 0 ? _f : BigInt(0), ceaPayload, // payload: ABI-encoded CEA multicall
         ueaAddress // revertRecipient: UEA
         );
         (0, context_1.printLog)(ctx, `executeCeaToPush — outbound request: ${JSON.stringify({
@@ -759,9 +754,43 @@ function executeCeaToPush(ctx, params, executeFn) {
         const currentBalance = ueaBalance;
         // Cosmos-EVM tx overhead costs ~1 PC per operation; 3 PC covers approve(s) + buffer.
         const OUTBOUND_GAS_RESERVE_R3 = BigInt(3e18);
-        if (currentBalance > OUTBOUND_GAS_RESERVE_R3 && currentBalance - OUTBOUND_GAS_RESERVE_R3 > nativeValueForGas) {
-            const adjustedValue = currentBalance - OUTBOUND_GAS_RESERVE_R3;
-            (0, context_1.printLog)(ctx, `executeCeaToPush — adjusting nativeValueForGas from ${nativeValueForGas.toString()} to ${adjustedValue.toString()} (UEA balance: ${currentBalance.toString()})`);
+        const ROUTE3_MINIMUM_DEPOSIT_USD = utils_1.Utils.helpers.parseUnits('10', 8); // $10
+        // For fresh wallets: predict post-fee-locking UPC balance using the same
+        // Uniswap V3 quoter the chain uses (pETH → WPC swap), matching Route 2 logic.
+        let effectiveBalance = currentBalance;
+        if (!isUEADeployed && effectiveBalance <= OUTBOUND_GAS_RESERVE_R3) {
+            const signerChain = ctx.universalSigner.account.chain;
+            const ethPrice = yield new price_fetch_1.PriceFetch(ctx.rpcUrls).getPrice(signerChain);
+            const nativeAmountETH = ethPrice > BigInt(0)
+                ? (ROUTE3_MINIMUM_DEPOSIT_USD * BigInt(1e18) + (ethPrice - BigInt(1))) / ethPrice + BigInt(1)
+                : BigInt(0);
+            if (nativeAmountETH > BigInt(0)) {
+                const originPrc20 = (0, helpers_1.getNativePRC20ForChain)(signerChain, ctx.pushNetwork);
+                const predictedUPC = yield (0, gas_calculator_1.estimateDepositFromLockedNative)(ctx, nativeAmountETH, originPrc20);
+                if (predictedUPC > BigInt(0)) {
+                    effectiveBalance = (predictedUPC * BigInt(90)) / BigInt(100);
+                    (0, context_1.printLog)(ctx, `executeCeaToPush — fresh wallet: Uniswap quote predicts ${predictedUPC.toString()} UPC ` +
+                        `from ${nativeAmountETH.toString()} wei pETH, using ${effectiveBalance.toString()} (90%)`);
+                }
+            }
+        }
+        // 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;
+        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 {
+            adjustedValue = nativeValueForGas;
+        }
+        if (adjustedValue !== nativeValueForGas) {
+            (0, context_1.printLog)(ctx, `executeCeaToPush — adjusting nativeValueForGas from ${nativeValueForGas.toString()} to ${adjustedValue.toString()} (effective balance: ${effectiveBalance.toString()})`);
             nativeValueForGas = adjustedValue;
         }
         // 12. Build Push Chain multicalls (approvals + sendUniversalTxOutbound)
@@ -778,17 +807,11 @@ function executeCeaToPush(ctx, params, executeFn) {
         // Sum native values from multicall entries for proper fee calculation
         const multicallNativeValue = pushChainMulticalls.reduce((sum, mc) => { var _a; return sum + ((_a = mc.value) !== null && _a !== void 0 ? _a : BigInt(0)); }, BigInt(0));
         // 13. Execute through the normal execute() flow
-        const executeParams = {
-            to: ueaAddress,
-            value: multicallNativeValue, // ensures correct requiredFunds calculation
-            data: pushChainMulticalls,
-            _ueaStatus: {
+        const executeParams = Object.assign({ to: ueaAddress, value: multicallNativeValue, data: pushChainMulticalls, _ueaStatus: {
                 isDeployed: isUEADeployed,
                 nonce: ueaNonce,
                 balance: ueaBalance,
-            },
-            _skipFeeLocking: true, // outbound executes on Push Chain, no external fee locking
-        };
+            }, _skipFeeLocking: isUEADeployed }, (!isUEADeployed ? { _minimumDepositUsd: ROUTE3_MINIMUM_DEPOSIT_USD } : {}));
         const response = yield executeFn(executeParams);
         // Add Route 3 context to response
         response.chain = sourceChain;
@@ -826,7 +849,6 @@ function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
         // Determine drain amount and token
         let drainAmount = BigInt(0);
         let tokenMintHex;
-        let prc20Token;
         if (((_a = params.funds) === null || _a === void 0 ? void 0 : _a.amount) && params.funds.amount > BigInt(0)) {
             // SPL token drain
             drainAmount = params.funds.amount;
@@ -835,22 +857,15 @@ function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
                 // Convert SPL mint address to 32-byte hex
                 const mintPk = new web3_js_1.PublicKey(token.address);
                 tokenMintHex = ('0x' + Buffer.from(mintPk.toBytes()).toString('hex'));
-                prc20Token = push_chain_1.PushChain.utils.tokens.getPRC20Address(token);
-            }
-            else {
-                prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
             }
         }
         else if (params.value && params.value > BigInt(0)) {
             // Native SOL drain
             drainAmount = params.value;
-            prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
-        }
-        else {
-            // Payload-only Route 3 SVM: no funds to drain, just execute data on Push Chain
-            drainAmount = BigInt(0);
-            prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
         }
+        // Route 3 SVM: ALWAYS use native PRC-20 for chain namespace lookup + gas fees.
+        // CEA uses its own pre-existing balance — no PRC-20 burn needed on Push Chain.
+        const prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
         // Build the SVM CPI payload (send_universal_tx_to_uea wrapped in execute)
         // If params.data is provided, pass it as extraPayload for Push Chain execution
         let extraPayload;
@@ -922,17 +937,11 @@ function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
         // Sum native values from multicall entries for proper fee calculation
         const multicallNativeValue = pushChainMulticalls.reduce((sum, mc) => { var _a; return sum + ((_a = mc.value) !== null && _a !== void 0 ? _a : BigInt(0)); }, BigInt(0));
         // Execute through the normal execute() flow
-        const executeParams = {
-            to: ueaAddress,
-            value: multicallNativeValue, // ensures correct requiredFunds calculation
-            data: pushChainMulticalls,
-            _ueaStatus: {
+        const executeParams = Object.assign({ to: ueaAddress, value: multicallNativeValue, data: pushChainMulticalls, _ueaStatus: {
                 isDeployed: isUEADeployed,
                 nonce: ueaNonce,
                 balance: ueaBalance,
-            },
-            _skipFeeLocking: true, // outbound executes on Push Chain, no external fee locking
-        };
+            }, _skipFeeLocking: isUEADeployed }, (!isUEADeployed ? { _minimumDepositUsd: utils_1.Utils.helpers.parseUnits('10', 8) } : {}));
         const response = yield executeFn(executeParams);
         // Add Route 3 SVM context to response
         response.chain = sourceChain;
@@ -1080,28 +1089,19 @@ function buildPayloadForRoute(ctx, params, route, nonce) {
                     const gatewayProgramHex = ('0x' + Buffer.from(programPk.toBytes()).toString('hex'));
                     let drainAmount = BigInt(0);
                     let tokenMintHex;
-                    let prc20Token;
                     if (((_j = params.funds) === null || _j === void 0 ? void 0 : _j.amount) && params.funds.amount > BigInt(0)) {
                         drainAmount = params.funds.amount;
                         const token = params.funds.token;
                         if (token && token.address) {
                             const mintPk = new web3_js_1.PublicKey(token.address);
                             tokenMintHex = ('0x' + Buffer.from(mintPk.toBytes()).toString('hex'));
-                            prc20Token = push_chain_1.PushChain.utils.tokens.getPRC20Address(token);
-                        }
-                        else {
-                            prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
                         }
                     }
                     else if (params.value && params.value > BigInt(0)) {
                         drainAmount = params.value;
-                        prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
-                    }
-                    else {
-                        // Payload-only Route 3 SVM: no funds to drain, just execute data on Push Chain
-                        drainAmount = BigInt(0);
-                        prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
                     }
+                    // Route 3 SVM: ALWAYS use native PRC-20, CEA uses its own balance.
+                    const prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
                     // Derive CEA PDA as revert recipient
                     const ueaBytes2 = Buffer.from(ueaAddress.slice(2), 'hex');
                     const [ceaPda2] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from('push_identity'), ueaBytes2], programPk);
@@ -1189,9 +1189,9 @@ function buildPayloadForRoute(ctx, params, route, nonce) {
                 ceaMulticalls.push(sendCall);
                 const ceaPayload = (0, payload_builders_1.buildCeaMulticallPayload)(ceaMulticalls);
                 const prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
-                // burnAmount = actual amount needed by CEA. Vault deposits this as msg.value.
-                // Fallback to BigInt(1) for payload-only outbound (precompile rejects amount=0).
-                const burnAmount = amount > BigInt(0) ? amount : BigInt(1);
+                // Route 3: CEA uses its own pre-existing balance — no PRC-20 burn needed.
+                // burnAmount = 0 makes this a payload-only outbound relay.
+                const burnAmount = BigInt(0);
                 const outboundReq = (0, payload_builders_1.buildOutboundRequest)(ceaAddress, prc20Token, burnAmount, (_o = params.gasLimit) !== null && _o !== void 0 ? _o : BigInt(0), ceaPayload, ueaAddress);
                 return { payload: ceaPayload, gatewayRequest: outboundReq };
             }

package/src/lib/orchestrator/orchestrator.types.d.ts

@@ -106,6 +106,14 @@ export type ExecuteParams = {
      * @internal
      */
     _skipFeeLocking?: boolean;
+    /**
+     * Internal: Minimum fee-locking deposit in USD (8 decimals).
+     * Overrides the default $1 floor when the caller needs a larger deposit
+     * (e.g., Route 2 needs enough UPC for the outbound swap).
+     * Still capped at $10 by lockFee.
+     * @internal
+     */
+    _minimumDepositUsd?: bigint;
 };
 /**
  * New Universal Transaction Receipt interface with prioritized field ordering