@pushchain/core 5.1.4-alpha.0 → 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

@@ -13,7 +13,15 @@ export declare function queryOutboundGasFee(ctx: OrchestratorContext, prc20Token
     protocolFee: bigint;
     nativeValueForGas: bigint;
     gasPrice: bigint;
+    universalCoreAddress: `0x${string}`;
 }>;
+/**
+ * Estimate the native WPC amount needed to swap for `gasFee` of `gasToken`
+ * by reading the Uniswap V3 pool price on Push Chain.
+ * Returns the estimated amount with a 2x safety buffer (excess is refunded by the contract).
+ * Falls back to a percentage of accountBalance if any on-chain query fails.
+ */
+export declare function estimateNativeValueForSwap(ctx: OrchestratorContext, universalCoreAddress: `0x${string}`, gasToken: `0x${string}`, gasFee: bigint, accountBalance: bigint): Promise<bigint>;
 export declare function queryRescueGasFee(ctx: OrchestratorContext, prc20Token: `0x${string}`): Promise<{
     gasToken: `0x${string}`;
     gasFee: bigint;
@@ -28,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

@@ -6,9 +6,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureErc20Allowance = ensureErc20Allowance;
 exports.queryOutboundGasFee = queryOutboundGasFee;
+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");
@@ -24,6 +26,43 @@ const context_1 = require("./context");
 const helpers_1 = require("./helpers");
 /** Buffer multiplier for nativeValueForGas. Excess is refunded by swapAndBurnGas to the UEA. */
 const GAS_FEE_BUFFER_MULTIPLIER = BigInt(1000000);
+// Minimal ABIs for Uniswap V3 pool price estimation
+const UNISWAP_V3_POOL_SLOT0_ABI = [
+    {
+        type: 'function',
+        name: 'slot0',
+        inputs: [],
+        outputs: [
+            { name: 'sqrtPriceX96', type: 'uint160', internalType: 'uint160' },
+            { name: 'tick', type: 'int24', internalType: 'int24' },
+            { name: 'observationIndex', type: 'uint16', internalType: 'uint16' },
+            { name: 'observationCardinality', type: 'uint16', internalType: 'uint16' },
+            { name: 'observationCardinalityNext', type: 'uint16', internalType: 'uint16' },
+            { name: 'feeProtocol', type: 'uint8', internalType: 'uint8' },
+            { name: 'unlocked', type: 'bool', internalType: 'bool' },
+        ],
+        stateMutability: 'view',
+    },
+];
+const UNISWAP_V3_FACTORY_ABI = [
+    {
+        type: 'function',
+        name: 'getPool',
+        inputs: [
+            { name: 'tokenA', type: 'address', internalType: 'address' },
+            { name: 'tokenB', type: 'address', internalType: 'address' },
+            { name: 'fee', type: 'uint24', internalType: 'uint24' },
+        ],
+        outputs: [{ name: 'pool', type: 'address', internalType: 'address' }],
+        stateMutability: 'view',
+    },
+];
+const UNIVERSAL_CORE_SWAP_HELPERS_ABI = [
+    { type: 'function', name: 'WPC', inputs: [], outputs: [{ name: '', type: 'address', internalType: 'address' }], stateMutability: 'view' },
+    { type: 'function', name: 'uniswapV3Factory', inputs: [], outputs: [{ name: '', type: 'address', internalType: 'address' }], stateMutability: 'view' },
+    { type: 'function', name: 'defaultFeeTier', inputs: [{ name: '', type: 'address', internalType: 'address' }], outputs: [{ name: '', type: 'uint24', internalType: 'uint24' }], stateMutability: 'view' },
+];
+const ZERO_ADDR = '0x0000000000000000000000000000000000000000';
 // ============================================================================
 // ERC-20 Allowance
 // ============================================================================
@@ -136,10 +175,113 @@ function queryOutboundGasFee(ctx, prc20Token, gasLimit) {
         }
         const nativeValueForGas = protocolFee + gasFee * GAS_FEE_BUFFER_MULTIPLIER;
         (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 5] using 1000000x buffer: nativeValueForGas=${nativeValueForGas}`);
-        return { gasToken, gasFee, protocolFee, nativeValueForGas, gasPrice };
+        return { gasToken, gasFee, protocolFee, nativeValueForGas, gasPrice, universalCoreAddress };
     });
 }
 // ============================================================================
+// Uniswap V3 Pool Price Estimation
+// ============================================================================
+/**
+ * Estimate the native WPC amount needed to swap for `gasFee` of `gasToken`
+ * by reading the Uniswap V3 pool price on Push Chain.
+ * Returns the estimated amount with a 2x safety buffer (excess is refunded by the contract).
+ * Falls back to a percentage of accountBalance if any on-chain query fails.
+ */
+function estimateNativeValueForSwap(ctx, universalCoreAddress, gasToken, gasFee, accountBalance) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const SWAP_BUFFER = BigInt(2); // 2x safety buffer; excess is refunded by swapAndBurnGas
+        const BALANCE_FALLBACK_DIVISOR = BigInt(10); // 10% of balance as fallback
+        const GAS_RESERVE = BigInt(3e18); // 3 UPC reserve for tx overhead
+        try {
+            // Read WPC, factory, and defaultFeeTier in parallel
+            const [wpcAddress, factoryAddress, 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: 'uniswapV3Factory',
+                    args: [],
+                }),
+                ctx.pushClient.readContract({
+                    address: universalCoreAddress,
+                    abi: UNIVERSAL_CORE_SWAP_HELPERS_ABI,
+                    functionName: 'defaultFeeTier',
+                    args: [gasToken],
+                }),
+            ]);
+            if (!feeTier) {
+                (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — no fee tier for gasToken, using balance fallback`);
+                return balanceFallback(accountBalance, BALANCE_FALLBACK_DIVISOR, GAS_RESERVE);
+            }
+            // Get pool address from factory
+            const poolAddress = yield ctx.pushClient.readContract({
+                address: factoryAddress,
+                abi: UNISWAP_V3_FACTORY_ABI,
+                functionName: 'getPool',
+                args: [wpcAddress, gasToken, feeTier],
+            });
+            if (poolAddress === ZERO_ADDR) {
+                (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — pool not found, using balance fallback`);
+                return balanceFallback(accountBalance, BALANCE_FALLBACK_DIVISOR, GAS_RESERVE);
+            }
+            // Read slot0 for current price
+            const slot0 = yield ctx.pushClient.readContract({
+                address: poolAddress,
+                abi: UNISWAP_V3_POOL_SLOT0_ABI,
+                functionName: 'slot0',
+                args: [],
+            });
+            const sqrtPriceX96 = slot0[0];
+            if (!sqrtPriceX96 || sqrtPriceX96 === BigInt(0)) {
+                (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — pool not initialized, using balance fallback`);
+                return balanceFallback(accountBalance, BALANCE_FALLBACK_DIVISOR, GAS_RESERVE);
+            }
+            // price (token1/token0 in raw units) = (sqrtPriceX96)² / 2¹⁹²
+            const Q192 = BigInt(1) << BigInt(192);
+            const priceNum = sqrtPriceX96 * sqrtPriceX96; // sqrtPrice² in Q192
+            // Uniswap V3 sorts tokens: token0 < token1 by address
+            const isGasTokenToken0 = gasToken.toLowerCase() < wpcAddress.toLowerCase();
+            let wpcNeeded;
+            if (isGasTokenToken0) {
+                // price = WPC_per_gasToken → wpcNeeded = gasFee * price
+                wpcNeeded = (gasFee * priceNum) / Q192;
+            }
+            else {
+                // price = gasToken_per_WPC → wpcNeeded = gasFee / price
+                wpcNeeded = (gasFee * Q192) / priceNum;
+            }
+            const result = wpcNeeded * SWAP_BUFFER;
+            (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — pool=${poolAddress}, sqrtPriceX96=${sqrtPriceX96}, ` +
+                `wpcNeeded=${wpcNeeded}, withBuffer(2x)=${result}`);
+            // Cap at (balance - reserve)
+            if (accountBalance > result + GAS_RESERVE) {
+                return result;
+            }
+            else if (accountBalance > GAS_RESERVE) {
+                return accountBalance - GAS_RESERVE;
+            }
+            return result; // let caller decide if balance is too low
+        }
+        catch (err) {
+            (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — failed: ${err instanceof Error ? err.message : String(err)}, using balance fallback`);
+            return balanceFallback(accountBalance, BALANCE_FALLBACK_DIVISOR, GAS_RESERVE);
+        }
+    });
+}
+function balanceFallback(balance, divisor, reserve) {
+    const fraction = balance / divisor;
+    if (balance > fraction + reserve)
+        return fraction;
+    if (balance > reserve)
+        return balance - reserve;
+    return fraction;
+}
+// ============================================================================
 // Rescue Gas Fee Query
 // ============================================================================
 function queryRescueGasFee(ctx, prc20Token) {
@@ -280,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

@@ -27,6 +27,7 @@ const context_1 = require("./context");
  */
 function sendPushTx(ctx, execute, eventBuffer, transformFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
         if (Array.isArray(execute.data)) {
             const PUSH_CHAIN_GAS_LIMIT = BigInt(500000);
             const MAX_NONCE_RETRIES = 3;
@@ -73,7 +74,29 @@ function sendPushTx(ctx, execute, eventBuffer, transformFn) {
                     hash: lastTxHash,
                 });
                 if (receipt.status === 'reverted') {
-                    throw new Error(`sendPushTx — multicall operation ${i + 1}/${calls.length} reverted (to: ${call.to}, txHash: ${lastTxHash})`);
+                    // Simulate the failed call to extract the revert reason
+                    let revertReason = 'unknown';
+                    try {
+                        yield ctx.pushClient.publicClient.call({
+                            to: call.to,
+                            data: (call.data || '0x'),
+                            value: call.value,
+                            account: ctx.universalSigner.account.address,
+                            blockNumber: receipt.blockNumber,
+                        });
+                    }
+                    catch (simErr) {
+                        // viem decodes common revert reasons into shortMessage
+                        revertReason =
+                            (simErr === null || simErr === void 0 ? void 0 : simErr.shortMessage) || ((_a = simErr === null || simErr === void 0 ? void 0 : simErr.cause) === null || _a === void 0 ? void 0 : _a.reason) || ((_b = simErr === null || simErr === void 0 ? void 0 : simErr.cause) === null || _b === void 0 ? void 0 : _b.message) || (simErr === null || simErr === void 0 ? void 0 : simErr.message) || String(simErr);
+                        // Also log the raw revert data if available
+                        const revertData = ((_c = simErr === null || simErr === void 0 ? void 0 : simErr.cause) === null || _c === void 0 ? void 0 : _c.data) || (simErr === null || simErr === void 0 ? void 0 : simErr.data);
+                        if (revertData) {
+                            revertReason += ` [data: ${revertData}]`;
+                        }
+                    }
+                    (0, context_1.printLog)(ctx, `sendPushTx — multicall operation ${i + 1}/${calls.length} reverted (to: ${call.to}, txHash: ${lastTxHash}, revertReason: ${revertReason})`);
+                    throw new Error(`sendPushTx — multicall operation ${i + 1}/${calls.length} reverted (to: ${call.to}, txHash: ${lastTxHash}, revertReason: ${revertReason})`);
                 }
                 (0, context_1.printLog)(ctx, `sendPushTx — operation ${i + 1}/${calls.length} confirmed in block ${receipt.blockNumber}`);
                 nonce++;