@pushchain/core 5.1.17 → 6.0.0

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

@@ -50,6 +50,12 @@ export type ExecuteParams = {
      * @reason Prevents runaway gas consumption and lets users enforce limits.
      */
     gasLimit?: bigint;
+    /**
+     * Optional cap on native PC used for outbound gas swap.
+     * Applies only to Push -> external-chain outbound legs. Omit or set 0n for
+     * uncapped legacy behavior.
+     */
+    maxPCForGas?: bigint;
     /**
      * Optional override for the EIP-1559 max fee per gas (in wei).
      * @reason Gives callers direct control over total gas price to speed up or save cost.
@@ -397,20 +403,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).
@@ -440,25 +432,26 @@ export interface SvmExecutePayloadFields {
  * Request structure for sendUniversalTxOutbound on Push Chain
  * Used for Routes 2, 3, 4 (outbound from Push)
  *
- * NOTE: The `target` field is a LEGACY parameter for contract compatibility.
- * The deployed UniversalGatewayPC contract still expects this field, but it will
- * be removed in future contract upgrades. Pass any non-zero address (e.g., CEA address).
- * The actual destination is determined by the relay from the token's SOURCE_CHAIN_NAMESPACE.
+ * NOTE: The `target` field is raw recipient bytes for the destination chain.
+ * For EVM CEA funds-parking, use the zero recipient when `payload` is empty.
  */
 export interface UniversalOutboundTxRequest {
     /**
-     * LEGACY/DUMMY: Raw destination address bytes for contract compatibility.
-     * Pass any non-zero address - this value is NOT used by the relay to determine
-     * the actual transaction destination. Will be removed in future contract upgrades.
+     * Raw destination recipient bytes. EVM routes usually pass a 20-byte address;
+     * SVM routes pass a 32-byte program/account address.
      */
     target: `0x${string}`;
     /** PRC20 token address on Push Chain to burn */
     token: `0x${string}`;
     /** Amount to burn (0 for no-burn, use existing CEA balance) */
     amount: bigint;
-    /** Gas limit for fee quote (0 = default BASE_GAS_LIMIT) */
+    /** Gas limit for fee quote (0 = per-chain default resolved by UniversalCore) */
     gasLimit: bigint;
-    /** Raw ABI-encoded Multicall[] (no selector prefix) */
+    /** Gas price override for destination-chain gas (0 = UniversalCore default) */
+    gasPrice: bigint;
+    /** Max native PC that may be used for gas swap (0 = uncapped legacy behavior) */
+    maxPCForGas: bigint;
+    /** Destination execution payload; empty only for explicit funds parking */
     payload: `0x${string}`;
     /** Address to receive funds on revert */
     revertRecipient: `0x${string}`;
@@ -502,8 +495,12 @@ export interface HopDescriptor {
     gasToken?: `0x${string}`;
     /** Gas fee amount in gas token */
     gasFee?: bigint;
+    /** Destination-chain gas price quoted by UniversalCore */
+    gasPrice?: bigint;
     /** Gas limit for outbound relay */
     gasLimit: bigint;
+    /** Max native PC used for outbound gas swap (0 = uncapped) */
+    maxPCForGas: bigint;
     /** UEA address */
     ueaAddress: `0x${string}`;
     /** Address to receive funds on revert */
@@ -514,6 +511,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;
 }
@@ -548,8 +549,12 @@ export interface CascadeSegment {
     gasToken?: `0x${string}`;
     /** Total gas fee for this segment */
     gasFee?: bigint;
+    /** Destination-chain gas price quoted by UniversalCore */
+    gasPrice?: bigint;
     /** Gas limit for this segment */
     gasLimit?: bigint;
+    /** Max native PC used for outbound gas swap (0 = uncapped) */
+    maxPCForGas?: bigint;
     /**
      * SDK 5.2 gas-abstraction sizing decision for this segment. When the
      * segment merges multiple hops, the strictest (highest category) sizing
@@ -766,6 +771,13 @@ export interface WaitForOutboundOptions {
      * has multiple outbound operations to different chains.
      */
     _expectedDestinationChain?: string;
+    /**
+     * @internal Zero-based index among outbound entries that match
+     * `_expectedDestinationChain`. Used when a composed cascade emits multiple
+     * outbound operations to the same chain and a later hop must track the later
+     * observed tx rather than the first one.
+     */
+    _outboundIndex?: number;
 }
 /**
  * UEA deployment and version status.

package/src/lib/orchestrator/payload-builders.d.ts

@@ -70,18 +70,19 @@ export declare function buildSendUniversalTxToUEA(ceaAddress: `0x${string}`, tok
 /**
  * Build UniversalOutboundTxRequest for Push Chain outbound
  *
- * @param target - LEGACY/DUMMY: Any non-zero address for contract compatibility.
- *                 This value is NOT used by the relay to determine the actual destination.
- *                 The relay determines the destination from the PRC-20 token's SOURCE_CHAIN_NAMESPACE.
- *                 Will be removed in future contract upgrades.
+ * @param target - Raw recipient bytes for the destination chain. For EVM CEA
+ *                 funds-parking, use the zero recipient when payload is empty.
  * @param prc20Token - PRC20 token address to burn (or address(0) for native)
  * @param amount - Amount to burn
  * @param gasLimit - Gas limit for fee calculation
- * @param payload - CEA multicall payload
+ * @param payload - Destination execution payload
  * @param revertRecipient - Address to receive funds on revert
+ * @param maxPCForGas - Max native PC used for gas swap (0 = uncapped)
+ * @param gasPrice - Destination-chain gas price override (0 = UniversalCore default)
  * @returns UniversalOutboundTxRequest object
  */
-export declare function buildOutboundRequest(target: `0x${string}`, prc20Token: `0x${string}`, amount: bigint, gasLimit: bigint, payload: `0x${string}`, revertRecipient: `0x${string}`): UniversalOutboundTxRequest;
+export declare function buildOutboundRequest(target: `0x${string}`, prc20Token: `0x${string}`, amount: bigint, gasLimit: bigint, payload: `0x${string}`, revertRecipient: `0x${string}`, maxPCForGas?: bigint, gasPrice?: bigint): UniversalOutboundTxRequest;
+export declare function assertCeaFundsParkingInvariant(recipient: `0x${string}`, payload: `0x${string}`): void;
 /**
  * Build ERC20 transfer multicall
  *

package/src/lib/orchestrator/payload-builders.js

@@ -6,6 +6,7 @@ exports.buildCeaMulticallPayload = buildCeaMulticallPayload;
 exports.buildInboundUniversalPayload = buildInboundUniversalPayload;
 exports.buildSendUniversalTxToUEA = buildSendUniversalTxToUEA;
 exports.buildOutboundRequest = buildOutboundRequest;
+exports.assertCeaFundsParkingInvariant = assertCeaFundsParkingInvariant;
 exports.buildErc20Transfer = buildErc20Transfer;
 exports.buildErc20WithdrawalMulticall = buildErc20WithdrawalMulticall;
 exports.buildMigrationPayload = buildMigrationPayload;
@@ -225,27 +226,38 @@ function buildSendUniversalTxToUEA(ceaAddress, token, amount, payload, revertRec
 /**
  * Build UniversalOutboundTxRequest for Push Chain outbound
  *
- * @param target - LEGACY/DUMMY: Any non-zero address for contract compatibility.
- *                 This value is NOT used by the relay to determine the actual destination.
- *                 The relay determines the destination from the PRC-20 token's SOURCE_CHAIN_NAMESPACE.
- *                 Will be removed in future contract upgrades.
+ * @param target - Raw recipient bytes for the destination chain. For EVM CEA
+ *                 funds-parking, use the zero recipient when payload is empty.
  * @param prc20Token - PRC20 token address to burn (or address(0) for native)
  * @param amount - Amount to burn
  * @param gasLimit - Gas limit for fee calculation
- * @param payload - CEA multicall payload
+ * @param payload - Destination execution payload
  * @param revertRecipient - Address to receive funds on revert
+ * @param maxPCForGas - Max native PC used for gas swap (0 = uncapped)
+ * @param gasPrice - Destination-chain gas price override (0 = UniversalCore default)
  * @returns UniversalOutboundTxRequest object
  */
-function buildOutboundRequest(target, prc20Token, amount, gasLimit, payload, revertRecipient) {
+function buildOutboundRequest(target, prc20Token, amount, gasLimit, payload, revertRecipient, maxPCForGas = BigInt(0), gasPrice = BigInt(0)) {
     return {
         target,
         token: prc20Token,
         amount,
         gasLimit,
+        gasPrice,
+        maxPCForGas,
         payload,
         revertRecipient,
     };
 }
+function assertCeaFundsParkingInvariant(recipient, payload) {
+    if (payload !== '0x')
+        return;
+    if (recipient === '0x')
+        return;
+    if (recipient.toLowerCase() === selectors_1.ZERO_ADDRESS.toLowerCase())
+        return;
+    throw new Error('Empty CEA payloads must use the zero recipient to park funds');
+}
 /**
  * Build ERC20 transfer multicall
  *

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,
@@ -258,13 +251,16 @@ const RAW_HOOKS_R1 = {
             level: 'SUCCESS',
         };
     },
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02]: (errMessage, decodedError) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02,
-        title: 'Push Chain Tx Failed',
-        message: errMessage,
-        response: Object.assign({ error: errMessage }, (decodedError ? { decodedError } : {})),
-        level: 'ERROR',
-    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02]: (errMessage, decodedError) => {
+        const normalizedErrMessage = (0, formatters_1.normalizePcInsufficientFundsError)(errMessage);
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02,
+            title: 'Push Chain Tx Failed',
+            message: normalizedErrMessage,
+            response: Object.assign({ error: normalizedErrMessage }, (decodedError ? { decodedError } : {})),
+            level: 'ERROR',
+        };
+    },
 };
 // =============================================================================
 // Route 2 — UEA → UGPC → CEA on target chain (201–299, signature-only)
@@ -313,8 +309,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 +332,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 +356,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 +523,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 +546,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 +570,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 },
@@ -671,17 +667,22 @@ const RAW_HOOKS_R3 = {
     // Phase is passed by the emission site so the title matches the leg that
     // actually failed. Default stays 'inbound' for callers that don't specify
     // (backwards-compat with fixtures + response-builder's inbound block).
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02]: (errorMessage, phase = 'inbound', chain, decodedError) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02,
-        title: phase === 'outbound'
-            ? `${friendlyChain(chain)} Tx Failed`
-            : phase === 'push'
-                ? 'Push Chain Tx Failed'
-                : 'Push Chain Inbound Tx Failed',
-        message: errorMessage,
-        response: Object.assign({ error: errorMessage, phase, chain: chain !== null && chain !== void 0 ? chain : null }, (decodedError ? { decodedError } : {})),
-        level: 'ERROR',
-    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02]: (errorMessage, phase = 'inbound', chain, decodedError) => {
+        const normalizedErrorMessage = phase === 'push'
+            ? (0, formatters_1.normalizePcInsufficientFundsError)(errorMessage)
+            : errorMessage;
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02,
+            title: phase === 'outbound'
+                ? `${friendlyChain(chain)} Tx Failed`
+                : phase === 'push'
+                    ? 'Push Chain Tx Failed'
+                    : 'Push Chain Inbound Tx Failed',
+            message: normalizedErrorMessage,
+            response: Object.assign({ error: normalizedErrorMessage, phase, chain: chain !== null && chain !== void 0 ? chain : null }, (decodedError ? { decodedError } : {})),
+            level: 'ERROR',
+        };
+    },
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03]: (sourceChain, elapsedMs, phase = 'inbound') => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03,
         title: phase === 'outbound'
@@ -786,8 +787,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 +810,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 +834,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);

package/src/lib/universal-tx-detector/cascade.js

@@ -25,6 +25,7 @@ const enums_1 = require("../constants/enums");
 Object.defineProperty(exports, "PUSH_NETWORK", { enumerable: true, get: function () { return enums_1.PUSH_NETWORK; } });
 const child_inbounds_1 = require("./child-inbounds");
 const detector_1 = require("./detector");
+const normalize_1 = require("./normalize");
 const PUSH_CHAIN_CAIPS = new Set([
     enums_1.CHAIN.PUSH_MAINNET,
     enums_1.CHAIN.PUSH_TESTNET_DONUT,
@@ -46,8 +47,10 @@ function traceUniversalTxCascade(startHash, startChain, opts) {
         const root = yield walk(startHash, startChain, 0, state, opts);
         if (!root) {
             // Should never happen for depth=0; return an empty detection node so the
-            // caller has something to render.
-            return {
+            // caller has something to render. No outbound summaries → nothing to
+            // normalize, but we still pass through `normalizeCascadeNodeForUser`
+            // for symmetry with the happy path below.
+            return (0, normalize_1.normalizeCascadeNodeForUser)({
                 detection: {
                     txHash: startHash,
                     chain: startChain,
@@ -60,9 +63,16 @@ function traceUniversalTxCascade(startHash, startChain, opts) {
                 },
                 children: [],
                 depth: 0,
-            };
+            });
         }
-        return root;
+        // User-facing normalization pass — recursively rewrites every
+        // `PushChainOutboundSummary.externalTxHash` in the tree to base58 for SVM
+        // destinations. Each internal `detectUniversalTx` call (in `walk`) already
+        // produced a normalized detection; this final pass also normalizes the
+        // edge-level `relation` summaries inside `expandPushOutbounds` /
+        // `expandExternalChildInbounds` which build summaries DIRECTLY (without
+        // going through `detectUniversalTx`).
+        return (0, normalize_1.normalizeCascadeNodeForUser)(root);
     });
 }
 // ── Core recursion ────────────────────────────────────────────────────

package/src/lib/universal-tx-detector/child-inbounds.js

@@ -22,6 +22,7 @@ const tslib_1 = require("tslib");
  * `pushClient.getUniversalTxByIdV2`, no event-attribute predicate needed.
  */
 const viem_1 = require("viem");
+const normalize_1 = require("./normalize");
 const STATUS_NAMES = {
     0: 'UNIVERSAL_TX_STATUS_UNSPECIFIED',
     1: 'INBOUND_SUCCESS',
@@ -75,7 +76,14 @@ function resolveChildInboundsFromDetection(pushClient, detection, diagnostics) {
         const inboundLogs = detection.detections
             .filter((d) => INBOUND_EVENT_NAMES.has(d.log.eventName))
             .map((d) => d.log);
-        return resolveChildInboundsFromLogs(pushClient, detection.chain, detection.txHash, inboundLogs, diagnostics);
+        const resolutions = yield resolveChildInboundsFromLogs(pushClient, detection.chain, detection.txHash, inboundLogs, diagnostics);
+        // User-facing normalization pass: rewrites nested
+        // `outboundHashes[n].externalTxHash` to base58 for SVM destinations.
+        // `pcTxHashes` is Push Chain (EVM) and stays hex by chain type. The lower-
+        // level `resolveChildInboundsFromLogs` is left producing raw hex so
+        // internal callers (`findChildUtxIdFromExternalTx` via the detector path)
+        // that go through it directly still see the canonical form.
+        return resolutions.map(normalize_1.normalizeChildInboundResolutionForUser);
     });
 }
 /**

package/src/lib/universal-tx-detector/detector.js

@@ -25,6 +25,7 @@ const events_1 = require("./events");
 const classify_1 = require("./classify");
 const child_inbounds_1 = require("./child-inbounds");
 const detector_svm_1 = require("./detector-svm");
+const normalize_1 = require("./normalize");
 // ── Status name table (copied from scripts/poll-outbound.ts:33-44) ────
 const UNIVERSAL_TX_STATUS_NAMES = {
     0: 'UNIVERSAL_TX_STATUS_UNSPECIFIED',
@@ -51,7 +52,7 @@ function detectUniversalTx(txHash_1, chain_2) {
             throw new Error(`detectUniversalTx: unknown chain ${chain}`);
         }
         if (chainInfo.vm === enums_1.VM.SVM) {
-            return (0, detector_svm_1.detectUniversalTxSvm)(txHash, chain, opts);
+            return (0, normalize_1.normalizeDetectionForUser)(yield (0, detector_svm_1.detectUniversalTxSvm)(txHash, chain, opts));
         }
         if (chainInfo.vm !== enums_1.VM.EVM) {
             throw new Error(`detectUniversalTx: unsupported vm=${chainInfo.vm} for ${chain}`);
@@ -132,7 +133,12 @@ function detectUniversalTx(txHash_1, chain_2) {
             notes.push('push cross-reference skipped (no pushClient provided)');
         }
         const detections = (0, classify_1.classifyAll)(classified.matchingLogs);
-        return {
+        // User-facing normalization pass: rewrites `pushChainTx.outboundHashes[n]
+        // .externalTxHash` to base58 for SVM destinations. The raw `0x`-hex form
+        // never leaves this function — internal consumers (findChildUtxIdFromExternalTx,
+        // Cosmos `inbound_tx_hash=` queries) work off their own input parameters,
+        // not the detection result's outbound summaries.
+        return (0, normalize_1.normalizeDetectionForUser)({
             txHash,
             chain,
             kind: classified.kind,
@@ -142,7 +148,7 @@ function detectUniversalTx(txHash_1, chain_2) {
             detections,
             pushChainTx,
             notes,
-        };
+        });
     });
 }
 // ── Helpers ───────────────────────────────────────────────────────────

package/src/lib/universal-tx-detector/events.d.ts

@@ -2,8 +2,10 @@
  * Event ABI fragments used by the universal-tx detector.
  *
  * Sourced from push-chain-gateway-contracts and push-chain-core-contracts:
- *   - UniversalTx, UniversalTxExecuted, RevertUniversalTx, FundsRescued
+ *   - UniversalTx, RevertUniversalTx, FundsRescued
  *       → contracts/evm-gateway/src/interfaces/IUniversalGateway.sol
+ *   - UniversalTxExecuted
+ *       → push-chain-core-contracts/src/Interfaces/ICEA.sol
  *   - UniversalTxFinalized, UniversalTxReverted, FundsRescued (vault)
  *       → contracts/evm-gateway/src/interfaces/IVault.sol
  *   - UniversalTxOutbound

package/src/lib/universal-tx-detector/events.js

@@ -3,8 +3,10 @@
  * Event ABI fragments used by the universal-tx detector.
  *
  * Sourced from push-chain-gateway-contracts and push-chain-core-contracts:
- *   - UniversalTx, UniversalTxExecuted, RevertUniversalTx, FundsRescued
+ *   - UniversalTx, RevertUniversalTx, FundsRescued
  *       → contracts/evm-gateway/src/interfaces/IUniversalGateway.sol
+ *   - UniversalTxExecuted
+ *       → push-chain-core-contracts/src/Interfaces/ICEA.sol
  *   - UniversalTxFinalized, UniversalTxReverted, FundsRescued (vault)
  *       → contracts/evm-gateway/src/interfaces/IVault.sol
  *   - UniversalTxOutbound

package/src/lib/universal-tx-detector/normalize.d.ts

@@ -0,0 +1,42 @@
+/**
+ * User-facing normalization pass for detector outputs.
+ *
+ * The detector module's internal pipeline produces `PushChainOutboundSummary`
+ * objects with raw `0x`-hex `externalTxHash` for SVM destinations — that's
+ * the form Cosmos delivers and the form `findChildUtxIdFromExternalTx` /
+ * `inbound_tx_hash='…'` queries require. For USER-facing entry points
+ * (`detectUniversalTx`, `traceUniversalTxCascade`,
+ * `resolveChildInboundsFromDetection`), the SVM hash should be base58 so
+ * consumers can paste it straight into a Solana explorer or
+ * `connection.getTransaction(sig)`.
+ *
+ * These helpers are applied at the three public-API return points (and
+ * NOWHERE else) — they walk the result tree and rewrite
+ * `PushChainOutboundSummary.externalTxHash` for SVM destinations. The
+ * internal pipeline never sees the normalized form.
+ *
+ * Helpers are idempotent: a value not starting with `0x` or whose
+ * `destinationChain` isn't SVM passes through unchanged. New objects are
+ * returned only when a field actually changed; otherwise the same reference
+ * is reused so EVM-only graphs incur near-zero allocation.
+ */
+import type { PushChainOutboundSummary, UniversalTxDetection } from './types';
+import type { CascadeNode } from './cascade';
+import type { ChildInboundResolution } from './child-inbounds';
+/**
+ * Normalize a single outbound summary's `externalTxHash` for user display.
+ * Returns the same reference when no change is needed.
+ */
+export declare function normalizeOutboundSummaryForUser(s: PushChainOutboundSummary): PushChainOutboundSummary;
+/**
+ * Normalize the outbound summaries embedded in `detection.pushChainTx`.
+ * The root `detection.txHash` is left untouched — per agreed scope.
+ */
+export declare function normalizeDetectionForUser(d: UniversalTxDetection): UniversalTxDetection;
+/**
+ * Normalize the outbound summaries inside a `ChildInboundResolution`.
+ * `pcTxHashes` (Push Chain — always EVM) is left untouched.
+ */
+export declare function normalizeChildInboundResolutionForUser(r: ChildInboundResolution): ChildInboundResolution;
+/** Recursively normalize a cascade tree. */
+export declare function normalizeCascadeNodeForUser(n: CascadeNode): CascadeNode;