@pushchain/core 5.1.5-alpha.0 → 5.1.5

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

@@ -23,6 +23,7 @@ const context_1 = require("./context");
 const helpers_1 = require("./helpers");
 const payload_builder_1 = require("./payload-builder");
 const signing_1 = require("./signing");
+const progress_hook_1 = require("../../progress-hook/progress-hook");
 const uea_manager_1 = require("./uea-manager");
 const confirmation_1 = require("./confirmation");
 const gateway_client_1 = require("./gateway-client");
@@ -31,37 +32,81 @@ 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");
+/**
+ * Encode a UniversalPayload for transport over the origin chain's gateway.
+ * - EVM origin → ABI encoding (chain decodes via DecodeUniversalPayloadEVM).
+ * - SVM origin → Borsh encoding (chain decodes via DecodeUniversalPayloadSolana).
+ *
+ * The encoded bytes are placed in the Solana gateway's UniversalTx event
+ * (or the EVM UniversalGateway's SendUniversalTx event) payload field. Push
+ * Chain's uexecutor module decodes from that same field using the source
+ * chain's namespace (see push-chain/x/uexecutor/types/decode_payload.go).
+ * Using the wrong encoder for SVM origin results in garbage fields — in
+ * particular gasLimit=0 — which surfaces as "intrinsic gas too low" when
+ * the chain calls executeUniversalTx on the (possibly lazy-deployed) UEA.
+ */
+function encodePayloadForOrigin(ctx, payload) {
+    const { vm } = chain_1.CHAIN_INFO[ctx.universalSigner.account.chain];
+    if (vm === enums_1.VM.SVM) {
+        const buf = (0, signing_1.encodeUniversalPayloadSvm)(payload);
+        return ('0x' + buf.toString('hex'));
+    }
+    return (0, signing_1.encodeUniversalPayload)(payload);
+}
 function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b;
+        var _a, _b, _c;
         const transformFn = (tx, buf = []) => (0, response_builder_1.transformToUniversalTxResponse)(ctx, tx, buf, getResponseCallbacks());
         // Set default value for value if undefined
         if (execute.value === undefined) {
             execute.value = BigInt(0);
         }
         const chain = ctx.universalSigner.account.chain;
-        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_01, chain, ctx.universalSigner.account.address);
+        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_101, chain, ctx.universalSigner.account.address);
         (0, helpers_1.validateMainnetConnection)(chain, ctx.pushClient.pushChainInfo.chainId);
+        // Gas estimation fires for both Push-to-Push and external-origin flows so
+        // reconstructProgressEvents (which always emits 102-01/02) and live execute
+        // stay in lockstep. For the Push-to-Push shortcut we have no origin-chain
+        // gas to estimate; surface the tx gas limit as the "cost" to match what
+        // the reconstruction path does (it reads universalTxResponse.gasLimit).
+        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_102_01);
         // Push to Push Tx
         if ((0, helpers_1.isPushChain)(chain)) {
-            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_07);
-            const tx = yield (0, push_chain_tx_1.sendPushTx)(ctx, execute, eventBuffer, transformFn);
-            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_01, [tx]);
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_102_02, (_a = execute.gasLimit) !== null && _a !== void 0 ? _a : BigInt(21000));
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_107);
+            let tx;
+            try {
+                tx = yield (0, push_chain_tx_1.sendPushTx)(ctx, execute, eventBuffer, transformFn);
+            }
+            catch (err) {
+                // Push Chain broadcast failed. Wallet rejection surfaces as 104-04;
+                // everything else (RPC fail, on-chain revert) as 199-02.
+                const errMsg = err instanceof Error ? err.message : String(err);
+                const { isUserDecline } = (0, progress_hook_1.classifyDeclineError)(errMsg);
+                (0, context_1.fireProgressHook)(ctx, isUserDecline ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04 : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
+                // Mark that a terminal-ish error hook has already fired so the
+                // outer orchestrator catch doesn't emit a second 199-02 on top.
+                ctx._routeTerminalEmitted = true;
+                if (!isUserDecline && !(err instanceof push_chain_tx_1.PushChainExecutionError)) {
+                    throw new push_chain_tx_1.PushChainExecutionError(errMsg);
+                }
+                throw err;
+            }
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_01, [tx]);
             return tx;
         }
         // Fetch Gas details and estimate cost of execution
-        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_02_01);
         const gasEstimate = execute.gasLimit || BigInt(1e7);
         const gasPrice = yield ctx.pushClient.getGasPrice();
         const requiredGasFee = gasEstimate * gasPrice;
         const requiredFunds = requiredGasFee + execute.value;
-        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_02_02, requiredFunds);
+        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_102_02, requiredFunds);
         // Fetch UEA Details (or use pre-fetched status if available)
         const UEA = (0, uea_manager_1.computeUEAOffchain)(ctx);
         let isUEADeployed;
         let nonce;
         let funds;
-        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_03_01);
+        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_103_01);
         if (execute._ueaStatus) {
             isUEADeployed = execute._ueaStatus.isDeployed;
             nonce = execute._ueaStatus.nonce;
@@ -69,7 +114,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
         }
         else {
             // Skip getCode if accountStatusCache already confirmed deployment
-            const deployedHint = (_b = (_a = ctx.accountStatusCache) === null || _a === void 0 ? void 0 : _a.uea) === null || _b === void 0 ? void 0 : _b.deployed;
+            const deployedHint = (_c = (_b = ctx.accountStatusCache) === null || _b === void 0 ? void 0 : _b.uea) === null || _c === void 0 ? void 0 : _c.deployed;
             if (deployedHint) {
                 const [balance, ueaNonce] = yield Promise.all([
                     ctx.pushClient.getBalance(UEA),
@@ -89,7 +134,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
                 funds = balance;
             }
         }
-        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_03_02, UEA, isUEADeployed);
+        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_103_02, UEA, isUEADeployed);
         // Validate and decode feeLockTxHash
         let feeLockTxHash = execute.feeLockTxHash;
         if (feeLockTxHash) {
@@ -122,7 +167,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             }, helpers_1.bigintReplacer));
             req = (0, payload_builder_1.buildUniversalTxRequest)(ctx.universalSigner.account.address, {
                 recipient: viem_1.zeroAddress, token: viem_1.zeroAddress, amount: BigInt(0),
-                payload: (0, signing_1.encodeUniversalPayload)(universalPayloadForReq),
+                payload: encodePayloadForOrigin(ctx, universalPayloadForReq),
             });
         }
         else {
@@ -151,7 +196,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
                     }, helpers_1.bigintReplacer));
                     req = (0, payload_builder_1.buildUniversalTxRequest)(ctx.universalSigner.account.address, {
                         recipient: viem_1.zeroAddress, token: viem_1.zeroAddress, amount: BigInt(0),
-                        payload: (0, signing_1.encodeUniversalPayload)(universalPayloadOther),
+                        payload: encodePayloadForOrigin(ctx, universalPayloadOther),
                     });
                 }
             }
@@ -172,7 +217,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
                 }, helpers_1.bigintReplacer));
                 req = (0, payload_builder_1.buildUniversalTxRequest)(ctx.universalSigner.account.address, {
                     recipient: viem_1.zeroAddress, token: viem_1.zeroAddress, amount: BigInt(0),
-                    payload: (0, signing_1.encodeUniversalPayload)(universalPayloadSelf),
+                    payload: encodePayloadForOrigin(ctx, universalPayloadSelf),
                 });
             }
         }
@@ -190,10 +235,21 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
         let verificationData;
         if (!feeLockingRequired) {
             const ueaVersion = yield (0, uea_manager_1.fetchUEAVersion)(ctx);
-            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_04_02);
-            const signature = yield (0, signing_1.signUniversalPayload)(ctx, universalPayload, UEA, ueaVersion);
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_02);
+            let signature;
+            try {
+                signature = yield (0, signing_1.signUniversalPayload)(ctx, universalPayload, UEA, ueaVersion);
+            }
+            catch (err) {
+                // Wallet decline, contract revert during sign, or RPC failure — the
+                // 104-04 builder's classifyDeclineError heuristic picks the right
+                // copy (real decline → "Verification Declined"; else "Signature Failed").
+                const errMsg = err instanceof Error ? err.message : String(err);
+                (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04, errMsg);
+                throw err;
+            }
             verificationData = (0, viem_1.bytesToHex)(signature);
-            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_04_03);
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_03);
         }
         else {
             // Fee Locking
@@ -299,7 +355,18 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
                     (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);
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_01);
+            let feeLockTxHashBytes;
+            try {
+                feeLockTxHashBytes = yield (0, gateway_client_1.lockFee)(ctx, effectiveLockAmountInUSD, universalPayload, req);
+            }
+            catch (err) {
+                // User declined the fee-lock tx submission or the origin-chain RPC
+                // rejected it — classifier picks decline vs generic signature failure.
+                const errMsg = err instanceof Error ? err.message : String(err);
+                (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04, errMsg);
+                throw err;
+            }
             feeLockTxHash = (0, viem_1.bytesToHex)(feeLockTxHashBytes);
             verificationData = (0, viem_1.bytesToHex)(feeLockTxHashBytes);
             const { vm } = chain_1.CHAIN_INFO[chain];
@@ -307,19 +374,63 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
                 ? bs58_1.bs58.encode(Buffer.from(feeLockTxHashBytes))
                 : feeLockTxHash;
             const originTx = yield (0, helpers_1.fetchOriginChainTransactionForProgress)(ctx, chain, feeLockTxHash, feeLockTxHashDisplay);
-            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_05_01, feeLockTxHashDisplay, originTx);
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_105_01, feeLockTxHashDisplay, originTx);
             yield (0, confirmation_1.waitForLockerFeeConfirmation)(ctx, feeLockTxHashBytes);
-            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_05_02);
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_105_02);
             const { defaultRPC, lockerContract } = chain_1.CHAIN_INFO[chain];
-            const pushChainUniversalTx = yield (0, response_builder_1.queryUniversalTxStatusFromGatewayTx)(ctx, new evm_client_1.EvmClient({ rpcUrls: ctx.rpcUrls[chain] || defaultRPC }), lockerContract, feeLockTxHash, 'sendTxWithGas');
-            const response = yield (0, push_chain_tx_1.extractPcTxAndTransform)(ctx, pushChainUniversalTx, feeLockTxHash, eventBuffer, 'sendTxWithGas', transformFn);
-            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_01, [response]);
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_107);
+            let response;
+            try {
+                const pushChainUniversalTx = yield (0, response_builder_1.queryUniversalTxStatusFromGatewayTx)(ctx, new evm_client_1.EvmClient({ rpcUrls: ctx.rpcUrls[chain] || defaultRPC }), lockerContract, feeLockTxHash, 'sendTxWithGas');
+                // extractPcTxAndTransform fires 199-02 itself on pcTx FAILED and throws
+                // PushChainExecutionError — don't double-emit. Anything else thrown
+                // here (gateway-tx lookup failure, RPC error) hasn't emitted 199-02
+                // yet, so the catch below surfaces it.
+                response = yield (0, push_chain_tx_1.extractPcTxAndTransform)(ctx, pushChainUniversalTx, feeLockTxHash, eventBuffer, 'sendTxWithGas', transformFn);
+            }
+            catch (err) {
+                if (!(err instanceof push_chain_tx_1.PushChainExecutionError)) {
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
+                    throw new push_chain_tx_1.PushChainExecutionError(errMsg, { gatewayTxHash: feeLockTxHash });
+                }
+                throw err;
+            }
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_01, [response]);
             return response;
         }
-        // Non-fee-locking path: Broadcasting Tx to PC via sendUniversalTx
-        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_07);
-        const transactions = yield (0, push_chain_tx_1.sendUniversalTx)(ctx, isUEADeployed, feeLockTxHash, universalPayload, verificationData, eventBuffer, transformFn);
-        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_01, transactions);
+        // Non-fee-locking path: Broadcasting Tx to PC via sendUniversalTx.
+        // Provide a resign callback so sendUniversalTx can recover from the
+        // UEA-nonce race: the EIP-712 hash uses the UEA's live storage nonce
+        // (not payload.nonce), so if anything advances it between our read and
+        // Cosmos inclusion the tx reverts with InvalidEVMSignature(0xc7dbd31d).
+        const resignOnSigMismatch = () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const freshNonce = yield (0, uea_manager_1.getUEANonce)(ctx, UEA);
+            const freshUeaVersion = yield (0, uea_manager_1.fetchUEAVersion)(ctx);
+            const freshPayload = JSON.parse(JSON.stringify(Object.assign(Object.assign({}, universalPayload), { nonce: freshNonce }), helpers_1.bigintReplacer));
+            const freshSig = yield (0, signing_1.signUniversalPayload)(ctx, freshPayload, UEA, freshUeaVersion);
+            return {
+                universalPayload: freshPayload,
+                verificationData: (0, viem_1.bytesToHex)(freshSig),
+            };
+        });
+        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_107);
+        let transactions;
+        try {
+            transactions = yield (0, push_chain_tx_1.sendUniversalTx)(ctx, isUEADeployed, feeLockTxHash, universalPayload, verificationData, eventBuffer, transformFn, resignOnSigMismatch);
+        }
+        catch (err) {
+            // Push Chain broadcast failed (Cosmos reject, UEA revert, nonce race
+            // exhaustion). Surface terminal 199-02 before re-throwing so the stream
+            // ends with the spec'd error hook. Typed PushChainExecutionError lets
+            // callers classify via instanceof without message sniffing.
+            const errMsg = err instanceof Error ? err.message : String(err);
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
+            if (err instanceof push_chain_tx_1.PushChainExecutionError)
+                throw err;
+            throw new push_chain_tx_1.PushChainExecutionError(errMsg);
+        }
+        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_01, transactions);
         return transactions[transactions.length - 1];
     });
 }

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

@@ -6,14 +6,16 @@ import { CHAIN } from '../../constants/enums';
 import { ConversionQuote, MoveableToken, PayableToken } from '../../constants/tokens';
 import { EvmClient } from '../../vm-client/evm-client';
 import type { OrchestratorContext } from './context';
+import { type GasSizingDecision } from './gas-usd-sizer';
 export declare function ensureErc20Allowance(ctx: OrchestratorContext, evmClient: EvmClient, tokenAddress: `0x${string}`, spender: `0x${string}`, requiredAmount: bigint): Promise<void>;
-export declare function queryOutboundGasFee(ctx: OrchestratorContext, prc20Token: `0x${string}`, gasLimit: bigint): Promise<{
+export declare function queryOutboundGasFee(ctx: OrchestratorContext, prc20Token: `0x${string}`, gasLimit: bigint, destinationChain?: CHAIN): Promise<{
     gasToken: `0x${string}`;
     gasFee: bigint;
     protocolFee: bigint;
     nativeValueForGas: bigint;
     gasPrice: bigint;
     universalCoreAddress: `0x${string}`;
+    sizing?: GasSizingDecision;
 }>;
 /**
  * Estimate the native WPC amount needed to swap for `gasFee` of `gasToken`
@@ -22,12 +24,13 @@ export declare function queryOutboundGasFee(ctx: OrchestratorContext, prc20Token
  * 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<{
+export declare function queryRescueGasFee(ctx: OrchestratorContext, prc20Token: `0x${string}`, destinationChain?: CHAIN): Promise<{
     gasToken: `0x${string}`;
     gasFee: bigint;
     rescueGasLimit: bigint;
     gasPrice: bigint;
     nativeValueForGas: bigint;
+    sizing?: GasSizingDecision;
 }>;
 export declare function calculateNativeAmountForDeposit(ctx: OrchestratorContext, chain: CHAIN, requiredFunds: bigint, ueaBalance: bigint): Promise<bigint>;
 export declare function calculateGasAmountFromAmountOutMinETH(ctx: OrchestratorContext, gasTokenAddress: `0x${string}`, amountOutMinETH: bigint | string, quoteExactOutputFn: (amountOut: bigint, opts: {

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

@@ -25,7 +25,13 @@ const utils_1 = require("../../utils");
 const svm_client_1 = require("../../vm-client/svm-client");
 const context_1 = require("./context");
 const helpers_1 = require("./helpers");
-/** Buffer multiplier for nativeValueForGas. Excess is refunded by swapAndBurnGas to the UEA. */
+const gas_usd_sizer_1 = require("./gas-usd-sizer");
+/**
+ * Legacy fallback buffer used ONLY when the caller does not supply a
+ * `destinationChain` and the USD sizer cannot be invoked. New code paths
+ * should always pass `destinationChain` so gas is sized against the real
+ * dollar cost (SDK 5.2). 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 = [
@@ -125,7 +131,7 @@ function ensureErc20Allowance(ctx, evmClient, tokenAddress, spender, requiredAmo
 // ============================================================================
 // Outbound Gas Fee Query
 // ============================================================================
-function queryOutboundGasFee(ctx, prc20Token, gasLimit) {
+function queryOutboundGasFee(ctx, prc20Token, gasLimit, destinationChain) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
         var _a, _b;
         const gatewayPcAddress = (0, helpers_1.getUniversalGatewayPCAddress)();
@@ -174,9 +180,32 @@ function queryOutboundGasFee(ctx, prc20Token, gasLimit) {
             (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 3] FAILED: ${err instanceof Error ? err.message : String(err)}`);
             throw err;
         }
-        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, universalCoreAddress };
+        let nativeValueForGas;
+        let sizing;
+        if (destinationChain !== undefined) {
+            try {
+                sizing = yield (0, gas_usd_sizer_1.sizeOutboundGas)(ctx, {
+                    gasFee,
+                    originChain: ctx.universalSigner.account.chain,
+                    destinationChain,
+                });
+                // All categories — A, B, and C — return the sizer's calibrated gas leg.
+                // R3 consumers additionally bump `nativeValueForGas` by `overflowNativePc`
+                // when category === 'C' (see route-handlers.executeCeaToPush).
+                nativeValueForGas = sizing.gasLegNativePc + protocolFee;
+                (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 5] sizer: category=${sizing.category}, gasUsd=${sizing.gasUsd}, ` +
+                    `gasLegNativePc=${sizing.gasLegNativePc}, overflowNativePc=${sizing.overflowNativePc}, nativeValueForGas=${nativeValueForGas}`);
+            }
+            catch (err) {
+                (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 5] sizer failed (${err instanceof Error ? err.message : String(err)}); falling back to 1M buffer`);
+                nativeValueForGas = protocolFee + gasFee * GAS_FEE_BUFFER_MULTIPLIER;
+            }
+        }
+        else {
+            nativeValueForGas = protocolFee + gasFee * GAS_FEE_BUFFER_MULTIPLIER;
+            (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 5] no destinationChain provided; legacy 1M buffer: nativeValueForGas=${nativeValueForGas}`);
+        }
+        return { gasToken, gasFee, protocolFee, nativeValueForGas, gasPrice, universalCoreAddress, sizing };
     });
 }
 // ============================================================================
@@ -285,7 +314,7 @@ function balanceFallback(balance, divisor, reserve) {
 // ============================================================================
 // Rescue Gas Fee Query
 // ============================================================================
-function queryRescueGasFee(ctx, prc20Token) {
+function queryRescueGasFee(ctx, prc20Token, destinationChain) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
         const gatewayPcAddress = (0, helpers_1.getUniversalGatewayPCAddress)();
         (0, context_1.printLog)(ctx, `queryRescueGasFee — inputs: gateway=${gatewayPcAddress}, prc20Token=${prc20Token}`);
@@ -324,9 +353,28 @@ function queryRescueGasFee(ctx, prc20Token) {
             (0, context_1.printLog)(ctx, `queryRescueGasFee — FAILED: ${err instanceof Error ? err.message : String(err)}`);
             throw err;
         }
-        const nativeValueForGas = gasFee * GAS_FEE_BUFFER_MULTIPLIER;
-        (0, context_1.printLog)(ctx, `queryRescueGasFee — using 1000000x buffer: nativeValueForGas=${nativeValueForGas}`);
-        return { gasToken, gasFee, rescueGasLimit, gasPrice, nativeValueForGas };
+        let nativeValueForGas;
+        let sizing;
+        if (destinationChain !== undefined) {
+            try {
+                sizing = yield (0, gas_usd_sizer_1.sizeOutboundGas)(ctx, {
+                    gasFee,
+                    originChain: ctx.universalSigner.account.chain,
+                    destinationChain,
+                });
+                nativeValueForGas = sizing.gasLegNativePc;
+                (0, context_1.printLog)(ctx, `queryRescueGasFee — sizer: category=${sizing.category}, gasUsd=${sizing.gasUsd}, nativeValueForGas=${nativeValueForGas}`);
+            }
+            catch (err) {
+                (0, context_1.printLog)(ctx, `queryRescueGasFee — sizer failed (${err instanceof Error ? err.message : String(err)}); falling back to 1M buffer`);
+                nativeValueForGas = gasFee * GAS_FEE_BUFFER_MULTIPLIER;
+            }
+        }
+        else {
+            nativeValueForGas = gasFee * GAS_FEE_BUFFER_MULTIPLIER;
+            (0, context_1.printLog)(ctx, `queryRescueGasFee — no destinationChain provided; legacy 1M buffer: nativeValueForGas=${nativeValueForGas}`);
+        }
+        return { gasToken, gasFee, rescueGasLimit, gasPrice, nativeValueForGas, sizing };
     });
 }
 // ============================================================================
@@ -335,7 +383,7 @@ function queryRescueGasFee(ctx, prc20Token) {
 function calculateNativeAmountForDeposit(ctx, chain, requiredFunds, ueaBalance) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
         var _a, _b;
-        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_02_01);
+        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_102_01);
         const oneUsd = utils_1.Utils.helpers.parseUnits('1', 8);
         const maxUsd = utils_1.Utils.helpers.parseUnits('1000', 8);
         const deficit = requiredFunds > ueaBalance ? requiredFunds - ueaBalance : BigInt(0);
@@ -380,7 +428,7 @@ function calculateNativeAmountForDeposit(ctx, chain, requiredFunds, ueaBalance)
         let nativeAmount = (depositUsd * oneNativeUnit + (nativeTokenUsdPrice - BigInt(1))) /
             nativeTokenUsdPrice;
         nativeAmount = nativeAmount + BigInt(1);
-        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_02_02, nativeAmount);
+        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_102_02, nativeAmount);
         return nativeAmount;
     });
 }

package/src/lib/orchestrator/internals/gas-usd-sizer.d.ts

@@ -0,0 +1,53 @@
+import { CHAIN } from '../../constants/enums';
+import type { OrchestratorContext } from './context';
+export type GasSizingCategory = 'A' | 'B' | 'C';
+export interface GasSizingInput {
+    /** Raw gasFee from getOutboundTxGasAndFees (in gasToken units, e.g., pETH 18d) */
+    gasFee: bigint;
+    /** Origin chain the user signed from — picks the PC/USD oracle pool */
+    originChain: CHAIN;
+    /**
+     * Destination chain whose native asset is represented by gasToken on PC.
+     * Used to price gasFee in USD via PriceFetch (Chainlink ETH/USD, Pyth SOL/USD).
+     */
+    destinationChain: CHAIN;
+}
+export interface GasSizingDecision {
+    category: GasSizingCategory;
+    /** Native PC to send as msg.value for the sendUniversalTxOutbound leg */
+    gasLegNativePc: bigint;
+    /** Native PC to bridge as funds alongside (only > 0 when category === 'C') */
+    overflowNativePc: bigint;
+    /** Diagnostic — raw gas cost in USD (1e8) */
+    gasUsd: bigint;
+    /** Diagnostic — portion to bridge in USD (1e8) */
+    overflowUsd: bigint;
+}
+export declare function sizeOutboundGas(ctx: OrchestratorContext, input: GasSizingInput): Promise<GasSizingDecision>;
+export interface R1SizingInput {
+    /** Push-chain gas cost in UPC wei (18 decimals) */
+    pushGasFeeWei: bigint;
+    /** Origin chain — picks the WPC/USD oracle pool */
+    originChain: CHAIN;
+}
+export interface R1SizingDecision {
+    category: GasSizingCategory;
+    /** Push-gas cost in USD (8 decimals) */
+    pushGasUsd: bigint;
+    /** USD the SDK should request on the origin gateway (8 decimals) */
+    paddedDepositUsd: bigint;
+}
+export declare function sizeR1PushGas(ctx: OrchestratorContext, input: R1SizingInput): Promise<R1SizingDecision>;
+/**
+ * Given gasFee (in gasToken units) and destination VM, return gasFee in USD
+ * (8 decimals). Exposed for direct use in places that already have the
+ * destUsdPrice cached (e.g., rescue flows).
+ */
+export declare function computeGasUsd(ctx: OrchestratorContext, gasFee: bigint, destinationChain: CHAIN): Promise<bigint>;
+/** Test-only export of thresholds. @internal */
+export declare const __THRESHOLDS: {
+    ONE_USD_8D: bigint;
+    TEN_USD_8D: bigint;
+};
+/** Alias for backward-compat at call sites. */
+export { getPcUsdPrice } from './pc-usd-oracle';

package/src/lib/orchestrator/internals/gas-usd-sizer.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPcUsdPrice = exports.__THRESHOLDS = void 0;
+exports.sizeOutboundGas = sizeOutboundGas;
+exports.sizeR1PushGas = sizeR1PushGas;
+exports.computeGasUsd = computeGasUsd;
+const tslib_1 = require("tslib");
+/**
+ * Gas sizing for outbound transactions (Routes 2/3/4).
+ *
+ * Categorizes destination gas cost into three buckets per the SDK 5.2 spec:
+ *   - A: gasUsd < $1     → floor to $1 worth of native PC
+ *   - B: $1 ≤ gasUsd ≤ $10 → happy path, use gasFee as sized
+ *   - C: gasUsd > $10    → split: $10 gas leg + overflow bridged as funds
+ *
+ * Output amounts are in native PC (nPUSH, 18 decimals) because that's what
+ * `sendUniversalTxOutbound` consumes as `msg.value` before swapAndBurnGas
+ * swaps it into the destination gas token (pETH, pSOL, …).
+ */
+const viem_1 = require("viem");
+const enums_1 = require("../../constants/enums");
+const chain_1 = require("../../constants/chain");
+const price_fetch_1 = require("../../price-fetch/price-fetch");
+const context_1 = require("./context");
+const pc_usd_oracle_1 = require("./pc-usd-oracle");
+// ============================================================================
+// Thresholds (USD, 8 decimals)
+// ============================================================================
+const ONE_USD_8D = (0, viem_1.parseUnits)('1', 8); // 100_000_000
+const TEN_USD_8D = (0, viem_1.parseUnits)('10', 8); // 1_000_000_000
+// ============================================================================
+// Public API
+// ============================================================================
+function sizeOutboundGas(ctx, input) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const { gasFee, originChain, destinationChain } = input;
+        // 1) Price gasFee in USD (8 decimals). gasFee is denominated in the
+        //    destination native (pETH = ETH value, pSOL = SOL value). The price
+        //    feed lives on the *origin* side (origin gateway's Chainlink/Pyth),
+        //    but we reuse the same feed via PriceFetch — the asset being priced
+        //    is ETH or SOL, not the route.
+        const destVm = chain_1.CHAIN_INFO[destinationChain].vm;
+        const priceSourceChain = destVm === enums_1.VM.SVM ? enums_1.CHAIN.SOLANA_DEVNET : enums_1.CHAIN.ETHEREUM_SEPOLIA;
+        const destDecimals = destVm === enums_1.VM.SVM ? 9 : 18;
+        let destUsdPrice;
+        try {
+            destUsdPrice = yield new price_fetch_1.PriceFetch(ctx.rpcUrls).getPrice(priceSourceChain);
+        }
+        catch (err) {
+            (0, context_1.printLog)(ctx, `sizeOutboundGas — PriceFetch.getPrice failed (${err instanceof Error ? err.message : String(err)}); treating as Case B passthrough`);
+            // Degrade gracefully: assume the raw gasFee is already a sane size and
+            // convert 1:1 to native PC. Callers keep their existing fallback logic.
+            return passthroughAsCaseB(ctx, gasFee, originChain);
+        }
+        const oneDestNativeUnit = (0, viem_1.parseUnits)('1', destDecimals);
+        const gasUsd = (gasFee * destUsdPrice) / oneDestNativeUnit;
+        (0, context_1.printLog)(ctx, `sizeOutboundGas — gasFee=${gasFee.toString()} ${destVm === enums_1.VM.SVM ? 'pSOL' : 'pETH'} (${destDecimals}d), ` +
+            `destUsdPrice=${destUsdPrice.toString()} (1e8), gasUsd=${gasUsd.toString()} (1e8)`);
+        // 2) Categorize and compute target USD for each leg.
+        let category;
+        let gasLegUsd;
+        let overflowUsd;
+        if (gasUsd < ONE_USD_8D) {
+            category = 'A';
+            gasLegUsd = ONE_USD_8D;
+            overflowUsd = BigInt(0);
+        }
+        else if (gasUsd <= TEN_USD_8D) {
+            category = 'B';
+            gasLegUsd = gasUsd;
+            overflowUsd = BigInt(0);
+        }
+        else {
+            category = 'C';
+            gasLegUsd = TEN_USD_8D;
+            overflowUsd = gasUsd - TEN_USD_8D;
+        }
+        // 3) Convert USD targets back to native PC via the per-route WPC/stable oracle.
+        const gasLegNativePc = yield (0, pc_usd_oracle_1.usdToPc)(ctx, gasLegUsd, originChain);
+        const overflowNativePc = overflowUsd > BigInt(0)
+            ? yield (0, pc_usd_oracle_1.usdToPc)(ctx, overflowUsd, originChain)
+            : BigInt(0);
+        (0, context_1.printLog)(ctx, `sizeOutboundGas — category=${category}, gasLegUsd=${gasLegUsd.toString()}, ` +
+            `overflowUsd=${overflowUsd.toString()}, gasLegNativePc=${gasLegNativePc.toString()}, ` +
+            `overflowNativePc=${overflowNativePc.toString()}`);
+        return {
+            category,
+            gasLegNativePc,
+            overflowNativePc,
+            gasUsd,
+            overflowUsd,
+        };
+    });
+}
+// ============================================================================
+// Internal helpers
+// ============================================================================
+/**
+ * When the USD price feed fails, fall back to a pass-through that keeps the
+ * Orchestrator alive: return the raw gasFee as a Case B result, converting
+ * through the existing PC/USD oracle (or its hardcoded fallback).
+ */
+function passthroughAsCaseB(ctx, gasFee, originChain) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const oneUsd = ONE_USD_8D;
+        const gasLegNativePc = yield (0, pc_usd_oracle_1.usdToPc)(ctx, oneUsd, originChain);
+        void gasFee;
+        return {
+            category: 'B',
+            gasLegNativePc,
+            overflowNativePc: BigInt(0),
+            gasUsd: oneUsd,
+            overflowUsd: BigInt(0),
+        };
+    });
+}
+function sizeR1PushGas(ctx, input) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const { pushGasFeeWei, originChain } = input;
+        // 1) Convert pushGasFeeWei (UPC wei, 18d) → USD (8d) via per-route oracle.
+        const pcUsdPrice = yield (0, pc_usd_oracle_1.getPcUsdPrice)(ctx, originChain);
+        const onePcUnit = (0, viem_1.parseUnits)('1', 18);
+        const pushGasUsd = (pushGasFeeWei * pcUsdPrice) / onePcUnit;
+        (0, context_1.printLog)(ctx, `sizeR1PushGas — pushGasFeeWei=${pushGasFeeWei.toString()} UPC (18d), ` +
+            `pcUsdPrice=${pcUsdPrice.toString()} (1e8), pushGasUsd=${pushGasUsd.toString()} (1e8)`);
+        // 2) Bucket.
+        let category;
+        let paddedDepositUsd;
+        if (pushGasUsd < ONE_USD_8D) {
+            category = 'A';
+            paddedDepositUsd = ONE_USD_8D;
+        }
+        else if (pushGasUsd <= TEN_USD_8D) {
+            category = 'B';
+            paddedDepositUsd = pushGasUsd;
+        }
+        else {
+            category = 'C';
+            paddedDepositUsd = pushGasUsd;
+        }
+        (0, context_1.printLog)(ctx, `sizeR1PushGas — category=${category}, paddedDepositUsd=${paddedDepositUsd.toString()} (1e8)`);
+        return { category, pushGasUsd, paddedDepositUsd };
+    });
+}
+/**
+ * Given gasFee (in gasToken units) and destination VM, return gasFee in USD
+ * (8 decimals). Exposed for direct use in places that already have the
+ * destUsdPrice cached (e.g., rescue flows).
+ */
+function computeGasUsd(ctx, gasFee, destinationChain) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const destVm = chain_1.CHAIN_INFO[destinationChain].vm;
+        const priceSourceChain = destVm === enums_1.VM.SVM ? enums_1.CHAIN.SOLANA_DEVNET : enums_1.CHAIN.ETHEREUM_SEPOLIA;
+        const destDecimals = destVm === enums_1.VM.SVM ? 9 : 18;
+        const destUsdPrice = yield new price_fetch_1.PriceFetch(ctx.rpcUrls).getPrice(priceSourceChain);
+        const oneUnit = (0, viem_1.parseUnits)('1', destDecimals);
+        return (gasFee * destUsdPrice) / oneUnit;
+    });
+}
+/** Test-only export of thresholds. @internal */
+exports.__THRESHOLDS = { ONE_USD_8D, TEN_USD_8D };
+/** Alias for backward-compat at call sites. */
+var pc_usd_oracle_2 = require("./pc-usd-oracle");
+Object.defineProperty(exports, "getPcUsdPrice", { enumerable: true, get: function () { return pc_usd_oracle_2.getPcUsdPrice; } });
+//# sourceMappingURL=gas-usd-sizer.js.map

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

@@ -129,6 +129,8 @@ function bigintReplacer(_key, value) {
 // Params Conversion
 // ============================================================================
 function toExecuteParams(params) {
+    // Post-route-detector, ChainTarget.address has already been normalized to
+    // 0x-prefixed hex for SVM targets (see route-detector.ts), so the cast is safe.
     const to = typeof params.to === 'string'
         ? params.to
         : params.to.address;