@pushchain/core 5.1.5-alpha.1 → 5.1.6

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

@@ -0,0 +1,233 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeUniversalTxId = exports.__internalStatusNames = void 0;
+exports.detectUniversalTx = detectUniversalTx;
+const tslib_1 = require("tslib");
+/**
+ * detectUniversalTx — given a source-chain tx hash + chain, fetch the receipt,
+ * decode all universal-tx events, classify the tx, and (optionally) cross-
+ * reference the corresponding universalTx on Push Chain via cosmos.
+ *
+ * Read-only. No signer required. No Push block-explorer dependency.
+ *
+ * Dispatches on CHAIN_INFO[chain].vm — EVM uses viem's parseEventLogs below,
+ * SVM delegates to detector-svm.ts which decodes Anchor program-data logs
+ * with the gateway IDL. Both branches return an identical UniversalTxDetection
+ * shape so downstream consumers (classify, cascade, child-inbounds,
+ * inbound-tracker) are VM-agnostic.
+ */
+const viem_1 = require("viem");
+const chain_1 = require("../constants/chain");
+const enums_1 = require("../constants/enums");
+const outbound_tracker_1 = require("../orchestrator/internals/outbound-tracker");
+Object.defineProperty(exports, "computeUniversalTxId", { enumerable: true, get: function () { return outbound_tracker_1.computeUniversalTxId; } });
+const events_1 = require("./events");
+const classify_1 = require("./classify");
+const child_inbounds_1 = require("./child-inbounds");
+const detector_svm_1 = require("./detector-svm");
+// ── Status name table (copied from scripts/poll-outbound.ts:33-44) ────
+const UNIVERSAL_TX_STATUS_NAMES = {
+    0: 'UNIVERSAL_TX_STATUS_UNSPECIFIED',
+    1: 'INBOUND_SUCCESS',
+    2: 'PENDING_INBOUND_EXECUTION',
+    3: 'PC_EXECUTED_SUCCESS',
+    4: 'PC_EXECUTED_FAILED',
+    5: 'PC_PENDING_REVERT',
+    6: 'OUTBOUND_PENDING',
+    7: 'OUTBOUND_SUCCESS',
+    8: 'OUTBOUND_FAILED',
+    9: 'CANCELED',
+};
+const INBOUND_KINDS = new Set([
+    'INBOUND_FROM_EOA',
+    'INBOUND_FROM_CEA',
+]);
+function detectUniversalTx(txHash_1, chain_2) {
+    return tslib_1.__awaiter(this, arguments, void 0, function* (txHash, chain, opts = {}) {
+        var _a;
+        const notes = [];
+        const chainInfo = chain_1.CHAIN_INFO[chain];
+        if (!chainInfo) {
+            throw new Error(`detectUniversalTx: unknown chain ${chain}`);
+        }
+        if (chainInfo.vm === enums_1.VM.SVM) {
+            return (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}`);
+        }
+        const rpcUrls = ((_a = opts.rpcUrls) === null || _a === void 0 ? void 0 : _a[chain]) && opts.rpcUrls[chain].length > 0
+            ? opts.rpcUrls[chain]
+            : chainInfo.defaultRPC.filter((r) => r && r.length > 0);
+        if (rpcUrls.length === 0) {
+            throw new Error(`detectUniversalTx: no RPC URL configured for chain ${chain}`);
+        }
+        const publicClient = (0, viem_1.createPublicClient)({
+            transport: (0, viem_1.fallback)(rpcUrls.map((url) => (0, viem_1.http)(url))),
+        });
+        let receipt;
+        try {
+            receipt = yield publicClient.getTransactionReceipt({ hash: txHash });
+        }
+        catch (err) {
+            // viem throws if the tx isn't found yet; treat as no-receipt.
+            notes.push(`receipt fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+            return emptyDetection(txHash, chain, notes);
+        }
+        if (!receipt) {
+            notes.push('no receipt returned by RPC');
+            return emptyDetection(txHash, chain, notes);
+        }
+        if (receipt.status === 'reverted' && receipt.logs.length === 0) {
+            notes.push('tx reverted with no logs');
+            return emptyDetection(txHash, chain, notes);
+        }
+        const parsed = (0, viem_1.parseEventLogs)({
+            abi: events_1.UNIVERSAL_TX_EVENT_ABI,
+            logs: receipt.logs,
+            strict: false,
+        });
+        const matchingLogs = parsed.map((p) => {
+            var _a, _b;
+            return ({
+                eventName: p.eventName,
+                address: p.address,
+                logIndex: typeof p.logIndex ===
+                    'bigint'
+                    ? Number(p.logIndex)
+                    : (_a = p.logIndex) !== null && _a !== void 0 ? _a : -1,
+                args: ((_b = p.args) !== null && _b !== void 0 ? _b : {}),
+            });
+        });
+        const classified = (0, classify_1.classify)(matchingLogs);
+        notes.push(...classified.notes);
+        const decoded = Object.assign({}, classified.decoded);
+        // Deterministic universalTxId derivation for primary kinds whose event
+        // doesn't carry it. Formulas from push-chain/x/uexecutor/types/keys.go:
+        //   - Inbound (any external-chain UniversalTx log):
+        //       sha256(`<caip>:<txHash>:<logIndex>`)   — GetInboundUniversalTxKey:49
+        //   - Push-initiated outbound (UniversalTxOutbound on Push Chain):
+        //       sha256(`<caip>:<txHash>`)              — GetPcUniversalTxKey:63
+        if (!decoded.universalTxId) {
+            const caip = chain; // CHAIN enum values are CAIP-2 strings.
+            if (INBOUND_KINDS.has(classified.kind) &&
+                classified.primaryLog &&
+                classified.primaryLog.logIndex >= 0) {
+                decoded.universalTxId = (0, child_inbounds_1.deriveChildUniversalTxId)(caip, txHash, classified.primaryLog.logIndex);
+                notes.push(`universalTxId derived via sha256("${caip}:<txHash>:${classified.primaryLog.logIndex}")`);
+            }
+            else if (classified.kind === 'OUTBOUND_INITIATED') {
+                decoded.universalTxId = (0, child_inbounds_1.derivePcUniversalTxId)(caip, txHash);
+                notes.push(`universalTxId derived via sha256("${caip}:<txHash>") — pc outbound`);
+            }
+        }
+        // Optional cosmos cross-reference.
+        let pushChainTx;
+        if (opts.pushClient &&
+            !opts.skipPushChainLookup &&
+            decoded.universalTxId) {
+            pushChainTx = yield crossReferencePushChain(opts.pushClient, decoded.universalTxId, classified.kind, notes);
+        }
+        else if (decoded.universalTxId && !opts.pushClient) {
+            notes.push('push cross-reference skipped (no pushClient provided)');
+        }
+        const detections = (0, classify_1.classifyAll)(classified.matchingLogs);
+        return {
+            txHash,
+            chain,
+            kind: classified.kind,
+            emitters: classified.emitters,
+            decoded,
+            matchingLogs: classified.matchingLogs,
+            detections,
+            pushChainTx,
+            notes,
+        };
+    });
+}
+// ── Helpers ───────────────────────────────────────────────────────────
+function emptyDetection(txHash, chain, notes) {
+    return {
+        txHash,
+        chain,
+        kind: 'UNKNOWN',
+        emitters: [],
+        decoded: {},
+        matchingLogs: [],
+        detections: [],
+        notes,
+    };
+}
+function crossReferencePushChain(pushClient, universalTxId, kind, notes) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        const id = universalTxId.startsWith('0x')
+            ? universalTxId.slice(2)
+            : universalTxId;
+        try {
+            const resp = yield pushClient.getUniversalTxByIdV2(id);
+            const utx = resp === null || resp === void 0 ? void 0 : resp.universalTx;
+            if (!utx || !utx.id) {
+                return {
+                    id,
+                    status: 0,
+                    statusName: UNIVERSAL_TX_STATUS_NAMES[0],
+                    pcTxHashes: [],
+                    outboundHashes: [],
+                    notFound: true,
+                };
+            }
+            const status = ((_a = utx.universalStatus) !== null && _a !== void 0 ? _a : 0);
+            const statusName = (_b = UNIVERSAL_TX_STATUS_NAMES[status]) !== null && _b !== void 0 ? _b : `UNKNOWN(${status})`;
+            const pcTxHashes = ((_c = utx.pcTx) !== null && _c !== void 0 ? _c : [])
+                .map((p) => p === null || p === void 0 ? void 0 : p.txHash)
+                .filter((h) => Boolean(h));
+            const outboundHashes = ((_d = utx.outboundTx) !== null && _d !== void 0 ? _d : []).map((ob) => {
+                var _a, _b, _c;
+                return ({
+                    subTxId: (_a = ob.id) !== null && _a !== void 0 ? _a : '',
+                    status: outboundStatusName(ob.outboundStatus),
+                    destinationChain: (_b = ob.destinationChain) !== null && _b !== void 0 ? _b : '',
+                    externalTxHash: ((_c = ob.observedTx) === null || _c === void 0 ? void 0 : _c.txHash) || undefined,
+                    amount: ob.amount,
+                    recipient: ob.recipient,
+                });
+            });
+            let stuckObservation;
+            if (INBOUND_KINDS.has(kind)) {
+                if (status === 0)
+                    stuckObservation = 'UNSPECIFIED';
+                else if (status === 2 && outboundHashes.length === 0)
+                    stuckObservation = 'PENDING_INBOUND_ONLY';
+            }
+            return {
+                id,
+                status,
+                statusName,
+                pcTxHashes,
+                outboundHashes,
+                stuckObservation,
+            };
+        }
+        catch (err) {
+            notes.push(`push cross-reference failed: ${err instanceof Error ? err.message : String(err)}`);
+            return undefined;
+        }
+    });
+}
+function outboundStatusName(n) {
+    switch (n) {
+        case 0:
+            return 'OUTBOUND_STATUS_UNSPECIFIED';
+        case 1:
+            return 'PENDING';
+        case 2:
+            return 'OBSERVED';
+        case 3:
+            return 'REVERTED';
+        default:
+            return `UNKNOWN(${n !== null && n !== void 0 ? n : '?'})`;
+    }
+}
+exports.__internalStatusNames = UNIVERSAL_TX_STATUS_NAMES;
+//# sourceMappingURL=detector.js.map