@pushchain/core 5.0.0 → 5.1.0

package/src/lib/orchestrator/cea-utils.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * CEA (Chain Executor Account) Utilities
+ *
+ * Functions for computing CEA addresses and interacting with CEAFactory contracts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCEAAddress = getCEAAddress;
+exports.getPushAccountForCEA = getPushAccountForCEA;
+exports.isCEA = isCEA;
+exports.chainSupportsCEA = chainSupportsCEA;
+exports.chainSupportsOutbound = chainSupportsOutbound;
+exports.getCEAFactoryAddress = getCEAFactoryAddress;
+exports.getAllCEAAddresses = getAllCEAAddresses;
+const tslib_1 = require("tslib");
+const viem_1 = require("viem");
+const chains_1 = require("viem/chains");
+const enums_1 = require("../constants/enums");
+const chain_1 = require("../constants/chain");
+const abi_1 = require("../constants/abi");
+/**
+ * Map CHAIN enum to viem chain object
+ */
+const VIEM_CHAINS = {
+    [enums_1.CHAIN.ETHEREUM_SEPOLIA]: chains_1.sepolia,
+    [enums_1.CHAIN.ARBITRUM_SEPOLIA]: chains_1.arbitrumSepolia,
+    [enums_1.CHAIN.BASE_SEPOLIA]: chains_1.baseSepolia,
+    [enums_1.CHAIN.BNB_TESTNET]: chains_1.bscTestnet,
+};
+/**
+ * Get viem chain object for a CHAIN enum
+ */
+function getViemChain(chain) {
+    const viemChain = VIEM_CHAINS[chain];
+    if (!viemChain) {
+        throw new Error(`No viem chain mapping for ${chain}`);
+    }
+    return viemChain;
+}
+/**
+ * Get CEA address for a UEA on a specific chain
+ *
+ * @param ueaAddress - UEA address on Push Chain
+ * @param chain - Target external chain
+ * @param rpcUrl - Optional custom RPC URL
+ * @returns CEA address and deployment status
+ * @throws Error if chain doesn't have CEAFactory
+ */
+function getCEAAddress(ueaAddress, chain, rpcUrl) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const factoryAddress = chain_1.CEA_FACTORY_ADDRESSES[chain];
+        if (!factoryAddress) {
+            throw new Error(`CEAFactory not available on chain ${chain}`);
+        }
+        const viemChain = getViemChain(chain);
+        const client = (0, viem_1.createPublicClient)({
+            chain: viemChain,
+            transport: (0, viem_1.http)(rpcUrl),
+        });
+        const [cea, isDeployed] = yield client.readContract({
+            abi: abi_1.CEA_FACTORY_EVM,
+            address: factoryAddress,
+            functionName: 'getCEAForPushAccount',
+            args: [ueaAddress],
+        });
+        return { cea, isDeployed };
+    });
+}
+/**
+ * Get Push Account (UEA) address for a CEA on a specific chain
+ *
+ * @param ceaAddress - CEA address on external chain
+ * @param chain - External chain where CEA is deployed
+ * @param rpcUrl - Optional custom RPC URL
+ * @returns Push account address on Push Chain
+ * @throws Error if chain doesn't have CEAFactory
+ */
+function getPushAccountForCEA(ceaAddress, chain, rpcUrl) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const factoryAddress = chain_1.CEA_FACTORY_ADDRESSES[chain];
+        if (!factoryAddress) {
+            throw new Error(`CEAFactory not available on chain ${chain}`);
+        }
+        const viemChain = getViemChain(chain);
+        const client = (0, viem_1.createPublicClient)({
+            chain: viemChain,
+            transport: (0, viem_1.http)(rpcUrl),
+        });
+        const uea = yield client.readContract({
+            abi: abi_1.CEA_FACTORY_EVM,
+            address: factoryAddress,
+            functionName: 'getPushAccountForCEA',
+            args: [ceaAddress],
+        });
+        return uea;
+    });
+}
+/**
+ * Check if an address is a CEA on a specific chain
+ *
+ * @param address - Address to check
+ * @param chain - External chain to check
+ * @param rpcUrl - Optional custom RPC URL
+ * @returns True if address is a CEA deployed by the factory
+ * @throws Error if chain doesn't have CEAFactory
+ */
+function isCEA(address, chain, rpcUrl) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const factoryAddress = chain_1.CEA_FACTORY_ADDRESSES[chain];
+        if (!factoryAddress) {
+            throw new Error(`CEAFactory not available on chain ${chain}`);
+        }
+        const viemChain = getViemChain(chain);
+        const client = (0, viem_1.createPublicClient)({
+            chain: viemChain,
+            transport: (0, viem_1.http)(rpcUrl),
+        });
+        return client.readContract({
+            abi: abi_1.CEA_FACTORY_EVM,
+            address: factoryAddress,
+            functionName: 'isCEA',
+            args: [address],
+        });
+    });
+}
+/**
+ * Check if a chain supports CEA operations (EVM only)
+ *
+ * @param chain - Chain to check
+ * @returns True if CEAFactory is available
+ */
+function chainSupportsCEA(chain) {
+    return chain_1.CEA_FACTORY_ADDRESSES[chain] !== undefined;
+}
+/**
+ * Check if a chain supports outbound operations (Route 2).
+ * - For EVM chains: checks CEAFactory availability
+ * - For SVM chains: always true (gateway-based, no CEA needed)
+ *
+ * @param chain - Chain to check
+ * @returns True if outbound transactions are supported
+ */
+function chainSupportsOutbound(chain) {
+    var _a;
+    if (((_a = chain_1.CHAIN_INFO[chain]) === null || _a === void 0 ? void 0 : _a.vm) === enums_1.VM.SVM) {
+        return true; // SVM uses gateway program, not CEA
+    }
+    return chain_1.CEA_FACTORY_ADDRESSES[chain] !== undefined;
+}
+/**
+ * Get CEAFactory address for a chain
+ *
+ * @param chain - Target chain
+ * @returns CEAFactory address or undefined
+ */
+function getCEAFactoryAddress(chain) {
+    return chain_1.CEA_FACTORY_ADDRESSES[chain];
+}
+/**
+ * Get CEA addresses for a UEA across all supported chains
+ *
+ * @param ueaAddress - UEA address on Push Chain
+ * @param rpcUrls - Optional custom RPC URLs per chain
+ * @returns Array of CEA addresses per chain
+ */
+function getAllCEAAddresses(ueaAddress, rpcUrls) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const chains = Object.keys(chain_1.CEA_FACTORY_ADDRESSES);
+        const results = yield Promise.all(chains.map((chain) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            try {
+                const { cea, isDeployed } = yield getCEAAddress(ueaAddress, chain, rpcUrls === null || rpcUrls === void 0 ? void 0 : rpcUrls[chain]);
+                return { chain, cea, isDeployed };
+            }
+            catch (error) {
+                return {
+                    chain,
+                    cea: '0x0000000000000000000000000000000000000000',
+                    isDeployed: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        })));
+        return results;
+    });
+}
+//# sourceMappingURL=cea-utils.js.map

package/src/lib/orchestrator/cea-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cea-utils.js","sourceRoot":"","sources":["../../../../../../packages/core/src/lib/orchestrator/cea-utils.ts"],"names":[],"mappings":"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"}

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

@@ -1,8 +1,9 @@
 import { CHAIN, PUSH_NETWORK } from '../constants/enums';
 import { ConversionQuote, MoveableToken, PayableToken } from '../constants/tokens';
+import { AccountStatus } from './orchestrator.types';
 import { ProgressEvent } from '../progress-hook/progress-hook.types';
 import { UniversalAccount, UniversalSigner } from '../universal/universal.types';
-import { ExecuteParams, UniversalTxResponse } from './orchestrator.types';
+import { ExecuteParams, MultiCall, UniversalExecuteParams, UniversalTxResponse, PreparedUniversalTx, ChainedTransactionBuilder, HopDescriptor, CascadeSegment, CascadedTransactionBuilder } from './orchestrator.types';
 export declare class Orchestrator {
     private readonly universalSigner;
     private pushNetwork;
@@ -11,6 +12,13 @@ export declare class Orchestrator {
     private progressHook?;
     private pushClient;
     private ueaVersionCache?;
+    private accountStatusCache;
+    /**
+     * Per-chain cache for detected gateway version (v0 or v1).
+     * Populated on first successful gateway tx per chain via try-V1-then-V0 fallback.
+     * TODO: Remove this cache + fallback logic once all chains are upgraded to V1.
+     */
+    private gatewayVersionCache;
     constructor(universalSigner: UniversalSigner, pushNetwork: PUSH_NETWORK, rpcUrls?: Partial<Record<CHAIN, string[]>>, printTraces?: boolean, progressHook?: ((progress: ProgressEvent) => void) | undefined);
     /**
      * Read-only accessors for current Orchestrator configuration
@@ -20,9 +28,215 @@ export declare class Orchestrator {
     getPrintTraces(): boolean;
     getProgressHook(): ((progress: ProgressEvent) => void) | undefined;
     /**
-     * Executes an interaction on Push Chain
+     * Fetches account status including UEA deployment state and version info.
+     * Results are cached — pass forceRefresh to bypass cache.
+     */
+    getAccountStatus(options?: {
+        forceRefresh?: boolean;
+    }): Promise<AccountStatus>;
+    /**
+     * Upgrades the UEA to the latest implementation version.
+     * Sends MsgMigrateUEA Cosmos message with EIP-712 signed MigrationPayload.
+     * The UEA contract delegates to the UEAMigration contract to update implementation.
+     */
+    upgradeAccount(options?: {
+        progressHook?: (progress: ProgressEvent) => void;
+    }): Promise<void>;
+    /**
+     * Fetches the latest UEA version from UEAFactory contract.
+     * This is the version of the newest registered implementation — used as minRequiredVersion.
+     * Returns empty string if factory is unavailable.
+     */
+    private fetchLatestUEAVersion;
+    /**
+     * Migrate the CEA contract on an external chain to the latest version.
+     * Sends a MIGRATION_SELECTOR payload via Route 2 to trigger CEA upgrade.
+     *
+     * @param chain - The external chain where the CEA should be migrated
+     * @returns Transaction response
+     */
+    migrateCEA(chain: CHAIN): Promise<UniversalTxResponse>;
+    /**
+     * Executes a transaction with automatic route detection.
+     *
+     * Supports both simple Push Chain transactions and multi-chain routing:
+     * - Route 1 (UOA_TO_PUSH): `to` is a simple address string
+     * - Route 2 (UOA_TO_CEA): `to` is `{ address, chain }` targeting external chain
+     * - Route 3 (CEA_TO_PUSH): `from.chain` specified, targeting Push Chain
+     * - Route 4 (CEA_TO_CEA): `from.chain` specified, targeting external chain
+     *
+     * @param params - ExecuteParams or UniversalExecuteParams
+     * @returns Transaction response
+     */
+    execute(params: ExecuteParams | UniversalExecuteParams): Promise<UniversalTxResponse>;
+    /**
+     * Executes a universal transaction with multi-chain routing support.
+     * Supports 4 routes:
+     * - Route 1: UOA → Push Chain (existing behavior)
+     * - Route 2: UOA → CEA (outbound to external chain)
+     * - Route 3: CEA → Push Chain (inbound from external chain)
+     * - Route 4: CEA → CEA (external chain to external chain via Push)
+     *
+     * @param params - Universal execution parameters with optional chain targets
+     * @returns UniversalTxResponse with chain information
+     */
+    /**
+     * Internal method for multi-chain transaction routing.
+     * Called by execute() when ChainTarget or from.chain is detected.
+     */
+    private executeMultiChain;
+    /**
+     * Prepare a universal transaction without executing it.
+     * Returns a PreparedUniversalTx that can be chained with thenOn() or sent with send().
+     *
+     * @param params - Universal execution parameters
+     * @returns PreparedUniversalTx with chaining capabilities
+     */
+    prepareTransaction(params: UniversalExecuteParams): Promise<PreparedUniversalTx>;
+    /**
+     * Build a HopDescriptor for a prepared transaction.
+     * Resolves CEA addresses, queries gas fees, and builds multicall arrays.
+     *
+     * @param params - Original user params
+     * @param route - Detected route
+     * @param ueaAddress - UEA address
+     * @returns HopDescriptor with all metadata
+     */
+    private buildHopDescriptor;
+    /**
+     * Query outbound gas fee from UniversalCore contract.
+     * Extracted from executeUoaToCea for reuse.
+     *
+     * @param prc20Token - PRC-20 token address
+     * @param gasLimit - Gas limit for the outbound
+     * @returns gasToken address and gasFee amount
+     */
+    queryOutboundGasFee(prc20Token: `0x${string}`, gasLimit: bigint): Promise<{
+        gasToken: `0x${string}`;
+        gasFee: bigint;
+        protocolFee: bigint;
+        nativeValueForGas: bigint;
+        gasPrice: bigint;
+    }>;
+    /**
+     * Classify hops into segments for cascade composition.
+     * Consecutive same-type/same-chain hops are merged.
+     *
+     * @param hops - Array of HopDescriptors from prepared transactions
+     * @returns Array of CascadeSegments
+     */
+    classifyIntoSegments(hops: HopDescriptor[]): CascadeSegment[];
+    /**
+     * Map route to segment type
+     */
+    private getSegmentType;
+    /**
+     * Compose cascade from segments using bottom-to-top nesting.
+     * Processes segments in reverse order, building nested payloads.
+     *
+     * @param segments - Classified segments from classifyIntoSegments()
+     * @param ueaAddress - UEA address
+     * @returns Final MultiCall[] to execute as the initial UEA multicall
+     */
+    composeCascade(segments: CascadeSegment[], ueaAddress: `0x${string}`, ueaBalance?: bigint, ueaNonce?: bigint): MultiCall[];
+    /**
+     * Creates a cascaded transaction builder for nested multi-chain execution.
+     * The cascade composes all hops bottom-to-top into a single Push Chain tx.
+     *
+     * @param preparedTxs - Array of prepared transactions
+     * @returns CascadedTransactionBuilder
+     */
+    createCascadedBuilder(preparedTxs: PreparedUniversalTx[]): CascadedTransactionBuilder;
+    /**
+     * @deprecated Use createCascadedBuilder instead.
+     * Creates a chained transaction builder for sequential multi-chain execution.
+     *
+     * @param transactions - Array of transactions to execute in sequence
+     * @returns ChainedTransactionBuilder
+     */
+    createChainedBuilder(transactions: UniversalExecuteParams[]): ChainedTransactionBuilder;
+    /**
+     * Route 2: Execute outbound transaction from Push Chain to external CEA
+     *
+     * This method builds a multicall that executes on Push Chain (from UEA context):
+     * 1. Approves the gateway to spend PRC-20 tokens (if needed)
+     * 2. Calls sendUniversalTxOutbound on UniversalGatewayPC precompile
+     *
+     * The multicall is executed through the normal execute() flow which handles
+     * fee-locking on the origin chain and signature verification.
+     *
+     * @param params - Universal execution parameters with ChainTarget
+     * @returns UniversalTxResponse
+     */
+    private executeUoaToCea;
+    /**
+     * Route 2 for SVM targets: Outbound from Push Chain to Solana.
+     *
+     * Three cases:
+     * 1. Withdraw SOL: Burn pSOL on Push Chain, recipient gets native SOL
+     * 2. Withdraw SPL: Burn PRC-20 on Push Chain, recipient gets SPL token
+     * 3. Execute (CPI): Burn pSOL + execute CPI on target Solana program
+     *
+     * @param params - Universal execution parameters
+     * @param target - ChainTarget with Solana chain and hex address
+     * @returns UniversalTxResponse
+     */
+    private executeUoaToCeaSvm;
+    /**
+     * Route 3: Execute inbound transaction from CEA to Push Chain
+     *
+     * This route instructs CEA on an external chain to call sendUniversalTxFromCEA,
+     * bridging funds/payloads back to Push Chain.
+     *
+     * Flow:
+     * 1. Build multicall for CEA: [approve Gateway (if ERC20), sendUniversalTxFromCEA]
+     * 2. Execute via Route 2 (UOA → CEA) with PAYLOAD-only (CEA uses its own funds)
+     * 3. CEA executes multicall, Gateway locks funds, relayer mints PRC-20 on Push Chain
+     *
+     * @param params - Universal execution parameters with from.chain specified
+     * @returns UniversalTxResponse
+     */
+    private executeCeaToPush;
+    /**
+     * Route 3 SVM: Execute CEA-to-Push for Solana chains.
+     *
+     * Unlike EVM Route 3 which builds CEA multicalls, SVM Route 3 encodes a
+     * `send_universal_tx_to_uea` instruction as an execute payload targeting
+     * the SVM gateway program (self-call). The drain amount is embedded in
+     * the instruction data, not in the outbound request amount.
+     */
+    private executeCeaToPushSvm;
+    /**
+     * Route 4: Execute CEA to CEA transaction via Push Chain
+     *
+     * @param params - Universal execution parameters with from.chain and to.chain
+     * @returns UniversalTxResponse
+     */
+    private executeCeaToCea;
+    /**
+     * Build payload for a specific route
+     */
+    private buildPayloadForRoute;
+    /**
+     * Convert UniversalExecuteParams to ExecuteParams for backwards compatibility
+     */
+    private toExecuteParams;
+    /**
+     * Get the UniversalGatewayPC address for the current Push network
+     */
+    private getUniversalGatewayPCAddress;
+    /**
+     * Get the native PRC-20 token address on Push Chain for a target external chain.
+     * Maps chains to their native asset representations on Push Chain.
+     *
+     * @param targetChain - The target external chain
+     * @returns PRC-20 token address on Push Chain
+     */
+    private getNativePRC20ForChain;
+    /**
+     * Get CAIP-2 chain namespace for a chain
      */
-    execute(execute: ExecuteParams): Promise<UniversalTxResponse>;
+    private getChainNamespace;
     /**
      * Locks a fee on the origin chain by interacting with the chain's fee-locker contract.
      *
@@ -32,6 +246,59 @@ export declare class Orchestrator {
      */
     private lockFee;
     private _buildUniversalTxRequest;
+    /**
+     * Returns the resolved gateway version for the current origin chain.
+     * Checks the per-chain runtime cache first, then falls back to static config.
+     * TODO: Remove V0 fallback once all chains are upgraded to V1.
+     */
+    private getGatewayVersion;
+    /**
+     * Returns true if the current origin chain uses the V1 gateway (revertRecipient address).
+     */
+    private isV1Gateway;
+    /**
+     * Returns the correct gateway ABI for the given version.
+     */
+    private getGatewayAbiForVersion;
+    /**
+     * Returns the correct gateway ABI based on the origin chain's gateway version.
+     */
+    private getGatewayAbi;
+    /**
+     * Converts a V0 UniversalTxRequest to V1 format.
+     */
+    private toGatewayRequestV1;
+    /**
+     * Converts a V0 UniversalTxRequest to the correct format based on gateway version.
+     */
+    private toGatewayRequest;
+    /**
+     * Converts a V0 UniversalTokenTxRequest to V1 format.
+     */
+    private toGatewayTokenRequestV1;
+    /**
+     * Converts a V0 UniversalTokenTxRequest to the correct format based on gateway version.
+     */
+    private toGatewayTokenRequest;
+    /**
+     * Sends a gateway transaction with V1-first, V0-fallback strategy.
+     *
+     * Strategy:
+     *   1. Try V1 (revertRecipient address format) first.
+     *   2. If V1 fails (contract not yet upgraded), retry with V0 (revertInstruction struct).
+     *   3. Cache the working version per chain so subsequent calls skip the fallback.
+     *
+     * TODO: Remove V0 fallback once all chains are upgraded to V1. After that,
+     *       delete this method and call writeContract directly with V1 ABI.
+     */
+    private sendGatewayTxWithFallback;
+    /**
+     * Sends a gateway token transaction with V1-first, V0-fallback strategy.
+     * Same as sendGatewayTxWithFallback but for UniversalTokenTxRequest (gas token path).
+     *
+     * TODO: Remove V0 fallback once all chains are upgraded to V1.
+     */
+    private sendGatewayTokenTxWithFallback;
     /**
      * Builds the SVM UniversalTxRequest object from an existing EVM-style UniversalTxRequest.
      * This allows reusing the same request shape for both EVM and SVM while only translating
@@ -43,6 +310,7 @@ export declare class Orchestrator {
      * Shape mirrors the request used in `svm-gateway` tests.
      */
     private _buildSvmUniversalTxRequest;
+    private _getSvmProtocolFee;
     private signUniversalPayload;
     /**
      * Sends a custom Cosmos tx to Push Chain (gasless) to execute user intent.
@@ -88,6 +356,83 @@ export declare class Orchestrator {
      *   v_type: u8 (0 = SignedVerification, 1 = UniversalTxVerification)
      */
     private encodeUniversalPayloadSvm;
+    /**
+     * Reconstructs SEND-TX-* progress events from on-chain transaction data.
+     * Used by trackTransaction to replay progress for already-completed transactions.
+     *
+     * @param universalTxResponse - The transformed transaction response
+     * @param universalTxData - Optional UniversalTx data from gRPC query (for cross-chain txs)
+     * @returns Array of ProgressEvent objects to emit
+     */
+    private reconstructProgressEvents;
+    /**
+     * Tracks a transaction by hash on Push Chain and returns UniversalTxResponse.
+     * Reconstructs and replays SEND-TX-* progress events for completed transactions.
+     *
+     * @param txHash - Transaction hash to track (Push Chain tx hash)
+     * @param options - Tracking options (chain, progressHook, waitForCompletion, advanced config)
+     * @returns Promise resolving to UniversalTxResponse with wait() and progressHook() methods
+     */
+    trackTransaction(txHash: string, options?: import('./orchestrator.types').TrackTransactionOptions): Promise<UniversalTxResponse>;
+    /**
+     * Returns the Push Chain enum value for the current network
+     */
+    private getPushChainForNetwork;
+    /**
+     * Compute UniversalTxId for Push Chain originated outbound transactions.
+     * Formula: keccak256("eip155:{pushChainId}:{pushChainTxHash}")
+     *
+     * @param pushChainTxHash - The Push Chain transaction hash
+     * @returns The UniversalTxId (keccak256 hash)
+     */
+    private computeUniversalTxId;
+    /**
+     * Extract universalsubTxId from a Push Chain transaction by fetching Cosmos events.
+     * The universalsubTxId is found in the 'outbound_created' Cosmos event (attribute 'utx_id'),
+     * NOT in the EVM event data.
+     *
+     * @param pushChainTxHash - The Push Chain transaction hash
+     * @returns The universalsubTxId or null if not found
+     */
+    extractUniversalSubTxIdFromTx(pushChainTxHash: string): Promise<string | null>;
+    /**
+     * Extract ALL universalSubTxIds from a Push Chain transaction.
+     * For cascaded transactions, a single Push Chain tx may emit multiple
+     * outbound_created events, each with its own utx_id.
+     *
+     * @param pushChainTxHash - The Push Chain transaction hash
+     * @returns Array of universalSubTxIds (may be empty)
+     */
+    extractAllUniversalSubTxIds(pushChainTxHash: string): Promise<string[]>;
+    /**
+     * Convert CAIP-2 namespace (e.g., "eip155:97") to CHAIN enum
+     *
+     * @param namespace - CAIP-2 chain namespace string
+     * @returns CHAIN enum value or null if not found
+     */
+    private chainFromNamespace;
+    private static readonly OUTBOUND_INITIAL_WAIT_MS;
+    private static readonly OUTBOUND_POLL_INTERVAL_MS;
+    private static readonly OUTBOUND_MAX_TIMEOUT_MS;
+    /**
+     * Wait for outbound transaction to complete and return external chain details.
+     * @internal Used by .wait() for outbound routes - not part of public API.
+     * Uses polling with configurable initial wait, interval, and timeout.
+     *
+     * Default strategy: 30s initial wait, then poll every 5s, 120s total timeout.
+     *
+     * @param pushChainTxHash - The Push Chain transaction hash
+     * @param options - Polling configuration options
+     * @returns External chain tx details
+     * @throws Error on timeout
+     */
+    private waitForOutboundTx;
+    /**
+     * Tracks ALL outbound transactions for a cascade with multiple outbound hops
+     * (e.g., BNB + Solana). Uses V2 API which returns outboundTx[] with per-outbound
+     * status tracking, matching each outbound to the correct hop by destination chain.
+     */
+    private waitForAllOutboundTxsV2;
     /**
      * Computes UEA for given UniversalAccount
      * @dev - This fn calls a view fn of Factory Contract