@pushchain/core 5.1.18 → 6.0.1

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.
@@ -50,6 +58,12 @@ export type ExecuteParams = {
      * @reason Prevents runaway gas consumption and lets users enforce limits.
      */
     gasLimit?: bigint;
+    /**
+     * Optional cap on native PC used for outbound gas swap.
+     * Applies only to Push -> external-chain outbound legs. Omit or set 0n for
+     * uncapped legacy behavior.
+     */
+    maxPCForGas?: bigint;
     /**
      * Optional override for the EIP-1559 max fee per gas (in wei).
      * @reason Gives callers direct control over total gas price to speed up or save cost.
@@ -74,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.
      */
@@ -426,25 +444,26 @@ export interface SvmExecutePayloadFields {
  * Request structure for sendUniversalTxOutbound on Push Chain
  * Used for Routes 2, 3, 4 (outbound from Push)
  *
- * NOTE: The `target` field is a LEGACY parameter for contract compatibility.
- * The deployed UniversalGatewayPC contract still expects this field, but it will
- * be removed in future contract upgrades. Pass any non-zero address (e.g., CEA address).
- * The actual destination is determined by the relay from the token's SOURCE_CHAIN_NAMESPACE.
+ * 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 {
     /**
-     * LEGACY/DUMMY: Raw destination address bytes for contract compatibility.
-     * Pass any non-zero address - this value is NOT used by the relay to determine
-     * the actual transaction destination. Will be removed in future contract upgrades.
+     * 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) */
     amount: bigint;
-    /** Gas limit for fee quote (0 = default BASE_GAS_LIMIT) */
+    /** Gas limit for fee quote (0 = per-chain default resolved by UniversalCore) */
     gasLimit: bigint;
-    /** Raw ABI-encoded Multicall[] (no selector prefix) */
+    /** Gas price override for destination-chain gas (0 = UniversalCore default) */
+    gasPrice: bigint;
+    /** Max native PC that may be used for gas swap (0 = uncapped legacy behavior) */
+    maxPCForGas: bigint;
+    /** Destination execution payload; empty only for explicit funds parking */
     payload: `0x${string}`;
     /** Address to receive funds on revert */
     revertRecipient: `0x${string}`;
@@ -488,8 +507,12 @@ export interface HopDescriptor {
     gasToken?: `0x${string}`;
     /** Gas fee amount in gas token */
     gasFee?: bigint;
+    /** Destination-chain gas price quoted by UniversalCore */
+    gasPrice?: bigint;
     /** Gas limit for outbound relay */
     gasLimit: bigint;
+    /** Max native PC used for outbound gas swap (0 = uncapped) */
+    maxPCForGas: bigint;
     /** UEA address */
     ueaAddress: `0x${string}`;
     /** Address to receive funds on revert */
@@ -538,8 +561,12 @@ export interface CascadeSegment {
     gasToken?: `0x${string}`;
     /** Total gas fee for this segment */
     gasFee?: bigint;
+    /** Destination-chain gas price quoted by UniversalCore */
+    gasPrice?: bigint;
     /** Gas limit for this segment */
     gasLimit?: bigint;
+    /** Max native PC used for outbound gas swap (0 = uncapped) */
+    maxPCForGas?: bigint;
     /**
      * SDK 5.2 gas-abstraction sizing decision for this segment. When the
      * segment merges multiple hops, the strictest (highest category) sizing
@@ -647,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
  */
@@ -756,6 +787,13 @@ export interface WaitForOutboundOptions {
      * has multiple outbound operations to different chains.
      */
     _expectedDestinationChain?: string;
+    /**
+     * @internal Zero-based index among outbound entries that match
+     * `_expectedDestinationChain`. Used when a composed cascade emits multiple
+     * outbound operations to the same chain and a later hop must track the later
+     * observed tx rather than the first one.
+     */
+    _outboundIndex?: number;
 }
 /**
  * UEA deployment and version status.

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

@@ -70,18 +70,19 @@ export declare function buildSendUniversalTxToUEA(ceaAddress: `0x${string}`, tok
 /**
  * Build UniversalOutboundTxRequest for Push Chain outbound
  *
- * @param target - LEGACY/DUMMY: Any non-zero address for contract compatibility.
- *                 This value is NOT used by the relay to determine the actual destination.
- *                 The relay determines the destination from the PRC-20 token's SOURCE_CHAIN_NAMESPACE.
- *                 Will be removed in future contract upgrades.
+ * @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
- * @param payload - CEA multicall payload
+ * @param payload - Destination execution payload
  * @param revertRecipient - Address to receive funds on revert
+ * @param maxPCForGas - Max native PC used for gas swap (0 = uncapped)
+ * @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}`): 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

@@ -6,6 +6,7 @@ exports.buildCeaMulticallPayload = buildCeaMulticallPayload;
 exports.buildInboundUniversalPayload = buildInboundUniversalPayload;
 exports.buildSendUniversalTxToUEA = buildSendUniversalTxToUEA;
 exports.buildOutboundRequest = buildOutboundRequest;
+exports.assertCeaFundsParkingInvariant = assertCeaFundsParkingInvariant;
 exports.buildErc20Transfer = buildErc20Transfer;
 exports.buildErc20WithdrawalMulticall = buildErc20WithdrawalMulticall;
 exports.buildMigrationPayload = buildMigrationPayload;
@@ -225,27 +226,38 @@ function buildSendUniversalTxToUEA(ceaAddress, token, amount, payload, revertRec
 /**
  * Build UniversalOutboundTxRequest for Push Chain outbound
  *
- * @param target - LEGACY/DUMMY: Any non-zero address for contract compatibility.
- *                 This value is NOT used by the relay to determine the actual destination.
- *                 The relay determines the destination from the PRC-20 token's SOURCE_CHAIN_NAMESPACE.
- *                 Will be removed in future contract upgrades.
+ * @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
- * @param payload - CEA multicall payload
+ * @param payload - Destination execution payload
  * @param revertRecipient - Address to receive funds on revert
+ * @param maxPCForGas - Max native PC used for gas swap (0 = uncapped)
+ * @param gasPrice - Destination-chain gas price override (0 = UniversalCore default)
  * @returns UniversalOutboundTxRequest object
  */
-function buildOutboundRequest(target, prc20Token, amount, gasLimit, payload, revertRecipient) {
+function buildOutboundRequest(recipient, prc20Token, amount, gasLimit, payload, revertRecipient, maxPCForGas = BigInt(0), gasPrice = BigInt(0)) {
     return {
-        target,
+        recipient,
         token: prc20Token,
         amount,
         gasLimit,
+        gasPrice,
+        maxPCForGas,
         payload,
         revertRecipient,
     };
 }
+function assertCeaFundsParkingInvariant(recipient, payload) {
+    if (payload !== '0x')
+        return;
+    if (recipient === '0x')
+        return;
+    if (recipient.toLowerCase() === selectors_1.ZERO_ADDRESS.toLowerCase())
+        return;
+    throw new Error('Empty CEA payloads must use the zero recipient to park funds');
+}
 /**
  * Build ERC20 transfer multicall
  *

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,
@@ -251,13 +263,16 @@ const RAW_HOOKS_R1 = {
             level: 'SUCCESS',
         };
     },
-    [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: Object.assign({ error: errMessage }, (decodedError ? { decodedError } : {})),
-        level: 'ERROR',
-    }),
+    [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02]: (errMessage, decodedError) => {
+        const normalizedErrMessage = (0, formatters_1.normalizePcInsufficientFundsError)(errMessage);
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02,
+            title: 'Push Chain Tx Failed',
+            message: normalizedErrMessage,
+            response: Object.assign({ error: normalizedErrMessage }, (decodedError ? { decodedError } : {})),
+            level: 'ERROR',
+        };
+    },
 };
 // =============================================================================
 // Route 2 — UEA → UGPC → CEA on target chain (201–299, signature-only)
@@ -304,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,
@@ -322,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) => {
@@ -518,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,
@@ -536,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) => {
@@ -664,17 +687,22 @@ 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, decodedError) => ({
-        id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02,
-        title: phase === 'outbound'
-            ? `${friendlyChain(chain)} Tx Failed`
-            : phase === 'push'
-                ? 'Push Chain Tx Failed'
-                : 'Push Chain Inbound Tx Failed',
-        message: errorMessage,
-        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_02]: (errorMessage, phase = 'inbound', chain, decodedError) => {
+        const normalizedErrorMessage = phase === 'push'
+            ? (0, formatters_1.normalizePcInsufficientFundsError)(errorMessage)
+            : errorMessage;
+        return {
+            id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02,
+            title: phase === 'outbound'
+                ? `${friendlyChain(chain)} Tx Failed`
+                : phase === 'push'
+                    ? 'Push Chain Tx Failed'
+                    : 'Push Chain Inbound Tx Failed',
+            message: normalizedErrorMessage,
+            response: Object.assign({ error: normalizedErrorMessage, 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') => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03,
         title: phase === 'outbound'
@@ -777,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,
@@ -795,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/universal-tx-detector/events.d.ts

@@ -2,8 +2,10 @@
  * Event ABI fragments used by the universal-tx detector.
  *
  * Sourced from push-chain-gateway-contracts and push-chain-core-contracts:
- *   - UniversalTx, UniversalTxExecuted, RevertUniversalTx, FundsRescued
+ *   - UniversalTx, RevertUniversalTx, FundsRescued
  *       → contracts/evm-gateway/src/interfaces/IUniversalGateway.sol
+ *   - UniversalTxExecuted
+ *       → push-chain-core-contracts/src/Interfaces/ICEA.sol
  *   - UniversalTxFinalized, UniversalTxReverted, FundsRescued (vault)
  *       → contracts/evm-gateway/src/interfaces/IVault.sol
  *   - UniversalTxOutbound

package/src/lib/universal-tx-detector/events.js

@@ -3,8 +3,10 @@
  * Event ABI fragments used by the universal-tx detector.
  *
  * Sourced from push-chain-gateway-contracts and push-chain-core-contracts:
- *   - UniversalTx, UniversalTxExecuted, RevertUniversalTx, FundsRescued
+ *   - UniversalTx, RevertUniversalTx, FundsRescued
  *       → contracts/evm-gateway/src/interfaces/IUniversalGateway.sol
+ *   - UniversalTxExecuted
+ *       → push-chain-core-contracts/src/Interfaces/ICEA.sol
  *   - UniversalTxFinalized, UniversalTxReverted, FundsRescued (vault)
  *       → contracts/evm-gateway/src/interfaces/IVault.sol
  *   - UniversalTxOutbound

package/src/lib/universal-tx-detector/svm-events.d.ts

@@ -10,7 +10,7 @@
 /**
  * Mapping: 8-byte discriminator (lowercase hex, no 0x) → Anchor event name.
  * Only events with EVM classifier parity are listed; the keeper-agnostic
- * ones (BlockUsdCapUpdated, ProtocolFeeCollected, etc.) are intentionally
+ * ones (BlockUsdCapUpdated, inbound-fee events, etc.) are intentionally
  * skipped — they wouldn't classify to any UniversalTxKind anyway.
  */
 export declare const SVM_EVENT_DISCRIMINATORS: Record<string, string>;

package/src/lib/universal-tx-detector/svm-events.js

@@ -15,7 +15,7 @@ const toHex = (bytes) => bytes.map((b) => b.toString(16).padStart(2, '0')).join(
 /**
  * Mapping: 8-byte discriminator (lowercase hex, no 0x) → Anchor event name.
  * Only events with EVM classifier parity are listed; the keeper-agnostic
- * ones (BlockUsdCapUpdated, ProtocolFeeCollected, etc.) are intentionally
+ * ones (BlockUsdCapUpdated, inbound-fee events, etc.) are intentionally
  * skipped — they wouldn't classify to any UniversalTxKind anyway.
  */
 exports.SVM_EVENT_DISCRIMINATORS = {

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