@pushchain/core 5.1.17 → 5.1.18

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