@pushchain/core 5.1.5-alpha.1 → 5.1.5

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

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * Event ABI fragments used by the universal-tx detector.
+ *
+ * Sourced from push-chain-gateway-contracts and push-chain-core-contracts:
+ *   - UniversalTx, UniversalTxExecuted, RevertUniversalTx, FundsRescued
+ *       → contracts/evm-gateway/src/interfaces/IUniversalGateway.sol
+ *   - UniversalTxFinalized, UniversalTxReverted, FundsRescued (vault)
+ *       → contracts/evm-gateway/src/interfaces/IVault.sol
+ *   - UniversalTxOutbound
+ *       → contracts/evm-gateway/src/interfaces/IUniversalGatewayPC.sol
+ *
+ * RevertInstructions is a struct `(address revertRecipient, bytes revertMsg)`
+ * per contracts/evm-gateway/src/libraries/Types.sol.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNIVERSAL_TX_EVENT_ABI = exports.EVENT_UNIVERSAL_TX_OUTBOUND = exports.EVENT_UNIVERSAL_TX_REVERTED = exports.EVENT_UNIVERSAL_TX_FINALIZED = exports.EVENT_FUNDS_RESCUED = exports.EVENT_REVERT_UNIVERSAL_TX = exports.EVENT_UNIVERSAL_TX_EXECUTED = exports.EVENT_UNIVERSAL_TX = void 0;
+const REVERT_INSTRUCTIONS_COMPONENTS = [
+    { internalType: 'address', name: 'revertRecipient', type: 'address' },
+    { internalType: 'bytes', name: 'revertMsg', type: 'bytes' },
+];
+// ── Source-chain UniversalGateway events ──────────────────────────────
+/**
+ * UniversalTx(
+ *   address indexed sender,
+ *   address indexed recipient,
+ *   address token,
+ *   uint256 amount,
+ *   bytes payload,
+ *   address revertRecipient,
+ *   TX_TYPE txType,
+ *   bytes signatureData,
+ *   bool fromCEA
+ * )
+ *
+ * Note: this event does NOT carry subTxId/universalTxId. The detector
+ * derives universalTxId deterministically from (sourceChainId, txHash).
+ */
+exports.EVENT_UNIVERSAL_TX = {
+    anonymous: false,
+    type: 'event',
+    name: 'UniversalTx',
+    inputs: [
+        { indexed: true, internalType: 'address', name: 'sender', type: 'address' },
+        { indexed: true, internalType: 'address', name: 'recipient', type: 'address' },
+        { indexed: false, internalType: 'address', name: 'token', type: 'address' },
+        { indexed: false, internalType: 'uint256', name: 'amount', type: 'uint256' },
+        { indexed: false, internalType: 'bytes', name: 'payload', type: 'bytes' },
+        { indexed: false, internalType: 'address', name: 'revertRecipient', type: 'address' },
+        { indexed: false, internalType: 'uint8', name: 'txType', type: 'uint8' },
+        { indexed: false, internalType: 'bytes', name: 'signatureData', type: 'bytes' },
+        { indexed: false, internalType: 'bool', name: 'fromCEA', type: 'bool' },
+    ],
+};
+/**
+ * UniversalTxExecuted(
+ *   bytes32 indexed subTxId,
+ *   bytes32 indexed universalTxId,
+ *   address indexed pushAccount,
+ *   address target,
+ *   address token,
+ *   uint256 amount,
+ *   bytes data
+ * )
+ */
+exports.EVENT_UNIVERSAL_TX_EXECUTED = {
+    anonymous: false,
+    type: 'event',
+    name: 'UniversalTxExecuted',
+    inputs: [
+        { indexed: true, internalType: 'bytes32', name: 'subTxId', type: 'bytes32' },
+        { indexed: true, internalType: 'bytes32', name: 'universalTxId', type: 'bytes32' },
+        { indexed: true, internalType: 'address', name: 'pushAccount', type: 'address' },
+        { indexed: false, internalType: 'address', name: 'target', type: 'address' },
+        { indexed: false, internalType: 'address', name: 'token', type: 'address' },
+        { indexed: false, internalType: 'uint256', name: 'amount', type: 'uint256' },
+        { indexed: false, internalType: 'bytes', name: 'data', type: 'bytes' },
+    ],
+};
+/**
+ * RevertUniversalTx(
+ *   bytes32 indexed subTxId,
+ *   bytes32 indexed universalTxId,
+ *   address indexed to,
+ *   address token,
+ *   uint256 amount,
+ *   RevertInstructions revertInstruction
+ * )
+ */
+exports.EVENT_REVERT_UNIVERSAL_TX = {
+    anonymous: false,
+    type: 'event',
+    name: 'RevertUniversalTx',
+    inputs: [
+        { indexed: true, internalType: 'bytes32', name: 'subTxId', type: 'bytes32' },
+        { indexed: true, internalType: 'bytes32', name: 'universalTxId', type: 'bytes32' },
+        { indexed: true, internalType: 'address', name: 'to', type: 'address' },
+        { indexed: false, internalType: 'address', name: 'token', type: 'address' },
+        { indexed: false, internalType: 'uint256', name: 'amount', type: 'uint256' },
+        {
+            indexed: false,
+            internalType: 'struct RevertInstructions',
+            name: 'revertInstruction',
+            type: 'tuple',
+            components: REVERT_INSTRUCTIONS_COMPONENTS,
+        },
+    ],
+};
+/**
+ * FundsRescued(
+ *   bytes32 indexed subTxId,
+ *   bytes32 indexed universalTxId,
+ *   address indexed token,
+ *   uint256 amount,
+ *   RevertInstructions revertInstruction
+ * )
+ *
+ * Emitted by both UniversalGateway and Vault.
+ */
+exports.EVENT_FUNDS_RESCUED = {
+    anonymous: false,
+    type: 'event',
+    name: 'FundsRescued',
+    inputs: [
+        { indexed: true, internalType: 'bytes32', name: 'subTxId', type: 'bytes32' },
+        { indexed: true, internalType: 'bytes32', name: 'universalTxId', type: 'bytes32' },
+        { indexed: true, internalType: 'address', name: 'token', type: 'address' },
+        { indexed: false, internalType: 'uint256', name: 'amount', type: 'uint256' },
+        {
+            indexed: false,
+            internalType: 'struct RevertInstructions',
+            name: 'revertInstruction',
+            type: 'tuple',
+            components: REVERT_INSTRUCTIONS_COMPONENTS,
+        },
+    ],
+};
+// ── Vault events ──────────────────────────────────────────────────────
+/**
+ * UniversalTxFinalized(
+ *   bytes32 indexed subTxId,
+ *   bytes32 indexed universalTxId,
+ *   address indexed pushAccount,
+ *   address recipient,
+ *   address token,
+ *   uint256 amount,
+ *   bytes data
+ * )
+ */
+exports.EVENT_UNIVERSAL_TX_FINALIZED = {
+    anonymous: false,
+    type: 'event',
+    name: 'UniversalTxFinalized',
+    inputs: [
+        { indexed: true, internalType: 'bytes32', name: 'subTxId', type: 'bytes32' },
+        { indexed: true, internalType: 'bytes32', name: 'universalTxId', type: 'bytes32' },
+        { indexed: true, internalType: 'address', name: 'pushAccount', type: 'address' },
+        { indexed: false, internalType: 'address', name: 'recipient', type: 'address' },
+        { indexed: false, internalType: 'address', name: 'token', type: 'address' },
+        { indexed: false, internalType: 'uint256', name: 'amount', type: 'uint256' },
+        { indexed: false, internalType: 'bytes', name: 'data', type: 'bytes' },
+    ],
+};
+/**
+ * UniversalTxReverted(
+ *   bytes32 indexed subTxId,
+ *   bytes32 indexed universalTxId,
+ *   address indexed token,
+ *   uint256 amount,
+ *   RevertInstructions revertInstruction
+ * )
+ */
+exports.EVENT_UNIVERSAL_TX_REVERTED = {
+    anonymous: false,
+    type: 'event',
+    name: 'UniversalTxReverted',
+    inputs: [
+        { indexed: true, internalType: 'bytes32', name: 'subTxId', type: 'bytes32' },
+        { indexed: true, internalType: 'bytes32', name: 'universalTxId', type: 'bytes32' },
+        { indexed: true, internalType: 'address', name: 'token', type: 'address' },
+        { indexed: false, internalType: 'uint256', name: 'amount', type: 'uint256' },
+        {
+            indexed: false,
+            internalType: 'struct RevertInstructions',
+            name: 'revertInstruction',
+            type: 'tuple',
+            components: REVERT_INSTRUCTIONS_COMPONENTS,
+        },
+    ],
+};
+// ── Push-chain GatewayPC event ────────────────────────────────────────
+/**
+ * UniversalTxOutbound(
+ *   bytes32 indexed subTxId,
+ *   address indexed sender,
+ *   string chainNamespace,
+ *   address indexed token,
+ *   bytes recipient,
+ *   uint256 amount,
+ *   address gasToken,
+ *   uint256 gasFee,
+ *   uint256 gasLimit,
+ *   bytes payload,
+ *   uint256 protocolFee,
+ *   address revertRecipient,
+ *   TX_TYPE txType,
+ *   uint256 gasPrice
+ * )
+ */
+exports.EVENT_UNIVERSAL_TX_OUTBOUND = {
+    anonymous: false,
+    type: 'event',
+    name: 'UniversalTxOutbound',
+    inputs: [
+        { indexed: true, internalType: 'bytes32', name: 'subTxId', type: 'bytes32' },
+        { indexed: true, internalType: 'address', name: 'sender', type: 'address' },
+        { indexed: false, internalType: 'string', name: 'chainNamespace', type: 'string' },
+        { indexed: true, internalType: 'address', name: 'token', type: 'address' },
+        { indexed: false, internalType: 'bytes', name: 'recipient', type: 'bytes' },
+        { indexed: false, internalType: 'uint256', name: 'amount', type: 'uint256' },
+        { indexed: false, internalType: 'address', name: 'gasToken', type: 'address' },
+        { indexed: false, internalType: 'uint256', name: 'gasFee', type: 'uint256' },
+        { indexed: false, internalType: 'uint256', name: 'gasLimit', type: 'uint256' },
+        { indexed: false, internalType: 'bytes', name: 'payload', type: 'bytes' },
+        { indexed: false, internalType: 'uint256', name: 'protocolFee', type: 'uint256' },
+        { indexed: false, internalType: 'address', name: 'revertRecipient', type: 'address' },
+        { indexed: false, internalType: 'uint8', name: 'txType', type: 'uint8' },
+        { indexed: false, internalType: 'uint256', name: 'gasPrice', type: 'uint256' },
+    ],
+};
+/** Aggregated ABI handed to viem's parseEventLogs. */
+exports.UNIVERSAL_TX_EVENT_ABI = [
+    exports.EVENT_UNIVERSAL_TX,
+    exports.EVENT_UNIVERSAL_TX_EXECUTED,
+    exports.EVENT_REVERT_UNIVERSAL_TX,
+    exports.EVENT_FUNDS_RESCUED,
+    exports.EVENT_UNIVERSAL_TX_FINALIZED,
+    exports.EVENT_UNIVERSAL_TX_REVERTED,
+    exports.EVENT_UNIVERSAL_TX_OUTBOUND,
+];
+//# sourceMappingURL=events.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * Universal-Tx Detector — read-only SDK utility that, given a source-chain tx
+ * hash + chain, decodes any universal-tx events in the receipt and (optionally)
+ * cross-references the corresponding universalTx on Push Chain.
+ *
+ * Entrypoint: `detectUniversalTx(txHash, chain, opts?)`.
+ */
+export { detectUniversalTx } from './detector';
+export { classify, classifyAll } from './classify';
+export { deriveChildUniversalTxId, derivePcUniversalTxId, resolveChildInboundsFromDetection, resolveChildInboundsFromLogs, } from './child-inbounds';
+export type { ChildInboundResolution } from './child-inbounds';
+export { traceUniversalTxCascade, flattenCascade } from './cascade';
+export type { CascadeEdge, CascadeNode, PcRefundSummary, TraceCascadeOptions, } from './cascade';
+export { detectUniversalTxAuto, listAutoProbeChains, } from './auto-detect';
+export type { AutoDetectionResult, DetectUniversalTxAutoOptions, } from './auto-detect';
+export { EVENT_UNIVERSAL_TX, EVENT_UNIVERSAL_TX_EXECUTED, EVENT_REVERT_UNIVERSAL_TX, EVENT_FUNDS_RESCUED, EVENT_UNIVERSAL_TX_FINALIZED, EVENT_UNIVERSAL_TX_REVERTED, EVENT_UNIVERSAL_TX_OUTBOUND, UNIVERSAL_TX_EVENT_ABI, } from './events';
+export type { KnownEventName } from './events';
+export type { DecodedIdentifiers, DetectionEntry, DetectUniversalTxOptions, MatchingLog, PushChainCrossRef, PushChainOutboundSummary, TxTypeName, UniversalTxDetection, UniversalTxKind, } from './types';

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

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNIVERSAL_TX_EVENT_ABI = exports.EVENT_UNIVERSAL_TX_OUTBOUND = exports.EVENT_UNIVERSAL_TX_REVERTED = exports.EVENT_UNIVERSAL_TX_FINALIZED = exports.EVENT_FUNDS_RESCUED = exports.EVENT_REVERT_UNIVERSAL_TX = exports.EVENT_UNIVERSAL_TX_EXECUTED = exports.EVENT_UNIVERSAL_TX = exports.listAutoProbeChains = exports.detectUniversalTxAuto = exports.flattenCascade = exports.traceUniversalTxCascade = exports.resolveChildInboundsFromLogs = exports.resolveChildInboundsFromDetection = exports.derivePcUniversalTxId = exports.deriveChildUniversalTxId = exports.classifyAll = exports.classify = exports.detectUniversalTx = void 0;
+/**
+ * Universal-Tx Detector — read-only SDK utility that, given a source-chain tx
+ * hash + chain, decodes any universal-tx events in the receipt and (optionally)
+ * cross-references the corresponding universalTx on Push Chain.
+ *
+ * Entrypoint: `detectUniversalTx(txHash, chain, opts?)`.
+ */
+var detector_1 = require("./detector");
+Object.defineProperty(exports, "detectUniversalTx", { enumerable: true, get: function () { return detector_1.detectUniversalTx; } });
+var classify_1 = require("./classify");
+Object.defineProperty(exports, "classify", { enumerable: true, get: function () { return classify_1.classify; } });
+Object.defineProperty(exports, "classifyAll", { enumerable: true, get: function () { return classify_1.classifyAll; } });
+var child_inbounds_1 = require("./child-inbounds");
+Object.defineProperty(exports, "deriveChildUniversalTxId", { enumerable: true, get: function () { return child_inbounds_1.deriveChildUniversalTxId; } });
+Object.defineProperty(exports, "derivePcUniversalTxId", { enumerable: true, get: function () { return child_inbounds_1.derivePcUniversalTxId; } });
+Object.defineProperty(exports, "resolveChildInboundsFromDetection", { enumerable: true, get: function () { return child_inbounds_1.resolveChildInboundsFromDetection; } });
+Object.defineProperty(exports, "resolveChildInboundsFromLogs", { enumerable: true, get: function () { return child_inbounds_1.resolveChildInboundsFromLogs; } });
+var cascade_1 = require("./cascade");
+Object.defineProperty(exports, "traceUniversalTxCascade", { enumerable: true, get: function () { return cascade_1.traceUniversalTxCascade; } });
+Object.defineProperty(exports, "flattenCascade", { enumerable: true, get: function () { return cascade_1.flattenCascade; } });
+var auto_detect_1 = require("./auto-detect");
+Object.defineProperty(exports, "detectUniversalTxAuto", { enumerable: true, get: function () { return auto_detect_1.detectUniversalTxAuto; } });
+Object.defineProperty(exports, "listAutoProbeChains", { enumerable: true, get: function () { return auto_detect_1.listAutoProbeChains; } });
+var events_1 = require("./events");
+Object.defineProperty(exports, "EVENT_UNIVERSAL_TX", { enumerable: true, get: function () { return events_1.EVENT_UNIVERSAL_TX; } });
+Object.defineProperty(exports, "EVENT_UNIVERSAL_TX_EXECUTED", { enumerable: true, get: function () { return events_1.EVENT_UNIVERSAL_TX_EXECUTED; } });
+Object.defineProperty(exports, "EVENT_REVERT_UNIVERSAL_TX", { enumerable: true, get: function () { return events_1.EVENT_REVERT_UNIVERSAL_TX; } });
+Object.defineProperty(exports, "EVENT_FUNDS_RESCUED", { enumerable: true, get: function () { return events_1.EVENT_FUNDS_RESCUED; } });
+Object.defineProperty(exports, "EVENT_UNIVERSAL_TX_FINALIZED", { enumerable: true, get: function () { return events_1.EVENT_UNIVERSAL_TX_FINALIZED; } });
+Object.defineProperty(exports, "EVENT_UNIVERSAL_TX_REVERTED", { enumerable: true, get: function () { return events_1.EVENT_UNIVERSAL_TX_REVERTED; } });
+Object.defineProperty(exports, "EVENT_UNIVERSAL_TX_OUTBOUND", { enumerable: true, get: function () { return events_1.EVENT_UNIVERSAL_TX_OUTBOUND; } });
+Object.defineProperty(exports, "UNIVERSAL_TX_EVENT_ABI", { enumerable: true, get: function () { return events_1.UNIVERSAL_TX_EVENT_ABI; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,41 @@
+/**
+ * SVM-side universal-tx event metadata.
+ *
+ * Anchor programs emit events as base64-encoded `Program data:` log lines
+ * prefixed with an 8-byte discriminator. The map below covers the four SVM
+ * gateway events that have EVM parity (source: universalGatewayV0.json
+ * events section). The discriminator bytes come from the IDL and are
+ * converted to lowercase hex for matching.
+ */
+/**
+ * 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
+ * skipped — they wouldn't classify to any UniversalTxKind anyway.
+ */
+export declare const SVM_EVENT_DISCRIMINATORS: Record<string, string>;
+/**
+ * Classifier field names from classify.ts use EVM-style camelCase
+ * (`subTxId`, `universalTxId`, `revertRecipient`, `fromCEA`, `txType`).
+ * SVM IDL fields are snake_case. This helper renames the subset that
+ * classify.ts reads so the shared decoder logic works unchanged.
+ *
+ * The mapping is event-agnostic: keys that don't appear in a given event
+ * are simply absent from the input and ignored.
+ */
+export declare const SVM_FIELD_RENAMES: Record<string, string>;
+/**
+ * Event-specific field aliases.
+ *
+ * EVM `UniversalTxFinalized` exposes the payload blob as `data`; on SVM
+ * the field is named `payload`. EVM `RevertUniversalTx` exposes the
+ * recipient as `to`; SVM names it `revert_recipient` (already renamed
+ * to `revertRecipient` via SVM_FIELD_RENAMES). We add both aliases so
+ * classify.ts's event-specific switch finds them under the expected key.
+ */
+export declare const SVM_EVENT_FIELD_ALIASES: Record<string, Array<{
+    from: string;
+    to: string;
+}>>;
+/** Lowercase hex discriminator from an Anchor program-data decoded buffer. */
+export declare function discriminatorHex(buf: Uint8Array): string;

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

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * SVM-side universal-tx event metadata.
+ *
+ * Anchor programs emit events as base64-encoded `Program data:` log lines
+ * prefixed with an 8-byte discriminator. The map below covers the four SVM
+ * gateway events that have EVM parity (source: universalGatewayV0.json
+ * events section). The discriminator bytes come from the IDL and are
+ * converted to lowercase hex for matching.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SVM_EVENT_FIELD_ALIASES = exports.SVM_FIELD_RENAMES = exports.SVM_EVENT_DISCRIMINATORS = void 0;
+exports.discriminatorHex = discriminatorHex;
+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
+ * skipped — they wouldn't classify to any UniversalTxKind anyway.
+ */
+exports.SVM_EVENT_DISCRIMINATORS = {
+    [toHex([108, 154, 216, 41, 181, 234, 29, 124])]: 'UniversalTx',
+    [toHex([179, 64, 150, 112, 117, 140, 156, 37])]: 'UniversalTxFinalized',
+    [toHex([249, 74, 39, 203, 149, 54, 48, 186])]: 'RevertUniversalTx',
+    [toHex([159, 37, 6, 93, 98, 122, 176, 210])]: 'FundsRescued',
+};
+/**
+ * Classifier field names from classify.ts use EVM-style camelCase
+ * (`subTxId`, `universalTxId`, `revertRecipient`, `fromCEA`, `txType`).
+ * SVM IDL fields are snake_case. This helper renames the subset that
+ * classify.ts reads so the shared decoder logic works unchanged.
+ *
+ * The mapping is event-agnostic: keys that don't appear in a given event
+ * are simply absent from the input and ignored.
+ */
+exports.SVM_FIELD_RENAMES = {
+    sub_tx_id: 'subTxId',
+    universal_tx_id: 'universalTxId',
+    revert_recipient: 'revertRecipient',
+    push_account: 'pushAccount',
+    from_cea: 'fromCEA',
+    tx_type: 'txType',
+    signature_data: 'signatureData',
+};
+/**
+ * Event-specific field aliases.
+ *
+ * EVM `UniversalTxFinalized` exposes the payload blob as `data`; on SVM
+ * the field is named `payload`. EVM `RevertUniversalTx` exposes the
+ * recipient as `to`; SVM names it `revert_recipient` (already renamed
+ * to `revertRecipient` via SVM_FIELD_RENAMES). We add both aliases so
+ * classify.ts's event-specific switch finds them under the expected key.
+ */
+exports.SVM_EVENT_FIELD_ALIASES = {
+    UniversalTxFinalized: [{ from: 'payload', to: 'data' }],
+    RevertUniversalTx: [{ from: 'revertRecipient', to: 'to' }],
+};
+/** Lowercase hex discriminator from an Anchor program-data decoded buffer. */
+function discriminatorHex(buf) {
+    if (buf.length < 8)
+        return '';
+    let hex = '';
+    for (let i = 0; i < 8; i++) {
+        hex += buf[i].toString(16).padStart(2, '0');
+    }
+    return hex;
+}
+//# sourceMappingURL=svm-events.js.map

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

@@ -0,0 +1,100 @@
+/**
+ * Public types for the universal-tx detector.
+ */
+import type { CHAIN, PUSH_NETWORK } from '../constants/enums';
+import type { PushClient } from '../push-client/push-client';
+/**
+ * High-level classification for a transaction.
+ * Priority when multiple universal-tx events exist in the same receipt:
+ *   OUTBOUND_FINALIZED > OUTBOUND_REVERTED > OUTBOUND_INITIATED
+ *   > INBOUND_REVERTED > INBOUND_FROM_CEA > INBOUND_FROM_EOA
+ *   > EXECUTED_ON_DEST > RESCUED_FUNDS > UNKNOWN
+ */
+export type UniversalTxKind = 'INBOUND_FROM_EOA' | 'INBOUND_FROM_CEA' | 'OUTBOUND_INITIATED' | 'OUTBOUND_FINALIZED' | 'OUTBOUND_REVERTED' | 'INBOUND_REVERTED' | 'EXECUTED_ON_DEST' | 'RESCUED_FUNDS' | 'UNKNOWN';
+export type TxTypeName = 'GAS' | 'GAS_AND_PAYLOAD' | 'FUNDS' | 'FUNDS_AND_PAYLOAD' | 'RESCUE_FUNDS' | 'UNKNOWN';
+export interface DecodedIdentifiers {
+    subTxId?: `0x${string}`;
+    universalTxId?: `0x${string}`;
+    sender?: `0x${string}`;
+    recipient?: `0x${string}` | string;
+    pushAccount?: `0x${string}`;
+    token?: `0x${string}`;
+    amount?: bigint;
+    payloadPreview?: `0x${string}`;
+    payloadLength?: number;
+    txType?: number;
+    txTypeName?: TxTypeName;
+    fromCEA?: boolean;
+    destinationChainNamespace?: string;
+    gasFee?: bigint;
+    gasLimit?: bigint;
+    protocolFee?: bigint;
+    revertRecipient?: `0x${string}`;
+    revertMsgPreview?: `0x${string}`;
+}
+export interface MatchingLog {
+    eventName: string;
+    address: `0x${string}`;
+    logIndex: number;
+    args: Record<string, unknown>;
+}
+export interface PushChainOutboundSummary {
+    subTxId: string;
+    status: string;
+    destinationChain: string;
+    externalTxHash?: string;
+    amount?: string;
+    recipient?: string;
+}
+export interface PushChainCrossRef {
+    id: string;
+    status: number;
+    statusName: string;
+    pcTxHashes: string[];
+    outboundHashes: PushChainOutboundSummary[];
+    /** Set when cosmos has not progressed the status for an inbound tx. */
+    stuckObservation?: 'UNSPECIFIED' | 'PENDING_INBOUND_ONLY';
+    /** Cosmos query returned no record for this universalTxId. */
+    notFound?: boolean;
+}
+export interface DetectionEntry {
+    kind: UniversalTxKind;
+    decoded: DecodedIdentifiers;
+    log: MatchingLog;
+}
+export interface UniversalTxDetection {
+    txHash: `0x${string}`;
+    chain: CHAIN;
+    /**
+     * Primary classification (highest-priority event in the receipt).
+     * See `detections` for the per-log list when a receipt carries multiple
+     * universal events (e.g. outbound finalize + CEA-originated inbound).
+     */
+    kind: UniversalTxKind;
+    /** Decoded identifiers for the primary log. */
+    decoded: DecodedIdentifiers;
+    /** Unique emitter addresses of the matching logs. */
+    emitters: `0x${string}`[];
+    matchingLogs: MatchingLog[];
+    /** One entry per matching universal-tx log. Empty when kind is UNKNOWN. */
+    detections: DetectionEntry[];
+    pushChainTx?: PushChainCrossRef;
+    notes: string[];
+}
+export interface DetectUniversalTxOptions {
+    /**
+     * PushClient used to cross-reference the cosmos side. When omitted
+     * (or skipPushChainLookup=true), `pushChainTx` stays undefined.
+     */
+    pushClient?: PushClient;
+    /**
+     * Per-chain RPC overrides. Falls back to CHAIN_INFO[chain].defaultRPC.
+     */
+    rpcUrls?: Partial<Record<CHAIN, string[]>>;
+    skipPushChainLookup?: boolean;
+    /**
+     * PUSH_NETWORK used for deriving universalTxId on inbound txs where the
+     * emitted UniversalTx event does not carry one. Defaults to TESTNET_DONUT.
+     */
+    pushNetwork?: PUSH_NETWORK;
+}

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/src/lib/utils.d.ts

@@ -3,7 +3,8 @@ import { construct, toUniversal as toUniversalSigner, toUniversalFromKeypair } f
 import { CHAIN, PUSH_NETWORK } from './constants/enums';
 import { type MoveableToken } from './constants/tokens';
 import type { PushChain } from './push-chain/push-chain';
-import { registerIdl as registerSvmIdl, getRegisteredIdls as getRegisteredSvmIdls, getIdl as getSvmIdl } from './orchestrator/svm-idl/registry';
+import type { Idl } from '@coral-xyz/anchor';
+import { registerIdl as registerSvmIdl, getRegisteredIdls as getRegisteredSvmIdls } from './orchestrator/svm-idl/registry';
 /**
  * @dev - THESE UTILS ARE EXPORTED TO SDK CONSUMER
  * @dev - Make sure each exported fn has good comments to help out sdk consumer
@@ -34,22 +35,17 @@ export declare class Utils {
         resolveControllerAccount: typeof resolveControllerAccount;
     };
     /**
-     * SVM (Solana) utilities for registering program Anchor IDLs.
+     * SVM (Solana) escape-hatch utilities.
      *
-     * Register your program's Anchor IDL once per process; `prepareTransaction`
-     * then resolves accounts, PDAs, and signers from the IDL so you only need
-     * to pass `data` (discriminator + Borsh args), the same shape used for EVM.
+     * `PushChain.utils.helpers.encodeTxData({ abi: idl, ... })` auto-registers
+     * the Anchor IDL internally, so normal callers never need these.
      *
-     * @example
-     * PushChain.utils.svm.registerIdl(
-     *   PROGRAM_ADDRESS_HEX,
-     *   testCounterIdl
-     * );
+     * Use `registerIdl` directly only when you build `data` manually (raw
+     * Anchor discriminator + Borsh bytes) and bypass `encodeTxData`.
      */
     static svm: {
         registerIdl: typeof registerSvmIdl;
         getRegisteredIdls: typeof getRegisteredSvmIdls;
-        getIdl: typeof getSvmIdl;
     };
     static signer: {
         /**
@@ -116,8 +112,29 @@ export declare class Utils {
          * and delegates to Utils.chains.getChainNamespace.
          */
         getChainName: (chainName: string) => string | undefined;
-        encodeTxData({ abi, functionName, args, }: {
-            abi: any;
+        /**
+         * Encode calldata for a universal tx.
+         *
+         * Pass `abi` for EVM targets, or `idl` for SVM (Anchor) targets. Exactly
+         * one of the two is required.
+         *
+         * @example EVM
+         * PushChain.utils.helpers.encodeTxData({
+         *   abi: erc20Abi,
+         *   functionName: 'transfer',
+         *   args: [to, amount],
+         * });
+         *
+         * @example SVM (Anchor)
+         * PushChain.utils.helpers.encodeTxData({
+         *   idl: counterIdl,
+         *   functionName: 'increment',
+         *   args: [],
+         * });
+         */
+        encodeTxData({ abi, idl, functionName, args, }: {
+            abi?: any;
+            idl?: Idl;
             functionName: string;
             args?: any[];
         }): `0x${string}`;