@pushchain/core 6.0.15 → 6.0.17

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

@@ -15,6 +15,8 @@
  * `executeFn` callback that replaces the former `this.execute()` call.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRequiredNativeBalanceForOutbound = getRequiredNativeBalanceForOutbound;
+exports.shouldSkipFeeLockingForOutbound = shouldSkipFeeLockingForOutbound;
 exports.resolveR2DestinationFundsToken = resolveR2DestinationFundsToken;
 exports.executeMultiChain = executeMultiChain;
 exports.executeUoaToCea = executeUoaToCea;
@@ -46,6 +48,13 @@ const payload_builders_1 = require("../payload-builders");
 const selectors_1 = require("../../constants/selectors");
 const erc20_evm_1 = require("../../constants/abi/erc20.evm");
 const push_chain_1 = require("../../push-chain/push-chain");
+function getRequiredNativeBalanceForOutbound(nativeValueForGas, gasReserve) {
+    return nativeValueForGas + gasReserve;
+}
+function shouldSkipFeeLockingForOutbound(opts) {
+    return (opts.isUEADeployed &&
+        opts.balance >= getRequiredNativeBalanceForOutbound(opts.nativeValueForGas, opts.gasReserve));
+}
 // =============================================================================
 // Route 2 (UEA → CEA) phase helpers
 // =============================================================================
@@ -524,6 +533,13 @@ function executeUoaToCea(ctx, params, executeFn) {
                 args: [ueaAddress],
             });
         }
+        const requiredNativeBalanceR2Evm = getRequiredNativeBalanceForOutbound(nativeValueForGas, EVM_GAS_RESERVE);
+        const skipFeeLockingR2Evm = shouldSkipFeeLockingForOutbound({
+            isUEADeployed,
+            balance: effectiveBalance,
+            nativeValueForGas,
+            gasReserve: EVM_GAS_RESERVE,
+        });
         (0, preflight_1.runPreflight)({
             ctx,
             ueaAddress,
@@ -557,7 +573,7 @@ function executeUoaToCea(ctx, params, executeFn) {
                 isDeployed: isUEADeployed,
                 nonce: ueaNonce,
                 balance: ueaBalance,
-            }, _skipFeeLocking: isUEADeployed }, (!isUEADeployed ? { _minimumDepositUsd: ROUTE2_MINIMUM_DEPOSIT_USD } : {}));
+            }, _skipFeeLocking: skipFeeLockingR2Evm, _requiredFundsOverride: requiredNativeBalanceR2Evm }, (!skipFeeLockingR2Evm ? { _minimumDepositUsd: ROUTE2_MINIMUM_DEPOSIT_USD } : {}));
         // Signature request — user is prompted to sign the universal payload.
         // executeFn is monolithic (sign → broadcast), so we emit the logical
         // post-sign / pre-broadcast markers as a burst after it returns so
@@ -614,6 +630,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
         if (hasSvmExecute) {
             (0, context_1.printLog)(ctx, `executeUoaToCeaSvm — encoded execute payload: ${(svmPayload.length - 2) / 2} bytes`);
         }
+        (0, payload_builders_1.assertSvmPayloadWithinRelayLimit)(svmPayload, `Route 2 SVM ${targetChain}`);
         // --- Determine PRC-20 token and burn amount (chain-local, pre-203) ---
         const { prc20Token, burnAmount } = resolveR2Prc20TokenSvm(params, targetChain, ctx.pushNetwork, hasSvmExecute);
         if (params.value && params.value > BigInt(0)) {
@@ -756,6 +773,13 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
                 args: [ueaAddress],
             });
         }
+        const requiredNativeBalanceR2Svm = getRequiredNativeBalanceForOutbound(nativeValueForGas, SVM_GAS_RESERVE);
+        const skipFeeLockingR2Svm = shouldSkipFeeLockingForOutbound({
+            isUEADeployed,
+            balance: ueaBalance,
+            nativeValueForGas,
+            gasReserve: SVM_GAS_RESERVE,
+        });
         (0, preflight_1.runPreflight)({
             ctx,
             ueaAddress,
@@ -791,7 +815,8 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
                 nonce: ueaNonce,
                 balance: ueaBalance,
             },
-            _skipFeeLocking: isUEADeployed, // skip fee-locking only if UEA is already deployed
+            _skipFeeLocking: skipFeeLockingR2Svm,
+            _requiredFundsOverride: requiredNativeBalanceR2Svm,
         };
         // Signature request — user is prompted to sign the universal payload.
         // Emit spec-ordered burst after executeFn returns (sign → verify → broadcast).
@@ -1077,6 +1102,13 @@ function executeCeaToPush(ctx, params, executeFn) {
         // payload-only (UEA never holds the source-chain PRC-20; see plan §9 #4).
         // Native UPC check still applies for the gas swap. It warns by default and
         // throws only when options.enforceGasCheck=true.
+        const requiredNativeBalanceR3Evm = getRequiredNativeBalanceForOutbound(nativeValueForGas, OUTBOUND_GAS_RESERVE_R3);
+        const skipFeeLockingR3Evm = shouldSkipFeeLockingForOutbound({
+            isUEADeployed,
+            balance: effectiveBalance,
+            nativeValueForGas,
+            gasReserve: OUTBOUND_GAS_RESERVE_R3,
+        });
         (0, preflight_1.runPreflight)({
             ctx,
             ueaAddress,
@@ -1104,7 +1136,7 @@ function executeCeaToPush(ctx, params, executeFn) {
                 isDeployed: isUEADeployed,
                 nonce: ueaNonce,
                 balance: ueaBalance,
-            }, _skipFeeLocking: isUEADeployed }, (!isUEADeployed ? { _minimumDepositUsd: ROUTE3_MINIMUM_DEPOSIT_USD } : {}));
+            }, _skipFeeLocking: skipFeeLockingR3Evm, _requiredFundsOverride: requiredNativeBalanceR3Evm }, (!skipFeeLockingR3Evm ? { _minimumDepositUsd: ROUTE3_MINIMUM_DEPOSIT_USD } : {}));
         (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_01);
         let response;
         try {
@@ -1190,6 +1222,7 @@ function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
             extraPayload: buildR3SvmExtraPayload(ctx, params, ueaAddress, sourceChain, ueaNonce + BigInt(1)),
             revertRecipientHex: ceaPdaHex,
         });
+        (0, payload_builders_1.assertSvmPayloadWithinRelayLimit)(svmPayload, `Route 3 SVM ${sourceChain}`);
         (0, context_1.printLog)(ctx, `executeCeaToPushSvm — drainAmount: ${drainAmount.toString()}, payload length: ${(svmPayload.length - 2) / 2} bytes`);
         const burnAmount = BigInt(0);
         let effectiveGasLimit = (_a = params.gasLimit) !== null && _a !== void 0 ? _a : BigInt(0);
@@ -1285,6 +1318,13 @@ function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
         }
         // SVM warn-threshold telemetry (no truncation — pre-flight handles drain protection).
         (0, preflight_1.maybeFireSvmWarnThreshold)(ctx, nativeValueForGas, gasToken, 'R3_SVM');
+        const requiredNativeBalanceR3Svm = getRequiredNativeBalanceForOutbound(nativeValueForGas, OUTBOUND_GAS_RESERVE_R3_SVM);
+        const skipFeeLockingR3Svm = shouldSkipFeeLockingForOutbound({
+            isUEADeployed,
+            balance: currentBalance,
+            nativeValueForGas,
+            gasReserve: OUTBOUND_GAS_RESERVE_R3_SVM,
+        });
         // Pre-flight (R3 SVM): no PRC-20 burn check. The drain amount lives in the
         // embedded Solana instruction and is withdrawn from the external CEA.
         (0, preflight_1.runPreflight)({
@@ -1312,8 +1352,8 @@ function executeCeaToPushSvm(ctx, params, sourceChain, executeFn) {
         const executeParams = Object.assign({ to: ueaAddress, value: multicallNativeValue, data: pushChainMulticalls, _ueaStatus: {
                 isDeployed: isUEADeployed,
                 nonce: ueaNonce,
-                balance: ueaBalance,
-            }, _skipFeeLocking: isUEADeployed }, (!isUEADeployed ? { _minimumDepositUsd: utils_1.Utils.helpers.parseUnits('10', 8) } : {}));
+                balance: currentBalance,
+            }, _skipFeeLocking: skipFeeLockingR3Svm, _requiredFundsOverride: requiredNativeBalanceR3Svm }, (!skipFeeLockingR3Svm ? { _minimumDepositUsd: utils_1.Utils.helpers.parseUnits('10', 8) } : {}));
         (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_304_01);
         let response;
         try {
@@ -1391,6 +1431,7 @@ function buildPayloadForRoute(ctx, params, route, nonce) {
                         to: target,
                         senderUea: ueaAddress,
                     });
+                    (0, payload_builders_1.assertSvmPayloadWithinRelayLimit)(payload, `Route 2 SVM ${target.chain}`);
                     let prc20Token = selectors_1.ZERO_ADDRESS;
                     let burnAmount = BigInt(0);
                     if ((_a = params.funds) === null || _a === void 0 ? void 0 : _a.amount) {
@@ -1450,6 +1491,7 @@ function buildPayloadForRoute(ctx, params, route, nonce) {
                         extraPayload: buildR3SvmExtraPayload(ctx, params, ueaAddress, sourceChain, nonce + BigInt(1)),
                         revertRecipientHex: ceaPdaHex2,
                     });
+                    (0, payload_builders_1.assertSvmPayloadWithinRelayLimit)(svmPayload, `Route 3 SVM ${sourceChain}`);
                     // Payload-only outbound: drain amount lives inside ixData.
                     const burnAmount = BigInt(0);
                     const outboundReq = (0, payload_builders_1.buildOutboundRequest)(gatewayProgramHex, prc20Token, burnAmount, (_h = params.gasLimit) !== null && _h !== void 0 ? _h : BigInt(0), svmPayload, ueaAddress, (_j = params.maxPCForGas) !== null && _j !== void 0 ? _j : BigInt(0));

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

@@ -25,15 +25,25 @@ function buildDomainSeparator(vm, chainId, version, verifyingContract) {
     const domainTypeHash = (0, viem_1.keccak256)((0, viem_1.toBytes)(vm === enums_1.VM.EVM
         ? 'EIP712Domain(string version,uint256 chainId,address verifyingContract)'
         : 'EIP712Domain_SVM(string version,string chainId,address verifyingContract)'));
+    // NOTE (SVM chainId encoding): the UEA_SVM currently deployed on Donut
+    // abi-encodes `_universalAccountId.chainId` as a RAW string in its
+    // domainSeparator() (pre-EIP-712-fix). We must match that byte-for-byte or the
+    // ed25519 signature is over the wrong digest and `executeUniversalTx` reverts
+    // with `InvalidSVMSignature` (0xa764e90c). The newer UEA_SVM (core-contracts
+    // commits 5d97ff4 "hash SVM domain separator chainId per EIP-712" + 62d47cc
+    // "bind … via EIP-712 salt") keccak-hashes chainId AND adds a `bytes32 salt =
+    // bytes32(block.chainid)`. When Donut is upgraded to that version, change the
+    // SVM branch back to `keccak256(toBytes(chainId))` and append the salt field.
+    // Verified against on-chain getUniversalPayloadHash on UEA 0xad977a75 (Donut).
     return (0, viem_1.keccak256)((0, viem_1.encodeAbiParameters)([
         { name: 'typeHash', type: 'bytes32' },
         { name: 'version', type: 'bytes32' },
-        { name: 'chainId', type: vm === enums_1.VM.EVM ? 'uint256' : 'bytes32' },
+        { name: 'chainId', type: vm === enums_1.VM.EVM ? 'uint256' : 'string' },
         { name: 'verifyingContract', type: 'address' },
     ], [
         domainTypeHash,
         (0, viem_1.keccak256)((0, viem_1.toBytes)(version)),
-        vm === enums_1.VM.EVM ? BigInt(chainId) : (0, viem_1.keccak256)((0, viem_1.toBytes)(chainId)),
+        vm === enums_1.VM.EVM ? BigInt(chainId) : chainId,
         verifyingContract,
     ]));
 }
@@ -203,14 +213,28 @@ function encodeUniversalPayload(payload) {
     ]);
 }
 function encodeUniversalPayloadSvm(payload) {
-    const writeU64 = (val) => {
+    const U64_MAX = (BigInt(1) << BigInt(64)) - BigInt(1);
+    const I64_MIN = -(BigInt(1) << BigInt(63));
+    const I64_MAX = (BigInt(1) << BigInt(63)) - BigInt(1);
+    const viewFor = (buf) => new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    const assertRange = (field, val, min, max) => {
+        if (val < min || val > max) {
+            throw new RangeError(`SVM payload field ${field} out of range: ${val.toString()} ` +
+                `(expected ${min.toString()}..${max.toString()})`);
+        }
+    };
+    const writeU64 = (field, val) => {
+        const n = BigInt(val);
+        assertRange(field, n, BigInt(0), U64_MAX);
         const b = Buffer.alloc(8);
-        b.writeBigUInt64LE(BigInt(val), 0);
+        viewFor(b).setBigUint64(0, n, true);
         return b;
     };
-    const writeI64 = (val) => {
+    const writeI64 = (field, val) => {
+        const n = BigInt(val);
+        assertRange(field, n, I64_MIN, I64_MAX);
         const b = Buffer.alloc(8);
-        b.writeBigInt64LE(BigInt(val), 0);
+        viewFor(b).setBigInt64(0, n, true);
         return b;
     };
     const writeVecU8 = (val) => {
@@ -218,7 +242,7 @@ function encodeUniversalPayloadSvm(payload) {
             ? val
             : Buffer.from(val);
         const len = Buffer.alloc(4);
-        len.writeUInt32LE(bytes.length, 0);
+        viewFor(len).setUint32(0, bytes.length, true);
         return Buffer.concat([len, bytes]);
     };
     const writeU8 = (val) => Buffer.from([val]);
@@ -227,18 +251,18 @@ function encodeUniversalPayloadSvm(payload) {
         const hex = to.slice(2).padStart(40, '0');
         return Buffer.from(hex, 'hex');
     })();
-    const valueBytes = writeU64(payload.value);
+    const valueBytes = writeU64('value', payload.value);
     const dataBytes = (() => {
         const data = payload.data;
         const hex = data.slice(2);
         const buf = hex.length ? Buffer.from(hex, 'hex') : Buffer.alloc(0);
         return writeVecU8(buf);
     })();
-    const gasLimitBytes = writeU64(payload.gasLimit);
-    const maxFeePerGasBytes = writeU64(payload.maxFeePerGas);
-    const maxPriorityFeePerGasBytes = writeU64(payload.maxPriorityFeePerGas);
-    const nonceBytes = writeU64(payload.nonce);
-    const deadlineBytes = writeI64(payload.deadline);
+    const gasLimitBytes = writeU64('gasLimit', payload.gasLimit);
+    const maxFeePerGasBytes = writeU64('maxFeePerGas', payload.maxFeePerGas);
+    const maxPriorityFeePerGasBytes = writeU64('maxPriorityFeePerGas', payload.maxPriorityFeePerGas);
+    const nonceBytes = writeU64('nonce', payload.nonce);
+    const deadlineBytes = writeI64('deadline', payload.deadline);
     const vTypeVal = (() => {
         const v = payload.vType;
         if (typeof v === 'number')

package/src/lib/orchestrator/orchestrator.js

@@ -339,8 +339,11 @@ class Orchestrator {
      */
     createCascadedBuilder(preparedTxs, options) {
         const perCallHook = options === null || options === void 0 ? void 0 : options.progressHook;
+        const cascadeOptions = (options === null || options === void 0 ? void 0 : options.enforceGasCheck) === true
+            ? { enforceGasCheck: true }
+            : undefined;
         if (!perCallHook) {
-            return (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks(), undefined);
+            return (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks(), undefined, cascadeOptions);
         }
         // Wrap ctx.progressHook for the synchronous send() phase — captures every
         // fireProgressHook(ctx, ...) call during pre-flight, composeCascade, and
@@ -353,7 +356,7 @@ class Orchestrator {
         // `dispatchCascadeProgressEvent` path delivers events to BOTH that hook
         // and ctx.progressHook (the init-time hook, restored by then) with
         // reference-dedup.
-        const innerBuilder = (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks(), perCallHook);
+        const innerBuilder = (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks(), perCallHook, cascadeOptions);
         return {
             send: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 const originalHook = this.progressHook;

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

@@ -140,11 +140,19 @@ export type ExecuteParams = {
     };
     /**
      * Internal: Skip fee locking for outbound flows (UEA→CEA).
-     * Outbound txs execute entirely on Push Chain and don't need
-     * external-chain fee locking.
+     * Outbound txs can skip external-chain fee locking only when the executing
+     * Push account already has enough native PC for the outbound gas swap plus
+     * Push-side execution reserve.
      * @internal
      */
     _skipFeeLocking?: boolean;
+    /**
+     * Internal: Minimum native PC balance required before standard execution may
+     * skip fee locking. Route handlers use this to include their own outbound
+     * gas-swap reserve in executeStandardPayload's fee-locking decision.
+     * @internal
+     */
+    _requiredFundsOverride?: bigint;
     /**
      * Internal: Minimum fee-locking deposit in USD (8 decimals).
      * Overrides the default $1 floor when the caller needs a larger deposit
@@ -717,6 +725,12 @@ export interface CascadeTrackOptions {
     eventHook?: (event: import('../progress-hook/progress-hook.types').ProgressEvent) => void;
 }
 export interface CascadeExecutionOptions {
+    /**
+     * Enforce SDK pre-flight gas/balance checks across the whole cascade.
+     * - false/omitted: individual prepared-hop settings decide enforcement
+     * - true: shortfalls throw InsufficientUEABalanceError before broadcast
+     */
+    enforceGasCheck?: boolean;
     /** Per-call progress callback. */
     progressHook?: (event: import('../progress-hook/progress-hook.types').ProgressEvent) => void;
 }

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

@@ -127,14 +127,14 @@ export declare function buildMigrationPayload(): `0x${string}`;
  * Build approval multicalls + sendUniversalTxOutbound call for Push Chain.
  *
  * Extracted from executeUoaToCea to be reusable in cascade composition.
- * Handles two cases:
- * - gasToken === prc20Token: single approval for burnAmount + gasFee
- * - gasToken !== prc20Token: two separate approvals
+ * The PRC-20 approval covers only the burn amount. Destination gas is funded
+ * through native PC msg.value on sendUniversalTxOutbound; UniversalCore swaps
+ * that native value into the route gas token inside swapAndBurnGas.
  *
  * @param opts.prc20Token - PRC-20 token to burn
- * @param opts.gasToken - Gas token for fee payment
+ * @param opts.gasToken - Gas token for fee payment, used by the outbound request
  * @param opts.burnAmount - Amount to burn
- * @param opts.gasFee - Gas fee amount
+ * @param opts.gasFee - Gas fee amount, used only for fallback native value sizing
  * @param opts.gatewayPcAddress - UniversalGatewayPC precompile address
  * @param opts.outboundRequest - The outbound request struct
  * @returns Array of MultiCall operations (approvals + outbound call)
@@ -157,6 +157,14 @@ export declare function isSvmChain(chain: CHAIN): boolean;
  * Must be exactly 32 bytes (0x + 64 hex chars = 66 characters total).
  */
 export declare function isValidSolanaHexAddress(address: string): boolean;
+/**
+ * Conservative upper bound for SVM outbound instruction data. Solana's packet
+ * limit is 1232 bytes before the transaction envelope, accounts, blockhash,
+ * and signatures, so SDK-built instruction data must stay well below that.
+ */
+export declare const SVM_RELAYABLE_PAYLOAD_MAX_BYTES = 1000;
+export declare function getHexPayloadByteLength(payload: `0x${string}`): number;
+export declare function assertSvmPayloadWithinRelayLimit(payload: `0x${string}`, context: string, maxBytes?: number): void;
 /**
  * Encode SVM execute payload for CPI execution on Solana.
  *

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MULTICALL_TUPLE_TYPE = void 0;
+exports.SVM_RELAYABLE_PAYLOAD_MAX_BYTES = exports.MULTICALL_TUPLE_TYPE = void 0;
 exports.buildExecuteMulticall = buildExecuteMulticall;
 exports.buildCeaMulticallPayload = buildCeaMulticallPayload;
 exports.buildInboundUniversalPayload = buildInboundUniversalPayload;
@@ -14,6 +14,8 @@ exports.buildMigrationPayload = buildMigrationPayload;
 exports.buildOutboundApprovalAndCall = buildOutboundApprovalAndCall;
 exports.isSvmChain = isSvmChain;
 exports.isValidSolanaHexAddress = isValidSolanaHexAddress;
+exports.getHexPayloadByteLength = getHexPayloadByteLength;
+exports.assertSvmPayloadWithinRelayLimit = assertSvmPayloadWithinRelayLimit;
 exports.encodeSvmExecutePayload = encodeSvmExecutePayload;
 exports.encodeSvmCeaToUeaPayload = encodeSvmCeaToUeaPayload;
 const viem_1 = require("viem");
@@ -340,14 +342,14 @@ function buildMigrationPayload() {
  * Build approval multicalls + sendUniversalTxOutbound call for Push Chain.
  *
  * Extracted from executeUoaToCea to be reusable in cascade composition.
- * Handles two cases:
- * - gasToken === prc20Token: single approval for burnAmount + gasFee
- * - gasToken !== prc20Token: two separate approvals
+ * The PRC-20 approval covers only the burn amount. Destination gas is funded
+ * through native PC msg.value on sendUniversalTxOutbound; UniversalCore swaps
+ * that native value into the route gas token inside swapAndBurnGas.
  *
  * @param opts.prc20Token - PRC-20 token to burn
- * @param opts.gasToken - Gas token for fee payment
+ * @param opts.gasToken - Gas token for fee payment, used by the outbound request
  * @param opts.burnAmount - Amount to burn
- * @param opts.gasFee - Gas fee amount
+ * @param opts.gasFee - Gas fee amount, used only for fallback native value sizing
  * @param opts.gatewayPcAddress - UniversalGatewayPC precompile address
  * @param opts.outboundRequest - The outbound request struct
  * @returns Array of MultiCall operations (approvals + outbound call)
@@ -413,6 +415,24 @@ function isSvmChain(chain) {
 function isValidSolanaHexAddress(address) {
     return /^0x[a-fA-F0-9]{64}$/.test(address);
 }
+/**
+ * Conservative upper bound for SVM outbound instruction data. Solana's packet
+ * limit is 1232 bytes before the transaction envelope, accounts, blockhash,
+ * and signatures, so SDK-built instruction data must stay well below that.
+ */
+exports.SVM_RELAYABLE_PAYLOAD_MAX_BYTES = 1000;
+function getHexPayloadByteLength(payload) {
+    return Math.max(0, (payload.length - 2) / 2);
+}
+function assertSvmPayloadWithinRelayLimit(payload, context, maxBytes = exports.SVM_RELAYABLE_PAYLOAD_MAX_BYTES) {
+    const payloadBytes = getHexPayloadByteLength(payload);
+    if (payloadBytes <= maxBytes)
+        return;
+    throw new Error(`SVM outbound payload for ${context} is ${payloadBytes} bytes, ` +
+        `exceeding relay-safe limit ${maxBytes} bytes. Solana cannot carry ` +
+        `this much instruction data in one transaction; split the cascade into ` +
+        `separate transactions or reduce the nested payload.`);
+}
 /** Convert 0x-prefixed hex string to Uint8Array */
 function hexToBytes(hex) {
     const h = hex.startsWith('0x') ? hex.slice(2) : hex;

package/src/lib/orchestrator/svm-idl/build-payload.js

@@ -15,12 +15,36 @@ function buildSvmPayloadFromParams(params) {
             hasExecute: false,
         };
     }
-    const resolved = (0, resolve_1.resolveSvmCall)({
-        programAddress: params.to.address,
-        data: (0, viem_1.hexToBytes)(params.data),
-        senderUea: params.senderUea,
-        targetChain: params.to.chain,
-    });
+    // `data` is the EVM-oriented calldata field. On an SVM hop it is only a real
+    // instruction when it resolves against a registered Anchor IDL (8-byte
+    // discriminator + matching instruction). EVM calldata (e.g. a 4-byte selector
+    // like `increment()`) is NOT an SVM instruction for the target program — treat
+    // it as "no execute" (empty svmPayload), matching the documented behaviour that
+    // the `data` field is ignored for SVM chains, rather than throwing mid-prepare.
+    //
+    // We deliberately only swallow "the data isn't a valid instruction for this
+    // program's IDL" (too short / no discriminator match). A "no IDL found" error
+    // still throws — that means the caller targeted a program whose IDL was never
+    // registered, which is a real configuration mistake they need to see.
+    let resolved;
+    try {
+        resolved = (0, resolve_1.resolveSvmCall)({
+            programAddress: params.to.address,
+            data: (0, viem_1.hexToBytes)(params.data),
+            senderUea: params.senderUea,
+            targetChain: params.to.chain,
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && /no IDL found/i.test(err.message)) {
+            throw err;
+        }
+        return {
+            svmPayload: '0x',
+            targetBytes: params.to.address,
+            hasExecute: false,
+        };
+    }
     const svmPayload = (0, payload_builders_1.encodeSvmExecutePayload)({
         targetProgram: resolved.targetProgram,
         accounts: resolved.accounts,

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

@@ -95,6 +95,10 @@ export declare class PushChain {
          * Accepts an array of PreparedUniversalTx (from prepareTransaction).
          *
          * @param txs - Prepared transactions to execute as a cascade.
+         * @param options.enforceGasCheck - Defaults to false. When true, the
+         *   cascade stops on pre-flight gas/balance shortfall instead of warning
+         *   and proceeding. This applies to every prepared transaction in the
+         *   cascade without having to set the flag on each prepared hop.
          * @param options.progressHook - Optional per-call progress callback.
          *   Additive with the init-time `progressHook` passed to `initialize`:
          *   both hooks receive every `ProgressEvent` emitted during this call

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

@@ -43,7 +43,25 @@ class PushClient extends evm_client_1.EvmClient {
         return tslib_1.__awaiter(this, arguments, void 0, function* (operation, operationName = 'operation') {
             const rpcUrls = this.pushChainInfo.tendermintRpc;
             let lastError = null;
-            for (let attempt = 0; attempt < rpcUrls.length; attempt++) {
+            // Cycle the RPC URLs, but also RETRY transient failures (5xx / network /
+            // "HTTP request failed") with backoff — otherwise a single 502 on a
+            // single-endpoint chain (e.g. Donut) aborts a tx mid status-poll. Total
+            // attempts = urls × (RETRIES_PER_URL + 1).
+            const RETRIES_PER_URL = 4;
+            const totalAttempts = rpcUrls.length * (RETRIES_PER_URL + 1);
+            const isTransient = (e) => {
+                var _a;
+                const m = `${(_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : ''}`.toLowerCase();
+                return (/\b(502|503|504|429)\b/.test(m) ||
+                    m.includes('http request failed') ||
+                    m.includes('server error') ||
+                    m.includes('timeout') ||
+                    m.includes('timed out') ||
+                    m.includes('econnreset') ||
+                    m.includes('socket hang up') ||
+                    m.includes('fetch failed'));
+            };
+            for (let attempt = 0; attempt < totalAttempts; attempt++) {
                 const rpcIndex = (this.currentRpcIndex + attempt) % rpcUrls.length;
                 const rpcUrl = rpcUrls[rpcIndex];
                 try {
@@ -55,10 +73,16 @@ class PushClient extends evm_client_1.EvmClient {
                 }
                 catch (error) {
                     lastError = error;
-                    if (attempt === rpcUrls.length - 1) {
+                    if (attempt === totalAttempts - 1) {
                         break;
                     }
-                    yield new Promise((resolve) => setTimeout(resolve, 100));
+                    // Non-transient errors: move to the next URL quickly. Transient ones:
+                    // back off (200ms → 400 → 800 …, capped) so a flaky RPC can recover.
+                    const cycle = Math.floor(attempt / rpcUrls.length);
+                    const delay = isTransient(lastError)
+                        ? Math.min(2000, 200 * Math.pow(2, cycle))
+                        : 100;
+                    yield new Promise((resolve) => setTimeout(resolve, delay));
                 }
             }
             throw new Error(`All RPC endpoints failed for ${operationName}. Last error: ${lastError === null || lastError === void 0 ? void 0 : lastError.message}`);

package/src/lib/vm-client/evm-client.js

@@ -14,7 +14,10 @@ const viem_1 = require("viem");
  */
 class EvmClient {
     constructor({ rpcUrls, chain }) {
-        const transports = rpcUrls.map((rpcUrl) => (0, viem_1.http)(rpcUrl));
+        // retryCount/retryDelay make reads (incl. contract reads + Push status
+        // queries via PushClient) resilient to transient RPC 5xx (e.g. 502s under
+        // load), which otherwise abort a tx mid-flight. viem retries with backoff.
+        const transports = rpcUrls.map((rpcUrl) => (0, viem_1.http)(rpcUrl, { retryCount: 5, retryDelay: 500 }));
         this.publicClient = (0, viem_1.createPublicClient)({
             chain,
             transport: (0, viem_1.fallback)(transports),