@pushchain/core 5.1.4-alpha.0 → 5.1.4-alpha.10

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

@@ -31,6 +31,8 @@ const payload_builder_1 = require("./payload-builder");
 const uea_manager_1 = require("./uea-manager");
 const gas_calculator_1 = require("./gas-calculator");
 const chain_1 = require("../../constants/chain");
+const utils_1 = require("../../utils");
+const price_fetch_1 = require("../../price-fetch/price-fetch");
 const route_detector_1 = require("../route-detector");
 const cea_utils_1 = require("../cea-utils");
 const payload_builders_1 = require("../payload-builders");
@@ -255,11 +257,7 @@ function executeUoaToCea(ctx, params, executeFn) {
             ctx.pushClient.getBalance(ueaAddress),
         ]);
         const isUEADeployed = isNativePushEOA || ueaCode !== undefined;
-        if (!isUEADeployed) {
-            throw new Error('UEA is not deployed. Please send an inbound transaction to Push Chain first ' +
-                '(e.g. sendTransaction with value) to deploy your Universal Execution Account before using outbound transfers.');
-        }
-        const ueaNonce = isNativePushEOA ? BigInt(0) : yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress);
+        const ueaNonce = (!isUEADeployed || isNativePushEOA) ? BigInt(0) : yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress);
         // Build the multicall that will execute ON Push Chain from UEA context
         // This includes: 1) approve PRC-20 (if needed), 2) call sendUniversalTxOutbound
         const pushChainMulticalls = [];
@@ -267,41 +265,62 @@ function executeUoaToCea(ctx, params, executeFn) {
         let gasFee = BigInt(0);
         let nativeValueForGas = BigInt(0);
         let gasToken = selectors_1.ZERO_ADDRESS;
+        let universalCoreAddress;
         if (prc20Token !== selectors_1.ZERO_ADDRESS) {
             try {
                 const result = yield (0, gas_calculator_1.queryOutboundGasFee)(ctx, prc20Token, outboundReq.gasLimit);
                 gasFee = result.gasFee;
                 gasToken = result.gasToken;
                 nativeValueForGas = result.nativeValueForGas;
+                universalCoreAddress = result.universalCoreAddress;
                 (0, context_1.printLog)(ctx, `executeUoaToCea — queried gas fee: ${gasFee.toString()}, gasToken: ${gasToken}, nativeValueForGas: ${nativeValueForGas.toString()}`);
             }
             catch (err) {
                 throw new Error(`Failed to query outbound gas fee: ${err}`);
             }
         }
-        // Adjust nativeValueForGas: the 1Mx multiplier from queryOutboundGasFee produces
-        // a value far too low for the actual WPC/gasToken swap price. Set it to 200 UPC
-        // (capped by balance) — enough for the swap, but avoids draining thin pools.
-        // The contract's swapAndBurnGas does exactOutputSingle and refunds excess PC.
+        // Balance-aware adjustment: MAXIMIZE nativeValueForGas within available balance.
+        // The contract's swapAndBurnGas does exactOutputSingle and refunds excess PC,
+        // so overshooting within balance is safe. Undershooting causes the swap to revert.
         const EVM_NATIVE_VALUE_TARGET = BigInt(200e18); // 200 UPC
         const EVM_GAS_RESERVE = BigInt(3e18); // 3 UPC for tx overhead
-        // Reuse ueaBalance fetched earlier (line 383) — no tx sent between, balance is stable
-        const currentBalance = ueaBalance;
+        const ROUTE2_MINIMUM_DEPOSIT_USD = utils_1.Utils.helpers.parseUnits('10', 8); // $10
+        // Determine effective balance for the adjustment.
+        // For deployed UEAs: use real balance.
+        // For fresh wallets: predict the post-fee-locking balance by querying the same
+        // Uniswap V3 quoter the chain uses (pETH → WPC swap in execute_inbound_gas.go).
+        let effectiveBalance = ueaBalance;
+        if (!isUEADeployed && effectiveBalance <= EVM_GAS_RESERVE) {
+            // Calculate the ETH amount lockFee will send (same formula as lockFee)
+            const ethPrice = yield new price_fetch_1.PriceFetch(ctx.rpcUrls).getPrice(signerChain);
+            const nativeAmountETH = ethPrice > BigInt(0)
+                ? (ROUTE2_MINIMUM_DEPOSIT_USD * BigInt(1e18) + (ethPrice - BigInt(1))) / ethPrice + BigInt(1)
+                : BigInt(0);
+            if (nativeAmountETH > BigInt(0)) {
+                // Query the real swap quote: how much WPC (UPC) for this pETH amount?
+                const originPrc20 = (0, helpers_1.getNativePRC20ForChain)(signerChain, ctx.pushNetwork);
+                const predictedUPC = yield (0, gas_calculator_1.estimateDepositFromLockedNative)(ctx, nativeAmountETH, originPrc20);
+                if (predictedUPC > BigInt(0)) {
+                    // 10% safety margin for slippage between quote and actual execution
+                    effectiveBalance = (predictedUPC * BigInt(90)) / BigInt(100);
+                    (0, context_1.printLog)(ctx, `executeUoaToCea — fresh wallet: Uniswap quote predicts ${predictedUPC.toString()} UPC ` +
+                        `from ${nativeAmountETH.toString()} wei pETH, using ${effectiveBalance.toString()} (90%)`);
+                }
+            }
+        }
         let adjustedValue;
-        if (currentBalance > EVM_NATIVE_VALUE_TARGET + EVM_GAS_RESERVE) {
-            // Enough balance: use 200 UPC target
+        if (effectiveBalance > EVM_NATIVE_VALUE_TARGET + EVM_GAS_RESERVE) {
             adjustedValue = EVM_NATIVE_VALUE_TARGET;
         }
-        else if (currentBalance > EVM_GAS_RESERVE) {
-            // Low balance: use what's available minus reserve
-            adjustedValue = currentBalance - EVM_GAS_RESERVE;
+        else if (effectiveBalance > EVM_GAS_RESERVE) {
+            adjustedValue = effectiveBalance - EVM_GAS_RESERVE;
         }
         else {
-            // Very low balance: use original query value as-is
             adjustedValue = nativeValueForGas;
         }
         if (adjustedValue !== nativeValueForGas) {
-            (0, context_1.printLog)(ctx, `executeUoaToCea — adjusting nativeValueForGas from ${nativeValueForGas.toString()} to ${adjustedValue.toString()} (UEA balance: ${currentBalance.toString()})`);
+            (0, context_1.printLog)(ctx, `executeUoaToCea — adjusting nativeValueForGas from ${nativeValueForGas.toString()} ` +
+                `to ${adjustedValue.toString()} (effective balance: ${effectiveBalance.toString()})`);
             nativeValueForGas = adjustedValue;
         }
         // Build outbound multicalls (approve burn + sendUniversalTxOutbound with native value)
@@ -345,17 +364,11 @@ function executeUoaToCea(ctx, params, executeFn) {
         // This handles fee-locking on origin chain and executes the multicall from UEA context
         // Sum native values from multicall entries for proper fee calculation
         const multicallNativeValue = pushChainMulticalls.reduce((sum, mc) => { var _a; return sum + ((_a = mc.value) !== null && _a !== void 0 ? _a : BigInt(0)); }, BigInt(0));
-        const executeParams = {
-            to: ueaAddress, // multicall executes from UEA
-            value: multicallNativeValue, // ensures correct requiredFunds calculation
-            data: pushChainMulticalls, // array triggers multicall mode
-            _ueaStatus: {
+        const executeParams = Object.assign({ to: ueaAddress, value: multicallNativeValue, data: pushChainMulticalls, _ueaStatus: {
                 isDeployed: isUEADeployed,
                 nonce: ueaNonce,
                 balance: ueaBalance,
-            },
-            _skipFeeLocking: true, // outbound executes on Push Chain, no external fee locking
-        };
+            }, _skipFeeLocking: isUEADeployed }, (!isUEADeployed ? { _minimumDepositUsd: ROUTE2_MINIMUM_DEPOSIT_USD } : {}));
         const response = yield executeFn(executeParams);
         // Add chain info to response
         response.chain = targetChain;
@@ -463,14 +476,11 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
             isUEADeployed = ueaCode !== undefined;
             ueaBalance = balance;
         }
-        if (!isUEADeployed) {
-            throw new Error('UEA is not deployed. Please send an inbound transaction to Push Chain first ' +
-                '(e.g. sendTransaction with value) to deploy your Universal Execution Account before using outbound transfers.');
-        }
-        const ueaNonce = isNativePushEOASvm ? BigInt(0) : yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress);
+        const ueaNonce = (!isUEADeployed || isNativePushEOASvm) ? BigInt(0) : yield (0, uea_manager_1.getUEANonce)(ctx, ueaAddress);
         // --- Query gas fee (identical to EVM path) ---
         let gasFee = BigInt(0);
         let gasToken = selectors_1.ZERO_ADDRESS;
+        let universalCoreAddress;
         let nativeValueForGas = BigInt(0);
         if (prc20Token !== selectors_1.ZERO_ADDRESS) {
             const gasLimit = outboundReq.gasLimit;
@@ -479,6 +489,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
                 gasFee = result.gasFee;
                 gasToken = result.gasToken;
                 nativeValueForGas = result.nativeValueForGas;
+                universalCoreAddress = result.universalCoreAddress;
                 // When user omits gasLimit (sent as 0), the contract computes fees using its internal
                 // baseGasLimitByChainNamespace. But the relay reads the stored gasLimit=0 from the
                 // on-chain outbound record and uses it as the Solana compute budget — 0 CU means the
@@ -494,30 +505,17 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
                 throw new Error(`Failed to query outbound gas fee: ${err}`);
             }
         }
-        // Adjust nativeValueForGas: the 1Mx multiplier from queryOutboundGasFee produces
-        // a value far too low for the actual WPC/gasToken swap price. Set it to 200 UPC
-        // (capped by balance) — enough for the swap, but avoids draining thin pools.
-        // The contract's swapAndBurnGas does exactOutputSingle and refunds excess PC.
-        const SVM_NATIVE_VALUE_TARGET = BigInt(200e18); // 200 UPC
-        const SVM_GAS_RESERVE = BigInt(3e18); // 3 UPC for tx overhead
-        // Reuse ueaBalance from earlier fetch — no tx sent between, balance is stable
-        const currentBalance = ueaBalance;
-        let adjustedValue;
-        if (currentBalance > SVM_NATIVE_VALUE_TARGET + SVM_GAS_RESERVE) {
-            // Enough balance: use 200 UPC target
-            adjustedValue = SVM_NATIVE_VALUE_TARGET;
-        }
-        else if (currentBalance > SVM_GAS_RESERVE) {
-            // Low balance: use what's available minus reserve
-            adjustedValue = currentBalance - SVM_GAS_RESERVE;
-        }
-        else {
-            // Very low balance: use original query value as-is
-            adjustedValue = nativeValueForGas;
-        }
-        if (adjustedValue !== nativeValueForGas) {
-            (0, context_1.printLog)(ctx, `executeUoaToCeaSvm — adjusting nativeValueForGas from ${nativeValueForGas.toString()} to ${adjustedValue.toString()} (UEA balance: ${currentBalance.toString()})`);
-            nativeValueForGas = adjustedValue;
+        // Estimate the actual WPC needed for the swap using on-chain pool price.
+        // The static 1Mx multiplier from queryOutboundGasFee doesn't reflect the real
+        // WPC/gasToken exchange rate. estimateNativeValueForSwap reads the Uniswap V3
+        // pool's slot0, computes the true cost, and adds a 2x buffer.
+        // Excess msg.value is refunded by the contract's swapAndBurnGas.
+        if (universalCoreAddress && gasFee > BigInt(0)) {
+            const estimated = yield (0, gas_calculator_1.estimateNativeValueForSwap)(ctx, universalCoreAddress, gasToken, gasFee, ueaBalance);
+            if (estimated > nativeValueForGas) {
+                (0, context_1.printLog)(ctx, `executeUoaToCeaSvm — adjusting nativeValueForGas from ${nativeValueForGas.toString()} to ${estimated.toString()} (pool-price estimate, UEA balance: ${ueaBalance.toString()})`);
+                nativeValueForGas = estimated;
+            }
         }
         // --- Build Push Chain multicalls (approve + sendUniversalTxOutbound) ---
         // Reuse the same builder as EVM — this part is identical
@@ -542,7 +540,7 @@ function executeUoaToCeaSvm(ctx, params, target, executeFn) {
                 nonce: ueaNonce,
                 balance: ueaBalance,
             },
-            _skipFeeLocking: true, // outbound executes on Push Chain, no external fee locking
+            _skipFeeLocking: isUEADeployed, // skip fee-locking only if UEA is already deployed
         };
         const response = yield executeFn(executeParams);
         // Add chain info to response
@@ -588,10 +586,8 @@ function executeCeaToPush(ctx, params, executeFn) {
         // 4. Get CEA address on source chain
         const { cea: ceaAddress, isDeployed: ceaDeployed } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, sourceChain, (_b = ctx.rpcUrls[sourceChain]) === null || _b === void 0 ? void 0 : _b[0]);
         (0, context_1.printLog)(ctx, `executeCeaToPush — sourceChain: ${sourceChain}, CEA: ${ceaAddress}, deployed: ${ceaDeployed}`);
-        if (!ceaDeployed) {
-            throw new Error(`CEA not deployed on ${sourceChain}. ` +
-                `Deploy CEA first using Route 2 (UOA -> CEA) before using Route 3.`);
-        }
+        // CEA auto-deploys on-chain: Vault.finalizeUniversalTx calls CEAFactory.deployCEA()
+        // if CEA doesn't exist yet. No SDK-side blocking needed.
         // 5. Get UniversalGateway address on source chain
         const gatewayAddress = chain_1.UNIVERSAL_GATEWAY_ADDRESSES[sourceChain];
         if (!gatewayAddress) {
@@ -628,7 +624,7 @@ function executeCeaToPush(ctx, params, executeFn) {
         // external chain), but that approach is racy: the balance can change between the SDK
         // query and relay execution, causing sendUniversalTxToUEA to revert with
         // InsufficientBalance. Pre-existing CEA funds remain parked and can be swept separately.
-        let bridgeAmount = amount;
+        const bridgeAmount = amount;
         // Note: CEA contract may reject amount=0 in sendUniversalTxToUEA.
         // Keeping bridgeAmount as-is (0) for payload-only to test precompile behavior.
         // For ERC20 tokens, add approve call for the bridge amount
@@ -954,7 +950,7 @@ function executeCeaToCea(ctx, params, executeFn) {
         // CEA -> CEA requires chaining Route 3 (CEA -> Push) and Route 2 (Push -> CEA)
         // This is a complex flow that requires coordination
         throw new Error('CEA -> CEA transactions are not yet fully implemented. ' +
-            'Use prepareTransaction().thenOn() to chain Route 3 -> Route 2 manually.');
+            'Use prepareTransaction() and executeTransactions() to chain Route 3 -> Route 2 manually.');
     });
 }
 // ---------------------------------------------------------------------------
@@ -1120,6 +1116,8 @@ function buildPayloadForRoute(ctx, params, route, nonce) {
                     return { payload: svmPayload, gatewayRequest: outboundReq };
                 }
                 const { cea: ceaAddress } = yield (0, cea_utils_1.getCEAAddress)(ueaAddress, sourceChain, (_l = ctx.rpcUrls[sourceChain]) === null || _l === void 0 ? void 0 : _l[0]);
+                // CEA auto-deploys on-chain: Vault.finalizeUniversalTx calls CEAFactory.deployCEA()
+                // if CEA doesn't exist yet. No SDK-side blocking needed.
                 const gatewayAddr = chain_1.UNIVERSAL_GATEWAY_ADDRESSES[sourceChain];
                 if (!gatewayAddr) {
                     throw new Error(`No UniversalGateway address configured for chain ${sourceChain}`);

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

@@ -4,7 +4,7 @@ import type { AccountStatus, UniversalTxResponse } from './orchestrator.types';
 import { ProgressEvent } from '../progress-hook/progress-hook.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';
+import { ExecuteParams, UniversalExecuteParams, PreparedUniversalTx, CascadedTxResponse, RescueFundsParams } from './orchestrator.types';
 export declare class Orchestrator {
     private readonly universalSigner;
     private pushNetwork;
@@ -79,9 +79,11 @@ export declare class Orchestrator {
      * The cascade composes all hops bottom-to-top into a single Push Chain tx.
      *
      * @param preparedTxs - Array of prepared transactions
-     * @returns CascadedTransactionBuilder
+     * @returns Object with send() method
      */
-    createCascadedBuilder(preparedTxs: PreparedUniversalTx[]): CascadedTransactionBuilder;
+    createCascadedBuilder(preparedTxs: PreparedUniversalTx[]): {
+        send: () => Promise<CascadedTxResponse>;
+    };
     /**
      * Queries gas fee for an outbound transaction from the UniversalCore contract.
      */

package/src/lib/orchestrator/orchestrator.js

@@ -129,7 +129,7 @@ class Orchestrator {
      */
     execute(params) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e;
+            var _a, _b, _c, _d;
             // Lazy UEA upgrade check
             try {
                 if (!this.accountStatusCache || !this.accountStatusCache.uea.loaded) {
@@ -166,16 +166,6 @@ class Orchestrator {
             try {
                 const rcb = () => this._getResponseCallbacks();
                 if (execute.funds) {
-                    const hasData = execute.data && execute.data !== '0x';
-                    const isSVM = ((_e = chain_1.CHAIN_INFO[this.ctx.universalSigner.account.chain]) === null || _e === void 0 ? void 0 : _e.vm) === enums_1.VM.SVM;
-                    // SVM two-phase: bridge funds first, then execute payload separately
-                    // (Push Chain node doesn't support FUNDS_AND_PAYLOAD payload decoding for SVM yet)
-                    if (hasData && isSVM) {
-                        const fundsOnly = Object.assign(Object.assign({}, execute), { data: undefined });
-                        yield (0, internals_1.executeFundsOnly)(this.ctx, fundsOnly, eventBuffer, rcb);
-                        const dataOnly = Object.assign(Object.assign({}, execute), { funds: undefined });
-                        return yield (0, internals_1.executeStandardPayload)(this.ctx, dataOnly, eventBuffer, rcb);
-                    }
                     return !hasData
                         ? yield (0, internals_1.executeFundsOnly)(this.ctx, execute, eventBuffer, rcb)
                         : yield (0, internals_1.executeFundsWithPayload)(this.ctx, execute, eventBuffer, rcb);
@@ -221,7 +211,7 @@ class Orchestrator {
      * The cascade composes all hops bottom-to-top into a single Push Chain tx.
      *
      * @param preparedTxs - Array of prepared transactions
-     * @returns CascadedTransactionBuilder
+     * @returns Object with send() method
      */
     createCascadedBuilder(preparedTxs) {
         return (0, internals_1.createCascadedBuilder)(this.ctx, preparedTxs, this._getCascadeCallbacks());

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

@@ -106,6 +106,14 @@ export type ExecuteParams = {
      * @internal
      */
     _skipFeeLocking?: boolean;
+    /**
+     * Internal: Minimum fee-locking deposit in USD (8 decimals).
+     * Overrides the default $1 floor when the caller needs a larger deposit
+     * (e.g., Route 2 needs enough UPC for the outbound swap).
+     * Still capped at $10 by lockFee.
+     * @internal
+     */
+    _minimumDepositUsd?: bigint;
 };
 /**
  * New Universal Transaction Receipt interface with prioritized field ordering
@@ -465,10 +473,6 @@ export interface PreparedUniversalTx {
     deadline: bigint;
     /** Internal hop descriptor for cascade nesting @internal */
     _hop: HopDescriptor;
-    /** Chain additional transactions after this one (cascade) */
-    thenOn: (nextTx: PreparedUniversalTx) => CascadedTransactionBuilder;
-    /** Execute this prepared transaction */
-    send: () => Promise<UniversalTxResponse>;
 }
 /**
  * @deprecated Use CascadedTxResponse instead.
@@ -485,17 +489,6 @@ export interface MultiChainTxResponse {
         status: 'pending' | 'confirmed' | 'failed';
     }[];
 }
-/**
- * Builder for composing cascaded (nested) multi-chain transactions.
- * Each call to thenOn() adds another hop to the cascade.
- * send() composes all hops bottom-to-top and executes a single Push Chain tx.
- */
-export interface CascadedTransactionBuilder {
-    /** Add another hop to the cascade */
-    thenOn: (nextTx: PreparedUniversalTx) => CascadedTransactionBuilder;
-    /** Compose all hops bottom-to-top and execute the single initial tx */
-    send: () => Promise<CascadedTxResponse>;
-}
 /**
  * Response for cascaded multi-chain transactions.
  * Contains the initial tx and tracking info for all hops.

package/src/lib/progress-hook/progress-hook.js

@@ -35,7 +35,7 @@ const RAW_HOOKS = {
     [progress_hook_types_1.PROGRESS_HOOK.SEND_TX_03_01]: () => ({
         id: progress_hook_types_1.PROGRESS_HOOK.SEND_TX_03_01,
         title: 'Resolving UEA',
-        message: 'Resolving Execution Account (UEA) – computing address, checking deployment status and balance',
+        message: 'Resolving Executor Account (UEA) – computing address, checking deployment status and balance',
         response: null,
         level: 'INFO',
     }),

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

@@ -6,7 +6,7 @@ import { TypedData, TypedDataDomain } from 'viem';
 import { ProgressEvent } from '../progress-hook/progress-hook.types';
 import type { AccountStatus } from '../orchestrator/orchestrator.types';
 import { MoveableToken, PayableToken, ConversionQuote, MoveableTokenAccessor, PayableTokenAccessor } from '../constants/tokens';
-import type { PreparedUniversalTx, CascadedTransactionBuilder } from '../orchestrator/orchestrator.types';
+import type { PreparedUniversalTx, CascadedTxResponse } from '../orchestrator/orchestrator.types';
 /**
  * @class PushChain
  *
@@ -71,15 +71,14 @@ export declare class PushChain {
         sendTransaction: Orchestrator['execute'];
         /**
          * Prepare a universal transaction without executing it.
-         * Returns a PreparedUniversalTx that can be chained with thenOn() or sent.
+         * Returns a PreparedUniversalTx that can be passed to executeTransactions.
          */
         prepareTransaction: Orchestrator['prepareTransaction'];
         /**
-         * Execute multiple transactions in sequence across chains.
-         * Accepts PreparedUniversalTx (from prepareTransaction) and returns
-         * a CascadedTransactionBuilder that supports .thenOn() for chaining.
+         * Execute one or more prepared transactions as a cascade across chains.
+         * Accepts an array of PreparedUniversalTx (from prepareTransaction).
          */
-        executeTransactions: (firstTx: PreparedUniversalTx) => CascadedTransactionBuilder;
+        executeTransactions: (txs: PreparedUniversalTx[]) => Promise<CascadedTxResponse>;
         /**
          * Tracks a transaction by hash on Push Chain
          */

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

@@ -87,12 +87,12 @@ class PushChain {
                 }
                 return orchestrator.prepareTransaction.bind(orchestrator)(params);
             },
-            executeTransactions: (firstTx) => {
+            executeTransactions: (txs) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 if (this.isReadMode) {
                     throw new Error('Read only mode cannot call executeTransactions function');
                 }
-                return orchestrator.createCascadedBuilder([firstTx]);
-            },
+                return orchestrator.createCascadedBuilder(txs).send();
+            }),
             trackTransaction: (txHash, options) => {
                 return orchestrator.trackTransaction.bind(orchestrator)(txHash, options);
             },
@@ -400,6 +400,7 @@ class PushChain {
             // Stored on instance so consumers can await it if needed: await client.accountStatusReady
             const ACCOUNT_STATUS_TIMEOUT = 30000;
             instance.accountStatusReady = Promise.race([
+                // eslint-disable-next-line @typescript-eslint/no-empty-function
                 instance.getAccountStatus().then(() => { }),
                 new Promise((_, reject) => setTimeout(() => reject(new Error('Account status fetch timed out')), ACCOUNT_STATUS_TIMEOUT)),
             ]).catch(() => {

package/src/lib/universal/account/account.d.ts

@@ -69,29 +69,37 @@ export declare function convertExecutorToOrigin(executorAddress: string, options
     _internal?: boolean;
 }): Promise<OriginAccountInfo>;
 /**
- * Derive the executor account (UEA or CEA) for a given origin account.
+ * Derive the executor account (UEA or CEA) for a given account.
  *
- * @param account - CAIP-10 formatted address string (e.g., "eip155:11155111:0xABC...")
- * @param options.chain - Target chain for CEA derivation. If omitted, derives UEA on Push Chain.
+ * - If account is on an external chain (Ethereum, Solana, etc.):
+ *   Computes the UEA on Push Chain via the factory contract's computeUEA.
+ *   If options.chain is an external chain, further derives the CEA on that chain.
+ *
+ * - If account is on Push Chain:
+ *   Returns the address as-is (it's already a UEA or Push EOA).
+ *   If options.chain is an external chain, derives the CEA on that chain.
+ *
+ * @param account - UniversalAccount with chain and address.
+ * @param options.chain - Target external chain for CEA derivation. If omitted, returns UEA.
  * @param options.skipNetworkCheck - If true, skip deployment check and return deployed: false.
  * @returns The derived executor account address and deployment status.
  */
-export declare function deriveExecutorAccount(account: string, options?: {
+export declare function deriveExecutorAccount(account: UniversalAccount, options?: {
     chain?: CHAIN;
     skipNetworkCheck?: boolean;
 }): Promise<DerivedExecutorAccount>;
 /**
  * Resolve the controller (origin) accounts for a given executor address.
  *
- * Given a UEA or CEA address (as CAIP-10), resolves the full controller chain
+ * Given a UEA or CEA plain address, resolves the full controller chain
  * back to the origin account.
  *
- * @param account - CAIP-10 formatted address string of the executor account
- * @param options.chain - Supplementary chain context (chain info is in CAIP-10)
+ * @param address - Plain address string of the executor account (e.g., "0xABC...")
+ * @param options.chain - Chain context. If external chain, address is treated as CEA on that chain. If omitted or Push chain, address is treated as UEA on Push Chain.
  * @param options.skipNetworkCheck - If true, skip existence checks, set exists: false
  * @returns Resolved accounts in the controller chain
  */
-export declare function resolveControllerAccount(account: string, options?: {
+export declare function resolveControllerAccount(address: string, options?: {
     chain?: CHAIN;
     skipNetworkCheck?: boolean;
 }): Promise<ResolvedControllerAccounts>;