@pushchain/core 5.1.15 → 5.1.16

package/src/lib/orchestrator/internals/svm-rent.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CEA_ATA_RENT_LAMPORTS_BUMP = void 0;
+exports.deriveSvmCeaPda = deriveSvmCeaPda;
+exports.deriveAtaPubkey = deriveAtaPubkey;
+exports.maybeBumpForCeaAtaRent = maybeBumpForCeaAtaRent;
+const tslib_1 = require("tslib");
+/**
+ * Conditional CEA-ATA rent bump for SVM SPL outbounds.
+ *
+ * The gateway program (svm-gateway) computes per-tx fees with a conditional
+ * rent for first-time SPL transfers — see `calculateSplExecuteFees` in
+ * `push-chain-gateway-contracts/contracts/svm-gateway/tests/helpers/test-utils.ts`:
+ *
+ *   const ataExists = await ceaAtaExists(connection, ceaAta);
+ *   const ceaAtaRent = ataExists ? 0n : BigInt(getMinimumBalanceForRentExemption(165));
+ *   gasFee = executedTxRent + ceaAtaRent + COMPUTE_BUFFER;
+ *
+ * The gateway's on-chain `getOutboundTxGasAndFees` quote does NOT factor in
+ * the ATA rent today, so the SDK has to bump `effectiveGasLimit` itself
+ * before calling that quote. Native-SOL outbounds use `calculateSolExecuteFees`
+ * which has no conditional rent, so no SDK bump is needed there.
+ */
+const web3_js_1 = require("@solana/web3.js");
+const buffer_1 = require("buffer");
+const context_1 = require("./context");
+const chain_1 = require("../../constants/chain");
+// ---------------------------------------------------------------------------
+// Constants — mirror gateway test-utils.ts. These are SOL protocol values;
+// they only change if Solana itself adjusts rent rates (effectively never).
+// ---------------------------------------------------------------------------
+/** ATA rent (165-byte SPL token account) + executed-tx rent (8-byte) + compute buffer.
+ *  Mirrors getMinimumBalanceForRentExemption(165) ≈ 2_039_280
+ *       + getMinimumBalanceForRentExemption(8) ≈ 9_200
+ *       + COMPUTE_BUFFER 100_000.
+ *  Signature fee (5_000) is already included in the gateway's base quote. */
+exports.CEA_ATA_RENT_LAMPORTS_BUMP = BigInt(2148480);
+/** SVM gateway program ID (matches CHAIN_INFO[SOLANA_DEVNET].lockerContract). */
+const SVM_GATEWAY_PROGRAM = new web3_js_1.PublicKey('CFVSincHYbETh2k7w6u1ENEkjbSLtveRCEBupKidw2VS');
+const TOKEN_PROGRAM_ID = new web3_js_1.PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
+const ASSOCIATED_TOKEN_PROGRAM_ID = new web3_js_1.PublicKey('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL');
+// ---------------------------------------------------------------------------
+// PDA derivations
+// ---------------------------------------------------------------------------
+/** Derive CEA PDA from a 20-byte EVM address. Seeds: ["push_identity", evmBytes]. */
+function deriveSvmCeaPda(evmAddress) {
+    const senderBytes = buffer_1.Buffer.from(evmAddress.slice(2), 'hex');
+    const [ceaPda] = web3_js_1.PublicKey.findProgramAddressSync([buffer_1.Buffer.from('push_identity'), senderBytes], SVM_GATEWAY_PROGRAM);
+    return ceaPda;
+}
+/** Derive a standard SPL Associated Token Account address. */
+function deriveAtaPubkey(owner, mint) {
+    const [ata] = web3_js_1.PublicKey.findProgramAddressSync([owner.toBuffer(), TOKEN_PROGRAM_ID.toBuffer(), mint.toBuffer()], ASSOCIATED_TOKEN_PROGRAM_ID);
+    return ata;
+}
+/**
+ * Returns the (possibly bumped) effectiveGasLimit. Logs the decision via
+ * printLog. On any RPC failure or invalid input, logs a warning and returns
+ * the input unchanged — better to risk one underflow than to block all SPL
+ * outbounds on RPC flake; pre-flight will surface insufficient gas anyway.
+ */
+function maybeBumpForCeaAtaRent(input) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e;
+        const { ctx, ueaAddress, targetChain, splMintBase58, burnAmount, effectiveGasLimit, } = input;
+        // Only applies to SPL outbounds. Native SOL outbounds use the gateway's
+        // calculateSolExecuteFees which has no ATA conditional.
+        if (!splMintBase58 || burnAmount === BigInt(0)) {
+            return effectiveGasLimit;
+        }
+        const rpcUrl = (_c = (_b = (_a = ctx.rpcUrls) === null || _a === void 0 ? void 0 : _a[targetChain]) === null || _b === void 0 ? void 0 : _b[0]) !== null && _c !== void 0 ? _c : (_e = (_d = chain_1.CHAIN_INFO[targetChain]) === null || _d === void 0 ? void 0 : _d.defaultRPC) === null || _e === void 0 ? void 0 : _e[0];
+        if (!rpcUrl) {
+            (0, context_1.printLog)(ctx, `maybeBumpForCeaAtaRent — no Solana RPC URL for ${targetChain}; skipping rent bump`);
+            return effectiveGasLimit;
+        }
+        try {
+            const ceaPda = deriveSvmCeaPda(ueaAddress);
+            const splMint = new web3_js_1.PublicKey(splMintBase58);
+            const ceaAta = deriveAtaPubkey(ceaPda, splMint);
+            const conn = new web3_js_1.Connection(rpcUrl, 'confirmed');
+            const info = yield conn.getAccountInfo(ceaAta);
+            const ataExists = info !== null && info.data.length > 0;
+            if (!ataExists) {
+                const bumped = effectiveGasLimit + exports.CEA_ATA_RENT_LAMPORTS_BUMP;
+                (0, context_1.printLog)(ctx, `maybeBumpForCeaAtaRent — CEA ATA ${ceaAta.toBase58()} not deployed on ${targetChain}; ` +
+                    `bumping effectiveGasLimit ${effectiveGasLimit} → ${bumped} ` +
+                    `(+${exports.CEA_ATA_RENT_LAMPORTS_BUMP} lamports for ATA rent + exec rent + compute buffer)`);
+                return bumped;
+            }
+            (0, context_1.printLog)(ctx, `maybeBumpForCeaAtaRent — CEA ATA ${ceaAta.toBase58()} already deployed on ${targetChain}; no rent bump`);
+            return effectiveGasLimit;
+        }
+        catch (err) {
+            (0, context_1.printLog)(ctx, `maybeBumpForCeaAtaRent — RPC error querying CEA ATA on ${targetChain}: ` +
+                `${err instanceof Error ? err.message : String(err)}; proceeding without bump`);
+            return effectiveGasLimit;
+        }
+    });
+}
+//# sourceMappingURL=svm-rent.js.map

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

@@ -126,7 +126,7 @@ function reconstructProgressEvents(universalTxResponse, universalTxData) {
     return events;
 }
 function reconstructR2(universalTxResponse, universalTxData, isFailed, errorMsg) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e, _f, _g;
     const events = [];
     const targetChain = ((_a = universalTxResponse.chain) !== null && _a !== void 0 ? _a : 'external');
     const targetAddress = (_d = (_c = (_b = universalTxData === null || universalTxData === void 0 ? void 0 : universalTxData.outboundTx) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.recipient) !== null && _d !== void 0 ? _d : universalTxResponse.to;
@@ -138,6 +138,18 @@ function reconstructR2(universalTxResponse, universalTxData, isFailed, errorMsg)
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_202_02](targetChain, BigInt(0), BigInt(0)));
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_01](targetChain));
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_02](universalTxResponse.from, targetAddress, targetChain, true));
+    // Pre-flight reconstruction. Live R2 fires SEND_TX_203_03 once for PRC-20
+    // (when funds.amount > 0) and once for native — but historical chain data
+    // doesn't preserve the pre-flight values. Emit the native check unconditionally
+    // (every R2 outbound has one) and a second copy when the recorded outbound
+    // had a non-zero burn amount (proxy for "user supplied funds.amount > 0").
+    // Values are zero-placeholders matching the existing 202-02 pattern.
+    const ueaFrom = universalTxResponse.from;
+    const burnAmount = BigInt((_g = (_f = (_e = universalTxData === null || universalTxData === void 0 ? void 0 : universalTxData.outboundTx) === null || _e === void 0 ? void 0 : _e[0]) === null || _f === void 0 ? void 0 : _f.amount) !== null && _g !== void 0 ? _g : '0');
+    if (burnAmount > BigInt(0)) {
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_03](BigInt(0), BigInt(0), true, ueaFrom, 'R2_EVM', { kind: 'PRC20' }));
+    }
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_03](BigInt(0), BigInt(0), true, ueaFrom, 'R2_EVM', { kind: 'NATIVE' }));
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_01]());
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_02]());
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_03]());
@@ -162,6 +174,9 @@ function reconstructR3(universalTxResponse, universalTxData, isFailed, errorMsg)
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_302_02](sourceChain, BigInt(0), BigInt(0)));
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_01](sourceChain));
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_02](universalTxResponse.from, ceaAddress, sourceChain));
+    // R3 pre-flight reconstruction — R3 EVM burnAmount=0, R3 SVM burnAmount=0
+    // (post-fix). Only the NATIVE pre-flight check fires; no PRC-20 second hook.
+    events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_03](BigInt(0), BigInt(0), true, universalTxResponse.from, 'R3_EVM', { kind: 'NATIVE' }));
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_01]());
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_02]());
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_03]());

package/src/lib/orchestrator/orchestrator.js

@@ -177,7 +177,40 @@ class Orchestrator {
                 // Check if this is a multi-chain request (has ChainTarget or from.chain)
                 const isMultiChain = (0, route_detector_1.isChainTarget)(params.to) || ('from' in params && ((_d = params.from) === null || _d === void 0 ? void 0 : _d.chain));
                 if (isMultiChain) {
-                    return yield (0, internals_1.executeMultiChain)(this.ctx, params, this.execute.bind(this));
+                    try {
+                        return yield (0, internals_1.executeMultiChain)(this.ctx, params, this.execute.bind(this));
+                    }
+                    catch (err) {
+                        // R2/R3/R4 outer catch — fires the route-correct terminal failure
+                        // hook (299-02 / 399-02) when an inner route handler throws BEFORE
+                        // its own try/catch around executeFn (e.g. pre-flight balance
+                        // check throws). Without this, the hook stream ends mid-flight and
+                        // consumers have no terminal close-out marker.
+                        if (!isRecursiveInnerCall && !this.ctx._routeTerminalEmitted) {
+                            const errMessage = err instanceof Error
+                                ? err.message
+                                : typeof err === 'string'
+                                    ? err
+                                    : 'Unknown error';
+                            // Lift any structured `decodedError` off the typed error so the
+                            // formatter's optional payload field gets populated.
+                            const decodedError = err instanceof Error && err.decodedError
+                                ? err.decodedError
+                                : undefined;
+                            if (this.currentRoute === route_detector_1.TransactionRoute.CEA_TO_PUSH) {
+                                (0, internals_1.fireProgressHook)(this.ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02, errMessage, 'push', undefined, decodedError);
+                            }
+                            else if (this.currentRoute === route_detector_1.TransactionRoute.UOA_TO_CEA) {
+                                // 299-02 needs the target chain — pull it off ChainTarget.
+                                const targetChain = (0, route_detector_1.isChainTarget)(params.to) && params.to ? params.to.chain : 'unknown';
+                                (0, internals_1.fireProgressHook)(this.ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02, targetChain, errMessage, decodedError);
+                            }
+                            else {
+                                (0, internals_1.fireProgressHook)(this.ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMessage, decodedError);
+                            }
+                        }
+                        throw err;
+                    }
                 }
                 // Standard Push Chain execution (Route 1)
                 const execute = params;

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

@@ -397,6 +397,20 @@ export type UniversalExecuteParams = Omit<ExecuteParams, 'to'> & {
      * Only applicable for Route 2 (UOA_TO_CEA) on EVM chains.
      */
     migration?: boolean;
+    /**
+     * Per-call SDK behaviour overrides. Reserved for opt-out flags that must
+     * not affect the global orchestrator config.
+     */
+    options?: {
+        /**
+         * Restore the legacy clamp-and-refund behaviour for outbound paths whose
+         * UEA balance is below the buffered pool quote. Default `false` — the
+         * SDK throws `InsufficientUEABalanceError` (see `runPreflight`) and does
+         * NOT submit a cosmos tx. Set `true` only when the caller intentionally
+         * relies on `swapAndBurnGas` refunds to power through low balances.
+         */
+        allowUnderfundedSwap?: boolean;
+    };
 };
 /**
  * Account metadata for SVM CPI execution (Solana Gateway pattern).
@@ -627,9 +641,19 @@ export interface CascadeTrackOptions {
     /** Per-hop progress callback */
     progressHook?: (event: CascadeProgressEvent) => void;
     /**
-     * Unified ProgressEvent stream for SEND-TX-08/99_03-05 telemetry.
-     * Fires per outbound hop during external chain polling. Use alongside
-     * `progressHook` — they emit complementary views of the same events.
+     * Unified ProgressEvent stream for the cascade marker set
+     * (001 / 002-xx / 203-xx / 204-xx / 209-xx / 299-01 / 999-xx and per-route
+     * awaiting/polling/success/failed/timeout hooks).
+     *
+     * Cascade markers ALSO fan out to the init-time `progressHook` set on
+     * `PushChain.initialize` (see `OrchestratorContext.progressHook`), so
+     * UI-kit consumers that wired progress at init receive the cascade stream
+     * without having to plumb `eventHook` through. When BOTH this `eventHook`
+     * and the init-time `ctx.progressHook` are wired, events are delivered to
+     * both with dedup (no double-fire if they reference the same function).
+     * If you don't want the global init-time `progressHook` to react to
+     * cascade markers, filter them inside that handler — there is no
+     * cascade-level opt-out for the init-time channel.
      */
     eventHook?: (event: import('../progress-hook/progress-hook.types').ProgressEvent) => void;
 }

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

@@ -22,6 +22,14 @@ const friendlyChain = (chainOrNs) => {
     const key = utils_1.Utils.chains.getChainName(asString);
     return key ? toTitleCase(key) : asString;
 };
+/**
+ * Format a wei-denominated UPC bigint as a human-readable PC string for use
+ * in progress-hook `message` fields. Used by the pre-flight hooks
+ * (203-03/04/05 + 003-03/04/05) so consumers see "956.7834 PC" instead of
+ * "956783432238079848707 wei UPC". Response payload bigints are NOT
+ * transformed — programmatic consumers still get raw wei.
+ */
+const formatPC = (wei, precision = 4) => `${utils_1.Utils.helpers.formatUnits(wei, { decimals: 18, precision })} PC`;
 /**
  * Classify a sign-time error as either a true wallet user-decline
  * (viem `UserRejectedRequestError`, ethers `ACTION_REJECTED`, EIP-1193 4001,
@@ -250,11 +258,11 @@ const RAW_HOOKS_R1 = {
             level: 'SUCCESS',
         };
     },
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02]: (errMessage) => ({
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02]: (errMessage, decodedError) => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02,
         title: 'Push Chain Tx Failed',
         message: errMessage,
-        response: { error: errMessage },
+        response: Object.assign({ error: errMessage }, (decodedError ? { decodedError } : {})),
         level: 'ERROR',
     }),
 };
@@ -302,6 +310,62 @@ const RAW_HOOKS_R2 = {
         response: { uea: ueaAddr, cea: ceaAddr, chain: targetChain, deployed },
         level: 'SUCCESS',
     }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_03]: (required, available, sufficient, ueaAddress, pathTag, extra) => {
+        var _a, _b, _c;
+        const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
+        const availableStr = kind === 'PRC20' ? `${available} units` : formatPC(available);
+        const requiredStr = kind === 'PRC20' ? `${required} units` : formatPC(required);
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_03,
+            title: 'Pre-flight Balance Check',
+            message: `UEA balance: ${availableStr}; required: ${requiredStr}; ` +
+                `${sufficient ? 'sufficient' : 'INSUFFICIENT'} (${pathTag})`,
+            response: {
+                required,
+                available,
+                sufficient,
+                ueaAddress,
+                pathTag,
+                kind,
+                burnToken: (_b = extra === null || extra === void 0 ? void 0 : extra.burnToken) !== null && _b !== void 0 ? _b : null,
+                segmentIndex: (_c = extra === null || extra === void 0 ? void 0 : extra.segmentIndex) !== null && _c !== void 0 ? _c : null,
+            },
+            level: sufficient ? 'INFO' : 'ERROR',
+        };
+    },
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_04]: (required, available, shortfall, ueaAddress, pathTag, extra) => {
+        var _a, _b, _c, _d;
+        const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
+        const shortfallStr = kind === 'PRC20' ? `${shortfall} units` : formatPC(shortfall);
+        const remediation = kind === 'PRC20'
+            ? `Bridge the burn token (${(_b = extra === null || extra === void 0 ? void 0 : extra.burnToken) !== null && _b !== void 0 ? _b : 'PRC-20'}) to UEA ${ueaAddress} before retrying.`
+            : `Bridge >=${shortfallStr} to UEA ${ueaAddress} before retrying.`;
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_04,
+            title: 'Insufficient UEA Balance',
+            message: `Shortfall ${shortfallStr} on ${pathTag}. ${remediation}`,
+            response: {
+                required,
+                available,
+                shortfall,
+                ueaAddress,
+                pathTag,
+                kind,
+                burnToken: (_c = extra === null || extra === void 0 ? void 0 : extra.burnToken) !== null && _c !== void 0 ? _c : null,
+                segmentIndex: (_d = extra === null || extra === void 0 ? void 0 : extra.segmentIndex) !== null && _d !== void 0 ? _d : null,
+            },
+            level: 'ERROR',
+        };
+    },
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_05]: (quoted, threshold, gasToken, pathTag) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_05,
+        title: 'SVM Native-Value Warn Threshold',
+        message: `Buffered pool quote ${formatPC(quoted)} exceeds warn threshold ${formatPC(threshold)} ` +
+            `for ${gasToken} (${pathTag}). Pool may be skewed or quote is unusually large. ` +
+            `No action taken — pre-flight will determine if balance covers it.`,
+        response: { quoted, threshold, gasToken, pathTag },
+        level: 'INFO',
+    }),
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_01]: () => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_01,
         title: 'Awaiting Signature',
@@ -365,11 +429,11 @@ const RAW_HOOKS_R2 = {
         response: Object.assign({ txHash: details.externalTxHash }, details),
         level: 'SUCCESS',
     }),
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02]: (targetChain, errorMessage) => ({
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02]: (targetChain, errorMessage, decodedError) => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02,
         title: `${friendlyChain(targetChain)} Tx Failed`,
         message: errorMessage,
-        response: { error: errorMessage, chain: targetChain },
+        response: Object.assign({ error: errorMessage, chain: targetChain }, (decodedError ? { decodedError } : {})),
         level: 'ERROR',
     }),
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_03]: (targetChain, elapsedMs) => ({
@@ -550,7 +614,7 @@ const RAW_HOOKS_R3 = {
     // Phase is passed by the emission site so the title matches the leg that
     // actually failed. Default stays 'inbound' for callers that don't specify
     // (backwards-compat with fixtures + response-builder's inbound block).
-    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02]: (errorMessage, phase = 'inbound', chain) => ({
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02]: (errorMessage, phase = 'inbound', chain, decodedError) => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02,
         title: phase === 'outbound'
             ? `${friendlyChain(chain)} Tx Failed`
@@ -558,7 +622,7 @@ const RAW_HOOKS_R3 = {
                 ? 'Push Chain Tx Failed'
                 : 'Push Chain Inbound Tx Failed',
         message: errorMessage,
-        response: { error: errorMessage, phase, chain: chain !== null && chain !== void 0 ? chain : null },
+        response: Object.assign({ error: errorMessage, phase, chain: chain !== null && chain !== void 0 ? chain : null }, (decodedError ? { decodedError } : {})),
         level: 'ERROR',
     }),
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03]: (sourceChain, elapsedMs, phase = 'inbound') => ({
@@ -658,6 +722,66 @@ const RAW_HOOKS_MULTICHAIN = {
         response: { n, total },
         level: 'INFO',
     }),
+    // Cascade pre-flight balance check. Mirrors SEND_TX_203_03 from the
+    // single-route bucket but lives in the cascade 0xx range so cascade
+    // streams remain self-consistent. `runPreflight` switches between
+    // 203-xx and 003-xx based on pathTag === 'CASCADE'.
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_03]: (required, available, sufficient, ueaAddress, pathTag, extra) => {
+        var _a, _b, _c;
+        const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
+        const availableStr = kind === 'PRC20' ? `${available} units` : formatPC(available);
+        const requiredStr = kind === 'PRC20' ? `${required} units` : formatPC(required);
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_03,
+            title: 'Cascade Pre-flight Balance Check',
+            message: `UEA balance: ${availableStr}; required: ${requiredStr}; ` +
+                `${sufficient ? 'sufficient' : 'INSUFFICIENT'} (${pathTag})`,
+            response: {
+                required,
+                available,
+                sufficient,
+                ueaAddress,
+                pathTag,
+                kind,
+                burnToken: (_b = extra === null || extra === void 0 ? void 0 : extra.burnToken) !== null && _b !== void 0 ? _b : null,
+                segmentIndex: (_c = extra === null || extra === void 0 ? void 0 : extra.segmentIndex) !== null && _c !== void 0 ? _c : null,
+            },
+            level: sufficient ? 'INFO' : 'ERROR',
+        };
+    },
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_04]: (required, available, shortfall, ueaAddress, pathTag, extra) => {
+        var _a, _b, _c, _d;
+        const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
+        const shortfallStr = kind === 'PRC20' ? `${shortfall} units` : formatPC(shortfall);
+        const remediation = kind === 'PRC20'
+            ? `Bridge the burn token (${(_b = extra === null || extra === void 0 ? void 0 : extra.burnToken) !== null && _b !== void 0 ? _b : 'PRC-20'}) to UEA ${ueaAddress} before retrying.`
+            : `Bridge >=${shortfallStr} to UEA ${ueaAddress} before retrying.`;
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_04,
+            title: 'Cascade Insufficient UEA Balance',
+            message: `Shortfall ${shortfallStr} on ${pathTag}. ${remediation}`,
+            response: {
+                required,
+                available,
+                shortfall,
+                ueaAddress,
+                pathTag,
+                kind,
+                burnToken: (_c = extra === null || extra === void 0 ? void 0 : extra.burnToken) !== null && _c !== void 0 ? _c : null,
+                segmentIndex: (_d = extra === null || extra === void 0 ? void 0 : extra.segmentIndex) !== null && _d !== void 0 ? _d : null,
+            },
+            level: 'ERROR',
+        };
+    },
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_05]: (quoted, threshold, gasToken, pathTag) => ({
+        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_05,
+        title: 'Cascade SVM Native-Value Warn Threshold',
+        message: `Buffered pool quote ${formatPC(quoted)} exceeds warn threshold ${formatPC(threshold)} ` +
+            `for ${gasToken} (${pathTag}). Pool may be skewed or quote is unusually large. ` +
+            `No action taken — pre-flight will determine if balance covers it.`,
+        response: { quoted, threshold, gasToken, pathTag },
+        level: 'INFO',
+    }),
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_01]: (hopCount) => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_01,
         title: 'All Multichain Transactions Successful',

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

@@ -46,6 +46,9 @@ export declare enum PROGRESS_HOOK {
     SEND_TX_202_02 = "SEND-TX-202-02",
     SEND_TX_203_01 = "SEND-TX-203-01",
     SEND_TX_203_02 = "SEND-TX-203-02",
+    SEND_TX_203_03 = "SEND-TX-203-03",
+    SEND_TX_203_04 = "SEND-TX-203-04",
+    SEND_TX_203_05 = "SEND-TX-203-05",
     SEND_TX_204_01 = "SEND-TX-204-01",
     SEND_TX_204_02 = "SEND-TX-204-02",
     SEND_TX_204_03 = "SEND-TX-204-03",
@@ -81,6 +84,9 @@ export declare enum PROGRESS_HOOK {
     SEND_TX_001 = "SEND-TX-001",
     SEND_TX_002_01 = "SEND-TX-002-01",
     SEND_TX_002_99_99 = "SEND-TX-002-99-99",
+    SEND_TX_003_03 = "SEND-TX-003-03",// Cascade pre-flight balance check (INFO when sufficient, ERROR when insufficient)
+    SEND_TX_003_04 = "SEND-TX-003-04",// Cascade pre-flight FAILED (ERROR, terminal precursor before 999-02)
+    SEND_TX_003_05 = "SEND-TX-003-05",// Cascade SVM warn-threshold tripped (INFO, no action)
     SEND_TX_999_01 = "SEND-TX-999-01",
     SEND_TX_999_02 = "SEND-TX-999-02",
     SEND_TX_999_03 = "SEND-TX-999-03",
@@ -92,8 +98,8 @@ export declare enum PROGRESS_HOOK {
     UEA_MIG_9903 = "UEA-MIG-9903"
 }
 export type PROGRESS_HOOK_R1 = PROGRESS_HOOK.SEND_TX_101 | PROGRESS_HOOK.SEND_TX_102_01 | PROGRESS_HOOK.SEND_TX_103_01 | PROGRESS_HOOK.SEND_TX_103_02 | PROGRESS_HOOK.SEND_TX_103_03 | PROGRESS_HOOK.SEND_TX_103_03_01 | PROGRESS_HOOK.SEND_TX_103_03_02 | PROGRESS_HOOK.SEND_TX_103_03_03 | PROGRESS_HOOK.SEND_TX_103_03_04 | PROGRESS_HOOK.SEND_TX_104_01 | PROGRESS_HOOK.SEND_TX_104_02 | PROGRESS_HOOK.SEND_TX_104_03 | PROGRESS_HOOK.SEND_TX_104_04 | PROGRESS_HOOK.SEND_TX_105_01 | PROGRESS_HOOK.SEND_TX_105_02 | PROGRESS_HOOK.SEND_TX_106_01 | PROGRESS_HOOK.SEND_TX_106_02 | PROGRESS_HOOK.SEND_TX_106_03 | PROGRESS_HOOK.SEND_TX_106_03_01 | PROGRESS_HOOK.SEND_TX_106_03_02 | PROGRESS_HOOK.SEND_TX_106_04 | PROGRESS_HOOK.SEND_TX_106_05 | PROGRESS_HOOK.SEND_TX_106_06 | PROGRESS_HOOK.SEND_TX_107 | PROGRESS_HOOK.SEND_TX_199_01 | PROGRESS_HOOK.SEND_TX_199_02;
-export type PROGRESS_HOOK_R2 = PROGRESS_HOOK.SEND_TX_201 | PROGRESS_HOOK.SEND_TX_202_01 | PROGRESS_HOOK.SEND_TX_202_02 | PROGRESS_HOOK.SEND_TX_203_01 | PROGRESS_HOOK.SEND_TX_203_02 | PROGRESS_HOOK.SEND_TX_204_01 | PROGRESS_HOOK.SEND_TX_204_02 | PROGRESS_HOOK.SEND_TX_204_03 | PROGRESS_HOOK.SEND_TX_204_04 | PROGRESS_HOOK.SEND_TX_207 | PROGRESS_HOOK.SEND_TX_209_01 | PROGRESS_HOOK.SEND_TX_209_02 | PROGRESS_HOOK.SEND_TX_299_01 | PROGRESS_HOOK.SEND_TX_299_02 | PROGRESS_HOOK.SEND_TX_299_03 | PROGRESS_HOOK.SEND_TX_299_99;
+export type PROGRESS_HOOK_R2 = PROGRESS_HOOK.SEND_TX_201 | PROGRESS_HOOK.SEND_TX_202_01 | PROGRESS_HOOK.SEND_TX_202_02 | PROGRESS_HOOK.SEND_TX_203_01 | PROGRESS_HOOK.SEND_TX_203_02 | PROGRESS_HOOK.SEND_TX_203_03 | PROGRESS_HOOK.SEND_TX_203_04 | PROGRESS_HOOK.SEND_TX_203_05 | PROGRESS_HOOK.SEND_TX_204_01 | PROGRESS_HOOK.SEND_TX_204_02 | PROGRESS_HOOK.SEND_TX_204_03 | PROGRESS_HOOK.SEND_TX_204_04 | PROGRESS_HOOK.SEND_TX_207 | PROGRESS_HOOK.SEND_TX_209_01 | PROGRESS_HOOK.SEND_TX_209_02 | PROGRESS_HOOK.SEND_TX_299_01 | PROGRESS_HOOK.SEND_TX_299_02 | PROGRESS_HOOK.SEND_TX_299_03 | PROGRESS_HOOK.SEND_TX_299_99;
 export type PROGRESS_HOOK_R3 = PROGRESS_HOOK.SEND_TX_199_99_99 | PROGRESS_HOOK.SEND_TX_301 | PROGRESS_HOOK.SEND_TX_302_01 | PROGRESS_HOOK.SEND_TX_302_02 | PROGRESS_HOOK.SEND_TX_303_01 | PROGRESS_HOOK.SEND_TX_303_02 | PROGRESS_HOOK.SEND_TX_303_03_01 | PROGRESS_HOOK.SEND_TX_303_03_02 | PROGRESS_HOOK.SEND_TX_303_03_03 | PROGRESS_HOOK.SEND_TX_304_01 | PROGRESS_HOOK.SEND_TX_304_02 | PROGRESS_HOOK.SEND_TX_304_03 | PROGRESS_HOOK.SEND_TX_304_04 | PROGRESS_HOOK.SEND_TX_307 | PROGRESS_HOOK.SEND_TX_309_01 | PROGRESS_HOOK.SEND_TX_309_02 | PROGRESS_HOOK.SEND_TX_309_03 | PROGRESS_HOOK.SEND_TX_310_01 | PROGRESS_HOOK.SEND_TX_310_02 | PROGRESS_HOOK.SEND_TX_399_01 | PROGRESS_HOOK.SEND_TX_399_02 | PROGRESS_HOOK.SEND_TX_399_03;
-export type PROGRESS_HOOK_MULTICHAIN = PROGRESS_HOOK.SEND_TX_001 | PROGRESS_HOOK.SEND_TX_002_01 | PROGRESS_HOOK.SEND_TX_002_99_99 | PROGRESS_HOOK.SEND_TX_999_01 | PROGRESS_HOOK.SEND_TX_999_02 | PROGRESS_HOOK.SEND_TX_999_03;
+export type PROGRESS_HOOK_MULTICHAIN = PROGRESS_HOOK.SEND_TX_001 | PROGRESS_HOOK.SEND_TX_002_01 | PROGRESS_HOOK.SEND_TX_002_99_99 | PROGRESS_HOOK.SEND_TX_003_03 | PROGRESS_HOOK.SEND_TX_003_04 | PROGRESS_HOOK.SEND_TX_003_05 | PROGRESS_HOOK.SEND_TX_999_01 | PROGRESS_HOOK.SEND_TX_999_02 | PROGRESS_HOOK.SEND_TX_999_03;
 export type PROGRESS_HOOK_MIG = PROGRESS_HOOK.UEA_MIG_01 | PROGRESS_HOOK.UEA_MIG_02 | PROGRESS_HOOK.UEA_MIG_03 | PROGRESS_HOOK.UEA_MIG_9901 | PROGRESS_HOOK.UEA_MIG_9902 | PROGRESS_HOOK.UEA_MIG_9903;
 export {};

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

@@ -37,6 +37,13 @@ var PROGRESS_HOOK;
     PROGRESS_HOOK["SEND_TX_202_02"] = "SEND-TX-202-02";
     PROGRESS_HOOK["SEND_TX_203_01"] = "SEND-TX-203-01";
     PROGRESS_HOOK["SEND_TX_203_02"] = "SEND-TX-203-02";
+    // Pre-flight balance check (203-03 INFO when sufficient or burn-token check passes;
+    // 203-04 ERROR terminal precursor on shortfall; 203-05 INFO SVM warn-threshold tripped).
+    // 203 bucket choice is temporal (sits between 203-02 CEA-resolved and 204-01 sign),
+    // not strictly semantic — UEA balance is on Push Chain, not the destination CEA.
+    PROGRESS_HOOK["SEND_TX_203_03"] = "SEND-TX-203-03";
+    PROGRESS_HOOK["SEND_TX_203_04"] = "SEND-TX-203-04";
+    PROGRESS_HOOK["SEND_TX_203_05"] = "SEND-TX-203-05";
     PROGRESS_HOOK["SEND_TX_204_01"] = "SEND-TX-204-01";
     PROGRESS_HOOK["SEND_TX_204_02"] = "SEND-TX-204-02";
     PROGRESS_HOOK["SEND_TX_204_03"] = "SEND-TX-204-03";
@@ -74,6 +81,14 @@ var PROGRESS_HOOK;
     PROGRESS_HOOK["SEND_TX_001"] = "SEND-TX-001";
     PROGRESS_HOOK["SEND_TX_002_01"] = "SEND-TX-002-01";
     PROGRESS_HOOK["SEND_TX_002_99_99"] = "SEND-TX-002-99-99";
+    // Cascade-scoped pre-flight hooks. Mirror the single-route 203-03/04/05
+    // semantics but live in the 0xx bucket so cascade hook streams stay
+    // self-consistent (rest of cascade uses 001 / 002-xx / 999-xx). The
+    // runPreflight helper switches between 203-xx and 003-xx based on
+    // pathTag === 'CASCADE'.
+    PROGRESS_HOOK["SEND_TX_003_03"] = "SEND-TX-003-03";
+    PROGRESS_HOOK["SEND_TX_003_04"] = "SEND-TX-003-04";
+    PROGRESS_HOOK["SEND_TX_003_05"] = "SEND-TX-003-05";
     PROGRESS_HOOK["SEND_TX_999_01"] = "SEND-TX-999-01";
     PROGRESS_HOOK["SEND_TX_999_02"] = "SEND-TX-999-02";
     PROGRESS_HOOK["SEND_TX_999_03"] = "SEND-TX-999-03";