@wireio/stake 0.4.2 → 0.4.69

package/src/networks/ethereum/ethereum.ts

@@ -8,13 +8,16 @@ import {
     TrancheSnapshot
 } from '../../types';
 import { EthereumContractService } from './contract';
-import { preLaunchReceipt } from './types';
+import { preLaunchReceipt, WithdrawReceipt } from './types';
 import { buildEthereumTrancheSnapshot } from './utils';
 import { ConvertClient } from './clients/convert.client';
 import { StakeClient } from './clients/stake.client';
 import { PretokenClient } from './clients/pretoken.client';
 import { OPPClient } from './clients/opp.client';
 import { ReceiptClient } from './clients/receipt.client';
+import { ValidatorClient } from './clients/validator.client';
+
+export const INITIAL_TRANCHE_SUPPLY = 35000;
 
 export class EthereumStakingClient implements IStakingClient {
     private readonly provider: ethers.providers.Web3Provider | ethers.providers.JsonRpcProvider;
@@ -27,10 +30,11 @@ export class EthereumStakingClient implements IStakingClient {
     private stakeClient: StakeClient;
     private oppClient: OPPClient;
     private receiptClient: ReceiptClient;
-
+    private validatorClient: ValidatorClient;
 
     get contract() { return this.contractService.contract; }
     get network() { return this.config.network; }
+    get address() { return this.signer?.getAddress(); }
 
     constructor(private config: StakerConfig) {
         try {
@@ -46,6 +50,7 @@ export class EthereumStakingClient implements IStakingClient {
             this.contractService = new EthereumContractService({
                 provider: this.provider,
                 signer: this.signer,
+                chainId: config.network.chainId as EvmChainID,
             });
 
             this.convertClient = new ConvertClient(this.contractService);
@@ -53,6 +58,7 @@ export class EthereumStakingClient implements IStakingClient {
             this.stakeClient = new StakeClient(this.contractService);
             this.oppClient = new OPPClient(this.contractService);
             this.receiptClient = new ReceiptClient(this.contractService);
+            this.validatorClient = new ValidatorClient(this.contractService)
         }
         catch (error) {
             // console.error('Error initializing EthereumStakingClient:', error);
@@ -89,13 +95,38 @@ export class EthereumStakingClient implements IStakingClient {
     async withdraw(amount: bigint): Promise<string> {
         this.ensureUser();
 
-        const address = await this.signer!.getAddress();
+        const address = await this.address!;
         const amountWei = BigNumber.from(amount);
 
         const result = await this.convertClient.performWithdraw(address, amountWei)
         return result.txHash;
     }
 
+    /**
+     * List withdrawal queue receipts for a wallet (pending / in-progress exits after safeBurn).
+     * @param address  Owner to query; defaults to the connected wallet.
+     * @returns Withdrawal receipt NFT entries from the protocol view
+     */
+    async getPendingWithdraws(address?: string): Promise<WithdrawReceipt[]> {
+        this.ensureUser();
+        const owner = address ?? await this.address!;
+        return await this.receiptClient.fetchWithdrawReceipts(owner);
+    }
+
+    /**
+     * Claim native ETH for a matured withdrawal using the WithdrawalQueue NFT token id
+     * (via DepositManager.claim after the delay has passed).
+     * @param tokenId  Withdrawal request / queue NFT token id
+     * @returns transaction hash
+     */
+    async claimWithdraw(tokenId: bigint): Promise<string> {
+        this.ensureUser();
+
+        const tokenIdBigNum = BigNumber.from(tokenId)
+        const result = await this.convertClient.claimWithdraw(tokenIdBigNum)
+        return result.txHash;
+    }
+
 
     /**
      * Stake liqETH via DepositManager.
@@ -105,7 +136,7 @@ export class EthereumStakingClient implements IStakingClient {
     async stake(amount: bigint): Promise<string> {
         this.ensureUser();
 
-        const walletAddress = await this.signer!.getAddress();
+        const walletAddress = await this.address!;
         const amountWei = BigNumber.from(amount);
 
         const result = await this.stakeClient.performStake(amountWei, walletAddress);
@@ -118,6 +149,46 @@ export class EthereumStakingClient implements IStakingClient {
         throw new Error("Method not yet implemented.");
     }
 
+    /**
+     * Deposit ETH to liqETH, then stake liqETH in a single transaction.
+     * @param amountWei  Amount in wei.
+     * @returns transaction hash
+     */
+    async depositAndStake(amountWei: bigint): Promise<string> {
+        this.ensureUser();
+        if (!amountWei || amountWei <= BigInt(0))
+            throw new Error('Amount must be greater than zero.');
+
+        const result = await this.stakeClient.performDepositAndStake(BigNumber.from(amountWei));
+        return result.txHash;
+    }
+
+    /**
+     * Deposit ETH to liqETH, then purchase pretokens in a single transaction.
+     * @param amountWei  Amount in wei.
+     * @returns transaction hash
+     */
+    async depositAndBuy(amountWei: bigint): Promise<string> {
+        this.ensureUser();
+        if (!amountWei || amountWei <= BigInt(0))
+            throw new Error('Amount must be greater than zero.');
+
+        const result = await this.stakeClient.performDepositAndPurchase(BigNumber.from(amountWei));
+        return result.txHash;
+    }
+
+    /**
+     * Unstake liqETH, then request a withdrawal in a single transaction.
+     * @param tokenId  The ReceiptNFT token ID for the stake position
+     * @returns transaction hash
+     */
+    async unstakeAndWithdraw(tokenId: bigint): Promise<string> {
+        this.ensureUser();
+
+        const result = await this.stakeClient.performUnstakeAndRequestWithdraw(BigNumber.from(tokenId));
+        return result.txHash;
+    }
+
 
     /**
      * ETH Prelaunch function to unstake liqEth
@@ -137,16 +208,34 @@ export class EthereumStakingClient implements IStakingClient {
     async buy(amount: bigint): Promise<string> {
         this.ensureUser();
 
-        const buyer = await this.signer!.getAddress();
+        const buyer = await this.address!;
 
         // ! Hoodi only - check if the mock aggregator price is stale, and if so, update it before submitting the buy request
-        await this.updateMockAggregatorPrice();
+        // const network = await this.provider.getNetwork();
+        // const chainId = network.chainId;
+        // const allowedTestChains = new Set([560048]);
+        // if (allowedTestChains.has(chainId)) await this.updateMockAggregatorPrice();
 
         let result = await this.pretokenClient.purchasePretokensWithLiqETH(amount, buyer);
         return result && result.txHash ? result.txHash : "Error - no resulting txHash";
     }
 
 
+    /**
+     * Validator functions
+     */
+    async validatorDeposit(): Promise<string> {
+        this.ensureUser();
+
+        let result = await this.validatorClient.validatorDepositAndLockBond();
+        return result && result.txHash ? result.txHash : "Error - no resulting txHash";
+    }
+    
+
+
+
+
+
     /**
      * Resolve the user's ETH + liqETH balances.
      *
@@ -154,54 +243,107 @@ export class EthereumStakingClient implements IStakingClient {
      * actual  = liqETH token balance (ERC-20)
      * tracked = liqETH tracked balance (protocol/accounting view)
      */
-    async getPortfolio(): Promise<Portfolio> {
-        this.ensureUser();
+    async getPortfolio(address?: string): Promise<Portfolio | null> {
 
-        const walletAddress = await this.signer!.getAddress();
+        try {
+            if (!this.signer) return Promise.resolve(null);
 
-        // 1) Native ETH balance
-        const nativeBalance = await this.provider.getBalance(walletAddress);
-        const nativeDecimals = this.network?.nativeCurrency?.decimals ?? 18;
-        const nativeSymbol = this.network?.nativeCurrency?.symbol ?? 'ETH';
+            const walletAddress = address ?? await this.address!;
 
-        // 2) liqETH ERC-20 balance (actual)
-        const liqBalance: ethers.BigNumber = await this.contract.LiqEth.balanceOf(walletAddress);
-        const liqSymbol = 'Liq' + (this.network?.nativeCurrency?.symbol ?? 'ETH');
+            // 1) Native ETH balance
+            const nativeBalance = await this.provider.getBalance(walletAddress);
+            const nativeDecimals = this.network?.nativeCurrency?.decimals ?? 18;
+            const nativeSymbol = this.network?.nativeCurrency?.symbol ?? 'ETH';
+
+            // 2) liqETH ERC-20 balance (actual)
+            const liqBalance: ethers.BigNumber = await this.contract.LiqEthToken.balanceOf(walletAddress);
+            const liqSymbol = 'Liq' + (this.network?.nativeCurrency?.symbol ?? 'ETH');
+
+            // 3) staked liqEth ERC-20 balance (calculate from receipts)
+            let stakeReceipts = await this.receiptClient.stakeReceipts(walletAddress);
+
+            let stakeBalanceBN = BigNumber.from(0);
+            for (let r of stakeReceipts) {
+                stakeBalanceBN = stakeBalanceBN.add(BigNumber.from(r.receipt.principal.amount));
+            }
+            let stakeSharesBN = BigNumber.from(0);
+            for (let r of stakeReceipts) {
+                stakeSharesBN = stakeSharesBN.add(BigNumber.from(r.receipt.shares.amount));
+            }
+
+            // 4) WIRE pretoken balance
+            const wireBalance: ethers.BigNumber = await this.contract.Pretoken.balanceOf(walletAddress);
+
+            // 5) Calculate staking yield 
+            let currentIndex = BigInt(0);
+            let totalShares = BigInt(0);
+            let userShares = BigInt(0);
+            const indexScale = BigInt(1e27);
+            try {
+                // These may throw if not implemented on contract
+                const [indexBn, totalSharesBn] = await Promise.all([
+                    this.contract.Depositor.index().catch(() => BigNumber.from(0)),
+                    this.contract.Depositor.totalShares().catch(() => BigNumber.from(0)),
+                ]);
+
+                const userSharesBn = stakeSharesBN;
+                currentIndex = BigInt(indexBn.toString());
+                totalShares = BigInt(totalSharesBn.toString());
+                userShares = BigInt(userSharesBn.toString());
+            } catch (error) {
+                console.log('Error fetching staking index/shares:', error);
+            }
+
+            // sharesToTokens(userShares, currentIndex) = userShares * currentIndex / indexScale
+            let estimatedClaim = BigInt(0);
+            let estimatedYield = BigInt(0);
+            
+            if (userShares > BigInt(0) && currentIndex > BigInt(0)) {
+                estimatedClaim = (userShares * currentIndex) / indexScale;
+                if (estimatedClaim > stakeBalanceBN.toBigInt()) {
+                    estimatedYield = estimatedClaim - stakeBalanceBN.toBigInt();
+                }
+            }
 
-        // 3) staked liqEth ERC-20 balance (calculate from receipts)
-        let stakeReceipts = await this.receiptClient.stakeReceipts(walletAddress);
-        let stakeBalanceBN = BigNumber.from(0);
-        for (let r of stakeReceipts) {
-            stakeBalanceBN = stakeBalanceBN.add(BigNumber.from(r.receipt.principal.amount));
-        }
 
-        // 4) WIRE pretoken balance
-        const wireBalance: ethers.BigNumber = await this.contract.Pretoken.balanceOf(walletAddress);
-
-        const portfolio: Portfolio = {
-            native: {
-                amount: nativeBalance.toBigInt(),
-                decimals: nativeDecimals,
-                symbol: nativeSymbol,
-            },
-            liq: {
-                amount: liqBalance.toBigInt(),
-                decimals: nativeDecimals,
-                symbol: liqSymbol,
-            },
-            staked: {
-                amount: stakeBalanceBN.toBigInt(),
-                decimals: nativeDecimals,
-                symbol: liqSymbol,
-            },
-            wire: {
-                amount: wireBalance.toBigInt(),
-                decimals: 18,
-                symbol: '$WIRE',
-            },
-            chainID: this.network.chainId
+            const portfolio: Portfolio = {
+                native: {
+                    amount: nativeBalance.toBigInt(),
+                    decimals: nativeDecimals,
+                    symbol: nativeSymbol,
+                },
+                liq: {
+                    amount: liqBalance.toBigInt(),
+                    decimals: nativeDecimals,
+                    symbol: liqSymbol,
+                },
+                staked: {
+                    amount: stakeBalanceBN.toBigInt(),
+                    decimals: nativeDecimals,
+                    symbol: liqSymbol,
+                },
+                wire: {
+                    amount: wireBalance.toBigInt(),
+                    decimals: 18,
+                    symbol: '$WIRE',
+                },
+
+                yield: {
+                    currentIndex,
+                    indexScale,
+                    totalShares,
+                    userShares,
+                    estimatedClaim,
+                    estimatedYield,
+                },
+                chainID: this.network.chainId
+            }
+            return portfolio;
+        }
+        catch (error) {
+            // console.log('Error fetching Ethereum portfolio:', error);
+            throw error;
         }
-        return portfolio;
     }
 
     /**
@@ -212,7 +354,7 @@ export class EthereumStakingClient implements IStakingClient {
     async fetchPrelaunchReceipts(address?: string): Promise<preLaunchReceipt[]> {
         this.ensureUser();
 
-        if (address === undefined) address = await this.signer!.getAddress();
+        if (address === undefined) address = await this.address!;
 
         //default to stake receipts
         return await this.receiptClient.stakeReceipts(address);
@@ -221,11 +363,13 @@ export class EthereumStakingClient implements IStakingClient {
     async getOPPMessages(address?: string): Promise<OPPAssertion[]> {
         this.ensureUser();
 
-        if (!address) address = await this.signer!.getAddress();
+        if (!address) address = await this.address!;
 
         return await this.oppClient.getMessages(address);
     }
 
+
+
     // Ensure that signer wallet is available for write operations
     private ensureUser() {
         if (!this.signer) {
@@ -240,16 +384,24 @@ export class EthereumStakingClient implements IStakingClient {
     // READ-ONLY Public Methods
     // ---------------------------------------------------------------------
 
-    // Estimated total APY for staking yeild
-    getSystemAPY(): Promise<number> {
-        // TODO
-        return Promise.resolve(0);
+    // Protocol-wide ETH staking APY in percent, e.g. 3.0 => "3.00%"
+    async getSystemAPY(): Promise<number> {
+        // NOTE: despite the name, this value is effectively *annual* BPS on-chain.
+        // e.g. 300 => 3% APY
+        const annualBpsBn = await this.contract.DepositManager.dailyRateBPS();
+        const annualBps = annualBpsBn.toNumber(); // e.g. 300 for 3%
+
+        // Convert basis points (1/100 of 1%) to percent:
+        // 10,000 bps = 100% ⇒ 100 bps = 1% ⇒ divide by 100.
+        const apyPercent = annualBps / 100;
+
+        return apyPercent; // 3 => "3.00%"
     }
 
     // Protocol fee charged for deposit from Native to LIQ
-    getDepositFee(amount: bigint): Promise<bigint> {
-        // TODO
-        return Promise.resolve(BigInt(0));
+    async getDepositFee(amountWei: bigint): Promise<bigint> {
+        const feeBn: BigNumber = await this.contract.DepositManager.procFee(amountWei);
+        return BigInt(feeBn.toString());
     }
 
     async getOPPStatus(): Promise<any> {
@@ -257,7 +409,7 @@ export class EthereumStakingClient implements IStakingClient {
     }
 
     async getEthStats(): Promise<any> {
-        let withdrawDelay = await this.contract.DepositManager.withdrawDelay();
+        let withdrawDelay = await this.contract.WithdrawalQueue.withdrawDelay();
         let minDeposit = await this.contract.DepositManager.minDeposit();
         let rewardCooldown = await this.contract.DepositManager.rewardCooldown();
 
@@ -273,117 +425,180 @@ export class EthereumStakingClient implements IStakingClient {
      * 
      * SUPPORTS READ-ONLY ACcESS
      */
-    async getTrancheSnapshot(options?: {
-        chainID?: ChainID;
-        windowBefore?: number;
-        windowAfter?: number;
-    }): Promise<TrancheSnapshot> {
-        const {
-            chainID = EvmChainID.Hoodi,
-            windowBefore,
-            windowAfter,
-        } = options ?? {};
-
-
-        const blockNumber = await this.provider.getBlockNumber();
-        const blockTag = { blockTag: blockNumber };
-
-        // Fetch all required contract data
-        const [totalSharesBn, indexBn, trancheNumberBn, trancheSupplyBn, tranchePriceWadBn, totalSupplyBn, supplyGrowthBps, priceGrowthBps, minPriceUsd, maxPriceUsd] = await Promise.all([
-            this.contract.Depositor.totalShares(blockTag),
-            this.contract.Depositor.index(blockTag),
-            this.contract.Pretoken.trancheNumber(blockTag),
-            this.contract.Pretoken.trancheSupply(blockTag),
-            this.contract.Pretoken.tranchePriceUsd(blockTag),
-            this.contract.Pretoken.totalSupply(blockTag),
-            this.contract.Pretoken.supplyGrowthBps(blockTag),
-            this.contract.Pretoken.priceGrowthBps(blockTag),
-            this.contract.EthUsdPriceConsumer.MIN_PRICE(),
-            this.contract.EthUsdPriceConsumer.MAX_PRICE(),
-        ]);
-
-
-        const totalTrancheSupply = BigInt(totalSupplyBn.toString()) / BigInt(1e10);
-        const currentTrancheSupply = BigInt(trancheSupplyBn.toString()) / BigInt(1e10);
-
-
-        // fetch price and timestamp from aggregator
-        const [roundId, answer, startedAt, updatedAt, answeredInRound] = await this.contract.Aggregator.latestRoundData();
-        let ethPriceUsd: bigint = BigInt(answer.toString());
-        let nativePriceTimestamp: number = Number(updatedAt);
-
-        // ! Placeholder from hoodi deployment - don't think this can be fetched dynamically
-        const initialTrancheSupply = BigInt(60000) * BigInt(1e8);
-
-        return buildEthereumTrancheSnapshot({
-            chainID,
-            totalSharesBn,
-            indexBn,
-            trancheNumberBn,
-            currentTrancheSupply,
-            tranchePriceWadBn,
-            totalTrancheSupply,
-            initialTrancheSupply,
-            supplyGrowthBps,
-            priceGrowthBps,
-            minPriceUsd,
-            maxPriceUsd,
-
-            ethPriceUsd,
-            nativePriceTimestamp,
-            ladderWindowBefore: windowBefore,
-            ladderWindowAfter: windowAfter,
-        });
+    async getTrancheSnapshot(chainID: ChainID): Promise<TrancheSnapshot> {
+        try {
+            const blockNumber = await this.provider.getBlockNumber();
+            const blockTag = { blockTag: blockNumber };
+
+            // Fetch all required contract data
+            const [totalSharesBn, indexBn, trancheNumberBn, trancheSupplyBn, tranchePriceUsdBn, totalSupplyBn, supplyGrowthBps, priceGrowthCents, minPriceUsd, maxPriceUsd] = await Promise.all([
+                this.contract.Depositor.totalShares(blockTag),
+                this.contract.Depositor.index(blockTag),
+                this.contract.Pretoken.trancheNumber(blockTag),
+                this.contract.Pretoken.trancheSupply(blockTag),
+                this.contract.Pretoken.tranchePriceUsd(blockTag),
+                this.contract.Pretoken.totalSupply(blockTag),
+                this.contract.Pretoken.supplyGrowthBps(blockTag),
+                this.contract.Pretoken.priceIncrementUsd(blockTag),
+                this.contract.EthUsdPriceConsumer.MIN_PRICE(),
+                this.contract.EthUsdPriceConsumer.MAX_PRICE(),
+            ]);
+
+            const totalTrancheSupply = BigInt(totalSupplyBn.toString()) / BigInt(1e10);
+            const currentTrancheSupply = BigInt(trancheSupplyBn.toString()) / BigInt(1e10);
+
+            // fetch price and timestamp from aggregator
+            // const [roundId, answer, startedAt, updatedAt, answeredInRound] = await this.contract.MockAggregator.latestRoundData();
+            //originally fetched ethPrice from aggregator - pulling from EthUsdPriceConsumer instead - this is where the actual price gets pulled from when purchasing pretokens.
+            // let ethPriceUsd: bigint = BigInt(answer.toString());)
+
+            let ethPriceUsdBn = await this.contract.EthUsdPriceConsumer.getPrice18Decimals();
+            let ethPriceUsd: bigint = BigInt(ethPriceUsdBn.toString()) / BigInt(1e10);
+
+            // let nativePriceTimestamp: number = Number(updatedAt);
+
+            const initialTrancheSupply = BigInt(INITIAL_TRANCHE_SUPPLY) * BigInt(1e8);
+
+            return buildEthereumTrancheSnapshot({
+                chainID,
+                totalSharesBn,
+                indexBn,
+                trancheNumberBn,
+                currentTrancheSupply,
+                tranchePriceUsdBn,
+                totalTrancheSupply,
+                initialTrancheSupply,
+                supplyGrowthBps,
+                priceGrowthCents,
+                minPriceUsd,
+                maxPriceUsd,
+                ethPriceUsd,
+            });
+        }
+        catch (err: any) {
+            throw new Error(`Error fetching Ethereum tranche snapshot: ${err?.message || err}`);
+        }
     }
 
-    // ---------------------------------------------------------------------
-    // Internal ETH Staking client helper functions
-    // ---------------------------------------------------------------------
+    /**
+     * Estimate a conservative native ETH buffer (in wei) to leave in the wallet
+     * so the user can pay gas for the current deposit and at least one more tx.
+     *
+     * Typical usage in UI:
+     *   const buffer = await client.estimateGasBuffer();
+     *   const maxSpendable = balanceWei > buffer ? balanceWei - buffer : 0n;
+     *
+     * @param options.txCount         How many transactions to cover (default 2: deposit + 1 more)
+     * @param options.safetyMultiplier Additional safety multiplier on top of txCount (default 1.5x)
+     * @param options.minBufferWei    Optional override minimum buffer (defaults ~0.002 ETH)
+     */
+    async getDepositBuffer(options?: {
+        txCount?: number;
+        safetyMultiplier?: number;
+        minBufferWei?: bigint;
+        balanceOverrideLamports?: bigint;
+    }): Promise<bigint> {
+        this.ensureUser();
 
-    // ! This is a temporary measure for Hoodi testnet because there is no aggregator deployed
-    private async updateMockAggregatorPrice() {
-        const aggregator = this.contract.Aggregator;
-
-        // read latest round & compute age
-        const [roundId, answer, startedAt, updatedAt, answeredInRound] = await aggregator.latestRoundData();
-        const now = (await this.provider.getBlock("latest")).timestamp;
-        const ageSec = Number(now) - Number(updatedAt);
-
-        const ONE_HOUR = 1 * 3600;
-        // const ONE_HOUR = 10;
-        if (ageSec > ONE_HOUR) {
-            // safety check - only run in non-production contexts
-            const network = await this.provider.getNetwork();
-            const chainId = network.chainId;
-            const allowedTestChains = new Set([560048]);
-            if (!allowedTestChains.has(chainId)) {
-                console.warn(`MockAggregator is stale (${ageSec}s) but chainId ${chainId} is not a test/local network — skipping update.`);
-                return;
-            }
+        const walletAddress = await this.address!;
 
+        // 1) Estimate a baseline gas usage using a simple self-transfer.
+        //    This is cheap and doesn't depend on your contract ABI at all.
+        const baseGas = await this.provider.estimateGas({
+            from: walletAddress,
+            to: walletAddress,
+            value: ethers.constants.Zero,
+        });
 
-            //fetch the current ETH / USD price
-            const res = await fetch('https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd');
-            const data = await res.json();
-            const ethUsd = data.ethereum.usd;
+        // 2) Fetch current gas price / max fee per gas.
+        const feeData = await this.provider.getFeeData();
+        let gasPrice =
+            feeData.maxFeePerGas ??
+            feeData.gasPrice ??
+            ethers.utils.parseUnits('20', 'gwei'); // conservative fallback
 
-            const currentEthPrice = ethers.utils.parseUnits(ethUsd.toString(), 8);
+        // 3) How many txs do we want to cover?
+        //    Default: 2 (deposit + one extra action such as stake or small follow-up).
+        const txCount = options?.txCount ?? 2;
 
-            try {
-                //update to be intentionally stale
-                // const alttx = await aggregator.updateStale(currentEthPrice, now - 7200);
-                // const altreceipt = await alttx.wait(1);
-                // console.log('stale update receipt', altreceipt)
-
-                //update answer with current timestamp
-                const tx = await aggregator.updateAnswer(currentEthPrice);
-                const txreceipt = await tx.wait(1);
-                // console.log('MockAggregator answer updated - receipt:', txreceipt)
-            } catch (err: any) {
-                console.error('MockAggregator updateAnswer failed', err?.message || err);
-            }
-        } else {
-            console.log(`MockAggregator updated ${ageSec}s ago — no update needed`);
+        // We also assume that contract interactions are more expensive than a simple transfer.
+        // Use a multiplier (e.g., 5x) on baseGas to approximate a more complex tx.
+        const COMPLEX_TX_MULTIPLIER = 5; // tuning knob
+        const totalGasUnits = baseGas
+            .mul(COMPLEX_TX_MULTIPLIER)
+            .mul(txCount);
+
+        const baseCost = totalGasUnits.mul(gasPrice);
+
+        // 4) Safety multiplier on top of that (e.g. 1.5x).
+        const safetyMultiplier = options?.safetyMultiplier ?? 1.5;
+        const safetyScaled = Math.round(safetyMultiplier * 100); // e.g. 150
+
+        const bufferedCost = baseCost
+            .mul(safetyScaled)
+            .div(100); // apply safety factor
+
+        let bufferWei = bufferedCost.toBigInt();
+
+        // 5) Enforce a minimum floor (e.g. ~0.002 ETH).
+        const defaultMinBufferWei = BigInt(2_000_000_000_000_000); // 0.002 ETH
+        const minBufferWei = options?.minBufferWei ?? defaultMinBufferWei;
+
+        if (bufferWei < minBufferWei) {
+            bufferWei = minBufferWei;
         }
+
+        return bufferWei;
     }
-}
+
+    // ---------------------------------------------------------------------
+    // Internal ETH Staking client helper functions
+    // ---------------------------------------------------------------------
+
+    // ! This is a temporary measure for Hoodi testnet because there is no aggregator deployed
+    // private async updateMockAggregatorPrice() {
+    //     const aggregator = this.contract.MockAggregator;
+
+    //     // read latest round & compute age
+    //     const [roundId, answer, startedAt, updatedAt, answeredInRound] = await aggregator.latestRoundData();
+    //     const now = (await this.provider.getBlock("latest")).timestamp;
+    //     const ageSec = Number(now) - Number(updatedAt);
+
+    //     const ONE_HOUR = 1 * 3600;
+    //     // const ONE_HOUR = 10;
+    //     if (ageSec > ONE_HOUR) {
+    //         // safety check - only run in non-production contexts
+    //         const network = await this.provider.getNetwork();
+    //         const chainId = network.chainId;
+    //         const allowedTestChains = new Set([560048]);
+    //         if (!allowedTestChains.has(chainId)) {
+    //             console.warn(`MockAggregator is stale (${ageSec}s) but chainId ${chainId} is not a test/local network — skipping update.`);
+    //             return;
+    //         }
+
+
+    //         //fetch the current ETH / USD price
+    //         const res = await fetch('https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd');
+    //         const data = await res.json();
+    //         const ethUsd = data.ethereum.usd;
+
+    //         const currentEthPrice = ethers.utils.parseUnits(ethUsd.toString(), 8);
+
+    //         try {
+    //             //update to be intentionally stale
+    //             // const alttx = await aggregator.updateStale(currentEthPrice, now - 7200);
+    //             // const altreceipt = await alttx.wait(1);
+    //             // console.log('stale update receipt', altreceipt)
+
+    //             //update answer with current timestamp
+    //             const tx = await aggregator.updateAnswer(currentEthPrice);
+    //             const txreceipt = await tx.wait(1);
+    //             // console.log('MockAggregator answer updated - receipt:', txreceipt)
+    //         } catch (err: any) {
+    //             console.error('MockAggregator updateAnswer failed', err?.message || err);
+    //         }
+    //     } else {
+    //         console.log(`MockAggregator updated ${ageSec}s ago — no update needed`);
+    //     }
+    // }
+}