@pushchain/core 5.1.5-alpha.1 → 5.1.5

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

@@ -0,0 +1,33 @@
+import type { KnownEventName } from './events';
+import type { DecodedIdentifiers, MatchingLog, TxTypeName, UniversalTxKind } from './types';
+export interface ClassifyResult {
+    kind: UniversalTxKind;
+    decoded: DecodedIdentifiers;
+    matchingLogs: MatchingLog[];
+    emitters: `0x${string}`[];
+    notes: string[];
+    /** The log that determined the kind (for downstream enrichment). */
+    primaryLog?: MatchingLog;
+}
+export interface DetectionEntry {
+    kind: UniversalTxKind;
+    decoded: DecodedIdentifiers;
+    log: MatchingLog;
+}
+export declare function classify(parsedLogs: MatchingLog[]): ClassifyResult;
+/**
+ * Per-log classification. Each matching universal-tx log yields one detection
+ * entry — so a receipt carrying `UniversalTxFinalized` + a CEA-originated
+ * `UniversalTx(fromCEA=true)` produces two entries.
+ *
+ * Unknown event names are dropped (they wouldn't have reached this stage
+ * anyway — parseEventLogs only emits logs that matched the ABI).
+ */
+export declare function classifyAll(logs: MatchingLog[]): DetectionEntry[];
+export declare const __internal: {
+    TX_TYPE_NAMES: Record<number, TxTypeName>;
+    CLASSIFICATION_PRIORITY: {
+        eventName: KnownEventName;
+        kind: UniversalTxKind | ((args: Record<string, unknown>) => UniversalTxKind);
+    }[];
+};

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

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__internal = void 0;
+exports.classify = classify;
+exports.classifyAll = classifyAll;
+/**
+ * TX_TYPE enum from push-chain-gateway-contracts/src/libraries/Types.sol:5-22.
+ */
+const TX_TYPE_NAMES = {
+    0: 'GAS',
+    1: 'GAS_AND_PAYLOAD',
+    2: 'FUNDS',
+    3: 'FUNDS_AND_PAYLOAD',
+    4: 'RESCUE_FUNDS',
+};
+/**
+ * Priority order: the first match wins. Mirrors the plan doc.
+ */
+const CLASSIFICATION_PRIORITY = [
+    { eventName: 'UniversalTxFinalized', kind: 'OUTBOUND_FINALIZED' },
+    { eventName: 'UniversalTxReverted', kind: 'OUTBOUND_REVERTED' },
+    { eventName: 'UniversalTxOutbound', kind: 'OUTBOUND_INITIATED' },
+    { eventName: 'RevertUniversalTx', kind: 'INBOUND_REVERTED' },
+    {
+        eventName: 'UniversalTx',
+        kind: (args) => args['fromCEA'] === true ? 'INBOUND_FROM_CEA' : 'INBOUND_FROM_EOA',
+    },
+    { eventName: 'UniversalTxExecuted', kind: 'EXECUTED_ON_DEST' },
+    { eventName: 'FundsRescued', kind: 'RESCUED_FUNDS' },
+];
+function classify(parsedLogs) {
+    const emitters = Array.from(new Set(parsedLogs.map((l) => l.address)));
+    if (parsedLogs.length === 0) {
+        return {
+            kind: 'UNKNOWN',
+            decoded: {},
+            matchingLogs: [],
+            emitters: [],
+            notes: ['no universal-tx events decoded'],
+        };
+    }
+    for (const { eventName, kind } of CLASSIFICATION_PRIORITY) {
+        const hit = parsedLogs.find((l) => l.eventName === eventName);
+        if (!hit)
+            continue;
+        const resolvedKind = typeof kind === 'function' ? kind(hit.args) : kind;
+        const decoded = buildDecoded(resolvedKind, hit, parsedLogs);
+        return {
+            kind: resolvedKind,
+            decoded,
+            matchingLogs: parsedLogs,
+            emitters,
+            notes: [],
+            primaryLog: hit,
+        };
+    }
+    return {
+        kind: 'UNKNOWN',
+        decoded: {},
+        matchingLogs: parsedLogs,
+        emitters,
+        notes: ['no known universal-tx event among decoded logs'],
+    };
+}
+// ── Identifier extraction ─────────────────────────────────────────────
+function buildDecoded(kind, primary, allLogs) {
+    const out = {};
+    const a = primary.args;
+    assignHex(out, 'subTxId', a['subTxId']);
+    assignHex(out, 'universalTxId', a['universalTxId']);
+    switch (primary.eventName) {
+        case 'UniversalTx':
+            out.sender = asAddress(a['sender']);
+            out.recipient = asAddress(a['recipient']);
+            out.token = asAddress(a['token']);
+            out.amount = asBigint(a['amount']);
+            setPayload(out, a['payload']);
+            out.revertRecipient = asAddress(a['revertRecipient']);
+            setTxType(out, a['txType']);
+            out.fromCEA = Boolean(a['fromCEA']);
+            break;
+        case 'UniversalTxExecuted':
+            out.pushAccount = asAddress(a['pushAccount']);
+            out.token = asAddress(a['token']);
+            out.amount = asBigint(a['amount']);
+            setPayload(out, a['data']);
+            break;
+        case 'RevertUniversalTx':
+            out.recipient = asAddress(a['to']);
+            out.token = asAddress(a['token']);
+            out.amount = asBigint(a['amount']);
+            setRevertInstruction(out, a['revertInstruction']);
+            break;
+        case 'FundsRescued':
+            out.token = asAddress(a['token']);
+            out.amount = asBigint(a['amount']);
+            setRevertInstruction(out, a['revertInstruction']);
+            break;
+        case 'UniversalTxFinalized':
+            out.pushAccount = asAddress(a['pushAccount']);
+            out.recipient = asAddress(a['recipient']);
+            out.token = asAddress(a['token']);
+            out.amount = asBigint(a['amount']);
+            setPayload(out, a['data']);
+            break;
+        case 'UniversalTxReverted':
+            out.token = asAddress(a['token']);
+            out.amount = asBigint(a['amount']);
+            setRevertInstruction(out, a['revertInstruction']);
+            break;
+        case 'UniversalTxOutbound':
+            out.sender = asAddress(a['sender']);
+            out.token = asAddress(a['token']);
+            out.amount = asBigint(a['amount']);
+            if (typeof a['recipient'] === 'string') {
+                out.recipient = a['recipient'];
+            }
+            setPayload(out, a['payload']);
+            if (typeof a['chainNamespace'] === 'string') {
+                out.destinationChainNamespace = a['chainNamespace'];
+            }
+            out.gasFee = asBigint(a['gasFee']);
+            out.gasLimit = asBigint(a['gasLimit']);
+            out.protocolFee = asBigint(a['protocolFee']);
+            out.revertRecipient = asAddress(a['revertRecipient']);
+            setTxType(out, a['txType']);
+            break;
+    }
+    // Enrichment: OUTBOUND_FINALIZED receipts usually also carry a UniversalTxExecuted
+    // fired by the CEA during the inner call. Use it to surface extra fields when
+    // the primary log was sparse.
+    if (kind === 'OUTBOUND_FINALIZED') {
+        const executed = allLogs.find((l) => l.eventName === 'UniversalTxExecuted');
+        if (executed && !out.pushAccount) {
+            out.pushAccount = asAddress(executed.args['pushAccount']);
+        }
+    }
+    return out;
+}
+// ── Type coercers ─────────────────────────────────────────────────────
+function asAddress(v) {
+    return typeof v === 'string' && v.startsWith('0x')
+        ? v
+        : undefined;
+}
+function asBigint(v) {
+    if (typeof v === 'bigint')
+        return v;
+    if (typeof v === 'number')
+        return BigInt(v);
+    if (typeof v === 'string') {
+        try {
+            return BigInt(v);
+        }
+        catch (_a) {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function assignHex(out, key, v) {
+    if (typeof v === 'string' && v.startsWith('0x')) {
+        out[key] = v;
+    }
+}
+function setTxType(out, raw) {
+    var _a;
+    const n = typeof raw === 'number'
+        ? raw
+        : typeof raw === 'bigint'
+            ? Number(raw)
+            : undefined;
+    if (n === undefined)
+        return;
+    out.txType = n;
+    out.txTypeName = (_a = TX_TYPE_NAMES[n]) !== null && _a !== void 0 ? _a : 'UNKNOWN';
+}
+function setPayload(out, raw) {
+    if (typeof raw !== 'string' || !raw.startsWith('0x'))
+        return;
+    const hex = raw;
+    // byte-length = (hex.length - 2) / 2
+    out.payloadLength = Math.max(0, (hex.length - 2) / 2);
+    out.payloadPreview = hex.slice(0, 2 + 64); // 32 bytes hex
+}
+function setRevertInstruction(out, raw) {
+    if (!raw)
+        return;
+    // viem decodes a (address,bytes) tuple as either an object with named keys
+    // (when ABI has components with names) or a positional array.
+    if (Array.isArray(raw)) {
+        const [recipient, msg] = raw;
+        out.revertRecipient = asAddress(recipient);
+        if (typeof msg === 'string' && msg.startsWith('0x')) {
+            out.revertMsgPreview = msg.slice(0, 2 + 64);
+        }
+    }
+    else if (typeof raw === 'object') {
+        const obj = raw;
+        out.revertRecipient = asAddress(obj['revertRecipient']);
+        const msg = obj['revertMsg'];
+        if (typeof msg === 'string' && msg.startsWith('0x')) {
+            out.revertMsgPreview = msg.slice(0, 2 + 64);
+        }
+    }
+}
+/**
+ * Per-log classification. Each matching universal-tx log yields one detection
+ * entry — so a receipt carrying `UniversalTxFinalized` + a CEA-originated
+ * `UniversalTx(fromCEA=true)` produces two entries.
+ *
+ * Unknown event names are dropped (they wouldn't have reached this stage
+ * anyway — parseEventLogs only emits logs that matched the ABI).
+ */
+function classifyAll(logs) {
+    const kindByEventName = new Map(CLASSIFICATION_PRIORITY.map(({ eventName, kind }) => [eventName, kind]));
+    const out = [];
+    for (const log of logs) {
+        const resolver = kindByEventName.get(log.eventName);
+        if (!resolver)
+            continue;
+        const kind = typeof resolver === 'function' ? resolver(log.args) : resolver;
+        out.push({ kind, decoded: buildDecoded(kind, log, logs), log });
+    }
+    return out;
+}
+exports.__internal = { TX_TYPE_NAMES, CLASSIFICATION_PRIORITY };
+//# sourceMappingURL=classify.js.map

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

@@ -0,0 +1,46 @@
+import type { Connection } from '@solana/web3.js';
+import { CHAIN } from '../constants/enums';
+import type { DetectUniversalTxOptions, UniversalTxDetection } from './types';
+export interface DetectUniversalTxSvmOptions extends DetectUniversalTxOptions {
+    /**
+     * Injected Solana connection for tests. In production, the detector
+     * constructs a Connection from CHAIN_INFO.defaultRPC (or opts.rpcUrls).
+     */
+    connection?: Connection;
+}
+/**
+ * SVM detector entry. Accepts a base58 Solana signature and returns the
+ * same UniversalTxDetection shape as the EVM detector so every downstream
+ * consumer (classify, cascade, child-inbounds, inbound-tracker) can treat
+ * EVM and SVM results uniformly.
+ */
+export declare function detectUniversalTxSvm(signature: string, chain: CHAIN, opts?: DetectUniversalTxSvmOptions): Promise<UniversalTxDetection>;
+/**
+ * Convert an Anchor-decoded event struct into the shape classify.ts expects.
+ *
+ *  - snake_case → camelCase for known keys (subTxId, universalTxId, etc.)
+ *  - PublicKey → `0x${hex}` 32-byte string
+ *  - Buffer/Uint8Array fixed arrays → `0x${hex}`
+ *  - BN/bigint numerics → bigint
+ *  - Anchor enum objects for tx_type → numeric variant index
+ *  - Event-specific aliases (UniversalTxFinalized.payload → data,
+ *    RevertUniversalTx.revertRecipient → to) so downstream switch arms find
+ *    the expected keys.
+ */
+declare function normalizeSvmEventArgs(eventName: string, raw: unknown): Record<string, unknown>;
+declare function extractTxTypeIndex(v: Record<string, unknown>): number | undefined;
+/**
+ * Accept either a base58 Solana signature (native form) or a 0x-prefixed
+ * 128-char hex of the 64-byte signature bytes (the form used by cosmos
+ * keeper storage and by the cascade walker when it hands off an
+ * `observedTx.txHash`). Return the base58 form the RPC expects.
+ */
+declare function normalizeSolanaSignature(input: string): string;
+declare function solanaSigToHex(base58Sig: string): `0x${string}`;
+export declare const __svmInternal: {
+    normalizeSvmEventArgs: typeof normalizeSvmEventArgs;
+    extractTxTypeIndex: typeof extractTxTypeIndex;
+    normalizeSolanaSignature: typeof normalizeSolanaSignature;
+    solanaSigToHex: typeof solanaSigToHex;
+};
+export {};

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

@@ -0,0 +1,324 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__svmInternal = void 0;
+exports.detectUniversalTxSvm = detectUniversalTxSvm;
+const tslib_1 = require("tslib");
+/**
+ * detectUniversalTxSvm — SVM counterpart to the EVM detector.
+ *
+ * Fetches the tx via Solana RPC, walks `meta.logMessages`, decodes each
+ * `Program data:` entry with Anchor's BorshEventCoder against the gateway
+ * IDL, normalizes field names to match classify.ts's EVM-derived shape,
+ * and hands the result to the same classifier used by the EVM branch.
+ *
+ * Behavior deliberately mirrors detector.ts: same UniversalTxDetection
+ * return, same universalTxId derivation strategy (primary-log fallback
+ * via deriveChildUniversalTxId on source-chain inbounds).
+ *
+ * Open contract with the push-chain cosmos keeper (documented in the
+ * plan): the keeper must derive SVM inbound universalTxIds using the
+ * Solana base58 signature verbatim inside `${caip}:${sig}:${logIndex}`.
+ * If the keeper uses a different representation (hex bytes, sub_tx_id
+ * field, etc.) the `rawSource` argument to deriveChildUniversalTxId below
+ * needs to swap — single line.
+ */
+const anchor_1 = require("@coral-xyz/anchor");
+const web3_js_1 = require("@solana/web3.js");
+const viem_1 = require("viem");
+const bs58_1 = require("../internal/bs58");
+const universalGatewayV0_json_1 = tslib_1.__importDefault(require("../constants/abi/universalGatewayV0.json"));
+const chain_1 = require("../constants/chain");
+const classify_1 = require("./classify");
+const svm_events_1 = require("./svm-events");
+const INBOUND_KINDS = new Set([
+    'INBOUND_FROM_EOA',
+    'INBOUND_FROM_CEA',
+]);
+/**
+ * SVM detector entry. Accepts a base58 Solana signature and returns the
+ * same UniversalTxDetection shape as the EVM detector so every downstream
+ * consumer (classify, cascade, child-inbounds, inbound-tracker) can treat
+ * EVM and SVM results uniformly.
+ */
+function detectUniversalTxSvm(signature_1, chain_2) {
+    return tslib_1.__awaiter(this, arguments, void 0, function* (signature, chain, opts = {}) {
+        var _a;
+        const notes = [];
+        const chainInfo = chain_1.CHAIN_INFO[chain];
+        const castHash = signature; // intentional — we widen downstream
+        if (!chainInfo) {
+            throw new Error(`detectUniversalTxSvm: unknown chain ${chain}`);
+        }
+        const connection = yield resolveConnection(chain, opts);
+        // The cascade (and cosmos) stores Solana signatures as 0x-prefixed hex of
+        // the 64-byte signature bytes. Solana RPC needs base58 — normalize here
+        // so callers can pass either form interchangeably.
+        const rpcSig = normalizeSolanaSignature(signature);
+        let tx;
+        try {
+            tx = yield connection.getTransaction(rpcSig, {
+                commitment: 'confirmed',
+                maxSupportedTransactionVersion: 0,
+            });
+        }
+        catch (err) {
+            notes.push(`svm tx fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+            return emptyDetection(castHash, chain, notes);
+        }
+        if (!tx || !tx.meta) {
+            notes.push('no svm tx returned by RPC');
+            return emptyDetection(castHash, chain, notes);
+        }
+        // Reverted with no logs — same early-out as EVM path.
+        const err = tx.meta.err;
+        const logMessages = ((_a = tx.meta.logMessages) !== null && _a !== void 0 ? _a : []);
+        if (err && logMessages.length === 0) {
+            notes.push('svm tx reverted with no logs');
+            return emptyDetection(castHash, chain, notes);
+        }
+        // Emitter for SVM is the gateway program id from CHAIN_INFO.
+        // Encoded as 0x-prefixed 32-byte hex so MatchingLog.address stays
+        // assignable to the `0x${string}` type without widening.
+        const emitterBase58 = chainInfo.lockerContract || '';
+        let emitter = '0x';
+        if (emitterBase58 && emitterBase58 !== 'TBD') {
+            try {
+                emitter = (0, viem_1.bytesToHex)(new web3_js_1.PublicKey(emitterBase58).toBytes());
+            }
+            catch (_b) {
+                emitter = '0x';
+            }
+        }
+        const eventCoder = new anchor_1.BorshEventCoder(universalGatewayV0_json_1.default);
+        const matchingLogs = [];
+        // Walk logMessages for `Program data:` entries. Each matched event gets
+        // assigned an ordinal logIndex — its position among matching events.
+        // This is the deterministic integer the cosmos keeper is expected to use
+        // when it derives an inbound universalTxId for SVM sources.
+        let ordinal = 0;
+        for (const rawLog of logMessages) {
+            if (typeof rawLog !== 'string')
+                continue;
+            const prefix = 'Program data: ';
+            if (!rawLog.startsWith(prefix))
+                continue;
+            const base64Data = rawLog.slice(prefix.length).trim();
+            // Fast discriminator check — skip non-universal events without running
+            // the full Borsh decode.
+            let bytes;
+            try {
+                bytes = new Uint8Array(Buffer.from(base64Data, 'base64'));
+            }
+            catch (_c) {
+                continue;
+            }
+            const disc = (0, svm_events_1.discriminatorHex)(bytes);
+            const eventName = svm_events_1.SVM_EVENT_DISCRIMINATORS[disc];
+            if (!eventName)
+                continue;
+            // BorshEventCoder can throw when the on-chain layout drifts from the
+            // bundled IDL (seen with older UniversalTx emissions). Isolate the
+            // failure to this event so the rest of the matching logs still surface.
+            let decoded = null;
+            try {
+                decoded = eventCoder.decode(base64Data);
+            }
+            catch (e) {
+                notes.push(`svm: borsh decode threw for ${eventName}: ${e instanceof Error ? e.message : String(e)}`);
+                continue;
+            }
+            if (!decoded || decoded.name !== eventName) {
+                notes.push(`svm: discriminator matched ${eventName} but borsh decode failed`);
+                continue;
+            }
+            const args = normalizeSvmEventArgs(eventName, decoded.data);
+            matchingLogs.push({
+                eventName,
+                address: emitter,
+                logIndex: ordinal,
+                args,
+            });
+            ordinal += 1;
+        }
+        if (matchingLogs.length === 0) {
+            notes.push('svm tx has no decoded universal-tx events');
+            return emptyDetection(castHash, chain, notes);
+        }
+        const classified = (0, classify_1.classify)(matchingLogs);
+        notes.push(...classified.notes);
+        const decoded = Object.assign({}, classified.decoded);
+        // Inbound fallback for universalTxId: same formula the EVM branch uses,
+        // but the raw signature flows through untouched (no 0x-prefix rewrite,
+        // see deriveSvmChildUniversalTxId in child-inbounds.ts).
+        if (!decoded.universalTxId) {
+            const caip = chain;
+            if (INBOUND_KINDS.has(classified.kind) &&
+                classified.primaryLog &&
+                classified.primaryLog.logIndex >= 0) {
+                // Use the hex form (matches cosmos keeper's on-chain storage).
+                const hexSig = solanaSigToHex(rpcSig);
+                const input = `${caip}:${hexSig}:${classified.primaryLog.logIndex}`;
+                decoded.universalTxId = (0, viem_1.sha256)((0, viem_1.toBytes)(input));
+                notes.push(`universalTxId derived via sha256("${caip}:<hexSig>:${classified.primaryLog.logIndex}") — svm`);
+            }
+        }
+        const detections = (0, classify_1.classifyAll)(classified.matchingLogs);
+        return {
+            txHash: castHash,
+            chain,
+            kind: classified.kind,
+            emitters: classified.emitters,
+            decoded,
+            matchingLogs: classified.matchingLogs,
+            detections,
+            // SVM detector doesn't do the cosmos cross-reference itself; upstream
+            // (orchestrator / cascade) already does its own lookup when needed.
+            notes,
+        };
+    });
+}
+// ── Helpers ───────────────────────────────────────────────────────────
+function resolveConnection(chain, opts) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        if (opts.connection)
+            return opts.connection;
+        const info = chain_1.CHAIN_INFO[chain];
+        const rpcUrls = ((_a = opts.rpcUrls) === null || _a === void 0 ? void 0 : _a[chain]) && opts.rpcUrls[chain].length > 0
+            ? opts.rpcUrls[chain]
+            : ((_b = info === null || info === void 0 ? void 0 : info.defaultRPC) !== null && _b !== void 0 ? _b : []).filter((r) => r && r.length > 0);
+        if (rpcUrls.length === 0) {
+            throw new Error(`detectUniversalTxSvm: no RPC URL configured for ${chain}`);
+        }
+        // Lazy import to avoid a top-level dependency cycle through @solana/web3.js
+        // for consumers of the EVM-only path.
+        const { Connection } = yield Promise.resolve().then(() => tslib_1.__importStar(require('@solana/web3.js')));
+        return new Connection(rpcUrls[0], 'confirmed');
+    });
+}
+function emptyDetection(txHash, chain, notes) {
+    return {
+        txHash,
+        chain,
+        kind: 'UNKNOWN',
+        emitters: [],
+        decoded: {},
+        matchingLogs: [],
+        detections: [],
+        notes,
+    };
+}
+/**
+ * Convert an Anchor-decoded event struct into the shape classify.ts expects.
+ *
+ *  - snake_case → camelCase for known keys (subTxId, universalTxId, etc.)
+ *  - PublicKey → `0x${hex}` 32-byte string
+ *  - Buffer/Uint8Array fixed arrays → `0x${hex}`
+ *  - BN/bigint numerics → bigint
+ *  - Anchor enum objects for tx_type → numeric variant index
+ *  - Event-specific aliases (UniversalTxFinalized.payload → data,
+ *    RevertUniversalTx.revertRecipient → to) so downstream switch arms find
+ *    the expected keys.
+ */
+function normalizeSvmEventArgs(eventName, raw) {
+    var _a, _b;
+    const src = raw;
+    const out = {};
+    for (const [srcKey, value] of Object.entries(src)) {
+        const renamed = (_a = svm_events_1.SVM_FIELD_RENAMES[srcKey]) !== null && _a !== void 0 ? _a : srcKey;
+        out[renamed] = coerceArgValue(srcKey, renamed, value);
+    }
+    const aliases = (_b = svm_events_1.SVM_EVENT_FIELD_ALIASES[eventName]) !== null && _b !== void 0 ? _b : [];
+    for (const { from, to } of aliases) {
+        if (out[to] === undefined && out[from] !== undefined) {
+            out[to] = out[from];
+        }
+    }
+    return out;
+}
+function coerceArgValue(srcKey, renamedKey, value) {
+    var _a;
+    // Anchor returns PublicKey instances for `pubkey` types. Normalize to
+    // `0x${hex}` so asAddress() in classify.ts accepts them.
+    if (value && typeof value === 'object' && value instanceof web3_js_1.PublicKey) {
+        return (0, viem_1.bytesToHex)(value.toBytes());
+    }
+    // Fixed-size byte arrays (u8; N) come through as Buffer/Uint8Array.
+    if (value &&
+        typeof value === 'object' &&
+        (value instanceof Uint8Array ||
+            (globalThis.Buffer && value instanceof globalThis.Buffer))) {
+        return (0, viem_1.bytesToHex)(new Uint8Array(value));
+    }
+    // Some @coral-xyz/anchor versions return `array:[u8,N]` fields as plain
+    // number arrays rather than Buffers. Treat a homogeneous byte-array
+    // exactly like a Uint8Array here.
+    if (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((v) => typeof v === 'number' && v >= 0 && v <= 255)) {
+        return (0, viem_1.bytesToHex)(new Uint8Array(value));
+    }
+    // BN from anchor — has toString().
+    if (value && typeof value === 'object' && typeof value.toString === 'function') {
+        const proto = Object.getPrototypeOf(value);
+        const ctorName = (_a = proto === null || proto === void 0 ? void 0 : proto.constructor) === null || _a === void 0 ? void 0 : _a.name;
+        if (ctorName === 'BN') {
+            try {
+                return BigInt(value.toString(10));
+            }
+            catch (_b) {
+                return undefined;
+            }
+        }
+    }
+    // Anchor enum → { [variantName]: {} }. tx_type must be surfaced as a
+    // numeric index to match classify.ts's setTxType expectations.
+    if (renamedKey === 'txType' && value && typeof value === 'object' && !Array.isArray(value)) {
+        return extractTxTypeIndex(value);
+    }
+    return value;
+}
+/**
+ * Resolve a Borsh-decoded Anchor enum value into its numeric variant index.
+ *
+ * The SVM IDL `TxType` enum is declared in the same order as the EVM solidity
+ * enum (GAS, GAS_AND_PAYLOAD, FUNDS, FUNDS_AND_PAYLOAD, RESCUE_FUNDS), so a
+ * positional lookup suffices.
+ */
+const TX_TYPE_ORDER = [
+    'gas',
+    'gasAndPayload',
+    'funds',
+    'fundsAndPayload',
+    'rescueFunds',
+];
+function extractTxTypeIndex(v) {
+    const key = Object.keys(v)[0];
+    if (!key)
+        return undefined;
+    const norm = key.toLowerCase();
+    const i = TX_TYPE_ORDER.findIndex((k) => k.toLowerCase() === norm);
+    return i < 0 ? undefined : i;
+}
+/**
+ * Accept either a base58 Solana signature (native form) or a 0x-prefixed
+ * 128-char hex of the 64-byte signature bytes (the form used by cosmos
+ * keeper storage and by the cascade walker when it hands off an
+ * `observedTx.txHash`). Return the base58 form the RPC expects.
+ */
+function normalizeSolanaSignature(input) {
+    if (input.startsWith('0x') && input.length === 2 + 128) {
+        return bs58_1.bs58.encode((0, viem_1.hexToBytes)(input));
+    }
+    return input;
+}
+function solanaSigToHex(base58Sig) {
+    return (0, viem_1.bytesToHex)(bs58_1.bs58.decode(base58Sig));
+}
+exports.__svmInternal = {
+    normalizeSvmEventArgs,
+    extractTxTypeIndex,
+    normalizeSolanaSignature,
+    solanaSigToHex,
+};
+//# sourceMappingURL=detector-svm.js.map

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

@@ -0,0 +1,13 @@
+import { CHAIN } from '../constants/enums';
+import { computeUniversalTxId } from '../orchestrator/internals/outbound-tracker';
+import type { DetectUniversalTxOptions, UniversalTxDetection } from './types';
+export declare function detectUniversalTx(txHash: `0x${string}`, chain: CHAIN, opts?: DetectUniversalTxOptions): Promise<UniversalTxDetection>;
+export declare const __internalStatusNames: Record<number, string>;
+/**
+ * Re-export the push-side legacy helper (keccak-based; retained for
+ * backwards-compat with orchestrator paths that already use it). For accurate
+ * universalTxId derivation matching the chain module, use
+ * {@link deriveChildUniversalTxId} or {@link derivePcUniversalTxId} from
+ * child-inbounds.ts.
+ */
+export { computeUniversalTxId };