@pushchain/core 5.1.5-alpha.1 → 5.1.5

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyDeclineError = classifyDeclineError;
 const utils_1 = require("../utils");
 const progress_hook_types_1 = require("./progress-hook.types");
 // Helper to wrap a hook function with timestamp
@@ -7,212 +8,576 @@ const withTimestamp = (fn) => {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return (...args) => (Object.assign(Object.assign({}, fn(...args)), { timestamp: new Date().toISOString() }));
 };
-const RAW_HOOKS = {
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_01]: (originChainNamespace, originChainAddress) => {
-        var _a;
-        return ({
-            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_01,
-            title: 'Origin Chain Detected',
-            message: `Origin chain: ${(_a = utils_1.Utils.chains.getChainName(originChainNamespace)) !== null && _a !== void 0 ? _a : originChainNamespace} - Origin Address: ${originChainAddress}`,
-            response: null,
-            level: 'INFO',
-        });
-    },
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_02_01]: () => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_02_01,
+const friendlyChain = (chainOrNs) => {
+    var _a;
+    if (!chainOrNs)
+        return 'chain';
+    const asString = String(chainOrNs);
+    return (_a = utils_1.Utils.chains.getChainName(asString)) !== null && _a !== void 0 ? _a : asString;
+};
+/**
+ * Classify a sign-time error as either a true wallet user-decline
+ * (viem `UserRejectedRequestError`, ethers `ACTION_REJECTED`, EIP-1193 4001,
+ * or textual "user rejected"/"user denied"/"declined by user") or a generic
+ * signature failure (insufficient funds, RPC failure, contract revert
+ * during sign, etc.). Shared by SEND_TX_104_04 (R1), SEND_TX_204_04 (R2),
+ * and SEND_TX_304_04 (R3) so the heuristic lives in one place.
+ *
+ * When `errorMessage` is omitted, treat it as a decline — the spec copy is
+ * already the decline copy ("Verification declined by user"), so flipping
+ * to "Signature Failed" would make the event self-contradict.
+ */
+function classifyDeclineError(errorMessage) {
+    const msg = errorMessage !== null && errorMessage !== void 0 ? errorMessage : 'Verification declined by user';
+    const isUserDecline = errorMessage === undefined ||
+        /user\s*reject/i.test(msg) ||
+        /user\s*denied/i.test(msg) ||
+        /rejected\s*the\s*request/i.test(msg) ||
+        /UserRejectedRequestError/i.test(msg) ||
+        /ACTION_REJECTED/i.test(msg) ||
+        /declined\s*by\s*user/i.test(msg) ||
+        /\b4001\b/.test(msg);
+    return {
+        isUserDecline,
+        title: isUserDecline ? 'Verification Declined' : 'Signature Failed',
+        message: isUserDecline ? 'Verification declined by user' : msg,
+    };
+}
+// =============================================================================
+// Route 1 — UOA → Push Chain (101–199)
+// =============================================================================
+const RAW_HOOKS_R1 = {
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_101]: (originChainNamespace, originChainAddress) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_101,
+        title: 'Origin Chain Detected',
+        message: `Origin chain: ${friendlyChain(originChainNamespace)} — Address: ${originChainAddress}`,
+        response: { chain: originChainNamespace, address: originChainAddress },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_102_01]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_102_01,
         title: 'Estimating Gas',
         message: 'Estimating and fetching gas limit, gas price for TX',
-        response: null,
+        response: { stage: 'estimating-gas' },
         level: 'INFO',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_02_02]: (executionCost) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_02_02,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_102_02]: (executionCost) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_102_02,
         title: 'Gas Estimated',
-        message: `Total execution cost (Gas cost + value): ${executionCost} UPC`,
-        response: null,
+        message: `Total execution cost: ${executionCost} UPC`,
+        response: { totalCost: executionCost, currency: 'UPC' },
         level: 'SUCCESS',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_03_01]: () => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_03_01,
-        title: 'Resolving UEA',
-        message: 'Resolving Executor Account (UEA) – computing address, checking deployment status and balance',
-        response: null,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_103_01]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_103_01,
+        title: 'Resolving Universal Execution Account',
+        message: 'Resolving UEA – computing address, checking deployment and balance',
+        response: { stage: 'resolving-uea' },
         level: 'INFO',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_03_02]: (ueaAddress, deployed) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_03_02,
-        title: 'UEA Resolved',
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_103_02]: (ueaAddress, deployed) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_103_02,
+        title: 'Universal Execution Account Resolved',
         message: `UEA: ${ueaAddress}, Deployed: ${deployed}`,
-        response: null,
+        response: { uea: ueaAddress, deployed },
         level: 'SUCCESS',
     }),
-    // Payload flow (04-x)
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_04_01]: () => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_04_01,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_01]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_01,
         title: 'Awaiting Transaction',
         message: 'Awaiting user transaction on origin chain',
-        response: null,
+        response: { stage: 'awaiting-transaction' },
         level: 'INFO',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_04_02]: () => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_04_02,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_02]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_02,
         title: 'Awaiting Signature',
         message: 'Awaiting user signature for universal payload',
-        response: null,
+        response: { stage: 'awaiting-signature' },
         level: 'INFO',
     }),
-    // V2 Payload flow
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_04_03]: () => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_04_03,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_03]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_03,
         title: 'Verification Success',
         message: 'Verification completed via Transaction or Signature',
-        response: null,
+        response: { stage: 'verified' },
         level: 'SUCCESS',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_04_04]: () => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_04_04,
-        title: 'Verification Declined',
-        message: 'Verification declined by user',
-        response: null,
-        level: 'ERROR',
-    }),
-    // Gas flow (05-x)
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_05_01]: (originChainTxHash, originChainTx) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_05_01,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04]: (errorMessage) => {
+        const { isUserDecline, title, message } = classifyDeclineError(errorMessage);
+        const response = {
+            error: errorMessage !== null && errorMessage !== void 0 ? errorMessage : 'Verification declined by user',
+            isUserDecline,
+        };
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04,
+            title,
+            message,
+            response,
+            level: 'ERROR',
+        };
+    },
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_105_01]: (originChainTxHash, originChainTx) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_105_01,
         title: 'Gas Funding In Progress',
         message: `Gas funding tx sent: ${originChainTxHash}`,
-        // Attach the full origin-chain transaction object when provided
-        response: originChainTx !== null && originChainTx !== void 0 ? originChainTx : null,
+        response: { txHash: originChainTxHash, originChainTx: originChainTx !== null && originChainTx !== void 0 ? originChainTx : null },
         level: 'INFO',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_05_02]: () => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_05_02,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_105_02]: (txHash) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_105_02,
         title: 'Gas Funding Confirmed',
         message: 'Gas funding confirmed on origin chain',
-        response: null,
+        response: { stage: 'gas-funded', txHash: txHash !== null && txHash !== void 0 ? txHash : null },
         level: 'SUCCESS',
     }),
-    // V2 Funds flow (06-x)
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_01]: (amount, decimals, symbol) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_01,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_01]: (amount, decimals, symbol) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_01,
         title: 'Preparing Funds Transfer',
         message: `Preparing to move ${utils_1.Utils.helpers.formatUnits(amount, decimals)} ${symbol} from origin chain`,
-        response: null,
+        response: { amount, symbol },
         level: 'INFO',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_02]: (txHash, amount, decimals, symbol, originChainTx) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_02,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_02]: (txHash, amount, decimals, symbol, originChainTx) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_02,
         title: 'Funds Lock Submitted',
-        message: `Locking ${utils_1.Utils.helpers.formatUnits(amount, decimals)} ${symbol} for transfer (Tx hash: ${txHash})`,
-        // Attach the full origin-chain transaction object when available
-        response: originChainTx !== null && originChainTx !== void 0 ? originChainTx : null,
+        message: `Locking ${utils_1.Utils.helpers.formatUnits(amount, decimals)} ${symbol} — Tx: ${txHash}`,
+        response: {
+            txHash,
+            amount,
+            symbol,
+            originChainTx: originChainTx !== null && originChainTx !== void 0 ? originChainTx : null,
+        },
         level: 'INFO',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_03]: (required) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_03,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03]: (required) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03,
         title: 'Awaiting Confirmations',
         message: `Waiting for ${required} confirmations`,
-        response: null,
+        response: { current: 0, required },
         level: 'INFO',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_03_01]: (current, required) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_03_01,
-        title: `Confirmation ${current}/${required} received`,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_01]: (current, required) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_01,
+        title: `Confirmation ${current}/${required} Received`,
         message: `${current}/${required} confirmations received`,
-        response: null,
+        response: { current, required },
         level: 'INFO',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_03_02]: (current, required) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_03_02,
-        title: `Confirmation ${current}/${required} received`,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_02]: (current, required) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_02,
+        title: `Confirmation ${current}/${required} Received`,
         message: `${current}/${required} confirmations received`,
-        response: null,
+        response: { current, required },
         level: 'SUCCESS',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_04]: () => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_04,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_04]: (txHash) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_04,
         title: 'Funds Confirmed',
         message: 'Origin chain lock confirmed',
-        response: null,
+        response: { stage: 'funds-confirmed', txHash: txHash !== null && txHash !== void 0 ? txHash : null },
         level: 'SUCCESS',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_05]: () => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_05,
-        title: 'Syncing State with Push Chain',
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_05]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_05,
+        title: 'Syncing with Push Chain',
         message: 'Waiting for transaction to appear on Push Chain',
-        response: null,
+        response: { stage: 'syncing-push-chain' },
         level: 'INFO',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_06]: (amount, decimals, symbol) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_06,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_06]: (amount, decimals, symbol) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_06,
         title: 'Funds Credited on Push Chain',
         message: `Funds credited: ${utils_1.Utils.helpers.formatUnits(amount, decimals)} ${symbol}`,
-        response: null,
+        response: { amount, symbol },
         level: 'SUCCESS',
     }),
-    // Execution flow (07-x)
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_07]: () => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_07,
-        title: 'Broadcasting to Push Chain',
-        message: 'Sending Tx to Push Chain...',
-        response: null,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_07_01]: (originChain, pushGasUsd, paddedDepositUsd) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_07_01,
+        title: `${friendlyChain(originChain)} Push Gas Sizing: Case A`,
+        message: `Push-chain gas < $1; padding deposit to $1 floor (pushGasUsd=${pushGasUsd}, paddedDepositUsd=${paddedDepositUsd})`,
+        response: { category: 'A', pushGasUsd, paddedDepositUsd, chain: originChain },
         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,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_07_02]: (originChain, pushGasUsd, paddedDepositUsd) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_07_02,
+        title: `${friendlyChain(originChain)} Push Gas Sizing: Case B`,
+        message: `Push-chain gas within $1–$10; happy path (pushGasUsd=${pushGasUsd}, paddedDepositUsd=${paddedDepositUsd})`,
+        response: { category: 'B', pushGasUsd, paddedDepositUsd, chain: originChain },
         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,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_07_03]: (originChain, pushGasUsd, paddedDepositUsd) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_07_03,
+        title: `${friendlyChain(originChain)} Push Gas Sizing: Case C`,
+        message: `Push-chain gas > $10; deposit passes through to origin gateway MAX_CAP_UNIVERSAL_TX_USD (pushGasUsd=${pushGasUsd}, paddedDepositUsd=${paddedDepositUsd})`,
+        response: { category: 'C', pushGasUsd, paddedDepositUsd, chain: originChain },
         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',
-        message: 'Tx executed successfully on Push Chain',
-        response: txResponse,
-        level: 'SUCCESS',
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_107]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_107,
+        title: 'Broadcasting to Push Chain',
+        message: 'Sending tx to Push Chain...',
+        response: { stage: 'broadcasting', destination: 'push-chain' },
+        level: 'INFO',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_02]: (errMessage) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_02,
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_01]: (txResponse, receipt) => {
+        var _a;
+        const first = Array.isArray(txResponse) ? txResponse[0] : undefined;
+        const txHash = (_a = first === null || first === void 0 ? void 0 : first.hash) !== null && _a !== void 0 ? _a : '';
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_01,
+            title: 'Push Chain Tx Success',
+            message: `Tx confirmed: ${txHash}`,
+            response: { txHash, response: txResponse, receipt: receipt !== null && receipt !== void 0 ? receipt : null },
+            level: 'SUCCESS',
+        };
+    },
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02]: (errMessage) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02,
         title: 'Push Chain Tx Failed',
         message: errMessage,
-        response: null,
+        response: { error: errMessage },
         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,
+};
+// =============================================================================
+// Route 2 — UEA → UGPC → CEA on target chain (201–299, signature-only)
+// =============================================================================
+const RAW_HOOKS_R2 = {
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_201]: (targetChain, targetAddress) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_201,
+        title: `${friendlyChain(targetChain)} Detected`,
+        message: `External chain: ${targetChain} — Target address: ${targetAddress}`,
+        response: { chain: targetChain, address: targetAddress },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_202_01]: (targetChain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_202_01,
+        title: `Estimating ${friendlyChain(targetChain)} Chain Gas`,
+        message: 'Querying Push Chain gas and UGPC relay fee',
+        response: { stage: 'estimating-gas', chain: targetChain },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_202_02]: (targetChain, pushGas, relayFee) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_202_02,
+        title: `${friendlyChain(targetChain)} Chain Gas Estimated`,
+        message: `Push gas: ${pushGas} UPC + UGPC relay: ${relayFee} UPC = ${pushGas + relayFee} UPC`,
+        response: {
+            gasEstimate: pushGas,
+            relayFee,
+            totalCost: pushGas + relayFee,
+            currency: 'UPC',
+        },
         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_203_01]: (targetChain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_01,
+        title: `Resolving ${friendlyChain(targetChain)} Execution Account`,
+        message: `Resolving UEA on Push Chain and CEA on ${targetChain}`,
+        response: { stage: 'resolving-cea', chain: targetChain },
+        level: 'INFO',
+    }),
+    [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`,
+        message: `UEA: ${ueaAddr}. CEA: ${ceaAddr} on ${targetChain}. Deployed: ${deployed}`,
+        response: { uea: ueaAddr, cea: ceaAddr, chain: targetChain, deployed },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_01]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_01,
+        title: 'Awaiting Signature',
+        message: 'Awaiting user signature for universal payload',
+        response: { stage: 'awaiting-signature' },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_02]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_02,
+        title: 'Signature Received',
+        message: 'Universal payload signed — preparing broadcast',
+        response: { stage: 'signed' },
+        level: 'SUCCESS',
     }),
-    [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',
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_03]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_03,
+        title: 'Verification Success',
+        message: 'Verification completed',
+        response: { stage: 'verified' },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_04]: (errorMessage) => {
+        const { isUserDecline, title, message } = classifyDeclineError(errorMessage);
+        const response = {
+            error: errorMessage !== null && errorMessage !== void 0 ? errorMessage : 'Verification declined by user',
+            isUserDecline,
+        };
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_04,
+            title,
+            message,
+            response,
+            level: 'ERROR',
+        };
+    },
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_207]: (targetChain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_207,
+        title: `Broadcasting from Push Chain → ${friendlyChain(targetChain)}`,
+        message: 'Sending tx to Push Chain...',
+        response: { chain: targetChain },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_209_01]: (targetChain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_209_01,
+        title: 'Awaiting Push Chain Relay',
+        message: `Waiting for UGPC to relay execution to ${targetChain}`,
+        response: { chain: targetChain },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_209_02]: (targetChain, elapsedMs) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_209_02,
+        title: `Syncing State with ${friendlyChain(targetChain)}`,
+        message: `Polling ${targetChain} for CEA execution`,
+        response: { chain: targetChain, elapsedMs },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_01]: (details) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_01,
+        title: `${friendlyChain(details.destinationChain)} Tx Success`,
+        message: `CEA executed on ${details.destinationChain} - tx: ${details.externalTxHash}`,
+        response: Object.assign({ txHash: details.externalTxHash }, details),
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02]: (targetChain, errorMessage) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02,
+        title: `${friendlyChain(targetChain)} Tx Failed`,
         message: errorMessage,
-        response: null,
+        response: { error: errorMessage, chain: targetChain },
+        level: 'ERROR',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_03]: (targetChain, elapsedMs) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_03,
+        title: `Syncing State with ${friendlyChain(targetChain)} Timeout`,
+        message: `Timed out waiting for UGPC relay to ${targetChain}`,
+        response: { error: 'relay timeout', chain: targetChain, elapsedMs },
+        level: 'ERROR',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_99]: (targetChain, txHash) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_99,
+        title: `${friendlyChain(targetChain)} Tx Completed`,
+        message: `Intermediate ${friendlyChain(targetChain)} tx confirmed: ${txHash}, progressing to next phase`,
+        response: { chain: targetChain, txHash },
+        level: 'INFO',
+    }),
+};
+// =============================================================================
+// Route 3 — UEA → UGPC → CEA → sendUniversalTxToUEA → Push Chain (301–399)
+// =============================================================================
+const RAW_HOOKS_R3 = {
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_99_99]: (txHash) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_99_99,
+        title: 'Push Chain TX Completed',
+        message: `Intermediate Push Chain tx confirmed: ${txHash}, progressing to next phase`,
+        response: { txHash },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_301]: (sourceChain, ceaAddress) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_301,
+        title: `${friendlyChain(sourceChain)}'s Executor Account Detected`,
+        message: `Source chain: ${sourceChain} — CEA: ${ceaAddress}`,
+        response: { chain: sourceChain, address: ceaAddress },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_01]: (sourceChain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_01,
+        title: `Estimating ${friendlyChain(sourceChain)} Gas`,
+        message: 'Querying Push Chain gas and UGPC relay fee',
+        response: { stage: 'estimating-gas', chain: sourceChain },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_02]: (sourceChain, pushGas, relayFee) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_02,
+        title: `${friendlyChain(sourceChain)} Gas Estimated`,
+        message: `Push gas: ${pushGas} UPC + UGPC relay: ${relayFee} UPC = ${pushGas + relayFee} UPC`,
+        response: {
+            gasEstimate: pushGas,
+            relayFee,
+            totalCost: pushGas + relayFee,
+            currency: 'UPC',
+        },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_03_01]: (sourceChain, gasUsd, gasLegNativePc) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_03_01,
+        title: `${friendlyChain(sourceChain)} Gas Sizing: Case A`,
+        message: `Gas cost < $1; padding to $1 minimum (gasUsd=${gasUsd}, gasLeg=${gasLegNativePc} UPC)`,
+        response: { category: 'A', gasUsd, gasLegNativePc, chain: sourceChain },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_03_02]: (sourceChain, gasUsd, gasLegNativePc) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_03_02,
+        title: `${friendlyChain(sourceChain)} Gas Sizing: Case B`,
+        message: `Gas cost within $1–$10 window; happy path (gasUsd=${gasUsd}, gasLeg=${gasLegNativePc} UPC)`,
+        response: { category: 'B', gasUsd, gasLegNativePc, chain: sourceChain },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_03_03]: (sourceChain, gasUsd, gasLegNativePc, overflowNativePc) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_03_03,
+        title: `${friendlyChain(sourceChain)} Gas Sizing: Case C`,
+        message: `Gas cost > $10; splitting into $10 gas leg + ${overflowNativePc} UPC overflow bridged as funds`,
+        response: {
+            category: 'C',
+            gasUsd,
+            gasLegNativePc,
+            overflowNativePc,
+            chain: sourceChain,
+        },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_01]: (sourceChain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_01,
+        title: 'Resolving Execution Accounts on Chains',
+        message: `Resolving UEA on Push Chain and CEA on ${sourceChain}`,
+        response: { stage: 'resolving-cea-uea', chain: sourceChain },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_02]: (ueaAddr, ceaAddr, sourceChain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_02,
+        title: 'Execution Accounts Resolved',
+        message: `UEA: ${ueaAddr}. CEA: ${ceaAddr} on ${sourceChain}. Deployed: true`,
+        response: { uea: ueaAddr, cea: ceaAddr, chain: sourceChain, deployed: true },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_01]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_01,
+        title: 'Awaiting Signature',
+        message: 'Awaiting user signature for universal payload',
+        response: { stage: 'awaiting-signature' },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_02]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_02,
+        title: 'Signature Received',
+        message: 'Universal payload signed — preparing broadcast',
+        response: { stage: 'signed' },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_03]: () => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_03,
+        title: 'Verification Success',
+        message: 'Verification completed',
+        response: { stage: 'verified' },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_04]: (errorMessage) => {
+        const { isUserDecline, title, message } = classifyDeclineError(errorMessage);
+        const response = {
+            error: errorMessage !== null && errorMessage !== void 0 ? errorMessage : 'Verification declined by user',
+            isUserDecline,
+        };
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_04,
+            title,
+            message,
+            response,
+            level: 'ERROR',
+        };
+    },
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_307]: (sourceChain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_307,
+        title: `Broadcasting from Push Chain → ${friendlyChain(sourceChain)}`,
+        message: 'Sending tx from Push Chain...',
+        response: { chain: sourceChain },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_01]: (sourceChain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_01,
+        title: `Awaiting ${friendlyChain(sourceChain)} Relay`,
+        message: `Waiting for UGPC to relay to CEA on ${sourceChain}`,
+        response: { chain: sourceChain },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_02]: (sourceChain, elapsedMs) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_02,
+        title: `Syncing State with ${friendlyChain(sourceChain)}`,
+        message: `Polling ${sourceChain} for CEA execution`,
+        response: { chain: sourceChain, elapsedMs },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_03]: (sourceChain, txHash) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_03,
+        title: `${friendlyChain(sourceChain)} Tx Confirmed`,
+        message: `CEA executed on ${sourceChain}: ${txHash} — return inbound initiated`,
+        response: { chain: sourceChain, txHash },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_310_01]: (sourceChain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_310_01,
+        title: `${friendlyChain(sourceChain)} → Push Chain Inbound Tx Submitted`,
+        message: `CEA initiated return — waiting for Push Chain inbound from ${sourceChain}`,
+        response: { chain: sourceChain },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_310_02]: (sourceChain, elapsedMs) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_310_02,
+        title: 'Syncing State with Push Chain for Inbound Tx',
+        message: `Polling Push Chain for inbound from ${sourceChain}`,
+        response: { chain: sourceChain, elapsedMs },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_01]: (sourceChain, txHash, receipt) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_01,
+        title: 'Push Chain Inbound Tx Success',
+        message: `Inbound from ${sourceChain} confirmed · Push tx: ${txHash}`,
+        response: { chain: sourceChain, txHash, receipt: receipt !== null && receipt !== void 0 ? receipt : null },
+        level: 'SUCCESS',
+    }),
+    // 399-02 / 399-03 are multi-use terminal hooks for R3:
+    //   • 'inbound' (default) — round-trip Push tx failed/timed out (target: Push)
+    //   • 'outbound' — source-chain CEA tx failed/timed out (target: source chain)
+    //   • 'push' — Push Chain execution itself failed (gateway tx revert / pre-wait)
+    // Phase is passed by the emission site so the title matches the leg that
+    // actually failed. Default stays 'inbound' for callers that don't specify
+    // (backwards-compat with fixtures + response-builder's inbound block).
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02]: (errorMessage, phase = 'inbound', chain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02,
+        title: phase === 'outbound'
+            ? `${friendlyChain(chain)} Tx Failed`
+            : phase === 'push'
+                ? 'Push Chain Tx Failed'
+                : 'Push Chain Inbound Tx Failed',
+        message: errorMessage,
+        response: { error: errorMessage, phase, chain: chain !== null && chain !== void 0 ? chain : null },
+        level: 'ERROR',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03]: (sourceChain, elapsedMs, phase = 'inbound') => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03,
+        title: phase === 'outbound'
+            ? `Syncing State with ${friendlyChain(sourceChain)} Timeout`
+            : phase === 'push'
+                ? 'Push Chain Tx Timeout'
+                : 'Push Chain Inbound Timeout',
+        message: phase === 'outbound'
+            ? `Timed out waiting for ${friendlyChain(sourceChain)} relay`
+            : phase === 'push'
+                ? `Timed out waiting for Push Chain tx`
+                : `Timed out waiting for inbound from ${sourceChain}`,
+        response: {
+            error: phase === 'outbound'
+                ? 'outbound timeout'
+                : phase === 'push'
+                    ? 'push timeout'
+                    : 'inbound timeout',
+            phase,
+            chain: sourceChain,
+            elapsedMs,
+        },
         level: 'ERROR',
     }),
-    // UEA Migration hooks
+};
+// =============================================================================
+// UEA Migration hooks (unchanged)
+// =============================================================================
+const RAW_HOOKS_MIG = {
     [progress_hook_types_1.PROGRESS_HOOK.UEA_MIG_01]: () => ({
         id: progress_hook_types_1.PROGRESS_HOOK.UEA_MIG_01,
         title: 'Checking UEA',
@@ -238,14 +603,14 @@ const RAW_HOOKS = {
         id: progress_hook_types_1.PROGRESS_HOOK.UEA_MIG_9901,
         title: 'UEA Migration Successful',
         message: `UEA migration is successful. UEA is now version ${newVersion}.`,
-        response: null,
+        response: { version: newVersion },
         level: 'SUCCESS',
     }),
     [progress_hook_types_1.PROGRESS_HOOK.UEA_MIG_9902]: () => ({
         id: progress_hook_types_1.PROGRESS_HOOK.UEA_MIG_9902,
         title: 'UEA Migration Failed',
         message: 'UEA migration failed. Check transaction on explorer.',
-        response: null,
+        response: { error: 'UEA migration failed' },
         level: 'ERROR',
     }),
     [progress_hook_types_1.PROGRESS_HOOK.UEA_MIG_9903]: () => ({
@@ -256,6 +621,55 @@ const RAW_HOOKS = {
         level: 'INFO',
     }),
 };
+// =============================================================================
+// Multichain (multi-hop) cascade markers (001 / 002 / 999)
+// =============================================================================
+const RAW_HOOKS_MULTICHAIN = {
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_001]: (hopCount, chains) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_001,
+        title: 'Multichain Transactions Initiated',
+        message: `${hopCount}-hop transaction — ${chains.map(friendlyChain).join(' → ')}`,
+        response: { hopCount, chains },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_002_01]: (n, total, fromChain, toChain) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_002_01,
+        title: `Starting Intermediate Transaction #${n}/${total}`,
+        message: `Starting tx ${n} of ${total}: ${friendlyChain(fromChain)} → ${friendlyChain(toChain)}`,
+        response: { n, total, fromChain, toChain },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_002_99_99]: (n, total) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_002_99_99,
+        title: `Intermediate Transaction #${n}/${total} Complete`,
+        message: `Tx ${n} of ${total} confirmed — proceeding to tx ${n + 1}`,
+        response: { n, total },
+        level: 'INFO',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_01]: (hopCount) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_01,
+        title: 'All Multichain Transactions Successful',
+        message: `${hopCount}-hop transaction confirmed across all chains`,
+        response: { hopCount },
+        level: 'SUCCESS',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_02]: (failedAt, total, errorMessage) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_02,
+        title: 'Multichain Transactions Failed',
+        message: `Cascade failed at hop ${failedAt} of ${total}: ${errorMessage}`,
+        response: { failedAt, total, error: errorMessage },
+        level: 'ERROR',
+    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_03]: (failedAt, total) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_03,
+        title: 'Multichain Transactions Timeout',
+        message: `Cascade timed out at hop ${failedAt} of ${total}`,
+        response: { failedAt, total, error: 'cascade timeout' },
+        level: 'ERROR',
+    }),
+};
+// Combine all routes into the master record
+const RAW_HOOKS = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, RAW_HOOKS_R1), RAW_HOOKS_R2), RAW_HOOKS_R3), RAW_HOOKS_MULTICHAIN), RAW_HOOKS_MIG);
 // Build final hooks with timestamp injection
 const PROGRESS_HOOKS = Object.fromEntries(Object.entries(RAW_HOOKS).map(([key, value]) => [key, withTimestamp(value)]));
 exports.default = PROGRESS_HOOKS;