@pushchain/core 6.0.0 → 6.0.1

package/package.json

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

package/src/lib/constants/abi/universalGatewayPC.evm.d.ts

@@ -96,7 +96,7 @@ export declare const UNIVERSAL_GATEWAY_PC: readonly [{
     readonly inputs: readonly [{
         readonly components: readonly [{
             readonly internalType: "bytes";
-            readonly name: "target";
+            readonly name: "recipient";
             readonly type: "bytes";
         }, {
             readonly internalType: "address";

package/src/lib/constants/abi/universalGatewayPC.evm.js

@@ -42,7 +42,7 @@ exports.UNIVERSAL_GATEWAY_PC = [
         inputs: [
             {
                 components: [
-                    { internalType: 'bytes', name: 'target', type: 'bytes' },
+                    { internalType: 'bytes', name: 'recipient', type: 'bytes' },
                     { internalType: 'address', name: 'token', type: 'address' },
                     { internalType: 'uint256', name: 'amount', type: 'uint256' },
                     { internalType: 'uint256', name: 'gasLimit', type: 'uint256' },

package/src/lib/constants/chain.d.ts

@@ -37,6 +37,8 @@ export declare const SYNTHETIC_PUSH_ERC20: Record<PUSH_NETWORK, {
     USDT_SOL: `0x${string}`;
     USDC_SOL: `0x${string}`;
     USDT_BNB: `0x${string}`;
+    USDC_BSC: `0x${string}`;
+    /** @deprecated Use USDC_BSC instead. */
     USDC_BNB: `0x${string}`;
     USDT_BASE: `0x${string}`;
     USDC_BASE: `0x${string}`;

package/src/lib/constants/chain.js

@@ -63,6 +63,7 @@ exports.SYNTHETIC_PUSH_ERC20 = {
         USDT_SOL: '0x4f1A3D22d170a2F4Bddb37845a962322e24f4e34',
         USDC_SOL: '0x04B8F634ABC7C879763F623e0f0550a4b5c4426F',
         USDT_BNB: '0x731aF1Da5365259d27528557EE4aFBA4baC90ef2',
+        USDC_BSC: '0x120EBf25Dad7D6a09Ad2316f23f9Be95DBb90639',
         USDC_BNB: '0x120EBf25Dad7D6a09Ad2316f23f9Be95DBb90639',
         USDT_BASE: '0x148823809B853e1db187BC09A9ac909BC42F971a',
         USDC_BASE: '0xD7C6cA1e2c0CE260BE0c0AD39C1540de460e3Be1',
@@ -83,6 +84,7 @@ exports.SYNTHETIC_PUSH_ERC20 = {
         USDT_SOL: '0x4f1A3D22d170a2F4Bddb37845a962322e24f4e34',
         USDC_SOL: '0x04B8F634ABC7C879763F623e0f0550a4b5c4426F',
         USDT_BNB: '0x731aF1Da5365259d27528557EE4aFBA4baC90ef2',
+        USDC_BSC: '0x120EBf25Dad7D6a09Ad2316f23f9Be95DBb90639',
         USDC_BNB: '0x120EBf25Dad7D6a09Ad2316f23f9Be95DBb90639',
         USDT_BASE: '0x148823809B853e1db187BC09A9ac909BC42F971a',
         USDC_BASE: '0xD7C6cA1e2c0CE260BE0c0AD39C1540de460e3Be1',
@@ -103,6 +105,7 @@ exports.SYNTHETIC_PUSH_ERC20 = {
         USDT_SOL: '0xTBD',
         USDC_SOL: '0xTBD',
         USDT_BNB: '0xTBD',
+        USDC_BSC: '0xTBD',
         USDC_BNB: '0xTBD',
         USDT_BASE: '0xTBD',
         USDC_BASE: '0xTBD',
@@ -123,6 +126,7 @@ exports.SYNTHETIC_PUSH_ERC20 = {
         USDT_SOL: '0xTBD',
         USDC_SOL: '0xTBD',
         USDT_BNB: '0xTBD',
+        USDC_BSC: '0xTBD',
         USDC_BNB: '0xTBD',
         USDT_BASE: '0xTBD',
         USDC_BASE: '0xTBD',

package/src/lib/constants/index.d.ts

@@ -1,6 +1,6 @@
 import { CHAIN, LIBRARY, PUSH_NETWORK } from './enums';
 import { TypedDataDomain, TypedData } from '../universal/signer/signer.types';
-export type { MoveableToken, PayableToken, PushChainMoveableToken, ChainSuffixAccessor, PushChainMoveableTokenAccessor, MoveableTokenConstantsMap, PayableTokenConstantsMap, } from './tokens';
+export type { MoveableToken, PayableToken, PushChainMoveableToken, ChainSuffixAccessor, UsdcChainSuffixAccessor, PushChainMoveableTokenAccessor, MoveableTokenConstantsMap, PayableTokenConstantsMap, } from './tokens';
 export declare const CONSTANTS: {
     PUSH_NETWORK: typeof PUSH_NETWORK;
     CHAIN: typeof CHAIN;

package/src/lib/constants/tokens.d.ts

@@ -76,6 +76,15 @@ export interface ChainSuffixAccessor {
     readonly bnb: PushChainMoveableToken;
     readonly sol: PushChainMoveableToken;
 }
+export interface UsdcChainSuffixAccessor {
+    readonly eth: PushChainMoveableToken;
+    readonly arb: PushChainMoveableToken;
+    readonly base: PushChainMoveableToken;
+    readonly bsc: PushChainMoveableToken;
+    /** @deprecated Use `bsc` instead. */
+    readonly bnb: PushChainMoveableToken;
+    readonly sol: PushChainMoveableToken;
+}
 export interface PushChainMoveableTokenAccessor {
     readonly pEth: PushChainMoveableToken;
     readonly pEthArb: PushChainMoveableToken;
@@ -86,7 +95,7 @@ export interface PushChainMoveableTokenAccessor {
     readonly pStEth: PushChainMoveableToken;
     readonly pDai: PushChainMoveableToken;
     readonly USDT: ChainSuffixAccessor;
-    readonly USDC: ChainSuffixAccessor;
+    readonly USDC: UsdcChainSuffixAccessor;
 }
 export type MoveableTokenConstantsMap = {
     ETHEREUM_SEPOLIA: MoveableTokenAccessor;

package/src/lib/constants/tokens.js

@@ -270,7 +270,7 @@ function buildPushChainMoveableTokenList() {
         mk('USDC', 6, s.USDC_ETH, enums_1.CHAIN.ETHEREUM_SEPOLIA),
         mk('USDC', 6, s.USDC_ARB, enums_1.CHAIN.ARBITRUM_SEPOLIA),
         mk('USDC', 6, s.USDC_BASE, enums_1.CHAIN.BASE_SEPOLIA),
-        mk('USDC', 6, s.USDC_BNB, enums_1.CHAIN.BNB_TESTNET),
+        mk('USDC', 6, s.USDC_BSC, enums_1.CHAIN.BNB_TESTNET),
         mk('USDC', 6, s.USDC_SOL, enums_1.CHAIN.SOLANA_DEVNET),
         mk('WETH', 18, s.WETH_ETH, enums_1.CHAIN.ETHEREUM_SEPOLIA),
         mk('stETH', 18, s.stETH_ETH, enums_1.CHAIN.ETHEREUM_SEPOLIA),
@@ -365,6 +365,7 @@ function buildPushChainMoveableTokenAccessor() {
         sourceChain,
         prc20Address: address,
     });
+    const usdcBsc = mk('USDC', 6, s.USDC_BSC, enums_1.CHAIN.BNB_TESTNET);
     return {
         pEth: mk('pETH', 18, s.pETH, enums_1.CHAIN.ETHEREUM_SEPOLIA),
         pEthArb: mk('pETH_ARB', 18, s.pETH_ARB, enums_1.CHAIN.ARBITRUM_SEPOLIA),
@@ -385,7 +386,8 @@ function buildPushChainMoveableTokenAccessor() {
             eth: mk('USDC', 6, s.USDC_ETH, enums_1.CHAIN.ETHEREUM_SEPOLIA),
             arb: mk('USDC', 6, s.USDC_ARB, enums_1.CHAIN.ARBITRUM_SEPOLIA),
             base: mk('USDC', 6, s.USDC_BASE, enums_1.CHAIN.BASE_SEPOLIA),
-            bnb: mk('USDC', 6, s.USDC_BNB, enums_1.CHAIN.BNB_TESTNET),
+            bsc: usdcBsc,
+            bnb: usdcBsc,
             sol: mk('USDC', 6, s.USDC_SOL, enums_1.CHAIN.SOLANA_DEVNET),
         },
     };

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

@@ -41,7 +41,9 @@ export interface ComposeCascadeResult {
     multicalls: MultiCall[];
     requiredNativeValue: bigint;
 }
-export declare function composeCascadeDetailed(ctx: OrchestratorContext, segments: CascadeSegment[], ueaAddress: `0x${string}`, ueaBalance?: bigint, ueaNonce?: bigint): Promise<ComposeCascadeResult>;
+export declare function composeCascadeDetailed(ctx: OrchestratorContext, segments: CascadeSegment[], ueaAddress: `0x${string}`, ueaBalance?: bigint, ueaNonce?: bigint, options?: {
+    enforceGasCheck?: boolean;
+}): Promise<ComposeCascadeResult>;
 export declare function composeCascade(ctx: OrchestratorContext, segments: CascadeSegment[], ueaAddress: `0x${string}`, ueaBalance?: bigint, ueaNonce?: bigint): Promise<MultiCall[]>;
 export declare function createCascadedBuilder(ctx: OrchestratorContext, preparedTxs: PreparedUniversalTx[], callbacks: CascadeCallbacks, defaultEventHook?: (event: import('../../progress-hook/progress-hook.types').ProgressEvent) => void): {
     send: () => Promise<CascadedTxResponse>;

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

@@ -753,7 +753,7 @@ function getInboundFundingForBurnToken(segments, beforeSegmentIndex, burnToken,
     }
     return total;
 }
-function composeCascadeDetailed(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
+function composeCascadeDetailed(ctx, segments, ueaAddress, ueaBalance, ueaNonce, options) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u;
         let accumulatedPushMulticalls = [];
@@ -762,6 +762,8 @@ function composeCascadeDetailed(ctx, segments, ueaAddress, ueaBalance, ueaNonce)
         const currentUeaBalance = ueaBalance !== null && ueaBalance !== void 0 ? ueaBalance : BigInt(0);
         const cascadeNativeSeed = getCascadeNativeSeed(segments);
         const effectiveUeaBalance = currentUeaBalance + cascadeNativeSeed;
+        const enforceGasCheck = (options === null || options === void 0 ? void 0 : options.enforceGasCheck) === true ||
+            segments.some((segment) => segment.hops.some((hop) => { var _a; return ((_a = hop.params.options) === null || _a === void 0 ? void 0 : _a.enforceGasCheck) === true; }));
         if (cascadeNativeSeed > BigInt(0)) {
             (0, context_1.printLog)(ctx, `composeCascade — counting cascade native seed ${cascadeNativeSeed.toString()} for cascade sizing (current UEA balance ${currentUeaBalance.toString()})`);
         }
@@ -773,8 +775,8 @@ function composeCascadeDetailed(ctx, segments, ueaAddress, ueaBalance, ueaNonce)
         // 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.
+        // producing under-funded swaps that revert inside Uniswap. Warn by default
+        // and throw only when enforceGasCheck=true.
         if (numOutbounds > 0) {
             (0, preflight_1.runPreflight)({
                 ctx,
@@ -785,6 +787,7 @@ function composeCascadeDetailed(ctx, segments, ueaAddress, ueaBalance, ueaNonce)
                 requiredValue: BigInt(1),
                 gasReserve: CASCADE_GAS_RESERVE,
                 pathTag: 'CASCADE',
+                enforceGasCheck,
             });
         }
         let perOutboundNativeValue;
@@ -867,6 +870,17 @@ function composeCascadeDetailed(ctx, segments, ueaAddress, ueaBalance, ueaNonce)
                 // knows which hop's pool is misbehaving.
                 if (estimated > BigInt(0) && value < estimated) {
                     const shortfall = estimated - value;
+                    (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_03, estimated, value, false, ueaAddress, 'CASCADE', {
+                        kind: 'NATIVE',
+                        segmentIndex: cascadeIdx,
+                        enforceGasCheck,
+                        shortfall,
+                    });
+                    if (!enforceGasCheck) {
+                        (0, context_1.printLog)(ctx, `composeCascade — SVM outbound segment ${cascadeIdx} has native shortfall ${shortfall.toString()}; proceeding because enforceGasCheck=false`);
+                        svmNativeValueBySegment.set(seg, value);
+                        continue;
+                    }
                     (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,
@@ -940,7 +954,13 @@ function composeCascadeDetailed(ctx, segments, ueaAddress, ueaBalance, ueaNonce)
                             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 });
+                        (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,
+                            enforceGasCheck,
+                            shortfall: sufficient ? BigInt(0) : segBurnAmount - onHand,
+                        });
                         const priorPushExecutionMayFundBurn = segments
                             .slice(0, segIdxLoop)
                             .some((s) => s.type === 'PUSH_EXECUTION');
@@ -951,21 +971,26 @@ function composeCascadeDetailed(ctx, segments, ueaAddress, ueaBalance, ueaNonce)
                             !priorInboundMayFundBurn) {
                             const projectedOnHand = onHand + priorInboundFundingForBurn;
                             const shortfall = segBurnAmount - projectedOnHand;
-                            (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_04, segBurnAmount, projectedOnHand, shortfall, ueaAddress, 'CASCADE', {
-                                kind: 'PRC20',
-                                burnToken: segBurnToken,
-                                segmentIndex: segIdxLoop,
-                            });
-                            throw new errors_1.InsufficientUEABalanceError({
-                                required: segBurnAmount,
-                                available: projectedOnHand,
-                                shortfall,
-                                ueaAddress,
-                                pathTag: 'CASCADE',
-                                reason: 'PRC20',
-                                burnToken: segBurnToken,
-                                segmentIndex: segIdxLoop,
-                            });
+                            if (!enforceGasCheck) {
+                                (0, context_1.printLog)(ctx, `composeCascade — PRC-20 shortfall ${shortfall.toString()} for segment ${segIdxLoop}; proceeding because enforceGasCheck=false`);
+                            }
+                            else {
+                                (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_04, segBurnAmount, projectedOnHand, shortfall, ueaAddress, 'CASCADE', {
+                                    kind: 'PRC20',
+                                    burnToken: segBurnToken,
+                                    segmentIndex: segIdxLoop,
+                                });
+                                throw new errors_1.InsufficientUEABalanceError({
+                                    required: segBurnAmount,
+                                    available: projectedOnHand,
+                                    shortfall,
+                                    ueaAddress,
+                                    pathTag: 'CASCADE',
+                                    reason: 'PRC20',
+                                    burnToken: segBurnToken,
+                                    segmentIndex: segIdxLoop,
+                                });
+                            }
                         }
                         else if (!sufficient && priorPushExecutionMayFundBurn) {
                             (0, context_1.printLog)(ctx, `composeCascade — skipping PRC-20 preflight failure for segment ${segIdxLoop}; earlier Push execution may fund ${segBurnToken} before this outbound runs`);
@@ -1252,11 +1277,14 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook) {
             const ueaAddress = (0, uea_manager_1.computeUEAOffchain)(ctx);
             // Extract HopDescriptors
             const hops = preparedTxs.map((tx) => tx._hop);
+            const enforceGasCheck = hops.some((hop) => { var _a; return ((_a = hop.params.options) === null || _a === void 0 ? void 0 : _a.enforceGasCheck) === true; });
+            const withCascadeOptions = (params) => enforceGasCheck
+                ? Object.assign(Object.assign({}, params), { options: Object.assign(Object.assign({}, params.options), { enforceGasCheck: true }) }) : params;
             // Classify into segments
             const segments = classifyIntoSegments(hops);
             // Check if this is a single-hop Route 1 (no composition needed)
             if (preparedTxs.length === 1 && preparedTxs[0].route === 'UOA_TO_PUSH') {
-                const response = yield callbacks.executeFn(hops[0].params);
+                const response = yield callbacks.executeFn(withCascadeOptions(hops[0].params));
                 const singleRoute1Result = {
                     initialTxHash: response.hash,
                     initialTxResponse: response,
@@ -1290,7 +1318,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook) {
             }
             // Check if single-hop Route 2 (just execute directly)
             if (preparedTxs.length === 1 && preparedTxs[0].route === 'UOA_TO_CEA') {
-                const response = yield callbacks.executeFn(hops[0].params);
+                const response = yield callbacks.executeFn(withCascadeOptions(hops[0].params));
                 const targetChain = hops[0].targetChain || (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork);
                 const singleRoute2Result = {
                     initialTxHash: response.hash,
@@ -1335,7 +1363,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook) {
             let composedMulticalls;
             let cascadeRequiredNativeValue = BigInt(0);
             try {
-                const composed = yield composeCascadeDetailed(ctx, segments, ueaAddress, ueaBalance, ueaNonceCascade);
+                const composed = yield composeCascadeDetailed(ctx, segments, ueaAddress, ueaBalance, ueaNonceCascade, { enforceGasCheck });
                 composedMulticalls = composed.multicalls;
                 cascadeRequiredNativeValue = composed.requiredNativeValue;
             }

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

@@ -146,6 +146,7 @@ function toExecuteParams(params) {
         maxFeePerGas: params.maxFeePerGas,
         maxPriorityFeePerGas: params.maxPriorityFeePerGas,
         deadline: params.deadline,
+        options: params.options,
         payGasWith: params.payGasWith,
         feeLockTxHash: params.feeLockTxHash,
     };

package/src/lib/orchestrator/internals/pc-usd-oracle.d.ts

@@ -1,6 +1,6 @@
 import { CHAIN } from '../../constants/enums';
 import type { OrchestratorContext } from './context';
-type StableKey = 'USDT_ETH' | 'USDT_ARB' | 'USDT_BASE' | 'USDT_BNB' | 'USDC_BNB' | 'USDT_SOL';
+type StableKey = 'USDT_ETH' | 'USDT_ARB' | 'USDT_BASE' | 'USDT_BNB' | 'USDC_BSC' | 'USDT_SOL';
 /**
  * Get $PC/USD price (8 decimals) for the given origin chain's route.
  * Returns 0 on any failure — caller is expected to fall back to

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

@@ -8,12 +8,13 @@
  * with `Error("STF")`, fees are burned, and the user sees an opaque
  * library string with no balance signal.
  *
- * `runPreflight` replaces that branch: it checks the **pre-clamp**
- * buffered pool quote against UEA balance (and optionally a PRC-20 burn
- * balance) and either:
- *   - emits `SEND-TX-203-03` (INFO, sufficient) and lets the caller proceed; or
+ * `runPreflight` checks the **pre-clamp** buffered pool quote against UEA
+ * balance (and optionally a PRC-20 burn balance) and either:
+ *   - emits `SEND-TX-203-03` (INFO, sufficient) and lets the caller proceed;
+ *   - emits `SEND-TX-203-03` (WARNING, insufficient) and proceeds when
+ *     enforceGasCheck is false/omitted; or
  *   - emits `SEND-TX-203-03` (ERROR, insufficient) + `SEND-TX-203-04` and
- *     throws `InsufficientUEABalanceError`.
+ *     throws `InsufficientUEABalanceError` when enforceGasCheck is true.
  *
  * The helper is intentionally not "pure" — it emits hooks and may throw.
  * Callers fetch all balances (so the helper itself does no I/O).
@@ -34,6 +35,8 @@ export interface RunPreflightOpts {
     burnToken?: `0x${string}`;
     burnAmount?: bigint;
     prc20Balance?: bigint;
+    /** Defaults to false: warn on shortfall and proceed. */
+    enforceGasCheck?: boolean;
     /** Cascade-only: identifies which segment failed. */
     segmentIndex?: number;
 }

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

@@ -9,12 +9,13 @@
  * with `Error("STF")`, fees are burned, and the user sees an opaque
  * library string with no balance signal.
  *
- * `runPreflight` replaces that branch: it checks the **pre-clamp**
- * buffered pool quote against UEA balance (and optionally a PRC-20 burn
- * balance) and either:
- *   - emits `SEND-TX-203-03` (INFO, sufficient) and lets the caller proceed; or
+ * `runPreflight` checks the **pre-clamp** buffered pool quote against UEA
+ * balance (and optionally a PRC-20 burn balance) and either:
+ *   - emits `SEND-TX-203-03` (INFO, sufficient) and lets the caller proceed;
+ *   - emits `SEND-TX-203-03` (WARNING, insufficient) and proceeds when
+ *     enforceGasCheck is false/omitted; or
  *   - emits `SEND-TX-203-03` (ERROR, insufficient) + `SEND-TX-203-04` and
- *     throws `InsufficientUEABalanceError`.
+ *     throws `InsufficientUEABalanceError` when enforceGasCheck is true.
  *
  * The helper is intentionally not "pure" — it emits hooks and may throw.
  * Callers fetch all balances (so the helper itself does no I/O).
@@ -32,7 +33,7 @@ const errors_1 = require("./errors");
  * sees the actionable PRC-20 shortfall instead of a stale native PC error.
  */
 function runPreflight(opts) {
-    const { ctx, ueaAddress, ueaBalance, requiredValue, gasReserve, pathTag, burnToken, burnAmount, prc20Balance, segmentIndex, } = opts;
+    const { ctx, ueaAddress, ueaBalance, requiredValue, gasReserve, pathTag, burnToken, burnAmount, prc20Balance, enforceGasCheck = false, segmentIndex, } = opts;
     // Each route bucket gets its own preflight IDs so hook streams stay
     // self-consistent within their convention (R2 → 203-xx, R3 → 303-xx,
     // cascade → 003-xx). The three hook formatters share an identical
@@ -54,9 +55,15 @@ function runPreflight(opts) {
     if (burnAmount && burnAmount > BigInt(0) && burnToken) {
         const onHand = prc20Balance !== null && prc20Balance !== void 0 ? prc20Balance : BigInt(0);
         const sufficient = onHand >= burnAmount;
-        (0, context_1.fireProgressHook)(ctx, HOOK_PRE_INFO, burnAmount, onHand, sufficient, ueaAddress, pathTag, { kind: 'PRC20', burnToken, segmentIndex });
-        if (!sufficient) {
-            const shortfall = burnAmount - onHand;
+        const shortfall = sufficient ? BigInt(0) : burnAmount - onHand;
+        (0, context_1.fireProgressHook)(ctx, HOOK_PRE_INFO, burnAmount, onHand, sufficient, ueaAddress, pathTag, {
+            kind: 'PRC20',
+            burnToken,
+            segmentIndex,
+            enforceGasCheck,
+            shortfall,
+        });
+        if (!sufficient && enforceGasCheck) {
             (0, context_1.fireProgressHook)(ctx, HOOK_PRE_FAIL, burnAmount, onHand, shortfall, ueaAddress, pathTag, { kind: 'PRC20', burnToken, segmentIndex });
             throw new errors_1.InsufficientUEABalanceError({
                 required: burnAmount,
@@ -69,25 +76,32 @@ function runPreflight(opts) {
                 segmentIndex,
             });
         }
+        else if (!sufficient) {
+            (0, context_1.printLog)(ctx, `[preflight ${pathTag}] PRC-20 shortfall ${shortfall.toString()} for ${burnToken}; proceeding because enforceGasCheck=false`);
+        }
     }
     // 2. Native (UPC) balance check.
     const totalRequired = requiredValue + gasReserve;
     const sufficient = ueaBalance >= totalRequired;
-    (0, context_1.fireProgressHook)(ctx, HOOK_PRE_INFO, totalRequired, ueaBalance, sufficient, ueaAddress, pathTag, { kind: 'NATIVE', segmentIndex });
+    const shortfall = sufficient ? BigInt(0) : totalRequired - ueaBalance;
+    (0, context_1.fireProgressHook)(ctx, HOOK_PRE_INFO, totalRequired, ueaBalance, sufficient, ueaAddress, pathTag, { kind: 'NATIVE', segmentIndex, enforceGasCheck, shortfall });
     if (sufficient) {
         return { ok: true, adjustedValue: requiredValue };
     }
-    const shortfall = totalRequired - ueaBalance;
-    (0, context_1.fireProgressHook)(ctx, HOOK_PRE_FAIL, totalRequired, ueaBalance, shortfall, ueaAddress, pathTag, { kind: 'NATIVE', segmentIndex });
-    throw new errors_1.InsufficientUEABalanceError({
-        required: totalRequired,
-        available: ueaBalance,
-        shortfall,
-        ueaAddress,
-        pathTag,
-        reason: 'NATIVE',
-        segmentIndex,
-    });
+    if (enforceGasCheck) {
+        (0, context_1.fireProgressHook)(ctx, HOOK_PRE_FAIL, totalRequired, ueaBalance, shortfall, ueaAddress, pathTag, { kind: 'NATIVE', segmentIndex });
+        throw new errors_1.InsufficientUEABalanceError({
+            required: totalRequired,
+            available: ueaBalance,
+            shortfall,
+            ueaAddress,
+            pathTag,
+            reason: 'NATIVE',
+            segmentIndex,
+        });
+    }
+    (0, context_1.printLog)(ctx, `[preflight ${pathTag}] native shortfall ${shortfall.toString()}; proceeding because enforceGasCheck=false`);
+    return { ok: true, adjustedValue: requiredValue };
 }
 /**
  * SVM-only telemetry threshold. Buffered pool quotes above this value

package/src/lib/orchestrator/internals/route-handlers.js

@@ -312,7 +312,7 @@ function executeMultiChain(ctx, params, executeFn) {
  */
 function executeUoaToCea(ctx, params, executeFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e;
         const target = params.to;
         const targetChain = target.chain;
         const targetAddress = target.address;
@@ -418,7 +418,7 @@ function executeUoaToCea(ctx, params, executeFn) {
         const outboundReq = (0, payload_builders_1.buildOutboundRequest)(targetBytes, prc20Token, burnAmount, gasLimitForQuery, ceaPayload, ueaAddress, // revert recipient is the UEA
         (_d = params.maxPCForGas) !== null && _d !== void 0 ? _d : BigInt(0), outboundGasPrice);
         (0, context_1.printLog)(ctx, `executeUoaToCea — outbound request: ${JSON.stringify({
-            target: outboundReq.target,
+            recipient: outboundReq.recipient,
             token: outboundReq.token,
             amount: outboundReq.amount.toString(),
             gasLimit: outboundReq.gasLimit.toString(),
@@ -480,10 +480,9 @@ function executeUoaToCea(ctx, params, executeFn) {
             (0, context_1.printLog)(ctx, `executeUoaToCea — capping nativeValueForGas at 200 UPC ceiling (was ${nativeValueForGas.toString()})`);
             nativeValueForGas = EVM_NATIVE_VALUE_SAFETY_CAP;
         }
-        // Pre-flight: throws InsufficientUEABalanceError when UEA cannot cover
-        // (nativeValueForGas + gasReserve) or the PRC-20 burn amount. Replaces the
-        // legacy silent-clamp that previously submitted under-funded swaps and
-        // bubbled up as Uniswap STF reverts. PRC-20 check fires whenever
+        // Pre-flight: warns by default when UEA cannot cover (nativeValueForGas +
+        // gasReserve) or the PRC-20 burn amount; throws only when
+        // options.enforceGasCheck=true. PRC-20 check fires whenever
         // burnAmount > 0 — user must pre-hold the burn token, even when it equals
         // the gas token (the gateway does transferFrom BEFORE the gas swap).
         let prc20BalanceR2Evm;
@@ -505,6 +504,7 @@ function executeUoaToCea(ctx, params, executeFn) {
             burnToken: prc20Token,
             burnAmount,
             prc20Balance: prc20BalanceR2Evm,
+            enforceGasCheck: ((_e = params.options) === null || _e === void 0 ? void 0 : _e.enforceGasCheck) === true,
         });
         // Preflight success means nativeValueForGas already covers required + reserve; no adjust needed.
         // Build outbound multicalls (approve burn + sendUniversalTxOutbound with native value)
@@ -568,7 +568,7 @@ function executeUoaToCea(ctx, params, executeFn) {
  */
 function executeUoaToCeaSvm(ctx, params, target, executeFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         const targetChain = target.chain;
         const targetAddress = target.address; // 0x-prefixed, 32 bytes
         const ueaAddress = (0, uea_manager_1.computeUEAOffchain)(ctx);
@@ -656,7 +656,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
         const outboundReq = (0, payload_builders_1.buildOutboundRequest)(targetBytes, prc20Token, burnAmount, effectiveGasLimit, svmPayload, ueaAddress, // revert recipient is the UEA
         (_f = params.maxPCForGas) !== null && _f !== void 0 ? _f : BigInt(0), outboundGasPriceSvm);
         (0, context_1.printLog)(ctx, `executeUoaToCeaSvm — outbound request: ${JSON.stringify({
-            target: outboundReq.target,
+            recipient: outboundReq.recipient,
             token: outboundReq.token,
             amount: outboundReq.amount.toString(),
             gasLimit: outboundReq.gasLimit.toString(),
@@ -710,10 +710,9 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
             (0, context_1.printLog)(ctx, `executeUoaToCeaSvm — nativeValueForGas=${nativeValueForGas.toString()} (includes 2.2x buffer)`);
             (0, preflight_1.maybeFireSvmWarnThreshold)(ctx, nativeValueForGas, gasToken, 'R2_SVM');
         }
-        // Pre-flight: throws InsufficientUEABalanceError when UEA cannot cover
-        // (nativeValueForGas + SVM_GAS_RESERVE) or the PRC-20 burn amount.
-        // Replaces the legacy silent-clamp that previously submitted under-funded
-        // swaps and bubbled up as Uniswap STF reverts.
+        // Pre-flight: warns by default when UEA cannot cover (nativeValueForGas +
+        // SVM_GAS_RESERVE) or the PRC-20 burn amount; throws only when
+        // options.enforceGasCheck=true.
         // PRC-20 burn-balance pre-check fires whenever `burnAmount > 0`, regardless
         // of whether `prc20Token` happens to equal `gasToken`. The gateway's
         // `sendUniversalTxOutbound` does `transferFrom(user, gateway, burnAmount)`
@@ -739,6 +738,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
             burnToken: prc20Token,
             burnAmount,
             prc20Balance: prc20BalanceR2Svm,
+            enforceGasCheck: ((_j = params.options) === null || _j === void 0 ? void 0 : _j.enforceGasCheck) === true,
         });
         // --- Build Push Chain multicalls (approve + sendUniversalTxOutbound) ---
         // Reuse the same builder as EVM — this part is identical
@@ -804,7 +804,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
  */
 function executeCeaToPush(ctx, params, executeFn) {
     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;
         // 1. Validate and extract source chain
         if (!((_a = params.from) === null || _a === void 0 ? void 0 : _a.chain)) {
             throw new Error('Route 3 (CEA -> Push) requires from.chain to specify the source CEA chain');
@@ -936,15 +936,15 @@ function executeCeaToPush(ctx, params, executeFn) {
         const outboundGasLimit = (_f = params.gasLimit) !== null && _f !== void 0 ? _f : selectors_1.DEFAULT_CEA_TO_PUSH_GAS_LIMIT;
         (0, context_1.printLog)(ctx, `executeCeaToPush — prc20Token: ${prc20Token}, burnAmount: ${burnAmount.toString()}`);
         // 9. Build outbound request (same structure as Route 2)
-        // target = CEA address (for self-execution), value = 0 in payload
-        let outboundReq = (0, payload_builders_1.buildOutboundRequest)(ceaAddress, // target: CEA address (to=CEA for self-execution)
+        // recipient = CEA address (for self-execution), value = 0 in payload
+        let outboundReq = (0, payload_builders_1.buildOutboundRequest)(ceaAddress, // recipient: CEA address (to=CEA for self-execution)
         prc20Token, // token: native PRC-20 for source chain (for namespace lookup)
         burnAmount, // amount: 0 (payload-only, CEA uses its own balance)
         outboundGasLimit, ceaPayload, // payload: ABI-encoded CEA multicall
         ueaAddress, // revertRecipient: UEA
         (_g = params.maxPCForGas) !== null && _g !== void 0 ? _g : BigInt(0));
         (0, context_1.printLog)(ctx, `executeCeaToPush — outbound request: ${JSON.stringify({
-            target: outboundReq.target,
+            recipient: outboundReq.recipient,
             token: outboundReq.token,
             amount: outboundReq.amount.toString(),
             gasLimit: outboundReq.gasLimit.toString(),
@@ -1047,7 +1047,8 @@ function executeCeaToPush(ctx, params, executeFn) {
         }
         // Pre-flight (R3 EVM): no PRC-20 burn check — `burnAmount = 0` makes this
         // payload-only (UEA never holds the source-chain PRC-20; see plan §9 #4).
-        // Native UPC check still applies for the gas swap.
+        // Native UPC check still applies for the gas swap. It warns by default and
+        // throws only when options.enforceGasCheck=true.
         (0, preflight_1.runPreflight)({
             ctx,
             ueaAddress,
@@ -1055,6 +1056,7 @@ function executeCeaToPush(ctx, params, executeFn) {
             requiredValue: nativeValueForGas,
             gasReserve: OUTBOUND_GAS_RESERVE_R3,
             pathTag: 'R3_EVM',
+            enforceGasCheck: ((_l = params.options) === null || _l === void 0 ? void 0 : _l.enforceGasCheck) === true,
         });
         // 12. Build Push Chain multicalls (approvals + sendUniversalTxOutbound)
         const pushChainMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({
@@ -1120,7 +1122,7 @@ function executeCeaToPush(ctx, params, executeFn) {
  */
 function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c, _d, _e, _f;
         if (typeof params.to !== 'string') {
             throw new Error('Route 3 SVM (CEA -> Push): to must be a Push Chain address (string), not a ChainTarget');
         }
@@ -1170,9 +1172,9 @@ function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
         // on the cascade path, and the same precompile is used here.
         const burnAmount = BigInt(0);
         let effectiveGasLimit = (_a = params.gasLimit) !== null && _a !== void 0 ? _a : BigInt(0);
-        // Build outbound request: target = gateway program (self-call)
+        // Build outbound request: recipient = gateway program (self-call)
         let outboundReq = (0, payload_builders_1.buildOutboundRequest)(gatewayProgramHex, prc20Token, burnAmount, effectiveGasLimit, svmPayload, ueaAddress, (_b = params.maxPCForGas) !== null && _b !== void 0 ? _b : BigInt(0));
-        (0, context_1.printLog)(ctx, `executeCeaToPushSvm — outbound request: target=${outboundReq.target.slice(0, 20)}..., token=${outboundReq.token}, maxPCForGas=${outboundReq.maxPCForGas}`);
+        (0, context_1.printLog)(ctx, `executeCeaToPushSvm — outbound request: recipient=${outboundReq.recipient.slice(0, 20)}..., token=${outboundReq.token}, maxPCForGas=${outboundReq.maxPCForGas}`);
         // Query gas fees
         let gasFee = BigInt(0);
         let protocolFeeR3Svm = BigInt(0);
@@ -1245,13 +1247,13 @@ function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
             : UPWARD_BASE_CEILING_R3_SVM;
         // Upward-only allocation: when balance has headroom over the calibrated
         // value, consume more of it (up to the ceiling above). Down-clamp +
-        // zero-balance throws live in pre-flight.
+        // zero-balance handling lives in pre-flight.
         // Ordering note: pre-flight runs AFTER the upward adjust below; the
         // semantics are equivalent to running it before — when upward adjust
         // applies it sets nativeValueForGas to balance-reserve (capped), and the
         // post-adjust pre-flight check is always satisfied. When upward adjust is
         // skipped (balance too low), pre-flight runs against the calibrated value
-        // and throws cleanly on shortfall.
+        // and either warns or throws based on options.enforceGasCheck.
         if (currentBalance > OUTBOUND_GAS_RESERVE_R3_SVM &&
             currentBalance - OUTBOUND_GAS_RESERVE_R3_SVM > nativeValueForGas) {
             const balanceDriven = currentBalance - OUTBOUND_GAS_RESERVE_R3_SVM;
@@ -1273,6 +1275,7 @@ function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
             requiredValue: nativeValueForGas,
             gasReserve: OUTBOUND_GAS_RESERVE_R3_SVM,
             pathTag: 'R3_SVM',
+            enforceGasCheck: ((_f = params.options) === null || _f === void 0 ? void 0 : _f.enforceGasCheck) === true,
         });
         // Build Push Chain multicalls (approvals + sendUniversalTxOutbound)
         const pushChainMulticalls = (0, payload_builders_1.buildOutboundApprovalAndCall)({

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

@@ -97,6 +97,14 @@ function gasLimitForSvmGasFeeBudget(gasFeeBudget, gasPrice) {
     }
     return (gasFeeBudget + gasPrice - BigInt(1)) / gasPrice;
 }
+function resolveSvmGasLimitUsed(quote) {
+    if (quote.gasLimitUsed > BigInt(0) ||
+        quote.gasFee <= BigInt(0) ||
+        quote.gasPrice <= BigInt(0)) {
+        return quote;
+    }
+    return Object.assign(Object.assign({}, quote), { gasLimitUsed: gasLimitForSvmGasFeeBudget(quote.gasFee, quote.gasPrice) });
+}
 function ensureSvmFinalizeGasBudgetQuote(_a) {
     return tslib_1.__awaiter(this, arguments, void 0, function* ({ ctx, ueaAddress, targetChain, prc20Token, quote, splMintBase58, burnAmount, pathTag, }) {
         const minGasFee = yield getSvmFinalizeGasBudget({
@@ -107,9 +115,10 @@ function ensureSvmFinalizeGasBudgetQuote(_a) {
             burnAmount,
         });
         if (quote.gasFee >= minGasFee) {
-            (0, context_1.printLog)(ctx, `${pathTag} — SVM finalize gas budget ok: gasFee=${quote.gasFee.toString()}, ` +
-                `minimum=${minGasFee.toString()}, gasLimit=${quote.gasLimitUsed.toString()}`);
-            return quote;
+            const resolvedQuote = resolveSvmGasLimitUsed(quote);
+            (0, context_1.printLog)(ctx, `${pathTag} — SVM finalize gas budget ok: gasFee=${resolvedQuote.gasFee.toString()}, ` +
+                `minimum=${minGasFee.toString()}, gasLimit=${resolvedQuote.gasLimitUsed.toString()}`);
+            return resolvedQuote;
         }
         const bumpedGasLimit = gasLimitForSvmGasFeeBudget(minGasFee, quote.gasPrice);
         (0, context_1.printLog)(ctx, `${pathTag} — bumping SVM gasLimit ${quote.gasLimitUsed.toString()} → ${bumpedGasLimit.toString()}; ` +
@@ -119,7 +128,7 @@ function ensureSvmFinalizeGasBudgetQuote(_a) {
             (0, context_1.printLog)(ctx, `${pathTag} — WARNING: bumped SVM gasFee=${bumpedQuote.gasFee.toString()} ` +
                 `still below finalize minimum=${minGasFee.toString()}`);
         }
-        return bumpedQuote;
+        return resolveSvmGasLimitUsed(bumpedQuote);
     });
 }
 /**

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

@@ -4,7 +4,7 @@ import type { AccountStatus, UniversalTxResponse } from './orchestrator.types';
 import { ProgressEvent } from '../progress-hook/progress-hook.types';
 import { PushClient } from '../push-client/push-client';
 import type { UniversalAccount, UniversalSigner } from '../universal/universal.types';
-import { ExecuteParams, UniversalExecuteParams, PreparedUniversalTx, CascadedTxResponse, RescueFundsParams } from './orchestrator.types';
+import { ExecuteParams, UniversalExecuteParams, PreparedUniversalTx, CascadedTxResponse, CascadeExecutionOptions, TransactionExecutionOptions, RescueFundsParams } from './orchestrator.types';
 import { TransactionRoute } from './route-detector';
 export declare class Orchestrator {
     private readonly universalSigner;
@@ -71,15 +71,16 @@ export declare class Orchestrator {
      * Routes 2-4 (multi-chain) delegate to prepareTransaction().send().
      * Route 1 (Push Chain) dispatches to extracted sub-flow modules.
      */
-    execute(params: ExecuteParams | UniversalExecuteParams): Promise<UniversalTxResponse>;
+    execute(params: ExecuteParams | UniversalExecuteParams, options?: TransactionExecutionOptions): Promise<UniversalTxResponse>;
     /**
      * Prepare a universal transaction without executing it.
      * Returns a PreparedUniversalTx that can be chained with thenOn() or sent with send().
      *
      * @param params - Universal execution parameters
+     * @param options - Optional transaction behavior switches.
      * @returns PreparedUniversalTx with chaining capabilities
      */
-    prepareTransaction(params: UniversalExecuteParams): Promise<PreparedUniversalTx>;
+    prepareTransaction(params: UniversalExecuteParams, options?: TransactionExecutionOptions): Promise<PreparedUniversalTx>;
     /**
      * Creates a cascaded transaction builder for nested multi-chain execution.
      * The cascade composes all hops bottom-to-top into a single Push Chain tx.
@@ -91,9 +92,7 @@ export declare class Orchestrator {
      *   tracking). Dedups by reference if it matches the init-time hook.
      * @returns Object with send() method
      */
-    createCascadedBuilder(preparedTxs: PreparedUniversalTx[], options?: {
-        progressHook?: (event: ProgressEvent) => void;
-    }): {
+    createCascadedBuilder(preparedTxs: PreparedUniversalTx[], options?: CascadeExecutionOptions): {
         send: () => Promise<CascadedTxResponse>;
     };
     /**

package/src/lib/orchestrator/orchestrator.js

@@ -129,9 +129,12 @@ class Orchestrator {
      * Routes 2-4 (multi-chain) delegate to prepareTransaction().send().
      * Route 1 (Push Chain) dispatches to extracted sub-flow modules.
      */
-    execute(params) {
+    execute(params, options) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d;
+            if (options) {
+                params = Object.assign(Object.assign({}, params), { options: Object.assign(Object.assign({}, params.options), options) });
+            }
             // Snapshot the caller's active route — `executeMultiChain` recurses into
             // this same method for R2/R3's inner Push-side execution, and without
             // snapshot/restore the recursive `detectRoute(params)` would clobber the
@@ -285,10 +288,14 @@ class Orchestrator {
      * Returns a PreparedUniversalTx that can be chained with thenOn() or sent with send().
      *
      * @param params - Universal execution parameters
+     * @param options - Optional transaction behavior switches.
      * @returns PreparedUniversalTx with chaining capabilities
      */
-    prepareTransaction(params) {
+    prepareTransaction(params, options) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (options) {
+                params = Object.assign(Object.assign({}, params), { options: Object.assign(Object.assign({}, params.options), options) });
+            }
             return (0, internals_1.prepareTransaction)(this.ctx, params, this._getCascadeCallbacks());
         });
     }
@@ -306,7 +313,7 @@ class Orchestrator {
     createCascadedBuilder(preparedTxs, options) {
         const perCallHook = options === null || options === void 0 ? void 0 : options.progressHook;
         if (!perCallHook) {
-            return (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks());
+            return (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks(), undefined);
         }
         // Wrap ctx.progressHook for the synchronous send() phase — captures every
         // fireProgressHook(ctx, ...) call during pre-flight, composeCascade, and

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

@@ -31,6 +31,14 @@ export type UniversalTo = `0x${string}` | ChainTarget;
  * Transaction route identifiers
  */
 export type TransactionRouteType = 'UOA_TO_PUSH' | 'UOA_TO_CEA' | 'CEA_TO_PUSH' | 'CEA_TO_CEA';
+export interface TransactionExecutionOptions {
+    /**
+     * Enforce the SDK pre-flight gas/balance check.
+     * - false/omitted: emit a warning on shortfall and continue
+     * - true: emit the failure hook, throw InsufficientUEABalanceError, and stop
+     */
+    enforceGasCheck?: boolean;
+}
 export type ExecuteParams = {
     /**
      * The target contract or account on Push Chain.
@@ -80,6 +88,10 @@ export type ExecuteParams = {
      * Optional for signature expiry
      */
     deadline?: bigint;
+    /**
+     * Optional transaction behavior switches.
+     */
+    options?: TransactionExecutionOptions;
     /**
      * Optional: pay gas in a specific token. If not provided, use `token` (bridge token) when present; otherwise, native token.
      */
@@ -432,7 +444,7 @@ export interface SvmExecutePayloadFields {
  * Request structure for sendUniversalTxOutbound on Push Chain
  * Used for Routes 2, 3, 4 (outbound from Push)
  *
- * NOTE: The `target` field is raw recipient bytes for the destination chain.
+ * NOTE: The `recipient` field is raw recipient bytes for the destination chain.
  * For EVM CEA funds-parking, use the zero recipient when `payload` is empty.
  */
 export interface UniversalOutboundTxRequest {
@@ -440,7 +452,7 @@ export interface UniversalOutboundTxRequest {
      * Raw destination recipient bytes. EVM routes usually pass a 20-byte address;
      * SVM routes pass a 32-byte program/account address.
      */
-    target: `0x${string}`;
+    recipient: `0x${string}`;
     /** PRC20 token address on Push Chain to burn */
     token: `0x${string}`;
     /** Amount to burn (0 for no-burn, use existing CEA balance) */
@@ -662,6 +674,10 @@ export interface CascadeTrackOptions {
      */
     eventHook?: (event: import('../progress-hook/progress-hook.types').ProgressEvent) => void;
 }
+export interface CascadeExecutionOptions {
+    /** Per-call progress callback. */
+    progressHook?: (event: import('../progress-hook/progress-hook.types').ProgressEvent) => void;
+}
 /**
  * Progress event emitted during cascade tracking
  */

package/src/lib/orchestrator/payload-builders.d.ts

@@ -70,8 +70,8 @@ export declare function buildSendUniversalTxToUEA(ceaAddress: `0x${string}`, tok
 /**
  * Build UniversalOutboundTxRequest for Push Chain outbound
  *
- * @param target - Raw recipient bytes for the destination chain. For EVM CEA
- *                 funds-parking, use the zero recipient when payload is empty.
+ * @param recipient - Raw recipient bytes for the destination chain. For EVM CEA
+ *                    funds-parking, use the zero recipient when payload is empty.
  * @param prc20Token - PRC20 token address to burn (or address(0) for native)
  * @param amount - Amount to burn
  * @param gasLimit - Gas limit for fee calculation
@@ -81,7 +81,7 @@ export declare function buildSendUniversalTxToUEA(ceaAddress: `0x${string}`, tok
  * @param gasPrice - Destination-chain gas price override (0 = UniversalCore default)
  * @returns UniversalOutboundTxRequest object
  */
-export declare function buildOutboundRequest(target: `0x${string}`, prc20Token: `0x${string}`, amount: bigint, gasLimit: bigint, payload: `0x${string}`, revertRecipient: `0x${string}`, maxPCForGas?: bigint, gasPrice?: bigint): UniversalOutboundTxRequest;
+export declare function buildOutboundRequest(recipient: `0x${string}`, prc20Token: `0x${string}`, amount: bigint, gasLimit: bigint, payload: `0x${string}`, revertRecipient: `0x${string}`, maxPCForGas?: bigint, gasPrice?: bigint): UniversalOutboundTxRequest;
 export declare function assertCeaFundsParkingInvariant(recipient: `0x${string}`, payload: `0x${string}`): void;
 /**
  * Build ERC20 transfer multicall

package/src/lib/orchestrator/payload-builders.js

@@ -226,8 +226,8 @@ function buildSendUniversalTxToUEA(ceaAddress, token, amount, payload, revertRec
 /**
  * Build UniversalOutboundTxRequest for Push Chain outbound
  *
- * @param target - Raw recipient bytes for the destination chain. For EVM CEA
- *                 funds-parking, use the zero recipient when payload is empty.
+ * @param recipient - Raw recipient bytes for the destination chain. For EVM CEA
+ *                    funds-parking, use the zero recipient when payload is empty.
  * @param prc20Token - PRC20 token address to burn (or address(0) for native)
  * @param amount - Amount to burn
  * @param gasLimit - Gas limit for fee calculation
@@ -237,9 +237,9 @@ function buildSendUniversalTxToUEA(ceaAddress, token, amount, payload, revertRec
  * @param gasPrice - Destination-chain gas price override (0 = UniversalCore default)
  * @returns UniversalOutboundTxRequest object
  */
-function buildOutboundRequest(target, prc20Token, amount, gasLimit, payload, revertRecipient, maxPCForGas = BigInt(0), gasPrice = BigInt(0)) {
+function buildOutboundRequest(recipient, prc20Token, amount, gasLimit, payload, revertRecipient, maxPCForGas = BigInt(0), gasPrice = BigInt(0)) {
     return {
-        target,
+        recipient,
         token: prc20Token,
         amount,
         gasLimit,

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

@@ -23,6 +23,18 @@ const friendlyChain = (chainOrNs) => {
     const key = utils_1.Utils.chains.getChainName(asString);
     return key ? toTitleCase(key) : asString;
 };
+function preflightLevel(sufficient, enforceGasCheck) {
+    if (sufficient)
+        return 'INFO';
+    return enforceGasCheck === false ? 'WARNING' : 'ERROR';
+}
+function preflightSuffix(sufficient, pathTag, enforceGasCheck) {
+    if (sufficient)
+        return `sufficient (${pathTag})`;
+    return enforceGasCheck === false
+        ? `INSUFFICIENT (${pathTag}); warning only, proceeding`
+        : `INSUFFICIENT (${pathTag})`;
+}
 /**
  * Classify a sign-time error as either a true wallet user-decline
  * (viem `UserRejectedRequestError`, ethers `ACTION_REJECTED`, EIP-1193 4001,
@@ -307,15 +319,16 @@ const RAW_HOOKS_R2 = {
         level: 'SUCCESS',
     }),
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_03]: (required, available, sufficient, ueaAddress, pathTag, extra) => {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
         const availableStr = kind === 'PRC20' ? `${available} units` : (0, formatters_1.formatPc)(available, 4);
         const requiredStr = kind === 'PRC20' ? `${required} units` : (0, formatters_1.formatPc)(required, 4);
+        const enforceGasCheck = extra === null || extra === void 0 ? void 0 : extra.enforceGasCheck;
         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})`,
+                preflightSuffix(sufficient, pathTag, enforceGasCheck),
             response: {
                 required,
                 available,
@@ -325,8 +338,11 @@ const RAW_HOOKS_R2 = {
                 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,
+                enforceGasCheck: enforceGasCheck !== null && enforceGasCheck !== void 0 ? enforceGasCheck : null,
+                warningOnly: !sufficient && enforceGasCheck === false,
+                shortfall: (_d = extra === null || extra === void 0 ? void 0 : extra.shortfall) !== null && _d !== void 0 ? _d : null,
             },
-            level: sufficient ? 'INFO' : 'ERROR',
+            level: preflightLevel(sufficient, enforceGasCheck),
         };
     },
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_203_04]: (required, available, shortfall, ueaAddress, pathTag, extra) => {
@@ -521,15 +537,16 @@ const RAW_HOOKS_R3 = {
     }),
     // R3 single-route pre-flight balance check. Same payload shape as 203-03/04/05.
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_04]: (required, available, sufficient, ueaAddress, pathTag, extra) => {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
         const availableStr = kind === 'PRC20' ? `${available} units` : (0, formatters_1.formatPc)(available, 4);
         const requiredStr = kind === 'PRC20' ? `${required} units` : (0, formatters_1.formatPc)(required, 4);
+        const enforceGasCheck = extra === null || extra === void 0 ? void 0 : extra.enforceGasCheck;
         return {
             id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_04,
             title: 'Pre-flight Balance Check',
             message: `UEA balance: ${availableStr}; required: ${requiredStr}; ` +
-                `${sufficient ? 'sufficient' : 'INSUFFICIENT'} (${pathTag})`,
+                preflightSuffix(sufficient, pathTag, enforceGasCheck),
             response: {
                 required,
                 available,
@@ -539,8 +556,11 @@ const RAW_HOOKS_R3 = {
                 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,
+                enforceGasCheck: enforceGasCheck !== null && enforceGasCheck !== void 0 ? enforceGasCheck : null,
+                warningOnly: !sufficient && enforceGasCheck === false,
+                shortfall: (_d = extra === null || extra === void 0 ? void 0 : extra.shortfall) !== null && _d !== void 0 ? _d : null,
             },
-            level: sufficient ? 'INFO' : 'ERROR',
+            level: preflightLevel(sufficient, enforceGasCheck),
         };
     },
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_303_05]: (required, available, shortfall, ueaAddress, pathTag, extra) => {
@@ -785,15 +805,16 @@ const RAW_HOOKS_MULTICHAIN = {
     // 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;
+        var _a, _b, _c, _d;
         const kind = (_a = extra === null || extra === void 0 ? void 0 : extra.kind) !== null && _a !== void 0 ? _a : 'NATIVE';
         const availableStr = kind === 'PRC20' ? `${available} units` : (0, formatters_1.formatPc)(available, 4);
         const requiredStr = kind === 'PRC20' ? `${required} units` : (0, formatters_1.formatPc)(required, 4);
+        const enforceGasCheck = extra === null || extra === void 0 ? void 0 : extra.enforceGasCheck;
         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})`,
+                preflightSuffix(sufficient, pathTag, enforceGasCheck),
             response: {
                 required,
                 available,
@@ -803,8 +824,11 @@ const RAW_HOOKS_MULTICHAIN = {
                 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,
+                enforceGasCheck: enforceGasCheck !== null && enforceGasCheck !== void 0 ? enforceGasCheck : null,
+                warningOnly: !sufficient && enforceGasCheck === false,
+                shortfall: (_d = extra === null || extra === void 0 ? void 0 : extra.shortfall) !== null && _d !== void 0 ? _d : null,
             },
-            level: sufficient ? 'INFO' : 'ERROR',
+            level: preflightLevel(sufficient, enforceGasCheck),
         };
     },
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_003_04]: (required, available, shortfall, ueaAddress, pathTag, extra) => {

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

@@ -7,7 +7,7 @@ export type ProgressEvent = {
     id: string;
     title: string;
     message: string;
-    level: 'INFO' | 'SUCCESS' | 'ERROR';
+    level: 'INFO' | 'SUCCESS' | 'WARNING' | 'ERROR';
     response: object | null;
     timestamp: string;
 };
@@ -68,7 +68,7 @@ export declare enum PROGRESS_HOOK {
     SEND_TX_303_03_01 = "SEND-TX-303-03-01",// Sizer: Case A (< $1, padded)
     SEND_TX_303_03_02 = "SEND-TX-303-03-02",// Sizer: Case B ($1–$10, happy path)
     SEND_TX_303_03_03 = "SEND-TX-303-03-03",// Sizer: Case C (> $10, split + overflow bridge)
-    SEND_TX_303_04 = "SEND-TX-303-04",// R3 pre-flight balance check (INFO when sufficient, ERROR when insufficient)
+    SEND_TX_303_04 = "SEND-TX-303-04",// R3 pre-flight balance check (INFO/WARNING/ERROR per enforceGasCheck)
     SEND_TX_303_05 = "SEND-TX-303-05",// R3 pre-flight FAILED (ERROR, terminal precursor before 399-02)
     SEND_TX_303_06 = "SEND-TX-303-06",// R3 SVM warn-threshold tripped (INFO, no action)
     SEND_TX_304_01 = "SEND-TX-304-01",
@@ -87,7 +87,7 @@ 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_03 = "SEND-TX-003-03",// Cascade pre-flight balance check (INFO/WARNING/ERROR per enforceGasCheck)
     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",

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

@@ -37,8 +37,10 @@ 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).
+    // Pre-flight balance check (203-03 INFO when sufficient, WARNING when
+    // short but enforceGasCheck=false, ERROR when enforceGasCheck=true;
+    // 203-04 ERROR terminal precursor on enforced 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";

package/src/lib/push-chain/push-chain.d.ts

@@ -6,7 +6,7 @@ import { TypedData, TypedDataDomain } from 'viem';
 import { ProgressEvent } from '../progress-hook/progress-hook.types';
 import type { AccountStatus } from '../orchestrator/orchestrator.types';
 import { MoveableToken, PayableToken, ConversionQuote, MoveableTokenAccessor, PayableTokenAccessor } from '../constants/tokens';
-import type { PreparedUniversalTx, CascadedTxResponse } from '../orchestrator/orchestrator.types';
+import type { PreparedUniversalTx, CascadedTxResponse, CascadeExecutionOptions } from '../orchestrator/orchestrator.types';
 /**
  * @class PushChain
  *
@@ -67,11 +67,19 @@ export declare class PushChain {
          *   to: { address: '0x...', chain: CHAIN.BNB_TESTNET },
          *   value: parseEther('0.001')
          * });
+         *
+         * @param options.enforceGasCheck - Defaults to false. When true, the
+         *   SDK stops on pre-flight gas/balance shortfall instead of warning
+         *   and proceeding.
          */
         sendTransaction: Orchestrator['execute'];
         /**
          * Prepare a universal transaction without executing it.
          * Returns a PreparedUniversalTx that can be passed to executeTransactions.
+         *
+         * @param options.enforceGasCheck - Defaults to false. When true, the
+         *   prepared transaction carries strict pre-flight gas/balance enforcement
+         *   into executeTransactions.
          */
         prepareTransaction: Orchestrator['prepareTransaction'];
         /**
@@ -86,9 +94,7 @@ export declare class PushChain {
          *   if it matches the init-time hook. Note: concurrent calls on the
          *   same instance share the hook channel during the broadcast phase.
          */
-        executeTransactions: (txs: PreparedUniversalTx[], options?: {
-            progressHook?: (event: ProgressEvent) => void;
-        }) => Promise<CascadedTxResponse>;
+        executeTransactions: (txs: PreparedUniversalTx[], options?: CascadeExecutionOptions) => Promise<CascadedTxResponse>;
         /**
          * Tracks a transaction by hash on Push Chain
          */

package/src/lib/push-chain/push-chain.js

@@ -81,8 +81,8 @@ class PushChain {
                 }
                 return orchestrator.execute.bind(orchestrator)(...args);
             },
-            prepareTransaction: (params) => {
-                return orchestrator.prepareTransaction.bind(orchestrator)(params);
+            prepareTransaction: (params, options) => {
+                return orchestrator.prepareTransaction.bind(orchestrator)(params, options);
             },
             executeTransactions: (txs, options) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 if (this.isReadMode) {

package/src/lib/utils.js

@@ -711,7 +711,7 @@ Utils.tokens = {
                 else if (isBaseFamily)
                     key = 'USDC_BASE';
                 else if (isBnbFamily)
-                    key = 'USDC_BNB';
+                    key = 'USDC_BSC';
                 else if (isSolFamily)
                     key = 'USDC_SOL';
                 else