@pushchain/core 6.0.17 → 6.0.19

package/src/lib/orchestrator/internals/execute-funds-only.js

@@ -182,13 +182,15 @@ function executeFundsOnlyEvm(ctx, execute, eventBuffer, transformFn, chain, rpcU
             txHash = yield (0, gateway_client_1.sendGatewayTxWithFallback)(ctx, evmClient, gatewayAddress, req, ctx.universalSigner, isNative ? nativeAmount + bridgeAmount : nativeAmount);
         }
         catch (err) {
-            (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04);
-            throw err;
+            const errMsg = (0, formatters_1.normalizePublicErrorMessage)(err);
+            (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04, errMsg);
+            ctx._routeTerminalEmitted = true;
+            throw new Error(errMsg);
         }
         const originTx = yield (0, helpers_2.fetchOriginChainTransactionForProgress)(ctx, chain, txHash, txHash);
         (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_02, txHash, bridgeAmount, execute.funds.token.decimals, symbol, originTx);
         yield (0, confirmation_1.waitForEvmConfirmationsWithCountdown)(ctx, evmClient, txHash, chain_1.CHAIN_INFO[chain].confirmations, chain_1.CHAIN_INFO[chain].timeout);
-        (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_04);
+        (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_04, txHash);
         (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_05);
         (0, context_2.printLog)(ctx, 'sendFunds — querying Push Chain status: ' + JSON.stringify({
             txHash, evmGatewayMethod: execute.to === ueaAddress ? 'sendFunds' : 'sendTxWithFunds',
@@ -202,7 +204,7 @@ function executeFundsOnlyEvm(ctx, execute, eventBuffer, transformFn, chain, rpcU
         }
         catch (err) {
             if (!(err instanceof push_chain_tx_1.PushChainExecutionError)) {
-                const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
+                const errMsg = (0, formatters_1.normalizePublicErrorMessage)(err);
                 (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
                 throw new push_chain_tx_1.PushChainExecutionError(errMsg, { gatewayTxHash: txHash });
             }
@@ -284,7 +286,7 @@ function executeFundsOnlySvm(ctx, execute, eventBuffer, transformFn, chain, rpcU
         const originTx = yield (0, helpers_2.fetchOriginChainTransactionForProgress)(ctx, chain, '0x', txSignature);
         (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_02, txSignature, bridgeAmount, execute.funds.token.decimals, symbol, originTx);
         yield (0, confirmation_1.waitForSvmConfirmationsWithCountdown)(ctx, svmClient, txSignature, chain_1.CHAIN_INFO[chain].confirmations, chain_1.CHAIN_INFO[chain].timeout);
-        (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_04);
+        (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_04, txSignature);
         (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_05);
         let response;
         try {
@@ -293,7 +295,7 @@ function executeFundsOnlySvm(ctx, execute, eventBuffer, transformFn, chain, rpcU
         }
         catch (err) {
             if (!(err instanceof push_chain_tx_1.PushChainExecutionError)) {
-                const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
+                const errMsg = (0, formatters_1.normalizePublicErrorMessage)(err);
                 (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
                 throw new push_chain_tx_1.PushChainExecutionError(errMsg, { gatewayTxHash: txSignature });
             }

package/src/lib/orchestrator/internals/execute-funds-payload.js

@@ -158,7 +158,7 @@ function executeFundsWithPayload(ctx, execute, eventBuffer, getResponseCallbacks
             }
         }
         // Final USD(8) -> native conversion reusing the cached price fetched above.
-        let nativeAmount = usdToNative(depositUsd);
+        const nativeAmount = usdToNative(depositUsd);
         (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_103_03_04, nativeAmount, depositUsd, chain);
         const bridgeAmount = execute.funds.amount;
         const symbol = execute.funds.token.symbol;
@@ -222,8 +222,10 @@ function executeFundsWithPayload(ctx, execute, eventBuffer, getResponseCallbacks
             }
         }
         catch (err) {
-            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04);
-            throw err;
+            const errMsg = (0, formatters_1.normalizePublicErrorMessage)(err);
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04, errMsg);
+            ctx._routeTerminalEmitted = true;
+            throw new Error(errMsg);
         }
         (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_03);
         (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_02, txHash, bridgeAmount, execute.funds.token.decimals, symbol);
@@ -246,7 +248,7 @@ function executeFundsWithPayload(ctx, execute, eventBuffer, getResponseCallbacks
                 feeLockTxHash = (0, viem_1.bytesToHex)(new Uint8Array(decoded));
             }
         }
-        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_04);
+        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_04, txHash);
         (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_05);
         let response;
         try {
@@ -261,7 +263,7 @@ function executeFundsWithPayload(ctx, execute, eventBuffer, getResponseCallbacks
         }
         catch (err) {
             if (!(err instanceof push_chain_tx_1.PushChainExecutionError)) {
-                const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
+                const errMsg = (0, formatters_1.normalizePublicErrorMessage)(err);
                 (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
                 throw new push_chain_tx_1.PushChainExecutionError(errMsg, { gatewayTxHash: txHash });
             }

package/src/lib/orchestrator/internals/execute-standard.js

@@ -111,7 +111,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             catch (err) {
                 // Push Chain broadcast failed. Wallet rejection surfaces as 104-04;
                 // everything else (RPC fail, on-chain revert) as 199-02.
-                const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
+                const errMsg = (0, formatters_1.normalizePublicErrorMessage)(err);
                 const { isUserDecline } = (0, progress_hook_1.classifyDeclineError)(errMsg);
                 (0, context_1.fireProgressHook)(ctx, isUserDecline ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04 : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
                 // Mark that a terminal-ish error hook has already fired so the
@@ -274,9 +274,10 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
                 // Wallet decline, contract revert during sign, or RPC failure — the
                 // 104-04 builder's classifyDeclineError heuristic picks the right
                 // copy (real decline → "Verification Declined"; else "Signature Failed").
-                const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
+                const errMsg = (0, formatters_1.normalizePublicErrorMessage)(err);
                 (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04, errMsg);
-                throw err;
+                ctx._routeTerminalEmitted = true;
+                throw new Error(errMsg);
             }
             verificationData = (0, viem_1.bytesToHex)(signature);
             (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_03);
@@ -393,9 +394,10 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             catch (err) {
                 // User declined the fee-lock tx submission or the origin-chain RPC
                 // rejected it — classifier picks decline vs generic signature failure.
-                const errMsg = err instanceof Error ? err.message : String(err);
+                const errMsg = (0, formatters_1.normalizePublicErrorMessage)(err);
                 (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_104_04, errMsg);
-                throw err;
+                ctx._routeTerminalEmitted = true;
+                throw new Error(errMsg);
             }
             feeLockTxHash = (0, viem_1.bytesToHex)(feeLockTxHashBytes);
             verificationData = (0, viem_1.bytesToHex)(feeLockTxHashBytes);
@@ -406,7 +408,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             const originTx = yield (0, helpers_1.fetchOriginChainTransactionForProgress)(ctx, chain, feeLockTxHash, feeLockTxHashDisplay);
             (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_105_01, feeLockTxHashDisplay, originTx);
             yield (0, confirmation_1.waitForLockerFeeConfirmation)(ctx, feeLockTxHashBytes);
-            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_105_02);
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_105_02, feeLockTxHashDisplay);
             const { defaultRPC, lockerContract } = chain_1.CHAIN_INFO[chain];
             (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_107);
             let response;
@@ -420,7 +422,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             }
             catch (err) {
                 if (!(err instanceof push_chain_tx_1.PushChainExecutionError)) {
-                    const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
+                    const errMsg = (0, formatters_1.normalizePublicErrorMessage)(err);
                     (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
                     throw new push_chain_tx_1.PushChainExecutionError(errMsg, { gatewayTxHash: feeLockTxHash });
                 }
@@ -454,7 +456,7 @@ function executeStandardPayload(ctx, execute, eventBuffer, getResponseCallbacks)
             // exhaustion). Surface terminal 199-02 before re-throwing so the stream
             // ends with the spec'd error hook. Typed PushChainExecutionError lets
             // callers classify via instanceof without message sniffing.
-            const errMsg = (0, formatters_1.normalizePcInsufficientFundsError)(err instanceof Error ? err.message : String(err));
+            const errMsg = (0, formatters_1.normalizePublicErrorMessage)(err);
             (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, errMsg);
             if (err instanceof push_chain_tx_1.PushChainExecutionError)
                 throw err;

package/src/lib/orchestrator/internals/gateway-client.js

@@ -30,6 +30,27 @@ const svm_helpers_2 = require("./svm-helpers");
 // ABI
 // ============================================================================
 const GATEWAY_ABI = abi_1.UNIVERSAL_GATEWAY_V1_SEND;
+const SOURCE_NATIVE_SYMBOL = {
+    [enums_1.CHAIN.ETHEREUM_MAINNET]: 'ETH',
+    [enums_1.CHAIN.ETHEREUM_SEPOLIA]: 'ETH',
+    [enums_1.CHAIN.ARBITRUM_SEPOLIA]: 'ETH',
+    [enums_1.CHAIN.BASE_SEPOLIA]: 'ETH',
+    [enums_1.CHAIN.BNB_TESTNET]: 'BNB',
+    [enums_1.CHAIN.SOLANA_MAINNET]: 'SOL',
+    [enums_1.CHAIN.SOLANA_TESTNET]: 'SOL',
+    [enums_1.CHAIN.SOLANA_DEVNET]: 'SOL',
+};
+function formatSourceNative(chain, amount) {
+    var _a;
+    const decimals = chain_1.CHAIN_INFO[chain].vm === enums_1.VM.SVM ? 9 : 18;
+    const symbol = (_a = SOURCE_NATIVE_SYMBOL[chain]) !== null && _a !== void 0 ? _a : 'native token';
+    return `${utils_1.Utils.helpers.formatUnits(amount, decimals)} ${symbol}`;
+}
+function insufficientSourceBalanceMessage(chain, available, required) {
+    return (`Insufficient source balance for transaction gas/value: ` +
+        `have ${formatSourceNative(chain, available)}, ` +
+        `need at least ${formatSourceNative(chain, required)}.`);
+}
 // ============================================================================
 // Request Conversion (V0 struct → V1 flat format)
 // ============================================================================
@@ -104,6 +125,13 @@ req) {
                     (nativeTokenUsdPrice - BigInt(1))) /
                     nativeTokenUsdPrice;
                 nativeAmount = nativeAmount + BigInt(1);
+                const sourceAddress = ctx.universalSigner.account.address;
+                const sourceBalance = yield evmClient.publicClient.getBalance({
+                    address: sourceAddress,
+                });
+                if (sourceBalance < nativeAmount) {
+                    throw new Error(insufficientSourceBalanceMessage(chain, sourceBalance, nativeAmount));
+                }
                 const txHash = yield sendGatewayTxWithFallback(ctx, evmClient, lockerContract, req, ctx.universalSigner, nativeAmount);
                 return (0, viem_1.hexToBytes)(txHash);
             }
@@ -130,12 +158,17 @@ req) {
                 const userPk = new web3_js_1.PublicKey(ctx.universalSigner.account.address);
                 const { feeVaultPda, protocolFeeLamports } = yield (0, svm_helpers_2.getSvmProtocolFee)(svmClient, programId);
                 const gasReq = (0, svm_helpers_1.buildSvmUniversalTxRequestFromReq)(req, userPk);
+                const requiredLamports = nativeAmount + protocolFeeLamports;
+                const sourceBalance = yield svmClient.getBalance(userPk.toBase58());
+                if (sourceBalance < requiredLamports) {
+                    throw new Error(insufficientSourceBalanceMessage(chain, sourceBalance, requiredLamports));
+                }
                 try {
                     const txHash = yield svmClient.writeContract({
                         abi: abi_1.SVM_GATEWAY_IDL,
                         address: programId.toBase58(),
                         functionName: 'sendUniversalTx',
-                        args: [gasReq, nativeAmount + protocolFeeLamports],
+                        args: [gasReq, requiredLamports],
                         signer: ctx.universalSigner,
                         accounts: {
                             config: configPda,

package/src/lib/orchestrator/internals/inbound-tracker.js

@@ -254,9 +254,10 @@ function waitForInboundPushTx(ctx_1, outboundExternalTxHash_1, sourceChain_1) {
                         // chain, treat as terminal-success; if it reverted, treat as
                         // terminal-failure. Cosmos-indexer lag stops blocking us here.
                         try {
-                            const receipt = yield ctx.pushClient.publicClient.getTransactionReceipt({
-                                hash: pushTxHash,
-                            });
+                            // Archive-fallback variant: a Push-leg receipt outside the prune
+                            // window still resolves via the archive node. On chains without an
+                            // archive endpoint this behaves as a plain prune-only lookup.
+                            const receipt = yield ctx.pushClient.getTransactionReceiptWithArchiveFallback(pushTxHash);
                             if ((receipt === null || receipt === void 0 ? void 0 : receipt.status) === 'success') {
                                 (0, context_1.printLog)(ctx, `[waitForInboundPushTx] Push RPC tiebreaker: ${pushTxHash} confirmed on chain (cosmos still status=${status}); treating as terminal-success`);
                                 progressHook === null || progressHook === void 0 ? void 0 : progressHook({

package/src/lib/orchestrator/internals/progress-route-hooks.d.ts

@@ -9,12 +9,16 @@
 import type { OutboundTxDetails } from '../orchestrator.types';
 import type { ProgressEvent } from '../../progress-hook/progress-hook.types';
 import { TransactionRoute } from '../route-detector';
+export type WaitHookMetadata = {
+    pushTxHash?: string;
+    txHash?: string;
+};
 export type WaitHookSet = {
-    awaiting: (chain: string) => ProgressEvent;
-    polling: (chain: string, elapsedMs: number) => ProgressEvent;
+    awaiting: (chain: string, pushTxHash?: string) => ProgressEvent;
+    polling: (chain: string, elapsedMs: number, pushTxHash?: string) => ProgressEvent;
     success: (details: OutboundTxDetails) => ProgressEvent;
-    timeout: (chain: string, elapsedMs: number) => ProgressEvent;
-    failed: (chain: string, errMsg: string) => ProgressEvent;
+    timeout: (chain: string, elapsedMs: number, pushTxHash?: string) => ProgressEvent;
+    failed: (chain: string, errMsg: string, metadata?: WaitHookMetadata) => ProgressEvent;
 };
 export declare function pickWaitHooks(route: TransactionRoute | string | undefined): WaitHookSet;
 /** True when the hook set is the no-op placeholder (route has no spec'd

package/src/lib/orchestrator/internals/progress-route-hooks.js

@@ -17,17 +17,17 @@ const route_detector_1 = require("../route-detector");
 function pickWaitHooks(route) {
     if (route === route_detector_1.TransactionRoute.UOA_TO_CEA) {
         return {
-            awaiting: (chain) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_209_01](chain),
-            polling: (chain, elapsed) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_209_02](chain, elapsed),
+            awaiting: (chain, pushTxHash) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_209_01](chain, pushTxHash),
+            polling: (chain, elapsed, pushTxHash) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_209_02](chain, elapsed, pushTxHash),
             success: (details) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_01](details),
-            timeout: (chain, elapsed) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_03](chain, elapsed),
-            failed: (chain, msg) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02](chain, msg),
+            timeout: (chain, elapsed, pushTxHash) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_03](chain, elapsed, pushTxHash),
+            failed: (chain, msg, metadata) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02](chain, msg, undefined, metadata === null || metadata === void 0 ? void 0 : metadata.pushTxHash, metadata === null || metadata === void 0 ? void 0 : metadata.txHash),
         };
     }
     if (route === route_detector_1.TransactionRoute.CEA_TO_PUSH) {
         return {
-            awaiting: (chain) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_01](chain),
-            polling: (chain, elapsed) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_02](chain, elapsed),
+            awaiting: (chain, pushTxHash) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_01](chain, pushTxHash),
+            polling: (chain, elapsed, pushTxHash) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_309_02](chain, elapsed, pushTxHash),
             // For R3, the outbound-poll "success" is the source-chain CEA executing
             // (309-03 INFO). Terminal 399-01 fires after the inbound-to-Push poll
             // (handled by waitForInboundPushTx in response-builder).
@@ -35,8 +35,8 @@ function pickWaitHooks(route) {
             // R3 outbound (source-chain CEA) failures share the 399-02/03 IDs with
             // R3 inbound; pass phase='outbound' so the title reflects the source
             // chain instead of "Push Chain Inbound …".
-            timeout: (chain, elapsed) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03](chain, elapsed, 'outbound'),
-            failed: (chain, msg) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](msg, 'outbound', chain),
+            timeout: (chain, elapsed, pushTxHash) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03](chain, elapsed, 'outbound', pushTxHash),
+            failed: (chain, msg, metadata) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](msg, 'outbound', chain, undefined, metadata === null || metadata === void 0 ? void 0 : metadata.pushTxHash, metadata === null || metadata === void 0 ? void 0 : metadata.txHash),
         };
     }
     // Route 4 (CEA_TO_CEA) has no spec'd ID range yet; cascade hops and

package/src/lib/orchestrator/internals/push-chain-tx.js

@@ -16,6 +16,7 @@ const viem_1 = require("viem");
 const chain_1 = require("../../constants/chain");
 const enums_1 = require("../../constants/enums");
 const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
+const evm_client_1 = require("../../vm-client/evm-client");
 const context_1 = require("./context");
 const error_decoder_1 = require("./error-decoder");
 const errors_1 = require("./errors");
@@ -69,6 +70,51 @@ function sendPushTx(ctx, execute, eventBuffer, transformFn) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c;
         if (Array.isArray(execute.data)) {
+            const calls = execute.data;
+            // Reject a zero `to` BEFORE route selection so behaviour is identical
+            // regardless of signer capability: ERC-7821 (the 7702 path) reinterprets
+            // `target == 0` as the account itself, whereas the legacy loop would send to
+            // the zero address. A zero target is almost always a bug — disallow it.
+            if (calls.some((c) => /^0x0{40}$/i.test(c.to))) {
+                throw new errors_1.PushChainExecutionError('A multicall entry has a zero `to` address. Use an explicit target ' +
+                    '(the EIP-7702 executor reinterprets a zero target as the account itself).');
+            }
+            // Preferred path: execute the batch atomically in a single EIP-7702 type-4
+            // transaction. Requires (a) a deployed PushBatchExecutor on this chain and
+            // (b) a wallet that can sign a 7702 authorization. When either is missing we
+            // fall back to the legacy non-atomic per-call loop below.
+            const executor = (0, chain_1.getBatchExecutorAddress)(ctx.universalSigner.account.chain);
+            if (executor && ctx.universalSigner.signAuthorization) {
+                try {
+                    (0, context_1.printLog)(ctx, `sendPushTx — executing ${calls.length} call(s) atomically via EIP-7702 (executor: ${executor})`);
+                    const txHash = yield ctx.pushClient.sendBatch7702({
+                        executor,
+                        calls,
+                        signer: ctx.universalSigner,
+                    });
+                    const txResponse = yield getIndexedPushTransaction(ctx, txHash, 'sendPushTx');
+                    return yield transformFn(txResponse, eventBuffer);
+                }
+                catch (err) {
+                    // Only fall back when the wallet genuinely can't sign a 7702
+                    // authorization. This is raised before any broadcast, so falling back
+                    // to sequential execution cannot double-execute. Any other error
+                    // (e.g. a real revert) must surface.
+                    if (!(err instanceof evm_client_1.EIP7702NotSupportedError))
+                        throw err;
+                    (0, context_1.printLog)(ctx, `sendPushTx — wallet cannot sign EIP-7702 authorization; falling back to sequential execution`);
+                    // eslint-disable-next-line no-console
+                    console.warn('[push-chain] Wallet cannot produce an EIP-7702 authorization — batch ' +
+                        'will execute as separate, non-atomic transactions (if one call reverts, ' +
+                        'earlier calls remain committed).');
+                }
+            }
+            else if (!ctx.universalSigner.signAuthorization) {
+                // eslint-disable-next-line no-console
+                console.warn('[push-chain] Signer does not support EIP-7702 — batch will execute as ' +
+                    'separate, non-atomic transactions (if one call reverts, earlier calls ' +
+                    'remain committed).');
+            }
             const PUSH_CHAIN_GAS_LIMIT = BigInt(500000);
             const MAX_NONCE_RETRIES = 3;
             let nonce = yield ctx.pushClient.publicClient.getTransactionCount({
@@ -76,7 +122,6 @@ function sendPushTx(ctx, execute, eventBuffer, transformFn) {
                 blockTag: 'pending',
             });
             let lastTxHash = '0x';
-            const calls = execute.data;
             for (let i = 0; i < calls.length; i++) {
                 const call = calls[i];
                 let txSent = false;
@@ -142,7 +187,11 @@ function sendPushTx(ctx, execute, eventBuffer, transformFn) {
                 nonce++;
             }
             const txResponse = yield getIndexedPushTransaction(ctx, lastTxHash, 'sendPushTx');
-            return yield transformFn(txResponse, eventBuffer);
+            // Sequential fallback: each call was a separate tx, so the batch is NOT
+            // atomic (an earlier call can be committed while a later one reverts).
+            const resp = yield transformFn(txResponse, eventBuffer);
+            resp.atomic = false;
+            return resp;
         }
         const txHash = yield ctx.pushClient.sendTransaction({
             to: execute.to,
@@ -263,11 +312,12 @@ function sendUniversalTx(ctx, isUEADeployed, feeLockTxHash, universalPayload, ve
             // wiring in `extractPcTxAndTransform` for the post-success `pcTx FAILED`
             // path. Also feeds the structured `decodedError` payload through to the
             // terminal hook (199-02 / 299-02 / 399-02 / 999-02).
-            let augmentedMessage = (_c = tx.rawLog) !== null && _c !== void 0 ? _c : '';
+            const rawMessage = (_c = tx.rawLog) !== null && _c !== void 0 ? _c : '';
+            let publicMessage = (0, formatters_1.normalizePublicErrorMessage)(rawMessage);
             let decodedForPayload;
-            const decoded = (0, error_decoder_1.decodeRevert)(augmentedMessage);
+            const decoded = (0, error_decoder_1.decodeRevert)(rawMessage);
             if ((decoded === null || decoded === void 0 ? void 0 : decoded.kind) === 'custom') {
-                augmentedMessage = `${augmentedMessage} [${decoded.name}: ${decoded.hint}]`;
+                publicMessage = (0, error_decoder_1.formatDecodedRevertForUser)(decoded);
                 decodedForPayload = {
                     name: decoded.name,
                     hint: decoded.hint,
@@ -275,7 +325,7 @@ function sendUniversalTx(ctx, isUEADeployed, feeLockTxHash, universalPayload, ve
                 };
             }
             else if ((decoded === null || decoded === void 0 ? void 0 : decoded.kind) === 'string') {
-                augmentedMessage = `${augmentedMessage} [Error(string): "${decoded.decoded}"]`;
+                publicMessage = (0, error_decoder_1.formatDecodedRevertForUser)(decoded);
                 decodedForPayload = {
                     decoded: decoded.decoded,
                     selector: decoded.selector,
@@ -290,12 +340,12 @@ function sendUniversalTx(ctx, isUEADeployed, feeLockTxHash, universalPayload, ve
                 `Block Height: ${tx.height}, TX Code: ${tx.code} (error)`,
                 `Gas Used: ${tx.gasUsed}, Gas Wanted: ${tx.gasWanted}`,
                 ...(failedEthTxHashes.length > 0 ? [`Ethereum TX Hash(es): ${failedEthTxHashes.join(', ')}`] : []),
-                `Error: ${augmentedMessage}`,
+                `Error: ${publicMessage}`,
             ].join(' | ');
             (0, context_1.printLog)(ctx, failureSummary);
             // Throw a typed error so the orchestrator's outer catch can lift the
             // structured `decodedError` straight onto the terminal-hook payload.
-            throw new errors_1.PushChainExecutionError(augmentedMessage, {
+            throw new errors_1.PushChainExecutionError(publicMessage, {
                 decodedError: decodedForPayload,
             });
         }
@@ -335,8 +385,9 @@ function extractPcTxAndTransform(ctx, pushChainUniversalTx, gatewayTxHash, event
             const failedPcTx = (lastPcTransaction === null || lastPcTransaction === void 0 ? void 0 : lastPcTransaction.status) === 'FAILED'
                 ? lastPcTransaction
                 : pushChainUniversalTx.pcTx.find((pcTx) => pcTx.status === 'FAILED' && pcTx.errorMsg);
-            const failedPcTxErrorMsg = (failedPcTx === null || failedPcTx === void 0 ? void 0 : failedPcTx.errorMsg)
-                ? (0, formatters_1.normalizePcInsufficientFundsError)(failedPcTx.errorMsg)
+            const rawFailedPcTxErrorMsg = (_b = failedPcTx === null || failedPcTx === void 0 ? void 0 : failedPcTx.errorMsg) !== null && _b !== void 0 ? _b : '';
+            let failedPcTxErrorMsg = rawFailedPcTxErrorMsg
+                ? (0, formatters_1.normalizePublicErrorMessage)(rawFailedPcTxErrorMsg)
                 : '';
             const errorDetails = failedPcTxErrorMsg ? `: ${failedPcTxErrorMsg}` : '';
             // Decode known revert selectors and ABI-encoded `Error(string)` reverts
@@ -344,9 +395,10 @@ function extractPcTxAndTransform(ctx, pushChainUniversalTx, gatewayTxHash, event
             // table can grow from real reverts.
             let hint = '';
             let decodedForPayload;
-            const decoded = (0, error_decoder_1.decodeRevert)((_b = failedPcTx === null || failedPcTx === void 0 ? void 0 : failedPcTx.errorMsg) !== null && _b !== void 0 ? _b : '');
+            const decoded = (0, error_decoder_1.decodeRevert)(rawFailedPcTxErrorMsg);
             if ((decoded === null || decoded === void 0 ? void 0 : decoded.kind) === 'custom') {
-                hint = ` [${decoded.name}: ${decoded.hint}]`;
+                failedPcTxErrorMsg = (0, error_decoder_1.formatDecodedRevertForUser)(decoded);
+                hint = '';
                 decodedForPayload = {
                     name: decoded.name,
                     hint: decoded.hint,
@@ -354,7 +406,8 @@ function extractPcTxAndTransform(ctx, pushChainUniversalTx, gatewayTxHash, event
                 };
             }
             else if ((decoded === null || decoded === void 0 ? void 0 : decoded.kind) === 'string') {
-                hint = ` [Error(string): "${decoded.decoded}"]`;
+                failedPcTxErrorMsg = (0, error_decoder_1.formatDecodedRevertForUser)(decoded);
+                hint = '';
                 decodedForPayload = {
                     decoded: decoded.decoded,
                     selector: decoded.selector,
@@ -363,11 +416,14 @@ function extractPcTxAndTransform(ctx, pushChainUniversalTx, gatewayTxHash, event
             else if ((decoded === null || decoded === void 0 ? void 0 : decoded.kind) === 'unknown') {
                 (0, context_1.printLog)(ctx, `[error-decoder] unknown selector ${decoded.selector} — consider adding to KNOWN_ERROR_SELECTORS`);
             }
-            const fullMessage = `Push Chain transaction failed for gateway tx: ${gatewayTxHash}${errorDetails}${hint}`;
+            const decodedErrorDetails = failedPcTxErrorMsg
+                ? `: ${failedPcTxErrorMsg}`
+                : errorDetails;
+            const fullMessage = `Push Chain transaction failed for gateway tx: ${gatewayTxHash}${decodedErrorDetails}${hint}`;
             // Live-emit 199-02 before throwing so the terminal failure hook reaches
             // any caller-registered progress stream (parity with reconstructProgressEvents
             // which emits 199-02 on replay).
-            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, fullMessage, decodedForPayload);
+            (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02, fullMessage, decodedForPayload, failedPcTx === null || failedPcTx === void 0 ? void 0 : failedPcTx.txHash);
             throw new errors_1.PushChainExecutionError(fullMessage, {
                 gatewayTxHash,
                 decodedError: decodedForPayload,

package/src/lib/orchestrator/internals/response-builder.js

@@ -687,12 +687,12 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                         fanOut(event, registeredProgressHook, ctx.progressHook);
                     };
                     // Awaiting relay
-                    emit(hooks.awaiting(targetChain));
+                    emit(hooks.awaiting(targetChain, universalTxResponse.hash));
                     let lastEmittedStatus;
                     const outboundTranslator = (event) => {
                         if (event.status === 'polling' && lastEmittedStatus !== 'polling') {
                             lastEmittedStatus = 'polling';
-                            emit(hooks.polling(targetChain, event.elapsed));
+                            emit(hooks.polling(targetChain, event.elapsed, universalTxResponse.hash));
                         }
                     };
                     try {
@@ -721,7 +721,7 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                         // otherwise time out after 300s.
                         if (route === route_detector_1.TransactionRoute.CEA_TO_PUSH &&
                             universalTxResponse._expectsInboundRoundTrip === true) {
-                            emit(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_310_01](targetChain));
+                            emit(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_310_01](targetChain, universalTxResponse.hash));
                             let inboundLastEmitted;
                             try {
                                 const inbound = yield (0, inbound_tracker_1.waitForInboundPushTx)(ctx, outboundDetails.externalTxHash, targetChain, {
@@ -732,7 +732,7 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                                         if (event.status === 'polling' &&
                                             inboundLastEmitted !== 'polling') {
                                             inboundLastEmitted = 'polling';
-                                            emit(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_310_02](targetChain, event.elapsedMs));
+                                            emit(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_310_02](targetChain, event.elapsedMs, universalTxResponse.hash));
                                         }
                                     },
                                 });
@@ -743,7 +743,7 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                                 else {
                                     // status === 'failed' (terminal failure status from chain)
                                     const failMsg = (_g = inbound.errorMessage) !== null && _g !== void 0 ? _g : 'inbound execution failed on Push Chain';
-                                    emit(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](failMsg, 'inbound', targetChain));
+                                    emit(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](failMsg, 'inbound', targetChain, undefined, universalTxResponse.hash, inbound.pushTxHash || undefined));
                                     baseReceipt = Object.assign(Object.assign({}, baseReceipt), { pushInboundUtxId: inbound.childUtxId, pushInboundTxHash: inbound.pushTxHash || undefined, externalStatus: 'failed', externalError: failMsg });
                                 }
                             }
@@ -755,8 +755,8 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                                 // Annotate receipt for inbound-leg outcome too.
                                 baseReceipt = Object.assign(Object.assign({}, baseReceipt), { externalStatus: isTimeout ? 'timeout' : 'failed', externalError: errMsg });
                                 emit(isTimeout
-                                    ? progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03](targetChain, inboundTimeoutMs, 'inbound')
-                                    : progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](errMsg, 'inbound', targetChain));
+                                    ? progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03](targetChain, inboundTimeoutMs, 'inbound', universalTxResponse.hash)
+                                    : progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](errMsg, 'inbound', targetChain, undefined, universalTxResponse.hash));
                                 callbacks.printLog(`[wait] R3 inbound tracking failed: ${errMsg}`);
                             }
                         }
@@ -764,15 +764,6 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                     catch (error) {
                         const errMsg = error instanceof Error ? error.message : String(error);
                         const isTimeout = error instanceof outbound_sync_1.OutboundTimeoutError;
-                        emit(isTimeout
-                            ? hooks.timeout(targetChain, outboundTimeoutMs)
-                            : hooks.failed(targetChain, errMsg));
-                        // Annotate the receipt so callers can distinguish external-leg
-                        // outcomes without sniffing errMsg. Push Chain leg still succeeded
-                        // (status stays 1); inspect `externalStatus` / `externalError` for
-                        // the external/inbound leg outcome. On a reverted outbound the
-                        // observed tx hash is carried by OutboundFailedError — expose it
-                        // as externalTxHash so consumers can link to the explorer.
                         const failedExternalTxHash = error instanceof outbound_sync_1.OutboundFailedError ? error.externalTxHash : undefined;
                         // Normalize to chain-native display form for SVM (base58); EVM hex
                         // passes through unchanged. `OutboundFailedError.destinationChain`
@@ -782,6 +773,18 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
                             ? (_h = (0, helpers_1.chainFromNamespace)(error.destinationChain)) !== null && _h !== void 0 ? _h : undefined
                             : undefined;
                         const failedExternalTxHashDisplay = (_j = (0, helpers_1.toExternalTxHashDisplay)(failedChain, failedExternalTxHash)) !== null && _j !== void 0 ? _j : failedExternalTxHash;
+                        emit(isTimeout
+                            ? hooks.timeout(targetChain, outboundTimeoutMs, universalTxResponse.hash)
+                            : hooks.failed(targetChain, errMsg, {
+                                pushTxHash: universalTxResponse.hash,
+                                txHash: failedExternalTxHashDisplay,
+                            }));
+                        // Annotate the receipt so callers can distinguish external-leg
+                        // outcomes without sniffing errMsg. Push Chain leg still succeeded
+                        // (status stays 1); inspect `externalStatus` / `externalError` for
+                        // the external/inbound leg outcome. On a reverted outbound the
+                        // observed tx hash is carried by OutboundFailedError — expose it
+                        // as externalTxHash so consumers can link to the explorer.
                         baseReceipt = Object.assign(Object.assign(Object.assign({}, baseReceipt), { externalStatus: isTimeout ? 'timeout' : 'failed', externalError: errMsg }), (failedExternalTxHashDisplay
                             ? { externalTxHash: failedExternalTxHashDisplay }
                             : {}));
@@ -825,6 +828,12 @@ function transformToUniversalTxResponse(ctx_1, tx_1) {
             // 7. Metadata
             type,
             typeVerbose,
+            // Atomic by default — a single tx, an EIP-7702 batch, and a UEA multicall
+            // are all all-or-nothing. Only the native sequential fallback loop overrides
+            // this to `false` (see sendPushTx in push-chain-tx.ts). Historical lookups
+            // via trackTransaction also keep the default, since the past execution mode
+            // isn't always recoverable.
+            atomic: true,
             signature,
             // 8. Raw Universal Fields
             raw: rawTransactionData,

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

@@ -124,7 +124,7 @@ function reconstructProgressEvents(universalTxResponse, universalTxData) {
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_103_03_04](universalTxResponse.gasLimit, BigInt(0)));
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_107]());
     if (isFailed) {
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02](errorMsg));
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_02](errorMsg, undefined, universalTxResponse.hash));
     }
     else {
         events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_199_01]([universalTxResponse]));
@@ -161,7 +161,7 @@ function reconstructR2(universalTxResponse, universalTxData, isFailed, errorMsg)
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_204_03]());
     events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_207](targetChain));
     if (isFailed) {
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02](errorMsg));
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02](targetChain, errorMsg, undefined, universalTxResponse.hash));
     }
     return events;
 }
@@ -187,7 +187,7 @@ function reconstructR3(universalTxResponse, universalTxData, isFailed, errorMsg)
     if (isFailed) {
         // Reconstructed Push-chain-tx failure — phase='push' so the title reads
         // "Push Chain Tx Failed" rather than the inbound copy.
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](errorMsg, 'push'));
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](errorMsg, 'push', undefined, undefined, undefined, universalTxResponse.hash));
     }
     return events;
 }
@@ -267,6 +267,7 @@ function decodeR3MergedInnerCount(outboundPayload) {
     return 0;
 }
 function reconstructMultichain(universalTxResponse, universalTxData, isFailed, errorMsg) {
+    var _a, _b, _c, _d, _e;
     const events = [];
     const outbounds = universalTxData.outboundTx;
     // Merged-R1 recovery: each R3 outbound's payload embeds the
@@ -343,14 +344,18 @@ function reconstructMultichain(universalTxResponse, universalTxData, isFailed, e
             failureMsg = legError;
         }
     });
+    const finalObservedTxHash = (_c = (_b = (_a = [...outbounds].reverse().find((ob) => { var _a; return (_a = ob.observedTx) === null || _a === void 0 ? void 0 : _a.txHash; })) === null || _a === void 0 ? void 0 : _a.observedTx) === null || _b === void 0 ? void 0 : _b.txHash) !== null && _c !== void 0 ? _c : universalTxResponse.hash;
+    const failedObservedTxHash = failedAt !== null
+        ? (_e = (_d = outbounds[failedAt - 1]) === null || _d === void 0 ? void 0 : _d.observedTx) === null || _e === void 0 ? void 0 : _e.txHash
+        : undefined;
     if (failedAt !== null) {
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_02](failedAt, hopCount, failureMsg));
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_02](failedAt, hopCount, failureMsg, failedObservedTxHash, universalTxResponse.hash));
     }
     else if (isFailed) {
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_02](hopCount, hopCount, errorMsg));
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_02](hopCount, hopCount, errorMsg, undefined, universalTxResponse.hash));
     }
     else {
-        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_01](hopCount));
+        events.push(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_01](hopCount, finalObservedTxHash));
     }
     return events;
 }