@pushchain/core 5.1.3 → 5.1.4-alpha.1

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

@@ -1,24 +1,24 @@
 import { CHAIN, PUSH_NETWORK } from '../constants/enums';
 import { ConversionQuote, MoveableToken, PayableToken } from '../constants/tokens';
-import { AccountStatus } from './orchestrator.types';
+import type { AccountStatus, UniversalTxResponse } from './orchestrator.types';
 import { ProgressEvent } from '../progress-hook/progress-hook.types';
-import { UniversalAccount, UniversalSigner } from '../universal/universal.types';
-import { ExecuteParams, MultiCall, UniversalExecuteParams, UniversalTxResponse, PreparedUniversalTx, ChainedTransactionBuilder, HopDescriptor, CascadeSegment, CascadedTransactionBuilder } from './orchestrator.types';
+import { PushClient } from '../push-client/push-client';
+import type { UniversalAccount, UniversalSigner } from '../universal/universal.types';
+import { ExecuteParams, UniversalExecuteParams, PreparedUniversalTx, CascadedTransactionBuilder, RescueFundsParams } from './orchestrator.types';
 export declare class Orchestrator {
     private readonly universalSigner;
     private pushNetwork;
     private readonly rpcUrls;
     private readonly printTraces;
     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;
+    private _pushClient;
+    private _pushClientOptions;
+    get pushClient(): PushClient;
+    accountStatusCache: AccountStatus | null;
+    accountStatusReadyPromise?: Promise<void>;
+    private get ctx();
+    private _getResponseCallbacks;
+    private _getCascadeCallbacks;
     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
@@ -42,12 +42,6 @@ export declare class Orchestrator {
     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.
@@ -57,34 +51,21 @@ export declare class Orchestrator {
      */
     migrateCEA(chain: CHAIN): Promise<UniversalTxResponse>;
     /**
-     * Executes a transaction with automatic route detection.
+     * Rescue stuck funds on a source chain.
+     * When a CEA-to-Push inbound transaction fails, tokens get locked in the
+     * Vault on the source chain. This triggers a manual revert via TSS to
+     * release those funds back to the user.
      *
-     * 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
+     * @param params - RescueFundsParams with universalTxId and prc20 token
      * @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
-     */
+    rescueFunds(params: RescueFundsParams): Promise<UniversalTxResponse>;
     /**
-     * Internal method for multi-chain transaction routing.
-     * Called by execute() when ChainTarget or from.chain is detected.
+     * Executes a transaction with automatic route detection.
+     * Routes 2-4 (multi-chain) delegate to prepareTransaction().send().
+     * Route 1 (Push Chain) dispatches to extracted sub-flow modules.
      */
-    private executeMultiChain;
+    execute(params: ExecuteParams | UniversalExecuteParams): Promise<UniversalTxResponse>;
     /**
      * Prepare a universal transaction without executing it.
      * Returns a PreparedUniversalTx that can be chained with thenOn() or sent with send().
@@ -94,22 +75,15 @@ export declare class Orchestrator {
      */
     prepareTransaction(params: UniversalExecuteParams): Promise<PreparedUniversalTx>;
     /**
-     * Build a HopDescriptor for a prepared transaction.
-     * Resolves CEA addresses, queries gas fees, and builds multicall arrays.
+     * 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 params - Original user params
-     * @param route - Detected route
-     * @param ueaAddress - UEA address
-     * @returns HopDescriptor with all metadata
+     * @param preparedTxs - Array of prepared transactions
+     * @returns CascadedTransactionBuilder
      */
-    private buildHopDescriptor;
+    createCascadedBuilder(preparedTxs: PreparedUniversalTx[]): CascadedTransactionBuilder;
     /**
-     * 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
+     * Queries gas fee for an outbound transaction from the UniversalCore contract.
      */
     queryOutboundGasFee(prc20Token: `0x${string}`, gasLimit: bigint): Promise<{
         gasToken: `0x${string}`;
@@ -119,267 +93,13 @@ export declare class Orchestrator {
         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
-     */
-    private getChainNamespace;
-    /**
-     * Locks a fee on the origin chain by interacting with the chain's fee-locker contract.
-     *
-     * @param amount - Fee amount in USDC (8 Decimals)
-     * @param executionHash - Optional execution payload hash (default: zeroHash)
-     * @returns Transaction hash bytes
-     */
-    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
-     * field encodings (addresses, bytes) to the Solana program format.
-     */
-    private _buildSvmUniversalTxRequestFromReq;
-    /**
-     * Builds the SVM UniversalTxRequest object expected by the Solana gateway program.
-     * Shape mirrors the request used in `svm-gateway` tests.
-     */
-    private _buildSvmUniversalTxRequest;
-    private _getSvmProtocolFee;
-    private signUniversalPayload;
-    /**
-     * Signs a MigrationPayload for UEA upgrade.
-     * EVM: EIP-712 signTypedData. SVM: manual hash + signMessage (same pattern as signUniversalPayload).
-     */
-    private signMigrationPayload;
-    /**
-     * Computes the EIP-712 struct hash for MigrationPayload (used by SVM path).
-     * Mirrors computeExecutionHash but for the MigrationPayload type.
-     */
-    private computeMigrationHash;
-    /**
-     * Sends a custom Cosmos tx to Push Chain (gasless) to execute user intent.
-     */
-    private sendUniversalTx;
-    /**
-     * Sends a EVM trx on Push Chain
-     * @dev - Only to be used from universal signer is on Push chain
-     * @param execute
-     * @returns Cosmos Tx Response for a given Evm Tx
-     */
-    private sendPushTx;
-    /**
-     * Computes the EIP-712 digest hash for the UniversalPayload structure.
-     * This is the message that should be signed by the user's wallet (e.g., Solana signer).
-     *
-     * The resulting hash is equivalent to:
-     * keccak256("\x19\x01" || domainSeparator || structHash)
-     *
-     * @param chainId - EVM chain ID of the destination chain (Push Chain)
-     * @param verifyingContract - Address of the verifying contract (i.e., the user's UEA smart wallet)
-     * @param version - Optional EIP-712 domain version (default: '0.1.0')
-     * @param payload - Execution details encoded into the UniversalPayload struct
-     * @returns keccak256 digest to be signed by the user
-     */
-    private computeExecutionHash;
-    /**
-     * ABI-encodes a UniversalPayload struct to bytes, matching the Solidity layout.
-     * This mirrors abi.encode(UniversalPayload) in the EVM contracts.
-     */
-    private encodeUniversalPayload;
-    /**
-     * Encodes a UniversalPayload into Borsh bytes for the SVM universal gateway.
-     * Layout mirrors Rust `UniversalPayload`:
-     *   to: [u8; 20],
-     *   value: u64,
-     *   data: Vec<u8> (u32 LE len + bytes),
-     *   gas_limit: u64,
-     *   max_fee_per_gas: u64,
-     *   max_priority_fee_per_gas: u64,
-     *   nonce: u64,
-     *   deadline: i64,
-     *   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;
+       * Extracts the first universal sub-tx ID from a Push Chain transaction's Cosmos events.
+       */
+    extractUniversalSubTxIdFromTx(pushChainTxHash: string): Promise<string | null>;
     /**
-     * Detect the transaction route from UniversalTxV2 data.
-     * Used by trackTransaction to infer the route when it's not set by execute().
+     * Extracts all universal sub-tx IDs from a cascaded Push Chain transaction.
      */
-    private detectRouteFromUniversalTxData;
+    extractAllUniversalSubTxIds(pushChainTxHash: string): Promise<string[]>;
     /**
      * Tracks a transaction by hash on Push Chain and returns UniversalTxResponse.
      * Reconstructs and replays SEND-TX-* progress events for completed transactions.
@@ -389,65 +109,6 @@ export declare class Orchestrator {
      * @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
@@ -458,22 +119,8 @@ export declare class Orchestrator {
         address: `0x${string}`;
         deployed: boolean;
     }>;
-    private _buildMulticallPayloadData;
-    private _sendSVMTxWithFunds;
     computeUEAOffchain(): `0x${string}`;
-    /**
-     * @dev - Although as of now nonce var is same in evm & svm so switch conditions does not matter
-     * @param address UEA address
-     * @returns UEA current nonce
-     */
-    private getUEANonce;
     getUOA(): UniversalAccount;
-    private waitForLockerFeeConfirmation;
-    /**
-     * Internal helper: fetches the full origin-chain transaction for a given hash,
-     * used only for progress-hook context (EVM or Solana).
-     */
-    private fetchOriginChainTransactionForProgress;
     /**
      * Quotes exact-output on Uniswap V3 for EVM origin chains using QuoterV2.
      * Returns the minimum required input (amountIn) to receive the target amountOut.
@@ -482,49 +129,4 @@ export declare class Orchestrator {
         from: PayableToken | undefined;
         to: MoveableToken | undefined;
     }): Promise<ConversionQuote>;
-    private ensureErc20Allowance;
-    /**
-     * Ensures we're on Sepolia, returns EVM client and gateway address.
-     */
-    private getOriginGatewayContext;
-    /**
-     * Computes UEA and fetches its nonce if deployed; returns 0 otherwise.
-     */
-    private getUeaNonceForExecution;
-    /**
-     * Returns UEA deployment status and nonce (0 if not deployed).
-     */
-    private getUeaStatusAndNonce;
-    /**
-     * For sendFunds, we will call internally the sendTxWithFunds.
-     */
-    private buildGatewayPayloadAndGas;
-    /********************************** HELPER FUNCTIONS **************************************************/
-    /**
-     * Transforms a TransactionReceipt to UniversalTxReceipt format
-     */
-    private transformToUniversalTxReceipt;
-    /**
-     * Transforms a TxResponse to the new UniversalTxResponse format
-     */
-    private transformToUniversalTxResponse;
-    private bigintReplacer;
-    /**
-     * Checks if the given chain belongs to the Push Chain ecosystem.
-     * Used to differentiate logic for Push-native interactions vs external chains.
-     *
-     * @param chain - The chain identifier (e.g., PUSH_MAINNET, PUSH_TESTNET_DONUT)
-     * @returns True if the chain is a Push chain, false otherwise.
-     */
-    private isPushChain;
-    private validateMainnetConnection;
-    private printLog;
-    private executeProgressHook;
-    private getSvmGatewayLogIndexFromTx;
-    private queryUniversalTxStatusFromGatewayTx;
-    private waitForEvmConfirmationsWithCountdown;
-    private waitForSvmConfirmationsWithCountdown;
-    private fetchUEAVersion;
-    private calculateGasAmountFromAmountOutMinETH;
-    private calculateNativeAmountForDeposit;
 }