@pushchain/core 5.1.17 → 5.1.18

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

@@ -26,31 +26,13 @@ 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;
+    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
@@ -75,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,
@@ -105,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,

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/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;
 }

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifyDeclineError = classifyDeclineError;
+const formatters_1 = require("../formatters");
 const utils_1 = require("../utils");
 const progress_hook_types_1 = require("./progress-hook.types");
 // Helper to wrap a hook function with timestamp
@@ -22,14 +23,6 @@ const friendlyChain = (chainOrNs) => {
     const key = utils_1.Utils.chains.getChainName(asString);
     return key ? toTitleCase(key) : asString;
 };
-/**
- * Format a wei-denominated UPC bigint as a human-readable PC string for use
- * in progress-hook `message` fields. Used by the pre-flight hooks
- * (203-03/04/05 + 003-03/04/05) so consumers see "956.7834 PC" instead of
- * "956783432238079848707 wei UPC". Response payload bigints are NOT
- * transformed — programmatic consumers still get raw wei.
- */
-const formatPC = (wei, precision = 4) => `${utils_1.Utils.helpers.formatUnits(wei, { decimals: 18, precision })} PC`;
 /**
  * Classify a sign-time error as either a true wallet user-decline
  * (viem `UserRejectedRequestError`, ethers `ACTION_REJECTED`, EIP-1193 4001,
@@ -313,8 +306,8 @@ const RAW_HOOKS_R2 = {
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_03]: (required, available, sufficient, ueaAddress, pathTag, extra) => {
         var _a, _b, _c;
         const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
-        const availableStr = kind === 'PRC20' ? `${available} units` : formatPC(available);
-        const requiredStr = kind === 'PRC20' ? `${required} units` : formatPC(required);
+        const availableStr = kind === 'PRC20' ? `${available} units` : (0, formatters_1.formatPc)(available, 4);
+        const requiredStr = kind === 'PRC20' ? `${required} units` : (0, formatters_1.formatPc)(required, 4);
         return {
             id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_03,
             title: 'Pre-flight Balance Check',
@@ -336,7 +329,7 @@ const RAW_HOOKS_R2 = {
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_04]: (required, available, shortfall, ueaAddress, pathTag, extra) => {
         var _a, _b, _c, _d;
         const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
-        const shortfallStr = kind === 'PRC20' ? `${shortfall} units` : formatPC(shortfall);
+        const shortfallStr = kind === 'PRC20' ? `${shortfall} units` : (0, formatters_1.formatPc)(shortfall, 4);
         const remediation = kind === 'PRC20'
             ? `Bridge the burn token (${(_b = extra === null || extra === void 0 ? void 0 : extra.burnToken) !== null && _b !== void 0 ? _b : 'PRC-20'}) to UEA ${ueaAddress} before retrying.`
             : `Bridge >=${shortfallStr} to UEA ${ueaAddress} before retrying.`;
@@ -360,7 +353,7 @@ const RAW_HOOKS_R2 = {
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_05]: (quoted, threshold, gasToken, pathTag) => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_05,
         title: 'SVM Native-Value Warn Threshold',
-        message: `Buffered pool quote ${formatPC(quoted)} exceeds warn threshold ${formatPC(threshold)} ` +
+        message: `Buffered pool quote ${(0, formatters_1.formatPc)(quoted, 4)} exceeds warn threshold ${(0, formatters_1.formatPc)(threshold, 4)} ` +
             `for ${gasToken} (${pathTag}). Pool may be skewed or quote is unusually large. ` +
             `No action taken — pre-flight will determine if balance covers it.`,
         response: { quoted, threshold, gasToken, pathTag },
@@ -527,8 +520,8 @@ const RAW_HOOKS_R3 = {
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_04]: (required, available, sufficient, ueaAddress, pathTag, extra) => {
         var _a, _b, _c;
         const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
-        const availableStr = kind === 'PRC20' ? `${available} units` : formatPC(available);
-        const requiredStr = kind === 'PRC20' ? `${required} units` : formatPC(required);
+        const availableStr = kind === 'PRC20' ? `${available} units` : (0, formatters_1.formatPc)(available, 4);
+        const requiredStr = kind === 'PRC20' ? `${required} units` : (0, formatters_1.formatPc)(required, 4);
         return {
             id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_04,
             title: 'Pre-flight Balance Check',
@@ -550,7 +543,7 @@ const RAW_HOOKS_R3 = {
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_05]: (required, available, shortfall, ueaAddress, pathTag, extra) => {
         var _a, _b, _c, _d;
         const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
-        const shortfallStr = kind === 'PRC20' ? `${shortfall} units` : formatPC(shortfall);
+        const shortfallStr = kind === 'PRC20' ? `${shortfall} units` : (0, formatters_1.formatPc)(shortfall, 4);
         const remediation = kind === 'PRC20'
             ? `Bridge the burn token (${(_b = extra === null || extra === void 0 ? void 0 : extra.burnToken) !== null && _b !== void 0 ? _b : 'PRC-20'}) to UEA ${ueaAddress} before retrying.`
             : `Bridge >=${shortfallStr} to UEA ${ueaAddress} before retrying.`;
@@ -574,7 +567,7 @@ const RAW_HOOKS_R3 = {
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_06]: (quoted, threshold, gasToken, pathTag) => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_06,
         title: 'SVM Native-Value Warn Threshold',
-        message: `Buffered pool quote ${formatPC(quoted)} exceeds warn threshold ${formatPC(threshold)} ` +
+        message: `Buffered pool quote ${(0, formatters_1.formatPc)(quoted, 4)} exceeds warn threshold ${(0, formatters_1.formatPc)(threshold, 4)} ` +
             `for ${gasToken} (${pathTag}). Pool may be skewed or quote is unusually large. ` +
             `No action taken — pre-flight will determine if balance covers it.`,
         response: { quoted, threshold, gasToken, pathTag },
@@ -786,8 +779,8 @@ const RAW_HOOKS_MULTICHAIN = {
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_03]: (required, available, sufficient, ueaAddress, pathTag, extra) => {
         var _a, _b, _c;
         const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
-        const availableStr = kind === 'PRC20' ? `${available} units` : formatPC(available);
-        const requiredStr = kind === 'PRC20' ? `${required} units` : formatPC(required);
+        const availableStr = kind === 'PRC20' ? `${available} units` : (0, formatters_1.formatPc)(available, 4);
+        const requiredStr = kind === 'PRC20' ? `${required} units` : (0, formatters_1.formatPc)(required, 4);
         return {
             id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_03,
             title: 'Cascade Pre-flight Balance Check',
@@ -809,7 +802,7 @@ const RAW_HOOKS_MULTICHAIN = {
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_04]: (required, available, shortfall, ueaAddress, pathTag, extra) => {
         var _a, _b, _c, _d;
         const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
-        const shortfallStr = kind === 'PRC20' ? `${shortfall} units` : formatPC(shortfall);
+        const shortfallStr = kind === 'PRC20' ? `${shortfall} units` : (0, formatters_1.formatPc)(shortfall, 4);
         const remediation = kind === 'PRC20'
             ? `Bridge the burn token (${(_b = extra === null || extra === void 0 ? void 0 : extra.burnToken) !== null && _b !== void 0 ? _b : 'PRC-20'}) to UEA ${ueaAddress} before retrying.`
             : `Bridge >=${shortfallStr} to UEA ${ueaAddress} before retrying.`;
@@ -833,7 +826,7 @@ const RAW_HOOKS_MULTICHAIN = {
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_05]: (quoted, threshold, gasToken, pathTag) => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_05,
         title: 'Cascade SVM Native-Value Warn Threshold',
-        message: `Buffered pool quote ${formatPC(quoted)} exceeds warn threshold ${formatPC(threshold)} ` +
+        message: `Buffered pool quote ${(0, formatters_1.formatPc)(quoted, 4)} exceeds warn threshold ${(0, formatters_1.formatPc)(threshold, 4)} ` +
             `for ${gasToken} (${pathTag}). Pool may be skewed or quote is unusually large. ` +
             `No action taken — pre-flight will determine if balance covers it.`,
         response: { quoted, threshold, gasToken, pathTag },

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

@@ -77,8 +77,18 @@ export declare class PushChain {
         /**
          * Execute one or more prepared transactions as a cascade across chains.
          * Accepts an array of PreparedUniversalTx (from prepareTransaction).
+         *
+         * @param txs - Prepared transactions to execute as a cascade.
+         * @param options.progressHook - Optional per-call progress callback.
+         *   Additive with the init-time `progressHook` passed to `initialize`:
+         *   both hooks receive every `ProgressEvent` emitted during this call
+         *   (pre-flight, broadcast, and cascade tracking). Dedups by reference
+         *   if it matches the init-time hook. Note: concurrent calls on the
+         *   same instance share the hook channel during the broadcast phase.
          */
-        executeTransactions: (txs: PreparedUniversalTx[]) => Promise<CascadedTxResponse>;
+        executeTransactions: (txs: PreparedUniversalTx[], options?: {
+            progressHook?: (event: ProgressEvent) => void;
+        }) => Promise<CascadedTxResponse>;
         /**
          * Tracks a transaction by hash on Push Chain
          */

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

@@ -84,11 +84,11 @@ class PushChain {
             prepareTransaction: (params) => {
                 return orchestrator.prepareTransaction.bind(orchestrator)(params);
             },
-            executeTransactions: (txs) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            executeTransactions: (txs, options) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 if (this.isReadMode) {
                     throw new Error('Read only mode cannot call executeTransactions function');
                 }
-                return orchestrator.createCascadedBuilder(txs).send();
+                return orchestrator.createCascadedBuilder(txs, options).send();
             }),
             trackTransaction: (txHash, options) => {
                 return orchestrator.trackTransaction.bind(orchestrator)(txHash, options);