@pushchain/core 5.1.3 → 5.1.4-alpha.1

package/src/lib/orchestrator/internals/gas-calculator.js

@@ -0,0 +1,424 @@
+"use strict";
+/**
+ * Gas fee queries, native amount calculations, ERC-20 allowance,
+ * and Uniswap V3 quoting — extracted from Orchestrator.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureErc20Allowance = ensureErc20Allowance;
+exports.queryOutboundGasFee = queryOutboundGasFee;
+exports.estimateNativeValueForSwap = estimateNativeValueForSwap;
+exports.queryRescueGasFee = queryRescueGasFee;
+exports.calculateNativeAmountForDeposit = calculateNativeAmountForDeposit;
+exports.calculateGasAmountFromAmountOutMinETH = calculateGasAmountFromAmountOutMinETH;
+const tslib_1 = require("tslib");
+const web3_js_1 = require("@solana/web3.js");
+const viem_1 = require("viem");
+const abi_1 = require("../../constants/abi");
+const chain_1 = require("../../constants/chain");
+const enums_1 = require("../../constants/enums");
+const tokens_1 = require("../../constants/tokens");
+const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
+const price_fetch_1 = require("../../price-fetch/price-fetch");
+const utils_1 = require("../../utils");
+const svm_client_1 = require("../../vm-client/svm-client");
+const context_1 = require("./context");
+const helpers_1 = require("./helpers");
+/** Buffer multiplier for nativeValueForGas. Excess is refunded by swapAndBurnGas to the UEA. */
+const GAS_FEE_BUFFER_MULTIPLIER = BigInt(1000000);
+// Minimal ABIs for Uniswap V3 pool price estimation
+const UNISWAP_V3_POOL_SLOT0_ABI = [
+    {
+        type: 'function',
+        name: 'slot0',
+        inputs: [],
+        outputs: [
+            { name: 'sqrtPriceX96', type: 'uint160', internalType: 'uint160' },
+            { name: 'tick', type: 'int24', internalType: 'int24' },
+            { name: 'observationIndex', type: 'uint16', internalType: 'uint16' },
+            { name: 'observationCardinality', type: 'uint16', internalType: 'uint16' },
+            { name: 'observationCardinalityNext', type: 'uint16', internalType: 'uint16' },
+            { name: 'feeProtocol', type: 'uint8', internalType: 'uint8' },
+            { name: 'unlocked', type: 'bool', internalType: 'bool' },
+        ],
+        stateMutability: 'view',
+    },
+];
+const UNISWAP_V3_FACTORY_ABI = [
+    {
+        type: 'function',
+        name: 'getPool',
+        inputs: [
+            { name: 'tokenA', type: 'address', internalType: 'address' },
+            { name: 'tokenB', type: 'address', internalType: 'address' },
+            { name: 'fee', type: 'uint24', internalType: 'uint24' },
+        ],
+        outputs: [{ name: 'pool', type: 'address', internalType: 'address' }],
+        stateMutability: 'view',
+    },
+];
+const UNIVERSAL_CORE_SWAP_HELPERS_ABI = [
+    { type: 'function', name: 'WPC', inputs: [], outputs: [{ name: '', type: 'address', internalType: 'address' }], stateMutability: 'view' },
+    { type: 'function', name: 'uniswapV3Factory', inputs: [], outputs: [{ name: '', type: 'address', internalType: 'address' }], stateMutability: 'view' },
+    { type: 'function', name: 'defaultFeeTier', inputs: [{ name: '', type: 'address', internalType: 'address' }], outputs: [{ name: '', type: 'uint24', internalType: 'uint24' }], stateMutability: 'view' },
+];
+const ZERO_ADDR = '0x0000000000000000000000000000000000000000';
+// ============================================================================
+// ERC-20 Allowance
+// ============================================================================
+function ensureErc20Allowance(ctx, evmClient, tokenAddress, spender, requiredAmount) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const chain = ctx.universalSigner.account.chain;
+        const owner = ctx.universalSigner.account.address;
+        const currentAllowance = yield evmClient.readContract({
+            abi: abi_1.ERC20_EVM,
+            address: tokenAddress,
+            functionName: 'allowance',
+            args: [owner, spender],
+        });
+        if (currentAllowance >= requiredAmount)
+            return;
+        if (currentAllowance > BigInt(0)) {
+            (0, context_1.printLog)(ctx, `Resetting existing allowance from ${currentAllowance.toString()} to 0 for spender ${spender}`);
+            const resetTxHash = yield evmClient.writeContract({
+                abi: abi_1.ERC20_EVM,
+                address: tokenAddress,
+                functionName: 'approve',
+                args: [spender, BigInt(0)],
+                signer: ctx.universalSigner,
+            });
+            yield evmClient.waitForConfirmations({
+                txHash: resetTxHash,
+                confirmations: 1,
+                timeoutMs: chain_1.CHAIN_INFO[chain].timeout,
+            });
+        }
+        const setTxHash = yield evmClient.writeContract({
+            abi: abi_1.ERC20_EVM,
+            address: tokenAddress,
+            functionName: 'approve',
+            args: [spender, requiredAmount],
+            signer: ctx.universalSigner,
+        });
+        yield evmClient.waitForConfirmations({
+            txHash: setTxHash,
+            confirmations: 1,
+            timeoutMs: chain_1.CHAIN_INFO[chain].timeout,
+        });
+        try {
+            const updated = yield evmClient.readContract({
+                abi: abi_1.ERC20_EVM,
+                address: tokenAddress,
+                functionName: 'allowance',
+                args: [owner, spender],
+            });
+            if (updated < requiredAmount) {
+                (0, context_1.printLog)(ctx, 'Warning: allowance not updated yet; proceeding');
+            }
+        }
+        catch (_a) {
+            // ignore
+        }
+    });
+}
+// ============================================================================
+// Outbound Gas Fee Query
+// ============================================================================
+function queryOutboundGasFee(ctx, prc20Token, gasLimit) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const gatewayPcAddress = (0, helpers_1.getUniversalGatewayPCAddress)();
+        const pushChain = (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork);
+        const rpcUrl = ((_b = (_a = chain_1.CHAIN_INFO[pushChain]) === null || _a === void 0 ? void 0 : _a.defaultRPC) === null || _b === void 0 ? void 0 : _b[0]) || 'unknown';
+        (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 1] inputs: gateway=${gatewayPcAddress}, prc20Token=${prc20Token}, gasLimit=${gasLimit}, rpcUrl=${rpcUrl}`);
+        let universalCoreAddress;
+        try {
+            universalCoreAddress = yield ctx.pushClient.readContract({
+                address: gatewayPcAddress,
+                abi: abi_1.UNIVERSAL_GATEWAY_PC,
+                functionName: 'UNIVERSAL_CORE',
+                args: [],
+            });
+            (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 2] UNIVERSAL_CORE resolved to: ${universalCoreAddress}`);
+        }
+        catch (err) {
+            (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 2] FAILED to read UNIVERSAL_CORE: ${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
+        const callData = (0, viem_1.encodeFunctionData)({
+            abi: abi_1.UNIVERSAL_CORE_EVM,
+            functionName: 'getOutboundTxGasAndFees',
+            args: [prc20Token, gasLimit],
+        });
+        (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 3] calling getOutboundTxGasAndFees on ${universalCoreAddress}`);
+        (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 3] eth_call: {"method":"eth_call","params":[{"to":"${universalCoreAddress}","data":"${callData}"},"latest"]}`);
+        let gasToken;
+        let gasFee;
+        let protocolFee;
+        let gasPrice = BigInt(0);
+        try {
+            const result = yield ctx.pushClient.readContract({
+                address: universalCoreAddress,
+                abi: abi_1.UNIVERSAL_CORE_EVM,
+                functionName: 'getOutboundTxGasAndFees',
+                args: [prc20Token, gasLimit],
+            });
+            gasToken = result[0];
+            gasFee = result[1];
+            protocolFee = result[2];
+            gasPrice = result[3];
+            (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 4] success: gasToken=${gasToken}, gasFee=${gasFee}, protocolFee=${protocolFee}, gasPrice=${gasPrice}`);
+        }
+        catch (err) {
+            (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 3] FAILED: ${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
+        const nativeValueForGas = protocolFee + gasFee * GAS_FEE_BUFFER_MULTIPLIER;
+        (0, context_1.printLog)(ctx, `queryOutboundGasFee — [step 5] using 1000000x buffer: nativeValueForGas=${nativeValueForGas}`);
+        return { gasToken, gasFee, protocolFee, nativeValueForGas, gasPrice, universalCoreAddress };
+    });
+}
+// ============================================================================
+// Uniswap V3 Pool Price Estimation
+// ============================================================================
+/**
+ * Estimate the native WPC amount needed to swap for `gasFee` of `gasToken`
+ * by reading the Uniswap V3 pool price on Push Chain.
+ * Returns the estimated amount with a 2x safety buffer (excess is refunded by the contract).
+ * Falls back to a percentage of accountBalance if any on-chain query fails.
+ */
+function estimateNativeValueForSwap(ctx, universalCoreAddress, gasToken, gasFee, accountBalance) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const SWAP_BUFFER = BigInt(2); // 2x safety buffer; excess is refunded by swapAndBurnGas
+        const BALANCE_FALLBACK_DIVISOR = BigInt(10); // 10% of balance as fallback
+        const GAS_RESERVE = BigInt(3e18); // 3 UPC reserve for tx overhead
+        try {
+            // Read WPC, factory, and defaultFeeTier in parallel
+            const [wpcAddress, factoryAddress, feeTier] = yield Promise.all([
+                ctx.pushClient.readContract({
+                    address: universalCoreAddress,
+                    abi: UNIVERSAL_CORE_SWAP_HELPERS_ABI,
+                    functionName: 'WPC',
+                    args: [],
+                }),
+                ctx.pushClient.readContract({
+                    address: universalCoreAddress,
+                    abi: UNIVERSAL_CORE_SWAP_HELPERS_ABI,
+                    functionName: 'uniswapV3Factory',
+                    args: [],
+                }),
+                ctx.pushClient.readContract({
+                    address: universalCoreAddress,
+                    abi: UNIVERSAL_CORE_SWAP_HELPERS_ABI,
+                    functionName: 'defaultFeeTier',
+                    args: [gasToken],
+                }),
+            ]);
+            if (!feeTier) {
+                (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — no fee tier for gasToken, using balance fallback`);
+                return balanceFallback(accountBalance, BALANCE_FALLBACK_DIVISOR, GAS_RESERVE);
+            }
+            // Get pool address from factory
+            const poolAddress = yield ctx.pushClient.readContract({
+                address: factoryAddress,
+                abi: UNISWAP_V3_FACTORY_ABI,
+                functionName: 'getPool',
+                args: [wpcAddress, gasToken, feeTier],
+            });
+            if (poolAddress === ZERO_ADDR) {
+                (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — pool not found, using balance fallback`);
+                return balanceFallback(accountBalance, BALANCE_FALLBACK_DIVISOR, GAS_RESERVE);
+            }
+            // Read slot0 for current price
+            const slot0 = yield ctx.pushClient.readContract({
+                address: poolAddress,
+                abi: UNISWAP_V3_POOL_SLOT0_ABI,
+                functionName: 'slot0',
+                args: [],
+            });
+            const sqrtPriceX96 = slot0[0];
+            if (!sqrtPriceX96 || sqrtPriceX96 === BigInt(0)) {
+                (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — pool not initialized, using balance fallback`);
+                return balanceFallback(accountBalance, BALANCE_FALLBACK_DIVISOR, GAS_RESERVE);
+            }
+            // price (token1/token0 in raw units) = (sqrtPriceX96)² / 2¹⁹²
+            const Q192 = BigInt(1) << BigInt(192);
+            const priceNum = sqrtPriceX96 * sqrtPriceX96; // sqrtPrice² in Q192
+            // Uniswap V3 sorts tokens: token0 < token1 by address
+            const isGasTokenToken0 = gasToken.toLowerCase() < wpcAddress.toLowerCase();
+            let wpcNeeded;
+            if (isGasTokenToken0) {
+                // price = WPC_per_gasToken → wpcNeeded = gasFee * price
+                wpcNeeded = (gasFee * priceNum) / Q192;
+            }
+            else {
+                // price = gasToken_per_WPC → wpcNeeded = gasFee / price
+                wpcNeeded = (gasFee * Q192) / priceNum;
+            }
+            const result = wpcNeeded * SWAP_BUFFER;
+            (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — pool=${poolAddress}, sqrtPriceX96=${sqrtPriceX96}, ` +
+                `wpcNeeded=${wpcNeeded}, withBuffer(2x)=${result}`);
+            // Cap at (balance - reserve)
+            if (accountBalance > result + GAS_RESERVE) {
+                return result;
+            }
+            else if (accountBalance > GAS_RESERVE) {
+                return accountBalance - GAS_RESERVE;
+            }
+            return result; // let caller decide if balance is too low
+        }
+        catch (err) {
+            (0, context_1.printLog)(ctx, `estimateNativeValueForSwap — failed: ${err instanceof Error ? err.message : String(err)}, using balance fallback`);
+            return balanceFallback(accountBalance, BALANCE_FALLBACK_DIVISOR, GAS_RESERVE);
+        }
+    });
+}
+function balanceFallback(balance, divisor, reserve) {
+    const fraction = balance / divisor;
+    if (balance > fraction + reserve)
+        return fraction;
+    if (balance > reserve)
+        return balance - reserve;
+    return fraction;
+}
+// ============================================================================
+// Rescue Gas Fee Query
+// ============================================================================
+function queryRescueGasFee(ctx, prc20Token) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const gatewayPcAddress = (0, helpers_1.getUniversalGatewayPCAddress)();
+        (0, context_1.printLog)(ctx, `queryRescueGasFee — inputs: gateway=${gatewayPcAddress}, prc20Token=${prc20Token}`);
+        let universalCoreAddress;
+        try {
+            universalCoreAddress = yield ctx.pushClient.readContract({
+                address: gatewayPcAddress,
+                abi: abi_1.UNIVERSAL_GATEWAY_PC,
+                functionName: 'UNIVERSAL_CORE',
+                args: [],
+            });
+            (0, context_1.printLog)(ctx, `queryRescueGasFee — UNIVERSAL_CORE resolved to: ${universalCoreAddress}`);
+        }
+        catch (err) {
+            (0, context_1.printLog)(ctx, `queryRescueGasFee — FAILED to read UNIVERSAL_CORE: ${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
+        let gasToken;
+        let gasFee;
+        let rescueGasLimit;
+        let gasPrice;
+        try {
+            const result = yield ctx.pushClient.readContract({
+                address: universalCoreAddress,
+                abi: abi_1.UNIVERSAL_CORE_EVM,
+                functionName: 'getRescueFundsGasLimit',
+                args: [prc20Token],
+            });
+            gasToken = result[0];
+            gasFee = result[1];
+            rescueGasLimit = result[2];
+            gasPrice = result[3];
+            (0, context_1.printLog)(ctx, `queryRescueGasFee — success: gasToken=${gasToken}, gasFee=${gasFee}, rescueGasLimit=${rescueGasLimit}, gasPrice=${gasPrice}`);
+        }
+        catch (err) {
+            (0, context_1.printLog)(ctx, `queryRescueGasFee — FAILED: ${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
+        const nativeValueForGas = gasFee * GAS_FEE_BUFFER_MULTIPLIER;
+        (0, context_1.printLog)(ctx, `queryRescueGasFee — using 1000000x buffer: nativeValueForGas=${nativeValueForGas}`);
+        return { gasToken, gasFee, rescueGasLimit, gasPrice, nativeValueForGas };
+    });
+}
+// ============================================================================
+// Native Amount Calculation for Deposit
+// ============================================================================
+function calculateNativeAmountForDeposit(ctx, chain, requiredFunds, ueaBalance) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_02_01);
+        const oneUsd = utils_1.Utils.helpers.parseUnits('1', 8);
+        const tenUsd = utils_1.Utils.helpers.parseUnits('10', 8);
+        const deficit = requiredFunds > ueaBalance ? requiredFunds - ueaBalance : BigInt(0);
+        let depositUsd = deficit > BigInt(0) ? ctx.pushClient.pushToUSDC(deficit) : oneUsd;
+        if (depositUsd < oneUsd)
+            depositUsd = oneUsd;
+        if (depositUsd > tenUsd)
+            throw new Error('Deposit value exceeds max $10 worth of native token');
+        if (chain_1.CHAIN_INFO[chain].vm === enums_1.VM.SVM) {
+            const svmClient = new svm_client_1.SvmClient({
+                rpcUrls: ctx.rpcUrls[enums_1.CHAIN.SOLANA_DEVNET] ||
+                    chain_1.CHAIN_INFO[enums_1.CHAIN.SOLANA_DEVNET].defaultRPC,
+            });
+            const programId = new web3_js_1.PublicKey(abi_1.SVM_GATEWAY_IDL.address);
+            const [configPda] = web3_js_1.PublicKey.findProgramAddressSync([(0, viem_1.stringToBytes)('config')], programId);
+            try {
+                const cfg = yield svmClient.readContract({
+                    abi: abi_1.SVM_GATEWAY_IDL,
+                    address: abi_1.SVM_GATEWAY_IDL.address,
+                    functionName: 'config',
+                    args: [configPda.toBase58()],
+                });
+                const minField = (_a = cfg.minCapUniversalTxUsd) !== null && _a !== void 0 ? _a : cfg.min_cap_universal_tx_usd;
+                const maxField = (_b = cfg.maxCapUniversalTxUsd) !== null && _b !== void 0 ? _b : cfg.max_cap_universal_tx_usd;
+                const minCapUsd = BigInt(minField.toString());
+                const maxCapUsd = BigInt(maxField.toString());
+                if (depositUsd < minCapUsd)
+                    depositUsd = minCapUsd;
+                const withMargin = (minCapUsd * BigInt(12)) / BigInt(10);
+                if (depositUsd < withMargin)
+                    depositUsd = withMargin;
+                if (depositUsd > maxCapUsd)
+                    depositUsd = maxCapUsd;
+            }
+            catch (_c) {
+                // best-effort
+            }
+        }
+        const nativeTokenUsdPrice = yield new price_fetch_1.PriceFetch(ctx.rpcUrls).getPrice(chain);
+        const nativeDecimals = chain_1.CHAIN_INFO[chain].vm === enums_1.VM.SVM ? 9 : 18;
+        const oneNativeUnit = utils_1.Utils.helpers.parseUnits('1', nativeDecimals);
+        let nativeAmount = (depositUsd * oneNativeUnit + (nativeTokenUsdPrice - BigInt(1))) /
+            nativeTokenUsdPrice;
+        nativeAmount = nativeAmount + BigInt(1);
+        (0, context_1.fireProgressHook)(ctx, progress_hook_types_1.PROGRESS_HOOK.SEND_TX_02_02, nativeAmount);
+        return nativeAmount;
+    });
+}
+// ============================================================================
+// ERC-20 Gas Amount from Exact Output Quote
+// ============================================================================
+function calculateGasAmountFromAmountOutMinETH(ctx, gasTokenAddress, amountOutMinETH, quoteExactOutputFn) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const originChain = ctx.universalSigner.account.chain;
+        if (originChain !== enums_1.CHAIN.ETHEREUM_SEPOLIA &&
+            originChain !== enums_1.CHAIN.ARBITRUM_SEPOLIA &&
+            originChain !== enums_1.CHAIN.BASE_SEPOLIA) {
+            throw new Error('Gas payment in ERC-20 is supported only on Ethereum Sepolia, Arbitrum Sepolia, and Base Sepolia for now');
+        }
+        const WETH = (_a = chain_1.CHAIN_INFO[originChain].dex) === null || _a === void 0 ? void 0 : _a.weth;
+        if (!WETH)
+            throw new Error('WETH address not configured for this chain');
+        let gasAmount;
+        if (gasTokenAddress.toLowerCase() === WETH.toLowerCase()) {
+            gasAmount = BigInt(amountOutMinETH);
+        }
+        else {
+            const fromList = (_b = tokens_1.PAYABLE_TOKENS[originChain]) !== null && _b !== void 0 ? _b : [];
+            const fromToken = fromList.find((t) => (t.address || '').toLowerCase() === gasTokenAddress.toLowerCase());
+            const toList = ((_c = tokens_1.MOVEABLE_TOKENS[originChain]) !== null && _c !== void 0 ? _c : []);
+            const toToken = toList.find((t) => t.symbol === 'WETH' ||
+                (t.address || '').toLowerCase() === (WETH || '').toLowerCase());
+            if (!fromToken || !toToken) {
+                throw new Error('Token not supported for quoting');
+            }
+            const targetOut = BigInt(amountOutMinETH);
+            const exactOutQuote = yield quoteExactOutputFn(targetOut, {
+                from: fromToken,
+                to: toToken,
+            });
+            const requiredIn = BigInt(exactOutQuote.amountIn);
+            gasAmount = (requiredIn * BigInt(101)) / BigInt(100);
+        }
+        return { gasAmount };
+    });
+}
+//# sourceMappingURL=gas-calculator.js.map

package/src/lib/orchestrator/internals/gateway-client.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Gateway interaction: request conversion, tx sending, and fee locking.
+ * All chains use V1 gateway ABI.
+ */
+import { CHAIN } from '../../constants/enums';
+import { EvmClient } from '../../vm-client/evm-client';
+import type { UniversalPayload } from '../../generated/v1/tx';
+import type { UniversalTxRequest, UniversalTxRequestV1, UniversalTokenTxRequest, UniversalTokenTxRequestV1 } from '../orchestrator.types';
+import type { UniversalSigner } from '../../universal/universal.types';
+import type { OrchestratorContext } from './context';
+export declare function toGatewayRequestV1(req: UniversalTxRequest): UniversalTxRequestV1;
+export declare function toGatewayTokenRequestV1(req: UniversalTokenTxRequest): UniversalTokenTxRequestV1;
+export declare function sendGatewayTxWithFallback(ctx: OrchestratorContext, evmClient: EvmClient, address: `0x${string}`, req: UniversalTxRequest, signer: UniversalSigner, value: bigint): Promise<`0x${string}`>;
+export declare function sendGatewayTokenTxWithFallback(ctx: OrchestratorContext, evmClient: EvmClient, address: `0x${string}`, req: UniversalTokenTxRequest, signer: UniversalSigner, value?: bigint): Promise<`0x${string}`>;
+export declare function lockFee(ctx: OrchestratorContext, amount: bigint, universalPayload: UniversalPayload, req: UniversalTxRequest): Promise<Uint8Array>;
+/**
+ * Creates an EVM client for the origin chain's gateway.
+ * Validates that the chain supports gateway operations.
+ */
+export declare function getOriginGatewayContext(ctx: OrchestratorContext): {
+    chain: CHAIN;
+    evmClient?: EvmClient;
+    gatewayAddress?: `0x${string}`;
+};

package/src/lib/orchestrator/internals/gateway-client.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Gateway interaction: request conversion, tx sending, and fee locking.
+ * All chains use V1 gateway ABI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toGatewayRequestV1 = toGatewayRequestV1;
+exports.toGatewayTokenRequestV1 = toGatewayTokenRequestV1;
+exports.sendGatewayTxWithFallback = sendGatewayTxWithFallback;
+exports.sendGatewayTokenTxWithFallback = sendGatewayTokenTxWithFallback;
+exports.lockFee = lockFee;
+exports.getOriginGatewayContext = getOriginGatewayContext;
+const tslib_1 = require("tslib");
+const bs58_1 = require("../../internal/bs58");
+const web3_js_1 = require("@solana/web3.js");
+const viem_1 = require("viem");
+const context_1 = require("./context");
+const abi_1 = require("../../constants/abi");
+const chain_1 = require("../../constants/chain");
+const enums_1 = require("../../constants/enums");
+const price_fetch_1 = require("../../price-fetch/price-fetch");
+const utils_1 = require("../../utils");
+const evm_client_1 = require("../../vm-client/evm-client");
+const helpers_1 = require("./helpers");
+const svm_client_1 = require("../../vm-client/svm-client");
+const context_2 = require("./context");
+const svm_helpers_1 = require("./svm-helpers");
+const svm_helpers_2 = require("./svm-helpers");
+// ============================================================================
+// ABI
+// ============================================================================
+const GATEWAY_ABI = abi_1.UNIVERSAL_GATEWAY_V1_SEND;
+// ============================================================================
+// Request Conversion (V0 struct → V1 flat format)
+// ============================================================================
+function toGatewayRequestV1(req) {
+    return {
+        recipient: req.recipient,
+        token: req.token,
+        amount: req.amount,
+        payload: req.payload,
+        revertRecipient: req.revertInstruction.fundRecipient,
+        signatureData: req.signatureData,
+    };
+}
+function toGatewayTokenRequestV1(req) {
+    return {
+        recipient: req.recipient,
+        token: req.token,
+        amount: req.amount,
+        gasToken: req.gasToken,
+        gasAmount: req.gasAmount,
+        payload: req.payload,
+        revertRecipient: req.revertInstruction.fundRecipient,
+        signatureData: req.signatureData,
+        amountOutMinETH: req.amountOutMinETH,
+        deadline: req.deadline,
+    };
+}
+// ============================================================================
+// Send Gateway Tx (V1 only)
+// ============================================================================
+function sendGatewayTxWithFallback(ctx, evmClient, address, req, signer, value) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        return evmClient.writeContract({
+            abi: GATEWAY_ABI,
+            address,
+            functionName: 'sendUniversalTx',
+            args: [toGatewayRequestV1(req)],
+            signer,
+            value,
+        });
+    });
+}
+function sendGatewayTokenTxWithFallback(ctx, evmClient, address, req, signer, value) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        return evmClient.writeContract(Object.assign({ abi: GATEWAY_ABI, address, functionName: 'sendUniversalTx', args: [toGatewayTokenRequestV1(req)], signer }, (value !== undefined && { value })));
+    });
+}
+// ============================================================================
+// Fee Locking
+// ============================================================================
+function lockFee(ctx, amount, universalPayload, 
+// DEBUG: lockFee entry
+req) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        const chain = ctx.universalSigner.account.chain;
+        const { lockerContract, vm, defaultRPC } = chain_1.CHAIN_INFO[chain];
+        if (!lockerContract) {
+            throw new Error(`Locker contract not configured for chain: ${chain}`);
+        }
+        const rpcUrls = ctx.rpcUrls[chain] || defaultRPC;
+        switch (vm) {
+            case enums_1.VM.EVM: {
+                const evmClient = (0, context_1.getOriginEvmClient)(ctx);
+                const nativeTokenUsdPrice = yield new price_fetch_1.PriceFetch(ctx.rpcUrls).getPrice(chain);
+                const nativeDecimals = 18;
+                const oneUsd = utils_1.Utils.helpers.parseUnits('1', 8);
+                const tenUsd = utils_1.Utils.helpers.parseUnits('10', 8);
+                let depositUsd = amount < oneUsd ? oneUsd : amount;
+                if (depositUsd > tenUsd)
+                    depositUsd = tenUsd;
+                let nativeAmount = (depositUsd * BigInt(Math.pow(10, nativeDecimals)) +
+                    (nativeTokenUsdPrice - BigInt(1))) /
+                    nativeTokenUsdPrice;
+                nativeAmount = nativeAmount + BigInt(1);
+                const txHash = yield sendGatewayTxWithFallback(ctx, evmClient, lockerContract, req, ctx.universalSigner, nativeAmount);
+                return (0, viem_1.hexToBytes)(txHash);
+            }
+            case enums_1.VM.SVM: {
+                const [nativeTokenUsdPrice, svmClient] = yield Promise.all([
+                    new price_fetch_1.PriceFetch(ctx.rpcUrls).getPrice(chain),
+                    Promise.resolve(new svm_client_1.SvmClient({ rpcUrls })),
+                ]);
+                const nativeDecimals = 9;
+                const oneUsd = utils_1.Utils.helpers.parseUnits('1', 8);
+                const tenUsd = utils_1.Utils.helpers.parseUnits('10', 8);
+                let depositUsd = amount < oneUsd ? oneUsd : amount;
+                if (depositUsd > tenUsd)
+                    depositUsd = tenUsd;
+                let nativeAmount = (depositUsd * BigInt(Math.pow(10, nativeDecimals)) +
+                    (nativeTokenUsdPrice - BigInt(1))) /
+                    nativeTokenUsdPrice;
+                nativeAmount = nativeAmount + BigInt(1);
+                const programId = new web3_js_1.PublicKey(abi_1.SVM_GATEWAY_IDL.address);
+                const [configPda] = web3_js_1.PublicKey.findProgramAddressSync([(0, viem_1.stringToBytes)('config')], programId);
+                const [vaultPda] = web3_js_1.PublicKey.findProgramAddressSync([(0, viem_1.stringToBytes)('vault')], programId);
+                const [rateLimitConfigPda] = web3_js_1.PublicKey.findProgramAddressSync([(0, viem_1.stringToBytes)('rate_limit_config')], programId);
+                const [tokenRateLimitPda] = web3_js_1.PublicKey.findProgramAddressSync([(0, viem_1.stringToBytes)('rate_limit'), web3_js_1.PublicKey.default.toBuffer()], programId);
+                const userPk = new web3_js_1.PublicKey(ctx.universalSigner.account.address);
+                const { feeVaultPda, protocolFeeLamports } = yield (0, svm_helpers_2.getSvmProtocolFee)(svmClient, programId);
+                const gasReq = (0, svm_helpers_1.buildSvmUniversalTxRequestFromReq)(req, userPk);
+                try {
+                    const txHash = yield svmClient.writeContract({
+                        abi: abi_1.SVM_GATEWAY_IDL,
+                        address: programId.toBase58(),
+                        functionName: 'sendUniversalTx',
+                        args: [gasReq, nativeAmount + protocolFeeLamports],
+                        signer: ctx.universalSigner,
+                        accounts: {
+                            config: configPda,
+                            vault: vaultPda,
+                            feeVault: feeVaultPda,
+                            userTokenAccount: vaultPda,
+                            gatewayTokenAccount: vaultPda,
+                            user: userPk,
+                            priceUpdate: new web3_js_1.PublicKey(chain_1.SVM_PYTH_PRICE_FEED),
+                            rateLimitConfig: rateLimitConfigPda,
+                            tokenRateLimit: tokenRateLimitPda,
+                            tokenProgram: new web3_js_1.PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'),
+                            systemProgram: web3_js_1.SystemProgram.programId,
+                        },
+                    });
+                    return new Uint8Array(bs58_1.bs58.decode(txHash));
+                }
+                catch (error) {
+                    (0, context_2.printLog)(ctx, `Error sending UniversalTx: ${error instanceof Error ? error.message : String(error)}`);
+                    throw error;
+                }
+            }
+            default:
+                throw new Error(`Unsupported VM type: ${vm}`);
+        }
+    });
+}
+// ============================================================================
+// Origin Gateway Context
+// ============================================================================
+/**
+ * Creates an EVM client for the origin chain's gateway.
+ * Validates that the chain supports gateway operations.
+ */
+function getOriginGatewayContext(ctx) {
+    const chain = ctx.universalSigner.account.chain;
+    if (!helpers_1.SUPPORTED_GATEWAY_CHAINS.includes(chain)) {
+        throw new Error('Funds + payload bridging is only supported on Ethereum Sepolia, Arbitrum Sepolia, Base Sepolia, BNB Testnet, and Solana Devnet for now');
+    }
+    if (chain_1.CHAIN_INFO[chain].vm === enums_1.VM.EVM) {
+        const { defaultRPC, lockerContract } = chain_1.CHAIN_INFO[chain];
+        const rpcUrls = ctx.rpcUrls[chain] || defaultRPC;
+        const evmClient = new evm_client_1.EvmClient({ rpcUrls });
+        const gatewayAddress = lockerContract;
+        if (!gatewayAddress) {
+            throw new Error('Universal Gateway address not configured');
+        }
+        return { chain, evmClient, gatewayAddress };
+    }
+    // SVM path does not require evmClient/gatewayAddress
+    return { chain };
+}
+//# sourceMappingURL=gateway-client.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * Pure utility functions extracted from Orchestrator.
+ *
+ * These have minimal dependencies and are used across multiple submodules.
+ */
+import { CHAIN, PUSH_NETWORK } from '../../constants/enums';
+import type { ExecuteParams, UniversalExecuteParams } from '../orchestrator.types';
+import type { OrchestratorContext } from './context';
+/** Chains that support gateway operations (multicall, funds bridging, etc.) */
+export declare const SUPPORTED_GATEWAY_CHAINS: CHAIN[];
+export declare function isPushChain(chain: CHAIN): boolean;
+export declare function getPushChainForNetwork(pushNetwork: PUSH_NETWORK): CHAIN;
+export declare function getChainNamespace(chain: CHAIN): string;
+export declare function chainFromNamespace(namespace: string): CHAIN | null;
+export declare function getNativePRC20ForChain(targetChain: CHAIN, pushNetwork: PUSH_NETWORK): `0x${string}`;
+export declare function getUniversalGatewayPCAddress(): `0x${string}`;
+/**
+ * Validates that a feeLockTxHash is a well-formed transaction hash.
+ * EVM: must be 0x-prefixed 64-hex-char string (66 chars total).
+ * SVM (Base58): must be at least 32 chars.
+ */
+export declare function validateFeeLockTxHash(feeLockTxHash: string): void;
+export declare function validateMainnetConnection(chain: CHAIN, pushChainId: string): void;
+export declare function bigintReplacer(_key: string, value: any): any;
+export declare function toExecuteParams(params: UniversalExecuteParams): ExecuteParams;
+export declare function fetchOriginChainTransactionForProgress(ctx: OrchestratorContext, chain: CHAIN, txHashHex: string, txHashDisplay: string): Promise<object | undefined>;