@pushchain/core 5.1.5-alpha.1 → 5.1.5

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

@@ -8,11 +8,15 @@ exports.transformToUniversalTxReceipt = transformToUniversalTxReceipt;
 exports.reconstructProgressEvents = reconstructProgressEvents;
 exports.detectRouteFromUniversalTxData = detectRouteFromUniversalTxData;
 const tslib_1 = require("tslib");
+const viem_1 = require("viem");
 const chain_1 = require("../../constants/chain");
 const enums_1 = require("../../constants/enums");
+const selectors_1 = require("../../constants/selectors");
 const types_1 = require("../../generated/uexecutor/v1/types");
+const types_2 = require("../../generated/uexecutor/v2/types");
 const progress_hook_1 = tslib_1.__importDefault(require("../../progress-hook/progress-hook"));
 const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
+const payload_builders_1 = require("../payload-builders");
 const route_detector_1 = require("../route-detector");
 // ============================================================================
 // Receipt Transform
@@ -42,14 +46,66 @@ function transformToUniversalTxReceipt(receipt, originalTxResponse) {
 // Progress Event Reconstruction
 // ============================================================================
 function reconstructProgressEvents(universalTxResponse, universalTxData) {
-    var _a;
+    var _a, _b, _c;
+    const route = universalTxResponse.route;
+    const pcTx = (_a = universalTxData === null || universalTxData === void 0 ? void 0 : universalTxData.pcTx) === null || _a === void 0 ? void 0 : _a[0];
+    const isOutboundFailed = (universalTxData === null || universalTxData === void 0 ? void 0 : universalTxData.universalStatus) === types_1.UniversalTxStatus.OUTBOUND_FAILED;
+    const isPcFailed = (pcTx === null || pcTx === void 0 ? void 0 : pcTx.status) === 'FAILED';
+    // R1 fallback keeps the inclusive view (any terminal failure → 199-02).
+    // R2 and R3 reconstructors narrow to Push-chain-only failures (see call
+    // sites below) — an outbound-leg revert is re-detected during wait() by
+    // `waitForOutboundTx` and emitted as 299-02 / 399-02 with the correctly
+    // scoped phase ('outbound' + source-chain). Emitting in both places
+    // would double-fire the terminal with a misleading 'push' title on top.
+    const isFailed = isPcFailed || isOutboundFailed;
+    const errorMsg = isOutboundFailed
+        ? 'Outbound transaction failed (status: OUTBOUND_FAILED)'
+        : ((pcTx === null || pcTx === void 0 ? void 0 : pcTx.errorMsg) || 'Unknown error');
+    // Route 2 / 3 reconstruction — keep parity with live emission from
+    // route-handlers.ts (which fires 201/203/207 or 301/303/307 then suppresses
+    // R1 IDs via fireProgressHook). Skip the R1 101–107 sequence here; it would
+    // only fire for R2/R3 because reconstructProgressEvents bypasses
+    // fireProgressHook (writes to events[] directly).
+    // For R2/R3 we only emit the reconstructed terminal when the Push-chain
+    // leg itself failed — so prefer pcTx.errorMsg over the outbound-failed
+    // sentinel. The outer `errorMsg` above carries the outbound text when
+    // `isOutboundFailed` is set; that path is handled by wait() instead.
+    const pcErrorMsg = (pcTx === null || pcTx === void 0 ? void 0 : pcTx.errorMsg) || 'Unknown error';
+    // Multichain cascade: a single Push-chain tx that fanned out into >1
+    // outbound legs (executeTransactions([tx1, tx2, …])). The cosmos record
+    // carries one UniversalTx with multiple outboundTx entries; wrap the
+    // per-leg R2/R3 backbones with the SEND-TX-001 / 002-xx / 999-xx markers
+    // so replay parity matches live cascade emission.
+    if (((_c = (_b = universalTxData === null || universalTxData === void 0 ? void 0 : universalTxData.outboundTx) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0) > 1) {
+        return reconstructMultichain(universalTxResponse, universalTxData, isFailed, errorMsg);
+    }
+    if (route === route_detector_1.TransactionRoute.UOA_TO_CEA) {
+        // R2: only Push-chain revert triggers the 299-02 terminal here; a
+        // cosmos OUTBOUND_FAILED without pcTx.FAILED is handled by wait().
+        return reconstructR2(universalTxResponse, universalTxData, isPcFailed, pcErrorMsg);
+    }
+    if (route === route_detector_1.TransactionRoute.CEA_TO_PUSH) {
+        // R3: same narrowing — only pcTx.FAILED triggers reconstructed 399-02.
+        return reconstructR3(universalTxResponse, universalTxData, isPcFailed, pcErrorMsg);
+    }
+    // Route 1 (and Route 4 fallback while R4 has no spec'd IDs) — emit the
+    // safe R1 backbone that applies to every sub-path: origin → gas → UEA
+    // (non-Push only) → broadcast → terminal. The sub-path-specific hooks
+    // (104-xx signature, 105-xx fee-lock, 106-xx funds-bridge) are intentionally
+    // omitted from reconstruction because R1 doesn't register a UniversalTx
+    // on Push Chain, so `universalTxData` is usually undefined here and we
+    // have no reliable signal to tell the three paths apart. Callers who want
+    // the full live sequence should either register `progressHook` at
+    // `initialize()` time (client-level) or call `tx.progressHook(cb)` after
+    // sendTransaction — both deliver the full stream from the execute-phase
+    // event buffer.
     const events = [];
     const originParts = universalTxResponse.origin.split(':');
     const chainNamespace = originParts.length >= 2 ? `${originParts[0]}:${originParts[1]}` : originParts[0];
     const originAddress = originParts.length >= 3 ? originParts[2] : universalTxResponse.from;
-    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_01](chainNamespace, originAddress));
-    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_02_01]());
-    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_02_02](universalTxResponse.gasLimit));
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_101](chainNamespace, originAddress));
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_102_01]());
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_102_02](universalTxResponse.gasLimit));
     const pushChainIds = [
         chain_1.CHAIN_INFO[enums_1.CHAIN.PUSH_MAINNET].chainId,
         chain_1.CHAIN_INFO[enums_1.CHAIN.PUSH_TESTNET_DONUT].chainId,
@@ -57,47 +113,239 @@ function reconstructProgressEvents(universalTxResponse, universalTxData) {
     ];
     const isPushOrigin = pushChainIds.some((id) => chainNamespace.includes(`eip155:${id}`));
     if (!isPushOrigin) {
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_03_01]());
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_03_02](universalTxResponse.from, true));
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_103_01]());
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_103_02](universalTxResponse.from, true));
     }
-    const inboundTx = universalTxData === null || universalTxData === void 0 ? void 0 : universalTxData.inboundTx;
-    const hasFundsFlow = inboundTx && BigInt(inboundTx.amount || '0') > BigInt(0);
-    if (!isPushOrigin) {
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_04_02]());
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_04_03]());
-    }
-    if (hasFundsFlow && inboundTx) {
-        const amount = BigInt(inboundTx.amount);
-        const decimals = 18;
-        const symbol = 'TOKEN';
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_01](amount, decimals, symbol));
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_02](inboundTx.txHash, amount, decimals, symbol));
-        const confirmations = 1;
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_03](confirmations));
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_03_02](confirmations, confirmations));
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_04]());
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_05]());
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_06_06](amount, decimals, symbol));
-    }
-    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_07]());
-    const pcTx = (_a = universalTxData === null || universalTxData === void 0 ? void 0 : universalTxData.pcTx) === null || _a === void 0 ? void 0 : _a[0];
-    const isOutboundFailed = (universalTxData === null || universalTxData === void 0 ? void 0 : universalTxData.universalStatus) === types_1.UniversalTxStatus.OUTBOUND_FAILED;
-    const isPcFailed = (pcTx === null || pcTx === void 0 ? void 0 : pcTx.status) === 'FAILED';
-    const isFailed = isPcFailed || isOutboundFailed;
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_107]());
     if (isFailed) {
-        const errorMsg = isOutboundFailed
-            ? 'Outbound transaction failed (status: OUTBOUND_FAILED)'
-            : ((pcTx === null || pcTx === void 0 ? void 0 : pcTx.errorMsg) || 'Unknown error');
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_02](errorMsg));
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02](errorMsg));
     }
     else {
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_01]([universalTxResponse]));
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_01]([universalTxResponse]));
+    }
+    return events;
+}
+function reconstructR2(universalTxResponse, universalTxData, isFailed, errorMsg) {
+    var _a, _b, _c, _d;
+    const events = [];
+    const targetChain = ((_a = universalTxResponse.chain) !== null && _a !== void 0 ? _a : 'external');
+    const targetAddress = (_d = (_c = (_b = universalTxData === null || universalTxData === void 0 ? void 0 : universalTxData.outboundTx) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.recipient) !== null && _d !== void 0 ? _d : universalTxResponse.to;
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_201](targetChain, targetAddress));
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_202_01](targetChain));
+    // Reconstruction: gas split unavailable from historical data — pass zeroes
+    // so the shape matches live emission. totalCost derives to 0 in the message,
+    // which is acceptable for a tracked (past) transaction.
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_202_02](targetChain, BigInt(0), BigInt(0)));
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_01](targetChain));
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_02](universalTxResponse.from, targetAddress, targetChain, true));
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_01]());
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_02]());
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_03]());
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_207](targetChain));
+    if (isFailed) {
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02](errorMsg));
+    }
+    else {
+        // Push Chain success is intermediate for R2 — the wait() outbound poll
+        // appends the real terminal (299-01/02/03) once the external leg resolves.
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_99](targetChain, universalTxResponse.hash));
+    }
+    return events;
+}
+function reconstructR3(universalTxResponse, universalTxData, isFailed, errorMsg) {
+    var _a, _b, _c, _d;
+    const events = [];
+    const sourceChain = ((_a = universalTxResponse.chain) !== null && _a !== void 0 ? _a : 'source');
+    const ceaAddress = (_d = (_c = (_b = universalTxData === null || universalTxData === void 0 ? void 0 : universalTxData.outboundTx) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.recipient) !== null && _d !== void 0 ? _d : universalTxResponse.to;
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_301](sourceChain, ceaAddress));
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_01](sourceChain));
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_02](sourceChain, BigInt(0), BigInt(0)));
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_01](sourceChain));
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_02](universalTxResponse.from, ceaAddress, sourceChain));
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_01]());
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_02]());
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_03]());
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_307](sourceChain));
+    if (isFailed) {
+        // Reconstructed Push-chain-tx failure — phase='push' so the title reads
+        // "Push Chain Tx Failed" rather than the inbound copy.
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](errorMsg, 'push'));
+    }
+    else {
+        // Push Chain success is intermediate for R3 — wait() drives the source-chain
+        // CEA poll (309-xx) and the inbound-to-Push poll (310-xx / 399-xx) on top.
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_99_99](universalTxResponse.hash));
+    }
+    return events;
+}
+// ============================================================================
+// Multichain cascade reconstruction
+// ============================================================================
+function decodeUeaMulticall(data) {
+    if (!data)
+        return null;
+    const normalized = data.startsWith('0x') ? data : `0x${data}`;
+    if (!normalized.toLowerCase().startsWith(selectors_1.UEA_MULTICALL_SELECTOR))
+        return null;
+    try {
+        const body = `0x${normalized.slice(10)}`;
+        const [tuples] = (0, viem_1.decodeAbiParameters)([payload_builders_1.MULTICALL_TUPLE_TYPE], body);
+        return tuples;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/**
+ * Count the merged R1 calls embedded inside an R3 outbound's payload.
+ *
+ * The outbound payload on-chain is UEA_MULTICALL_SELECTOR + abi-encoded
+ * MultiCall[] targeting the CEA. One of those inner calls is
+ * `sendUniversalTxToUEA(token, amount, payload, revertRecipient)` whose
+ * `payload` argument is itself a UEA_MULTICALL_SELECTOR + MultiCall[] blob
+ * — that blob is what will execute on Push Chain after the round-trip. Its
+ * tuple count equals the number of user R1 hops merged into this R3 leg.
+ */
+function decodeR3MergedInnerCount(outboundPayload) {
+    const outerCalls = decodeUeaMulticall(outboundPayload);
+    if (!outerCalls)
+        return 0;
+    for (const call of outerCalls) {
+        const d = (call.data || '').toLowerCase();
+        if (!d.startsWith(`0x${SEND_UNIVERSAL_TX_TO_UEA_SELECTOR}`))
+            continue;
+        try {
+            const innerBody = `0x${d.slice(10)}`;
+            // sendUniversalTxToUEA(token, amount, payload, revertRecipient).
+            // The `payload` arg is an ABI-encoded UniversalPayload struct
+            // produced by buildInboundUniversalPayload() — its `.data` field is
+            // the UEA_MULTICALL bytes that will execute on Push after the
+            // round-trip.
+            const [, , upStructBytes] = (0, viem_1.decodeAbiParameters)([
+                { type: 'address' },
+                { type: 'uint256' },
+                { type: 'bytes' },
+                { type: 'address' },
+            ], innerBody);
+            const [universalPayload] = (0, viem_1.decodeAbiParameters)([
+                {
+                    type: 'tuple',
+                    components: [
+                        { name: 'to', type: 'address' },
+                        { name: 'value', type: 'uint256' },
+                        { name: 'data', type: 'bytes' },
+                        { name: 'gasLimit', type: 'uint256' },
+                        { name: 'maxFeePerGas', type: 'uint256' },
+                        { name: 'maxPriorityFeePerGas', type: 'uint256' },
+                        { name: 'nonce', type: 'uint256' },
+                        { name: 'deadline', type: 'uint256' },
+                        { name: 'vType', type: 'uint8' },
+                    ],
+                },
+            ], upStructBytes);
+            const pushCalls = decodeUeaMulticall(universalPayload.data);
+            if (pushCalls)
+                return pushCalls.length;
+        }
+        catch (_a) {
+            // fall through to next outer call
+        }
+    }
+    return 0;
+}
+function reconstructMultichain(universalTxResponse, universalTxData, isFailed, errorMsg) {
+    const events = [];
+    const outbounds = universalTxData.outboundTx;
+    // Merged-R1 recovery: each R3 outbound's payload embeds the
+    // sendUniversalTxToUEA call whose `payload` arg is the UEA multicall that
+    // will execute on Push after the round-trip. Its tuple count equals the
+    // number of user R1 hops the orchestrator folded into that R3 leg.
+    // Total user-level hopCount =
+    //   (outbounds that are NOT R3) + Σ (merged inner-call count per R3 leg).
+    // Falls back to `outbounds.length` when no R3 legs or decode fails
+    // (pure R2 cascade).
+    let r3LegCount = 0;
+    let totalMergedInner = 0;
+    for (const ob of outbounds) {
+        const isR3 = (ob.payload || '')
+            .toLowerCase()
+            .includes(SEND_UNIVERSAL_TX_TO_UEA_SELECTOR);
+        if (!isR3)
+            continue;
+        r3LegCount += 1;
+        const inner = decodeR3MergedInnerCount(ob.payload || '');
+        // When decode fails, assume the R3 leg represents 1 user hop so the
+        // fallback converges on outbounds.length.
+        totalMergedInner += inner > 0 ? inner : 1;
+    }
+    const recovered = r3LegCount > 0
+        ? outbounds.length - r3LegCount + totalMergedInner
+        : outbounds.length;
+    // Defensive clamp: never under-count what's already visible on-chain.
+    const hopCount = Math.max(recovered, outbounds.length);
+    // Source chain for SEND-TX-001: the Push Chain (initiator of a cascade
+    // always executes a multicall on Push first). Fall back to the response's
+    // chain if origin parsing fails.
+    const pushChainId = chain_1.CHAIN_INFO[enums_1.CHAIN.PUSH_TESTNET_DONUT].chainId;
+    const sourceChain = `eip155:${pushChainId}`;
+    const destChains = outbounds.map((ob) => ob.destinationChain);
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_001](hopCount, [
+        sourceChain,
+        ...destChains,
+    ]));
+    let failedAt = null;
+    let failureMsg = errorMsg;
+    outbounds.forEach((ob, i) => {
+        var _a;
+        const hopNum = i + 1;
+        const fromChain = i === 0 ? sourceChain : outbounds[i - 1].destinationChain;
+        const toChain = ob.destinationChain;
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_002_01](hopNum, hopCount, fromChain, toChain));
+        // Build a single-leg view so the per-leg reconstructors (R2/R3) emit
+        // their usual backbone. We narrow `outboundTx` to this leg so any field
+        // reads (e.g. `outboundTx[0].recipient`) resolve to this leg's data.
+        const legResponse = Object.assign(Object.assign({}, universalTxResponse), { chain: toChain, chainNamespace: toChain });
+        const legData = Object.assign(Object.assign({}, universalTxData), { outboundTx: [ob] });
+        const payload = (ob.payload || '').toLowerCase();
+        const isR3Leg = payload.includes(SEND_UNIVERSAL_TX_TO_UEA_SELECTOR);
+        const legFailed = ob.outboundStatus === types_2.OutboundStatus.REVERTED;
+        const legError = ob.abortReason || ((_a = ob.observedTx) === null || _a === void 0 ? void 0 : _a.errorMsg) || 'leg execution failed';
+        if (isR3Leg) {
+            events.push(...reconstructR3(legResponse, legData, legFailed, legError));
+        }
+        else {
+            events.push(...reconstructR2(legResponse, legData, legFailed, legError));
+        }
+        if (!legFailed) {
+            events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_002_99_99](hopNum, hopCount));
+        }
+        else if (failedAt === null) {
+            failedAt = hopNum;
+            failureMsg = legError;
+        }
+    });
+    if (failedAt !== null) {
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_02](failedAt, hopCount, failureMsg));
+    }
+    else if (isFailed) {
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_02](hopCount, hopCount, errorMsg));
+    }
+    else {
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_01](hopCount));
     }
     return events;
 }
 // ============================================================================
 // Route Detection from V2 Data
 // ============================================================================
+/**
+ * Function selector of `sendUniversalTxToUEA(address,uint256,bytes,address)`.
+ * R3 (CEA → Push round-trip) outbound payloads always contain a CEA
+ * self-call to this method — its presence in the outbound payload bytes
+ * disambiguates a fresh R3 outbound (no inbound leg yet) from R2.
+ * Verified via `keccak256(toBytes('sendUniversalTxToUEA(address,uint256,bytes,address)')).slice(0,10)`.
+ */
+const SEND_UNIVERSAL_TX_TO_UEA_SELECTOR = 'e7c1e3fc';
 function detectRouteFromUniversalTxData(universalTxData) {
     if (!universalTxData)
         return undefined;
@@ -109,6 +357,16 @@ function detectRouteFromUniversalTxData(universalTxData) {
         types_1.UniversalTxStatus.OUTBOUND_FAILED,
     ].includes(universalTxData.universalStatus);
     if (hasOutbound || statusIndicatesOutbound) {
+        // Disambiguate R3 from R2 when the inbound leg of an R3 round-trip
+        // hasn't materialized yet (fresh tx). R3 outbounds always carry a CEA
+        // self-call to `sendUniversalTxToUEA(...)` — its selector in the
+        // payload bytes is a deterministic signal.
+        const r3Signal = universalTxData.outboundTx.some((ob) => {
+            const payload = (ob.payload || '').toLowerCase();
+            return payload.includes(SEND_UNIVERSAL_TX_TO_UEA_SELECTOR);
+        });
+        if (r3Signal)
+            return route_detector_1.TransactionRoute.CEA_TO_PUSH;
         return hasInbound
             ? route_detector_1.TransactionRoute.CEA_TO_CEA
             : route_detector_1.TransactionRoute.UOA_TO_CEA;

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

@@ -5,6 +5,7 @@ import { ProgressEvent } from '../progress-hook/progress-hook.types';
 import { PushClient } from '../push-client/push-client';
 import type { UniversalAccount, UniversalSigner } from '../universal/universal.types';
 import { ExecuteParams, UniversalExecuteParams, PreparedUniversalTx, CascadedTxResponse, RescueFundsParams } from './orchestrator.types';
+import { TransactionRoute } from './route-detector';
 export declare class Orchestrator {
     private readonly universalSigner;
     private pushNetwork;
@@ -16,6 +17,11 @@ export declare class Orchestrator {
     get pushClient(): PushClient;
     accountStatusCache: AccountStatus | null;
     accountStatusReadyPromise?: Promise<void>;
+    /**
+     * @internal Mirrors `OrchestratorContext.currentRoute` — set at the top of
+     * execute()/trackTransaction() so emission sites pick the right ID range.
+     */
+    currentRoute?: TransactionRoute;
     private get ctx();
     private _getResponseCallbacks;
     private _getCascadeCallbacks;
@@ -87,7 +93,7 @@ export declare class Orchestrator {
     /**
      * Queries gas fee for an outbound transaction from the UniversalCore contract.
      */
-    queryOutboundGasFee(prc20Token: `0x${string}`, gasLimit: bigint): Promise<{
+    queryOutboundGasFee(prc20Token: `0x${string}`, gasLimit: bigint, destinationChain?: CHAIN): Promise<{
         gasToken: `0x${string}`;
         gasFee: bigint;
         protocolFee: bigint;

package/src/lib/orchestrator/orchestrator.js

@@ -23,6 +23,7 @@ class Orchestrator {
             transformToUniversalTxReceipt: (receipt, resp) => (0, internals_1.transformToUniversalTxReceipt)(receipt, resp),
             printLog: (msg) => (0, internals_1.printLog)(this.ctx, msg),
             outboundConstants: { initialWaitMs: internals_1.OUTBOUND_INITIAL_WAIT_MS, pollingIntervalMs: internals_1.OUTBOUND_POLL_INTERVAL_MS, maxTimeoutMs: internals_1.OUTBOUND_MAX_TIMEOUT_MS },
+            inboundConstants: { initialWaitMs: internals_1.INBOUND_INITIAL_WAIT_MS, pollingIntervalMs: internals_1.OUTBOUND_POLL_INTERVAL_MS, maxTimeoutMs: internals_1.INBOUND_MAX_TIMEOUT_MS },
         };
     }
     _getCascadeCallbacks() {
@@ -130,67 +131,118 @@ class Orchestrator {
     execute(params) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d;
-            // Lazy UEA upgrade check
+            // Snapshot the caller's active route — `executeMultiChain` recurses into
+            // this same method for R2/R3's inner Push-side execution, and without
+            // snapshot/restore the recursive `detectRoute(params)` would clobber the
+            // outer R2/R3 route with UOA_TO_PUSH (the inner `to` is a string, no
+            // `from`), defeating R1-suppression in fireProgressHook.
+            const previousRoute = this.currentRoute;
+            const isRecursiveInnerCall = previousRoute !== undefined;
+            let detectedRoute;
             try {
-                if (!this.accountStatusCache || !this.accountStatusCache.uea.loaded) {
-                    yield ((_a = this.accountStatusReadyPromise) !== null && _a !== void 0 ? _a : this.getAccountStatus());
-                }
-                // If background resolved but cache still empty (timeout/error), fetch fresh
-                if (!this.accountStatusCache || !this.accountStatusCache.uea.loaded) {
-                    yield this.getAccountStatus();
-                }
-                if (((_b = this.accountStatusCache) === null || _b === void 0 ? void 0 : _b.uea.deployed) &&
-                    ((_c = this.accountStatusCache) === null || _c === void 0 ? void 0 : _c.uea.requiresUpgrade)) {
-                    yield this.upgradeAccount({ progressHook: this.progressHook });
-                }
+                detectedRoute = (0, route_detector_1.detectRoute)(params);
             }
-            catch (err) {
-                (0, internals_1.printLog)(this.ctx, `Lazy UEA upgrade check failed: ${err instanceof Error ? err.message : String(err)}. Proceeding with transaction.`);
+            catch (_e) {
+                detectedRoute = route_detector_1.TransactionRoute.UOA_TO_PUSH;
             }
-            // Check if this is a multi-chain request (has ChainTarget or from.chain)
-            const isMultiChain = (0, route_detector_1.isChainTarget)(params.to) || ('from' in params && ((_d = params.from) === null || _d === void 0 ? void 0 : _d.chain));
-            if (isMultiChain) {
-                return (0, internals_1.executeMultiChain)(this.ctx, params, this.execute.bind(this));
-            }
-            // Standard Push Chain execution (Route 1)
-            const execute = params;
-            const hasFunds = !!execute.funds;
-            const hasData = execute.data && execute.data !== '0x';
-            const eventBuffer = [];
-            const originalHook = this.progressHook;
-            this.progressHook = (event) => {
-                eventBuffer.push(event);
-                if (originalHook)
-                    originalHook(event);
-            };
+            // Don't downgrade an outer R2/R3/R4 route when the recursive inner call
+            // resolves to R1 — keep the outer perspective so emission stays consistent.
+            const shouldPreserveOuter = isRecursiveInnerCall &&
+                previousRoute !== route_detector_1.TransactionRoute.UOA_TO_PUSH &&
+                detectedRoute === route_detector_1.TransactionRoute.UOA_TO_PUSH;
+            this.currentRoute = shouldPreserveOuter ? previousRoute : detectedRoute;
+            // Reset the terminal-emitted flag at the start of each execute call so
+            // the outer catch below can tell whether a route handler already fired
+            // a terminal-ish error hook (104-04 / 204-04 / 304-04 / 199-02) and
+            // should suppress the second terminal (199-02 / 299-02 / 399-02).
+            this.ctx._routeTerminalEmitted = false;
             try {
-                const rcb = () => this._getResponseCallbacks();
-                if (execute.funds) {
-                    return !hasData
-                        ? yield (0, internals_1.executeFundsOnly)(this.ctx, execute, eventBuffer, rcb)
-                        : yield (0, internals_1.executeFundsWithPayload)(this.ctx, execute, eventBuffer, rcb);
+                // Lazy UEA upgrade check
+                try {
+                    if (!this.accountStatusCache || !this.accountStatusCache.uea.loaded) {
+                        yield ((_a = this.accountStatusReadyPromise) !== null && _a !== void 0 ? _a : this.getAccountStatus());
+                    }
+                    // If background resolved but cache still empty (timeout/error), fetch fresh
+                    if (!this.accountStatusCache || !this.accountStatusCache.uea.loaded) {
+                        yield this.getAccountStatus();
+                    }
+                    if (((_b = this.accountStatusCache) === null || _b === void 0 ? void 0 : _b.uea.deployed) &&
+                        ((_c = this.accountStatusCache) === null || _c === void 0 ? void 0 : _c.uea.requiresUpgrade)) {
+                        yield this.upgradeAccount({ progressHook: this.progressHook });
+                    }
+                }
+                catch (err) {
+                    (0, internals_1.printLog)(this.ctx, `Lazy UEA upgrade check failed: ${err instanceof Error ? err.message : String(err)}. Proceeding with transaction.`);
+                }
+                // Check if this is a multi-chain request (has ChainTarget or from.chain)
+                const isMultiChain = (0, route_detector_1.isChainTarget)(params.to) || ('from' in params && ((_d = params.from) === null || _d === void 0 ? void 0 : _d.chain));
+                if (isMultiChain) {
+                    return yield (0, internals_1.executeMultiChain)(this.ctx, params, this.execute.bind(this));
+                }
+                // Standard Push Chain execution (Route 1)
+                const execute = params;
+                const hasFunds = !!execute.funds;
+                const hasData = execute.data && execute.data !== '0x';
+                const eventBuffer = [];
+                const originalHook = this.progressHook;
+                this.progressHook = (event) => {
+                    eventBuffer.push(event);
+                    if (originalHook)
+                        originalHook(event);
+                };
+                try {
+                    const rcb = () => this._getResponseCallbacks();
+                    if (execute.funds) {
+                        return !hasData
+                            ? yield (0, internals_1.executeFundsOnly)(this.ctx, execute, eventBuffer, rcb)
+                            : yield (0, internals_1.executeFundsWithPayload)(this.ctx, execute, eventBuffer, rcb);
+                    }
+                    return yield (0, internals_1.executeStandardPayload)(this.ctx, execute, eventBuffer, rcb);
+                }
+                catch (err) {
+                    const errMessage = err instanceof Error
+                        ? err.message
+                        : typeof err === 'string'
+                            ? err
+                            : (() => {
+                                try {
+                                    return JSON.stringify(err);
+                                }
+                                catch (_a) {
+                                    return 'Unknown error';
+                                }
+                            })();
+                    // Only the outermost frame emits the terminal error hook, and it picks
+                    // the route-correct ID. Recursive inner frames just re-throw so the
+                    // outer catch drives emission — avoids double-firing 199/299/399 events.
+                    // Additionally, if an inner route handler already fired a terminal-ish
+                    // error (104-04/204-04/304-04/199-02 via execute-standard), the flag is
+                    // set on ctx and we skip emitting a second terminal here.
+                    if (!isRecursiveInnerCall && !this.ctx._routeTerminalEmitted) {
+                        // For R3, the failure surfaced during execute-phase (pre-wait) is a
+                        // Push-chain-side failure — tag phase='push' so 399-02 renders the
+                        // correct "Push Chain Tx Failed" title instead of the inbound copy.
+                        if (this.currentRoute === route_detector_1.TransactionRoute.CEA_TO_PUSH) {
+                            (0, internals_1.fireProgressHook)(this.ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02, errMessage, 'push');
+                        }
+                        else {
+                            const terminalId = this.currentRoute === route_detector_1.TransactionRoute.UOA_TO_CEA
+                                ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02
+                                : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02;
+                            (0, internals_1.fireProgressHook)(this.ctx, terminalId, errMessage);
+                        }
+                    }
+                    throw err;
+                }
+                finally {
+                    // Restore original progressHook
+                    this.progressHook = originalHook;
                 }
-                return yield (0, internals_1.executeStandardPayload)(this.ctx, execute, eventBuffer, rcb);
-            }
-            catch (err) {
-                const errMessage = err instanceof Error
-                    ? err.message
-                    : typeof err === 'string'
-                        ? err
-                        : (() => {
-                            try {
-                                return JSON.stringify(err);
-                            }
-                            catch (_a) {
-                                return 'Unknown error';
-                            }
-                        })();
-                (0, internals_1.fireProgressHook)(this.ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_99_02, errMessage);
-                throw err;
             }
             finally {
-                // Restore original progressHook
-                this.progressHook = originalHook;
+                // Restore the caller's route so a recursive inner R1 execute doesn't
+                // leak its UOA_TO_PUSH route back to the outer R2/R3 frame.
+                this.currentRoute = previousRoute;
             }
         });
     }
@@ -219,9 +271,9 @@ class Orchestrator {
     /**
      * Queries gas fee for an outbound transaction from the UniversalCore contract.
      */
-    queryOutboundGasFee(prc20Token, gasLimit) {
+    queryOutboundGasFee(prc20Token, gasLimit, destinationChain) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            return (0, internals_1.queryOutboundGasFee)(this.ctx, prc20Token, gasLimit);
+            return (0, internals_1.queryOutboundGasFee)(this.ctx, prc20Token, gasLimit, destinationChain);
         });
     }
     /**