@pushchain/core 5.1.17 → 5.1.18

package/src/lib/orchestrator/internals/error-decoder.d.ts

@@ -10,12 +10,8 @@
  * Unknown selectors fall through with `kind: 'unknown'` so callers can log
  * them at INFO and grow the table from real reverts.
  *
- * The selector→name mappings below are EMPIRICAL: they were observed in
- * production e2e logs and SDK test fixtures. `keccak256` of the obvious
- * parameterless signatures (e.g. `keccak256("InsufficientBalance()")` =
- * `0x01e1e567`) does NOT reproduce the listed selectors, so the deployed-
- * source mapping is still unverified. Names and hints are worded as
- * "likely cause" until the bytecode-source trace lands.
+ * The selector→name mappings below come from source-verified custom errors
+ * where available, with production/e2e observations kept as provenance.
  */
 export interface KnownErrorSelector {
     /** Best-effort error name. Worded as a likely cause until source-traced. */

package/src/lib/orchestrator/internals/error-decoder.js

@@ -11,12 +11,8 @@
  * Unknown selectors fall through with `kind: 'unknown'` so callers can log
  * them at INFO and grow the table from real reverts.
  *
- * The selector→name mappings below are EMPIRICAL: they were observed in
- * production e2e logs and SDK test fixtures. `keccak256` of the obvious
- * parameterless signatures (e.g. `keccak256("InsufficientBalance()")` =
- * `0x01e1e567`) does NOT reproduce the listed selectors, so the deployed-
- * source mapping is still unverified. Names and hints are worded as
- * "likely cause" until the bytecode-source trace lands.
+ * The selector→name mappings below come from source-verified custom errors
+ * where available, with production/e2e observations kept as provenance.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ERROR_STRING_SELECTOR = exports.KNOWN_ERROR_SELECTORS = void 0;
@@ -36,10 +32,14 @@ exports.KNOWN_ERROR_SELECTORS = {
     },
     '0xf4d678b8': {
         name: 'InsufficientBalance',
-        hint: 'Likely cause: UEA does not hold enough of the burn token (PRC-20 mapped from the outbound `funds.token`). ' +
-            'For Solana SPL outbounds, ensure UEA holds the corresponding pUSDT.sol / pUSDC.sol mint before retrying. ' +
-            'Same selector may also surface from other balance-check reverters; verify burn-token balance first.',
-        provenance: 'Production e2e: e2e-2026-04-16T16-27-58-082Z.log:342 (R2 SPL fresh-UEA, no pUSDT.sol)',
+        hint: 'Likely cause: the executing account does not hold enough of the token being moved. ' +
+            'For Push outbounds, verify the UEA PRC-20 burn-token balance. For CEA→Push routes, verify the source-chain CEA balance.',
+        provenance: 'CommonErrors/CEAErrors.InsufficientBalance(); production e2e: e2e-2026-04-16T16-27-58-082Z.log:342',
+    },
+    '0xb4fa3fb3': {
+        name: 'InvalidInput',
+        hint: 'Likely cause: contract-level input validation failed. For CEA self-calls, the multicall entry must use value=0 and the encoded sendUniversalTxToUEA amount/revertRecipient must be valid.',
+        provenance: 'CommonErrors/CEAErrors.InvalidInput(); observed while replaying failed Route 3 CEA self-call tx 0x6fc0635d76edae0659ff131fd4bbf3349e01946708ce56dc2668d878f34a6077',
     },
     '0x66f9d09e': {
         name: 'GasLimitBelowBase',

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

@@ -52,7 +52,7 @@ export interface InsufficientUEABalanceErrorOpts {
     shortfall: bigint;
     ueaAddress: `0x${string}`;
     pathTag: PreflightPathTag;
-    /** 'NATIVE' = UPC shortfall; 'PRC20' = burn-token shortfall. */
+    /** 'NATIVE' = native PC shortfall; 'PRC20' = burn-token shortfall. */
     reason?: PreflightShortfallReason;
     /** Burn token address (only set when reason === 'PRC20'). */
     burnToken?: `0x${string}`;

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

@@ -11,6 +11,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InsufficientUEABalanceError = exports.PushChainExecutionError = void 0;
+const formatters_1 = require("../../formatters");
 /**
  * Typed error for Route 1 Push Chain tx failures. Thrown by
  * `extractPcTxAndTransform` when the final pcTx commits with `status === 'FAILED'`,
@@ -50,13 +51,15 @@ class InsufficientUEABalanceError extends PushChainExecutionError {
         const tokenSuffix = reason === 'PRC20' && opts.burnToken
             ? ` of token ${opts.burnToken}`
             : '';
-        const currencyLabel = reason === 'PRC20' ? 'units' : 'wei UPC';
+        const availableLabel = reason === 'PRC20' ? `${opts.available} units` : (0, formatters_1.formatPc)(opts.available);
+        const requiredLabel = reason === 'PRC20' ? `${opts.required} units` : (0, formatters_1.formatPc)(opts.required);
+        const shortfallLabel = reason === 'PRC20' ? `${opts.shortfall} units` : (0, formatters_1.formatPc)(opts.shortfall);
         const remediation = reason === 'PRC20'
             ? `Bridge the burn token to UEA on Push Chain before retrying.`
-            : `Bridge >=${opts.shortfall} wei UPC to the UEA on Push Chain before retrying.`;
+            : `Bridge >=${shortfallLabel} to the UEA on Push Chain before retrying.`;
         const message = `InsufficientUEABalance [${opts.pathTag}${segLabel}:${reason}]: ` +
-            `UEA ${opts.ueaAddress} has ${opts.available} ${currencyLabel}${tokenSuffix}; ` +
-            `outbound requires ${opts.required} ${currencyLabel}; shortfall ${opts.shortfall} ${currencyLabel}. ` +
+            `UEA ${opts.ueaAddress} has ${availableLabel}${tokenSuffix}; ` +
+            `outbound requires ${requiredLabel}; shortfall ${shortfallLabel}. ` +
             remediation;
         // Lift the structured info into the parent's decodedError so the
         // orchestrator's outer catch can pass it straight through to the

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

@@ -16,6 +16,7 @@ const chain_1 = require("../../constants/chain");
 const enums_1 = require("../../constants/enums");
 const tx_1 = require("../../generated/v1/tx");
 const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
+const formatters_1 = require("../../formatters");
 const utils_1 = require("../../utils");
 const evm_client_1 = require("../../vm-client/evm-client");
 const payload_builders_1 = require("../payload-builders");
@@ -352,15 +353,15 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
                                         const maxTransferable = funds + maxFromDeposit;
                                         maxTransferableNote =
                                             `Max transferable right now (at $1000 cap, pool-limited): ` +
-                                                `~${(Number(maxTransferable) / 1e18).toFixed(4)} $PC ` +
-                                                `(UEA balance ${(Number(funds) / 1e18).toFixed(4)} + ` +
-                                                `pool-safe deposit ${(Number(maxFromDeposit) / 1e18).toFixed(4)} − gas).`;
+                                                `~${(0, formatters_1.formatPc)(maxTransferable, 4)} ` +
+                                                `(UEA balance ${(0, formatters_1.formatPc)(funds, 4)} + ` +
+                                                `pool-safe deposit ${(0, formatters_1.formatPc)(maxFromDeposit, 4)} - gas).`;
                                         (0, context_1.printLog)(ctx, `Fee-lock capacity: ${maxTransferableNote}`);
                                     }
                                 }
-                                throw new Error(`Insufficient deposit: the fee-lock will deposit ~${(Number(safeUPC) / 1e18).toFixed(4)} $PC ` +
-                                    `but the transaction requires ~${(Number(requiredFunds) / 1e18).toFixed(4)} $PC ` +
-                                    `(shortfall: ~${(Number(shortfall) / 1e18).toFixed(4)} $PC). ` +
+                                throw new Error(`Insufficient deposit: the fee-lock will deposit ~${(0, formatters_1.formatPc)(safeUPC, 4)} ` +
+                                    `but the transaction requires ~${(0, formatters_1.formatPc)(requiredFunds, 4)} ` +
+                                    `(shortfall: ~${(0, formatters_1.formatPc)(shortfall, 4)}). ` +
                                     `The fee-lock deposit is capped at $1000 USD. ` +
                                     (maxTransferableNote ? maxTransferableNote + ' ' : '') +
                                     `Reduce the transfer value or pre-fund the UEA (${UEA}) on Push Chain.`);

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

@@ -64,6 +64,31 @@ const UNISWAP_V3_FACTORY_ABI = [
         stateMutability: 'view',
     },
 ];
+const UNISWAP_V3_QUOTER_EXACT_OUTPUT_ABI = [
+    {
+        type: 'function',
+        name: 'quoteExactOutputSingle',
+        inputs: [
+            {
+                type: 'tuple',
+                components: [
+                    { name: 'tokenIn', type: 'address' },
+                    { name: 'tokenOut', type: 'address' },
+                    { name: 'amount', type: 'uint256' },
+                    { name: 'fee', type: 'uint24' },
+                    { name: 'sqrtPriceLimitX96', type: 'uint160' },
+                ],
+            },
+        ],
+        outputs: [
+            { name: 'amountIn', type: 'uint256' },
+            { name: 'sqrtPriceX96After', type: 'uint160' },
+            { name: 'initializedTicksCrossed', type: 'uint32' },
+            { name: 'gasEstimate', type: 'uint256' },
+        ],
+        stateMutability: 'view',
+    },
+];
 const UNIVERSAL_CORE_SWAP_HELPERS_ABI = [
     { type: 'function', name: 'WPC', inputs: [], outputs: [{ name: '', type: 'address', internalType: 'address' }], stateMutability: 'view' },
     { type: 'function', name: 'uniswapV3Factory', inputs: [], outputs: [{ name: '', type: 'address', internalType: 'address' }], stateMutability: 'view' },
@@ -219,7 +244,19 @@ function queryOutboundGasFee(ctx, prc20Token, gasLimit, destinationChain) {
  */
 function estimateNativeValueForSwap(ctx, universalCoreAddress, gasToken, gasFee, accountBalance) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        const SWAP_BUFFER = BigInt(2); // 2x safety buffer; excess is refunded by swapAndBurnGas
+        var _a, _b;
+        // 2.2x safety buffer applied to the pool quote; excess is refunded by
+        // swapAndBurnGas. Composed of a 2x pool-slippage cushion plus 10%
+        // headroom that used to live in the R2 route-handler callers (×110/100
+        // after this function returned). Folded into one place here so the cap
+        // branch below correctly bounds the FINAL inflated value — the previous
+        // arrangement (outer ×1.10 on top of an inner cap that returned
+        // `balance - GAS_RESERVE`) caused a deterministic preflight failure
+        // whenever the cap fired: required = 1.10 × (balance − 3 PC) + 3 PC ≈
+        // balance × 1.10 − 0.3 PC > balance for any non-trivial balance. See
+        // preflight.ts:215.
+        const SWAP_BUFFER_NUM = BigInt(22);
+        const SWAP_BUFFER_DEN = BigInt(10);
         const BALANCE_FALLBACK_DIVISOR = BigInt(10); // 10% of balance as fallback
         const GAS_RESERVE = BigInt(3e18); // 3 UPC reserve for tx overhead
         try {
@@ -248,6 +285,34 @@ function estimateNativeValueForSwap(ctx, universalCoreAddress, gasToken, gasFee,
                 (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — no fee tier for gasToken, using balance fallback`);
                 return balanceFallback(accountBalance, BALANCE_FALLBACK_DIVISOR, GAS_RESERVE);
             }
+            const pushChain = (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork);
+            const quoterAddress = (_b = (_a = chain_1.CHAIN_INFO[pushChain]) === null || _a === void 0 ? void 0 : _a.dex) === null || _b === void 0 ? void 0 : _b.uniV3QuoterV2;
+            if (quoterAddress && !quoterAddress.startsWith('0xTBD')) {
+                try {
+                    const quote = yield ctx.pushClient.readContract({
+                        address: quoterAddress,
+                        abi: UNISWAP_V3_QUOTER_EXACT_OUTPUT_ABI,
+                        functionName: 'quoteExactOutputSingle',
+                        args: [
+                            {
+                                tokenIn: wpcAddress,
+                                tokenOut: gasToken,
+                                amount: gasFee,
+                                fee: feeTier,
+                                sqrtPriceLimitX96: BigInt(0),
+                            },
+                        ],
+                    });
+                    const exactWpcNeeded = quote[0];
+                    const result = (exactWpcNeeded * SWAP_BUFFER_NUM) / SWAP_BUFFER_DEN;
+                    (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — exactOutput quoter=${quoterAddress}, ` +
+                        `wpcNeeded=${exactWpcNeeded}, withBuffer(2.2x)=${result}`);
+                    return capSwapEstimate(result, accountBalance, GAS_RESERVE);
+                }
+                catch (quoteErr) {
+                    (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — exactOutput quote failed: ${quoteErr instanceof Error ? quoteErr.message : String(quoteErr)}, falling back to slot0 price`);
+                }
+            }
             // Get pool address from factory
             const poolAddress = yield ctx.pushClient.readContract({
                 address: factoryAddress,
@@ -285,17 +350,10 @@ function estimateNativeValueForSwap(ctx, universalCoreAddress, gasToken, gasFee,
                 // price = gasToken_per_WPC → wpcNeeded = gasFee / price
                 wpcNeeded = (gasFee * Q192) / priceNum;
             }
-            const result = wpcNeeded * SWAP_BUFFER;
+            const result = (wpcNeeded * SWAP_BUFFER_NUM) / SWAP_BUFFER_DEN;
             (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — pool=${poolAddress}, sqrtPriceX96=${sqrtPriceX96}, ` +
-                `wpcNeeded=${wpcNeeded}, withBuffer(2x)=${result}`);
-            // Cap at (balance - reserve)
-            if (accountBalance > result + GAS_RESERVE) {
-                return result;
-            }
-            else if (accountBalance > GAS_RESERVE) {
-                return accountBalance - GAS_RESERVE;
-            }
-            return result; // let caller decide if balance is too low
+                `wpcNeeded=${wpcNeeded}, withBuffer(2.2x)=${result}`);
+            return capSwapEstimate(result, accountBalance, GAS_RESERVE);
         }
         catch (err) {
             (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — failed: ${err instanceof Error ? err.message : String(err)}, using balance fallback`);
@@ -303,6 +361,15 @@ function estimateNativeValueForSwap(ctx, universalCoreAddress, gasToken, gasFee,
         }
     });
 }
+function capSwapEstimate(result, accountBalance, reserve) {
+    if (accountBalance > result + reserve) {
+        return result;
+    }
+    if (accountBalance > reserve) {
+        return accountBalance - reserve;
+    }
+    return result; // let caller decide if balance is too low
+}
 function balanceFallback(balance, divisor, reserve) {
     const fraction = balance / divisor;
     if (balance > fraction + reserve)

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

@@ -9,9 +9,10 @@ import type { OrchestratorContext } from './context';
 /** Chains that support gateway operations (multicall, funds bridging, etc.) */
 export declare const SUPPORTED_GATEWAY_CHAINS: CHAIN[];
 export declare function isPushChain(chain: CHAIN): boolean;
+export { toExternalTxHashDisplay } from '../../utils/external-tx-hash';
 export declare function getPushChainForNetwork(pushNetwork: PUSH_NETWORK): CHAIN;
 export declare function getChainNamespace(chain: CHAIN): string;
-export declare function chainFromNamespace(namespace: string): CHAIN | null;
+export { chainFromNamespace } from '../../utils/external-tx-hash';
 export declare function getNativePRC20ForChain(targetChain: CHAIN, pushNetwork: PUSH_NETWORK): `0x${string}`;
 export declare function getUniversalGatewayPCAddress(): `0x${string}`;
 /**

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

@@ -5,11 +5,10 @@
  * These have minimal dependencies and are used across multiple submodules.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_GATEWAY_CHAINS = void 0;
+exports.chainFromNamespace = exports.toExternalTxHashDisplay = exports.SUPPORTED_GATEWAY_CHAINS = void 0;
 exports.isPushChain = isPushChain;
 exports.getPushChainForNetwork = getPushChainForNetwork;
 exports.getChainNamespace = getChainNamespace;
-exports.chainFromNamespace = chainFromNamespace;
 exports.getNativePRC20ForChain = getNativePRC20ForChain;
 exports.getUniversalGatewayPCAddress = getUniversalGatewayPCAddress;
 exports.validateFeeLockTxHash = validateFeeLockTxHash;
@@ -38,6 +37,14 @@ function isPushChain(chain) {
         chain === enums_1.CHAIN.PUSH_TESTNET_DONUT ||
         chain === enums_1.CHAIN.PUSH_LOCALNET);
 }
+// `toExternalTxHashDisplay` moved to ../../utils/external-tx-hash so the
+// detector module can use it without back-importing from orchestrator/internals
+// (inbound-tracker.ts already imports universal-tx-detector — a back-import
+// from detector would create a cross-layer tangle). Re-exported here so
+// existing call sites (outbound-sync.ts / response-builder.ts / cascade.ts)
+// keep their current import path unchanged.
+var external_tx_hash_1 = require("../../utils/external-tx-hash");
+Object.defineProperty(exports, "toExternalTxHashDisplay", { enumerable: true, get: function () { return external_tx_hash_1.toExternalTxHashDisplay; } });
 function getPushChainForNetwork(pushNetwork) {
     if (pushNetwork === enums_1.PUSH_NETWORK.MAINNET) {
         return enums_1.CHAIN.PUSH_MAINNET;
@@ -55,15 +62,10 @@ function getChainNamespace(chain) {
     const namespace = chain_1.VM_NAMESPACE[vm];
     return `${namespace}:${chainId}`;
 }
-function chainFromNamespace(namespace) {
-    for (const [chainKey, info] of Object.entries(chain_1.CHAIN_INFO)) {
-        const expected = `${chain_1.VM_NAMESPACE[info.vm]}:${info.chainId}`;
-        if (expected === namespace) {
-            return chainKey;
-        }
-    }
-    return null;
-}
+// Moved to ../../utils/external-tx-hash alongside `toExternalTxHashDisplay`
+// so both the orchestrator and the detector module share one implementation.
+var external_tx_hash_2 = require("../../utils/external-tx-hash");
+Object.defineProperty(exports, "chainFromNamespace", { enumerable: true, get: function () { return external_tx_hash_2.chainFromNamespace; } });
 function getNativePRC20ForChain(targetChain, pushNetwork) {
     const synthetics = chain_1.SYNTHETIC_PUSH_ERC20[pushNetwork];
     switch (targetChain) {

package/src/lib/orchestrator/internals/outbound-sync.d.ts

@@ -67,6 +67,7 @@ export declare function waitForAllOutboundTxsV2(ctx: OrchestratorContext, pushCh
     initialWaitMs: number;
     pollingIntervalMs: number;
     timeout: number;
+    _resolvedSubTxId?: string;
     progressHook?: (event: {
         hopIndex: number;
         route: TransactionRouteType;

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

@@ -11,7 +11,6 @@ exports.waitForOutboundTx = waitForOutboundTx;
 exports.waitForAllOutboundTxsV2 = waitForAllOutboundTxsV2;
 const tslib_1 = require("tslib");
 const viem_1 = require("viem");
-const bs58_1 = require("../../internal/bs58");
 const chain_1 = require("../../constants/chain");
 const enums_1 = require("../../constants/enums");
 const types_1 = require("../../generated/uexecutor/v1/types");
@@ -142,7 +141,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;
+        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;
         // Terminal failure states — fail fast instead of polling until timeout
         const TERMINAL_FAILURE_STATES = new Set([
@@ -195,20 +194,37 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
                 const statusNum = (_b = utxResponse === null || utxResponse === void 0 ? void 0 : utxResponse.universalTx) === null || _b === void 0 ? void 0 : _b.universalStatus;
                 const statusName = (_c = types_1.UniversalTxStatus[statusNum]) !== null && _c !== void 0 ? _c : statusNum;
                 const outbounds = ((_d = utxResponse === null || utxResponse === void 0 ? void 0 : utxResponse.universalTx) === null || _d === void 0 ? void 0 : _d.outboundTx) || [];
-                (0, context_1.printLog)(ctx, `[waitForOutboundTx] Poll #${pollCount} | status: ${statusNum} (${statusName}) | outboundTx count: ${outbounds.length} | first txHash: '${((_f = (_e = outbounds[0]) === null || _e === void 0 ? void 0 : _e.observedTx) === null || _f === void 0 ? void 0 : _f.txHash) || ''}' | first dest: '${((_g = outbounds[0]) === null || _g === void 0 ? void 0 : _g.destinationChain) || ''}'`);
+                const firstOutbound = outbounds[0];
+                const firstOutboundChain = (firstOutbound === null || firstOutbound === void 0 ? void 0 : firstOutbound.destinationChain)
+                    ? (0, helpers_1.chainFromNamespace)(firstOutbound.destinationChain)
+                    : undefined;
+                const firstDisplayTxHash = (_h = (_f = (0, helpers_1.toExternalTxHashDisplay)(firstOutboundChain !== null && firstOutboundChain !== void 0 ? firstOutboundChain : undefined, (_e = firstOutbound === null || firstOutbound === void 0 ? void 0 : firstOutbound.observedTx) === null || _e === void 0 ? void 0 : _e.txHash)) !== null && _f !== void 0 ? _f : (_g = firstOutbound === null || firstOutbound === void 0 ? void 0 : firstOutbound.observedTx) === null || _g === void 0 ? void 0 : _g.txHash) !== null && _h !== void 0 ? _h : '';
+                (0, context_1.printLog)(ctx, `[waitForOutboundTx] Poll #${pollCount} | status: ${statusNum} (${statusName}) | outboundTx count: ${outbounds.length} | first txHash: '${firstDisplayTxHash}' | first dest: '${(firstOutbound === null || firstOutbound === void 0 ? void 0 : firstOutbound.destinationChain) || ''}'`);
                 // Check for terminal failure states — fail fast
                 if (TERMINAL_FAILURE_STATES.has(statusNum)) {
                     (0, context_1.printLog)(ctx, `[waitForOutboundTx] Terminal failure state: ${statusName}`);
                     progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'failed', elapsed: Date.now() - startTime });
                     throw new OutboundFailedError(`Outbound transaction failed with status ${statusName}. Push Chain TX: ${pushChainTxHash}.`, pushChainTxHash);
                 }
+                const pcTxs = ((_j = utxResponse === null || utxResponse === void 0 ? void 0 : utxResponse.universalTx) === null || _j === void 0 ? void 0 : _j.pcTx) || [];
+                const failedPcTx = pcTxs.find((pcTx) => {
+                    const status = String(pcTx.status || '').toUpperCase();
+                    return status === 'FAILED' || Boolean(pcTx.errorMsg);
+                });
+                if (failedPcTx) {
+                    const failedTxHash = failedPcTx.txHash || pushChainTxHash;
+                    const reason = 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
                 for (const ob of outbounds) {
                     // 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`);
                         progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'failed', elapsed: Date.now() - startTime });
-                        throw new OutboundFailedError(`Outbound to ${ob.destinationChain} reverted: ${((_h = ob.observedTx) === null || _h === void 0 ? void 0 : _h.errorMsg) || 'Unknown'}. Push Chain TX: ${pushChainTxHash}.`, pushChainTxHash, ob.destinationChain, (_j = ob.observedTx) === null || _j === void 0 ? void 0 : _j.txHash);
+                        throw new OutboundFailedError(`Outbound to ${ob.destinationChain} reverted: ${((_k = ob.observedTx) === null || _k === void 0 ? void 0 : _k.errorMsg) || 'Unknown'}. Push Chain TX: ${pushChainTxHash}.`, pushChainTxHash, ob.destinationChain, (_l = ob.observedTx) === null || _l === void 0 ? void 0 : _l.txHash);
                     }
                     // FOUND gating logic:
                     //   1. Primary path — cosmos has transitioned to OBSERVED (the
@@ -218,7 +234,7 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
                     //      destination chain's own RPC: if its receipt is success,
                     //      treat as FOUND; if reverted, throw OutboundFailedError.
                     //      Pending receipts keep polling.
-                    if ((_k = ob.observedTx) === null || _k === void 0 ? void 0 : _k.txHash) {
+                    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`);
@@ -232,7 +248,7 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
                             // Tiebreaker: ask the destination-chain RPC directly.
                             const verdict = yield verifyExternalEvmReceipt(ctx, chain, ob.observedTx.txHash);
                             if (verdict === 'reverted') {
-                                (0, context_1.printLog)(ctx, `[waitForOutboundTx] Source-chain RPC reports REVERTED for ${ob.destinationChain} tx ${ob.observedTx.txHash} (cosmos still ${(_l = types_1.UniversalTxStatus[statusNum]) !== null && _l !== void 0 ? _l : statusNum})`);
+                                (0, context_1.printLog)(ctx, `[waitForOutboundTx] Source-chain RPC reports REVERTED for ${ob.destinationChain} tx ${ob.observedTx.txHash} (cosmos still ${(_o = types_1.UniversalTxStatus[statusNum]) !== null && _o !== void 0 ? _o : statusNum})`);
                                 progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'failed', elapsed: Date.now() - startTime });
                                 throw new OutboundFailedError(`Outbound to ${ob.destinationChain} reverted on source-chain RPC (tx: ${ob.observedTx.txHash}). Push Chain TX: ${pushChainTxHash}.`, pushChainTxHash, ob.destinationChain, ob.observedTx.txHash);
                             }
@@ -240,24 +256,26 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
                                 // 'pending' or 'unsupported' — keep polling, cosmos will catch up.
                                 continue;
                             }
-                            (0, context_1.printLog)(ctx, `[waitForOutboundTx] Source-chain RPC tiebreaker: ${chain} tx ${ob.observedTx.txHash} succeeded; treating as FOUND despite cosmos status ${(_m = types_1.UniversalTxStatus[statusNum]) !== null && _m !== void 0 ? _m : statusNum}`);
+                            (0, context_1.printLog)(ctx, `[waitForOutboundTx] Source-chain RPC tiebreaker: ${chain} tx ${ob.observedTx.txHash} succeeded; treating as FOUND despite cosmos status ${(_p = types_1.UniversalTxStatus[statusNum]) !== null && _p !== void 0 ? _p : statusNum}`);
                         }
                         {
-                            const explorerBaseUrl = (_o = chain_1.CHAIN_INFO[chain]) === null || _o === void 0 ? void 0 : _o.explorerUrl;
-                            const isSvm = ((_p = chain_1.CHAIN_INFO[chain]) === null || _p === void 0 ? void 0 : _p.vm) === enums_1.VM.SVM;
-                            // For SVM chains, convert hex txHash to base58 and append cluster param
-                            let displayTxHash = ob.observedTx.txHash;
+                            const explorerBaseUrl = (_q = chain_1.CHAIN_INFO[chain]) === null || _q === void 0 ? void 0 : _q.explorerUrl;
+                            const isSvm = ((_r = chain_1.CHAIN_INFO[chain]) === null || _r === void 0 ? void 0 : _r.vm) === enums_1.VM.SVM;
+                            const displayTxHash = (_s = (0, helpers_1.toExternalTxHashDisplay)(chain, ob.observedTx.txHash)) !== null && _s !== void 0 ? _s : ob.observedTx.txHash;
                             let explorerUrl = '';
-                            if (isSvm && ob.observedTx.txHash.startsWith('0x')) {
-                                const bytes = new Uint8Array(Buffer.from(ob.observedTx.txHash.slice(2), 'hex'));
-                                displayTxHash = bs58_1.bs58.encode(Buffer.from(bytes));
+                            if (isSvm) {
                                 const cluster = chain === enums_1.CHAIN.SOLANA_DEVNET ? '?cluster=devnet'
                                     : chain === enums_1.CHAIN.SOLANA_TESTNET ? '?cluster=testnet' : '';
                                 explorerUrl = explorerBaseUrl ? `${explorerBaseUrl}/tx/${displayTxHash}${cluster}` : '';
                             }
                             else {
-                                explorerUrl = explorerBaseUrl ? `${explorerBaseUrl}/tx/${ob.observedTx.txHash}` : '';
+                                explorerUrl = explorerBaseUrl ? `${explorerBaseUrl}/tx/${displayTxHash}` : '';
                             }
+                            // OutboundTxDetails carries the raw `0x`-hex form so internal
+                            // consumers (R3 inbound tracker in response-builder.ts:786 →
+                            // findChildUtxIdFromExternalTx → Cosmos query) keep working.
+                            // The base58 display form is applied at every user-facing
+                            // boundary via `toExternalTxHashDisplay` (helpers.ts).
                             const details = {
                                 externalTxHash: ob.observedTx.txHash,
                                 destinationChain: chain,
@@ -266,7 +284,7 @@ function waitForOutboundTx(ctx_1, pushChainTxHash_1) {
                                 amount: ob.amount,
                                 assetAddr: ob.externalAssetAddr,
                             };
-                            (0, context_1.printLog)(ctx, `[waitForOutboundTx] FOUND on poll #${pollCount} | elapsed: ${Date.now() - startTime}ms | externalTxHash: ${details.externalTxHash}`);
+                            (0, context_1.printLog)(ctx, `[waitForOutboundTx] FOUND on poll #${pollCount} | elapsed: ${Date.now() - startTime}ms | externalTxHash: ${displayTxHash}`);
                             progressHook === null || progressHook === void 0 ? void 0 : progressHook({ status: 'found', elapsed: Date.now() - startTime });
                             return details;
                         }
@@ -302,8 +320,8 @@ 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;
-        const { initialWaitMs, pollingIntervalMs, timeout, progressHook } = options;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+        const { initialWaitMs, pollingIntervalMs, timeout, progressHook, _resolvedSubTxId, } = options;
         const startTime = Date.now();
         // Build a map: CAIP-2 namespace -> hop(s) for matching outbound entries
         const chainToHops = new Map();
@@ -341,7 +359,11 @@ function waitForAllOutboundTxsV2(ctx, pushChainTxHash, outboundHops, options) {
             });
         }
         // Extract sub-tx ID for V2 query
-        let cachedQueryId;
+        let cachedQueryId = _resolvedSubTxId
+            ? _resolvedSubTxId.startsWith('0x')
+                ? _resolvedSubTxId.slice(2)
+                : _resolvedSubTxId
+            : undefined;
         let pollCount = 0;
         let consecutiveErrors = 0;
         const MAX_CONSECUTIVE_ERRORS = 10;
@@ -372,11 +394,18 @@ function waitForAllOutboundTxsV2(ctx, pushChainTxHash, outboundHops, options) {
                         const unconfirmedForChain = hopsForChain.filter((h) => h.status !== 'confirmed' && h.status !== 'failed');
                         if (unconfirmedForChain.length === 0)
                             continue;
-                        // Fail fast on per-outbound REVERTED
-                        if (ob.outboundStatus === types_2.OutboundStatus.REVERTED) {
+                        const externalTxHash = (_e = ob.observedTx) === null || _e === void 0 ? void 0 : _e.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) ||
+                                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: ${((_e = ob.observedTx) === null || _e === void 0 ? void 0 : _e.errorMsg) || 'Unknown'}`);
+                                (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,
@@ -386,43 +415,70 @@ function waitForAllOutboundTxsV2(ctx, pushChainTxHash, outboundHops, options) {
                             }
                             return { success: false, failedAt: unconfirmedForChain[0].hopIndex };
                         }
-                        // Check for OBSERVED with txHash
-                        const externalTxHash = (_f = ob.observedTx) === null || _f === void 0 ? void 0 : _f.txHash;
-                        if (externalTxHash && (ob.outboundStatus === types_2.OutboundStatus.OBSERVED || ob.outboundStatus === 0)) {
+                        // Check for observed tx hash. Cosmos may lag the status transition,
+                        // so EVM destinations are verified against the destination receipt.
+                        if (hasObservedTxHash && externalTxHash) {
                             const chain = (0, helpers_1.chainFromNamespace)(destChain);
+                            if (!chain)
+                                continue;
+                            const isCosmosObserved = ob.outboundStatus === types_2.OutboundStatus.OBSERVED;
+                            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 };
+                                }
+                                if (verdict !== 'success') {
+                                    continue;
+                                }
+                            }
+                            // Build the display form for SVM (base58) used in `hop.txHash` /
+                            // `hop.outboundDetails.externalTxHash` / the progressHook event —
+                            // these are USER-FACING. The internal raw-hex form stays only
+                            // 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;
                             let explorerUrl = '';
                             if (chain && externalTxHash) {
-                                const explorerBaseUrl = (_g = chain_1.CHAIN_INFO[chain]) === null || _g === void 0 ? void 0 : _g.explorerUrl;
-                                const isSvm = ((_h = chain_1.CHAIN_INFO[chain]) === null || _h === void 0 ? void 0 : _h.vm) === enums_1.VM.SVM;
-                                if (isSvm && externalTxHash.startsWith('0x')) {
-                                    const bytes = new Uint8Array(Buffer.from(externalTxHash.slice(2), 'hex'));
-                                    const base58Hash = bs58_1.bs58.encode(Buffer.from(bytes));
+                                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;
+                                if (isSvm) {
                                     const cluster = chain === enums_1.CHAIN.SOLANA_DEVNET ? '?cluster=devnet'
                                         : chain === enums_1.CHAIN.SOLANA_TESTNET ? '?cluster=testnet' : '';
-                                    explorerUrl = explorerBaseUrl ? `${explorerBaseUrl}/tx/${base58Hash}${cluster}` : '';
+                                    explorerUrl = explorerBaseUrl ? `${explorerBaseUrl}/tx/${displayTxHash}${cluster}` : '';
                                 }
                                 else {
-                                    explorerUrl = explorerBaseUrl ? `${explorerBaseUrl}/tx/${externalTxHash}` : '';
+                                    explorerUrl = explorerBaseUrl ? `${explorerBaseUrl}/tx/${displayTxHash}` : '';
                                 }
                             }
                             for (const hop of unconfirmedForChain) {
                                 hop.status = 'confirmed';
-                                hop.txHash = externalTxHash;
+                                hop.txHash = displayTxHash;
                                 hop.outboundDetails = {
-                                    externalTxHash,
+                                    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: ${externalTxHash}`);
+                                (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: externalTxHash,
+                                    txHash: displayTxHash,
                                 });
                             }
                         }
@@ -439,7 +495,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 = (_j = utx === null || utx === void 0 ? void 0 : utx.outboundTx) === null || _j === void 0 ? void 0 : _j.some((ob) => {
+                        const hasPendingOutbound = (_m = utx === null || utx === void 0 ? void 0 : utx.outboundTx) === null || _m === void 0 ? void 0 : _m.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/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,30 +36,16 @@ 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;
 /**