@pushchain/core 5.1.14 → 5.1.16

package/package.json

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

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

@@ -15,6 +15,22 @@ export interface CascadeCallbacks {
         failedAt?: number;
     }>;
 }
+/**
+ * Fan out a cascade progress event to up to two listeners with dedup.
+ *
+ * The two listener slots are:
+ *   - `primary`: explicit `eventHook` from CascadeTrackOptions (passed at call
+ *     time to `waitForAll` / `wait`).
+ *   - `secondary`: init-time `ctx.progressHook` from PushChain.initialize.
+ *
+ * Both may be undefined; if both reference the same function we invoke once.
+ * Events with an empty `id` (the no-op sentinel returned by pickWaitHooks for
+ * R4/unknown routes) are dropped so consumers don't see placeholder frames.
+ *
+ * Exported for unit testing. Production code calls this from the
+ * `emitHopEvent` closure inside `createCascadedBuilder.waitForAll`.
+ */
+export declare function dispatchCascadeProgressEvent(event: import('../../progress-hook/progress-hook.types').ProgressEvent, primary?: (e: import('../../progress-hook/progress-hook.types').ProgressEvent) => void, secondary?: (e: import('../../progress-hook/progress-hook.types').ProgressEvent) => void): void;
 export declare function prepareTransaction(ctx: OrchestratorContext, params: UniversalExecuteParams, callbacks: CascadeCallbacks): Promise<PreparedUniversalTx>;
 export declare function buildHopDescriptor(ctx: OrchestratorContext, params: UniversalExecuteParams, route: TransactionRoute, ueaAddress: `0x${string}`): Promise<HopDescriptor>;
 export declare function classifyIntoSegments(hops: HopDescriptor[]): CascadeSegment[];

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

@@ -6,6 +6,7 @@
  * getSegmentType, composeCascade, createCascadedBuilder, createChainedBuilder.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchCascadeProgressEvent = dispatchCascadeProgressEvent;
 exports.prepareTransaction = prepareTransaction;
 exports.buildHopDescriptor = buildHopDescriptor;
 exports.classifyIntoSegments = classifyIntoSegments;
@@ -33,6 +34,36 @@ 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");
+const preflight_1 = require("./preflight");
+const svm_rent_1 = require("./svm-rent");
+const errors_1 = require("./errors");
+const context_2 = require("./context");
+// ============================================================================
+// dispatchCascadeProgressEvent
+// ============================================================================
+/**
+ * Fan out a cascade progress event to up to two listeners with dedup.
+ *
+ * The two listener slots are:
+ *   - `primary`: explicit `eventHook` from CascadeTrackOptions (passed at call
+ *     time to `waitForAll` / `wait`).
+ *   - `secondary`: init-time `ctx.progressHook` from PushChain.initialize.
+ *
+ * Both may be undefined; if both reference the same function we invoke once.
+ * Events with an empty `id` (the no-op sentinel returned by pickWaitHooks for
+ * R4/unknown routes) are dropped so consumers don't see placeholder frames.
+ *
+ * Exported for unit testing. Production code calls this from the
+ * `emitHopEvent` closure inside `createCascadedBuilder.waitForAll`.
+ */
+function dispatchCascadeProgressEvent(event, primary, secondary) {
+    if (!event.id)
+        return;
+    if (primary)
+        primary(event);
+    if (secondary && secondary !== primary)
+        secondary(event);
+}
 // ============================================================================
 // prepareTransaction
 // ============================================================================
@@ -89,7 +120,7 @@ function prepareTransaction(ctx, params, callbacks) {
 // ============================================================================
 function buildHopDescriptor(ctx, params, route, ueaAddress) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
         // Pass 0 when user omits gasLimit → contract uses per-chain baseGasLimitByChainNamespace
         const gasLimit = (_a = params.gasLimit) !== null && _a !== void 0 ? _a : BigInt(0);
         const routeStr = route;
@@ -147,8 +178,21 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                     let gasToken = selectors_1.ZERO_ADDRESS;
                     let gasFee = BigInt(0);
                     let sizing;
+                    // Conditional CEA-ATA rent bump (SPL-only). Mirrors single-route
+                    // executeUoaToCeaSvm path. See svm-rent.ts for rationale.
+                    const splMintBase58 = burnAmount > BigInt(0)
+                        ? (_d = (_c = params.funds) === null || _c === void 0 ? void 0 : _c.token) === null || _d === void 0 ? void 0 : _d.address
+                        : undefined;
+                    const effectiveGasLimit = yield (0, svm_rent_1.maybeBumpForCeaAtaRent)({
+                        ctx,
+                        ueaAddress,
+                        targetChain,
+                        splMintBase58,
+                        burnAmount,
+                        effectiveGasLimit: gasLimit,
+                    });
                     if (prc20Token !== selectors_1.ZERO_ADDRESS) {
-                        const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, gasLimit, targetChain);
+                        const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, effectiveGasLimit, targetChain);
                         gasToken = result.gasToken;
                         gasFee = result.gasFee;
                         sizing = result.sizing;
@@ -161,7 +205,7 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                         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]);
+                const { cea: ceaAddress } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, targetChain, (_e = ctx.rpcUrls[targetChain]) === null || _e === void 0 ? void 0 : _e[0]);
                 // Migration path: raw MIGRATION_SELECTOR payload, no multicall wrapping
                 if (params.migration) {
                     const prc20Token = (0, helpers_1.getNativePRC20ForChain)(targetChain, ctx.pushNetwork);
@@ -191,7 +235,7 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                         // When ERC-20 funds are provided with a single payload, auto-prepend a
                         // transfer() call so the tokens minted to the CEA are forwarded to the
                         // target address. This mirrors the Route 1 behavior in buildExecuteMulticall.
-                        if ((_d = params.funds) === null || _d === void 0 ? void 0 : _d.amount) {
+                        if ((_f = params.funds) === null || _f === void 0 ? void 0 : _f.amount) {
                             const token = params.funds.token;
                             if (token && token.mechanism !== 'native') {
                                 const erc20Transfer = (0, viem_1.encodeFunctionData)({
@@ -211,7 +255,7 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                         // native value to the CEA, and the multicall forwards it to the target.
                         ceaMulticalls.push({
                             to: target.address,
-                            value: (_e = params.value) !== null && _e !== void 0 ? _e : BigInt(0),
+                            value: (_g = params.value) !== null && _g !== void 0 ? _g : BigInt(0),
                             data: params.data,
                         });
                     }
@@ -227,7 +271,7 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                         });
                     }
                 }
-                else if ((_f = params.funds) === null || _f === void 0 ? void 0 : _f.amount) {
+                else if ((_h = params.funds) === null || _h === void 0 ? void 0 : _h.amount) {
                     // Funds-only transfer (no data, no value). Without this branch the
                     // CEA multicall is empty and relayed funds stay in the CEA instead
                     // of reaching the caller's recipient.
@@ -259,7 +303,7 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                 // Determine PRC-20 token and burn amount
                 let prc20Token = selectors_1.ZERO_ADDRESS;
                 let burnAmount = BigInt(0);
-                if ((_g = params.funds) === null || _g === void 0 ? void 0 : _g.amount) {
+                if ((_j = params.funds) === null || _j === void 0 ? void 0 : _j.amount) {
                     const token = params.funds.token;
                     if (token) {
                         prc20Token = push_chain_1.PushChain.utils.tokens.getPRC20Address(token).address;
@@ -317,7 +361,7 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                         Buffer.from(ceaPda.toBytes()).toString('hex'));
                     let amount = BigInt(0);
                     let prc20Token;
-                    if (((_h = params.funds) === null || _h === void 0 ? void 0 : _h.amount) && params.funds.amount > BigInt(0)) {
+                    if (((_k = params.funds) === null || _k === void 0 ? void 0 : _k.amount) && params.funds.amount > BigInt(0)) {
                         amount = params.funds.amount;
                         const token = params.funds.token;
                         if (token && token.address) {
@@ -348,14 +392,14 @@ function buildHopDescriptor(ctx, params, route, ueaAddress) {
                         gasFee,
                         sizing });
                 }
-                const { cea: ceaAddress } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, sourceChain, (_j = ctx.rpcUrls[sourceChain]) === null || _j === void 0 ? void 0 : _j[0]);
+                const { cea: ceaAddress } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, sourceChain, (_l = ctx.rpcUrls[sourceChain]) === null || _l === void 0 ? void 0 : _l[0]);
                 // CEA auto-deploys on-chain: Vault.finalizeUniversalTx calls CEAFactory.deployCEA()
                 // if CEA doesn't exist yet. No SDK-side blocking needed.
                 // Determine token/amount for the inbound
                 let tokenAddress = selectors_1.ZERO_ADDRESS;
                 let amount = BigInt(0);
                 let nativeValue = BigInt(0);
-                if ((_k = params.funds) === null || _k === void 0 ? void 0 : _k.amount) {
+                if ((_m = params.funds) === null || _m === void 0 ? void 0 : _m.amount) {
                     const token = params.funds.token;
                     if (token) {
                         if (token.mechanism === 'native') {
@@ -520,7 +564,7 @@ function getSegmentType(route) {
 // ============================================================================
 function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
         let accumulatedPushMulticalls = [];
         const gatewayPcAddress = (0, helpers_1.getUniversalGatewayPCAddress)();
         // Compute per-outbound nativeValueForGas from UEA balance
@@ -528,6 +572,29 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
         // 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
+        // Cascade pre-flight: catches the zero-balance silent-segment-zero failure
+        // mode. When `ueaBalance <= CASCADE_GAS_RESERVE`, `perOutboundNativeValue`
+        // is left undefined and downstream segments silently allocate value=0,
+        // producing under-funded swaps that revert inside Uniswap. Throw early
+        // with a structured error so the caller knows which path / hop failed.
+        // Honor the per-call opt-out from the first non-PUSH segment (segments share
+        // the same UniversalExecuteParams.options.allowUnderfundedSwap shape).
+        const firstOutboundSegment = segments.find((s) => s.type !== 'PUSH_EXECUTION');
+        const cascadeAllowUnderfunded = ((_d = (_c = (_b = (_a = firstOutboundSegment === null || firstOutboundSegment === void 0 ? void 0 : firstOutboundSegment.hops) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.params) === null || _c === void 0 ? void 0 : _c.options) === null || _d === void 0 ? void 0 : _d.allowUnderfundedSwap) ===
+            true;
+        if (numOutbounds > 0) {
+            (0, preflight_1.runPreflight)({
+                ctx,
+                ueaAddress,
+                ueaBalance: ueaBalance !== null && ueaBalance !== void 0 ? ueaBalance : BigInt(0),
+                // Required = at least one wei of allocatable PC after reserve. The
+                // per-segment min-swap check below catches finer-grained shortfalls.
+                requiredValue: BigInt(1),
+                gasReserve: CASCADE_GAS_RESERVE,
+                pathTag: 'CASCADE',
+                allowUnderfundedSwap: cascadeAllowUnderfunded,
+            });
+        }
         let perOutboundNativeValue;
         if (ueaBalance && numOutbounds > 0 && ueaBalance > CASCADE_GAS_RESERVE) {
             perOutboundNativeValue =
@@ -568,17 +635,57 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
             const perSvmCap = svmTotal / BigInt(svmSegments.length);
             const UNCAPPED_BALANCE = BigInt(1e30); // effectively disable estimator's internal cap
             for (const seg of svmSegments) {
+                // Cascade-level segment index (position in `segments`, not in `svmSegments`)
+                // so the error's `segmentIndex` lines up with what the caller sees.
+                const cascadeIdx = segments.indexOf(seg);
                 const estimated = yield (0, gas_calculator_1.estimateNativeValueForSwap)(ctx, universalCoreAddress, seg.gasToken, seg.gasFee, UNCAPPED_BALANCE);
+                // SVM warn-threshold telemetry (no truncation — pre-flight handles drain protection).
+                (0, preflight_1.maybeFireSvmWarnThreshold)(ctx, estimated, seg.gasToken, 'CASCADE');
                 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}`);
+                // Upward-allocation ceiling (mirrors R3 SVM Fix #4 in route-handlers.ts:1690).
+                // When UEA balance is huge, the flat split or perSvmCap can produce a value
+                // far above what the swap actually needs. Submitting that into a Uniswap
+                // pool moves the price for other users. Cap at max(200 PC, 5×estimated):
+                //   - fair pool (estimated ≈ 100 PC): cap = 500 PC → caps voluntary excess
+                //   - skewed pool (estimated > 200 PC): cap = 5×estimated → still allows
+                //     pool-skew margin; min-swap check below still fires if value < estimated
+                // The contract still refunds excess via swapAndBurnGas, so this is purely
+                // a guard against submitting wasteful msg.value to fair-priced pools.
+                const UPWARD_BASE_CEILING_CASCADE_SVM = BigInt(200) * BigInt(1e18);
+                const upwardCeilingCascadeSvm = estimated * BigInt(5) > UPWARD_BASE_CEILING_CASCADE_SVM
+                    ? estimated * BigInt(5)
+                    : UPWARD_BASE_CEILING_CASCADE_SVM;
+                if (value > upwardCeilingCascadeSvm) {
+                    (0, context_1.printLog)(ctx, `composeCascade — SVM outbound to ${(_e = seg.hops[0]) === null || _e === void 0 ? void 0 : _e.targetChain}: capping value from ${value} to upwardCeiling=${upwardCeilingCascadeSvm} (pool quote=${estimated})`);
+                    value = upwardCeilingCascadeSvm;
+                }
+                (0, context_1.printLog)(ctx, `composeCascade — SVM outbound to ${(_f = seg.hops[0]) === null || _f === void 0 ? void 0 : _f.targetChain}: gasFee=${seg.gasFee}, estimatedWpc=${estimated}, flat=${flat}, perSvmCap=${perSvmCap}, upwardCeiling=${upwardCeilingCascadeSvm}, chosen=${value}`);
+                // Per-segment minimum-viable-swap check: if the chosen `value` is below
+                // the live pool quote (`estimated`), the cap squeezed the budget below
+                // what the swap actually needs and the segment will revert inside
+                // Uniswap with STF. Throw cleanly with `segmentIndex` so the caller
+                // knows which hop's pool is misbehaving.
+                if (estimated > BigInt(0) && value < estimated && !cascadeAllowUnderfunded) {
+                    const shortfall = estimated - value;
+                    (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_04, estimated, value, shortfall, ueaAddress, 'CASCADE', { kind: 'NATIVE', segmentIndex: cascadeIdx });
+                    throw new errors_1.InsufficientUEABalanceError({
+                        required: estimated,
+                        available: value,
+                        shortfall,
+                        ueaAddress,
+                        pathTag: 'CASCADE',
+                        reason: 'NATIVE',
+                        segmentIndex: cascadeIdx,
+                    });
+                }
                 svmNativeValueBySegment.set(seg, value);
             }
         }
-        for (let i = segments.length - 1; i >= 0; i--) {
-            const segment = segments[i];
+        for (let segIdxLoop = segments.length - 1; segIdxLoop >= 0; segIdxLoop--) {
+            const segment = segments[segIdxLoop];
             switch (segment.type) {
                 case 'PUSH_EXECUTION': {
                     // Prepend Push Chain multicalls to accumulated
@@ -596,7 +703,7 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
                     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';
+                        outboundPayload = (_g = firstHop.svmPayload) !== null && _g !== void 0 ? _g : '0x';
                         // For SVM, to.address IS the target (program for execute, recipient for withdraw)
                         const svmTarget = firstHop.params.to;
                         targetForOutbound = svmTarget.address;
@@ -612,8 +719,40 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
                         // Get CEA address from the first hop
                         targetForOutbound = (firstHop === null || firstHop === void 0 ? void 0 : firstHop.ceaAddress) || ueaAddress;
                     }
+                    // Per-segment PRC-20 burn-balance pre-check (cascade R2-style segments
+                    // only — INBOUND_FROM_CEA segments are payload-only with totalBurnAmount=0
+                    // per the 2026-03-19 fix). Skip MIGRATION (totalBurnAmount=0). Fires
+                    // whenever burnAmount > 0 even when burn token equals gas token — the
+                    // gateway's transferFrom happens BEFORE the gas swap, so user must
+                    // pre-hold the burn amount.
+                    const segBurnAmount = segment.totalBurnAmount || BigInt(0);
+                    const segBurnToken = segment.prc20Token;
+                    if (segBurnAmount > BigInt(0) && segBurnToken && !isMigration) {
+                        const onHand = yield ctx.pushClient.readContract({
+                            address: segBurnToken,
+                            abi: erc20_evm_1.ERC20_EVM,
+                            functionName: 'balanceOf',
+                            args: [ueaAddress],
+                        });
+                        const sufficient = onHand >= segBurnAmount;
+                        (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_03, segBurnAmount, onHand, sufficient, ueaAddress, 'CASCADE', { kind: 'PRC20', burnToken: segBurnToken, segmentIndex: segIdxLoop });
+                        if (!sufficient && !cascadeAllowUnderfunded) {
+                            const shortfall = segBurnAmount - onHand;
+                            (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_04, segBurnAmount, onHand, shortfall, ueaAddress, 'CASCADE', { kind: 'PRC20', burnToken: segBurnToken, segmentIndex: segIdxLoop });
+                            throw new errors_1.InsufficientUEABalanceError({
+                                required: segBurnAmount,
+                                available: onHand,
+                                shortfall,
+                                ueaAddress,
+                                pathTag: 'CASCADE',
+                                reason: 'PRC20',
+                                burnToken: segBurnToken,
+                                segmentIndex: segIdxLoop,
+                            });
+                        }
+                    }
                     // 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);
+                    const outboundReq = (0, payload_builders_1.buildOutboundRequest)(targetForOutbound, segment.prc20Token || selectors_1.ZERO_ADDRESS, segment.totalBurnAmount || BigInt(0), (_h = segment.gasLimit) !== null && _h !== void 0 ? _h : BigInt(0), outboundPayload, ueaAddress);
                     // Build approval + outbound multicalls
                     const segGasFee = segment.gasFee || BigInt(0);
                     const svmOverride = svmNativeValueBySegment.get(segment);
@@ -629,7 +768,7 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
                     else {
                         evmFallbackValue = segGasFee * BigInt(1000000);
                     }
-                    let nativeValueForGas = (_d = svmOverride !== null && svmOverride !== void 0 ? svmOverride : perOutboundNativeValue) !== null && _d !== void 0 ? _d : evmFallbackValue;
+                    let nativeValueForGas = (_j = svmOverride !== null && svmOverride !== void 0 ? svmOverride : perOutboundNativeValue) !== null && _j !== void 0 ? _j : 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
@@ -661,7 +800,7 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
                     // 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)) {
+                        if (((_k = h === null || h === void 0 ? void 0 : h.params) === null || _k === void 0 ? void 0 : _k.data) || ((_l = h === null || h === void 0 ? void 0 : h.params) === null || _l === void 0 ? void 0 : _l.value)) {
                             const hopCalls = (0, payload_builders_1.buildExecuteMulticall)({
                                 execute: {
                                     to: h.params.to,
@@ -702,7 +841,7 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
                         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)) {
+                        if (((_m = params.funds) === null || _m === void 0 ? void 0 : _m.amount) && params.funds.amount > BigInt(0)) {
                             drainAmount = params.funds.amount;
                             const token = params.funds.token;
                             if (token && token.address) {
@@ -731,7 +870,7 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
                         });
                         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);
+                            (0, helpers_1.getNativePRC20ForChain)(sourceChain, ctx.pushNetwork), svmBurnAmount, (_o = segment.gasLimit) !== null && _o !== void 0 ? _o : BigInt(0), svmPayload, ueaAddress);
                         const inboundGasFee = segment.gasFee || BigInt(0);
                         let svmInboundFallback;
                         if (ueaBalance && ueaBalance > BigInt(0)) {
@@ -744,7 +883,7 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
                         // 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' &&
+                        if (((_p = segment.sizing) === null || _p === void 0 ? void 0 : _p.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})`);
@@ -779,7 +918,7 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
                     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) {
+                        if ((_q = hParams.funds) === null || _q === void 0 ? void 0 : _q.amount) {
                             const token = hParams.funds.token;
                             if (token) {
                                 if (token.mechanism === 'native') {
@@ -854,7 +993,7 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
                     // 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' &&
+                    if (((_r = segment.sizing) === null || _r === void 0 ? void 0 : _r.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})`);
@@ -885,6 +1024,7 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
 function createCascadedBuilder(ctx, preparedTxs, callbacks) {
     return {
         send: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a;
             const ueaAddress = (0, uea_manager_1.computeUEAOffchain)(ctx);
             // Extract HopDescriptors
             const hops = preparedTxs.map((tx) => tx._hop);
@@ -970,7 +1110,22 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
             const ueaNonceCascade = ueaCodeCascade !== undefined
                 ? yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress)
                 : BigInt(0);
-            const composedMulticalls = yield composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonceCascade);
+            let composedMulticalls;
+            try {
+                composedMulticalls = yield composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonceCascade);
+            }
+            catch (err) {
+                // Pre-flight or per-segment min-swap failure inside composeCascade
+                // throws before the cascade ever broadcasts. Fire 999-02 with the
+                // segmentIndex (1-indexed for the failedAt slot) so consumers see a
+                // terminal "cascade failed" frame instead of the stream stopping
+                // silently after 203-04.
+                if (err instanceof errors_1.InsufficientUEABalanceError) {
+                    const failedHopIndex = (_a = err.segmentIndex) !== null && _a !== void 0 ? _a : 0;
+                    (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_02, failedHopIndex + 1, preparedTxs.length, err.message);
+                }
+                throw err;
+            }
             // Execute the composed multicall as a single Push Chain tx
             const executeParams = {
                 to: ueaAddress,
@@ -998,14 +1153,17 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                     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);
+                    // Per-hop progress emission. Fans out cascade markers to BOTH the
+                    // explicit `eventHook` (passed into waitForAll) AND the init-time
+                    // `ctx.progressHook` (set on PushChain.initialize), deduping if the
+                    // two are the same reference. This is the bridge that lets UI-kit
+                    // consumers — which only listen on `ctx.progressHook` — receive the
+                    // cascade-level marker stream (001 / 002-xx / 203-xx / 204-xx /
+                    // 209-xx / 299-01 / 999-xx) without having to manually wire
+                    // `eventHook` at every call site. Drops events whose id is '' (the
+                    // no-op sentinel returned by pickWaitHooks for R4/unknown routes).
+                    const emitHopEvent = (event) => {
+                        dispatchCascadeProgressEvent(event, eventHook, ctx.progressHook);
                     };
                     // ---- Multichain (multi-hop) cascade markers (001 / 002 / 999) ----
                     // Only fire when this is genuinely a multi-hop cascade. Single-hop
@@ -1026,7 +1184,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                             ? 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));
+                        emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_002_01](n, totalHops, fromChain, toChain));
                     };
                     const emitHopComplete = (hopIndex0) => {
                         if (!isMulti)
@@ -1034,25 +1192,25 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                         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));
+                        emitHopEvent(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));
+                        emitHopEvent(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));
+                        emitHopEvent(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));
+                        emitHopEvent(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));
+                        emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_001](totalHops, chainLabels));
                     }
                     try {
                         // 1. Wait for initial Push Chain tx confirmation
@@ -1126,7 +1284,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                         status: 'timeout',
                                         elapsed: Date.now() - startTime,
                                     });
-                                    emitHopEvent(eventHook, hopHooks.timeout(hop.executionChain, Date.now() - startTime));
+                                    emitHopEvent(hopHooks.timeout(hop.executionChain, Date.now() - startTime));
                                     emitCascadeTimeout(hop.hopIndex);
                                     return {
                                         success: false,
@@ -1135,7 +1293,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                     };
                                 }
                                 emitHopStart(hop.hopIndex);
-                                emitHopEvent(eventHook, hopHooks.awaiting(hop.executionChain));
+                                emitHopEvent(hopHooks.awaiting(hop.executionChain));
                                 cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                     hopIndex: hop.hopIndex,
                                     route: hop.route,
@@ -1160,14 +1318,14 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                             if (event.status === 'polling' &&
                                                 lastEmittedStatus !== 'polling') {
                                                 lastEmittedStatus = 'polling';
-                                                emitHopEvent(eventHook, hopHooks.polling(hop.executionChain, event.elapsed));
+                                                emitHopEvent(hopHooks.polling(hop.executionChain, event.elapsed));
                                             }
                                         },
                                     });
                                     hop.status = 'confirmed';
                                     hop.txHash = outboundDetails.externalTxHash;
                                     hop.outboundDetails = outboundDetails;
-                                    emitHopEvent(eventHook, hopHooks.success(outboundDetails));
+                                    emitHopEvent(hopHooks.success(outboundDetails));
                                     emitHopComplete(hop.hopIndex);
                                     cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                         hopIndex: hop.hopIndex,
@@ -1181,7 +1339,7 @@ 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');
-                                    emitHopEvent(eventHook, isTimeout
+                                    emitHopEvent(isTimeout
                                         ? hopHooks.timeout(hop.executionChain, remainingTimeout)
                                         : hopHooks.failed(hop.executionChain, errMsg));
                                     if (isTimeout) {
@@ -1211,7 +1369,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                 // polling begins, using the route-specific awaiting hook.
                                 for (const outHop of outboundHops) {
                                     emitHopStart(outHop.hopIndex);
-                                    emitHopEvent(eventHook, (0, progress_route_hooks_1.pickWaitHooks)(outHop.route).awaiting(outHop.executionChain));
+                                    emitHopEvent((0, progress_route_hooks_1.pickWaitHooks)(outHop.route).awaiting(outHop.executionChain));
                                 }
                                 const perHopLastStatus = new Map();
                                 const confirmedHops = new Set();
@@ -1235,7 +1393,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                         if (event.status === 'polling' &&
                                             prev !== 'polling') {
                                             perHopLastStatus.set(event.hopIndex, 'polling');
-                                            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));
+                                            emitHopEvent(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 &&
@@ -1247,7 +1405,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                             // guard above, so we only reach here with full details.
                                             if (matchedHop === null || matchedHop === void 0 ? void 0 : matchedHop.outboundDetails) {
                                                 confirmedHops.add(event.hopIndex);
-                                                emitHopEvent(eventHook, eventHooks.success(matchedHop.outboundDetails));
+                                                emitHopEvent(eventHooks.success(matchedHop.outboundDetails));
                                                 emitHopComplete(event.hopIndex);
                                             }
                                         }
@@ -1259,7 +1417,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks) {
                                     const failMsg = failedHop
                                         ? `Outbound failed for hop ${failedIdx} on ${failedHop.executionChain}`
                                         : `Outbound cascade failed at hop ${failedIdx}`;
-                                    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));
+                                    emitHopEvent((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,

package/src/lib/orchestrator/internals/error-decoder.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Decoder for revert-error messages surfaced by Cosmos `tx.rawLog`.
+ *
+ * Two extraction paths:
+ *   1. 4-byte custom selector (e.g. `0xacfdb444:` or `0xf4d678b8000000…`) —
+ *      looked up against `KNOWN_ERROR_SELECTORS` for a friendly name + hint.
+ *   2. `Error(string)` ABI-encoded revert (`0x08c379a0` selector + offset +
+ *      length + data) — decoded into the original UTF-8 string.
+ *
+ * Unknown selectors fall through with `kind: 'unknown'` so callers can log
+ * them at INFO and grow the table from real reverts.
+ *
+ * The selector→name mappings below are EMPIRICAL: they were observed in
+ * production e2e logs and SDK test fixtures. `keccak256` of the obvious
+ * parameterless signatures (e.g. `keccak256("InsufficientBalance()")` =
+ * `0x01e1e567`) does NOT reproduce the listed selectors, so the deployed-
+ * source mapping is still unverified. Names and hints are worded as
+ * "likely cause" until the bytecode-source trace lands.
+ */
+export interface KnownErrorSelector {
+    /** Best-effort error name. Worded as a likely cause until source-traced. */
+    name: string;
+    /** User-facing remediation hint. */
+    hint: string;
+    /** Where this mapping was first observed (log path or fixture). */
+    provenance: string;
+}
+export declare const KNOWN_ERROR_SELECTORS: Record<`0x${string}`, KnownErrorSelector>;
+/** Selector for `Error(string)` (Solidity `require(false, "msg")`). */
+export declare const ERROR_STRING_SELECTOR: `0x${string}`;
+export type DecodedRevertCustom = {
+    kind: 'custom';
+    selector: `0x${string}`;
+    name: string;
+    hint: string;
+    provenance: string;
+};
+export type DecodedRevertString = {
+    kind: 'string';
+    selector: `0x${string}`;
+    decoded: string;
+};
+export type DecodedRevertUnknown = {
+    kind: 'unknown';
+    selector: `0x${string}`;
+};
+export type DecodedRevert = DecodedRevertCustom | DecodedRevertString | DecodedRevertUnknown;
+/**
+ * Extracts the first hex blob after `ret ` from a Cosmos tx error message,
+ * pulls the 4-byte selector, and looks it up. Returns `null` when no blob
+ * is found.
+ *
+ * **Assumption**: today's Cosmos `tx.rawLog` format contains a single
+ * `ret 0x…:` substring per failed message. If a future log format includes
+ * nested call traces with multiple `ret` substrings, this regex will pick
+ * the first selector — which may not be the most relevant one. Revisit
+ * if multi-revert log formats appear in production.
+ */
+export declare function decodeRevert(errorMsg: string): DecodedRevert | null;