@pushchain/core 5.1.17 → 6.0.0

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'`,
@@ -28,7 +29,7 @@ exports.InsufficientUEABalanceError = exports.PushChainExecutionError = void 0;
  */
 class PushChainExecutionError extends Error {
     constructor(message, opts = {}) {
-        super(message);
+        super((0, formatters_1.normalizePcInsufficientFundsError)(message));
         this.code = 'PUSH_CHAIN_EXECUTION_FAILED';
         this.name = 'PushChainExecutionError';
         this.gatewayTxHash = opts.gatewayTxHash;
@@ -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-funds-only.js

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

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

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

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

@@ -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");
@@ -103,7 +104,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             catch (err) {
                 // Push Chain broadcast failed. Wallet rejection surfaces as 104-04;
                 // everything else (RPC fail, on-chain revert) as 199-02.
-                const errMsg = err instanceof Error ? err.message : String(err);
+                const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
                 const { isUserDecline } = (0, progress_hook_1.classifyDeclineError)(errMsg);
                 (0, context_1.fireProgressHook)(ctx, isUserDecline ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04 : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
                 // Mark that a terminal-ish error hook has already fired so the
@@ -266,7 +267,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
                 // Wallet decline, contract revert during sign, or RPC failure — the
                 // 104-04 builder's classifyDeclineError heuristic picks the right
                 // copy (real decline → "Verification Declined"; else "Signature Failed").
-                const errMsg = err instanceof Error ? err.message : String(err);
+                const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
                 (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04, errMsg);
                 throw err;
             }
@@ -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.`);
@@ -412,7 +413,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             }
             catch (err) {
                 if (!(err instanceof push_chain_tx_1.PushChainExecutionError)) {
-                    const errMsg = err instanceof Error ? err.message : String(err);
+                    const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
                     (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
                     throw new push_chain_tx_1.PushChainExecutionError(errMsg, { gatewayTxHash: feeLockTxHash });
                 }
@@ -446,7 +447,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             // exhaustion). Surface terminal 199-02 before re-throwing so the stream
             // ends with the spec'd error hook. Typed PushChainExecutionError lets
             // callers classify via instanceof without message sniffing.
-            const errMsg = err instanceof Error ? err.message : String(err);
+            const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
             (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
             if (err instanceof push_chain_tx_1.PushChainExecutionError)
                 throw err;

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

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

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

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

package/src/lib/orchestrator/internals/helpers.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) {
@@ -140,6 +142,7 @@ function toExecuteParams(params) {
         data: params.data,
         funds: params.funds,
         gasLimit: params.gasLimit,
+        maxPCForGas: params.maxPCForGas,
         maxFeePerGas: params.maxFeePerGas,
         maxPriorityFeePerGas: params.maxPriorityFeePerGas,
         deadline: params.deadline,

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

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

package/src/lib/orchestrator/internals/outbound-sync.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;