@pushchain/core 5.1.4-alpha.1 → 5.1.4-alpha.10

package/src/lib/index.d.ts

@@ -1,7 +1,7 @@
 import { PushChain } from './push-chain/push-chain';
 export type { ConversionQuote } from './constants/tokens';
 export type { UniversalSigner, UniversalAccount, UniversalSignerSkeleton, DerivedExecutorAccount, ResolvedAccount, ResolvedControllerAccounts, AccountType, AccountRole, } from './universal/universal.types';
-export type { ChainTarget, ChainSource, UniversalTo, TransactionRouteType, UniversalExecuteParams, UniversalOutboundTxRequest, PreparedUniversalTx, CascadedTransactionBuilder, CascadedTxResponse, CascadeHopInfo, CascadeTrackOptions, CascadeProgressEvent, CascadeCompletionResult, MultiChainTxResponse, OutboundTxDetails, WaitForOutboundOptions, SvmGatewayAccountMeta, SvmExecutePayloadFields, SvmExecuteParams, AccountStatus, UEAStatus, RescueFundsParams, } from './orchestrator/orchestrator.types';
+export type { ChainTarget, ChainSource, UniversalTo, TransactionRouteType, UniversalExecuteParams, UniversalOutboundTxRequest, PreparedUniversalTx, CascadedTxResponse, CascadeHopInfo, CascadeTrackOptions, CascadeProgressEvent, CascadeCompletionResult, MultiChainTxResponse, OutboundTxDetails, WaitForOutboundOptions, SvmGatewayAccountMeta, SvmExecutePayloadFields, SvmExecuteParams, AccountStatus, UEAStatus, RescueFundsParams, } from './orchestrator/orchestrator.types';
 export { parseUEAVersion } from './orchestrator/orchestrator.types';
 export { TransactionRoute, detectRoute, isChainTarget } from './orchestrator/route-detector';
 export { getCEAAddress, getPushAccountForCEA, isCEA, chainSupportsCEA, chainSupportsOutbound, getCEAFactoryAddress, getAllCEAAddresses, } from './orchestrator/cea-utils';

package/src/lib/orchestrator/internals/cascade.d.ts

@@ -5,7 +5,7 @@
  * getSegmentType, composeCascade, createCascadedBuilder, createChainedBuilder.
  */
 import { TransactionRoute } from '../route-detector';
-import type { HopDescriptor, CascadeSegment, CascadeSegmentType, PreparedUniversalTx, CascadedTransactionBuilder, CascadeHopInfo, UniversalTxResponse, UniversalExecuteParams, MultiCall, WaitForOutboundOptions, OutboundTxDetails } from '../orchestrator.types';
+import type { HopDescriptor, CascadeSegment, CascadeSegmentType, PreparedUniversalTx, CascadedTxResponse, CascadeHopInfo, UniversalTxResponse, UniversalExecuteParams, MultiCall, WaitForOutboundOptions, OutboundTxDetails } from '../orchestrator.types';
 import type { OrchestratorContext } from './context';
 export interface CascadeCallbacks {
     executeFn: (params: any) => Promise<UniversalTxResponse>;
@@ -20,4 +20,6 @@ export declare function buildHopDescriptor(ctx: OrchestratorContext, params: Uni
 export declare function classifyIntoSegments(hops: HopDescriptor[]): CascadeSegment[];
 export declare function getSegmentType(route: string): CascadeSegmentType;
 export declare function composeCascade(ctx: OrchestratorContext, segments: CascadeSegment[], ueaAddress: `0x${string}`, ueaBalance?: bigint, ueaNonce?: bigint): MultiCall[];
-export declare function createCascadedBuilder(ctx: OrchestratorContext, preparedTxs: PreparedUniversalTx[], callbacks: CascadeCallbacks): CascadedTransactionBuilder;
+export declare function createCascadedBuilder(ctx: OrchestratorContext, preparedTxs: PreparedUniversalTx[], callbacks: CascadeCallbacks): {
+    send: () => Promise<CascadedTxResponse>;
+};

package/src/lib/orchestrator/internals/cascade.js

@@ -37,16 +37,28 @@ function prepareTransaction(ctx, params, callbacks) {
             clientChain: ctx.universalSigner.account.chain,
         });
         const route = (0, route_detector_1.detectRoute)(params);
-        // Skip getCode if accountStatusCache already confirmed deployment
+        // Push native EOA: block Route 1 — use sendTransaction() for direct Push calls
+        const signerChain = ctx.universalSigner.account.chain;
+        const isPushNativeEOA = (0, helpers_1.isPushChain)(signerChain);
+        if (isPushNativeEOA && route === route_detector_1.TransactionRoute.UOA_TO_PUSH) {
+            throw new Error('Push native accounts cannot use prepareTransaction for Push Chain transactions. ' +
+                'Use sendTransaction() instead for direct Push Chain calls.');
+        }
+        // Fetch UEA nonce (skip for Push native EOA — uses EVM nonce, not UEA contract nonce)
         let nonce;
-        const deployedHintCascade = (_b = (_a = ctx.accountStatusCache) === null || _a === void 0 ? void 0 : _a.uea) === null || _b === void 0 ? void 0 : _b.deployed;
         const ueaAddress = (0, uea_manager_1.computeUEAOffchain)(ctx);
-        if (deployedHintCascade) {
-            nonce = yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress);
+        if (isPushNativeEOA) {
+            nonce = BigInt(0);
         }
         else {
-            const status = yield (0, uea_manager_1.getUeaStatusAndNonce)(ctx);
-            nonce = status.nonce;
+            const deployedHintCascade = (_b = (_a = ctx.accountStatusCache) === null || _a === void 0 ? void 0 : _a.uea) === null || _b === void 0 ? void 0 : _b.deployed;
+            if (deployedHintCascade) {
+                nonce = yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress);
+            }
+            else {
+                const status = yield (0, uea_manager_1.getUeaStatusAndNonce)(ctx);
+                nonce = status.nonce;
+            }
         }
         // Build the payload based on route
         const { payload, gatewayRequest } = yield (0, route_handlers_1.buildPayloadForRoute)(ctx, params, route, nonce);
@@ -62,8 +74,6 @@ function prepareTransaction(ctx, params, callbacks) {
             nonce,
             deadline,
             _hop: hop,
-            thenOn: (nextTx) => createCascadedBuilder(ctx, [prepared, nextTx], callbacks),
-            send: () => callbacks.executeFn(params),
         };
         return prepared;
     });
@@ -222,8 +232,13 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                     burnAmount = params.value;
                 }
                 else if (params.data) {
+                    // PAYLOAD-only (no value transfer): still need native PRC-20 token for
+                    // chain namespace lookup + gas fees, but burn amount must be zero.
+                    // Matches the direct executeUoaToCea path (route-handlers.ts).
+                    // Using burnAmount=1 would trigger transferFrom on the PRC-20 token,
+                    // which reverts when the UEA has no PRC-20 balance for that chain.
                     prc20Token = (0, helpers_1.getNativePRC20ForChain)(targetChain, ctx.pushNetwork);
-                    burnAmount = BigInt(1); // Minimum for precompile
+                    burnAmount = BigInt(0);
                 }
                 // Query gas fee
                 let gasToken = selectors_1.ZERO_ADDRESS;
@@ -285,10 +300,12 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                         gasToken = result.gasToken;
                         gasFee = result.gasFee;
                     }
-                    return Object.assign(Object.assign({}, baseDescriptor), { sourceChain, ceaAddress: ceaPdaHex, isSvmTarget: true, prc20Token, burnAmount: amount > BigInt(0) ? amount : BigInt(1), gasToken,
+                    return Object.assign(Object.assign({}, baseDescriptor), { sourceChain, ceaAddress: ceaPdaHex, isSvmTarget: true, prc20Token, burnAmount: amount, gasToken,
                         gasFee });
                 }
-                const { cea: ceaAddress, isDeployed } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, sourceChain, (_h = ctx.rpcUrls[sourceChain]) === null || _h === void 0 ? void 0 : _h[0]);
+                const { cea: ceaAddress } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, sourceChain, (_h = ctx.rpcUrls[sourceChain]) === null || _h === void 0 ? void 0 : _h[0]);
+                // CEA auto-deploys on-chain: Vault.finalizeUniversalTx calls CEAFactory.deployCEA()
+                // if CEA doesn't exist yet. No SDK-side blocking needed.
                 // Determine token/amount for the inbound
                 let tokenAddress = selectors_1.ZERO_ADDRESS;
                 let amount = BigInt(0);
@@ -321,7 +338,7 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                 }
                 return Object.assign(Object.assign({}, baseDescriptor), { sourceChain,
                     ceaAddress,
-                    prc20Token, burnAmount: amount > BigInt(0) ? amount : BigInt(1), gasToken,
+                    prc20Token, burnAmount: amount, gasToken,
                     gasFee });
             }
             default:
@@ -553,15 +570,15 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
                             ? new Uint8Array(Buffer.from(intermediatePayload.slice(2), 'hex'))
                             : undefined,
                     });
-                    const burnAmount = BigInt(1);
+                    const svmBurnAmount = segment.totalBurnAmount || BigInt(0);
                     const outboundReq = (0, payload_builders_1.buildOutboundRequest)(gatewayProgramHex, segment.prc20Token ||
-                        (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork), burnAmount, (_g = segment.gasLimit) !== null && _g !== void 0 ? _g : BigInt(0), svmPayload, ueaAddress);
+                        (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork), svmBurnAmount, (_g = segment.gasLimit) !== null && _g !== void 0 ? _g : BigInt(0), svmPayload, ueaAddress);
                     const inboundGasFee = segment.gasFee || BigInt(0);
                     const outboundMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
                         prc20Token: segment.prc20Token ||
                             (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork),
                         gasToken: segment.gasToken || selectors_1.ZERO_ADDRESS,
-                        burnAmount,
+                        burnAmount: svmBurnAmount,
                         gasFee: inboundGasFee,
                         nativeValueForGas: perOutboundNativeValue !== null && perOutboundNativeValue !== void 0 ? perOutboundNativeValue : inboundGasFee * BigInt(1000),
                         gatewayPcAddress,
@@ -628,13 +645,13 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
                 // Wrap CEA multicall in outbound from Push Chain
                 const ceaPayload = (0, payload_builders_1.buildCeaMulticallPayload)(ceaMulticalls);
                 const outboundReq = (0, payload_builders_1.buildOutboundRequest)(ceaAddress, segment.prc20Token ||
-                    (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork), segment.totalBurnAmount || BigInt(1), (_j = segment.gasLimit) !== null && _j !== void 0 ? _j : BigInt(0), ceaPayload, ueaAddress);
+                    (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork), segment.totalBurnAmount || BigInt(0), (_j = segment.gasLimit) !== null && _j !== void 0 ? _j : BigInt(0), ceaPayload, ueaAddress);
                 const inboundGasFee = segment.gasFee || BigInt(0);
                 const outboundMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
                     prc20Token: segment.prc20Token ||
                         (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork),
                     gasToken: segment.gasToken || selectors_1.ZERO_ADDRESS,
-                    burnAmount: segment.totalBurnAmount || BigInt(1),
+                    burnAmount: segment.totalBurnAmount || BigInt(0),
                     gasFee: inboundGasFee,
                     nativeValueForGas: perOutboundNativeValue !== null && perOutboundNativeValue !== void 0 ? perOutboundNativeValue : inboundGasFee * BigInt(1000),
                     gatewayPcAddress,
@@ -653,7 +670,6 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
 // ============================================================================
 function createCascadedBuilder(ctx, preparedTxs, callbacks) {
     return {
-        thenOn: (nextTx) => createCascadedBuilder(ctx, [...preparedTxs, nextTx], callbacks),
         send: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
             const ueaAddress = (0, uea_manager_1.computeUEAOffchain)(ctx);
             // Extract HopDescriptors

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

@@ -198,7 +198,11 @@ 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;
+            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/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");
@@ -255,11 +257,7 @@ function executeUoaToCea(ctx, params, executeFn) {
             ctx.pushClient.getBalance(ueaAddress),
         ]);
         const isUEADeployed = isNativePushEOA || ueaCode !== undefined;
-        if (!isUEADeployed) {
-            throw new Error('UEA is not deployed. Please send an inbound transaction to Push Chain first ' +
-                '(e.g. sendTransaction with value) to deploy your Universal Execution Account before using outbound transfers.');
-        }
-        const ueaNonce = isNativePushEOA ? BigInt(0) : yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress);
+        const ueaNonce = (!isUEADeployed || isNativePushEOA) ? BigInt(0) : yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress);
         // Build the multicall that will execute ON Push Chain from UEA context
         // This includes: 1) approve PRC-20 (if needed), 2) call sendUniversalTxOutbound
         const pushChainMulticalls = [];
@@ -267,41 +265,62 @@ function executeUoaToCea(ctx, params, executeFn) {
         let gasFee = BigInt(0);
         let nativeValueForGas = BigInt(0);
         let gasToken = selectors_1.ZERO_ADDRESS;
+        let universalCoreAddress;
         if (prc20Token !== selectors_1.ZERO_ADDRESS) {
             try {
                 const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, outboundReq.gasLimit);
                 gasFee = result.gasFee;
                 gasToken = result.gasToken;
                 nativeValueForGas = result.nativeValueForGas;
+                universalCoreAddress = result.universalCoreAddress;
                 (0, context_1.printLog)(ctx, `executeUoaToCea — queried gas fee: ${gasFee.toString()}, gasToken: ${gasToken}, nativeValueForGas: ${nativeValueForGas.toString()}`);
             }
             catch (err) {
                 throw new Error(`Failed to query outbound gas fee: ${err}`);
             }
         }
-        // Adjust nativeValueForGas: the 1Mx multiplier from queryOutboundGasFee produces
-        // a value far too low for the actual WPC/gasToken swap price. Set it to 200 UPC
-        // (capped by balance) — enough for the swap, but avoids draining thin pools.
-        // The contract's swapAndBurnGas does exactOutputSingle and refunds excess PC.
+        // Balance-aware adjustment: MAXIMIZE nativeValueForGas within available balance.
+        // The contract's swapAndBurnGas does exactOutputSingle and refunds excess PC,
+        // 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
-        // Reuse ueaBalance fetched earlier (line 383) — no tx sent between, balance is stable
-        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: use 200 UPC 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
-            adjustedValue = currentBalance - EVM_GAS_RESERVE;
+        else if (effectiveBalance > EVM_GAS_RESERVE) {
+            adjustedValue = effectiveBalance - EVM_GAS_RESERVE;
         }
         else {
-            // Very low balance: use original query value as-is
             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)
@@ -345,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: true, // outbound executes on Push Chain, no external fee locking
-        };
+            }, _skipFeeLocking: isUEADeployed }, (!isUEADeployed ? { _minimumDepositUsd: ROUTE2_MINIMUM_DEPOSIT_USD } : {}));
         const response = yield executeFn(executeParams);
         // Add chain info to response
         response.chain = targetChain;
@@ -463,11 +476,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
             isUEADeployed = ueaCode !== undefined;
             ueaBalance = balance;
         }
-        if (!isUEADeployed) {
-            throw new Error('UEA is not deployed. Please send an inbound transaction to Push Chain first ' +
-                '(e.g. sendTransaction with value) to deploy your Universal Execution Account before using outbound transfers.');
-        }
-        const ueaNonce = isNativePushEOASvm ? BigInt(0) : yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress);
+        const ueaNonce = (!isUEADeployed || isNativePushEOASvm) ? BigInt(0) : yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress);
         // --- Query gas fee (identical to EVM path) ---
         let gasFee = BigInt(0);
         let gasToken = selectors_1.ZERO_ADDRESS;
@@ -531,7 +540,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
                 nonce: ueaNonce,
                 balance: ueaBalance,
             },
-            _skipFeeLocking: true, // outbound executes on Push Chain, no external fee locking
+            _skipFeeLocking: isUEADeployed, // skip fee-locking only if UEA is already deployed
         };
         const response = yield executeFn(executeParams);
         // Add chain info to response
@@ -577,10 +586,8 @@ function executeCeaToPush(ctx, params, executeFn) {
         // 4. Get CEA address on source chain
         const { cea: ceaAddress, isDeployed: ceaDeployed } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, sourceChain, (_b = ctx.rpcUrls[sourceChain]) === null || _b === void 0 ? void 0 : _b[0]);
         (0, context_1.printLog)(ctx, `executeCeaToPush — sourceChain: ${sourceChain}, CEA: ${ceaAddress}, deployed: ${ceaDeployed}`);
-        if (!ceaDeployed) {
-            throw new Error(`CEA not deployed on ${sourceChain}. ` +
-                `Deploy CEA first using Route 2 (UOA -> CEA) before using Route 3.`);
-        }
+        // CEA auto-deploys on-chain: Vault.finalizeUniversalTx calls CEAFactory.deployCEA()
+        // if CEA doesn't exist yet. No SDK-side blocking needed.
         // 5. Get UniversalGateway address on source chain
         const gatewayAddress = chain_1.UNIVERSAL_GATEWAY_ADDRESSES[sourceChain];
         if (!gatewayAddress) {
@@ -617,7 +624,7 @@ function executeCeaToPush(ctx, params, executeFn) {
         // external chain), but that approach is racy: the balance can change between the SDK
         // query and relay execution, causing sendUniversalTxToUEA to revert with
         // InsufficientBalance. Pre-existing CEA funds remain parked and can be swept separately.
-        let bridgeAmount = amount;
+        const bridgeAmount = amount;
         // Note: CEA contract may reject amount=0 in sendUniversalTxToUEA.
         // Keeping bridgeAmount as-is (0) for payload-only to test precompile behavior.
         // For ERC20 tokens, add approve call for the bridge amount
@@ -943,7 +950,7 @@ function executeCeaToCea(ctx, params, executeFn) {
         // CEA -> CEA requires chaining Route 3 (CEA -> Push) and Route 2 (Push -> CEA)
         // This is a complex flow that requires coordination
         throw new Error('CEA -> CEA transactions are not yet fully implemented. ' +
-            'Use prepareTransaction().thenOn() to chain Route 3 -> Route 2 manually.');
+            'Use prepareTransaction() and executeTransactions() to chain Route 3 -> Route 2 manually.');
     });
 }
 // ---------------------------------------------------------------------------
@@ -1109,6 +1116,8 @@ function buildPayloadForRoute(ctx, params, route, nonce) {
                     return { payload: svmPayload, gatewayRequest: outboundReq };
                 }
                 const { cea: ceaAddress } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, sourceChain, (_l = ctx.rpcUrls[sourceChain]) === null || _l === void 0 ? void 0 : _l[0]);
+                // CEA auto-deploys on-chain: Vault.finalizeUniversalTx calls CEAFactory.deployCEA()
+                // if CEA doesn't exist yet. No SDK-side blocking needed.
                 const gatewayAddr = chain_1.UNIVERSAL_GATEWAY_ADDRESSES[sourceChain];
                 if (!gatewayAddr) {
                     throw new Error(`No UniversalGateway address configured for chain ${sourceChain}`);

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

@@ -4,7 +4,7 @@ import type { AccountStatus, UniversalTxResponse } from './orchestrator.types';
 import { ProgressEvent } from '../progress-hook/progress-hook.types';
 import { PushClient } from '../push-client/push-client';
 import type { UniversalAccount, UniversalSigner } from '../universal/universal.types';
-import { ExecuteParams, UniversalExecuteParams, PreparedUniversalTx, CascadedTransactionBuilder, RescueFundsParams } from './orchestrator.types';
+import { ExecuteParams, UniversalExecuteParams, PreparedUniversalTx, CascadedTxResponse, RescueFundsParams } from './orchestrator.types';
 export declare class Orchestrator {
     private readonly universalSigner;
     private pushNetwork;
@@ -79,9 +79,11 @@ export declare class Orchestrator {
      * The cascade composes all hops bottom-to-top into a single Push Chain tx.
      *
      * @param preparedTxs - Array of prepared transactions
-     * @returns CascadedTransactionBuilder
+     * @returns Object with send() method
      */
-    createCascadedBuilder(preparedTxs: PreparedUniversalTx[]): CascadedTransactionBuilder;
+    createCascadedBuilder(preparedTxs: PreparedUniversalTx[]): {
+        send: () => Promise<CascadedTxResponse>;
+    };
     /**
      * Queries gas fee for an outbound transaction from the UniversalCore contract.
      */

package/src/lib/orchestrator/orchestrator.js

@@ -129,7 +129,7 @@ class Orchestrator {
      */
     execute(params) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e;
+            var _a, _b, _c, _d;
             // Lazy UEA upgrade check
             try {
                 if (!this.accountStatusCache || !this.accountStatusCache.uea.loaded) {
@@ -166,16 +166,6 @@ class Orchestrator {
             try {
                 const rcb = () => this._getResponseCallbacks();
                 if (execute.funds) {
-                    const hasData = execute.data && execute.data !== '0x';
-                    const isSVM = ((_e = chain_1.CHAIN_INFO[this.ctx.universalSigner.account.chain]) === null || _e === void 0 ? void 0 : _e.vm) === enums_1.VM.SVM;
-                    // SVM two-phase: bridge funds first, then execute payload separately
-                    // (Push Chain node doesn't support FUNDS_AND_PAYLOAD payload decoding for SVM yet)
-                    if (hasData && isSVM) {
-                        const fundsOnly = Object.assign(Object.assign({}, execute), { data: undefined });
-                        yield (0, internals_1.executeFundsOnly)(this.ctx, fundsOnly, eventBuffer, rcb);
-                        const dataOnly = Object.assign(Object.assign({}, execute), { funds: undefined });
-                        return yield (0, internals_1.executeStandardPayload)(this.ctx, dataOnly, eventBuffer, rcb);
-                    }
                     return !hasData
                         ? yield (0, internals_1.executeFundsOnly)(this.ctx, execute, eventBuffer, rcb)
                         : yield (0, internals_1.executeFundsWithPayload)(this.ctx, execute, eventBuffer, rcb);
@@ -221,7 +211,7 @@ class Orchestrator {
      * The cascade composes all hops bottom-to-top into a single Push Chain tx.
      *
      * @param preparedTxs - Array of prepared transactions
-     * @returns CascadedTransactionBuilder
+     * @returns Object with send() method
      */
     createCascadedBuilder(preparedTxs) {
         return (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks());

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
@@ -465,10 +473,6 @@ export interface PreparedUniversalTx {
     deadline: bigint;
     /** Internal hop descriptor for cascade nesting @internal */
     _hop: HopDescriptor;
-    /** Chain additional transactions after this one (cascade) */
-    thenOn: (nextTx: PreparedUniversalTx) => CascadedTransactionBuilder;
-    /** Execute this prepared transaction */
-    send: () => Promise<UniversalTxResponse>;
 }
 /**
  * @deprecated Use CascadedTxResponse instead.
@@ -485,17 +489,6 @@ export interface MultiChainTxResponse {
         status: 'pending' | 'confirmed' | 'failed';
     }[];
 }
-/**
- * Builder for composing cascaded (nested) multi-chain transactions.
- * Each call to thenOn() adds another hop to the cascade.
- * send() composes all hops bottom-to-top and executes a single Push Chain tx.
- */
-export interface CascadedTransactionBuilder {
-    /** Add another hop to the cascade */
-    thenOn: (nextTx: PreparedUniversalTx) => CascadedTransactionBuilder;
-    /** Compose all hops bottom-to-top and execute the single initial tx */
-    send: () => Promise<CascadedTxResponse>;
-}
 /**
  * Response for cascaded multi-chain transactions.
  * Contains the initial tx and tracking info for all hops.

package/src/lib/progress-hook/progress-hook.js

@@ -35,7 +35,7 @@ const RAW_HOOKS = {
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_03_01]: () => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_03_01,
         title: 'Resolving UEA',
-        message: 'Resolving Execution Account (UEA) – computing address, checking deployment status and balance',
+        message: 'Resolving Executor Account (UEA) – computing address, checking deployment status and balance',
         response: null,
         level: 'INFO',
     }),

package/src/lib/push-chain/push-chain.d.ts

@@ -6,7 +6,7 @@ import { TypedData, TypedDataDomain } from 'viem';
 import { ProgressEvent } from '../progress-hook/progress-hook.types';
 import type { AccountStatus } from '../orchestrator/orchestrator.types';
 import { MoveableToken, PayableToken, ConversionQuote, MoveableTokenAccessor, PayableTokenAccessor } from '../constants/tokens';
-import type { PreparedUniversalTx, CascadedTransactionBuilder } from '../orchestrator/orchestrator.types';
+import type { PreparedUniversalTx, CascadedTxResponse } from '../orchestrator/orchestrator.types';
 /**
  * @class PushChain
  *
@@ -71,15 +71,14 @@ export declare class PushChain {
         sendTransaction: Orchestrator['execute'];
         /**
          * Prepare a universal transaction without executing it.
-         * Returns a PreparedUniversalTx that can be chained with thenOn() or sent.
+         * Returns a PreparedUniversalTx that can be passed to executeTransactions.
          */
         prepareTransaction: Orchestrator['prepareTransaction'];
         /**
-         * Execute multiple transactions in sequence across chains.
-         * Accepts PreparedUniversalTx (from prepareTransaction) and returns
-         * a CascadedTransactionBuilder that supports .thenOn() for chaining.
+         * Execute one or more prepared transactions as a cascade across chains.
+         * Accepts an array of PreparedUniversalTx (from prepareTransaction).
          */
-        executeTransactions: (firstTx: PreparedUniversalTx) => CascadedTransactionBuilder;
+        executeTransactions: (txs: PreparedUniversalTx[]) => Promise<CascadedTxResponse>;
         /**
          * Tracks a transaction by hash on Push Chain
          */

package/src/lib/push-chain/push-chain.js

@@ -87,12 +87,12 @@ class PushChain {
                 }
                 return orchestrator.prepareTransaction.bind(orchestrator)(params);
             },
-            executeTransactions: (firstTx) => {
+            executeTransactions: (txs) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 if (this.isReadMode) {
                     throw new Error('Read only mode cannot call executeTransactions function');
                 }
-                return orchestrator.createCascadedBuilder([firstTx]);
-            },
+                return orchestrator.createCascadedBuilder(txs).send();
+            }),
             trackTransaction: (txHash, options) => {
                 return orchestrator.trackTransaction.bind(orchestrator)(txHash, options);
             },
@@ -400,6 +400,7 @@ class PushChain {
             // Stored on instance so consumers can await it if needed: await client.accountStatusReady
             const ACCOUNT_STATUS_TIMEOUT = 30000;
             instance.accountStatusReady = Promise.race([
+                // eslint-disable-next-line @typescript-eslint/no-empty-function
                 instance.getAccountStatus().then(() => { }),
                 new Promise((_, reject) => setTimeout(() => reject(new Error('Account status fetch timed out')), ACCOUNT_STATUS_TIMEOUT)),
             ]).catch(() => {