@pushchain/core 5.1.5-alpha.1 → 5.1.6

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

@@ -22,14 +22,17 @@ const route_detector_1 = require("../route-detector");
 const cea_utils_1 = require("../cea-utils");
 const payload_builders_1 = require("../payload-builders");
 const push_chain_1 = require("../../push-chain/push-chain");
+const context_1 = require("./context");
 const helpers_1 = require("./helpers");
 const payload_builder_1 = require("./payload-builder");
 const uea_manager_1 = require("./uea-manager");
 const gas_calculator_1 = require("./gas-calculator");
+const abi_1 = require("../../constants/abi");
 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_route_hooks_1 = require("./progress-route-hooks");
 const progress_hook_1 = tslib_1.__importDefault(require("../../progress-hook/progress-hook"));
+const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
+const build_payload_1 = require("../svm-idl/build-payload");
 // ============================================================================
 // prepareTransaction
 // ============================================================================
@@ -133,21 +136,29 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                         burnAmount = params.value;
                     }
                     else if (hasSvmExecute) {
+                        // PAYLOAD-only SVM execute: still need native PRC-20 for chain namespace
+                        // + gas fees, but burn amount must be zero. Matches executeUoaToCeaSvm
+                        // (route-handlers.ts) and the EVM cascade branch below.
+                        // Using burnAmount=1 would trigger transferFrom on the PRC-20 token,
+                        // which reverts with InsufficientBalance when the UEA has no pSOL balance.
                         prc20Token = (0, helpers_1.getNativePRC20ForChain)(targetChain, ctx.pushNetwork);
-                        burnAmount = BigInt(1);
+                        burnAmount = BigInt(0);
                     }
                     let gasToken = selectors_1.ZERO_ADDRESS;
                     let gasFee = BigInt(0);
+                    let sizing;
                     if (prc20Token !== selectors_1.ZERO_ADDRESS) {
-                        const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit);
+                        const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit, targetChain);
                         gasToken = result.gasToken;
                         gasFee = result.gasFee;
+                        sizing = result.sizing;
                     }
                     return Object.assign(Object.assign({}, baseDescriptor), { targetChain, isSvmTarget: true, svmPayload,
                         prc20Token,
                         burnAmount,
                         gasToken,
-                        gasFee });
+                        gasFee,
+                        sizing });
                 }
                 // EVM path: Resolve CEA address + build CEA multicalls
                 const { cea: ceaAddress } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, targetChain, (_c = ctx.rpcUrls[targetChain]) === null || _c === void 0 ? void 0 : _c[0]);
@@ -157,16 +168,18 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                     const burnAmount = BigInt(0); // Migration is logic-only — no funds. CEA rejects msg.value != 0.
                     let gasToken = selectors_1.ZERO_ADDRESS;
                     let gasFee = BigInt(0);
+                    let sizing;
                     if (prc20Token !== selectors_1.ZERO_ADDRESS) {
-                        const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit);
+                        const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit, targetChain);
                         gasToken = result.gasToken;
                         gasFee = result.gasFee;
+                        sizing = result.sizing;
                     }
                     return Object.assign(Object.assign({}, baseDescriptor), { targetChain,
                         ceaAddress, ceaMulticalls: [], prc20Token,
                         burnAmount,
                         gasToken,
-                        gasFee, isMigration: true });
+                        gasFee, isMigration: true, sizing });
                 }
                 // Build CEA multicalls
                 const ceaMulticalls = [];
@@ -240,10 +253,12 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                 // Query gas fee
                 let gasToken = selectors_1.ZERO_ADDRESS;
                 let gasFee = BigInt(0);
+                let sizing;
                 if (prc20Token !== selectors_1.ZERO_ADDRESS) {
-                    const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit);
+                    const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit, targetChain);
                     gasToken = result.gasToken;
                     gasFee = result.gasFee;
+                    sizing = result.sizing;
                 }
                 return Object.assign(Object.assign({}, baseDescriptor), { targetChain,
                     ceaAddress,
@@ -251,7 +266,8 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                     prc20Token,
                     burnAmount,
                     gasToken,
-                    gasFee });
+                    gasFee,
+                    sizing });
             }
             case route_detector_1.TransactionRoute.CEA_TO_PUSH: {
                 // Route 3: Build CEA multicalls for sendUniversalTxFromCEA
@@ -292,13 +308,16 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                     }
                     let gasToken = selectors_1.ZERO_ADDRESS;
                     let gasFee = BigInt(0);
+                    let sizing;
                     if (prc20Token !== selectors_1.ZERO_ADDRESS) {
-                        const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit);
+                        const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit, sourceChain);
                         gasToken = result.gasToken;
                         gasFee = result.gasFee;
+                        sizing = result.sizing;
                     }
                     return Object.assign(Object.assign({}, baseDescriptor), { sourceChain, ceaAddress: ceaPdaHex, isSvmTarget: true, prc20Token, burnAmount: amount, gasToken,
-                        gasFee });
+                        gasFee,
+                        sizing });
                 }
                 const { cea: ceaAddress } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, sourceChain, (_h = ctx.rpcUrls[sourceChain]) === null || _h === void 0 ? void 0 : _h[0]);
                 // CEA auto-deploys on-chain: Vault.finalizeUniversalTx calls CEAFactory.deployCEA()
@@ -328,15 +347,18 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                 const prc20Token = (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork);
                 let gasToken = selectors_1.ZERO_ADDRESS;
                 let gasFee = BigInt(0);
+                let sizing;
                 if (prc20Token !== selectors_1.ZERO_ADDRESS) {
-                    const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit);
+                    const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit, sourceChain);
                     gasToken = result.gasToken;
                     gasFee = result.gasFee;
+                    sizing = result.sizing;
                 }
                 return Object.assign(Object.assign({}, baseDescriptor), { sourceChain,
                     ceaAddress,
                     prc20Token, burnAmount: amount, gasToken,
-                    gasFee });
+                    gasFee,
+                    sizing });
             }
             default:
                 return baseDescriptor;
@@ -356,10 +378,20 @@ function classifyIntoSegments(hops) {
         const chain = hop.targetChain || hop.sourceChain;
         const canMerge = currentSegment &&
             currentSegment.type === segType &&
-            // Same-chain merging for OUTBOUND_TO_CEA (EVM only — SVM hops are atomic)
+            // Same-chain merging for OUTBOUND_TO_CEA (EVM only — SVM hops are atomic).
+            // Same-source merging for INBOUND_FROM_CEA (EVM only) — multiple R3 hops
+            // that share a source chain collapse into ONE CEA→UEA round-trip whose
+            // inbound multicall runs every hop's target op. Without this merge the
+            // cascade composer would nest the second R3 as an outbound from inside
+            // the first inbound's UEA multicall, which fails inside UGPC.
+            // sendUniversalTxOutbound because the UEA holds no PRC20 at that point
+            // (see cascade.ts composeCascade INBOUND_FROM_CEA branch).
             (segType === 'OUTBOUND_TO_CEA'
                 ? currentSegment.targetChain === hop.targetChain && !hop.isSvmTarget
-                : segType === 'PUSH_EXECUTION');
+                : segType === 'INBOUND_FROM_CEA'
+                    ? currentSegment.sourceChain === hop.sourceChain &&
+                        !(0, payload_builders_1.isSvmChain)(hop.sourceChain)
+                    : segType === 'PUSH_EXECUTION');
         if (canMerge && currentSegment) {
             // Merge into current segment
             currentSegment.hops.push(hop);
@@ -379,12 +411,36 @@ function classifyIntoSegments(hops) {
                 currentSegment.gasFee =
                     (currentSegment.gasFee || BigInt(0)) + (hop.gasFee || BigInt(0));
             }
+            else if (segType === 'INBOUND_FROM_CEA') {
+                // Sum burn amounts so the single sendUniversalTxToUEA carries the
+                // combined native value forwarded from CEA back to the UEA.
+                currentSegment.totalBurnAmount =
+                    (currentSegment.totalBurnAmount || BigInt(0)) +
+                        (hop.burnAmount || BigInt(0));
+                if (hop.gasLimit > (currentSegment.gasLimit || BigInt(0))) {
+                    currentSegment.gasLimit = hop.gasLimit;
+                }
+                currentSegment.gasFee =
+                    (currentSegment.gasFee || BigInt(0)) + (hop.gasFee || BigInt(0));
+            }
             else if (segType === 'PUSH_EXECUTION') {
                 currentSegment.mergedPushMulticalls = [
                     ...(currentSegment.mergedPushMulticalls || []),
                     ...(hop.pushMulticalls || []),
                 ];
             }
+            // Merge sizing: take the strictest category (C > B > A). Overflow
+            // from a Case C hop wins so the segment's msg.value covers the
+            // highest-cost hop in the merge.
+            if (hop.sizing) {
+                if (!currentSegment.sizing) {
+                    currentSegment.sizing = hop.sizing;
+                }
+                else if (categoryRank(hop.sizing.category) >
+                    categoryRank(currentSegment.sizing.category)) {
+                    currentSegment.sizing = hop.sizing;
+                }
+            }
         }
         else {
             // Start a new segment
@@ -404,12 +460,17 @@ function classifyIntoSegments(hops) {
                 gasToken: hop.gasToken,
                 gasFee: hop.gasFee,
                 gasLimit: hop.gasLimit,
+                sizing: hop.sizing,
             };
             segments.push(currentSegment);
         }
     }
     return segments;
 }
+/** Ordering for sizing-category severity (higher = stricter). */
+function categoryRank(c) {
+    return c === 'C' ? 2 : c === 'B' ? 1 : 0;
+}
 // ============================================================================
 // getSegmentType
 // ============================================================================
@@ -429,237 +490,365 @@ function getSegmentType(route) {
 // composeCascade
 // ============================================================================
 function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
-    var _a, _b, _c, _d, _e, _f, _g;
-    let accumulatedPushMulticalls = [];
-    const gatewayPcAddress = (0, helpers_1.getUniversalGatewayPCAddress)();
-    // Compute per-outbound nativeValueForGas from UEA balance
-    // Each outbound segment needs native value for the gas swap on the destination chain.
-    // The contract refunds excess, so over-allocating is safe.
-    const numOutbounds = segments.filter((s) => s.type !== 'PUSH_EXECUTION').length;
-    const CASCADE_GAS_RESERVE = BigInt(3e18); // 3 PC reserve for gas costs
-    let perOutboundNativeValue;
-    if (ueaBalance && numOutbounds > 0 && ueaBalance > CASCADE_GAS_RESERVE) {
-        perOutboundNativeValue =
-            (ueaBalance - CASCADE_GAS_RESERVE) / BigInt(numOutbounds);
-    }
-    for (let i = segments.length - 1; i >= 0; i--) {
-        const segment = segments[i];
-        switch (segment.type) {
-            case 'PUSH_EXECUTION': {
-                // Prepend Push Chain multicalls to accumulated
-                accumulatedPushMulticalls = [
-                    ...(segment.mergedPushMulticalls || []),
-                    ...accumulatedPushMulticalls,
-                ];
-                break;
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        let accumulatedPushMulticalls = [];
+        const gatewayPcAddress = (0, helpers_1.getUniversalGatewayPCAddress)();
+        // Compute per-outbound nativeValueForGas from UEA balance
+        // Each outbound segment needs native value for the gas swap on the destination chain.
+        // The contract refunds excess, so over-allocating is safe.
+        const numOutbounds = segments.filter((s) => s.type !== 'PUSH_EXECUTION').length;
+        const CASCADE_GAS_RESERVE = BigInt(3e18); // 3 PC reserve for gas costs
+        let perOutboundNativeValue;
+        if (ueaBalance && numOutbounds > 0 && ueaBalance > CASCADE_GAS_RESERVE) {
+            perOutboundNativeValue =
+                (ueaBalance - CASCADE_GAS_RESERVE) / BigInt(numOutbounds);
+        }
+        // Pool-price-based native-value override for SVM outbounds.
+        // The flat split above works for EVM gas tokens (pBNB/pETH — cheap per unit),
+        // but pSOL has a much higher WPC/pSOL pool price, so the flat 1 PC split is
+        // insufficient to swap for gasFee wei of pSOL and Uniswap reverts "STF".
+        // Mirror executeUoaToCeaSvm's pool-price read (route-handlers.ts) per SVM segment.
+        const svmSegments = segments.filter((s) => {
+            var _a;
+            return s.type === 'OUTBOUND_TO_CEA' &&
+                ((_a = s.hops[0]) === null || _a === void 0 ? void 0 : _a.isSvmTarget) === true &&
+                s.gasToken &&
+                s.gasFee &&
+                s.gasFee > BigInt(0);
+        });
+        const svmNativeValueBySegment = new Map();
+        if (svmSegments.length > 0 && ueaBalance && ueaBalance > CASCADE_GAS_RESERVE) {
+            const universalCoreAddress = yield ctx.pushClient.readContract({
+                address: gatewayPcAddress,
+                abi: abi_1.UNIVERSAL_GATEWAY_PC,
+                functionName: 'UNIVERSAL_CORE',
+                args: [],
+            });
+            // Compute per-SVM budget = ueaBalance − (PC needed for EVM outbounds) − 1 PC safety
+            // (outer-tx gas + refund headroom). Pass a huge accountBalance to the estimator so
+            // its internal cap is effectively disabled; we cap externally to the per-SVM budget.
+            const numEvmOutbounds = numOutbounds - svmSegments.length;
+            const evmReservation = perOutboundNativeValue && numEvmOutbounds > 0
+                ? perOutboundNativeValue * BigInt(numEvmOutbounds)
+                : BigInt(0);
+            const outerSafety = BigInt(1e18); // 1 PC for outer-tx gas
+            const svmTotal = ueaBalance > evmReservation + outerSafety
+                ? ueaBalance - evmReservation - outerSafety
+                : BigInt(0);
+            const perSvmCap = svmTotal / BigInt(svmSegments.length);
+            const UNCAPPED_BALANCE = BigInt(1e30); // effectively disable estimator's internal cap
+            for (const seg of svmSegments) {
+                const estimated = yield (0, gas_calculator_1.estimateNativeValueForSwap)(ctx, universalCoreAddress, seg.gasToken, seg.gasFee, UNCAPPED_BALANCE);
+                const flat = perOutboundNativeValue !== null && perOutboundNativeValue !== void 0 ? perOutboundNativeValue : BigInt(0);
+                let value = estimated > flat ? estimated : flat;
+                if (perSvmCap > BigInt(0) && value > perSvmCap)
+                    value = perSvmCap;
+                (0, context_1.printLog)(ctx, `composeCascade — SVM outbound to ${(_a = seg.hops[0]) === null || _a === void 0 ? void 0 : _a.targetChain}: gasFee=${seg.gasFee}, estimatedWpc=${estimated}, flat=${flat}, perSvmCap=${perSvmCap}, chosen=${value}`);
+                svmNativeValueBySegment.set(seg, value);
             }
-            case 'OUTBOUND_TO_CEA': {
-                const firstHop = segment.hops[0];
-                const isSvmSegment = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.isSvmTarget) === true;
-                let outboundPayload;
-                let targetForOutbound;
-                const isMigration = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.isMigration) === true;
-                if (isSvmSegment) {
-                    // SVM: use the pre-built SVM payload from the hop descriptor
-                    outboundPayload = (_a = firstHop.svmPayload) !== null && _a !== void 0 ? _a : '0x';
-                    // For SVM, to.address IS the target (program for execute, recipient for withdraw)
-                    const svmTarget = firstHop.params.to;
-                    targetForOutbound = svmTarget.address;
-                }
-                else if (isMigration) {
-                    // Migration: use raw 4-byte MIGRATION_SELECTOR, no multicall wrapping
-                    outboundPayload = (0, payload_builders_1.buildMigrationPayload)();
-                    targetForOutbound = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.ceaAddress) || ueaAddress;
-                }
-                else {
-                    // EVM: build CEA payload from merged multicalls
-                    outboundPayload = (0, payload_builders_1.buildCeaMulticallPayload)(segment.mergedCeaMulticalls || []);
-                    // Get CEA address from the first hop
-                    targetForOutbound = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.ceaAddress) || ueaAddress;
+        }
+        for (let i = segments.length - 1; i >= 0; i--) {
+            const segment = segments[i];
+            switch (segment.type) {
+                case 'PUSH_EXECUTION': {
+                    // Prepend Push Chain multicalls to accumulated
+                    accumulatedPushMulticalls = [
+                        ...(segment.mergedPushMulticalls || []),
+                        ...accumulatedPushMulticalls,
+                    ];
+                    break;
                 }
-                // Build outbound request
-                const outboundReq = (0, payload_builders_1.buildOutboundRequest)(targetForOutbound, segment.prc20Token || selectors_1.ZERO_ADDRESS, segment.totalBurnAmount || BigInt(0), (_b = segment.gasLimit) !== null && _b !== void 0 ? _b : BigInt(0), outboundPayload, ueaAddress);
-                // Build approval + outbound multicalls
-                const segGasFee = segment.gasFee || BigInt(0);
-                const outboundMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
-                    prc20Token: segment.prc20Token || selectors_1.ZERO_ADDRESS,
-                    gasToken: segment.gasToken || selectors_1.ZERO_ADDRESS,
-                    burnAmount: segment.totalBurnAmount || BigInt(0),
-                    gasFee: segGasFee,
-                    nativeValueForGas: perOutboundNativeValue !== null && perOutboundNativeValue !== void 0 ? perOutboundNativeValue : segGasFee * BigInt(1000),
-                    gatewayPcAddress,
-                    outboundRequest: outboundReq,
-                });
-                // Prepend to accumulated
-                accumulatedPushMulticalls = [
-                    ...outboundMulticalls,
-                    ...accumulatedPushMulticalls,
-                ];
-                break;
-            }
-            case 'INBOUND_FROM_CEA': {
-                // The accumulated multicalls = what runs on Push Chain AFTER inbound arrives.
-                // Wrap in UniversalPayload struct with correct UEA nonce for the relay.
-                // Build push multicalls from this hop's own data (e.g., counter.increment())
-                // This is the Route 3 hop's payload that executes on Push Chain after inbound.
-                const hop0 = segment.hops[0];
-                if ((_c = hop0 === null || hop0 === void 0 ? void 0 : hop0.params) === null || _c === void 0 ? void 0 : _c.data) {
-                    const hopPushMulticalls = (0, payload_builders_1.buildExecuteMulticall)({
-                        execute: {
-                            to: hop0.params.to,
-                            value: hop0.params.value,
-                            data: hop0.params.data,
-                        },
-                        ueaAddress,
+                case 'OUTBOUND_TO_CEA': {
+                    const firstHop = segment.hops[0];
+                    const isSvmSegment = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.isSvmTarget) === true;
+                    let outboundPayload;
+                    let targetForOutbound;
+                    const isMigration = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.isMigration) === true;
+                    if (isSvmSegment) {
+                        // SVM: use the pre-built SVM payload from the hop descriptor
+                        outboundPayload = (_b = firstHop.svmPayload) !== null && _b !== void 0 ? _b : '0x';
+                        // For SVM, to.address IS the target (program for execute, recipient for withdraw)
+                        const svmTarget = firstHop.params.to;
+                        targetForOutbound = svmTarget.address;
+                    }
+                    else if (isMigration) {
+                        // Migration: use raw 4-byte MIGRATION_SELECTOR, no multicall wrapping
+                        outboundPayload = (0, payload_builders_1.buildMigrationPayload)();
+                        targetForOutbound = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.ceaAddress) || ueaAddress;
+                    }
+                    else {
+                        // EVM: build CEA payload from merged multicalls
+                        outboundPayload = (0, payload_builders_1.buildCeaMulticallPayload)(segment.mergedCeaMulticalls || []);
+                        // Get CEA address from the first hop
+                        targetForOutbound = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.ceaAddress) || ueaAddress;
+                    }
+                    // Build outbound request
+                    const outboundReq = (0, payload_builders_1.buildOutboundRequest)(targetForOutbound, segment.prc20Token || selectors_1.ZERO_ADDRESS, segment.totalBurnAmount || BigInt(0), (_c = segment.gasLimit) !== null && _c !== void 0 ? _c : BigInt(0), outboundPayload, ueaAddress);
+                    // Build approval + outbound multicalls
+                    const segGasFee = segment.gasFee || BigInt(0);
+                    const svmOverride = svmNativeValueBySegment.get(segment);
+                    // When UEA balance < CASCADE_GAS_RESERVE, perOutboundNativeValue is
+                    // undefined. Mirror the drained-UEA branch in executeUoaToCea
+                    // (route-handlers.ts): send the entire available balance divided
+                    // across outbound segments. The contract refunds excess via
+                    // swapAndBurnGas, so overshooting is safe; undershooting causes STF.
+                    let evmFallbackValue;
+                    if (ueaBalance && ueaBalance > BigInt(0)) {
+                        evmFallbackValue = ueaBalance / BigInt(Math.max(numOutbounds, 1));
+                    }
+                    else {
+                        evmFallbackValue = segGasFee * BigInt(1000000);
+                    }
+                    let nativeValueForGas = (_d = svmOverride !== null && svmOverride !== void 0 ? svmOverride : perOutboundNativeValue) !== null && _d !== void 0 ? _d : evmFallbackValue;
+                    // SDK 5.2 Case C: when the segment's sizing is category C, compose
+                    // R2/OUTBOUND_TO_CEA segments no longer apply Case A/B/C sizing
+                    // (scoped to R1 + R3 only). segment.sizing may still be populated
+                    // from the hop descriptor merge, but it is not consulted here —
+                    // nativeValueForGas is driven by pool-quote on the single-hop path
+                    // and by the cascade-level per-outbound allocation above.
+                    const outboundMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
+                        prc20Token: segment.prc20Token || selectors_1.ZERO_ADDRESS,
+                        gasToken: segment.gasToken || selectors_1.ZERO_ADDRESS,
+                        burnAmount: segment.totalBurnAmount || BigInt(0),
+                        gasFee: segGasFee,
+                        nativeValueForGas,
+                        gatewayPcAddress,
+                        outboundRequest: outboundReq,
                     });
-                    // Prepend the Route 3's own push calls before subsequent hops
+                    // Prepend to accumulated
                     accumulatedPushMulticalls = [
-                        ...hopPushMulticalls,
+                        ...outboundMulticalls,
                         ...accumulatedPushMulticalls,
                     ];
+                    break;
                 }
-                let intermediatePayload = '0x';
-                if (accumulatedPushMulticalls.length > 0) {
-                    const multicallPayload = (0, payload_builder_1.buildMulticallPayloadData)(ctx, ueaAddress, accumulatedPushMulticalls);
-                    // +1: the outbound tx consumes one nonce via execute()
-                    intermediatePayload = (0, payload_builders_1.buildInboundUniversalPayload)(multicallPayload, { nonce: (ueaNonce !== null && ueaNonce !== void 0 ? ueaNonce : BigInt(0)) + BigInt(1) });
-                }
-                const hop = segment.hops[0];
-                const sourceChain = hop.sourceChain;
-                const ceaAddress = hop.ceaAddress || ueaAddress;
-                // SVM chains: build SVM CPI payload instead of EVM CEA multicall
-                if ((0, payload_builders_1.isSvmChain)(sourceChain)) {
-                    const lockerContract = chain_1.CHAIN_INFO[sourceChain].lockerContract;
-                    if (!lockerContract) {
-                        throw new Error(`No SVM gateway program configured for chain ${sourceChain}`);
+                case 'INBOUND_FROM_CEA': {
+                    // The accumulated multicalls = what runs on Push Chain AFTER inbound arrives.
+                    // Wrap in UniversalPayload struct with correct UEA nonce for the relay.
+                    // Build push multicalls from EVERY merged hop's own data in original
+                    // order (e.g. counter.increment() + value transfer). Multi-hop R3
+                    // segments (same sourceChain) bundle all target ops into the single
+                    // UEA multicall so no nested outbound is needed.
+                    const mergedHopMulticalls = [];
+                    for (const h of segment.hops) {
+                        if (((_e = h === null || h === void 0 ? void 0 : h.params) === null || _e === void 0 ? void 0 : _e.data) || ((_f = h === null || h === void 0 ? void 0 : h.params) === null || _f === void 0 ? void 0 : _f.value)) {
+                            const hopCalls = (0, payload_builders_1.buildExecuteMulticall)({
+                                execute: {
+                                    to: h.params.to,
+                                    value: h.params.value,
+                                    data: h.params.data,
+                                },
+                                ueaAddress,
+                            });
+                            mergedHopMulticalls.push(...hopCalls);
+                        }
                     }
-                    const programPk = new web3_js_1.PublicKey(lockerContract);
-                    const gatewayProgramHex = ('0x' +
-                        Buffer.from(programPk.toBytes()).toString('hex'));
-                    let drainAmount = BigInt(0);
-                    let tokenMintHex;
-                    const params = hop.params;
-                    if (((_d = params.funds) === null || _d === void 0 ? void 0 : _d.amount) && params.funds.amount > BigInt(0)) {
-                        drainAmount = params.funds.amount;
-                        const token = params.funds.token;
-                        if (token && token.address) {
-                            const mintPk = new web3_js_1.PublicKey(token.address);
-                            tokenMintHex = ('0x' +
-                                Buffer.from(mintPk.toBytes()).toString('hex'));
+                    if (mergedHopMulticalls.length > 0) {
+                        accumulatedPushMulticalls = [
+                            ...mergedHopMulticalls,
+                            ...accumulatedPushMulticalls,
+                        ];
+                    }
+                    // Primary hop carries the sourceChain / CEA address (shared across merged hops).
+                    const hop0 = segment.hops[0];
+                    let intermediatePayload = '0x';
+                    if (accumulatedPushMulticalls.length > 0) {
+                        const multicallPayload = (0, payload_builder_1.buildMulticallPayloadData)(ctx, ueaAddress, accumulatedPushMulticalls);
+                        // +1: the outbound tx consumes one nonce via execute()
+                        intermediatePayload = (0, payload_builders_1.buildInboundUniversalPayload)(multicallPayload, { nonce: (ueaNonce !== null && ueaNonce !== void 0 ? ueaNonce : BigInt(0)) + BigInt(1) });
+                    }
+                    const hop = segment.hops[0];
+                    const sourceChain = hop.sourceChain;
+                    const ceaAddress = hop.ceaAddress || ueaAddress;
+                    // SVM chains: build SVM CPI payload instead of EVM CEA multicall
+                    if ((0, payload_builders_1.isSvmChain)(sourceChain)) {
+                        const lockerContract = chain_1.CHAIN_INFO[sourceChain].lockerContract;
+                        if (!lockerContract) {
+                            throw new Error(`No SVM gateway program configured for chain ${sourceChain}`);
                         }
+                        const programPk = new web3_js_1.PublicKey(lockerContract);
+                        const gatewayProgramHex = ('0x' +
+                            Buffer.from(programPk.toBytes()).toString('hex'));
+                        let drainAmount = BigInt(0);
+                        let tokenMintHex;
+                        const params = hop.params;
+                        if (((_g = params.funds) === null || _g === void 0 ? void 0 : _g.amount) && params.funds.amount > BigInt(0)) {
+                            drainAmount = params.funds.amount;
+                            const token = params.funds.token;
+                            if (token && token.address) {
+                                const mintPk = new web3_js_1.PublicKey(token.address);
+                                tokenMintHex = ('0x' +
+                                    Buffer.from(mintPk.toBytes()).toString('hex'));
+                            }
+                        }
+                        else if (params.value && params.value > BigInt(0)) {
+                            drainAmount = params.value;
+                        }
+                        // Derive CEA PDA as revert recipient
+                        const ueaBytes = Buffer.from(ueaAddress.slice(2), 'hex');
+                        const [ceaPda] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from('push_identity'), ueaBytes], programPk);
+                        const ceaPdaHex = ('0x' +
+                            Buffer.from(ceaPda.toBytes()).toString('hex'));
+                        // Build SVM payload with intermediate Push Chain payload embedded
+                        const svmPayload = (0, payload_builders_1.encodeSvmCeaToUeaPayload)({
+                            gatewayProgramHex,
+                            drainAmount,
+                            tokenMintHex,
+                            revertRecipientHex: ceaPdaHex,
+                            extraPayload: intermediatePayload !== '0x'
+                                ? new Uint8Array(Buffer.from(intermediatePayload.slice(2), 'hex'))
+                                : undefined,
+                        });
+                        const svmBurnAmount = segment.totalBurnAmount || BigInt(0);
+                        const outboundReq = (0, payload_builders_1.buildOutboundRequest)(gatewayProgramHex, segment.prc20Token ||
+                            (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork), svmBurnAmount, (_h = segment.gasLimit) !== null && _h !== void 0 ? _h : BigInt(0), svmPayload, ueaAddress);
+                        const inboundGasFee = segment.gasFee || BigInt(0);
+                        let svmInboundFallback;
+                        if (ueaBalance && ueaBalance > BigInt(0)) {
+                            svmInboundFallback = ueaBalance / BigInt(Math.max(numOutbounds, 1));
+                        }
+                        else {
+                            svmInboundFallback = inboundGasFee * BigInt(1000000);
+                        }
+                        let svmInboundNativeValue = perOutboundNativeValue !== null && perOutboundNativeValue !== void 0 ? perOutboundNativeValue : svmInboundFallback;
+                        // SDK 5.2 R3-style Case C bump: when the inbound segment's sizing
+                        // is C, top up the swap budget by the overflow. No bridge-swap —
+                        // R3 has no destination funds delivery.
+                        if (((_j = segment.sizing) === null || _j === void 0 ? void 0 : _j.category) === 'C' &&
+                            segment.sizing.overflowNativePc > BigInt(0)) {
+                            const bumped = svmInboundNativeValue + segment.sizing.overflowNativePc;
+                            (0, context_1.printLog)(ctx, `composeCascade — INBOUND_FROM_CEA (SVM) Case C: bumping nativeValueForGas from ${svmInboundNativeValue} to ${bumped} (overflow=${segment.sizing.overflowNativePc})`);
+                            svmInboundNativeValue = bumped;
+                        }
+                        const outboundMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
+                            prc20Token: segment.prc20Token ||
+                                (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork),
+                            gasToken: segment.gasToken || selectors_1.ZERO_ADDRESS,
+                            burnAmount: svmBurnAmount,
+                            gasFee: inboundGasFee,
+                            nativeValueForGas: svmInboundNativeValue,
+                            gatewayPcAddress,
+                            outboundRequest: outboundReq,
+                        });
+                        accumulatedPushMulticalls = [...outboundMulticalls];
+                        break;
                     }
-                    else if (params.value && params.value > BigInt(0)) {
-                        drainAmount = params.value;
+                    // EVM path: Build CEA multicall: [approve?, sendUniversalTxFromCEA(payload)]
+                    const ceaMulticalls = [];
+                    // Add primary hop's own CEA operations if any
+                    // (e.g., approve + swap before bridging back)
+                    if (hop.ceaMulticalls && hop.ceaMulticalls.length > 0) {
+                        ceaMulticalls.push(...hop.ceaMulticalls);
                     }
-                    // Derive CEA PDA as revert recipient
-                    const ueaBytes = Buffer.from(ueaAddress.slice(2), 'hex');
-                    const [ceaPda] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from('push_identity'), ueaBytes], programPk);
-                    const ceaPdaHex = ('0x' +
-                        Buffer.from(ceaPda.toBytes()).toString('hex'));
-                    // Build SVM payload with intermediate Push Chain payload embedded
-                    const svmPayload = (0, payload_builders_1.encodeSvmCeaToUeaPayload)({
-                        gatewayProgramHex,
-                        drainAmount,
-                        tokenMintHex,
-                        revertRecipientHex: ceaPdaHex,
-                        extraPayload: intermediatePayload !== '0x'
-                            ? new Uint8Array(Buffer.from(intermediatePayload.slice(2), 'hex'))
-                            : undefined,
-                    });
-                    const svmBurnAmount = segment.totalBurnAmount || BigInt(0);
-                    const outboundReq = (0, payload_builders_1.buildOutboundRequest)(gatewayProgramHex, segment.prc20Token ||
-                        (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork), svmBurnAmount, (_e = segment.gasLimit) !== null && _e !== void 0 ? _e : BigInt(0), svmPayload, ueaAddress);
+                    // Aggregate token/amount across all merged hops so the single
+                    // sendUniversalTxToUEA call carries the combined forward amount.
+                    // For multi-hop R3 segments (same sourceChain), ERC20 funds across
+                    // hops must resolve to the same token — otherwise this path can't
+                    // express it in one call and the caller should split manually.
+                    let tokenAddress = selectors_1.ZERO_ADDRESS;
+                    let amount = BigInt(0);
+                    for (const mergedHop of segment.hops) {
+                        const hParams = mergedHop.params;
+                        if ((_k = hParams.funds) === null || _k === void 0 ? void 0 : _k.amount) {
+                            const token = hParams.funds.token;
+                            if (token) {
+                                if (token.mechanism === 'native') {
+                                    amount += hParams.funds.amount;
+                                }
+                                else {
+                                    const addr = token.address;
+                                    if (tokenAddress !== selectors_1.ZERO_ADDRESS &&
+                                        tokenAddress.toLowerCase() !== addr.toLowerCase()) {
+                                        throw new Error(`composeCascade: merged R3 hops target different ERC20 tokens (${tokenAddress} vs ${addr}); split into separate executeTransactions batches`);
+                                    }
+                                    tokenAddress = addr;
+                                    amount += hParams.funds.amount;
+                                    // CEA approves gateway once with the cumulative allowance.
+                                    const gatewayAddr = chain_1.UNIVERSAL_GATEWAY_ADDRESSES[sourceChain];
+                                    if (!gatewayAddr) {
+                                        throw new Error(`No UniversalGateway address configured for chain ${sourceChain}`);
+                                    }
+                                    // Reset allowance to 0 first for USDT-style tokens
+                                    const approveZeroData = (0, viem_1.encodeFunctionData)({
+                                        abi: erc20_evm_1.ERC20_EVM,
+                                        functionName: 'approve',
+                                        args: [gatewayAddr, BigInt(0)],
+                                    });
+                                    ceaMulticalls.push({
+                                        to: tokenAddress,
+                                        value: BigInt(0),
+                                        data: approveZeroData,
+                                    });
+                                    const approveData = (0, viem_1.encodeFunctionData)({
+                                        abi: erc20_evm_1.ERC20_EVM,
+                                        functionName: 'approve',
+                                        args: [gatewayAddr, hParams.funds.amount],
+                                    });
+                                    ceaMulticalls.push({
+                                        to: tokenAddress,
+                                        value: BigInt(0),
+                                        data: approveData,
+                                    });
+                                }
+                            }
+                        }
+                        else if (hParams.value && hParams.value > BigInt(0)) {
+                            amount += hParams.value;
+                        }
+                    }
+                    // Build sendUniversalTxToUEA self-call on CEA (to=CEA, value=0)
+                    const sendCall = (0, payload_builders_1.buildSendUniversalTxToUEA)(ceaAddress, tokenAddress, amount, intermediatePayload, ceaAddress);
+                    ceaMulticalls.push(sendCall);
+                    // Wrap CEA multicall in outbound from Push Chain
+                    const ceaPayload = (0, payload_builders_1.buildCeaMulticallPayload)(ceaMulticalls);
+                    // The nested outbound back to the source chain needs a non-zero
+                    // gasLimit — UGPC.sendUniversalTxOutbound reverts with
+                    // "Missing or invalid parameters" on 0. When the hop didn't supply
+                    // one (typical for a pure-R3 leg composed inside a cascade), fall
+                    // back to DEFAULT_OUTBOUND_GAS_LIMIT just like the initial outbound
+                    // path does.
+                    const effectiveGasLimit = segment.gasLimit && segment.gasLimit > BigInt(0)
+                        ? segment.gasLimit
+                        : selectors_1.DEFAULT_OUTBOUND_GAS_LIMIT;
+                    const outboundReq = (0, payload_builders_1.buildOutboundRequest)(ceaAddress, segment.prc20Token ||
+                        (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork), segment.totalBurnAmount || BigInt(0), effectiveGasLimit, ceaPayload, ueaAddress);
                     const inboundGasFee = segment.gasFee || BigInt(0);
+                    let evmInboundFallback;
+                    if (ueaBalance && ueaBalance > BigInt(0)) {
+                        evmInboundFallback = ueaBalance / BigInt(Math.max(numOutbounds, 1));
+                    }
+                    else {
+                        evmInboundFallback = inboundGasFee * BigInt(1000000);
+                    }
+                    let evmInboundNativeValue = perOutboundNativeValue !== null && perOutboundNativeValue !== void 0 ? perOutboundNativeValue : evmInboundFallback;
+                    // SDK 5.2 R3-style Case C bump: when the inbound segment's sizing
+                    // is C, top up the swap budget by the overflow. No bridge-swap —
+                    // R3 has no destination funds delivery.
+                    if (((_l = segment.sizing) === null || _l === void 0 ? void 0 : _l.category) === 'C' &&
+                        segment.sizing.overflowNativePc > BigInt(0)) {
+                        const bumped = evmInboundNativeValue + segment.sizing.overflowNativePc;
+                        (0, context_1.printLog)(ctx, `composeCascade — INBOUND_FROM_CEA (EVM) Case C: bumping nativeValueForGas from ${evmInboundNativeValue} to ${bumped} (overflow=${segment.sizing.overflowNativePc})`);
+                        evmInboundNativeValue = bumped;
+                    }
                     const outboundMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
                         prc20Token: segment.prc20Token ||
                             (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork),
                         gasToken: segment.gasToken || selectors_1.ZERO_ADDRESS,
-                        burnAmount: svmBurnAmount,
+                        burnAmount: segment.totalBurnAmount || BigInt(0),
                         gasFee: inboundGasFee,
-                        nativeValueForGas: perOutboundNativeValue !== null && perOutboundNativeValue !== void 0 ? perOutboundNativeValue : inboundGasFee * BigInt(1000),
+                        nativeValueForGas: evmInboundNativeValue,
                         gatewayPcAddress,
                         outboundRequest: outboundReq,
                     });
+                    // Reset accumulated -- everything is now inside this outbound
                     accumulatedPushMulticalls = [...outboundMulticalls];
                     break;
                 }
-                // EVM path: Build CEA multicall: [approve?, sendUniversalTxFromCEA(payload)]
-                const ceaMulticalls = [];
-                // Add hop's own CEA operations if any
-                // (e.g., approve + swap before bridging back)
-                if (hop.ceaMulticalls && hop.ceaMulticalls.length > 0) {
-                    ceaMulticalls.push(...hop.ceaMulticalls);
-                }
-                // Determine token/amount for inbound
-                let tokenAddress = selectors_1.ZERO_ADDRESS;
-                let amount = BigInt(0);
-                const params = hop.params;
-                if ((_f = params.funds) === null || _f === void 0 ? void 0 : _f.amount) {
-                    const token = params.funds.token;
-                    if (token) {
-                        if (token.mechanism === 'native') {
-                            amount = params.funds.amount;
-                        }
-                        else {
-                            tokenAddress = token.address;
-                            amount = params.funds.amount;
-                            // Add approve for ERC20 (CEA approves gateway)
-                            const gatewayAddr = chain_1.UNIVERSAL_GATEWAY_ADDRESSES[sourceChain];
-                            if (!gatewayAddr) {
-                                throw new Error(`No UniversalGateway address configured for chain ${sourceChain}`);
-                            }
-                            // Reset allowance to 0 first for USDT-style tokens
-                            const approveZeroData = (0, viem_1.encodeFunctionData)({
-                                abi: erc20_evm_1.ERC20_EVM,
-                                functionName: 'approve',
-                                args: [gatewayAddr, BigInt(0)],
-                            });
-                            ceaMulticalls.push({
-                                to: tokenAddress,
-                                value: BigInt(0),
-                                data: approveZeroData,
-                            });
-                            const approveData = (0, viem_1.encodeFunctionData)({
-                                abi: erc20_evm_1.ERC20_EVM,
-                                functionName: 'approve',
-                                args: [gatewayAddr, amount],
-                            });
-                            ceaMulticalls.push({
-                                to: tokenAddress,
-                                value: BigInt(0),
-                                data: approveData,
-                            });
-                        }
-                    }
-                }
-                else if (params.value && params.value > BigInt(0)) {
-                    amount = params.value;
-                }
-                // Build sendUniversalTxToUEA self-call on CEA (to=CEA, value=0)
-                const sendCall = (0, payload_builders_1.buildSendUniversalTxToUEA)(ceaAddress, tokenAddress, amount, intermediatePayload, ceaAddress);
-                ceaMulticalls.push(sendCall);
-                // Wrap CEA multicall in outbound from Push Chain
-                const ceaPayload = (0, payload_builders_1.buildCeaMulticallPayload)(ceaMulticalls);
-                const outboundReq = (0, payload_builders_1.buildOutboundRequest)(ceaAddress, segment.prc20Token ||
-                    (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork), segment.totalBurnAmount || BigInt(0), (_g = segment.gasLimit) !== null && _g !== void 0 ? _g : BigInt(0), ceaPayload, ueaAddress);
-                const inboundGasFee = segment.gasFee || BigInt(0);
-                const outboundMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
-                    prc20Token: segment.prc20Token ||
-                        (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork),
-                    gasToken: segment.gasToken || selectors_1.ZERO_ADDRESS,
-                    burnAmount: segment.totalBurnAmount || BigInt(0),
-                    gasFee: inboundGasFee,
-                    nativeValueForGas: perOutboundNativeValue !== null && perOutboundNativeValue !== void 0 ? perOutboundNativeValue : inboundGasFee * BigInt(1000),
-                    gatewayPcAddress,
-                    outboundRequest: outboundReq,
-                });
-                // Reset accumulated -- everything is now inside this outbound
-                accumulatedPushMulticalls = [...outboundMulticalls];
-                break;
             }
         }
-    }
-    return accumulatedPushMulticalls;
+        return accumulatedPushMulticalls;
+    });
 }
 // ============================================================================
 // createCascadedBuilder
@@ -752,7 +941,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
             const ueaNonceCascade = ueaCodeCascade !== undefined
                 ? yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress)
                 : BigInt(0);
-            const composedMulticalls = composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonceCascade);
+            const composedMulticalls = yield composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonceCascade);
             // Execute the composed multicall as a single Push Chain tx
             const executeParams = {
                 to: ueaAddress,
@@ -777,14 +966,77 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                 hops: hopInfos,
                 hopCount: hops.length,
                 waitForAll: (opts) => tslib_1.__awaiter(this, void 0, void 0, function* () {
-                    var _a, _b;
+                    var _a, _b, _c, _d, _e;
                     const { pollingIntervalMs = 10000, timeout = 300000, progressHook: cascadeProgressHook, eventHook, } = opts || {};
                     const startTime = Date.now();
+                    // Per-hop progress emission. Drops events whose id is '' (the no-op
+                    // sentinel returned by pickWaitHooks for R4/unknown routes), so
+                    // consumers don't see placeholder events while the cascade still
+                    // drives its own state machine.
+                    const emitHopEvent = (hook, event) => {
+                        if (!hook || !event.id)
+                            return;
+                        hook(event);
+                    };
+                    // ---- Multichain (multi-hop) cascade markers (001 / 002 / 999) ----
+                    // Only fire when this is genuinely a multi-hop cascade. Single-hop
+                    // R1/R2 takes the early-return paths above and never reaches here,
+                    // but guard explicitly in case someone wires a 1-element prepared list.
+                    const totalHops = hopInfos.length;
+                    const isMulti = totalHops > 1;
+                    const chainLabels = hops.map((h) => {
+                        var _a, _b;
+                        return String((_b = (_a = h.targetChain) !== null && _a !== void 0 ? _a : h.sourceChain) !== null && _b !== void 0 ? _b : (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork));
+                    });
+                    const signerOriginChain = String((_a = ctx.universalSigner.account.chain) !== null && _a !== void 0 ? _a : 'origin');
+                    const emitHopStart = (hopIndex0) => {
+                        if (!isMulti)
+                            return;
+                        const n = hopIndex0 + 1;
+                        const fromChain = hopIndex0 === 0
+                            ? signerOriginChain
+                            : chainLabels[hopIndex0 - 1];
+                        const toChain = chainLabels[hopIndex0];
+                        emitHopEvent(eventHook, progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_002_01](n, totalHops, fromChain, toChain));
+                    };
+                    const emitHopComplete = (hopIndex0) => {
+                        if (!isMulti)
+                            return;
+                        const n = hopIndex0 + 1;
+                        if (n >= totalHops)
+                            return; // skip after final hop — 999-01 takes over
+                        emitHopEvent(eventHook, progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_002_99_99](n, totalHops));
+                    };
+                    const emitCascadeSuccess = () => {
+                        if (!isMulti)
+                            return;
+                        emitHopEvent(eventHook, progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_01](totalHops));
+                    };
+                    const emitCascadeFailed = (failedIdx0, errMsg) => {
+                        if (!isMulti)
+                            return;
+                        emitHopEvent(eventHook, progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_02](failedIdx0 + 1, totalHops, errMsg));
+                    };
+                    const emitCascadeTimeout = (failedIdx0) => {
+                        if (!isMulti)
+                            return;
+                        emitHopEvent(eventHook, progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_03](failedIdx0 + 1, totalHops));
+                    };
+                    if (isMulti) {
+                        emitHopEvent(eventHook, progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_001](totalHops, chainLabels));
+                    }
                     try {
                         // 1. Wait for initial Push Chain tx confirmation
+                        // Emit 002-01 for hop 0 ONLY when the first hop is a Push (R1) tx —
+                        // its "start" coincides with submitting the composed Push tx. For
+                        // cascades that begin with R2/R3, the per-outbound/inbound branches
+                        // below own the emitHopStart for hop 0 to avoid a duplicate marker.
+                        if (((_b = hopInfos[0]) === null || _b === void 0 ? void 0 : _b.route) === 'UOA_TO_PUSH') {
+                            emitHopStart(0);
+                        }
                         cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                             hopIndex: 0,
-                            route: ((_a = hopInfos[0]) === null || _a === void 0 ? void 0 : _a.route) || 'UOA_TO_PUSH',
+                            route: ((_c = hopInfos[0]) === null || _c === void 0 ? void 0 : _c.route) || 'UOA_TO_PUSH',
                             chain: (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork),
                             status: 'waiting',
                             elapsed: Date.now() - startTime,
@@ -803,6 +1055,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                     txHash: response.hash,
                                     elapsed: Date.now() - startTime,
                                 });
+                                emitHopComplete(hop.hopIndex);
                             }
                         }
                         // 2. Track outbound hops (Route 2: UOA_TO_CEA)
@@ -833,6 +1086,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                             if (outboundHops.length === 1) {
                                 // Single direct outbound hop: use the existing V1-based tracking
                                 const hop = outboundHops[0];
+                                const hopHooks = (0, progress_route_hooks_1.pickWaitHooks)(hop.route);
                                 const remainingTimeout = timeout - (Date.now() - startTime);
                                 if (remainingTimeout <= 0) {
                                     hop.status = 'failed';
@@ -843,14 +1097,16 @@ 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));
+                                    emitHopEvent(eventHook, hopHooks.timeout(hop.executionChain, Date.now() - startTime));
+                                    emitCascadeTimeout(hop.hopIndex);
                                     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));
+                                emitHopStart(hop.hopIndex);
+                                emitHopEvent(eventHook, hopHooks.awaiting(hop.executionChain));
                                 cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                     hopIndex: hop.hopIndex,
                                     route: hop.route,
@@ -875,14 +1131,15 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                             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));
+                                                emitHopEvent(eventHook, hopHooks.polling(hop.executionChain, 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));
+                                    emitHopEvent(eventHook, hopHooks.success(outboundDetails));
+                                    emitHopComplete(hop.hopIndex);
                                     cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                         hopIndex: hop.hopIndex,
                                         route: hop.route,
@@ -895,9 +1152,15 @@ 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));
+                                    emitHopEvent(eventHook, isTimeout
+                                        ? hopHooks.timeout(hop.executionChain, remainingTimeout)
+                                        : hopHooks.failed(hop.executionChain, errMsg));
+                                    if (isTimeout) {
+                                        emitCascadeTimeout(hop.hopIndex);
+                                    }
+                                    else {
+                                        emitCascadeFailed(hop.hopIndex, errMsg);
+                                    }
                                     hop.status = 'failed';
                                     cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                         hopIndex: hop.hopIndex,
@@ -916,9 +1179,10 @@ 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.
+                                // polling begins, using the route-specific awaiting hook.
                                 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));
+                                    emitHopStart(outHop.hopIndex);
+                                    emitHopEvent(eventHook, (0, progress_route_hooks_1.pickWaitHooks)(outHop.route).awaiting(outHop.executionChain));
                                 }
                                 const perHopLastStatus = new Map();
                                 const confirmedHops = new Set();
@@ -927,6 +1191,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                     pollingIntervalMs,
                                     timeout: timeout - (Date.now() - startTime),
                                     progressHook: (event) => {
+                                        var _a, _b;
                                         cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                             hopIndex: event.hopIndex,
                                             route: event.route,
@@ -935,11 +1200,13 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                             txHash: event.txHash,
                                             elapsed: Date.now() - startTime,
                                         });
+                                        const matchedHop = outboundHops.find((h) => h.hopIndex === event.hopIndex);
+                                        const eventHooks = (0, progress_route_hooks_1.pickWaitHooks)(matchedHop === null || matchedHop === void 0 ? void 0 : matchedHop.route);
                                         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));
+                                            emitHopEvent(eventHook, eventHooks.polling((_b = (_a = matchedHop === null || matchedHop === void 0 ? void 0 : matchedHop.executionChain) !== null && _a !== void 0 ? _a : event.chain) !== null && _b !== void 0 ? _b : '', Date.now() - startTime));
                                         }
                                         if (event.status === 'confirmed' &&
                                             event.txHash &&
@@ -949,21 +1216,22 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                             // 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));
+                                                emitHopEvent(eventHook, eventHooks.success(matchedHop.outboundDetails));
+                                                emitHopComplete(event.hopIndex);
                                             }
                                         }
                                     },
                                 });
                                 if (!allOutboundDetails.success) {
-                                    const failedIdx = (_b = allOutboundDetails.failedAt) !== null && _b !== void 0 ? _b : 0;
+                                    const failedIdx = (_d = allOutboundDetails.failedAt) !== null && _d !== void 0 ? _d : 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));
+                                    emitHopEvent(eventHook, (0, progress_route_hooks_1.pickWaitHooks)(failedHop === null || failedHop === void 0 ? void 0 : failedHop.route).failed((_e = failedHop === null || failedHop === void 0 ? void 0 : failedHop.executionChain) !== null && _e !== void 0 ? _e : '', failMsg));
+                                    emitCascadeFailed(failedIdx, failMsg);
                                     return {
                                         success: false,
                                         hops: hopInfos,
@@ -973,9 +1241,13 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                             }
                         }
                         // 3. Route 3 (CEA_TO_PUSH) tracking - mark as submitted
+                        // Cascade does not poll inbound completion; we surface the hop-start
+                        // marker so consumers see a "Starting tx N" event for the inbound,
+                        // but skip emitHopComplete since we never observe terminal state.
                         const inboundHops = hopInfos.filter((h) => h.route === 'CEA_TO_PUSH');
                         for (const inboundHop of inboundHops) {
                             inboundHop.status = 'submitted';
+                            emitHopStart(inboundHop.hopIndex);
                             cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                 hopIndex: inboundHop.hopIndex,
                                 route: inboundHop.route,
@@ -984,14 +1256,24 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                 elapsed: Date.now() - startTime,
                             });
                         }
+                        emitCascadeSuccess();
                         return { success: true, hops: hopInfos };
                     }
                     catch (err) {
                         const failedIdx = hopInfos.findIndex((h) => h.status !== 'confirmed');
+                        const errMsg = err instanceof Error ? err.message : String(err);
+                        const failedAt = failedIdx >= 0 ? failedIdx : 0;
+                        const isTimeout = errMsg.startsWith('Timeout');
+                        if (isTimeout) {
+                            emitCascadeTimeout(failedAt);
+                        }
+                        else {
+                            emitCascadeFailed(failedAt, errMsg);
+                        }
                         return {
                             success: false,
                             hops: hopInfos,
-                            failedAt: failedIdx >= 0 ? failedIdx : 0,
+                            failedAt,
                         };
                     }
                 }),