@pushchain/core 5.1.16 → 5.1.18

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

@@ -23,7 +23,7 @@ import { type PreflightPathTag } from './errors';
 export interface RunPreflightOpts {
     ctx: OrchestratorContext;
     ueaAddress: `0x${string}`;
-    /** Effective UEA balance in wei UPC (already includes fresh-wallet prediction). */
+    /** Effective UEA balance in native PC wei (already includes fresh-wallet prediction). */
     ueaBalance: bigint;
     /** Buffered pool quote (pre-clamp) — what the SDK would actually attempt. */
     requiredValue: bigint;
@@ -36,45 +36,31 @@ export interface RunPreflightOpts {
     prc20Balance?: bigint;
     /** Cascade-only: identifies which segment failed. */
     segmentIndex?: number;
-    /**
-     * Per-call opt-out (`params.options.allowUnderfundedSwap`). When `true`,
-     * pre-flight logs the shortfall but does NOT fire 203-04 or throw —
-     * caller can fall back to the legacy clamp-and-refund branch.
-     */
-    allowUnderfundedSwap?: boolean;
 }
 export type PreflightResult = {
     ok: true;
     /** What `nativeValueForGas` should be (== requiredValue when sufficient). */
     adjustedValue: bigint;
-} | {
-    ok: false;
-    /** Set when allowUnderfundedSwap=true: the legacy clamped value. */
-    legacyClampedValue: bigint;
 };
 /**
  * Pre-flight check. PRC-20 balance is checked before the native check —
  * a missing burn token fails before the gas-balance check, so the user
- * sees the actionable PRC-20 shortfall instead of a stale UPC error.
- *
- * Returns a result object instead of throwing for the legacy opt-out
- * path. The throw happens here (not in the caller) for the default
- * `allowUnderfundedSwap=false` case so all 6 paths share one throw site.
+ * sees the actionable PRC-20 shortfall instead of a stale native PC error.
  */
 export declare function runPreflight(opts: RunPreflightOpts): PreflightResult;
 /**
  * SVM-only telemetry threshold. Buffered pool quotes above this value
- * fire `SEND-TX-203-05` (single-route) or `SEND-TX-003-05` (cascade).
- * The threshold is for visibility, not truncation — pre-flight handles
- * drain protection. v2 may add a hard cap once telemetry justifies a
- * number.
+ * fire `SEND-TX-203-05` (R2 single-route), `SEND-TX-303-06` (R3
+ * single-route), or `SEND-TX-003-05` (cascade). The threshold is for
+ * visibility, not truncation — pre-flight handles drain protection.
+ * v2 may add a hard cap once telemetry justifies a number.
  */
 export declare const SVM_NATIVE_VALUE_WARN_THRESHOLD: bigint;
 /**
  * Fire the SVM warn-threshold hook + log line if the buffered quote
  * exceeds the threshold. Non-blocking; `nativeValueForGas` is not
- * truncated by the caller. The hook ID switches to the cascade 0xx
- * bucket (`003-05`) when `pathTag === 'CASCADE'` so cascade streams
- * stay self-consistent.
+ * truncated by the caller. The hook ID switches between buckets so
+ * each stream stays self-consistent within its convention (R2 → 203,
+ * R3 → 303, cascade → 003).
  */
 export declare function maybeFireSvmWarnThreshold(ctx: OrchestratorContext, bufferedQuote: bigint, gasToken: `0x${string}`, pathTag: PreflightPathTag): void;

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

@@ -26,41 +26,29 @@ exports.maybeFireSvmWarnThreshold = maybeFireSvmWarnThreshold;
 const context_1 = require("./context");
 const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
 const errors_1 = require("./errors");
-/**
- * Internal: compute the legacy clamp value (matches the pre-existing
- * branches in route-handlers.ts:643-659 / :968-980 / :1396-1412).
- * Returned only when `allowUnderfundedSwap=true`.
- */
-function legacyClamp(ueaBalance, requiredValue, gasReserve) {
-    if (ueaBalance >= requiredValue + gasReserve)
-        return requiredValue;
-    if (ueaBalance > gasReserve)
-        return ueaBalance - gasReserve;
-    if (ueaBalance > BigInt(0))
-        return ueaBalance < requiredValue ? ueaBalance : requiredValue;
-    return BigInt(0);
-}
 /**
  * Pre-flight check. PRC-20 balance is checked before the native check —
  * a missing burn token fails before the gas-balance check, so the user
- * sees the actionable PRC-20 shortfall instead of a stale UPC error.
- *
- * Returns a result object instead of throwing for the legacy opt-out
- * path. The throw happens here (not in the caller) for the default
- * `allowUnderfundedSwap=false` case so all 6 paths share one throw site.
+ * 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, allowUnderfundedSwap, } = opts;
-    // Cascade context emits 003-xx (cascade 0xx bucket); single routes (R2/R3)
-    // emit 203-xx (R2 bucket). The two ID sets share an identical formatter
+    const { ctx, ueaAddress, ueaBalance, requiredValue, gasReserve, pathTag, burnToken, burnAmount, prc20Balance, 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
     // signature, so the runtime branching is just an ID swap at each fire site.
     const isCascade = pathTag === 'CASCADE';
+    const isR3 = pathTag === 'R3_EVM' || pathTag === 'R3_SVM';
     const HOOK_PRE_INFO = isCascade
         ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_03
-        : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_03;
+        : isR3
+            ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_04
+            : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_03;
     const HOOK_PRE_FAIL = isCascade
         ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_04
-        : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_04;
+        : isR3
+            ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_05
+            : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_04;
     // 1. PRC-20 burn-balance check (skipped when burnAmount = 0 — R3 paths
     //    structurally hold zero of the source-chain native PRC-20; see plan §9 #4).
     if (burnAmount && burnAmount > BigInt(0) && burnToken) {
@@ -69,15 +57,6 @@ function runPreflight(opts) {
         (0, context_1.fireProgressHook)(ctx, HOOK_PRE_INFO, burnAmount, onHand, sufficient, ueaAddress, pathTag, { kind: 'PRC20', burnToken, segmentIndex });
         if (!sufficient) {
             const shortfall = burnAmount - onHand;
-            if (allowUnderfundedSwap) {
-                (0, context_1.printLog)(ctx, `[preflight ${pathTag}] PRC-20 shortfall ${shortfall} of ${burnToken}; ` +
-                    `allowUnderfundedSwap=true — proceeding with legacy clamp behaviour, ` +
-                    `swap is expected to revert with InsufficientBalance(0xf4d678b8) on-chain.`);
-                return {
-                    ok: false,
-                    legacyClampedValue: legacyClamp(ueaBalance, requiredValue, gasReserve),
-                };
-            }
             (0, context_1.fireProgressHook)(ctx, HOOK_PRE_FAIL, burnAmount, onHand, shortfall, ueaAddress, pathTag, { kind: 'PRC20', burnToken, segmentIndex });
             throw new errors_1.InsufficientUEABalanceError({
                 required: burnAmount,
@@ -99,13 +78,6 @@ function runPreflight(opts) {
         return { ok: true, adjustedValue: requiredValue };
     }
     const shortfall = totalRequired - ueaBalance;
-    if (allowUnderfundedSwap) {
-        const clamped = legacyClamp(ueaBalance, requiredValue, gasReserve);
-        (0, context_1.printLog)(ctx, `[preflight ${pathTag}] UPC shortfall ${shortfall} wei; ` +
-            `allowUnderfundedSwap=true — proceeding with legacy clamped value ${clamped}, ` +
-            `swap may revert inside Uniswap with Error("STF") if the clamp under-funds the pool quote.`);
-        return { ok: false, legacyClampedValue: clamped };
-    }
     (0, context_1.fireProgressHook)(ctx, HOOK_PRE_FAIL, totalRequired, ueaBalance, shortfall, ueaAddress, pathTag, { kind: 'NATIVE', segmentIndex });
     throw new errors_1.InsufficientUEABalanceError({
         required: totalRequired,
@@ -119,25 +91,27 @@ function runPreflight(opts) {
 }
 /**
  * SVM-only telemetry threshold. Buffered pool quotes above this value
- * fire `SEND-TX-203-05` (single-route) or `SEND-TX-003-05` (cascade).
- * The threshold is for visibility, not truncation — pre-flight handles
- * drain protection. v2 may add a hard cap once telemetry justifies a
- * number.
+ * fire `SEND-TX-203-05` (R2 single-route), `SEND-TX-303-06` (R3
+ * single-route), or `SEND-TX-003-05` (cascade). The threshold is for
+ * visibility, not truncation — pre-flight handles drain protection.
+ * v2 may add a hard cap once telemetry justifies a number.
  */
 exports.SVM_NATIVE_VALUE_WARN_THRESHOLD = BigInt(5000) * BigInt(1e18);
 /**
  * Fire the SVM warn-threshold hook + log line if the buffered quote
  * exceeds the threshold. Non-blocking; `nativeValueForGas` is not
- * truncated by the caller. The hook ID switches to the cascade 0xx
- * bucket (`003-05`) when `pathTag === 'CASCADE'` so cascade streams
- * stay self-consistent.
+ * truncated by the caller. The hook ID switches between buckets so
+ * each stream stays self-consistent within its convention (R2 → 203,
+ * R3 → 303, cascade → 003).
  */
 function maybeFireSvmWarnThreshold(ctx, bufferedQuote, gasToken, pathTag) {
     if (bufferedQuote <= exports.SVM_NATIVE_VALUE_WARN_THRESHOLD)
         return;
     const HOOK_WARN = pathTag === 'CASCADE'
         ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_05
-        : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_05;
+        : pathTag === 'R3_EVM' || pathTag === 'R3_SVM'
+            ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_06
+            : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_05;
     (0, context_1.fireProgressHook)(ctx, HOOK_WARN, bufferedQuote, exports.SVM_NATIVE_VALUE_WARN_THRESHOLD, gasToken, pathTag);
     (0, context_1.printLog)(ctx, `[preflight ${pathTag}] SVM warn-threshold tripped: bufferedQuote=${bufferedQuote} > ` +
         `${exports.SVM_NATIVE_VALUE_WARN_THRESHOLD} for gasToken=${gasToken} — pool may be skewed`);

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

@@ -536,7 +536,7 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
             accessList: Array.isArray(tx.accessList) ? [...tx.accessList] : [],
             // 6. Utilities
             wait: (waitOptions) => tslib_1.__awaiter(this, void 0, void 0, function* () {
-                var _a, _b, _c, _d, _e, _f;
+                var _a, _b, _c, _d, _e, _f, _g, _h, _j;
                 // For trackTransaction replays the tx is historical — cosmos already
                 // has the full graph indexed, so the 20s/30s initial-wait buffers
                 // designed for live sends are pure deadweight. Default them to 0 when
@@ -605,9 +605,17 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                             timeout: outboundTimeoutMs,
                             progressHook: outboundTranslator,
                         });
-                        emit(hooks.success(outboundDetails));
-                        // Merge external chain details into receipt
-                        baseReceipt = Object.assign(Object.assign({}, baseReceipt), { externalTxHash: outboundDetails.externalTxHash, externalChain: outboundDetails.destinationChain, externalExplorerUrl: outboundDetails.explorerUrl, externalRecipient: outboundDetails.recipient, externalAmount: outboundDetails.amount, externalAssetAddr: outboundDetails.assetAddr, externalStatus: 'success' });
+                        // `outboundDetails.externalTxHash` is the raw `0x`-hex form (kept
+                        // internally so the R3 inbound tracker below can query Cosmos with
+                        // it via `waitForInboundPushTx → findChildUtxIdFromExternalTx`).
+                        // For every USER-FACING surface (progress hook event + receipt) we
+                        // want the chain-native form so consumers can paste it straight
+                        // into an explorer / RPC: base58 for SVM, hex for EVM. Build a
+                        // display copy and use it for both the hook and the receipt.
+                        const displayExternalTxHash = (_f = (0, helpers_1.toExternalTxHashDisplay)(outboundDetails.destinationChain, outboundDetails.externalTxHash)) !== null && _f !== void 0 ? _f : outboundDetails.externalTxHash;
+                        const userFacingOutboundDetails = Object.assign(Object.assign({}, outboundDetails), { externalTxHash: displayExternalTxHash });
+                        emit(hooks.success(userFacingOutboundDetails));
+                        baseReceipt = Object.assign(Object.assign({}, baseReceipt), { externalTxHash: displayExternalTxHash, externalChain: outboundDetails.destinationChain, externalExplorerUrl: outboundDetails.explorerUrl, externalRecipient: outboundDetails.recipient, externalAmount: outboundDetails.amount, externalAssetAddr: outboundDetails.assetAddr, externalStatus: 'success' });
                         // R3 round-trip: poll Push Chain for the inbound tx that the
                         // source-chain CEA's sendUniversalTxToUEA call produces. Correlate
                         // via the outbound external tx hash → child UTX id → child pcTx.
@@ -637,7 +645,7 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                                 }
                                 else {
                                     // status === 'failed' (terminal failure status from chain)
-                                    const failMsg = (_f = inbound.errorMessage) !== null && _f !== void 0 ? _f : 'inbound execution failed on Push Chain';
+                                    const failMsg = (_g = inbound.errorMessage) !== null && _g !== void 0 ? _g : 'inbound execution failed on Push Chain';
                                     emit(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](failMsg, 'inbound', targetChain));
                                     baseReceipt = Object.assign(Object.assign({}, baseReceipt), { pushInboundUtxId: inbound.childUtxId, pushInboundTxHash: inbound.pushTxHash || undefined, externalStatus: 'failed', externalError: failMsg });
                                 }
@@ -669,8 +677,16 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                         // observed tx hash is carried by OutboundFailedError — expose it
                         // as externalTxHash so consumers can link to the explorer.
                         const failedExternalTxHash = error instanceof outbound_sync_1.OutboundFailedError ? error.externalTxHash : undefined;
-                        baseReceipt = Object.assign(Object.assign(Object.assign({}, baseReceipt), { externalStatus: isTimeout ? 'timeout' : 'failed', externalError: errMsg }), (failedExternalTxHash
-                            ? { externalTxHash: failedExternalTxHash }
+                        // Normalize to chain-native display form for SVM (base58); EVM hex
+                        // passes through unchanged. `OutboundFailedError.destinationChain`
+                        // is a chain namespace string (e.g., 'solana:devnet') — convert to
+                        // the CHAIN enum via the same helper used in outbound-sync.
+                        const failedChain = error instanceof outbound_sync_1.OutboundFailedError && error.destinationChain
+                            ? (_h = (0, helpers_1.chainFromNamespace)(error.destinationChain)) !== null && _h !== void 0 ? _h : undefined
+                            : undefined;
+                        const failedExternalTxHashDisplay = (_j = (0, helpers_1.toExternalTxHashDisplay)(failedChain, failedExternalTxHash)) !== null && _j !== void 0 ? _j : failedExternalTxHash;
+                        baseReceipt = Object.assign(Object.assign(Object.assign({}, baseReceipt), { externalStatus: isTimeout ? 'timeout' : 'failed', externalError: errMsg }), (failedExternalTxHashDisplay
+                            ? { externalTxHash: failedExternalTxHashDisplay }
                             : {}));
                         // Outbound polling timed out or failed — return the annotated
                         // receipt without throwing. Push Chain tx succeeded, external

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

@@ -281,7 +281,7 @@ function executeMultiChain(ctx, params, executeFn) {
  */
 function executeUoaToCea(ctx, params, executeFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d;
+        var _a, _b, _c;
         const target = params.to;
         const targetChain = target.chain;
         const targetAddress = target.address;
@@ -430,12 +430,16 @@ function executeUoaToCea(ctx, params, executeFn) {
                 }
             }
         }
-        // Pool-quote + 10% safety buffer. Over-send is refunded by the contract.
+        // estimateNativeValueForSwap applies the full 2.2x safety buffer
+        // internally (pool-slippage cushion + the 10% headroom that used to be
+        // multiplied here). Folded into one place so the function's cap branch
+        // bounds the final value — the previous outer ×110/100 on top of the
+        // inner cap broke preflight whenever the cap fired. Over-send is refunded
+        // by the contract.
         let nativeValueForGas = BigInt(0);
         if (universalCoreAddress && gasFee > BigInt(0)) {
-            const estimated = yield (0, gas_calculator_1.estimateNativeValueForSwap)(ctx, universalCoreAddress, gasToken, gasFee, effectiveBalance);
-            nativeValueForGas = (estimated * BigInt(110)) / BigInt(100);
-            (0, context_1.printLog)(ctx, `executeUoaToCea — nativeValueForGas: pool-quote=${estimated.toString()}, with 10% buffer=${nativeValueForGas.toString()}`);
+            nativeValueForGas = yield (0, gas_calculator_1.estimateNativeValueForSwap)(ctx, universalCoreAddress, gasToken, gasFee, effectiveBalance);
+            (0, context_1.printLog)(ctx, `executeUoaToCea — nativeValueForGas=${nativeValueForGas.toString()} (includes 2.2x buffer)`);
         }
         // Hard safety cap so a broken pool price can't drain the UEA.
         if (nativeValueForGas > EVM_NATIVE_VALUE_SAFETY_CAP) {
@@ -457,8 +461,7 @@ function executeUoaToCea(ctx, params, executeFn) {
                 args: [ueaAddress],
             });
         }
-        const allowUnderfundedR2Evm = ((_d = params.options) === null || _d === void 0 ? void 0 : _d.allowUnderfundedSwap) === true;
-        const preflightR2Evm = (0, preflight_1.runPreflight)({
+        (0, preflight_1.runPreflight)({
             ctx,
             ueaAddress,
             ueaBalance: effectiveBalance,
@@ -468,13 +471,8 @@ function executeUoaToCea(ctx, params, executeFn) {
             burnToken: prc20Token,
             burnAmount,
             prc20Balance: prc20BalanceR2Evm,
-            allowUnderfundedSwap: allowUnderfundedR2Evm,
         });
-        if (!preflightR2Evm.ok) {
-            nativeValueForGas = preflightR2Evm.legacyClampedValue;
-            (0, context_1.printLog)(ctx, `executeUoaToCea — allowUnderfundedSwap=true; using legacy clamped value ${nativeValueForGas.toString()}`);
-        }
-        // ok=true → nativeValueForGas already covers required + reserve; no adjust needed.
+        // Preflight success means nativeValueForGas already covers required + reserve; no adjust needed.
         // Build outbound multicalls (approve burn + sendUniversalTxOutbound with native value)
         const outboundMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
             prc20Token,
@@ -536,7 +534,7 @@ function executeUoaToCea(ctx, params, executeFn) {
  */
 function executeUoaToCeaSvm(ctx, params, target, executeFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        var _a, _b, _c, _d, _e, _f, _g, _h;
         const targetChain = target.chain;
         const targetAddress = target.address; // 0x-prefixed, 32 bytes
         const ueaAddress = (0, uea_manager_1.computeUEAOffchain)(ctx);
@@ -648,8 +646,10 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
         }
         const ueaNonce = (!isUEADeployed || isNativePushEOASvm) ? BigInt(0) : yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress);
         // R2 does NOT use Case A/B/C gas abstraction (scoped to R1 + R3 only).
-        // Size msg.value from the live WPC/gasToken Uniswap V3 pool quote plus
-        // a 10% safety buffer. swapAndBurnGas refunds the excess as PC via
+        // Size msg.value from the live WPC/gasToken Uniswap V3 pool quote. The
+        // 2.2x safety buffer is applied inside estimateNativeValueForSwap (was
+        // split as inner 2x + outer 10% — combined to keep the cap branch
+        // mathematically correct). swapAndBurnGas refunds the excess as PC via
         // refundUnusedGas.
         //
         // SVM pools (WPC/pSOL) are thinner than EVM pools so the pool-quote can
@@ -664,9 +664,10 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
         const SVM_GAS_RESERVE = BigInt(3e18); // 3 UPC for outer-tx gas
         let nativeValueForGas = BigInt(0);
         if (universalCoreAddress && gasFee > BigInt(0)) {
-            const estimated = yield (0, gas_calculator_1.estimateNativeValueForSwap)(ctx, universalCoreAddress, gasToken, gasFee, ueaBalance);
-            nativeValueForGas = (estimated * BigInt(110)) / BigInt(100);
-            (0, context_1.printLog)(ctx, `executeUoaToCeaSvm — nativeValueForGas: pool-quote=${estimated.toString()}, with 10% buffer=${nativeValueForGas.toString()}`);
+            // 2.2x safety buffer is applied inside estimateNativeValueForSwap so
+            // the function's balance-cap branch bounds the final value correctly.
+            nativeValueForGas = yield (0, gas_calculator_1.estimateNativeValueForSwap)(ctx, universalCoreAddress, gasToken, gasFee, ueaBalance);
+            (0, context_1.printLog)(ctx, `executeUoaToCeaSvm — nativeValueForGas=${nativeValueForGas.toString()} (includes 2.2x buffer)`);
             (0, preflight_1.maybeFireSvmWarnThreshold)(ctx, nativeValueForGas, gasToken, 'R2_SVM');
         }
         // Pre-flight: throws InsufficientUEABalanceError when UEA cannot cover
@@ -688,8 +689,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
                 args: [ueaAddress],
             });
         }
-        const allowUnderfundedR2Svm = ((_j = params.options) === null || _j === void 0 ? void 0 : _j.allowUnderfundedSwap) === true;
-        const preflightR2Svm = (0, preflight_1.runPreflight)({
+        (0, preflight_1.runPreflight)({
             ctx,
             ueaAddress,
             ueaBalance,
@@ -699,12 +699,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
             burnToken: prc20Token,
             burnAmount,
             prc20Balance: prc20BalanceR2Svm,
-            allowUnderfundedSwap: allowUnderfundedR2Svm,
         });
-        if (!preflightR2Svm.ok) {
-            nativeValueForGas = preflightR2Svm.legacyClampedValue;
-            (0, context_1.printLog)(ctx, `executeUoaToCeaSvm — allowUnderfundedSwap=true; using legacy clamped value ${nativeValueForGas.toString()}`);
-        }
         // --- Build Push Chain multicalls (approve + sendUniversalTxOutbound) ---
         // Reuse the same builder as EVM — this part is identical
         const pushChainMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
@@ -769,7 +764,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
  */
 function executeCeaToPush(ctx, params, executeFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        var _a, _b, _c, _d, _e, _f, _g, _h;
         // 1. Validate and extract source chain
         if (!((_a = params.from) === null || _a === void 0 ? void 0 : _a.chain)) {
             throw new Error('Route 3 (CEA -> Push) requires from.chain to specify the source CEA chain');
@@ -903,8 +898,8 @@ function executeCeaToPush(ctx, params, executeFn) {
             // so the inbound will arrive when the UEA nonce is already incremented.
             pushPayload = (0, payload_builders_1.buildInboundUniversalPayload)(multicallPayload, { nonce: ueaNonce + BigInt(1) });
         }
-        // Build sendUniversalTxToUEA self-call on CEA
-        // CEA multicall: to=CEA (self-call), value=0
+        // Build sendUniversalTxToUEA self-call on CEA. CEA self-calls must always
+        // use value=0; native sends spend from the CEA's existing balance.
         // CEA internally calls gateway.sendUniversalTxFromCEA(...)
         // Uses bridgeAmount (= burn amount deposited by Vault)
         const sendUniversalTxCall = (0, payload_builders_1.buildSendUniversalTxToUEA)(ceaAddress, // to: CEA address (self-call)
@@ -929,13 +924,14 @@ function executeCeaToPush(ctx, params, executeFn) {
         // tokens FROM the CEA back to Push Chain, not to round-trip them.
         const prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
         const burnAmount = BigInt(0);
+        const outboundGasLimit = (_f = params.gasLimit) !== null && _f !== void 0 ? _f : selectors_1.DEFAULT_CEA_TO_PUSH_GAS_LIMIT;
         (0, context_1.printLog)(ctx, `executeCeaToPush — prc20Token: ${prc20Token}, burnAmount: ${burnAmount.toString()}`);
         // 9. Build outbound request (same structure as Route 2)
         // target = CEA address (for self-execution), value = 0 in payload
         const outboundReq = (0, payload_builders_1.buildOutboundRequest)(ceaAddress, // target: CEA address (to=CEA for self-execution)
         prc20Token, // token: native PRC-20 for source chain (for namespace lookup)
         burnAmount, // amount: 0 (payload-only, CEA uses its own balance)
-        (_f = params.gasLimit) !== null && _f !== void 0 ? _f : BigInt(0), ceaPayload, // payload: ABI-encoded CEA multicall
+        outboundGasLimit, ceaPayload, // payload: ABI-encoded CEA multicall
         ueaAddress // revertRecipient: UEA
         );
         (0, context_1.printLog)(ctx, `executeCeaToPush — outbound request: ${JSON.stringify({
@@ -957,10 +953,9 @@ function executeCeaToPush(ctx, params, executeFn) {
         let gasToken = selectors_1.ZERO_ADDRESS;
         let sizingDecisionR3;
         if (prc20Token !== selectors_1.ZERO_ADDRESS) {
-            const gasLimit = outboundReq.gasLimit;
             (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_01, sourceChain);
             try {
-                const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit, sourceChain);
+                const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, outboundGasLimit, sourceChain);
                 gasToken = result.gasToken;
                 gasFee = result.gasFee;
                 protocolFeeR3 = result.protocolFee;
@@ -1040,20 +1035,14 @@ function executeCeaToPush(ctx, params, executeFn) {
         // Pre-flight (R3 EVM): no PRC-20 burn check — `burnAmount = 0` makes this
         // payload-only (UEA never holds the source-chain PRC-20; see plan §9 #4).
         // Native UPC check still applies for the gas swap.
-        const allowUnderfundedR3Evm = ((_j = params.options) === null || _j === void 0 ? void 0 : _j.allowUnderfundedSwap) === true;
-        const preflightR3Evm = (0, preflight_1.runPreflight)({
+        (0, preflight_1.runPreflight)({
             ctx,
             ueaAddress,
             ueaBalance: effectiveBalance,
             requiredValue: nativeValueForGas,
             gasReserve: OUTBOUND_GAS_RESERVE_R3,
             pathTag: 'R3_EVM',
-            allowUnderfundedSwap: allowUnderfundedR3Evm,
         });
-        if (!preflightR3Evm.ok) {
-            nativeValueForGas = preflightR3Evm.legacyClampedValue;
-            (0, context_1.printLog)(ctx, `executeCeaToPush — allowUnderfundedSwap=true; using legacy clamped value ${nativeValueForGas.toString()}`);
-        }
         // 12. Build Push Chain multicalls (approvals + sendUniversalTxOutbound)
         const pushChainMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
             prc20Token,
@@ -1118,7 +1107,7 @@ function executeCeaToPush(ctx, params, executeFn) {
  */
 function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c, _d;
         if (typeof params.to !== 'string') {
             throw new Error('Route 3 SVM (CEA -> Push): to must be a Push Chain address (string), not a ChainTarget');
         }
@@ -1266,20 +1255,14 @@ function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
         // Pre-flight (R3 SVM): no PRC-20 burn check — `burnAmount = 1` is a legacy
         // precompile-validation shim against a token UEAs structurally don't hold
         // (see plan §9 #4 / §10.2 latent-bug ticket). Native UPC check still applies.
-        const allowUnderfundedR3Svm = ((_e = params.options) === null || _e === void 0 ? void 0 : _e.allowUnderfundedSwap) === true;
-        const preflightR3Svm = (0, preflight_1.runPreflight)({
+        (0, preflight_1.runPreflight)({
             ctx,
             ueaAddress,
             ueaBalance: currentBalance,
             requiredValue: nativeValueForGas,
             gasReserve: OUTBOUND_GAS_RESERVE_R3_SVM,
             pathTag: 'R3_SVM',
-            allowUnderfundedSwap: allowUnderfundedR3Svm,
         });
-        if (!preflightR3Svm.ok) {
-            nativeValueForGas = preflightR3Svm.legacyClampedValue;
-            (0, context_1.printLog)(ctx, `executeCeaToPushSvm — allowUnderfundedSwap=true; using legacy clamped value ${nativeValueForGas.toString()}`);
-        }
         // Build Push Chain multicalls (approvals + sendUniversalTxOutbound)
         const pushChainMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
             prc20Token,
@@ -1559,7 +1542,8 @@ function buildPayloadForRoute(ctx, params, route, nonce) {
                     const multicallPayload = (0, payload_builder_1.buildMulticallPayloadData)(ctx, pushDestination, multicallData);
                     pushPayload = (0, payload_builders_1.buildInboundUniversalPayload)(multicallPayload, { nonce: ueaNonceHop + BigInt(1) });
                 }
-                // Build sendUniversalTxToUEA self-call on CEA (to=CEA, value=0)
+                // Build sendUniversalTxToUEA self-call on CEA. CEA self-calls must
+                // always use value=0; native sends spend from the CEA balance.
                 const sendCall = (0, payload_builders_1.buildSendUniversalTxToUEA)(ceaAddress, tokenAddress, amount, pushPayload, ceaAddress);
                 ceaMulticalls.push(sendCall);
                 const ceaPayload = (0, payload_builders_1.buildCeaMulticallPayload)(ceaMulticalls);
@@ -1567,7 +1551,8 @@ function buildPayloadForRoute(ctx, params, route, nonce) {
                 // Route 3: CEA uses its own pre-existing balance — no PRC-20 burn needed.
                 // burnAmount = 0 makes this a payload-only outbound relay.
                 const burnAmount = BigInt(0);
-                const outboundReq = (0, payload_builders_1.buildOutboundRequest)(ceaAddress, prc20Token, burnAmount, (_l = params.gasLimit) !== null && _l !== void 0 ? _l : BigInt(0), ceaPayload, ueaAddress);
+                const outboundGasLimit = (_l = params.gasLimit) !== null && _l !== void 0 ? _l : selectors_1.DEFAULT_CEA_TO_PUSH_GAS_LIMIT;
+                const outboundReq = (0, payload_builders_1.buildOutboundRequest)(ceaAddress, prc20Token, burnAmount, outboundGasLimit, ceaPayload, ueaAddress);
                 return { payload: ceaPayload, gatewayRequest: outboundReq };
             }
             default:

package/src/lib/orchestrator/internals/tx-transformer.js

@@ -176,7 +176,8 @@ function reconstructR3(universalTxResponse, universalTxData, isFailed, errorMsg)
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_02](universalTxResponse.from, ceaAddress, sourceChain));
     // R3 pre-flight reconstruction — R3 EVM burnAmount=0, R3 SVM burnAmount=0
     // (post-fix). Only the NATIVE pre-flight check fires; no PRC-20 second hook.
-    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_03](BigInt(0), BigInt(0), true, universalTxResponse.from, 'R3_EVM', { kind: 'NATIVE' }));
+    // R3 single-route uses 303-04 (R3 bucket); see runPreflight in preflight.ts.
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_04](BigInt(0), BigInt(0), true, universalTxResponse.from, 'R3_EVM', { kind: 'NATIVE' }));
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_01]());
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_02]());
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_03]());

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

@@ -85,9 +85,15 @@ export declare class Orchestrator {
      * The cascade composes all hops bottom-to-top into a single Push Chain tx.
      *
      * @param preparedTxs - Array of prepared transactions
+     * @param options - Optional per-call options. `progressHook` is additive with
+     *   the init-time hook from `PushChain.initialize` and receives every
+     *   `ProgressEvent` emitted during this cascade (pre-flight, broadcast, and
+     *   tracking). Dedups by reference if it matches the init-time hook.
      * @returns Object with send() method
      */
-    createCascadedBuilder(preparedTxs: PreparedUniversalTx[]): {
+    createCascadedBuilder(preparedTxs: PreparedUniversalTx[], options?: {
+        progressHook?: (event: ProgressEvent) => void;
+    }): {
         send: () => Promise<CascadedTxResponse>;
     };
     /**

package/src/lib/orchestrator/orchestrator.js

@@ -30,6 +30,7 @@ class Orchestrator {
         return {
             executeFn: this.execute.bind(this),
             waitForOutboundTxFn: (hash, opts) => (0, internals_1.waitForOutboundTx)(this.ctx, hash, opts),
+            waitForInboundPushTxFn: (hash, sourceChain, opts) => (0, internals_1.waitForInboundPushTx)(this.ctx, hash, sourceChain, opts),
             waitForAllOutboundTxsFn: (hash, hops, opts) => (0, internals_1.waitForAllOutboundTxsV2)(this.ctx, hash, hops, opts),
         };
     }
@@ -296,10 +297,47 @@ class Orchestrator {
      * The cascade composes all hops bottom-to-top into a single Push Chain tx.
      *
      * @param preparedTxs - Array of prepared transactions
+     * @param options - Optional per-call options. `progressHook` is additive with
+     *   the init-time hook from `PushChain.initialize` and receives every
+     *   `ProgressEvent` emitted during this cascade (pre-flight, broadcast, and
+     *   tracking). Dedups by reference if it matches the init-time hook.
      * @returns Object with send() method
      */
-    createCascadedBuilder(preparedTxs) {
-        return (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks());
+    createCascadedBuilder(preparedTxs, options) {
+        const perCallHook = options === null || options === void 0 ? void 0 : options.progressHook;
+        if (!perCallHook) {
+            return (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks());
+        }
+        // Wrap ctx.progressHook for the synchronous send() phase — captures every
+        // fireProgressHook(ctx, ...) call during pre-flight, composeCascade, and
+        // the Push Chain broadcast. Restored when send() resolves/rejects so the
+        // wrapper doesn't leak across calls.
+        //
+        // For the asynchronous tracking phase (waitForAll), we pass perCallHook as
+        // the cascade builder's `defaultEventHook` — waitForAll falls back to it
+        // when callers don't pass their own `eventHook`, and the existing
+        // `dispatchCascadeProgressEvent` path delivers events to BOTH that hook
+        // and ctx.progressHook (the init-time hook, restored by then) with
+        // reference-dedup.
+        const innerBuilder = (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks(), perCallHook);
+        return {
+            send: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                const originalHook = this.progressHook;
+                const wrapped = (event) => {
+                    if (originalHook && originalHook !== perCallHook) {
+                        originalHook(event);
+                    }
+                    perCallHook(event);
+                };
+                this.progressHook = wrapped;
+                try {
+                    return yield innerBuilder.send();
+                }
+                finally {
+                    this.progressHook = originalHook;
+                }
+            }),
+        };
     }
     /**
      * Queries gas fee for an outbound transaction from the UniversalCore contract.

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

@@ -397,20 +397,6 @@ export type UniversalExecuteParams = Omit<ExecuteParams, 'to'> & {
      * Only applicable for Route 2 (UOA_TO_CEA) on EVM chains.
      */
     migration?: boolean;
-    /**
-     * Per-call SDK behaviour overrides. Reserved for opt-out flags that must
-     * not affect the global orchestrator config.
-     */
-    options?: {
-        /**
-         * Restore the legacy clamp-and-refund behaviour for outbound paths whose
-         * UEA balance is below the buffered pool quote. Default `false` — the
-         * SDK throws `InsufficientUEABalanceError` (see `runPreflight`) and does
-         * NOT submit a cosmos tx. Set `true` only when the caller intentionally
-         * relies on `swapAndBurnGas` refunds to power through low balances.
-         */
-        allowUnderfundedSwap?: boolean;
-    };
 };
 /**
  * Account metadata for SVM CPI execution (Solana Gateway pattern).
@@ -514,6 +500,10 @@ export interface HopDescriptor {
     svmPayload?: `0x${string}`;
     /** Whether this hop is a CEA migration (raw MIGRATION_SELECTOR payload) */
     isMigration?: boolean;
+    /** Whether this Route 3 hop only seeds native PC into the UEA. @internal */
+    nativeSeedOnly?: boolean;
+    /** Native PC amount seeded by a value-only Route 3 hop. @internal */
+    nativeSeedAmount?: bigint;
     /** SDK 5.2 gas-abstraction sizing decision for this hop. @internal */
     sizing?: import('./internals/gas-usd-sizer').GasSizingDecision;
 }