@pushchain/core 6.0.18 → 6.0.20

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+@pushchain/core@6.0.20 (2026-07-10)
+
+- fix: support custom EIP-7702 signers and dynamic multicall gas
+
+---
+
+@pushchain/core@6.0.19 (2026-07-01)
+
+- feat: use OZ ERC-7821 executor for 7702 batching
+- feat: native EIP-7702 atomic multicall for native-Push EOAs
+- feat: archive-RPC fallback for prune-miss reads in tracking
+
+---
+
 @pushchain/core@6.0.17 (2026-06-09)
 
 - fix: make SVM payload encoding browser-safe

package/package.json

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

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

@@ -54,12 +54,27 @@ export declare const SYNTHETIC_PUSH_ERC20: Record<PUSH_NETWORK, {
  * References -
  * https://namespaces.chainagnostic.org/solana/caip2
  */
+/**
+ * EIP-7702 batch executor (`PushBatchExecutor`) delegation targets, per chain.
+ *
+ * Native Push EOAs delegate their code to this contract (via a type-4 / SetCode
+ * transaction) to execute a `MultiCall[]` batch atomically in a single tx,
+ * replacing the legacy non-atomic per-call loop.
+ *
+ * An entry is absent until the contract is deployed to that chain. When absent,
+ * the SDK falls back to sequential single-call execution. Fill in the address
+ * after deploying `push-chain-core-contracts/src/executor/PushBatchExecutor.sol`.
+ */
+export declare const PUSH_BATCH_EXECUTOR_ADDRESS: Partial<Record<CHAIN, `0x${string}`>>;
+/** Returns the configured 7702 batch-executor address for a chain, if any. */
+export declare function getBatchExecutorAddress(chain: CHAIN): `0x${string}` | undefined;
 export declare const CHAIN_INFO: Record<CHAIN, {
     chainId: string;
     vm: VM;
     lockerContract?: string;
     gatewayVersion?: 'v0' | 'v1';
     defaultRPC: string[];
+    archiveRPC?: string[];
     confirmations: number;
     fastConfirmations: number;
     timeout: number;
@@ -77,6 +92,7 @@ export declare const CHAIN_INFO: Record<CHAIN, {
 export declare const PUSH_CHAIN_INFO: Record<CHAIN.PUSH_MAINNET | CHAIN.PUSH_TESTNET_DONUT | CHAIN.PUSH_LOCALNET, (typeof CHAIN_INFO)[CHAIN.PUSH_MAINNET] & {
     denom: string;
     tendermintRpc: string[];
+    archiveTendermintRpc?: string[];
     prefix: string;
     factoryAddress: `0x${string}`;
     pushDecimals: bigint;

package/src/lib/constants/chain.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CHAIN_EXPLORERS = exports.CEA_FACTORY_ADDRESSES = exports.VAULT_ADDRESSES = exports.SVM_PYTH_PRICE_FEED = exports.UNIVERSAL_GATEWAY_ADDRESSES = exports.PUSH_VIEM_CHAINS = exports.PUSH_CHAIN_INFO = exports.CHAIN_INFO = exports.SYNTHETIC_PUSH_ERC20 = exports.UEA_MIGRATION = exports.UEA_FACTORY = exports.UEA_PROXY = exports.VM_NAMESPACE = void 0;
+exports.CHAIN_EXPLORERS = exports.CEA_FACTORY_ADDRESSES = exports.VAULT_ADDRESSES = exports.SVM_PYTH_PRICE_FEED = exports.UNIVERSAL_GATEWAY_ADDRESSES = exports.PUSH_VIEM_CHAINS = exports.PUSH_CHAIN_INFO = exports.CHAIN_INFO = exports.PUSH_BATCH_EXECUTOR_ADDRESS = exports.SYNTHETIC_PUSH_ERC20 = exports.UEA_MIGRATION = exports.UEA_FACTORY = exports.UEA_PROXY = exports.VM_NAMESPACE = void 0;
+exports.getBatchExecutorAddress = getBatchExecutorAddress;
 exports.getPushViemChain = getPushViemChain;
 exports.getExplorerTxUrl = getExplorerTxUrl;
 exports.getExplorerAddressUrl = getExplorerAddressUrl;
@@ -41,8 +42,8 @@ exports.UEA_FACTORY = {
  */
 exports.UEA_MIGRATION = {
     [enums_1.PUSH_NETWORK.MAINNET]: '0xTBD',
-    [enums_1.PUSH_NETWORK.TESTNET_DONUT]: '0x6b44D1c691F4F9e33Ce39776554844acEcF35D75',
-    [enums_1.PUSH_NETWORK.TESTNET]: '0x6b44D1c691F4F9e33Ce39776554844acEcF35D75',
+    [enums_1.PUSH_NETWORK.TESTNET_DONUT]: '0x862F13DBb7E21e552f7DAF6D954E7155e7f666AD',
+    [enums_1.PUSH_NETWORK.TESTNET]: '0x862F13DBb7E21e552f7DAF6D954E7155e7f666AD',
     [enums_1.PUSH_NETWORK.LOCALNET]: '0xTBD',
 };
 /**
@@ -145,6 +146,27 @@ exports.SYNTHETIC_PUSH_ERC20 = {
  * References -
  * https://namespaces.chainagnostic.org/solana/caip2
  */
+/**
+ * EIP-7702 batch executor (`PushBatchExecutor`) delegation targets, per chain.
+ *
+ * Native Push EOAs delegate their code to this contract (via a type-4 / SetCode
+ * transaction) to execute a `MultiCall[]` batch atomically in a single tx,
+ * replacing the legacy non-atomic per-call loop.
+ *
+ * An entry is absent until the contract is deployed to that chain. When absent,
+ * the SDK falls back to sequential single-call execution. Fill in the address
+ * after deploying `push-chain-core-contracts/src/executor/PushBatchExecutor.sol`.
+ */
+exports.PUSH_BATCH_EXECUTOR_ADDRESS = {
+    // OpenZeppelin ERC-7821 based executor (with payable receive), deployed
+    // 2026-06-22, tx 0xbbe4176a….
+    [enums_1.CHAIN.PUSH_TESTNET_DONUT]: '0x0106BF2F9B02f32203A83a3bDaD79fE8818f3796',
+    // [CHAIN.PUSH_MAINNET]: '0x...', // TODO: set after mainnet deploy
+};
+/** Returns the configured 7702 batch-executor address for a chain, if any. */
+function getBatchExecutorAddress(chain) {
+    return exports.PUSH_BATCH_EXECUTOR_ADDRESS[chain];
+}
 exports.CHAIN_INFO = {
     // Push
     [enums_1.CHAIN.PUSH_MAINNET]: {
@@ -160,6 +182,9 @@ exports.CHAIN_INFO = {
         chainId: '42101',
         vm: enums_1.VM.EVM,
         defaultRPC: ['https://evm.donut.rpc.push.org/'],
+        // Archive (full-history) EVM RPC — fallback for tracking older txs the
+        // prune `defaultRPC` has dropped.
+        archiveRPC: ['https://archive.evm.donut.rpc.push.org/'],
         confirmations: 1,
         fastConfirmations: 0,
         timeout: 30000,
@@ -305,7 +330,10 @@ exports.CHAIN_INFO = {
  */
 exports.PUSH_CHAIN_INFO = {
     [enums_1.CHAIN.PUSH_MAINNET]: Object.assign(Object.assign({}, exports.CHAIN_INFO[enums_1.CHAIN.PUSH_MAINNET]), { denom: 'upc', tendermintRpc: ['TBD'], prefix: 'push', factoryAddress: '0xTBD', pushDecimals: BigInt(1e18), usdcDecimals: BigInt(1e8), pushToUsdcNumerator: BigInt(1e7), pushToUsdcDenominator: BigInt(1e18) }),
-    [enums_1.CHAIN.PUSH_TESTNET_DONUT]: Object.assign(Object.assign({}, exports.CHAIN_INFO[enums_1.CHAIN.PUSH_TESTNET_DONUT]), { denom: 'upc', tendermintRpc: ['https://donut.rpc.push.org/'], prefix: 'push', factoryAddress: '0x00000000000000000000000000000000000000eA', pushDecimals: BigInt(1e18), usdcDecimals: BigInt(1e8), pushToUsdcNumerator: BigInt(1e7), pushToUsdcDenominator: BigInt(1e18) }),
+    [enums_1.CHAIN.PUSH_TESTNET_DONUT]: Object.assign(Object.assign({}, exports.CHAIN_INFO[enums_1.CHAIN.PUSH_TESTNET_DONUT]), { denom: 'upc', tendermintRpc: ['https://donut.rpc.push.org/'], 
+        // Archive (full-history) Tendermint RPC — fallback for tracking older txs
+        // whose legs fall outside the prune window.
+        archiveTendermintRpc: ['https://archive.donut.rpc.push.org/'], prefix: 'push', factoryAddress: '0x00000000000000000000000000000000000000eA', pushDecimals: BigInt(1e18), usdcDecimals: BigInt(1e8), pushToUsdcNumerator: BigInt(1e7), pushToUsdcDenominator: BigInt(1e18) }),
     [enums_1.CHAIN.PUSH_LOCALNET]: Object.assign(Object.assign({}, exports.CHAIN_INFO[enums_1.CHAIN.PUSH_LOCALNET]), { denom: 'upc', tendermintRpc: ['http://localhost:26657'], prefix: 'push', factoryAddress: '0x00000000000000000000000000000000000000eA', pushDecimals: BigInt(1e18), usdcDecimals: BigInt(1e8), pushToUsdcNumerator: BigInt(1e7), pushToUsdcDenominator: BigInt(1e18) }),
 };
 // ============================================================================

package/src/lib/formatters.d.ts

@@ -5,3 +5,4 @@ export declare function formatPc(valueWei: bigint, precision?: number): string;
  * debugging but prefix it with the human PC amount users can reason about.
  */
 export declare function normalizePcInsufficientFundsError(message: string): string;
+export declare function normalizePublicErrorMessage(error: unknown): string;

package/src/lib/formatters.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatPc = formatPc;
 exports.normalizePcInsufficientFundsError = normalizePcInsufficientFundsError;
+exports.normalizePublicErrorMessage = normalizePublicErrorMessage;
 const PC_DECIMALS = 18;
 function formatTokenUnits(value, decimals, precision) {
     if (!Number.isInteger(decimals) || decimals < 0) {
@@ -30,6 +31,46 @@ function formatTokenUnits(value, decimals, precision) {
 function formatPc(valueWei, precision) {
     return `${formatTokenUnits(valueWei, PC_DECIMALS, precision)} PC`;
 }
+function getErrorMessage(error) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+    if (typeof error === 'string')
+        return error;
+    const stringifyFallback = (value) => {
+        try {
+            const json = JSON.stringify(value);
+            return json === undefined ? String(value) : json;
+        }
+        catch (_a) {
+            return String(value);
+        }
+    };
+    if (error instanceof Error) {
+        const maybe = error;
+        return String((_g = (_f = (_e = (_c = (_a = maybe.shortMessage) !== null && _a !== void 0 ? _a : (_b = maybe.cause) === null || _b === void 0 ? void 0 : _b.shortMessage) !== null && _c !== void 0 ? _c : (_d = maybe.cause) === null || _d === void 0 ? void 0 : _d.reason) !== null && _e !== void 0 ? _e : maybe.details) !== null && _f !== void 0 ? _f : maybe.message) !== null && _g !== void 0 ? _g : stringifyFallback(error));
+    }
+    if (typeof error === 'object' && error !== null) {
+        const maybe = error;
+        return String((_q = (_p = (_o = (_m = (_k = (_h = maybe.shortMessage) !== null && _h !== void 0 ? _h : (_j = maybe.cause) === null || _j === void 0 ? void 0 : _j.shortMessage) !== null && _k !== void 0 ? _k : (_l = maybe.cause) === null || _l === void 0 ? void 0 : _l.reason) !== null && _m !== void 0 ? _m : maybe.reason) !== null && _o !== void 0 ? _o : maybe.details) !== null && _p !== void 0 ? _p : maybe.message) !== null && _q !== void 0 ? _q : stringifyFallback(error));
+    }
+    return String(error);
+}
+function collectErrorMessages(error, depth = 0) {
+    if (depth > 4)
+        return [];
+    if (typeof error === 'string')
+        return [error];
+    if (error instanceof Error || (typeof error === 'object' && error !== null)) {
+        const maybe = error;
+        const values = [
+            maybe.shortMessage,
+            maybe.details,
+            maybe.reason,
+            maybe.message,
+        ].filter((value) => typeof value === 'string');
+        return [...values, ...collectErrorMessages(maybe.cause, depth + 1)];
+    }
+    return [String(error)];
+}
 /**
  * Push Chain EVM/RPC insufficient-funds errors surface native balances as raw
  * wei, usually in the form "have <wei> want <wei>". Preserve the raw value for
@@ -41,6 +82,30 @@ function normalizePcInsufficientFundsError(message) {
     }
     return message
         .replace(/\bhave\s+([0-9]+)(?=\s+want\b)/gi, (_match, value) => `have ${formatPc(BigInt(value))} (${value} wei)`)
-        .replace(/\bwant\s+([0-9]+)(?![\d.]|\s*(?:wei|PC))/gi, (_match, value) => `want ${formatPc(BigInt(value))} (${value} wei)`);
+        .replace(/\bwant\s+([0-9]+)(?!\d|\.\d|\s*(?:wei|PC))/gi, (_match, value) => `want ${formatPc(BigInt(value))} (${value} wei)`);
+}
+function normalizePublicErrorMessage(error) {
+    const message = normalizePcInsufficientFundsError(getErrorMessage(error));
+    const searchableMessage = normalizePcInsufficientFundsError(collectErrorMessages(error).join(' '));
+    const haveWant = searchableMessage.match(/\bhave\s+([0-9]+(?:\.[0-9]+)?\s+PC)(?:\s+\([^)]+\))?\s+want\s+([0-9]+(?:\.[0-9]+)?\s+PC)/i);
+    if (/insufficient funds for gas \* price \+ value/i.test(searchableMessage) ||
+        /exceeds the balance of the account/i.test(searchableMessage) ||
+        /insufficient funds for intrinsic transaction cost/i.test(searchableMessage)) {
+        const havePc = haveWant === null || haveWant === void 0 ? void 0 : haveWant[1];
+        const wantPc = haveWant === null || haveWant === void 0 ? void 0 : haveWant[2];
+        if (havePc && wantPc) {
+            return `Insufficient balance for transaction gas/value: have ${havePc}, need ${wantPc}.`;
+        }
+        return 'Insufficient balance for transaction gas/value.';
+    }
+    if (/Attempt to debit an account but found no record of a prior credit/i.test(searchableMessage)) {
+        return 'Insufficient Solana balance for transaction fee/value: account has no prior credit.';
+    }
+    if (/insufficient lamports/i.test(searchableMessage) ||
+        /custom program error: 0x1/i.test(searchableMessage) ||
+        /insufficient funds for rent/i.test(searchableMessage)) {
+        return 'Insufficient Solana balance for transaction fee/value.';
+    }
+    return message.length > 500 ? `${message.slice(0, 497)}...` : message;
 }
 //# sourceMappingURL=formatters.js.map

package/src/lib/index.d.ts

@@ -1,6 +1,6 @@
 import { PushChain } from './push-chain/push-chain';
 export type { ConversionQuote } from './constants/tokens';
-export type { UniversalSigner, UniversalAccount, UniversalSignerSkeleton, DerivedExecutorAccount, ResolvedAccount, ResolvedControllerAccounts, AccountType, AccountRole, } from './universal/universal.types';
+export type { UniversalSigner, UniversalAccount, UniversalSignerSkeleton, SignAuthorizationParams, SignedAuthorization, DerivedExecutorAccount, ResolvedAccount, ResolvedControllerAccounts, AccountType, AccountRole, } from './universal/universal.types';
 export type { ChainTarget, ChainSource, UniversalTo, TransactionRouteType, UniversalExecuteParams, UniversalOutboundTxRequest, PreparedUniversalTx, CascadedTxResponse, CascadeHopInfo, CascadeTrackOptions, CascadeProgressEvent, CascadeCompletionResult, MultiChainTxResponse, OutboundTxDetails, WaitForOutboundOptions, SvmGatewayAccountMeta, SvmExecutePayloadFields, AccountStatus, UEAStatus, RescueFundsParams, } from './orchestrator/orchestrator.types';
 export { parseUEAVersion } from './orchestrator/orchestrator.types';
 export { TransactionRoute, detectRoute, isChainTarget } from './orchestrator/route-detector';

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

@@ -1363,9 +1363,9 @@ function composeCascade(ctx, segments, ueaAddress, ueaBalance, ueaNonce) {
 // createCascadedBuilder
 // ============================================================================
 function txHashFromProgressEvent(event) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e, _f;
     const response = event.response;
-    return (_d = (_a = response === null || response === void 0 ? void 0 : response.txHash) !== null && _a !== void 0 ? _a : (_c = (_b = response === null || response === void 0 ? void 0 : response.response) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.hash) !== null && _d !== void 0 ? _d : '';
+    return ((_f = (_c = (_b = (_a = response === null || response === void 0 ? void 0 : response.txHash) !== null && _a !== void 0 ? _a : response === null || response === void 0 ? void 0 : response.pushTxHash) !== null && _b !== void 0 ? _b : response === null || response === void 0 ? void 0 : response.rootTxHash) !== null && _c !== void 0 ? _c : (_e = (_d = response === null || response === void 0 ? void 0 : response.response) === null || _d === void 0 ? void 0 : _d[0]) === null || _e === void 0 ? void 0 : _e.hash) !== null && _f !== void 0 ? _f : '');
 }
 function withMultihopRootProgressMapping(ctx, run) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
@@ -1534,7 +1534,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                 hops: hopInfos,
                 hopCount: hops.length,
                 waitForAll: (opts) => tslib_1.__awaiter(this, void 0, void 0, function* () {
-                    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+                    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
                     const { pollingIntervalMs = 10000, timeout = 300000, progressHook: cascadeProgressHook, eventHook = defaultEventHook, } = opts || {};
                     const startTime = Date.now();
                     // Per-hop progress emission. Fans out cascade markers to BOTH the
@@ -1576,20 +1576,26 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                             return; // skip after final hop — 999-01 takes over
                         emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_002_99_99](n, totalHops));
                     };
+                    const currentFinalTxHash = () => {
+                        var _a, _b;
+                        return (_b = (_a = [...hopInfos]
+                            .reverse()
+                            .find((hop) => hop.status === 'confirmed' && hop.txHash)) === null || _a === void 0 ? void 0 : _a.txHash) !== null && _b !== void 0 ? _b : response.hash;
+                    };
                     const emitCascadeSuccess = () => {
                         if (!isMulti)
                             return;
-                        emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_01](totalHops));
+                        emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_01](totalHops, currentFinalTxHash()));
                     };
-                    const emitCascadeFailed = (failedIdx0, errMsg) => {
+                    const emitCascadeFailed = (failedIdx0, errMsg, txHash, pushTxHash) => {
                         if (!isMulti)
                             return;
-                        emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_02](failedIdx0 + 1, totalHops, errMsg));
+                        emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_02](failedIdx0 + 1, totalHops, errMsg, txHash, pushTxHash));
                     };
-                    const emitCascadeTimeout = (failedIdx0) => {
+                    const emitCascadeTimeout = (failedIdx0, txHash, pushTxHash) => {
                         if (!isMulti)
                             return;
-                        emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_03](failedIdx0 + 1, totalHops));
+                        emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_999_03](failedIdx0 + 1, totalHops, txHash, pushTxHash));
                     };
                     const emitRouteIntermediateComplete = (hop, txHash) => {
                         var _a;
@@ -1612,10 +1618,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                         }
                     };
                     const buildCompletionResult = (success, failedAt) => {
-                        var _a, _b;
-                        const finalTxHash = (_b = (_a = [...hopInfos]
-                            .reverse()
-                            .find((hop) => hop.status === 'confirmed' && hop.txHash)) === null || _a === void 0 ? void 0 : _a.txHash) !== null && _b !== void 0 ? _b : response.hash;
+                        const finalTxHash = currentFinalTxHash();
                         cascadeResponse.finalTxHash = finalTxHash;
                         return Object.assign({ success, hops: hopInfos, finalTxHash, finalTxResponse: cascadeResponse }, (failedAt !== undefined ? { failedAt } : {}));
                     };
@@ -1643,7 +1646,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                         const isAfterCeaToPush = (index) => ceaToPushIndex >= 0 && index > ceaToPushIndex;
                         const rootOutboundIndexByHop = buildRootOutboundIndexByHop(segments, hops);
                         const trackOutboundHops = (outboundHops, pushTxHash, resolvedSubTxId, outboundIndexByHop, trackingOptions) => tslib_1.__awaiter(this, void 0, void 0, function* () {
-                            var _a, _b, _c, _d;
+                            var _a, _b, _c, _d, _e;
                             if (outboundHops.length === 0)
                                 return null;
                             const shouldDeferHopCompletion = (hop) => (trackingOptions === null || trackingOptions === void 0 ? void 0 : trackingOptions.deferCeaToPushCompletion) === true &&
@@ -1661,12 +1664,12 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                                         status: 'timeout',
                                         elapsed: Date.now() - startTime,
                                     });
-                                    emitHopEvent(hopHooks.timeout(hop.executionChain, Date.now() - startTime));
-                                    emitCascadeTimeout(hop.hopIndex);
+                                    emitHopEvent(hopHooks.timeout(hop.executionChain, Date.now() - startTime, pushTxHash));
+                                    emitCascadeTimeout(hop.hopIndex, undefined, pushTxHash);
                                     return buildCompletionResult(false, hop.hopIndex);
                                 }
                                 emitHopStart(hop.hopIndex);
-                                emitHopEvent(hopHooks.awaiting(hop.executionChain));
+                                emitHopEvent(hopHooks.awaiting(hop.executionChain, pushTxHash));
                                 cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                     hopIndex: hop.hopIndex,
                                     route: hop.route,
@@ -1691,7 +1694,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                                             if (event.status === 'polling' &&
                                                 lastEmittedStatus !== 'polling') {
                                                 lastEmittedStatus = 'polling';
-                                                emitHopEvent(hopHooks.polling(hop.executionChain, event.elapsed));
+                                                emitHopEvent(hopHooks.polling(hop.executionChain, event.elapsed, pushTxHash));
                                             }
                                         } }));
                                     // `outboundDetails.externalTxHash` from waitForOutboundTx
@@ -1726,21 +1729,29 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                                 catch (err) {
                                     const errMsg = err instanceof Error ? err.message : String(err);
                                     const isTimeout = errMsg.startsWith('Timeout waiting for outbound transaction');
+                                    const failedExternalTxHash = err === null || err === void 0 ? void 0 : err.externalTxHash;
+                                    const failedDisplayTxHash = (_c = (0, helpers_1.toExternalTxHashDisplay)(hop.executionChain, failedExternalTxHash)) !== null && _c !== void 0 ? _c : failedExternalTxHash;
                                     emitHopEvent(isTimeout
-                                        ? hopHooks.timeout(hop.executionChain, remainingTimeout)
-                                        : hopHooks.failed(hop.executionChain, errMsg));
+                                        ? hopHooks.timeout(hop.executionChain, remainingTimeout, pushTxHash)
+                                        : hopHooks.failed(hop.executionChain, errMsg, {
+                                            pushTxHash,
+                                            txHash: failedDisplayTxHash,
+                                        }));
                                     if (isTimeout) {
-                                        emitCascadeTimeout(hop.hopIndex);
+                                        emitCascadeTimeout(hop.hopIndex, failedDisplayTxHash, pushTxHash);
                                     }
                                     else {
-                                        emitCascadeFailed(hop.hopIndex, errMsg);
+                                        emitCascadeFailed(hop.hopIndex, errMsg, failedDisplayTxHash, pushTxHash);
                                     }
+                                    if (failedDisplayTxHash)
+                                        hop.txHash = failedDisplayTxHash;
                                     hop.status = 'failed';
                                     cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                         hopIndex: hop.hopIndex,
                                         route: hop.route,
                                         chain: hop.executionChain,
                                         status: 'failed',
+                                        txHash: failedDisplayTxHash,
                                         elapsed: Date.now() - startTime,
                                     });
                                     return buildCompletionResult(false, hop.hopIndex);
@@ -1749,7 +1760,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                             else {
                                 for (const outHop of outboundHops) {
                                     emitHopStart(outHop.hopIndex);
-                                    emitHopEvent((0, progress_route_hooks_1.pickWaitHooks)(outHop.route).awaiting(outHop.executionChain));
+                                    emitHopEvent((0, progress_route_hooks_1.pickWaitHooks)(outHop.route).awaiting(outHop.executionChain, pushTxHash));
                                 }
                                 const perHopLastStatus = new Map();
                                 const confirmedHops = new Set();
@@ -1774,7 +1785,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                                         const prev = perHopLastStatus.get(event.hopIndex);
                                         if (event.status === 'polling' && prev !== 'polling') {
                                             perHopLastStatus.set(event.hopIndex, 'polling');
-                                            emitHopEvent(eventHooks.polling((_b = (_a = matchedHop === null || matchedHop === void 0 ? void 0 : matchedHop.executionChain) !== null && _a !== void 0 ? _a : event.chain) !== null && _b !== void 0 ? _b : '', Date.now() - startTime));
+                                            emitHopEvent(eventHooks.polling((_b = (_a = matchedHop === null || matchedHop === void 0 ? void 0 : matchedHop.executionChain) !== null && _a !== void 0 ? _a : event.chain) !== null && _b !== void 0 ? _b : '', Date.now() - startTime, pushTxHash));
                                         }
                                         if (event.status === 'confirmed' &&
                                             event.txHash &&
@@ -1799,13 +1810,16 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                                         }
                                     } }));
                                 if (!allOutboundDetails.success) {
-                                    const failedIdx = (_c = allOutboundDetails.failedAt) !== null && _c !== void 0 ? _c : 0;
+                                    const failedIdx = (_d = allOutboundDetails.failedAt) !== null && _d !== void 0 ? _d : 0;
                                     const failedHop = outboundHops.find((h) => h.hopIndex === failedIdx);
                                     const failMsg = failedHop
                                         ? `Outbound failed for hop ${failedIdx} on ${failedHop.executionChain}`
                                         : `Outbound cascade failed at hop ${failedIdx}`;
-                                    emitHopEvent((0, progress_route_hooks_1.pickWaitHooks)(failedHop === null || failedHop === void 0 ? void 0 : failedHop.route).failed((_d = failedHop === null || failedHop === void 0 ? void 0 : failedHop.executionChain) !== null && _d !== void 0 ? _d : '', failMsg));
-                                    emitCascadeFailed(failedIdx, failMsg);
+                                    emitHopEvent((0, progress_route_hooks_1.pickWaitHooks)(failedHop === null || failedHop === void 0 ? void 0 : failedHop.route).failed((_e = failedHop === null || failedHop === void 0 ? void 0 : failedHop.executionChain) !== null && _e !== void 0 ? _e : '', failMsg, {
+                                        pushTxHash,
+                                        txHash: failedHop === null || failedHop === void 0 ? void 0 : failedHop.txHash,
+                                    }));
+                                    emitCascadeFailed(failedIdx, failMsg, failedHop === null || failedHop === void 0 ? void 0 : failedHop.txHash, pushTxHash);
                                     return buildCompletionResult(false, failedIdx);
                                 }
                                 if (trackingOptions === null || trackingOptions === void 0 ? void 0 : trackingOptions.deferCeaToPushCompletion) {
@@ -1874,15 +1888,15 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                             const remainingTimeout = timeout - (Date.now() - startTime);
                             if (remainingTimeout <= 0) {
                                 inboundHop.status = 'failed';
-                                emitHopEvent(hopHooks.timeout(inboundHop.executionChain, Date.now() - startTime));
-                                emitCascadeTimeout(inboundHop.hopIndex);
+                                emitHopEvent(hopHooks.timeout(inboundHop.executionChain, Date.now() - startTime, response.hash));
+                                emitCascadeTimeout(inboundHop.hopIndex, undefined, response.hash);
                                 return buildCompletionResult(false, inboundHop.hopIndex);
                             }
                             const hasTrackedSourceOutbound = Boolean(inboundHop.outboundDetails) &&
                                 ((_d = chain_1.CHAIN_INFO[inboundHop.executionChain]) === null || _d === void 0 ? void 0 : _d.vm) === enums_1.VM.EVM;
                             if (!hasTrackedSourceOutbound) {
                                 emitHopStart(inboundHop.hopIndex);
-                                emitHopEvent(hopHooks.awaiting(inboundHop.executionChain));
+                                emitHopEvent(hopHooks.awaiting(inboundHop.executionChain, response.hash));
                             }
                             cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                 hopIndex: inboundHop.hopIndex,
@@ -1917,7 +1931,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                                             if (event.status === 'polling' &&
                                                 outboundLastStatus !== 'polling') {
                                                 outboundLastStatus = 'polling';
-                                                emitHopEvent(hopHooks.polling(inboundHop.executionChain, event.elapsed));
+                                                emitHopEvent(hopHooks.polling(inboundHop.executionChain, event.elapsed, response.hash));
                                             }
                                         },
                                     });
@@ -1926,16 +1940,19 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                             catch (err) {
                                 const errMsg = err instanceof Error ? err.message : String(err);
                                 const isTimeout = errMsg.startsWith('Timeout waiting for outbound transaction');
+                                const failedExternalTxHash = err === null || err === void 0 ? void 0 : err.externalTxHash;
+                                const failedDisplayTxHash = (_f = (0, helpers_1.toExternalTxHashDisplay)(inboundHop.executionChain, failedExternalTxHash)) !== null && _f !== void 0 ? _f : failedExternalTxHash;
                                 emitHopEvent(isTimeout
-                                    ? hopHooks.timeout(inboundHop.executionChain, remainingTimeout)
-                                    : hopHooks.failed(inboundHop.executionChain, errMsg));
+                                    ? hopHooks.timeout(inboundHop.executionChain, remainingTimeout, response.hash)
+                                    : hopHooks.failed(inboundHop.executionChain, errMsg, {
+                                        pushTxHash: response.hash,
+                                        txHash: failedDisplayTxHash,
+                                    }));
                                 if (isTimeout)
-                                    emitCascadeTimeout(inboundHop.hopIndex);
+                                    emitCascadeTimeout(inboundHop.hopIndex, failedDisplayTxHash, response.hash);
                                 else
-                                    emitCascadeFailed(inboundHop.hopIndex, errMsg);
+                                    emitCascadeFailed(inboundHop.hopIndex, errMsg, failedDisplayTxHash, response.hash);
                                 inboundHop.status = 'failed';
-                                const failedExternalTxHash = err === null || err === void 0 ? void 0 : err.externalTxHash;
-                                const failedDisplayTxHash = (_f = (0, helpers_1.toExternalTxHashDisplay)(inboundHop.executionChain, failedExternalTxHash)) !== null && _f !== void 0 ? _f : failedExternalTxHash;
                                 if (failedDisplayTxHash)
                                     inboundHop.txHash = failedDisplayTxHash;
                                 cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
@@ -1952,7 +1969,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                             inboundHop.outboundDetails = Object.assign(Object.assign({}, sourceOutboundDetails), { externalTxHash: displayExternalTxHash });
                             inboundHop.txHash = displayExternalTxHash;
                             emitHopEvent(hopHooks.success(inboundHop.outboundDetails));
-                            emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_310_01](inboundHop.executionChain));
+                            emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_310_01](inboundHop.executionChain, response.hash));
                             let inboundLastStatus;
                             const inboundRemainingTimeout = timeout - (Date.now() - startTime);
                             try {
@@ -1964,7 +1981,7 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                                         if (event.status === 'polling' &&
                                             inboundLastStatus !== 'polling') {
                                             inboundLastStatus = 'polling';
-                                            emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_310_02](inboundHop.executionChain, event.elapsedMs));
+                                            emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_310_02](inboundHop.executionChain, event.elapsedMs, response.hash));
                                         }
                                     },
                                 });
@@ -1973,12 +1990,12 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                                 const errMsg = err instanceof Error ? err.message : String(err);
                                 const isTimeout = err instanceof inbound_tracker_1.InboundTimeoutError;
                                 emitHopEvent(isTimeout
-                                    ? progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03](inboundHop.executionChain, inboundRemainingTimeout, 'inbound')
-                                    : progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](errMsg, 'inbound', inboundHop.executionChain));
+                                    ? progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03](inboundHop.executionChain, inboundRemainingTimeout, 'inbound', response.hash)
+                                    : progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](errMsg, 'inbound', inboundHop.executionChain, undefined, response.hash));
                                 if (isTimeout)
-                                    emitCascadeTimeout(inboundHop.hopIndex);
+                                    emitCascadeTimeout(inboundHop.hopIndex, undefined, response.hash);
                                 else
-                                    emitCascadeFailed(inboundHop.hopIndex, errMsg);
+                                    emitCascadeFailed(inboundHop.hopIndex, errMsg, undefined, response.hash);
                                 inboundHop.status = 'failed';
                                 cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                     hopIndex: inboundHop.hopIndex,
@@ -1994,8 +2011,8 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                                 inboundHop.status = 'failed';
                                 inboundHop.txHash =
                                     childInbound.pushTxHash || displayExternalTxHash;
-                                emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](failMsg, 'inbound', inboundHop.executionChain));
-                                emitCascadeFailed(inboundHop.hopIndex, failMsg);
+                                emitHopEvent(progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](failMsg, 'inbound', inboundHop.executionChain, undefined, response.hash, childInbound.pushTxHash || undefined));
+                                emitCascadeFailed(inboundHop.hopIndex, failMsg, childInbound.pushTxHash || undefined, response.hash);
                                 cascadeProgressHook === null || cascadeProgressHook === void 0 ? void 0 : cascadeProgressHook({
                                     hopIndex: inboundHop.hopIndex,
                                     route: inboundHop.route,
@@ -2056,12 +2073,13 @@ function createCascadedBuilder(ctx, preparedTxs, callbacks, defaultEventHook, op
                         const failedIdx = hopInfos.findIndex((h) => h.status !== 'confirmed');
                         const errMsg = err instanceof Error ? err.message : String(err);
                         const failedAt = failedIdx >= 0 ? failedIdx : 0;
+                        const failedTxHash = (_k = hopInfos[failedAt]) === null || _k === void 0 ? void 0 : _k.txHash;
                         const isTimeout = errMsg.startsWith('Timeout');
                         if (isTimeout) {
-                            emitCascadeTimeout(failedAt);
+                            emitCascadeTimeout(failedAt, failedTxHash, response.hash);
                         }
                         else {
-                            emitCascadeFailed(failedAt, errMsg);
+                            emitCascadeFailed(failedAt, errMsg, failedTxHash, response.hash);
                         }
                         return buildCompletionResult(false, failedAt);
                     }

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

@@ -51,10 +51,10 @@ function waitForEvmReceipt(evmClient, txHash, timeoutMs) {
 function waitForEvmConfirmationsWithCountdown(ctx, evmClient, txHash, confirmations, timeoutMs) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
         if (confirmations <= 0) {
-            (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_02, 0, 0);
+            (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_02, 0, 0, txHash);
             return;
         }
-        (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03, confirmations);
+        (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03, confirmations, txHash);
         const start = Date.now();
         const receipt = yield waitForEvmReceipt(evmClient, txHash, timeoutMs);
         const targetBlock = receipt.blockNumber + BigInt(confirmations);
@@ -64,7 +64,7 @@ function waitForEvmConfirmationsWithCountdown(ctx, evmClient, txHash, confirmati
             const currentBlock = yield evmClient.publicClient.getBlockNumber();
             if (currentBlock >= targetBlock) {
                 if (lastEmitted < confirmations) {
-                    (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_02, confirmations, confirmations);
+                    (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_02, confirmations, confirmations, txHash);
                 }
                 return;
             }
@@ -73,7 +73,7 @@ function waitForEvmConfirmationsWithCountdown(ctx, evmClient, txHash, confirmati
             if (completed > lastEmitted) {
                 (0, context_2.fireProgressHook)(ctx, completed >= confirmations
                     ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_02
-                    : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_01, completed, confirmations);
+                    : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_01, completed, confirmations, txHash);
                 lastEmitted = completed;
                 if (completed >= confirmations)
                     return;
@@ -88,10 +88,10 @@ function waitForEvmConfirmationsWithCountdown(ctx, evmClient, txHash, confirmati
 function waitForSvmConfirmationsWithCountdown(ctx, svmClient, txSignature, confirmations, timeoutMs) {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
         if (confirmations <= 0) {
-            (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_02, 0, 0);
+            (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_02, 0, 0, txSignature);
             return;
         }
-        (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03, confirmations);
+        (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03, confirmations, txSignature);
         const start = Date.now();
         let lastConfirmed = 0;
         // eslint-disable-next-line no-constant-condition
@@ -113,12 +113,12 @@ function waitForSvmConfirmationsWithCountdown(ctx, svmClient, txSignature, confi
                     const clamped = currentConfirms >= confirmations ? confirmations : currentConfirms;
                     (0, context_2.fireProgressHook)(ctx, clamped >= confirmations
                         ? progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_02
-                        : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_01, Math.max(1, clamped), confirmations);
+                        : progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_01, Math.max(1, clamped), confirmations, txSignature);
                     lastConfirmed = currentConfirms;
                 }
                 if (hasEnoughConfirmations || isFinalized) {
                     if (lastConfirmed < confirmations) {
-                        (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_02, confirmations, confirmations);
+                        (0, context_2.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_106_03_02, confirmations, confirmations, txSignature);
                     }
                     return;
                 }

package/src/lib/orchestrator/internals/error-decoder.d.ts

@@ -41,6 +41,7 @@ export type DecodedRevertUnknown = {
     selector: `0x${string}`;
 };
 export type DecodedRevert = DecodedRevertCustom | DecodedRevertString | DecodedRevertUnknown;
+export declare function formatDecodedRevertForUser(decoded: DecodedRevert): string;
 /**
  * Extracts the first hex blob after `ret ` from a Cosmos tx error message,
  * pulls the 4-byte selector, and looks it up. Returns `null` when no blob

package/src/lib/orchestrator/internals/error-decoder.js

@@ -16,6 +16,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ERROR_STRING_SELECTOR = exports.KNOWN_ERROR_SELECTORS = void 0;
+exports.formatDecodedRevertForUser = formatDecodedRevertForUser;
 exports.decodeRevert = decodeRevert;
 exports.KNOWN_ERROR_SELECTORS = {
     '0xacfdb444': {
@@ -57,6 +58,15 @@ exports.KNOWN_ERROR_SELECTORS = {
 exports.ERROR_STRING_SELECTOR = '0x08c379a0';
 /** Hard cap on the decoded string length; protects against malformed data. */
 const MAX_DECODED_STRING_LEN = 1024;
+function formatDecodedRevertForUser(decoded) {
+    if (decoded.kind === 'custom') {
+        return `${decoded.name}: ${decoded.hint}`;
+    }
+    if (decoded.kind === 'string') {
+        return `Reverted with Error("${decoded.decoded}")`;
+    }
+    return `Unknown EVM revert selector ${decoded.selector}`;
+}
 /**
  * Extracts the first hex blob after `ret ` from a Cosmos tx error message,
  * pulls the 4-byte selector, and looks it up. Returns `null` when no blob

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

@@ -29,7 +29,7 @@ const formatters_1 = require("../../formatters");
  */
 class PushChainExecutionError extends Error {
     constructor(message, opts = {}) {
-        super((0, formatters_1.normalizePcInsufficientFundsError)(message));
+        super((0, formatters_1.normalizePublicErrorMessage)(message));
         this.code = 'PUSH_CHAIN_EXECUTION_FAILED';
         this.name = 'PushChainExecutionError';
         this.gatewayTxHash = opts.gatewayTxHash;