@pushchain/core 5.1.17 → 6.0.0

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/universal-tx-detector/svm-events.d.ts

@@ -10,7 +10,7 @@
 /**
  * Mapping: 8-byte discriminator (lowercase hex, no 0x) → Anchor event name.
  * Only events with EVM classifier parity are listed; the keeper-agnostic
- * ones (BlockUsdCapUpdated, ProtocolFeeCollected, etc.) are intentionally
+ * ones (BlockUsdCapUpdated, inbound-fee events, etc.) are intentionally
  * skipped — they wouldn't classify to any UniversalTxKind anyway.
  */
 export declare const SVM_EVENT_DISCRIMINATORS: Record<string, string>;

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

@@ -15,7 +15,7 @@ const toHex = (bytes) => bytes.map((b) => b.toString(16).padStart(2, '0')).join(
 /**
  * Mapping: 8-byte discriminator (lowercase hex, no 0x) → Anchor event name.
  * Only events with EVM classifier parity are listed; the keeper-agnostic
- * ones (BlockUsdCapUpdated, ProtocolFeeCollected, etc.) are intentionally
+ * ones (BlockUsdCapUpdated, inbound-fee events, etc.) are intentionally
  * skipped — they wouldn't classify to any UniversalTxKind anyway.
  */
 exports.SVM_EVENT_DISCRIMINATORS = {

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