@pushchain/core 5.1.16 → 5.1.18

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

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

package/src/lib/progress-hook/progress-hook.types.d.ts

@@ -68,6 +68,9 @@ export declare enum PROGRESS_HOOK {
     SEND_TX_303_03_01 = "SEND-TX-303-03-01",// Sizer: Case A (< $1, padded)
     SEND_TX_303_03_02 = "SEND-TX-303-03-02",// Sizer: Case B ($1–$10, happy path)
     SEND_TX_303_03_03 = "SEND-TX-303-03-03",// Sizer: Case C (> $10, split + overflow bridge)
+    SEND_TX_303_04 = "SEND-TX-303-04",// R3 pre-flight balance check (INFO when sufficient, ERROR when insufficient)
+    SEND_TX_303_05 = "SEND-TX-303-05",// R3 pre-flight FAILED (ERROR, terminal precursor before 399-02)
+    SEND_TX_303_06 = "SEND-TX-303-06",// R3 SVM warn-threshold tripped (INFO, no action)
     SEND_TX_304_01 = "SEND-TX-304-01",
     SEND_TX_304_02 = "SEND-TX-304-02",
     SEND_TX_304_03 = "SEND-TX-304-03",
@@ -99,7 +102,7 @@ export declare enum PROGRESS_HOOK {
 }
 export type PROGRESS_HOOK_R1 = PROGRESS_HOOK.SEND_TX_101 | PROGRESS_HOOK.SEND_TX_102_01 | PROGRESS_HOOK.SEND_TX_103_01 | PROGRESS_HOOK.SEND_TX_103_02 | PROGRESS_HOOK.SEND_TX_103_03 | PROGRESS_HOOK.SEND_TX_103_03_01 | PROGRESS_HOOK.SEND_TX_103_03_02 | PROGRESS_HOOK.SEND_TX_103_03_03 | PROGRESS_HOOK.SEND_TX_103_03_04 | PROGRESS_HOOK.SEND_TX_104_01 | PROGRESS_HOOK.SEND_TX_104_02 | PROGRESS_HOOK.SEND_TX_104_03 | PROGRESS_HOOK.SEND_TX_104_04 | PROGRESS_HOOK.SEND_TX_105_01 | PROGRESS_HOOK.SEND_TX_105_02 | PROGRESS_HOOK.SEND_TX_106_01 | PROGRESS_HOOK.SEND_TX_106_02 | PROGRESS_HOOK.SEND_TX_106_03 | PROGRESS_HOOK.SEND_TX_106_03_01 | PROGRESS_HOOK.SEND_TX_106_03_02 | PROGRESS_HOOK.SEND_TX_106_04 | PROGRESS_HOOK.SEND_TX_106_05 | PROGRESS_HOOK.SEND_TX_106_06 | PROGRESS_HOOK.SEND_TX_107 | PROGRESS_HOOK.SEND_TX_199_01 | PROGRESS_HOOK.SEND_TX_199_02;
 export type PROGRESS_HOOK_R2 = PROGRESS_HOOK.SEND_TX_201 | PROGRESS_HOOK.SEND_TX_202_01 | PROGRESS_HOOK.SEND_TX_202_02 | PROGRESS_HOOK.SEND_TX_203_01 | PROGRESS_HOOK.SEND_TX_203_02 | PROGRESS_HOOK.SEND_TX_203_03 | PROGRESS_HOOK.SEND_TX_203_04 | PROGRESS_HOOK.SEND_TX_203_05 | PROGRESS_HOOK.SEND_TX_204_01 | PROGRESS_HOOK.SEND_TX_204_02 | PROGRESS_HOOK.SEND_TX_204_03 | PROGRESS_HOOK.SEND_TX_204_04 | PROGRESS_HOOK.SEND_TX_207 | PROGRESS_HOOK.SEND_TX_209_01 | PROGRESS_HOOK.SEND_TX_209_02 | PROGRESS_HOOK.SEND_TX_299_01 | PROGRESS_HOOK.SEND_TX_299_02 | PROGRESS_HOOK.SEND_TX_299_03 | PROGRESS_HOOK.SEND_TX_299_99;
-export type PROGRESS_HOOK_R3 = PROGRESS_HOOK.SEND_TX_199_99_99 | PROGRESS_HOOK.SEND_TX_301 | PROGRESS_HOOK.SEND_TX_302_01 | PROGRESS_HOOK.SEND_TX_302_02 | PROGRESS_HOOK.SEND_TX_303_01 | PROGRESS_HOOK.SEND_TX_303_02 | PROGRESS_HOOK.SEND_TX_303_03_01 | PROGRESS_HOOK.SEND_TX_303_03_02 | PROGRESS_HOOK.SEND_TX_303_03_03 | PROGRESS_HOOK.SEND_TX_304_01 | PROGRESS_HOOK.SEND_TX_304_02 | PROGRESS_HOOK.SEND_TX_304_03 | PROGRESS_HOOK.SEND_TX_304_04 | PROGRESS_HOOK.SEND_TX_307 | PROGRESS_HOOK.SEND_TX_309_01 | PROGRESS_HOOK.SEND_TX_309_02 | PROGRESS_HOOK.SEND_TX_309_03 | PROGRESS_HOOK.SEND_TX_310_01 | PROGRESS_HOOK.SEND_TX_310_02 | PROGRESS_HOOK.SEND_TX_399_01 | PROGRESS_HOOK.SEND_TX_399_02 | PROGRESS_HOOK.SEND_TX_399_03;
+export type PROGRESS_HOOK_R3 = PROGRESS_HOOK.SEND_TX_199_99_99 | PROGRESS_HOOK.SEND_TX_301 | PROGRESS_HOOK.SEND_TX_302_01 | PROGRESS_HOOK.SEND_TX_302_02 | PROGRESS_HOOK.SEND_TX_303_01 | PROGRESS_HOOK.SEND_TX_303_02 | PROGRESS_HOOK.SEND_TX_303_03_01 | PROGRESS_HOOK.SEND_TX_303_03_02 | PROGRESS_HOOK.SEND_TX_303_03_03 | PROGRESS_HOOK.SEND_TX_303_04 | PROGRESS_HOOK.SEND_TX_303_05 | PROGRESS_HOOK.SEND_TX_303_06 | PROGRESS_HOOK.SEND_TX_304_01 | PROGRESS_HOOK.SEND_TX_304_02 | PROGRESS_HOOK.SEND_TX_304_03 | PROGRESS_HOOK.SEND_TX_304_04 | PROGRESS_HOOK.SEND_TX_307 | PROGRESS_HOOK.SEND_TX_309_01 | PROGRESS_HOOK.SEND_TX_309_02 | PROGRESS_HOOK.SEND_TX_309_03 | PROGRESS_HOOK.SEND_TX_310_01 | PROGRESS_HOOK.SEND_TX_310_02 | PROGRESS_HOOK.SEND_TX_399_01 | PROGRESS_HOOK.SEND_TX_399_02 | PROGRESS_HOOK.SEND_TX_399_03;
 export type PROGRESS_HOOK_MULTICHAIN = PROGRESS_HOOK.SEND_TX_001 | PROGRESS_HOOK.SEND_TX_002_01 | PROGRESS_HOOK.SEND_TX_002_99_99 | PROGRESS_HOOK.SEND_TX_003_03 | PROGRESS_HOOK.SEND_TX_003_04 | PROGRESS_HOOK.SEND_TX_003_05 | PROGRESS_HOOK.SEND_TX_999_01 | PROGRESS_HOOK.SEND_TX_999_02 | PROGRESS_HOOK.SEND_TX_999_03;
 export type PROGRESS_HOOK_MIG = PROGRESS_HOOK.UEA_MIG_01 | PROGRESS_HOOK.UEA_MIG_02 | PROGRESS_HOOK.UEA_MIG_03 | PROGRESS_HOOK.UEA_MIG_9901 | PROGRESS_HOOK.UEA_MIG_9902 | PROGRESS_HOOK.UEA_MIG_9903;
 export {};

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

@@ -64,6 +64,14 @@ var PROGRESS_HOOK;
     PROGRESS_HOOK["SEND_TX_303_03_01"] = "SEND-TX-303-03-01";
     PROGRESS_HOOK["SEND_TX_303_03_02"] = "SEND-TX-303-03-02";
     PROGRESS_HOOK["SEND_TX_303_03_03"] = "SEND-TX-303-03-03";
+    // R3 single-route pre-flight balance check. Mirror of R2's 203-03/04/05
+    // semantics scoped to the R3 (3xx) bucket. Slots 303-03/-03-* are already
+    // owned by the sizer cluster so preflight uses the next free slots
+    // (304-01..04 are sign/verify), inserted between sizer and signature
+    // burst because that is the temporal point where UEA balance is checked.
+    PROGRESS_HOOK["SEND_TX_303_04"] = "SEND-TX-303-04";
+    PROGRESS_HOOK["SEND_TX_303_05"] = "SEND-TX-303-05";
+    PROGRESS_HOOK["SEND_TX_303_06"] = "SEND-TX-303-06";
     PROGRESS_HOOK["SEND_TX_304_01"] = "SEND-TX-304-01";
     PROGRESS_HOOK["SEND_TX_304_02"] = "SEND-TX-304-02";
     PROGRESS_HOOK["SEND_TX_304_03"] = "SEND-TX-304-03";

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

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

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOutboundSummaryForUser = normalizeOutboundSummaryForUser;
+exports.normalizeDetectionForUser = normalizeDetectionForUser;
+exports.normalizeChildInboundResolutionForUser = normalizeChildInboundResolutionForUser;
+exports.normalizeCascadeNodeForUser = normalizeCascadeNodeForUser;
+const external_tx_hash_1 = require("../utils/external-tx-hash");
+/**
+ * Normalize a single outbound summary's `externalTxHash` for user display.
+ * Returns the same reference when no change is needed.
+ */
+function normalizeOutboundSummaryForUser(s) {
+    if (!s.externalTxHash)
+        return s;
+    const chain = (0, external_tx_hash_1.chainFromNamespace)(s.destinationChain);
+    const next = (0, external_tx_hash_1.toExternalTxHashDisplay)(chain !== null && chain !== void 0 ? chain : undefined, s.externalTxHash);
+    if (next === s.externalTxHash)
+        return s;
+    return Object.assign(Object.assign({}, s), { externalTxHash: next });
+}
+/**
+ * Normalize the outbound summaries inside `PushChainCrossRef.outboundHashes`.
+ * Reuses the input when no nested summary changed.
+ */
+function normalizeCrossRefForUser(x) {
+    if (!x.outboundHashes || x.outboundHashes.length === 0)
+        return x;
+    let changed = false;
+    const next = x.outboundHashes.map((s) => {
+        const n = normalizeOutboundSummaryForUser(s);
+        if (n !== s)
+            changed = true;
+        return n;
+    });
+    if (!changed)
+        return x;
+    return Object.assign(Object.assign({}, x), { outboundHashes: next });
+}
+/**
+ * Normalize the outbound summaries embedded in `detection.pushChainTx`.
+ * The root `detection.txHash` is left untouched — per agreed scope.
+ */
+function normalizeDetectionForUser(d) {
+    if (!d.pushChainTx)
+        return d;
+    const nextPushChainTx = normalizeCrossRefForUser(d.pushChainTx);
+    if (nextPushChainTx === d.pushChainTx)
+        return d;
+    return Object.assign(Object.assign({}, d), { pushChainTx: nextPushChainTx });
+}
+/**
+ * Normalize the outbound summaries inside a `ChildInboundResolution`.
+ * `pcTxHashes` (Push Chain — always EVM) is left untouched.
+ */
+function normalizeChildInboundResolutionForUser(r) {
+    if (!r.outboundHashes || r.outboundHashes.length === 0)
+        return r;
+    let changed = false;
+    const next = r.outboundHashes.map((s) => {
+        const n = normalizeOutboundSummaryForUser(s);
+        if (n !== s)
+            changed = true;
+        return n;
+    });
+    if (!changed)
+        return r;
+    return Object.assign(Object.assign({}, r), { outboundHashes: next });
+}
+/**
+ * Type guard: identifies a `CascadeEdge.relation` as a
+ * `PushChainOutboundSummary`. Outbound summaries carry `destinationChain` and
+ * (optionally) `externalTxHash`; refund summaries and child-inbound
+ * resolutions don't.
+ */
+function isOutboundRelation(r) {
+    return (typeof r.destinationChain === 'string' &&
+        !('universalTxId' in r) &&
+        !('parentOutboundId' in r));
+}
+function isChildInboundRelation(r) {
+    return 'universalTxId' in r;
+}
+/** Recursively normalize a cascade tree. */
+function normalizeCascadeNodeForUser(n) {
+    const nextDetection = normalizeDetectionForUser(n.detection);
+    let childrenChanged = nextDetection !== n.detection;
+    const nextChildren = n.children.map((edge) => {
+        let nextRelation = edge.relation;
+        if (isOutboundRelation(edge.relation)) {
+            nextRelation = normalizeOutboundSummaryForUser(edge.relation);
+        }
+        else if (isChildInboundRelation(edge.relation)) {
+            nextRelation = normalizeChildInboundResolutionForUser(edge.relation);
+        }
+        const nextNode = edge.node ? normalizeCascadeNodeForUser(edge.node) : edge.node;
+        if (nextRelation === edge.relation && nextNode === edge.node)
+            return edge;
+        childrenChanged = true;
+        return Object.assign(Object.assign({}, edge), { relation: nextRelation, node: nextNode });
+    });
+    if (!childrenChanged)
+        return n;
+    return Object.assign(Object.assign({}, n), { detection: nextDetection, children: nextChildren });
+}
+//# sourceMappingURL=normalize.js.map

package/src/lib/utils/external-tx-hash.d.ts

@@ -0,0 +1,37 @@
+/**
+ * External-tx-hash display helpers.
+ *
+ * Lives at a neutral cross-module location so both the orchestrator and the
+ * universal-tx-detector module can import without creating a circular /
+ * back-layered dependency (orchestrator/internals imports detector via
+ * inbound-tracker.ts; detector must not import back into orchestrator).
+ *
+ * The SDK stores SVM (Solana) outbound tx signatures as `0x`-prefixed hex
+ * internally — that's how the Cosmos keeper indexes them. Users, however,
+ * expect Solana explorers / RPCs to see base58 signatures. `toExternalTxHashDisplay`
+ * is the one-way conversion applied at every user-facing boundary; the
+ * internal canonical form stays hex.
+ */
+import { CHAIN } from '../constants/enums';
+/**
+ * Convert an outbound tx hash from the internal canonical form (`0x`-prefixed
+ * hex, as Cosmos delivers it) to the form users expect on the destination
+ * chain. SVM signatures (64 bytes) become base58; EVM hashes pass through
+ * unchanged. Idempotent: a value that already lacks `0x` or whose chain isn't
+ * SVM is returned as-is.
+ *
+ * Used at user-facing boundaries that surface `externalTxHash` (receipt
+ * construction in response-builder, cascade hop info in cascade.ts, detector
+ * public-API output normalization). Do NOT apply at internal boundaries —
+ * `findChildUtxIdFromExternalTx` and the Cosmos tx-search query in
+ * inbound-tracker.ts expect the raw hex form.
+ */
+export declare function toExternalTxHashDisplay(chain: CHAIN | undefined, rawTxHash: string | undefined): string | undefined;
+/**
+ * Map a CAIP namespace string (e.g. `'solana:devnet'`, `'eip155:11155111'`)
+ * to the corresponding `CHAIN` enum value, or `null` if no matching chain is
+ * registered. Used to resolve `PushChainOutboundSummary.destinationChain`
+ * (string) to a CHAIN enum so `toExternalTxHashDisplay` can decide whether
+ * to convert.
+ */
+export declare function chainFromNamespace(namespace: string): CHAIN | null;

package/src/lib/utils/external-tx-hash.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * External-tx-hash display helpers.
+ *
+ * Lives at a neutral cross-module location so both the orchestrator and the
+ * universal-tx-detector module can import without creating a circular /
+ * back-layered dependency (orchestrator/internals imports detector via
+ * inbound-tracker.ts; detector must not import back into orchestrator).
+ *
+ * The SDK stores SVM (Solana) outbound tx signatures as `0x`-prefixed hex
+ * internally — that's how the Cosmos keeper indexes them. Users, however,
+ * expect Solana explorers / RPCs to see base58 signatures. `toExternalTxHashDisplay`
+ * is the one-way conversion applied at every user-facing boundary; the
+ * internal canonical form stays hex.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toExternalTxHashDisplay = toExternalTxHashDisplay;
+exports.chainFromNamespace = chainFromNamespace;
+const chain_1 = require("../constants/chain");
+const enums_1 = require("../constants/enums");
+const bs58_1 = require("../internal/bs58");
+/**
+ * Convert an outbound tx hash from the internal canonical form (`0x`-prefixed
+ * hex, as Cosmos delivers it) to the form users expect on the destination
+ * chain. SVM signatures (64 bytes) become base58; EVM hashes pass through
+ * unchanged. Idempotent: a value that already lacks `0x` or whose chain isn't
+ * SVM is returned as-is.
+ *
+ * Used at user-facing boundaries that surface `externalTxHash` (receipt
+ * construction in response-builder, cascade hop info in cascade.ts, detector
+ * public-API output normalization). Do NOT apply at internal boundaries —
+ * `findChildUtxIdFromExternalTx` and the Cosmos tx-search query in
+ * inbound-tracker.ts expect the raw hex form.
+ */
+function toExternalTxHashDisplay(chain, rawTxHash) {
+    var _a;
+    if (!rawTxHash)
+        return rawTxHash;
+    if (!chain || ((_a = chain_1.CHAIN_INFO[chain]) === null || _a === void 0 ? void 0 : _a.vm) !== enums_1.VM.SVM)
+        return rawTxHash;
+    if (!rawTxHash.startsWith('0x'))
+        return rawTxHash;
+    const bytes = new Uint8Array(Buffer.from(rawTxHash.slice(2), 'hex'));
+    return bs58_1.bs58.encode(Buffer.from(bytes));
+}
+/**
+ * Map a CAIP namespace string (e.g. `'solana:devnet'`, `'eip155:11155111'`)
+ * to the corresponding `CHAIN` enum value, or `null` if no matching chain is
+ * registered. Used to resolve `PushChainOutboundSummary.destinationChain`
+ * (string) to a CHAIN enum so `toExternalTxHashDisplay` can decide whether
+ * to convert.
+ */
+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;
+}
+//# sourceMappingURL=external-tx-hash.js.map