@pushchain/core 6.0.19 → 6.0.21

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

@@ -2,7 +2,6 @@
 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-
@@ -43,112 +42,107 @@ 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, 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}`);
-        }
-        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);
+async function detectUniversalTx(txHash, chain, opts = {}) {
+    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, normalize_1.normalizeDetectionForUser)(await (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 = opts.rpcUrls?.[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 = await 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) => ({
+        eventName: p.eventName,
+        address: p.address,
+        logIndex: typeof p.logIndex ===
+            'bigint'
+            ? Number(p.logIndex)
+            : p.logIndex ?? -1,
+        args: (p.args ??
+            {}),
+    }));
+    const classified = (0, classify_1.classify)(matchingLogs);
+    notes.push(...classified.notes);
+    const decoded = { ...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 (decoded.universalTxId && !opts.pushClient) {
-            notes.push('push cross-reference skipped (no pushClient provided)');
+        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`);
         }
-        const detections = (0, classify_1.classifyAll)(classified.matchingLogs);
-        // 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,
-            emitters: classified.emitters,
-            decoded,
-            matchingLogs: classified.matchingLogs,
-            detections,
-            pushChainTx,
-            notes,
-        });
+    }
+    // Optional cosmos cross-reference.
+    let pushChainTx;
+    if (opts.pushClient &&
+        !opts.skipPushChainLookup &&
+        decoded.universalTxId) {
+        pushChainTx = await 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);
+    // 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,
+        emitters: classified.emitters,
+        decoded,
+        matchingLogs: classified.matchingLogs,
+        detections,
+        pushChainTx,
+        notes,
     });
 }
 // ── Helpers ───────────────────────────────────────────────────────────
@@ -164,62 +158,56 @@ function emptyDetection(txHash, chain, notes) {
         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';
-            }
+async function crossReferencePushChain(pushClient, universalTxId, kind, notes) {
+    const id = universalTxId.startsWith('0x')
+        ? universalTxId.slice(2)
+        : universalTxId;
+    try {
+        const resp = await pushClient.getUniversalTxByIdV2(id);
+        const utx = resp?.universalTx;
+        if (!utx || !utx.id) {
             return {
                 id,
-                status,
-                statusName,
-                pcTxHashes,
-                outboundHashes,
-                stuckObservation,
+                status: 0,
+                statusName: UNIVERSAL_TX_STATUS_NAMES[0],
+                pcTxHashes: [],
+                outboundHashes: [],
+                notFound: true,
             };
         }
-        catch (err) {
-            notes.push(`push cross-reference failed: ${err instanceof Error ? err.message : String(err)}`);
-            return undefined;
+        const status = (utx.universalStatus ?? 0);
+        const statusName = UNIVERSAL_TX_STATUS_NAMES[status] ?? `UNKNOWN(${status})`;
+        const pcTxHashes = (utx.pcTx ?? [])
+            .map((p) => p?.txHash)
+            .filter((h) => Boolean(h));
+        const outboundHashes = (utx.outboundTx ?? []).map((ob) => ({
+            subTxId: ob.id ?? '',
+            status: outboundStatusName(ob.outboundStatus),
+            destinationChain: ob.destinationChain ?? '',
+            externalTxHash: ob.observedTx?.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) {
@@ -232,7 +220,7 @@ function outboundStatusName(n) {
         case 3:
             return 'REVERTED';
         default:
-            return `UNKNOWN(${n !== null && n !== void 0 ? n : '?'})`;
+            return `UNKNOWN(${n ?? '?'})`;
     }
 }
 exports.__internalStatusNames = UNIVERSAL_TX_STATUS_NAMES;

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

@@ -35,10 +35,10 @@ 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);
+    const next = (0, external_tx_hash_1.toExternalTxHashDisplay)(chain ?? undefined, s.externalTxHash);
     if (next === s.externalTxHash)
         return s;
-    return Object.assign(Object.assign({}, s), { externalTxHash: next });
+    return { ...s, externalTxHash: next };
 }
 /**
  * Normalize the outbound summaries inside `PushChainCrossRef.outboundHashes`.
@@ -56,7 +56,7 @@ function normalizeCrossRefForUser(x) {
     });
     if (!changed)
         return x;
-    return Object.assign(Object.assign({}, x), { outboundHashes: next });
+    return { ...x, outboundHashes: next };
 }
 /**
  * Normalize the outbound summaries embedded in `detection.pushChainTx`.
@@ -68,7 +68,7 @@ function normalizeDetectionForUser(d) {
     const nextPushChainTx = normalizeCrossRefForUser(d.pushChainTx);
     if (nextPushChainTx === d.pushChainTx)
         return d;
-    return Object.assign(Object.assign({}, d), { pushChainTx: nextPushChainTx });
+    return { ...d, pushChainTx: nextPushChainTx };
 }
 /**
  * Normalize the outbound summaries inside a `ChildInboundResolution`.
@@ -86,7 +86,7 @@ function normalizeChildInboundResolutionForUser(r) {
     });
     if (!changed)
         return r;
-    return Object.assign(Object.assign({}, r), { outboundHashes: next });
+    return { ...r, outboundHashes: next };
 }
 /**
  * Type guard: identifies a `CascadeEdge.relation` as a
@@ -118,10 +118,10 @@ function normalizeCascadeNodeForUser(n) {
         if (nextRelation === edge.relation && nextNode === edge.node)
             return edge;
         childrenChanged = true;
-        return Object.assign(Object.assign({}, edge), { relation: nextRelation, node: nextNode });
+        return { ...edge, relation: nextRelation, node: nextNode };
     });
     if (!childrenChanged)
         return n;
-    return Object.assign(Object.assign({}, n), { detection: nextDetection, children: nextChildren });
+    return { ...n, detection: nextDetection, children: nextChildren };
 }
 //# sourceMappingURL=normalize.js.map

package/src/lib/utils/external-tx-hash.js

@@ -33,10 +33,9 @@ const bs58_1 = require("../internal/bs58");
  * 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)
+    if (!chain || chain_1.CHAIN_INFO[chain]?.vm !== enums_1.VM.SVM)
         return rawTxHash;
     if (!rawTxHash.startsWith('0x'))
         return rawTxHash;

package/src/lib/utils.d.ts

@@ -3,6 +3,7 @@ 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 type { PC20AddressResult } from './orchestrator/orchestrator.types';
 import type { Idl } from '@coral-xyz/anchor';
 import { registerIdl as registerSvmIdl, getRegisteredIdls as getRegisteredSvmIdls } from './orchestrator/svm-idl/registry';
 /**
@@ -285,6 +286,49 @@ export declare class Utils {
             decimals: number;
             network: PUSH_NETWORK;
         };
+        /**
+         * Resolve a PC20 token against UniversalCore's on-chain registry, and list
+         * every confirmed address it has across chains.
+         *
+         * Accepts either end of the mapping — an external wrapper or the canonical
+         * Push-native token — and always returns the canonical token at `address`,
+         * with every known deployment in `registry`.
+         *
+         * Unlike `getPRC20Address`, this is **asynchronous**: PC20 mappings are
+         * dynamic and live on chain, so there is no static table to consult. It is
+         * never symbol-based — identity is address-and-chain only.
+         *
+         * `chain` is optional. When omitted, the SDK works out which chain the
+         * address belongs to. Note the deliberate asymmetry with the transaction
+         * path: `funds.token` still *requires* `chain`, and sending with one that
+         * disagrees with where the funds actually are is rejected before any
+         * approval. Lookup is lenient; spending is not.
+         *
+         * @example
+         * ```ts
+         * const token = await PushChain.utils.tokens.getPC20Address('0xWrapper', {
+         *   chain: CONSTANTS.CHAIN.ETHEREUM_SEPOLIA, // optional
+         *   network: CONSTANTS.PUSH_NETWORK.TESTNET_DONUT,
+         * });
+         *
+         * token.address   // '0x…' canonical Push-native PC20
+         * token.registry  // [{ address, chain, chainName }, …]
+         * ```
+         *
+         * @throws {PC20WrapperNotRegisteredError} the address is unknown to the registry
+         * @throws {PC20RegistryMismatchError} forward/reverse registry disagreement
+         * @throws {PC20ExpectedButPRC20Error} a synthetic PRC20 was supplied
+         * @throws {PC20AmbiguousAddressError} `chain` omitted and several chains
+         *   claim the address with different Push sources
+         */
+        getPC20Address(address: string, options: {
+            network: PUSH_NETWORK;
+            /** Where the address lives. Omit to have the SDK work it out. */
+            chain?: CHAIN;
+            rpcUrls?: Partial<Record<CHAIN, string[]>>;
+            /** Also run live factory-identity checks. Slower; off by default. */
+            strict?: boolean;
+        }): Promise<PC20AddressResult>;
     };
     /**
      * Internal: resolves a CHAIN enum from either a CHAIN value or a PushChain client instance.