@pushchain/core 5.1.18 → 6.0.1

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

@@ -29,7 +29,7 @@ const formatters_1 = require("../../formatters");
  */
 class PushChainExecutionError extends Error {
     constructor(message, opts = {}) {
-        super(message);
+        super((0, formatters_1.normalizePcInsufficientFundsError)(message));
         this.code = 'PUSH_CHAIN_EXECUTION_FAILED';
         this.name = 'PushChainExecutionError';
         this.gatewayTxHash = opts.gatewayTxHash;

package/src/lib/orchestrator/internals/execute-funds-only.js

@@ -29,6 +29,7 @@ const push_chain_tx_1 = require("./push-chain-tx");
 const svm_helpers_1 = require("./svm-helpers");
 const helpers_2 = require("./helpers");
 const response_builder_2 = require("./response-builder");
+const formatters_1 = require("../../formatters");
 function executeFundsOnly(ctx, execute, eventBuffer, getResponseCallbacks) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
         const transformFn = (tx, buf = []) => (0, response_builder_2.transformToUniversalTxResponse)(ctx, tx, buf, getResponseCallbacks());
@@ -139,7 +140,7 @@ function executeFundsOnlyEvm(ctx, execute, eventBuffer, transformFn, chain, rpcU
         }
         catch (err) {
             if (!(err instanceof push_chain_tx_1.PushChainExecutionError)) {
-                const errMsg = err instanceof Error ? err.message : String(err);
+                const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
                 (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
                 throw new push_chain_tx_1.PushChainExecutionError(errMsg, { gatewayTxHash: txHash });
             }
@@ -230,7 +231,7 @@ function executeFundsOnlySvm(ctx, execute, eventBuffer, transformFn, chain, rpcU
         }
         catch (err) {
             if (!(err instanceof push_chain_tx_1.PushChainExecutionError)) {
-                const errMsg = err instanceof Error ? err.message : String(err);
+                const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
                 (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
                 throw new push_chain_tx_1.PushChainExecutionError(errMsg, { gatewayTxHash: txSignature });
             }

package/src/lib/orchestrator/internals/execute-funds-payload.js

@@ -32,6 +32,7 @@ const push_chain_tx_1 = require("./push-chain-tx");
 const svm_bridge_1 = require("./svm-bridge");
 const signing_1 = require("./signing");
 const quote_1 = require("./quote");
+const formatters_1 = require("../../formatters");
 function executeFundsWithPayload(ctx, execute, eventBuffer, getResponseCallbacks) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
@@ -240,7 +241,7 @@ function executeFundsWithPayload(ctx, execute, eventBuffer, getResponseCallbacks
         }
         catch (err) {
             if (!(err instanceof push_chain_tx_1.PushChainExecutionError)) {
-                const errMsg = err instanceof Error ? err.message : String(err);
+                const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(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: txHash });
             }

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

@@ -104,7 +104,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             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 errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(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
@@ -267,7 +267,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
                 // 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);
+                const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(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;
             }
@@ -413,7 +413,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             }
             catch (err) {
                 if (!(err instanceof push_chain_tx_1.PushChainExecutionError)) {
-                    const errMsg = err instanceof Error ? err.message : String(err);
+                    const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(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 });
                 }
@@ -447,7 +447,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             // 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);
+            const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(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;

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

@@ -14,6 +14,7 @@ export declare function queryOutboundGasFee(ctx: OrchestratorContext, prc20Token
     protocolFee: bigint;
     nativeValueForGas: bigint;
     gasPrice: bigint;
+    gasLimitUsed: bigint;
     universalCoreAddress: `0x${string}`;
     sizing?: GasSizingDecision;
 }>;

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

@@ -158,7 +158,7 @@ function ensureErc20Allowance(ctx, evmClient, tokenAddress, spender, requiredAmo
 // ============================================================================
 function queryOutboundGasFee(ctx, prc20Token, gasLimit, destinationChain) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b;
+        var _a, _b, _c;
         const gatewayPcAddress = (0, helpers_1.getUniversalGatewayPCAddress)();
         const pushChain = (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork);
         const rpcUrl = ((_b = (_a = chain_1.CHAIN_INFO[pushChain]) === null || _a === void 0 ? void 0 : _a.defaultRPC) === null || _b === void 0 ? void 0 : _b[0]) || 'unknown';
@@ -168,13 +168,13 @@ function queryOutboundGasFee(ctx, prc20Token, gasLimit, destinationChain) {
             universalCoreAddress = yield ctx.pushClient.readContract({
                 address: gatewayPcAddress,
                 abi: abi_1.UNIVERSAL_GATEWAY_PC,
-                functionName: 'UNIVERSAL_CORE',
+                functionName: 'universalCore',
                 args: [],
             });
-            (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 2] UNIVERSAL_CORE resolved to: ${universalCoreAddress}`);
+            (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 2] universalCore resolved to: ${universalCoreAddress}`);
         }
         catch (err) {
-            (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 2] FAILED to read UNIVERSAL_CORE: ${err instanceof Error ? err.message : String(err)}`);
+            (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 2] FAILED to read universalCore: ${err instanceof Error ? err.message : String(err)}`);
             throw err;
         }
         const callData = (0, viem_1.encodeFunctionData)({
@@ -188,6 +188,7 @@ function queryOutboundGasFee(ctx, prc20Token, gasLimit, destinationChain) {
         let gasFee;
         let protocolFee;
         let gasPrice = BigInt(0);
+        let gasLimitUsed = gasLimit;
         try {
             const result = yield ctx.pushClient.readContract({
                 address: universalCoreAddress,
@@ -199,7 +200,8 @@ function queryOutboundGasFee(ctx, prc20Token, gasLimit, destinationChain) {
             gasFee = result[1];
             protocolFee = result[2];
             gasPrice = result[3];
-            (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 4] success: gasToken=${gasToken}, gasFee=${gasFee}, protocolFee=${protocolFee}, gasPrice=${gasPrice}`);
+            gasLimitUsed = (_c = result[5]) !== null && _c !== void 0 ? _c : gasLimit;
+            (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 4] success: gasToken=${gasToken}, gasFee=${gasFee}, protocolFee=${protocolFee}, gasPrice=${gasPrice}, gasLimitUsed=${gasLimitUsed}`);
         }
         catch (err) {
             (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 3] FAILED: ${err instanceof Error ? err.message : String(err)}`);
@@ -230,7 +232,7 @@ function queryOutboundGasFee(ctx, prc20Token, gasLimit, destinationChain) {
             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 };
+        return { gasToken, gasFee, protocolFee, nativeValueForGas, gasPrice, gasLimitUsed, universalCoreAddress, sizing };
     });
 }
 // ============================================================================
@@ -390,13 +392,13 @@ function queryRescueGasFee(ctx, prc20Token, destinationChain) {
             universalCoreAddress = yield ctx.pushClient.readContract({
                 address: gatewayPcAddress,
                 abi: abi_1.UNIVERSAL_GATEWAY_PC,
-                functionName: 'UNIVERSAL_CORE',
+                functionName: 'universalCore',
                 args: [],
             });
-            (0, context_1.printLog)(ctx, `queryRescueGasFee — UNIVERSAL_CORE resolved to: ${universalCoreAddress}`);
+            (0, context_1.printLog)(ctx, `queryRescueGasFee — universalCore resolved to: ${universalCoreAddress}`);
         }
         catch (err) {
-            (0, context_1.printLog)(ctx, `queryRescueGasFee — FAILED to read UNIVERSAL_CORE: ${err instanceof Error ? err.message : String(err)}`);
+            (0, context_1.printLog)(ctx, `queryRescueGasFee — FAILED to read universalCore: ${err instanceof Error ? err.message : String(err)}`);
             throw err;
         }
         let gasToken;
@@ -562,7 +564,7 @@ function estimateDepositFromLockedNative(ctx, nativeAmountForLocker, prc20Token)
             const universalCoreAddress = yield ctx.pushClient.readContract({
                 address: gatewayPcAddress,
                 abi: abi_1.UNIVERSAL_GATEWAY_PC,
-                functionName: 'UNIVERSAL_CORE',
+                functionName: 'universalCore',
                 args: [],
             });
             const [wpcAddress, feeTier] = yield Promise.all([
@@ -654,7 +656,7 @@ function estimateNativeForDesiredDeposit(ctx, desiredWpc, prc20Token) {
             const universalCoreAddress = yield ctx.pushClient.readContract({
                 address: gatewayPcAddress,
                 abi: abi_1.UNIVERSAL_GATEWAY_PC,
-                functionName: 'UNIVERSAL_CORE',
+                functionName: 'universalCore',
                 args: [],
             });
             const [wpcAddress, feeTier] = yield Promise.all([

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

@@ -142,9 +142,11 @@ function toExecuteParams(params) {
         data: params.data,
         funds: params.funds,
         gasLimit: params.gasLimit,
+        maxPCForGas: params.maxPCForGas,
         maxFeePerGas: params.maxFeePerGas,
         maxPriorityFeePerGas: params.maxPriorityFeePerGas,
         deadline: params.deadline,
+        options: params.options,
         payGasWith: params.payGasWith,
         feeLockTxHash: params.feeLockTxHash,
     };

package/src/lib/orchestrator/internals/inbound-tracker.js

@@ -20,6 +20,7 @@ const types_1 = require("../../generated/uexecutor/v2/types");
 const context_1 = require("./context");
 const detector_1 = require("../../universal-tx-detector/detector");
 const child_inbounds_1 = require("../../universal-tx-detector/child-inbounds");
+const formatters_1 = require("../../formatters");
 const TERMINAL_SUCCESS_STATUSES = new Set([
     types_1.UniversalTxStatus.INBOUND_SUCCESS,
     types_1.UniversalTxStatus.PC_EXECUTED_SUCCESS,
@@ -205,8 +206,9 @@ function waitForInboundPushTx(ctx_1, outboundExternalTxHash_1, sourceChain_1) {
                         }
                     }
                     else if (TERMINAL_FAILURE_STATUSES.has(status)) {
-                        const errMsg = ((_l = (_k = utx === null || utx === void 0 ? void 0 : utx.pcTx) === null || _k === void 0 ? void 0 : _k[0]) === null || _l === void 0 ? void 0 : _l.errorMsg) ||
-                            `inbound terminated with status ${status}`;
+                        const errMsg = ((_l = (_k = utx === null || utx === void 0 ? void 0 : utx.pcTx) === null || _k === void 0 ? void 0 : _k[0]) === null || _l === void 0 ? void 0 : _l.errorMsg)
+                            ? (0, formatters_1.normalizePcInsufficientFundsError)(utx.pcTx[0].errorMsg)
+                            : `inbound terminated with status ${status}`;
                         progressHook === null || progressHook === void 0 ? void 0 : progressHook({
                             status: 'failed',
                             elapsedMs: elapsed(),

package/src/lib/orchestrator/internals/outbound-sync.js

@@ -15,6 +15,7 @@ const chain_1 = require("../../constants/chain");
 const enums_1 = require("../../constants/enums");
 const types_1 = require("../../generated/uexecutor/v1/types");
 const types_2 = require("../../generated/uexecutor/v2/types");
+const formatters_1 = require("../../formatters");
 const context_1 = require("./context");
 const helpers_1 = require("./helpers");
 const outbound_tracker_1 = require("./outbound-tracker");
@@ -142,7 +143,7 @@ function verifyExternalEvmReceipt(ctx, destinationChain, externalTxHash) {
 function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
     return tslib_1.__awaiter(this, arguments, void 0, function* (ctx, pushChainTxHash, options = {}) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
-        const { initialWaitMs = exports.OUTBOUND_INITIAL_WAIT_MS, pollingIntervalMs = exports.OUTBOUND_POLL_INTERVAL_MS, timeout = exports.OUTBOUND_MAX_TIMEOUT_MS, progressHook, _resolvedSubTxId, _expectedDestinationChain, } = options;
+        const { initialWaitMs = exports.OUTBOUND_INITIAL_WAIT_MS, pollingIntervalMs = exports.OUTBOUND_POLL_INTERVAL_MS, timeout = exports.OUTBOUND_MAX_TIMEOUT_MS, progressHook, _resolvedSubTxId, _expectedDestinationChain, _outboundIndex, } = options;
         // Terminal failure states — fail fast instead of polling until timeout
         const TERMINAL_FAILURE_STATES = new Set([
             types_1.UniversalTxStatus.OUTBOUND_FAILED,
@@ -213,13 +214,30 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
                 });
                 if (failedPcTx) {
                     const failedTxHash = failedPcTx.txHash || pushChainTxHash;
-                    const reason = failedPcTx.errorMsg || 'Push Chain execution failed';
+                    const reason = failedPcTx.errorMsg
+                        ? (0, formatters_1.normalizePcInsufficientFundsError)(failedPcTx.errorMsg)
+                        : 'Push Chain execution failed';
                     (0, context_1.printLog)(ctx, `[waitForOutboundTx] Push Chain execution failed before outbound emission: ${reason}`);
                     progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'failed', elapsed: Date.now() - startTime });
                     throw new OutboundFailedError(`Push Chain execution failed before outbound emission: ${reason}. Push Chain TX: ${failedTxHash}.`, pushChainTxHash, undefined, failedPcTx.txHash || undefined);
                 }
-                // Iterate V2 outbound array
+                // Iterate V2 outbound array. For cascade tracking, multiple outbound
+                // entries can target the same destination chain (for example R2 BSC
+                // followed by R3 BSC -> Push). `_outboundIndex` disambiguates those
+                // same-chain entries by order after `_expectedDestinationChain` filtering.
+                let matchingOutboundIndex = 0;
                 for (const ob of outbounds) {
+                    // If a destination chain filter is set, skip outbound entries that don't match.
+                    if (_expectedDestinationChain && ob.destinationChain !== _expectedDestinationChain) {
+                        (0, context_1.printLog)(ctx, `[waitForOutboundTx] Poll #${pollCount} | outbound chain '${ob.destinationChain}' does not match expected '${_expectedDestinationChain}', skipping`);
+                        continue;
+                    }
+                    const currentOutboundIndex = matchingOutboundIndex;
+                    matchingOutboundIndex += 1;
+                    if (_outboundIndex !== undefined && currentOutboundIndex !== _outboundIndex) {
+                        (0, context_1.printLog)(ctx, `[waitForOutboundTx] Poll #${pollCount} | outbound index ${currentOutboundIndex} for '${ob.destinationChain}' does not match expected index ${_outboundIndex}, skipping`);
+                        continue;
+                    }
                     // Fail fast on per-outbound REVERTED status
                     if (ob.outboundStatus === types_2.OutboundStatus.REVERTED) {
                         (0, context_1.printLog)(ctx, `[waitForOutboundTx] Outbound to ${ob.destinationChain} REVERTED`);
@@ -235,11 +253,6 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
                     //      treat as FOUND; if reverted, throw OutboundFailedError.
                     //      Pending receipts keep polling.
                     if ((_m = ob.observedTx) === null || _m === void 0 ? void 0 : _m.txHash) {
-                        // If a destination chain filter is set, skip outbound entries that don't match
-                        if (_expectedDestinationChain && ob.destinationChain !== _expectedDestinationChain) {
-                            (0, context_1.printLog)(ctx, `[waitForOutboundTx] Poll #${pollCount} | outbound chain '${ob.destinationChain}' does not match expected '${_expectedDestinationChain}', skipping`);
-                            continue;
-                        }
                         const chain = (0, helpers_1.chainFromNamespace)(ob.destinationChain);
                         if (!chain)
                             continue;
@@ -320,7 +333,7 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
  */
 function waitForAllOutboundTxsV2(ctx, pushChainTxHash, outboundHops, options) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
         const { initialWaitMs, pollingIntervalMs, timeout, progressHook, _resolvedSubTxId, } = options;
         const startTime = Date.now();
         // Build a map: CAIP-2 namespace -> hop(s) for matching outbound entries
@@ -386,34 +399,38 @@ function waitForAllOutboundTxsV2(ctx, pushChainTxHash, outboundHops, options) {
                 const statusName = (_a = types_1.UniversalTxStatus[statusNum]) !== null && _a !== void 0 ? _a : statusNum;
                 (0, context_1.printLog)(ctx, `[waitForAllOutboundTxsV2] Poll #${pollCount} | status: ${statusNum} (${statusName}) | outboundTx count: ${(_c = (_b = utx === null || utx === void 0 ? void 0 : utx.outboundTx) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0}`);
                 if ((_d = utx === null || utx === void 0 ? void 0 : utx.outboundTx) === null || _d === void 0 ? void 0 : _d.length) {
+                    const outboundOrdinalByChain = new Map();
                     for (const ob of utx.outboundTx) {
                         const destChain = ob.destinationChain;
                         const hopsForChain = chainToHops.get(destChain);
                         if (!hopsForChain)
                             continue;
-                        const unconfirmedForChain = hopsForChain.filter((h) => h.status !== 'confirmed' && h.status !== 'failed');
-                        if (unconfirmedForChain.length === 0)
+                        const outboundOrdinal = (_e = outboundOrdinalByChain.get(destChain)) !== null && _e !== void 0 ? _e : 0;
+                        outboundOrdinalByChain.set(destChain, outboundOrdinal + 1);
+                        const targetHop = hopsForChain[outboundOrdinal];
+                        if (!targetHop ||
+                            targetHop.status === 'confirmed' ||
+                            targetHop.status === 'failed') {
                             continue;
-                        const externalTxHash = (_e = ob.observedTx) === null || _e === void 0 ? void 0 : _e.txHash;
+                        }
+                        const externalTxHash = (_f = ob.observedTx) === null || _f === void 0 ? void 0 : _f.txHash;
                         const hasObservedTxHash = !!externalTxHash && externalTxHash !== 'EMPTY';
                         const observedFailure = hasObservedTxHash &&
-                            ((_f = ob.observedTx) === null || _f === void 0 ? void 0 : _f.success) === false &&
-                            Boolean(((_g = ob.observedTx) === null || _g === void 0 ? void 0 : _g.errorMsg) ||
+                            ((_g = ob.observedTx) === null || _g === void 0 ? void 0 : _g.success) === false &&
+                            Boolean(((_h = ob.observedTx) === null || _h === void 0 ? void 0 : _h.errorMsg) ||
                                 ob.abortReason ||
                                 ob.outboundStatus >= types_2.OutboundStatus.REVERTED);
                         // Fail fast on per-outbound REVERTED or observed destination failure.
                         if (ob.outboundStatus === types_2.OutboundStatus.REVERTED || observedFailure) {
-                            for (const hop of unconfirmedForChain) {
-                                hop.status = 'failed';
-                                (0, context_1.printLog)(ctx, `[waitForAllOutboundTxsV2] Outbound to ${destChain} REVERTED | hop ${hop.hopIndex} | error: ${ob.abortReason || ((_h = ob.observedTx) === null || _h === void 0 ? void 0 : _h.errorMsg) || 'Unknown'}`);
-                                progressHook === null || progressHook === void 0 ? void 0 : progressHook({
-                                    hopIndex: hop.hopIndex,
-                                    route: hop.route,
-                                    chain: hop.executionChain,
-                                    status: 'failed',
-                                });
-                            }
-                            return { success: false, failedAt: unconfirmedForChain[0].hopIndex };
+                            targetHop.status = 'failed';
+                            (0, context_1.printLog)(ctx, `[waitForAllOutboundTxsV2] Outbound to ${destChain} REVERTED | outboundIndex ${outboundOrdinal} | hop ${targetHop.hopIndex} | error: ${ob.abortReason || ((_j = ob.observedTx) === null || _j === void 0 ? void 0 : _j.errorMsg) || 'Unknown'}`);
+                            progressHook === null || progressHook === void 0 ? void 0 : progressHook({
+                                hopIndex: targetHop.hopIndex,
+                                route: targetHop.route,
+                                chain: targetHop.executionChain,
+                                status: 'failed',
+                            });
+                            return { success: false, failedAt: targetHop.hopIndex };
                         }
                         // Check for observed tx hash. Cosmos may lag the status transition,
                         // so EVM destinations are verified against the destination receipt.
@@ -425,17 +442,15 @@ function waitForAllOutboundTxsV2(ctx, pushChainTxHash, outboundHops, options) {
                             if (!isCosmosObserved) {
                                 const verdict = yield verifyExternalEvmReceipt(ctx, chain, externalTxHash);
                                 if (verdict === 'reverted') {
-                                    for (const hop of unconfirmedForChain) {
-                                        hop.status = 'failed';
-                                        (0, context_1.printLog)(ctx, `[waitForAllOutboundTxsV2] Source-chain RPC reports REVERTED for ${destChain} tx ${externalTxHash} | hop ${hop.hopIndex}`);
-                                        progressHook === null || progressHook === void 0 ? void 0 : progressHook({
-                                            hopIndex: hop.hopIndex,
-                                            route: hop.route,
-                                            chain: hop.executionChain,
-                                            status: 'failed',
-                                        });
-                                    }
-                                    return { success: false, failedAt: unconfirmedForChain[0].hopIndex };
+                                    targetHop.status = 'failed';
+                                    (0, context_1.printLog)(ctx, `[waitForAllOutboundTxsV2] Source-chain RPC reports REVERTED for ${destChain} tx ${externalTxHash} | outboundIndex ${outboundOrdinal} | hop ${targetHop.hopIndex}`);
+                                    progressHook === null || progressHook === void 0 ? void 0 : progressHook({
+                                        hopIndex: targetHop.hopIndex,
+                                        route: targetHop.route,
+                                        chain: targetHop.executionChain,
+                                        status: 'failed',
+                                    });
+                                    return { success: false, failedAt: targetHop.hopIndex };
                                 }
                                 if (verdict !== 'success') {
                                     continue;
@@ -447,11 +462,11 @@ function waitForAllOutboundTxsV2(ctx, pushChainTxHash, outboundHops, options) {
                             // inside this function; it's not exposed to consumers from the
                             // cascade path (cascade.ts doesn't call findChildUtxIdFromExternalTx
                             // for the cascade outbound hash).
-                            const displayTxHash = (_j = (0, helpers_1.toExternalTxHashDisplay)(chain !== null && chain !== void 0 ? chain : undefined, externalTxHash)) !== null && _j !== void 0 ? _j : externalTxHash;
+                            const displayTxHash = (_k = (0, helpers_1.toExternalTxHashDisplay)(chain !== null && chain !== void 0 ? chain : undefined, externalTxHash)) !== null && _k !== void 0 ? _k : externalTxHash;
                             let explorerUrl = '';
                             if (chain && externalTxHash) {
-                                const explorerBaseUrl = (_k = chain_1.CHAIN_INFO[chain]) === null || _k === void 0 ? void 0 : _k.explorerUrl;
-                                const isSvm = ((_l = chain_1.CHAIN_INFO[chain]) === null || _l === void 0 ? void 0 : _l.vm) === enums_1.VM.SVM;
+                                const explorerBaseUrl = (_l = chain_1.CHAIN_INFO[chain]) === null || _l === void 0 ? void 0 : _l.explorerUrl;
+                                const isSvm = ((_m = chain_1.CHAIN_INFO[chain]) === null || _m === void 0 ? void 0 : _m.vm) === enums_1.VM.SVM;
                                 if (isSvm) {
                                     const cluster = chain === enums_1.CHAIN.SOLANA_DEVNET ? '?cluster=devnet'
                                         : chain === enums_1.CHAIN.SOLANA_TESTNET ? '?cluster=testnet' : '';
@@ -461,26 +476,24 @@ function waitForAllOutboundTxsV2(ctx, pushChainTxHash, outboundHops, options) {
                                     explorerUrl = explorerBaseUrl ? `${explorerBaseUrl}/tx/${displayTxHash}` : '';
                                 }
                             }
-                            for (const hop of unconfirmedForChain) {
-                                hop.status = 'confirmed';
-                                hop.txHash = displayTxHash;
-                                hop.outboundDetails = {
-                                    externalTxHash: displayTxHash,
-                                    destinationChain: chain || hop.executionChain,
-                                    explorerUrl,
-                                    recipient: ob.recipient,
-                                    amount: ob.amount,
-                                    assetAddr: ob.externalAssetAddr,
-                                };
-                                (0, context_1.printLog)(ctx, `[waitForAllOutboundTxsV2] FOUND outbound for ${destChain} | hop ${hop.hopIndex} | externalTxHash: ${displayTxHash}`);
-                                progressHook === null || progressHook === void 0 ? void 0 : progressHook({
-                                    hopIndex: hop.hopIndex,
-                                    route: hop.route,
-                                    chain: hop.executionChain,
-                                    status: 'confirmed',
-                                    txHash: displayTxHash,
-                                });
-                            }
+                            targetHop.status = 'confirmed';
+                            targetHop.txHash = displayTxHash;
+                            targetHop.outboundDetails = {
+                                externalTxHash: displayTxHash,
+                                destinationChain: chain || targetHop.executionChain,
+                                explorerUrl,
+                                recipient: ob.recipient,
+                                amount: ob.amount,
+                                assetAddr: ob.externalAssetAddr,
+                            };
+                            (0, context_1.printLog)(ctx, `[waitForAllOutboundTxsV2] FOUND outbound for ${destChain} | outboundIndex ${outboundOrdinal} | hop ${targetHop.hopIndex} | externalTxHash: ${displayTxHash}`);
+                            progressHook === null || progressHook === void 0 ? void 0 : progressHook({
+                                hopIndex: targetHop.hopIndex,
+                                route: targetHop.route,
+                                chain: targetHop.executionChain,
+                                status: 'confirmed',
+                                txHash: displayTxHash,
+                            });
                         }
                     }
                 }
@@ -495,7 +508,7 @@ function waitForAllOutboundTxsV2(ctx, pushChainTxHash, outboundHops, options) {
                 if (statusNum === types_1.UniversalTxStatus.PC_EXECUTED_SUCCESS) {
                     const stillUnresolved = outboundHops.filter((h) => h.status !== 'confirmed');
                     if (stillUnresolved.length > 0) {
-                        const hasPendingOutbound = (_m = utx === null || utx === void 0 ? void 0 : utx.outboundTx) === null || _m === void 0 ? void 0 : _m.some((ob) => {
+                        const hasPendingOutbound = (_o = utx === null || utx === void 0 ? void 0 : utx.outboundTx) === null || _o === void 0 ? void 0 : _o.some((ob) => {
                             var _a;
                             return ob.outboundStatus === types_2.OutboundStatus.PENDING &&
                                 (!((_a = ob.observedTx) === null || _a === void 0 ? void 0 : _a.txHash) || ob.observedTx.txHash === 'EMPTY');

package/src/lib/orchestrator/internals/pc-usd-oracle.d.ts

@@ -1,6 +1,6 @@
 import { CHAIN } from '../../constants/enums';
 import type { OrchestratorContext } from './context';
-type StableKey = 'USDT_ETH' | 'USDT_ARB' | 'USDT_BASE' | 'USDT_BNB' | 'USDT_SOL';
+type StableKey = 'USDT_ETH' | 'USDT_ARB' | 'USDT_BASE' | 'USDT_BNB' | 'USDC_BSC' | 'USDT_SOL';
 /**
  * Get $PC/USD price (8 decimals) for the given origin chain's route.
  * Returns 0 on any failure — caller is expected to fall back to

package/src/lib/orchestrator/internals/pc-usd-oracle.js

@@ -15,8 +15,9 @@ const tslib_1 = require("tslib");
  *   - Ethereum / Arbitrum / Base / BNB → WPC/USDT.<route>
  *   - Solana → WPC/USDT.sol
  *
- * Pool pair (USDT vs USDC) is pending Zaryab/Zartaj confirmation — flip the
- * ORIGIN_TO_STABLE map below if they pick USDC.
+ * Confirmed testnet pool-token addresses are sourced from
+ * SYNTHETIC_PUSH_ERC20. Flip ORIGIN_TO_STABLE if a route should use USDC
+ * instead of USDT.
  *
  * Returns price in **8 decimals** (USD per 1 WPC) to match the convention
  * used by PriceFetch.getPrice.
@@ -153,7 +154,7 @@ function getPcUsdPrice(ctx, originChain) {
             const universalCoreAddress = yield ctx.pushClient.readContract({
                 address: gatewayPcAddress,
                 abi: abi_1.UNIVERSAL_GATEWAY_PC,
-                functionName: 'UNIVERSAL_CORE',
+                functionName: 'universalCore',
                 args: [],
             });
             const [wpcAddress, factoryAddress, defaultFeeTier] = yield Promise.all([

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

@@ -8,12 +8,13 @@
  * with `Error("STF")`, fees are burned, and the user sees an opaque
  * library string with no balance signal.
  *
- * `runPreflight` replaces that branch: it checks the **pre-clamp**
- * buffered pool quote against UEA balance (and optionally a PRC-20 burn
- * balance) and either:
- *   - emits `SEND-TX-203-03` (INFO, sufficient) and lets the caller proceed; or
+ * `runPreflight` checks the **pre-clamp** buffered pool quote against UEA
+ * balance (and optionally a PRC-20 burn balance) and either:
+ *   - emits `SEND-TX-203-03` (INFO, sufficient) and lets the caller proceed;
+ *   - emits `SEND-TX-203-03` (WARNING, insufficient) and proceeds when
+ *     enforceGasCheck is false/omitted; or
  *   - emits `SEND-TX-203-03` (ERROR, insufficient) + `SEND-TX-203-04` and
- *     throws `InsufficientUEABalanceError`.
+ *     throws `InsufficientUEABalanceError` when enforceGasCheck is true.
  *
  * The helper is intentionally not "pure" — it emits hooks and may throw.
  * Callers fetch all balances (so the helper itself does no I/O).
@@ -34,6 +35,8 @@ export interface RunPreflightOpts {
     burnToken?: `0x${string}`;
     burnAmount?: bigint;
     prc20Balance?: bigint;
+    /** Defaults to false: warn on shortfall and proceed. */
+    enforceGasCheck?: boolean;
     /** Cascade-only: identifies which segment failed. */
     segmentIndex?: number;
 }

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

@@ -9,12 +9,13 @@
  * with `Error("STF")`, fees are burned, and the user sees an opaque
  * library string with no balance signal.
  *
- * `runPreflight` replaces that branch: it checks the **pre-clamp**
- * buffered pool quote against UEA balance (and optionally a PRC-20 burn
- * balance) and either:
- *   - emits `SEND-TX-203-03` (INFO, sufficient) and lets the caller proceed; or
+ * `runPreflight` checks the **pre-clamp** buffered pool quote against UEA
+ * balance (and optionally a PRC-20 burn balance) and either:
+ *   - emits `SEND-TX-203-03` (INFO, sufficient) and lets the caller proceed;
+ *   - emits `SEND-TX-203-03` (WARNING, insufficient) and proceeds when
+ *     enforceGasCheck is false/omitted; or
  *   - emits `SEND-TX-203-03` (ERROR, insufficient) + `SEND-TX-203-04` and
- *     throws `InsufficientUEABalanceError`.
+ *     throws `InsufficientUEABalanceError` when enforceGasCheck is true.
  *
  * The helper is intentionally not "pure" — it emits hooks and may throw.
  * Callers fetch all balances (so the helper itself does no I/O).
@@ -32,7 +33,7 @@ const errors_1 = require("./errors");
  * sees the actionable PRC-20 shortfall instead of a stale native PC error.
  */
 function runPreflight(opts) {
-    const { ctx, ueaAddress, ueaBalance, requiredValue, gasReserve, pathTag, burnToken, burnAmount, prc20Balance, segmentIndex, } = opts;
+    const { ctx, ueaAddress, ueaBalance, requiredValue, gasReserve, pathTag, burnToken, burnAmount, prc20Balance, enforceGasCheck = false, segmentIndex, } = opts;
     // Each route bucket gets its own preflight IDs so hook streams stay
     // self-consistent within their convention (R2 → 203-xx, R3 → 303-xx,
     // cascade → 003-xx). The three hook formatters share an identical
@@ -54,9 +55,15 @@ function runPreflight(opts) {
     if (burnAmount && burnAmount > BigInt(0) && burnToken) {
         const onHand = prc20Balance !== null && prc20Balance !== void 0 ? prc20Balance : BigInt(0);
         const sufficient = onHand >= burnAmount;
-        (0, context_1.fireProgressHook)(ctx, HOOK_PRE_INFO, burnAmount, onHand, sufficient, ueaAddress, pathTag, { kind: 'PRC20', burnToken, segmentIndex });
-        if (!sufficient) {
-            const shortfall = burnAmount - onHand;
+        const shortfall = sufficient ? BigInt(0) : burnAmount - onHand;
+        (0, context_1.fireProgressHook)(ctx, HOOK_PRE_INFO, burnAmount, onHand, sufficient, ueaAddress, pathTag, {
+            kind: 'PRC20',
+            burnToken,
+            segmentIndex,
+            enforceGasCheck,
+            shortfall,
+        });
+        if (!sufficient && enforceGasCheck) {
             (0, context_1.fireProgressHook)(ctx, HOOK_PRE_FAIL, burnAmount, onHand, shortfall, ueaAddress, pathTag, { kind: 'PRC20', burnToken, segmentIndex });
             throw new errors_1.InsufficientUEABalanceError({
                 required: burnAmount,
@@ -69,25 +76,32 @@ function runPreflight(opts) {
                 segmentIndex,
             });
         }
+        else if (!sufficient) {
+            (0, context_1.printLog)(ctx, `[preflight ${pathTag}] PRC-20 shortfall ${shortfall.toString()} for ${burnToken}; proceeding because enforceGasCheck=false`);
+        }
     }
     // 2. Native (UPC) balance check.
     const totalRequired = requiredValue + gasReserve;
     const sufficient = ueaBalance >= totalRequired;
-    (0, context_1.fireProgressHook)(ctx, HOOK_PRE_INFO, totalRequired, ueaBalance, sufficient, ueaAddress, pathTag, { kind: 'NATIVE', segmentIndex });
+    const shortfall = sufficient ? BigInt(0) : totalRequired - ueaBalance;
+    (0, context_1.fireProgressHook)(ctx, HOOK_PRE_INFO, totalRequired, ueaBalance, sufficient, ueaAddress, pathTag, { kind: 'NATIVE', segmentIndex, enforceGasCheck, shortfall });
     if (sufficient) {
         return { ok: true, adjustedValue: requiredValue };
     }
-    const shortfall = totalRequired - ueaBalance;
-    (0, context_1.fireProgressHook)(ctx, HOOK_PRE_FAIL, totalRequired, ueaBalance, shortfall, ueaAddress, pathTag, { kind: 'NATIVE', segmentIndex });
-    throw new errors_1.InsufficientUEABalanceError({
-        required: totalRequired,
-        available: ueaBalance,
-        shortfall,
-        ueaAddress,
-        pathTag,
-        reason: 'NATIVE',
-        segmentIndex,
-    });
+    if (enforceGasCheck) {
+        (0, context_1.fireProgressHook)(ctx, HOOK_PRE_FAIL, totalRequired, ueaBalance, shortfall, ueaAddress, pathTag, { kind: 'NATIVE', segmentIndex });
+        throw new errors_1.InsufficientUEABalanceError({
+            required: totalRequired,
+            available: ueaBalance,
+            shortfall,
+            ueaAddress,
+            pathTag,
+            reason: 'NATIVE',
+            segmentIndex,
+        });
+    }
+    (0, context_1.printLog)(ctx, `[preflight ${pathTag}] native shortfall ${shortfall.toString()}; proceeding because enforceGasCheck=false`);
+    return { ok: true, adjustedValue: requiredValue };
 }
 /**
  * SVM-only telemetry threshold. Buffered pool quotes above this value

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

@@ -20,6 +20,7 @@ const context_1 = require("./context");
 const error_decoder_1 = require("./error-decoder");
 const errors_1 = require("./errors");
 Object.defineProperty(exports, "PushChainExecutionError", { enumerable: true, get: function () { return errors_1.PushChainExecutionError; } });
+const formatters_1 = require("../../formatters");
 // ============================================================================
 // sendPushTx
 // ============================================================================
@@ -302,7 +303,10 @@ function extractPcTxAndTransform(ctx, pushChainUniversalTx, gatewayTxHash, event
             const failedPcTx = (lastPcTransaction === null || lastPcTransaction === void 0 ? void 0 : lastPcTransaction.status) === 'FAILED'
                 ? lastPcTransaction
                 : pushChainUniversalTx.pcTx.find((pcTx) => pcTx.status === 'FAILED' && pcTx.errorMsg);
-            const errorDetails = (failedPcTx === null || failedPcTx === void 0 ? void 0 : failedPcTx.errorMsg) ? `: ${failedPcTx.errorMsg}` : '';
+            const failedPcTxErrorMsg = (failedPcTx === null || failedPcTx === void 0 ? void 0 : failedPcTx.errorMsg)
+                ? (0, formatters_1.normalizePcInsufficientFundsError)(failedPcTx.errorMsg)
+                : '';
+            const errorDetails = failedPcTxErrorMsg ? `: ${failedPcTxErrorMsg}` : '';
             // Decode known revert selectors and ABI-encoded `Error(string)` reverts
             // into actionable hints. Unknown selectors are logged at INFO so the
             // table can grow from real reverts.