@pushchain/core 6.0.13 → 6.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushchain/core",
-  "version": "6.0.13",
+  "version": "6.0.15",
   "homepage": "https://push.org",
   "keywords": [
     "pushchain",

package/src/lib/orchestrator/internals/response-builder.d.ts

@@ -4,7 +4,9 @@
  * Contains: queryUniversalTxStatusFromGatewayTx, trackTransaction,
  * transformToUniversalTxResponse, and the ResponseBuilderCallbacks interface.
  */
+import { CHAIN } from '../../constants/enums';
 import { UniversalTx } from '../../generated/uexecutor/v1/types';
+import type { UniversalTxV2 } from '../../generated/uexecutor/v2/types';
 import { ProgressEvent } from '../../progress-hook/progress-hook.types';
 import { EvmClient } from '../../vm-client/evm-client';
 import type { TxResponse } from '../../vm-client/vm-client.types';
@@ -27,5 +29,22 @@ export interface ResponseBuilderCallbacks {
     };
 }
 export declare function queryUniversalTxStatusFromGatewayTx(ctx: OrchestratorContext, evmClient: EvmClient | undefined, gatewayAddress: `0x${string}` | undefined, txHash: string, evmGatewayMethod: 'sendFunds' | 'sendTxWithFunds' | 'sendTxWithGas'): Promise<UniversalTx | undefined>;
+/**
+ * Source-hash resolution for trackTransaction.
+ *
+ * When the caller tracks by an ORIGIN/source-leg hash (a Sepolia tx hash, a
+ * Solana signature, …) instead of the Push Chain root hash, the universal
+ * record can't be fetched by that hash: `PushClient` is EVM-only (so it can't
+ * even read a Solana tx), and external-inbound records are keyed by a derived
+ * `universalTxId`, not by the source hash. Delegate to the universal-tx
+ * detector (which dispatches EVM/SVM) to derive the `universalTxId`, then load
+ * the universal record and its first Push pcTx so the caller can reconstruct
+ * from the Push side.
+ */
+export declare function resolveUniversalTxFromSourceHash(ctx: OrchestratorContext, sourceHash: string, sourceChain: CHAIN, rpcUrls: Partial<Record<CHAIN, string[]>>): Promise<{
+    universalTxData: UniversalTxV2;
+    pushTxHash: string;
+    sourceSender?: string;
+}>;
 export declare function trackTransaction(ctx: OrchestratorContext, txHash: string, options?: TrackTransactionOptions, callbacks?: ResponseBuilderCallbacks): Promise<UniversalTxResponse>;
 export declare function transformToUniversalTxResponse(ctx: OrchestratorContext, tx: TxResponse, eventBuffer: ProgressEvent[] | undefined, callbacks: ResponseBuilderCallbacks): Promise<UniversalTxResponse>;

package/src/lib/orchestrator/internals/response-builder.js

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.queryUniversalTxStatusFromGatewayTx = queryUniversalTxStatusFromGatewayTx;
+exports.resolveUniversalTxFromSourceHash = resolveUniversalTxFromSourceHash;
 exports.trackTransaction = trackTransaction;
 exports.transformToUniversalTxResponse = transformToUniversalTxResponse;
 const tslib_1 = require("tslib");
@@ -27,6 +28,7 @@ const svm_helpers_1 = require("./svm-helpers");
 const outbound_tracker_1 = require("./outbound-tracker");
 const inbound_tracker_1 = require("./inbound-tracker");
 const tx_transformer_1 = require("./tx-transformer");
+const detector_1 = require("../../universal-tx-detector/detector");
 const progress_route_hooks_1 = require("./progress-route-hooks");
 const outbound_sync_1 = require("./outbound-sync");
 /**
@@ -162,6 +164,56 @@ txHash, evmGatewayMethod) {
 // ============================================================================
 // trackTransaction
 // ============================================================================
+/** Push Chain CHAIN ids — tracking these uses the Push-native path. */
+const PUSH_CHAINS = new Set([
+    enums_1.CHAIN.PUSH_MAINNET,
+    enums_1.CHAIN.PUSH_TESTNET_DONUT,
+    enums_1.CHAIN.PUSH_LOCALNET,
+]);
+/**
+ * Source-hash resolution for trackTransaction.
+ *
+ * When the caller tracks by an ORIGIN/source-leg hash (a Sepolia tx hash, a
+ * Solana signature, …) instead of the Push Chain root hash, the universal
+ * record can't be fetched by that hash: `PushClient` is EVM-only (so it can't
+ * even read a Solana tx), and external-inbound records are keyed by a derived
+ * `universalTxId`, not by the source hash. Delegate to the universal-tx
+ * detector (which dispatches EVM/SVM) to derive the `universalTxId`, then load
+ * the universal record and its first Push pcTx so the caller can reconstruct
+ * from the Push side.
+ */
+function resolveUniversalTxFromSourceHash(ctx, sourceHash, sourceChain, rpcUrls) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const detection = yield (0, detector_1.detectUniversalTx)(sourceHash, sourceChain, {
+            pushClient: ctx.pushClient,
+            rpcUrls: Object.assign(Object.assign({}, ctx.rpcUrls), rpcUrls),
+            // We do our own getUniversalTxByIdV2 below; the detector's cosmos
+            // cross-ref can come back empty for SVM even when the record exists.
+            skipPushChainLookup: true,
+        });
+        const utxId = detection.decoded.universalTxId;
+        if (!utxId) {
+            throw new Error(`trackTransaction: could not resolve a universal transaction from hash ` +
+                `"${sourceHash}" on ${sourceChain} (detected kind: ${detection.kind}). ` +
+                `Pass the Push Chain root hash, or a source hash that emitted a ` +
+                `UniversalTx event.`);
+        }
+        const utxResponse = yield ctx.pushClient.getUniversalTxByIdV2(utxId);
+        const universalTxData = utxResponse === null || utxResponse === void 0 ? void 0 : utxResponse.universalTx;
+        if (!universalTxData) {
+            throw new Error(`trackTransaction: resolved universalTxId ${utxId} from ${sourceChain} ` +
+                `hash "${sourceHash}", but no universal transaction record exists on ` +
+                `Push Chain yet (it may still be relaying).`);
+        }
+        const pushTxHash = (_b = (_a = universalTxData.pcTx) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.txHash;
+        if (!pushTxHash) {
+            throw new Error(`trackTransaction: universal tx ${utxId} (from ${sourceChain} hash ` +
+                `"${sourceHash}") has no Push Chain tx recorded yet.`);
+        }
+        return { universalTxData, pushTxHash, sourceSender: detection.decoded.sender };
+    });
+}
 function trackTransaction(ctx, txHash, options, callbacks) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
         var _a, _b;
@@ -169,7 +221,33 @@ function trackTransaction(ctx, txHash, options, callbacks) {
             throw new Error('trackTransaction requires ResponseBuilderCallbacks');
         }
         const { chain = (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork), progressHook, waitForCompletion = true, advanced = {}, } = options !== null && options !== void 0 ? options : {};
+        // Fail fast on an unsupported `chain`. It defaults to Push Chain when the
+        // caller omits it; an explicitly-passed value that isn't a known CHAIN_INFO
+        // entry (a raw numeric chainId, a typo, or a chain from a plain-JS caller
+        // that skips the CHAIN type) would otherwise throw an opaque "Cannot read
+        // properties of undefined (reading 'defaultRPC')" at the RPC lookup below.
+        if (!chain_1.CHAIN_INFO[chain]) {
+            throw new Error(`trackTransaction: unsupported chain "${String(chain)}". Pass a ` +
+                `PushChain.CONSTANTS.CHAIN value. Supported: ${Object.keys(chain_1.CHAIN_INFO).join(', ')}`);
+        }
         const { timeout = 300000, pollingIntervalMs = 1000, rpcUrls = {} } = advanced;
+        // Source-hash mode: a non-Push `chain` means `txHash` is an origin/source-leg
+        // hash (a Sepolia tx hash, a Solana signature, …), not a Push Chain hash.
+        // Resolve it to the universal record + its Push pcTx via the detector, then
+        // reconstruct from the Push side. Push-native tracking (below) is unchanged.
+        let preResolvedUtxData;
+        let sourceOriginChain;
+        let sourceSender;
+        let trackChain = chain;
+        let trackHash = txHash;
+        if (!PUSH_CHAINS.has(chain)) {
+            const resolved = yield resolveUniversalTxFromSourceHash(ctx, txHash, chain, rpcUrls);
+            preResolvedUtxData = resolved.universalTxData;
+            sourceOriginChain = chain;
+            sourceSender = resolved.sourceSender;
+            trackHash = resolved.pushTxHash;
+            trackChain = (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork);
+        }
         // Event buffer for replay via response.progressHook()
         const eventBuffer = [];
         // Helper to emit progress events. Per-tx hook (passed to trackTransaction)
@@ -180,8 +258,11 @@ function trackTransaction(ctx, txHash, options, callbacks) {
             (0, context_1.printLog)(ctx, event.message);
             fanOut(event, progressHook, ctx.progressHook);
         };
-        // Create client for target chain with optional RPC override
-        const chainRPCs = rpcUrls[chain] || ctx.rpcUrls[chain] || chain_1.CHAIN_INFO[chain].defaultRPC;
+        // Create client for target chain with optional RPC override. In source-hash
+        // mode `trackChain` is Push (the resolved pcTx lives on Push Chain).
+        const chainRPCs = rpcUrls[trackChain] ||
+            ctx.rpcUrls[trackChain] ||
+            chain_1.CHAIN_INFO[trackChain].defaultRPC;
         const client = new push_client_1.PushClient({
             rpcUrls: chainRPCs,
             network: ctx.pushNetwork,
@@ -192,37 +273,39 @@ function trackTransaction(ctx, txHash, options, callbacks) {
         // eslint-disable-next-line no-constant-condition
         while (true) {
             try {
-                tx = yield client.getTransaction(txHash);
+                tx = yield client.getTransaction(trackHash);
                 break; // Found transaction
             }
             catch (err) {
                 if (!waitForCompletion) {
-                    throw new Error(`Transaction ${txHash} not found`);
+                    throw new Error(`Transaction ${trackHash} not found`);
                 }
                 // Check timeout
                 if (Date.now() - start > timeout) {
-                    throw new Error(`Timeout: transaction ${txHash} not confirmed within ${timeout}ms`);
+                    throw new Error(`Timeout: transaction ${trackHash} not confirmed within ${timeout}ms`);
                 }
                 // Brief delay before retry
                 yield new Promise((r) => setTimeout(r, pollingIntervalMs));
             }
         }
-        // Try to get UniversalTx data for richer progress reconstruction
-        // (may not exist for direct Push Chain transactions)
-        // Three-tier lookup: direct hash → computed keccak ID → Cosmos event extraction
-        let universalTxData;
-        try {
-            const utxResponse = yield ctx.pushClient.getUniversalTxByIdV2(txHash);
-            if (utxResponse === null || utxResponse === void 0 ? void 0 : utxResponse.universalTx) {
-                universalTxData = utxResponse.universalTx;
+        // Try to get UniversalTx data for richer progress reconstruction.
+        // In source-hash mode we already resolved the record above; otherwise run the
+        // three-tier lookup: direct hash → computed keccak ID → Cosmos extraction.
+        let universalTxData = preResolvedUtxData;
+        if (!universalTxData) {
+            try {
+                const utxResponse = yield ctx.pushClient.getUniversalTxByIdV2(trackHash);
+                if (utxResponse === null || utxResponse === void 0 ? void 0 : utxResponse.universalTx) {
+                    universalTxData = utxResponse.universalTx;
+                }
+            }
+            catch (_c) {
+                // Ignore - try computed ID next
             }
-        }
-        catch (_c) {
-            // Ignore - try computed ID next
         }
         if (!universalTxData) {
             try {
-                const computedId = (0, outbound_tracker_1.computeUniversalTxId)(ctx.pushNetwork, txHash);
+                const computedId = (0, outbound_tracker_1.computeUniversalTxId)(ctx.pushNetwork, trackHash);
                 const queryId = computedId.startsWith('0x') ? computedId.slice(2) : computedId;
                 const utxResponse = yield ctx.pushClient.getUniversalTxByIdV2(queryId);
                 if (utxResponse === null || utxResponse === void 0 ? void 0 : utxResponse.universalTx) {
@@ -235,7 +318,7 @@ function trackTransaction(ctx, txHash, options, callbacks) {
         }
         if (!universalTxData) {
             try {
-                const extractedId = yield (0, outbound_tracker_1.extractUniversalSubTxIdFromTx)(ctx, txHash);
+                const extractedId = yield (0, outbound_tracker_1.extractUniversalSubTxIdFromTx)(ctx, trackHash);
                 if (extractedId) {
                     const queryId = extractedId.startsWith('0x') ? extractedId.slice(2) : extractedId;
                     const utxResponse = yield ctx.pushClient.getUniversalTxByIdV2(queryId);
@@ -279,6 +362,33 @@ function trackTransaction(ctx, txHash, options, callbacks) {
                 universalTxResponse._expectsInboundRoundTrip = true;
             }
         }
+        // Source-hash mode: the pcTx we fetched lives on Push Chain, so the
+        // transform resolves chain to the Push side. Surface the true source chain
+        // the caller tracked so `chain`/`chainNamespace` reflect where the universal
+        // tx actually originated. (An outbound-derived chain above, if any, wins.)
+        if (sourceOriginChain && !universalTxResponse.chain) {
+            universalTxResponse.chain = sourceOriginChain;
+            universalTxResponse.chainNamespace = sourceOriginChain;
+        }
+        // Override `origin` with the true source account. The transform derives
+        // origin from the Push pcTx (whose `from` is the keeper that submitted the
+        // inbound), so in source-hash mode it would otherwise read as a Push
+        // address. Rebuild it as `<sourceChainCaip>:<sourceSender>` using the
+        // chain's native address encoding (0x for EVM, base58 for SVM).
+        if (sourceOriginChain && sourceSender) {
+            let originAddr = sourceSender;
+            try {
+                originAddr =
+                    chain_1.CHAIN_INFO[sourceOriginChain].vm === enums_1.VM.SVM
+                        ? bs58_1.bs58.encode((0, viem_1.toBytes)(sourceSender))
+                        : (0, viem_1.getAddress)(sourceSender);
+            }
+            catch (_f) {
+                // Keep the raw sender if re-encoding fails.
+            }
+            universalTxResponse.origin = `${sourceOriginChain}:${originAddr}`;
+            universalTxResponse.chainId = chain_1.CHAIN_INFO[sourceOriginChain].chainId;
+        }
         // Reconstruct and emit SEND-TX-* progress events
         const reconstructedEvents = (0, tx_transformer_1.reconstructProgressEvents)(universalTxResponse, universalTxData);
         for (const event of reconstructedEvents) {
@@ -499,6 +609,7 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
         const universalTxResponse = {
             // 1. Identity
             hash: tx.hash,
+            finalTxHash: tx.hash, // Push tx hash; .wait()'s receipt refines it for R2/R3
             origin,
             // 2. Block Info
             blockNumber: tx.blockNumber || BigInt(0),
@@ -520,7 +631,7 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
             accessList: Array.isArray(tx.accessList) ? [...tx.accessList] : [],
             // 6. Utilities
             wait: (waitOptions) => tslib_1.__awaiter(this, void 0, void 0, function* () {
-                var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
                 // For trackTransaction replays the tx is historical — cosmos already
                 // has the full graph indexed, so the 20s/30s initial-wait buffers
                 // designed for live sends are pure deadweight. Default them to 0 when
@@ -662,6 +773,10 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                         callbacks.printLog(`[wait] External chain tracking ${isTimeout ? 'timed out' : 'failed'}: ${errMsg}`);
                     }
                 }
+                // Resolve the terminal hash for the whole journey: inbound (R3) >
+                // external outbound (R2) > the Push tx itself (R1). Single-tx analogue
+                // of CascadeCompletionResult.finalTxHash.
+                baseReceipt = Object.assign(Object.assign({}, baseReceipt), { finalTxHash: (_l = (_k = baseReceipt.pushInboundTxHash) !== null && _k !== void 0 ? _k : baseReceipt.externalTxHash) !== null && _l !== void 0 ? _l : baseReceipt.hash });
                 return baseReceipt;
             }),
             // Internal: register a wait-phase progressHook without replaying

package/src/lib/orchestrator/internals/tx-transformer.js

@@ -41,6 +41,9 @@ function transformToUniversalTxReceipt(receipt, originalTxResponse) {
             from: originalTxResponse.from,
             to: originalTxResponse.to,
         },
+        // Terminal-hash baseline = this Push tx. `wait()` upgrades it to the
+        // external/inbound leg for R2/R3 (see UniversalTxReceipt.finalTxHash).
+        finalTxHash: receipt.transactionHash,
     };
 }
 // ============================================================================

package/src/lib/orchestrator/orchestrator.d.ts

@@ -118,9 +118,14 @@ export declare class Orchestrator {
      * Tracks a transaction by hash on Push Chain and returns UniversalTxResponse.
      * Reconstructs and replays SEND-TX-* progress events for completed transactions.
      *
-     * @param txHash - Transaction hash to track (Push Chain tx hash)
+     * @param txHash - Transaction hash to track. A Push Chain root hash by
+     *   default; when `options.chain` is a non-Push chain, an origin/source-leg
+     *   hash (a source EVM tx hash or a Solana signature) that is resolved to the
+     *   universal transaction via the universal-tx detector.
      * @param options - Tracking options (chain, progressHook, waitForCompletion, advanced config)
      * @returns Promise resolving to UniversalTxResponse with wait() and progressHook() methods
+     * @throws If `options.chain` is provided but is not a supported chain (not present in CHAIN_INFO)
+     * @throws If a source-leg hash cannot be resolved to a universal transaction on Push Chain
      */
     trackTransaction(txHash: string, options?: import('./orchestrator.types').TrackTransactionOptions): Promise<UniversalTxResponse>;
     /**

package/src/lib/orchestrator/orchestrator.js

@@ -401,9 +401,14 @@ class Orchestrator {
      * Tracks a transaction by hash on Push Chain and returns UniversalTxResponse.
      * Reconstructs and replays SEND-TX-* progress events for completed transactions.
      *
-     * @param txHash - Transaction hash to track (Push Chain tx hash)
+     * @param txHash - Transaction hash to track. A Push Chain root hash by
+     *   default; when `options.chain` is a non-Push chain, an origin/source-leg
+     *   hash (a source EVM tx hash or a Solana signature) that is resolved to the
+     *   universal transaction via the universal-tx detector.
      * @param options - Tracking options (chain, progressHook, waitForCompletion, advanced config)
      * @returns Promise resolving to UniversalTxResponse with wait() and progressHook() methods
+     * @throws If `options.chain` is provided but is not a supported chain (not present in CHAIN_INFO)
+     * @throws If a source-leg hash cannot be resolved to a universal transaction on Push Chain
      */
     trackTransaction(txHash, options) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {

package/src/lib/orchestrator/orchestrator.types.d.ts

@@ -159,6 +159,15 @@ export type ExecuteParams = {
  */
 export interface UniversalTxResponse {
     hash: string;
+    /**
+     * Terminal tx hash for this transaction. On the RESPONSE (returned by
+     * sendTransaction/prepareTransaction, before any cross-chain leg lands) this
+     * equals `hash` — the Push Chain tx. After `.wait()`, the receipt's
+     * `finalTxHash` resolves to the external/inbound leg for R2/R3
+     * (`pushInboundTxHash ?? externalTxHash ?? hash`). Provided so callers can
+     * read one terminal hash off either the response or the receipt.
+     */
+    finalTxHash?: string;
     origin: string;
     blockNumber: bigint;
     blockHash: string;
@@ -336,6 +345,21 @@ export interface UniversalTxReceipt {
     pushInboundTxHash?: string;
     /** Child UTX id that owns the inbound execution. */
     pushInboundUtxId?: string;
+    /**
+     * The terminal on-chain tx hash for this transaction's journey — one "where
+     * did it ultimately land" hash, so callers don't have to branch on route:
+     *   - R1 (UOA_TO_PUSH): the Push Chain tx          → `hash`
+     *   - R2 (UOA_TO_CEA):  the external outbound tx    → `externalTxHash`
+     *   - R3 (CEA_TO_PUSH): the inbound Push tx that closed the round-trip
+     *                       → `pushInboundTxHash` (falls back to `externalTxHash`)
+     *
+     * Resolved as `pushInboundTxHash ?? externalTxHash ?? hash`. This is the
+     * single-transaction analogue of `CascadeCompletionResult.finalTxHash`,
+     * which points at the last confirmed hop of an `executeTransactions`
+     * cascade. The leg-specific fields above stay available when you need to
+     * distinguish the outbound vs inbound leg explicitly.
+     */
+    finalTxHash?: string;
 }
 /**
  * Signature interface modeled after ethers.js v6 Signature interface
@@ -724,7 +748,16 @@ export interface CascadeCompletionResult {
 }
 export interface TrackTransactionOptions {
     /**
-     * Target chain to track transaction on. Defaults to Push Chain based on client network.
+     * Chain the `txHash` belongs to. Defaults to Push Chain based on the client
+     * network — pass the Push Chain root hash in that case.
+     *
+     * Pass a NON-Push chain (e.g. `CHAIN.ETHEREUM_SEPOLIA`, `CHAIN.SOLANA_DEVNET`)
+     * to track by an ORIGIN/source-leg hash — a source EVM tx hash or a Solana
+     * signature. The universal transaction is resolved from the source hash via
+     * the universal-tx detector and reconstructed from the Push side.
+     *
+     * Must be a supported chain (present in CHAIN_INFO); `trackTransaction`
+     * throws on an unsupported value.
      */
     chain?: import('../constants/enums').CHAIN;
     /**

package/src/lib/progress-hook/progress-hook.js

@@ -328,7 +328,7 @@ const RAW_HOOKS_R2 = {
     }),
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_02]: (ueaAddr, ceaAddr, targetChain, deployed) => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_02,
-        title: `${friendlyChain(targetChain)} Execution Account Ready`,
+        title: `${friendlyChain(targetChain)} Execution Account Resolved`,
         message: `UEA: ${ueaAddr}. CEA: ${ceaAddr} on ${targetChain}. Deployed: ${deployed}`,
         response: { uea: ueaAddr, cea: ceaAddr, chain: targetChain, deployed },
         level: 'SUCCESS',