@pushchain/core 5.1.3 → 5.1.4-alpha.1

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

@@ -360,6 +360,17 @@ export interface UniversalOutboundTxRequest {
     /** Address to receive funds on revert */
     revertRecipient: `0x${string}`;
 }
+/**
+ * Parameters for rescuing stuck funds on a source chain.
+ * Used when a CEA-to-Push inbound transaction fails and tokens are
+ * locked in the Vault on the source chain.
+ */
+export interface RescueFundsParams {
+    /** The universalTxId of the failed inbound transaction (bytes32 hash, 0x-prefixed) */
+    universalTxId: `0x${string}`;
+    /** PRC-20 token address on Push Chain whose source-chain counterpart is locked */
+    prc20: `0x${string}`;
+}
 /**
  * Internal metadata attached to each prepared transaction.
  * Carries all information needed to nest this hop into a cascade.
@@ -459,16 +470,6 @@ export interface PreparedUniversalTx {
     /** Execute this prepared transaction */
     send: () => Promise<UniversalTxResponse>;
 }
-/**
- * @deprecated Use CascadedTransactionBuilder instead.
- * Kept for backward compatibility.
- */
-export interface ChainedTransactionBuilder {
-    /** Add another transaction to the chain */
-    thenOn: (nextTx: UniversalExecuteParams) => ChainedTransactionBuilder;
-    /** Execute all chained transactions */
-    send: () => Promise<MultiChainTxResponse>;
-}
 /**
  * @deprecated Use CascadedTxResponse instead.
  * Kept for backward compatibility.

package/src/lib/orchestrator/payload-builders.js

@@ -20,7 +20,10 @@ exports.encodeSvmExecutePayload = encodeSvmExecutePayload;
 exports.encodeSvmCeaToUeaPayload = encodeSvmCeaToUeaPayload;
 const viem_1 = require("viem");
 const push_chain_1 = require("../push-chain/push-chain");
-const abi_1 = require("../constants/abi");
+const cea_evm_1 = require("../constants/abi/cea.evm");
+const erc20_evm_1 = require("../constants/abi/erc20.evm");
+const universalGatewayV0_evm_1 = require("../constants/abi/universalGatewayV0.evm");
+const universalGatewayPC_evm_1 = require("../constants/abi/universalGatewayPC.evm");
 const selectors_1 = require("../constants/selectors");
 const chain_1 = require("../constants/chain");
 const enums_1 = require("../constants/enums");
@@ -66,7 +69,7 @@ function buildExecuteMulticall({ execute, ueaAddress, logger, }) {
         // - When execute.data is an array (explicit multicall), user handles fund transfers in their calls
         if (!isNative && !isArrayMulticall) {
             const erc20Transfer = (0, viem_1.encodeFunctionData)({
-                abi: abi_1.ERC20_EVM,
+                abi: erc20_evm_1.ERC20_EVM,
                 functionName: 'transfer',
                 args: [execute.to, (_q = execute.funds) === null || _q === void 0 ? void 0 : _q.amount],
             });
@@ -219,12 +222,24 @@ function buildSingleCeaCall(target, value, data) {
  * @returns Array of multicall operations
  */
 function buildApproveAndInteract(tokenAddress, spender, amount, interactCall) {
+    // Reset allowance to 0 first to handle non-standard ERC-20 tokens (e.g. USDT)
+    // that revert if approve is called with non-zero value when current allowance is non-zero.
+    const approveZeroData = (0, viem_1.encodeFunctionData)({
+        abi: erc20_evm_1.ERC20_EVM,
+        functionName: 'approve',
+        args: [spender, BigInt(0)],
+    });
     const approveData = (0, viem_1.encodeFunctionData)({
-        abi: abi_1.ERC20_EVM,
+        abi: erc20_evm_1.ERC20_EVM,
         functionName: 'approve',
         args: [spender, amount],
     });
     return [
+        {
+            to: tokenAddress,
+            value: BigInt(0),
+            data: approveZeroData,
+        },
         {
             to: tokenAddress,
             value: BigInt(0),
@@ -248,7 +263,7 @@ function buildApproveAndInteract(tokenAddress, spender, amount, interactCall) {
  */
 function buildSendUniversalTxFromCEA(gatewayAddress, recipient, token, amount, payload, revertRecipient, signatureData = '0x', nativeValue = BigInt(0)) {
     const calldata = (0, viem_1.encodeFunctionData)({
-        abi: abi_1.UNIVERSAL_GATEWAY_V0,
+        abi: universalGatewayV0_evm_1.UNIVERSAL_GATEWAY_V0,
         functionName: 'sendUniversalTxFromCEA',
         args: [
             {
@@ -286,7 +301,7 @@ function buildSendUniversalTxFromCEA(gatewayAddress, recipient, token, amount, p
  */
 function buildSendUniversalTxToUEA(ceaAddress, token, amount, payload, revertRecipient) {
     const calldata = (0, viem_1.encodeFunctionData)({
-        abi: abi_1.CEA_EVM,
+        abi: cea_evm_1.CEA_EVM,
         functionName: 'sendUniversalTxToUEA',
         args: [token, amount, payload, revertRecipient],
     });
@@ -344,7 +359,7 @@ function buildNativeTransfer(to, value) {
  */
 function buildErc20Transfer(tokenAddress, to, amount) {
     const transferData = (0, viem_1.encodeFunctionData)({
-        abi: abi_1.ERC20_EVM,
+        abi: erc20_evm_1.ERC20_EVM,
         functionName: 'transfer',
         args: [to, amount],
     });
@@ -406,13 +421,24 @@ function buildOutboundApprovalAndCall(opts) {
     const { prc20Token, burnAmount, gasFee, gatewayPcAddress, outboundRequest } = opts;
     const multicalls = [];
     // ERC20 approve for burn amount (contract calls transferFrom for PRC20 burn)
+    // Reset to 0 first for USDT-style tokens that revert on non-zero to non-zero approve.
     if (burnAmount > BigInt(0) &&
         prc20Token.toLowerCase() !== selectors_1.ZERO_ADDRESS.toLowerCase()) {
+        const approveZeroData = (0, viem_1.encodeFunctionData)({
+            abi: erc20_evm_1.ERC20_EVM,
+            functionName: 'approve',
+            args: [gatewayPcAddress, BigInt(0)],
+        });
         const approveData = (0, viem_1.encodeFunctionData)({
-            abi: abi_1.ERC20_EVM,
+            abi: erc20_evm_1.ERC20_EVM,
             functionName: 'approve',
             args: [gatewayPcAddress, burnAmount],
         });
+        multicalls.push({
+            to: prc20Token,
+            value: BigInt(0),
+            data: approveZeroData,
+        });
         multicalls.push({
             to: prc20Token,
             value: BigInt(0),
@@ -421,7 +447,7 @@ function buildOutboundApprovalAndCall(opts) {
     }
     // Gas fee + protocol fee paid as native msg.value (no ERC20 approve for gas)
     const outboundCallData = (0, viem_1.encodeFunctionData)({
-        abi: abi_1.UNIVERSAL_GATEWAY_PC,
+        abi: universalGatewayPC_evm_1.UNIVERSAL_GATEWAY_PC,
         functionName: 'sendUniversalTxOutbound',
         args: [outboundRequest],
     });

package/src/lib/price-fetch/price-fetch.js

@@ -5,36 +5,46 @@ const tslib_1 = require("tslib");
 const enums_1 = require("../constants/enums");
 const chain_1 = require("../constants/chain");
 const evm_client_1 = require("../vm-client/evm-client");
-const abi_1 = require("../constants/abi");
+const feeLocker_evm_1 = require("../constants/abi/feeLocker.evm");
+const feeLocker_json_1 = tslib_1.__importDefault(require("../constants/abi/feeLocker.json"));
 const anchor_1 = require("@coral-xyz/anchor");
 const web3_js_1 = require("@solana/web3.js");
 const web3_js_2 = require("@solana/web3.js");
 const anchor_2 = require("@coral-xyz/anchor");
+// Module-level price cache — survives across PriceFetch instances.
+// Chainlink feeds update every 1-2h or on 0.5% price move; 30s TTL is safe.
+const PRICE_CACHE_TTL_MS = 30000;
+const priceCache = new Map();
 class PriceFetch {
     constructor(rpcUrls = {}) {
         this.rpcUrls = rpcUrls;
     }
     getPrice(chain) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const cached = priceCache.get(chain);
+            if (cached && Date.now() < cached.expiry) {
+                return cached.price;
+            }
             const rpcUrls = this.rpcUrls[chain] || chain_1.CHAIN_INFO[chain].defaultRPC;
             const vm = chain_1.CHAIN_INFO[chain].vm;
             const { lockerContract } = chain_1.CHAIN_INFO[chain];
             if (!lockerContract) {
                 throw new Error(`Locker contract not configured for chain: ${chain}`);
             }
+            let price;
             switch (vm) {
                 case enums_1.VM.EVM: {
                     const evmClient = new evm_client_1.EvmClient({ rpcUrls });
                     const result = yield evmClient.readContract({
-                        abi: abi_1.FEE_LOCKER_EVM,
+                        abi: feeLocker_evm_1.FEE_LOCKER_EVM,
                         address: lockerContract,
                         functionName: 'getEthUsdPrice',
                     });
                     // getEthUsdPrice returns price scaled to 1e18 and the chainlink feed decimals.
                     // Downstream lockFee math expects the price in 8 decimals, so scale down from 1e18 to 1e8.
                     const [price1e18] = result;
-                    const price = price1e18 / BigInt(Math.pow(10, 10)); // 1e18 -> 1e8
-                    return price;
+                    price = price1e18 / BigInt(Math.pow(10, 10)); // 1e18 -> 1e8
+                    break;
                 }
                 case enums_1.VM.SVM: {
                     const PRICE_ACCOUNT = new web3_js_2.PublicKey('7UVimffxr9ow1uXYxsr4LHAcV58mLzhmwaeKvJ1pjLiE');
@@ -43,7 +53,7 @@ class PriceFetch {
                         publicKey: new web3_js_2.PublicKey('EfQYRThwBu4MsU7Lf3D2e68tCtdwfYj6f66ot1e2HNrq'),
                         // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     }, { commitment: 'confirmed' });
-                    const program = new anchor_1.Program(abi_1.FEE_LOCKER_SVM, provider);
+                    const program = new anchor_1.Program(feeLocker_json_1.default, provider);
                     const result = yield program.methods['getSolPrice']()
                         .accounts({
                         priceUpdate: PRICE_ACCOUNT,
@@ -53,13 +63,15 @@ class PriceFetch {
                         throw new Error('Invalid price data returned');
                     }
                     // Exponent on this function is always NEGATIVE
-                    const price = result.price.toNumber();
-                    return BigInt(price);
+                    price = BigInt(result.price.toNumber());
+                    break;
                 }
                 default: {
                     throw new Error(`Unsupported VM ${vm}`);
                 }
             }
+            priceCache.set(chain, { price, expiry: Date.now() + PRICE_CACHE_TTL_MS });
+            return price;
         });
     }
 }

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

@@ -91,6 +91,12 @@ export declare class PushChain {
          * @param chain - The external chain where the CEA should be migrated
          */
         migrateCEA: Orchestrator['migrateCEA'];
+        /**
+         * Rescue stuck funds on a source chain.
+         * When a CEA-to-Push inbound tx fails, tokens get locked in the Vault.
+         * This triggers a manual revert via TSS to release those funds.
+         */
+        rescueFunds: Orchestrator['rescueFunds'];
         /**
          * Signs an arbitrary message
          */

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

@@ -9,7 +9,7 @@ const chain_1 = require("../constants/chain");
 const orchestrator_1 = require("../orchestrator/orchestrator");
 const signer_1 = require("../universal/signer");
 const utils_1 = require("../utils");
-const anchor_1 = require("@coral-xyz/anchor");
+const bs58_1 = require("../internal/bs58");
 const viem_1 = require("viem");
 const evm_client_1 = require("../vm-client/evm-client");
 const tokens_1 = require("../constants/tokens");
@@ -102,6 +102,12 @@ class PushChain {
                 }
                 return orchestrator.migrateCEA.bind(orchestrator)(chain);
             },
+            rescueFunds: (params) => {
+                if (this.isReadMode) {
+                    throw new Error('Read only mode cannot call rescueFunds function');
+                }
+                return orchestrator.rescueFunds.bind(orchestrator)(params);
+            },
             signMessage: (data) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 if (this.isReadMode) {
                     throw new Error('Read only mode cannot call signMessage function');
@@ -112,7 +118,7 @@ class PushChain {
                     return (0, viem_1.bytesToHex)(sigBytes);
                 }
                 else if (chain_1.CHAIN_INFO[chain].vm === enums_1.VM.SVM) {
-                    return anchor_1.utils.bytes.bs58.encode(sigBytes);
+                    return bs58_1.bs58.encode(Buffer.from(sigBytes));
                 }
                 return (0, viem_1.bytesToHex)(sigBytes);
             }),
@@ -399,6 +405,8 @@ class PushChain {
             ]).catch(() => {
                 // Silently ignore — lazy check in execute() will retry if needed
             });
+            // Let execute() await the background fetch instead of re-fetching
+            orchestrator.accountStatusReadyPromise = instance.accountStatusReady;
             return instance;
         });
     }

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

@@ -7,6 +7,8 @@ import { QueryGetUniversalTxResponseV2 } from '../generated/uexecutor/v2/query';
 import { EvmClient } from '../vm-client/evm-client';
 import { PushClientOptions } from './push-client.types';
 export declare class PushClient extends EvmClient {
+    /** Gas limit for Cosmos transactions on Push Chain */
+    private static readonly COSMOS_GAS_LIMIT;
     pushChainInfo: {
         chainId: string;
         vm: import("../constants/enums").VM;
@@ -33,6 +35,7 @@ export declare class PushClient extends EvmClient {
         pushToUsdcDenominator: bigint;
     };
     private readonly ephemeralKey;
+    private readonly ephemeralAccount;
     private currentRpcIndex;
     constructor(clientOptions: PushClientOptions);
     /**

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

@@ -5,7 +5,6 @@ const tslib_1 = require("tslib");
 const viem_1 = require("viem");
 const tx_1 = require("../generated/v1/tx");
 const tx_2 = require("cosmjs-types/cosmos/tx/v1beta1/tx");
-const protobufjs_1 = require("protobufjs");
 const proto_signing_1 = require("@cosmjs/proto-signing");
 const stargate_1 = require("@cosmjs/stargate");
 const query_1 = require("../generated/uexecutor/v1/query");
@@ -33,6 +32,7 @@ class PushClient extends evm_client_1.EvmClient {
             this.pushChainInfo = chain_1.PUSH_CHAIN_INFO[enums_1.CHAIN.PUSH_LOCALNET];
         }
         this.ephemeralKey = (0, accounts_1.generatePrivateKey)();
+        this.ephemeralAccount = (0, accounts_1.privateKeyToAccount)(this.ephemeralKey);
     }
     /**
      * Executes an operation with automatic fallback to next RPC endpoint on failure.
@@ -110,10 +110,9 @@ class PushClient extends evm_client_1.EvmClient {
     }
     // --- Tx Signer ---
     getSignerAddress() {
-        const account = (0, accounts_1.privateKeyToAccount)(this.ephemeralKey);
         return {
-            evmAddress: account.address,
-            cosmosAddress: (0, encoding_1.toBech32)(this.pushChainInfo.prefix, (0, viem_1.hexToBytes)(account.address)),
+            evmAddress: this.ephemeralAccount.address,
+            cosmosAddress: (0, encoding_1.toBech32)(this.pushChainInfo.prefix, (0, viem_1.hexToBytes)(this.ephemeralAccount.address)),
         };
     }
     /**
@@ -122,10 +121,8 @@ class PushClient extends evm_client_1.EvmClient {
      */
     signCosmosTx(txBody) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            const account = (0, accounts_1.privateKeyToAccount)(this.ephemeralKey);
-            const sender = (0, encoding_1.toBech32)(this.pushChainInfo.prefix, (0, viem_1.hexToBytes)(account.address));
+            const sender = (0, encoding_1.toBech32)(this.pushChainInfo.prefix, (0, viem_1.hexToBytes)(this.ephemeralAccount.address));
             return this.executeWithRpcFallback((rpcUrl) => tslib_1.__awaiter(this, void 0, void 0, function* () {
-                // 🔍 Get on-chain account info
                 const tmClient = yield tendermint_rpc_1.Tendermint34Client.connect(rpcUrl);
                 const status = yield tmClient.status();
                 const chainId = status.nodeInfo.network;
@@ -136,26 +133,32 @@ class PushClient extends evm_client_1.EvmClient {
                     baseAccount = auth_1.BaseAccount.decode(accountResp.value);
                 }
                 catch (err) {
-                    // Ignore
+                    // Account may not exist on-chain yet; default to sequence=0 / accountNumber=0
+                    console.warn(`[PushClient:signCosmosTx] Account lookup failed for ${sender}, defaulting to sequence=0:`, err);
                 }
                 // 📦 Encode pubkey
-                const uncompressedPubKey = (0, viem_1.hexToBytes)(account.publicKey);
+                const uncompressedPubKey = (0, viem_1.hexToBytes)(this.ephemeralAccount.publicKey);
                 const compressedPubKey = crypto_1.Secp256k1.compressPubkey(uncompressedPubKey);
+                // Manual protobuf encode: field 1 (tag=10), length-delimited bytes
+                const keyLen = compressedPubKey.length;
+                const pubkeyValue = new Uint8Array(2 + keyLen);
+                pubkeyValue[0] = 10; // field 1, wire type 2 (length-delimited)
+                pubkeyValue[1] = keyLen;
+                pubkeyValue.set(compressedPubKey, 2);
                 const pubkeyEncoded = {
                     typeUrl: '/cosmos.evm.crypto.v1.ethsecp256k1.PubKey',
-                    value: protobufjs_1.Writer.create().uint32(10).bytes(compressedPubKey).finish(),
+                    value: pubkeyValue,
                 };
                 const authInfoBytes = (0, proto_signing_1.makeAuthInfoBytes)([
                     {
                         pubkey: pubkeyEncoded,
                         sequence: baseAccount ? Number(baseAccount.sequence) : 0,
                     },
-                ], [], 100000000000, // gas
-                undefined, undefined);
+                ], [], PushClient.COSMOS_GAS_LIMIT, undefined, undefined);
                 const txBodyBytes = tx_2.TxBody.encode(txBody).finish();
                 const signDoc = (0, proto_signing_1.makeSignDoc)(txBodyBytes, authInfoBytes, chainId, baseAccount ? Number(baseAccount.accountNumber) : 0);
                 const digest = (0, viem_1.keccak256)(tx_2.SignDoc.encode(signDoc).finish());
-                const signature = yield account.sign({ hash: digest });
+                const signature = yield this.ephemeralAccount.sign({ hash: digest });
                 return tx_2.TxRaw.fromPartial({
                     bodyBytes: txBodyBytes,
                     authInfoBytes,
@@ -168,8 +171,7 @@ class PushClient extends evm_client_1.EvmClient {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             return this.executeWithRpcFallback((rpcUrl) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 const client = yield stargate_1.StargateClient.connect(rpcUrl);
-                const result = yield client.broadcastTx(tx_2.TxRaw.encode(txRaw).finish());
-                return result;
+                return client.broadcastTx(tx_2.TxRaw.encode(txRaw).finish());
             }), 'broadcastCosmosTx');
         });
     }
@@ -184,8 +186,7 @@ class PushClient extends evm_client_1.EvmClient {
                 const rpc = (0, stargate_1.createProtobufRpcClient)(queryClient);
                 const request = query_1.QueryGetUniversalTxRequest.fromPartial({ id });
                 const responseBytes = yield rpc.request('uexecutor.v1.Query', 'GetUniversalTx', query_1.QueryGetUniversalTxRequest.encode(request).finish());
-                const response = query_1.QueryGetUniversalTxResponse.decode(responseBytes);
-                return response;
+                return query_1.QueryGetUniversalTxResponse.decode(responseBytes);
             }), 'getUniversalTxById');
         });
     }
@@ -196,24 +197,12 @@ class PushClient extends evm_client_1.EvmClient {
     getUniversalTxByIdV2(id) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             return this.executeWithRpcFallback((rpcUrl) => tslib_1.__awaiter(this, void 0, void 0, function* () {
-                var _a, _b, _c;
-                console.log(`[PushClient:getUniversalTxByIdV2] Querying v2 API | ID: ${id} | RPC: ${rpcUrl}`);
-                const t0 = Date.now();
                 const tmClient = yield tendermint_rpc_1.Tendermint34Client.connect(rpcUrl);
                 const queryClient = new stargate_1.QueryClient(tmClient);
                 const rpc = (0, stargate_1.createProtobufRpcClient)(queryClient);
                 const request = query_2.QueryGetUniversalTxRequestV2.fromPartial({ id });
                 const responseBytes = yield rpc.request('uexecutor.v2.Query', 'GetUniversalTx', query_2.QueryGetUniversalTxRequestV2.encode(request).finish());
-                const response = query_2.QueryGetUniversalTxResponseV2.decode(responseBytes);
-                const utx = response === null || response === void 0 ? void 0 : response.universalTx;
-                console.log(`[PushClient:getUniversalTxByIdV2] v2 response in ${Date.now() - t0}ms | universalTx exists: ${!!utx} | status: ${utx === null || utx === void 0 ? void 0 : utx.universalStatus} | outboundTx count: ${(_b = (_a = utx === null || utx === void 0 ? void 0 : utx.outboundTx) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0}`);
-                if ((_c = utx === null || utx === void 0 ? void 0 : utx.outboundTx) === null || _c === void 0 ? void 0 : _c.length) {
-                    utx.outboundTx.forEach((ob, i) => {
-                        var _a;
-                        console.log(`[PushClient:getUniversalTxByIdV2]   outbound[${i}]: id=${ob.id} | outboundStatus=${ob.outboundStatus} | observedTx.txHash=${((_a = ob.observedTx) === null || _a === void 0 ? void 0 : _a.txHash) || 'EMPTY'} | dest=${ob.destinationChain} | recipient=${ob.recipient}`);
-                    });
-                }
-                return response;
+                return query_2.QueryGetUniversalTxResponseV2.decode(responseBytes);
             }), 'getUniversalTxByIdV2');
         });
     }
@@ -227,7 +216,6 @@ class PushClient extends evm_client_1.EvmClient {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             return this.executeWithRpcFallback((rpcUrl) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 const client = yield stargate_1.StargateClient.connect(rpcUrl);
-                // Raw string query—must be one string, not a KV array:
                 const query = `ethereum_tx.ethereumTxHash='${txHash}'`;
                 const results = yield client.searchTx(query);
                 // Convert bigint values to strings in the results. This is done to avoid JSON.stringify()
@@ -243,4 +231,6 @@ class PushClient extends evm_client_1.EvmClient {
     }
 }
 exports.PushClient = PushClient;
+/** Gas limit for Cosmos transactions on Push Chain */
+PushClient.COSMOS_GAS_LIMIT = 100000000000;
 //# sourceMappingURL=push-client.js.map

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

@@ -1,5 +1,5 @@
-import { CHAIN } from '../../constants/enums';
-import { ExecutorAccountInfo, OriginAccountInfo, UniversalAccount } from '../universal.types';
+import { CHAIN, PUSH_NETWORK } from '../../constants/enums';
+import { DerivedExecutorAccount, ExecutorAccountInfo, OriginAccountInfo, ResolvedControllerAccounts, UniversalAccount } from '../universal.types';
 /**
  * Creates a `UniversalAccount` object from an address and chain options.
  * Alternative to createUniversalAccount with a different parameter structure.
@@ -51,28 +51,47 @@ export declare function toChainAgnostic(address: string, options: {
  * // → { chain: CHAIN.ETHEREUM_SEPOLIA, address: '0xabc...' }
  */
 export declare function fromChainAgnostic(caip: string): UniversalAccount;
+/**
+ * @deprecated Use `deriveExecutorAccount()` instead, which accepts a CAIP-10
+ *   string and uses `options.chain` to control UEA vs CEA derivation.
+ */
 export declare function convertOriginToExecutor(account: UniversalAccount, options?: {
     chain?: CHAIN;
     onlyCompute?: boolean;
 }): Promise<ExecutorAccountInfo>;
+export declare function convertExecutorToOriginAccount(ueaAddress: `0x${string}`, options?: {
+    network?: PUSH_NETWORK;
+}): Promise<OriginAccountInfo>;
+export declare function convertExecutorToOrigin(executorAddress: string, options?: {
+    chain?: CHAIN;
+    network?: PUSH_NETWORK;
+    /** @internal Skip deprecation warning for SDK-internal calls */
+    _internal?: boolean;
+}): Promise<OriginAccountInfo>;
 /**
- * Convert Executor to Origin Account
+ * Derive the executor account (UEA or CEA) for a given origin account.
  *
- * Given a UEA (executor) address on Push Chain, returns the mapped origin
- * account and an existence flag.
- *
- * @deprecated Use `convertExecutorToOrigin()` instead, which supports both
- *   UEA and CEA lookups via the optional `options.chain` parameter.
+ * @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.
+ * @param options.skipNetworkCheck - If true, skip deployment check and return deployed: false.
+ * @returns The derived executor account address and deployment status.
  */
-export declare function convertExecutorToOriginAccount(ueaAddress: `0x${string}`): Promise<OriginAccountInfo>;
+export declare function deriveExecutorAccount(account: string, options?: {
+    chain?: CHAIN;
+    skipNetworkCheck?: boolean;
+}): Promise<DerivedExecutorAccount>;
 /**
- * Convert Executor to Origin Account (with optional chain context)
+ * Resolve the controller (origin) accounts for a given executor address.
+ *
+ * Given a UEA or CEA address (as CAIP-10), resolves the full controller chain
+ * back to the origin account.
  *
- * - Without `chain`: treats the address as a UEA on Push Chain and returns
- *   the mapped origin account (same as convertExecutorToOriginAccount).
- * - With `chain`: treats the address as a CEA on the specified external chain,
- *   looks up the corresponding PushAccount (UEA) on Push Chain, and returns it.
+ * @param account - CAIP-10 formatted address string of the executor account
+ * @param options.chain - Supplementary chain context (chain info is in CAIP-10)
+ * @param options.skipNetworkCheck - If true, skip existence checks, set exists: false
+ * @returns Resolved accounts in the controller chain
  */
-export declare function convertExecutorToOrigin(executorAddress: string, options?: {
+export declare function resolveControllerAccount(account: string, options?: {
     chain?: CHAIN;
-}): Promise<OriginAccountInfo>;
+    skipNetworkCheck?: boolean;
+}): Promise<ResolvedControllerAccounts>;