@pushchain/core 5.1.5-alpha.0 → 5.1.5-alpha.1

package/package.json

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

package/src/lib/orchestrator/internals/cascade.js

@@ -28,6 +28,8 @@ const uea_manager_1 = require("./uea-manager");
 const gas_calculator_1 = require("./gas-calculator");
 const route_handlers_1 = require("./route-handlers");
 const build_payload_1 = require("../svm-idl/build-payload");
+const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
+const progress_hook_1 = tslib_1.__importDefault(require("../../progress-hook/progress-hook"));
 // ============================================================================
 // prepareTransaction
 // ============================================================================
@@ -775,8 +777,8 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                 hops: hopInfos,
                 hopCount: hops.length,
                 waitForAll: (opts) => tslib_1.__awaiter(this, void 0, void 0, function* () {
-                    var _a;
-                    const { pollingIntervalMs = 10000, timeout = 300000, progressHook: cascadeProgressHook, } = opts || {};
+                    var _a, _b;
+                    const { pollingIntervalMs = 10000, timeout = 300000, progressHook: cascadeProgressHook, eventHook, } = opts || {};
                     const startTime = Date.now();
                     try {
                         // 1. Wait for initial Push Chain tx confirmation
@@ -841,12 +843,14 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                         status: 'timeout',
                                         elapsed: Date.now() - startTime,
                                     });
+                                    eventHook === null || eventHook === void 0 ? void 0 : eventHook(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_04](Date.now() - startTime));
                                     return {
                                         success: false,
                                         hops: hopInfos,
                                         failedAt: hop.hopIndex,
                                     };
                                 }
+                                eventHook === null || eventHook === void 0 ? void 0 : eventHook(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_08_01](hop.executionChain));
                                 cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                     hopIndex: hop.hopIndex,
                                     route: hop.route,
@@ -854,6 +858,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                     status: 'polling',
                                     elapsed: Date.now() - startTime,
                                 });
+                                let lastEmittedStatus;
                                 try {
                                     const outboundDetails = yield callbacks.waitForOutboundTxFn(response.hash, {
                                         initialWaitMs: Math.min(60000, remainingTimeout),
@@ -867,11 +872,17 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                                 status: event.status,
                                                 elapsed: Date.now() - startTime,
                                             });
+                                            if (event.status === 'polling' &&
+                                                lastEmittedStatus !== 'polling') {
+                                                lastEmittedStatus = 'polling';
+                                                eventHook === null || eventHook === void 0 ? void 0 : eventHook(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_08_02](event.elapsed));
+                                            }
                                         },
                                     });
                                     hop.status = 'confirmed';
                                     hop.txHash = outboundDetails.externalTxHash;
                                     hop.outboundDetails = outboundDetails;
+                                    eventHook === null || eventHook === void 0 ? void 0 : eventHook(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_03](outboundDetails));
                                     cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                         hopIndex: hop.hopIndex,
                                         route: hop.route,
@@ -882,6 +893,11 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                     });
                                 }
                                 catch (err) {
+                                    const errMsg = err instanceof Error ? err.message : String(err);
+                                    const isTimeout = errMsg.startsWith('Timeout waiting for outbound transaction');
+                                    eventHook === null || eventHook === void 0 ? void 0 : eventHook(isTimeout
+                                        ? progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_04](remainingTimeout)
+                                        : progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_05](errMsg));
                                     hop.status = 'failed';
                                     cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                         hopIndex: hop.hopIndex,
@@ -899,6 +915,13 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                             }
                             else {
                                 // Multiple outbound hops: use V2 API which returns outboundTx[]
+                                // Emit "Awaiting External Chain" once per outbound hop before
+                                // polling begins.
+                                for (const outHop of outboundHops) {
+                                    eventHook === null || eventHook === void 0 ? void 0 : eventHook(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_08_01](outHop.executionChain));
+                                }
+                                const perHopLastStatus = new Map();
+                                const confirmedHops = new Set();
                                 const allOutboundDetails = yield callbacks.waitForAllOutboundTxsFn(response.hash, outboundHops, {
                                     initialWaitMs: Math.min(60000, timeout - (Date.now() - startTime)),
                                     pollingIntervalMs,
@@ -912,13 +935,39 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                             txHash: event.txHash,
                                             elapsed: Date.now() - startTime,
                                         });
+                                        const prev = perHopLastStatus.get(event.hopIndex);
+                                        if (event.status === 'polling' &&
+                                            prev !== 'polling') {
+                                            perHopLastStatus.set(event.hopIndex, 'polling');
+                                            eventHook === null || eventHook === void 0 ? void 0 : eventHook(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_08_02](Date.now() - startTime));
+                                        }
+                                        if (event.status === 'confirmed' &&
+                                            event.txHash &&
+                                            !confirmedHops.has(event.hopIndex)) {
+                                            // waitForAllOutboundTxsV2 populates hop.outboundDetails
+                                            // on the matched hop before emitting 'confirmed' (see
+                                            // outbound-sync.ts:348-355). Auto-promotion paths
+                                            // without a txHash are skipped by the `event.txHash`
+                                            // guard above, so we only reach here with full details.
+                                            const matchedHop = outboundHops.find((h) => h.hopIndex === event.hopIndex);
+                                            if (matchedHop === null || matchedHop === void 0 ? void 0 : matchedHop.outboundDetails) {
+                                                confirmedHops.add(event.hopIndex);
+                                                eventHook === null || eventHook === void 0 ? void 0 : eventHook(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_03](matchedHop.outboundDetails));
+                                            }
+                                        }
                                     },
                                 });
                                 if (!allOutboundDetails.success) {
+                                    const failedIdx = (_b = allOutboundDetails.failedAt) !== null && _b !== void 0 ? _b : 0;
+                                    const failedHop = outboundHops.find((h) => h.hopIndex === failedIdx);
+                                    const failMsg = failedHop
+                                        ? `Outbound failed for hop ${failedIdx} on ${failedHop.executionChain}`
+                                        : `Outbound cascade failed at hop ${failedIdx}`;
+                                    eventHook === null || eventHook === void 0 ? void 0 : eventHook(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_05](failMsg));
                                     return {
                                         success: false,
                                         hops: hopInfos,
-                                        failedAt: allOutboundDetails.failedAt,
+                                        failedAt: failedIdx,
                                     };
                                 }
                             }

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

@@ -16,6 +16,8 @@ const viem_1 = require("viem");
 const uea_evm_1 = require("../../constants/abi/uea.evm");
 const chain_1 = require("../../constants/chain");
 const enums_1 = require("../../constants/enums");
+const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
+const progress_hook_1 = tslib_1.__importDefault(require("../../progress-hook/progress-hook"));
 const account_1 = require("../../universal/account/account");
 const push_client_1 = require("../../push-client/push-client");
 const route_detector_1 = require("../route-detector");
@@ -472,19 +474,40 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                     ? (0, route_detector_1.getRouteInfo)(universalTxResponse.route)
                     : undefined;
                 if (routeInfo === null || routeInfo === void 0 ? void 0 : routeInfo.isOutbound) {
+                    // Response-level only — NOT routed through ctx.progressHook because
+                    // the default ui-kit toast lacks icon/hide-timer handling for these
+                    // events. A follow-up ui-kit PR will add handling and can route
+                    // through both hooks.
+                    registeredProgressHook === null || registeredProgressHook === void 0 ? void 0 : registeredProgressHook(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_08_01]());
+                    let lastEmittedStatus;
+                    const outboundTranslator = (event) => {
+                        if (!registeredProgressHook)
+                            return;
+                        if (event.status === 'polling' && lastEmittedStatus !== 'polling') {
+                            lastEmittedStatus = 'polling';
+                            registeredProgressHook(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_08_02](event.elapsed));
+                        }
+                    };
                     try {
                         const outboundDetails = yield callbacks.waitForOutboundTx(tx.hash, {
                             initialWaitMs: callbacks.outboundConstants.initialWaitMs,
                             pollingIntervalMs: callbacks.outboundConstants.pollingIntervalMs,
                             timeout: callbacks.outboundConstants.maxTimeoutMs,
+                            progressHook: outboundTranslator,
                         });
+                        registeredProgressHook === null || registeredProgressHook === void 0 ? void 0 : registeredProgressHook(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_03](outboundDetails));
                         // Merge external chain details into receipt
                         baseReceipt = Object.assign(Object.assign({}, baseReceipt), { externalTxHash: outboundDetails.externalTxHash, externalChain: outboundDetails.destinationChain, externalExplorerUrl: outboundDetails.explorerUrl, externalRecipient: outboundDetails.recipient, externalAmount: outboundDetails.amount, externalAssetAddr: outboundDetails.assetAddr });
                     }
                     catch (error) {
+                        const errMsg = error instanceof Error ? error.message : String(error);
+                        const isTimeout = errMsg.startsWith('Timeout waiting for outbound transaction');
+                        registeredProgressHook === null || registeredProgressHook === void 0 ? void 0 : registeredProgressHook(isTimeout
+                            ? progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_04](callbacks.outboundConstants.maxTimeoutMs)
+                            : progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_05](errMsg));
                         // Outbound polling timed out - return partial receipt (don't throw)
                         // Push Chain tx succeeded, external tracking can be retried later
-                        callbacks.printLog(`[wait] External chain tracking failed: ${error instanceof Error ? error.message : String(error)}`);
+                        callbacks.printLog(`[wait] External chain tracking failed: ${errMsg}`);
                     }
                 }
                 return baseReceipt;

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

@@ -138,7 +138,10 @@ export interface UniversalTxResponse {
     wait: () => Promise<UniversalTxReceipt>;
     /**
      * Register a progress callback for events during wait().
-     * Call this BEFORE calling wait() to receive tracking events.
+     * Call this BEFORE calling wait() to receive tracking events, including
+     * the SEND-TX-08-xx / SEND-TX-99-03/04/05 external chain polling events
+     * emitted on outbound routes. Registering after wait() resolves will
+     * replay the pre-execution event buffer but miss outbound polling events.
      * @param callback - Function called with each progress event
      */
     progressHook: (callback: (event: import('../progress-hook/progress-hook.types').ProgressEvent) => void) => void;
@@ -515,8 +518,14 @@ export interface CascadeTrackOptions {
     pollingIntervalMs?: number;
     /** Total timeout (default: 600000ms = 10 min) */
     timeout?: number;
-    /** Progress callback */
+    /** Per-hop progress callback */
     progressHook?: (event: CascadeProgressEvent) => void;
+    /**
+     * Unified ProgressEvent stream for SEND-TX-08/99_03-05 telemetry.
+     * Fires per outbound hop during external chain polling. Use alongside
+     * `progressHook` — they emit complementary views of the same events.
+     */
+    eventHook?: (event: import('../progress-hook/progress-hook.types').ProgressEvent) => void;
 }
 /**
  * Progress event emitted during cascade tracking

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

@@ -158,6 +158,25 @@ const RAW_HOOKS = {
         response: null,
         level: 'INFO',
     }),
+    // External chain polling (08-x) — emitted from .wait() / cascade.waitForAll()
+    // after Push Chain tx success, while the SDK polls the relay for the
+    // external chain tx hash on outbound routes.
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_08_01]: (destinationChain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_08_01,
+        title: 'Awaiting External Chain',
+        message: destinationChain
+            ? `Waiting for relay to dispatch to ${destinationChain}...`
+            : 'Waiting for relay to dispatch to external chain...',
+        response: null,
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_08_02]: (elapsedMs) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_08_02,
+        title: 'Polling External Chain',
+        message: `Polling relay for external transaction hash (elapsed: ${Math.round(elapsedMs / 1000)}s)`,
+        response: null,
+        level: 'INFO',
+    }),
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_01]: (txResponse) => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_01,
         title: 'Push Chain Tx Success',
@@ -172,6 +191,27 @@ const RAW_HOOKS = {
         response: null,
         level: 'ERROR',
     }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_03]: (details) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_03,
+        title: 'External Chain Tx Confirmed',
+        message: `External tx confirmed on ${details.destinationChain}: ${details.externalTxHash}`,
+        response: details,
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_04]: (elapsedMs) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_04,
+        title: 'External Chain Tx Timeout',
+        message: `Timed out waiting for external chain tx after ${Math.round(elapsedMs / 1000)}s. Push Chain tx succeeded; the relay may still be processing.`,
+        response: null,
+        level: 'WARNING',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_05]: (errorMessage) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_05,
+        title: 'External Chain Tx Failed',
+        message: errorMessage,
+        response: null,
+        level: 'ERROR',
+    }),
     // UEA Migration hooks
     [progress_hook_types_1.PROGRESS_HOOK.UEA_MIG_01]: () => ({
         id: progress_hook_types_1.PROGRESS_HOOK.UEA_MIG_01,

package/src/lib/progress-hook/progress-hook.types.d.ts

@@ -34,8 +34,13 @@ export declare enum PROGRESS_HOOK {
     SEND_TX_06_05 = "SEND-TX-06-05",// Syncing with Push Chain
     SEND_TX_06_06 = "SEND-TX-06-06",// Funds Credited on Push Chain (was 06_05)
     SEND_TX_07 = "SEND-TX-07",// Broadcasting to Push Chain
+    SEND_TX_08_01 = "SEND-TX-08-01",// Awaiting External Chain
+    SEND_TX_08_02 = "SEND-TX-08-02",// Polling External Chain
     SEND_TX_99_01 = "SEND-TX-99-01",
     SEND_TX_99_02 = "SEND-TX-99-02",
+    SEND_TX_99_03 = "SEND-TX-99-03",// External Chain Tx Confirmed (SUCCESS)
+    SEND_TX_99_04 = "SEND-TX-99-04",// External Chain Tx Timeout (WARNING)
+    SEND_TX_99_05 = "SEND-TX-99-05",// External Chain Tx Failed (ERROR)
     UEA_MIG_01 = "UEA-MIG-01",
     UEA_MIG_02 = "UEA-MIG-02",
     UEA_MIG_03 = "UEA-MIG-03",

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

@@ -28,9 +28,15 @@ var PROGRESS_HOOK;
     PROGRESS_HOOK["SEND_TX_06_06"] = "SEND-TX-06-06";
     // 07-x: Execution / broadcasting flow
     PROGRESS_HOOK["SEND_TX_07"] = "SEND-TX-07";
+    // 08-x: External chain polling (after Push Chain tx success, outbound routes)
+    PROGRESS_HOOK["SEND_TX_08_01"] = "SEND-TX-08-01";
+    PROGRESS_HOOK["SEND_TX_08_02"] = "SEND-TX-08-02";
     // 99-x: Final outcome
     PROGRESS_HOOK["SEND_TX_99_01"] = "SEND-TX-99-01";
     PROGRESS_HOOK["SEND_TX_99_02"] = "SEND-TX-99-02";
+    PROGRESS_HOOK["SEND_TX_99_03"] = "SEND-TX-99-03";
+    PROGRESS_HOOK["SEND_TX_99_04"] = "SEND-TX-99-04";
+    PROGRESS_HOOK["SEND_TX_99_05"] = "SEND-TX-99-05";
     // UEA Migration hooks
     PROGRESS_HOOK["UEA_MIG_01"] = "UEA-MIG-01";
     PROGRESS_HOOK["UEA_MIG_02"] = "UEA-MIG-02";