@wireio/stake 2.2.2 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@wireio/stake",
-    "version": "2.2.2",
+    "version": "2.3.1",
     "description": "LIQ Staking Module for Wire Network",
     "homepage": "https://gitea.gitgo.app/Wire/sdk-stake",
     "license": "FSL-1.1-Apache-2.0",
@@ -64,7 +64,7 @@
         "@types/node": "^18.19.0",
         "@typescript-eslint/eslint-plugin": "^5.60.0",
         "@typescript-eslint/parser": "^5.60.0",
-        "@wireio/core": "^0.3.0",
+        "@wireio/core": "^0.3.1",
         "assert": "^2.0.0",
         "chai": "^4.3.6",
         "esbuild": "^0.25.8",

package/src/index.ts

@@ -13,8 +13,8 @@ export * as SOL from './networks/solana/types';
 export * from './networks/solana/utils';
 
 // CLIENTS
-export * from './networks/solana/clients/deposit.client';
+export * from './networks/solana/clients/convert.client';
 export * from './networks/solana/clients/distribution.client';
 export * from './networks/solana/clients/leaderboard.client';
 export * from './networks/solana/clients/outpost.client';
-export * from './networks/solana/clients/token.client';
+export * from './networks/solana/clients/token.client';

package/src/networks/ethereum/clients/receipt.client.ts

@@ -1,7 +1,7 @@
 import { BigNumber } from "ethers";
-import { preLaunchReceipt, WithdrawReceipt } from "../types";
+import { preLaunchReceipt } from "../types";
+import { WithdrawReceipt, ReceiptNFTKind } from "../../../types";
 import { EthereumContractService } from "../contract";
-import { ReceiptNFTKind } from "../../../types";
 
 export class ReceiptClient {
 
@@ -13,8 +13,7 @@ export class ReceiptClient {
         this.contractService = contract;
     }
 
-
-
+    // NOTE: Stake/pretoken receipts intentionally ignored for withdraw view.
     async allReceipts(address: string): Promise<preLaunchReceipt[]> {
         return this.fetchPreLaunchReceipts(address);
     }
@@ -23,9 +22,7 @@ export class ReceiptClient {
         try {
             const receipts = await this.fetchPreLaunchReceipts(address, ReceiptNFTKind.STAKE);
             return receipts;
-        }
-        catch (err) {
-            // console.log('Error fetching stake receipts:', err);
+        } catch (err) {
             return [];
         }
     }
@@ -34,28 +31,20 @@ export class ReceiptClient {
         return this.fetchPreLaunchReceipts(address, ReceiptNFTKind.PRETOKEN_PURCHASE);
     }
 
-
-
     /**
-     * 
-     * @param address (string) to fetch receipts for
-     * @returns preLaunchReceipt[]
+     * Fetch ReceiptNFT data (stake/pretoken) for an address, optionally filtered by kind.
      */
     async fetchPreLaunchReceipts(address: string, type?: ReceiptNFTKind): Promise<preLaunchReceipt[]> {
         const receiptContract = this.contract.ReceiptNFT;
 
-        // first figure out which tokenIds this address owns, from events
         const tokenIds = await this.getOwnedReceiptNFTsFor(address);
-
         const results: preLaunchReceipt[] = [];
 
-        // next fetch on-chain receipt data just for those ids
         for (const idBN of tokenIds) {
             try {
                 const receiptData = await receiptContract.getReceipt(idBN);
 
-                //skip any receipt not of the requested type
-                if(type !== undefined && receiptData.kind !== type) continue;
+                if (type !== undefined && receiptData.kind !== type) continue;
 
                 results.push({ 
                     tokenId: idBN.toBigInt(), 
@@ -78,7 +67,6 @@ export class ReceiptClient {
                     }
                 });
             } catch (err) {
-                // in case of any mismatch or race, just skip this id
                 console.warn(`Failed to load receipt for tokenId=${idBN.toString()}`, err);
                 continue;
             }
@@ -88,50 +76,6 @@ export class ReceiptClient {
     }
 
 
-
-
-    private async getOwnedReceiptNFTsFor(
-        owner: string,
-        fromBlock = 0,
-        toBlock: number | string = "latest"
-    ): Promise<BigNumber[]> {
-        const receiptContract = this.contract.ReceiptNFT;
-
-        // Logs where address received tokens
-        const toLogs = await receiptContract.queryFilter(
-            receiptContract.filters.Transfer(null, owner),
-            fromBlock,
-            toBlock
-        );
-
-        // Logs where address sent tokens (including burns from owner → 0)
-        const fromLogs = await receiptContract.queryFilter(
-            receiptContract.filters.Transfer(owner, null),
-            fromBlock,
-            toBlock
-        );
-
-        const owned = new Set<string>();
-
-        // Add all received tokenIds
-        for (const e of toLogs) {
-            const tokenId = e.args?.tokenId;
-            if (!tokenId) continue;
-            owned.add(tokenId.toString());
-        }
-
-        // Remove all sent tokenIds
-        for (const e of fromLogs) {
-            const tokenId = e.args?.tokenId;
-            if (!tokenId) continue;
-            owned.delete(tokenId.toString());
-        }
-
-        // Convert to BigNumbers
-        return Array.from(owned).map((id) => BigNumber.from(id));
-    }
-
-
     /**
      * 
      * @param address (string) to fetch receipts for
@@ -147,16 +91,21 @@ export class ReceiptClient {
             try {
                 const receiptData = await this.contract.WithdrawalQueue.info(idBN);
 
-                results.push({ 
-                    tokenId: idBN.toBigInt(), 
+                // status: ready if readyAt <= now; otherwise queued
+                const readyAtMs = Number(receiptData.readyAt) * 1000;
+                const status = readyAtMs <= Date.now() ? 'ready' : 'queued';
+
+                results.push({
+                    tokenId: idBN.toBigInt(),
                     receipt: {
-                        ethAmount: receiptData.ethAmount,
-                        ethBalance: {
+                        amount: {
                             amount: receiptData.ethAmount.toBigInt(),
                             decimals: 18,
-                            symbol: "ETH"
+                            symbol: "ETH",
                         },
-                        readyAt: new Date(Number(receiptData.readyAt.toString()) * 1000).valueOf(),
+                        readyAt: readyAtMs,
+                        chain: 'ETH',
+                        status,
                     }
                 });
             } catch (err) {
@@ -211,4 +160,40 @@ export class ReceiptClient {
         // Convert to BigNumbers
         return Array.from(owned).map((id) => BigNumber.from(id));
     }
-}
+
+    private async getOwnedReceiptNFTsFor(
+        owner: string,
+        fromBlock = 0,
+        toBlock: number | string = "latest"
+    ): Promise<BigNumber[]> {
+        const receiptContract = this.contract.ReceiptNFT;
+
+        const toLogs = await receiptContract.queryFilter(
+            receiptContract.filters.Transfer(null, owner),
+            fromBlock,
+            toBlock
+        );
+
+        const fromLogs = await receiptContract.queryFilter(
+            receiptContract.filters.Transfer(owner, null),
+            fromBlock,
+            toBlock
+        );
+
+        const owned = new Set<string>();
+
+        for (const e of toLogs) {
+            const tokenId = e.args?.tokenId;
+            if (!tokenId) continue;
+            owned.add(tokenId.toString());
+        }
+
+        for (const e of fromLogs) {
+            const tokenId = e.args?.tokenId;
+            if (!tokenId) continue;
+            owned.delete(tokenId.toString());
+        }
+
+        return Array.from(owned).map((id) => BigNumber.from(id));
+    }
+}

package/src/networks/ethereum/ethereum.ts

@@ -32,9 +32,9 @@ export class EthereumStakingClient implements IStakingClient {
     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 {
@@ -95,7 +95,7 @@ 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)
@@ -107,9 +107,9 @@ export class EthereumStakingClient implements IStakingClient {
      * @param amount  Amount in wei (or something convertible to BigNumber).
      * @returns transaction hash
      */
-    async loadPendingWithdraws(): Promise<WithdrawReceipt[]> {
+    async getPendingWithdraws(): Promise<WithdrawReceipt[]> {
         this.ensureUser();
-        const address = await this.signer!.getAddress();
+        const address = await this.address!;
 
         return await this.receiptClient.fetchWithdrawReceipts(address);
     }
@@ -136,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);
@@ -168,7 +168,7 @@ 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
         // const network = await this.provider.getNetwork();
@@ -208,7 +208,7 @@ export class EthereumStakingClient implements IStakingClient {
         try {
             if (!this.signer) return Promise.resolve(null);
 
-            const walletAddress = await this.signer!.getAddress();
+            const walletAddress = await this.address!;
 
             // 1) Native ETH balance
             const nativeBalance = await this.provider.getBalance(walletAddress);
@@ -314,7 +314,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);
@@ -323,7 +323,7 @@ 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);
     }
@@ -460,7 +460,7 @@ export class EthereumStakingClient implements IStakingClient {
     }): Promise<bigint> {
         this.ensureUser();
 
-        const walletAddress = await this.signer!.getAddress();
+        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.

package/src/networks/ethereum/types.ts

@@ -1,5 +1,5 @@
 import { BigNumber, ethers } from 'ethers';
-import { BalanceView } from '../../types';
+import { BalanceView, ChainSymbol, WithdrawReceipt as UnifiedWithdrawReceipt } from '../../types';
 
 export const CONTRACT_NAMES = [
     // LiqETH contracts
@@ -99,17 +99,20 @@ export interface SharesBurnedEvent {
     tokenValue: BigNumber;
 }
 
+/**
+ * Legacy stake/pretoken receipt (kept for compatibility; not used in withdraw UI).
+ */
 export interface preLaunchReceipt {
     tokenId: bigint;
     receipt: {
-        account: string,
-        currency: number,
-        kind: number,
-        indexAtMint: BalanceView,
-        principal: BalanceView,
-        shares: BalanceView,
-        timestamp: string,
-    }
+        account: string;
+        currency: number;
+        kind: number;
+        indexAtMint: BalanceView;
+        principal: BalanceView;
+        shares: BalanceView;
+        timestamp: string;
+    };
 }
 
 export interface ClaimedEvent {
@@ -117,14 +120,8 @@ export interface ClaimedEvent {
     amount: BigNumber;
 }
 
-export interface WithdrawReceipt {
-    tokenId: bigint;
-    receipt: {
-        ethAmount: BigNumber;
-        ethBalance: BalanceView;
-        readyAt: number;
-    }
-}
+// Unified withdraw receipt type is defined centrally in src/types.ts
+export type WithdrawReceipt = UnifiedWithdrawReceipt;
 
 
 

package/src/networks/solana/clients/convert.client.ts

@@ -0,0 +1,339 @@
+import { AnchorProvider, BN, Program } from '@coral-xyz/anchor';
+import {
+    SystemProgram,
+    TransactionInstruction,
+    StakeProgram,
+    SYSVAR_INSTRUCTIONS_PUBKEY,
+    SYSVAR_CLOCK_PUBKEY,
+    SYSVAR_RENT_PUBKEY,
+    SYSVAR_STAKE_HISTORY_PUBKEY,
+    Connection,
+    PublicKey,
+} from '@solana/web3.js';
+
+import {
+    TOKEN_2022_PROGRAM_ID,
+    ASSOCIATED_TOKEN_PROGRAM_ID,
+    getAssociatedTokenAddressSync,
+} from '@solana/spl-token';
+
+import { LiqsolCoreClientIdl, SolanaProgramService } from '../program';
+import { GlobalAccount, ReceiptData, WalletLike } from '../types';
+import { BalanceView, WithdrawReceipt } from '../../../types';
+import { normalizeToBigInt } from '../utils';
+
+/**
+ * ConvertClient (Solana):
+ * - deposit SOL -> liqSOL
+ * - request withdraw (liqSOL burn -> NFT receipt)
+ * - list withdrawal receipts owned by a user
+ * - build claim_withdraw instruction
+ */
+export class ConvertClient {
+    private program: Program<LiqsolCoreClientIdl>;
+
+    get connection(): Connection {
+        return this.provider.connection;
+    }
+
+    get wallet(): WalletLike {
+        return this.provider.wallet;
+    }
+
+    constructor(
+        private readonly provider: AnchorProvider,
+        private readonly pgs: SolanaProgramService,
+    ) {
+        this.program = pgs.getProgram('liqsolCore');
+    }
+
+    /**
+     * Build a deposit instruction (SOL -> liqSOL).
+     */
+    async buildDepositTx(
+        amount: bigint,
+        user = this.wallet.publicKey,
+    ): Promise<TransactionInstruction> {
+        if (!user) throw new Error('ConvertClient.buildDepositTx: wallet not connected');
+        if (!amount || amount <= BigInt(0))
+            throw new Error('ConvertClient.buildDepositTx: amount must be greater than zero.');
+
+        const depositAuthority = this.pgs.deriveDepositAuthorityPda();
+        const liqsolMint = this.pgs.deriveLiqsolMintPda();
+        const liqsolMintAuthority = this.pgs.deriveLiqsolMintAuthorityPda();
+        const reservePool = this.pgs.deriveReservePoolPda();
+        const vault = this.pgs.deriveVaultPda();
+        const controllerState = this.pgs.deriveStakeControllerStatePda();
+        const payoutState = this.pgs.derivePayoutStatePda();
+        const bucketAuthority = this.pgs.deriveBucketAuthorityPda();
+        const payRateHistory = this.pgs.derivePayRateHistoryPda();
+        const globalConfig = this.pgs.deriveGlobalConfigPda();
+
+        const userAta = getAssociatedTokenAddressSync(liqsolMint, user, true, TOKEN_2022_PROGRAM_ID);
+        const distributionState = this.pgs.deriveDistributionStatePda();
+        const userRecord = this.pgs.deriveUserRecordPda(userAta);
+        const bucketTokenAccount = getAssociatedTokenAddressSync(
+            liqsolMint,
+            bucketAuthority,
+            true,
+            TOKEN_2022_PROGRAM_ID,
+        );
+
+        const seed = Math.floor(Math.random() * 2 ** 32);
+        const ephemeralStake = await this.pgs.deriveEphemeralStakeAddress(user, seed);
+
+        return await this.program.methods
+            .deposit(new BN(amount.toString()), seed)
+            .accounts({
+                user,
+                depositAuthority,
+                systemProgram: SystemProgram.programId,
+                tokenProgram: TOKEN_2022_PROGRAM_ID,
+                associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
+                liqsolProgram: this.pgs.PROGRAM_IDS.LIQSOL_TOKEN,
+                stakeProgram: StakeProgram.programId,
+                liqsolMint,
+                userAta,
+                liqsolMintAuthority,
+                reservePool,
+                vault,
+                ephemeralStake,
+                controllerState,
+                payoutState,
+                bucketAuthority,
+                bucketTokenAccount,
+                userRecord,
+                distributionState,
+                payRateHistory,
+                instructionsSysvar: SYSVAR_INSTRUCTIONS_PUBKEY,
+                clock: SYSVAR_CLOCK_PUBKEY,
+                stakeHistory: SYSVAR_STAKE_HISTORY_PUBKEY,
+                rent: SYSVAR_RENT_PUBKEY,
+                globalConfig,
+            })
+            .instruction();
+    }
+
+    /**
+     * Build a withdraw-request instruction (liqSOL burn -> NFT receipt).
+     */
+    async buildWithdrawTx(
+        amount: bigint,
+        user = this.wallet.publicKey,
+    ): Promise<TransactionInstruction> {
+        if (!user) throw new Error('ConvertClient.buildWithdrawTx: wallet not connected');
+        if (!amount || amount <= BigInt(0))
+            throw new Error('ConvertClient.buildWithdrawTx: amount must be greater than zero.');
+
+        const liqsolMint = this.pgs.deriveLiqsolMintPda();
+        const userAta = getAssociatedTokenAddressSync(liqsolMint, user, true, TOKEN_2022_PROGRAM_ID);
+        const userRecord = this.pgs.deriveUserRecordPda(userAta);
+        const distributionState = this.pgs.deriveDistributionStatePda();
+
+        const global = this.pgs.deriveWithdrawGlobalPda();
+        const reservePool = this.pgs.deriveReservePoolPda();
+        const stakeAllocationState = this.pgs.deriveStakeAllocationStatePda();
+        const stakeMetrics = this.pgs.deriveStakeMetricsPda();
+        const maintenanceLedger = this.pgs.deriveMaintenanceLedgerPda();
+        const globalConfig = this.pgs.deriveGlobalConfigPda();
+
+        const globalAcct: GlobalAccount = await this.program.account.global.fetch(global);
+        const rawId = globalAcct.nextReceiptId;
+        const receiptId = normalizeToBigInt(rawId);
+
+        const mintAuthority = this.pgs.deriveWithdrawMintAuthorityPda();
+        const metadata = this.pgs.deriveWithdrawMintMetadataPda();
+        const nftMint = this.pgs.deriveWithdrawNftMintPda(receiptId);
+        const receiptData = this.pgs.deriveLiqReceiptDataPda(nftMint);
+        const owner = user;
+        const nftAta = getAssociatedTokenAddressSync(nftMint, owner, true, TOKEN_2022_PROGRAM_ID);
+
+        const bucketAuthority = this.pgs.deriveBucketAuthorityPda();
+        const bucketTokenAccount = getAssociatedTokenAddressSync(
+            liqsolMint,
+            bucketAuthority,
+            true,
+            TOKEN_2022_PROGRAM_ID,
+        );
+
+        return await this.program.methods
+            .requestWithdraw(new BN(amount.toString()))
+            .accounts({
+                user,
+                owner,
+                global,
+                liqsolMint,
+                userAta,
+                userRecord,
+                reservePool,
+                stakeAllocationState,
+                stakeMetrics,
+                maintenanceLedger,
+                clock: SYSVAR_CLOCK_PUBKEY,
+                mintAuthority,
+                receiptData,
+                metadata,
+                nftMint,
+                nftAta,
+                distributionState,
+                bucketTokenAccount,
+                tokenProgram: TOKEN_2022_PROGRAM_ID,
+                tokenInterface: TOKEN_2022_PROGRAM_ID,
+                associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
+                systemProgram: SystemProgram.programId,
+                rent: SYSVAR_RENT_PUBKEY,
+                globalConfig,
+            })
+            .instruction();
+    }
+
+    /**
+     * Enumerate withdrawal receipt NFTs owned by `owner`.
+     */
+    async fetchWithdrawReceipts(owner: PublicKey): Promise<WithdrawReceipt[]> {
+        const globalPda = this.pgs.deriveWithdrawGlobalPda();
+        const globalAcct: GlobalAccount = await this.program.account.global.fetch(globalPda);
+        const nextId = normalizeToBigInt(globalAcct.nextReceiptId);
+
+        const mintToId = new Map<string, bigint>();
+        for (let i = BigInt(0); i < nextId; i++) {
+            const mint = this.pgs.deriveWithdrawNftMintPda(i);
+            mintToId.set(mint.toBase58(), i);
+        }
+
+        const tokenAccounts = await this.connection.getParsedTokenAccountsByOwner(owner, {
+            programId: TOKEN_2022_PROGRAM_ID,
+        });
+
+        const receipts: WithdrawReceipt[] = [];
+
+        for (const { pubkey, account } of tokenAccounts.value) {
+            const info: any = account.data?.['parsed']?.info;
+            if (!info) continue;
+            const amount = info.tokenAmount;
+            const decimals = Number(amount?.decimals ?? 0);
+            const uiAmount = Number(amount?.uiAmount ?? 0);
+            if (decimals !== 0 || uiAmount !== 1) continue;
+
+            const mintStr: string | undefined = info.mint;
+            if (!mintStr) continue;
+            const receiptId = mintToId.get(mintStr);
+            if (receiptId === undefined) continue;
+
+            const mintKey = new PublicKey(mintStr);
+            const receiptDataPda = this.pgs.deriveLiqReceiptDataPda(mintKey);
+
+            let receiptData: ReceiptData;
+            try {
+                const raw = await this.program.account.liqReceiptData.fetch(receiptDataPda);
+                receiptData = {
+                    receiptId: normalizeToBigInt(raw.receiptId),
+                    liqports: normalizeToBigInt(raw.liqports),
+                    epoch: normalizeToBigInt(raw.epoch),
+                    fulfilled: Boolean(raw.fulfilled),
+                };
+            } catch (err) {
+                console.warn(`ConvertClient: failed to fetch receipt data for mint ${mintStr}`, err);
+                continue;
+            }
+
+            const { etaMs, readyAtMs } = await this.estimateEpochEta(receiptData.epoch);
+            const status = receiptData.fulfilled ? 'claimed' : etaMs <= 0 ? 'ready' : 'queued';
+
+            const amountView: BalanceView = {
+                amount: receiptData.liqports,
+                decimals: 9,
+                symbol: 'SOL',
+            };
+
+            receipts.push({
+                tokenId: receiptData.receiptId,
+                receipt: {
+                    amount: amountView,
+                    readyAt: readyAtMs,
+                    chain: 'SOL',
+                    epoch: receiptData.epoch,
+                    status,
+                    mint: mintKey.toBase58(),
+                    ownerAta: pubkey.toBase58(),
+                },
+            });
+        }
+
+        return receipts;
+    }
+
+    /**
+     * Build the claim_withdraw instruction for a given receiptId.
+     */
+    async buildClaimWithdrawTx(
+        receiptId: bigint,
+        user: PublicKey,
+    ): Promise<TransactionInstruction> {
+        const mintAccount = this.pgs.deriveWithdrawNftMintPda(receiptId);
+        const receiptData = this.pgs.deriveLiqReceiptDataPda(mintAccount);
+        const ownerAta = getAssociatedTokenAddressSync(
+            mintAccount,
+            user,
+            true,
+            TOKEN_2022_PROGRAM_ID,
+        );
+
+        const accounts = {
+            user,
+            global: this.pgs.deriveWithdrawGlobalPda(),
+            mintAuthority: this.pgs.deriveWithdrawMintAuthorityPda(),
+            receiptData,
+            mintAccount,
+            ownerAta,
+            reservePool: this.pgs.deriveReservePoolPda(),
+            vault: this.pgs.deriveVaultPda(),
+            clock: SYSVAR_CLOCK_PUBKEY,
+            stakeHistory: SYSVAR_STAKE_HISTORY_PUBKEY,
+            globalConfig: this.pgs.deriveGlobalConfigPda(),
+            tokenProgram: TOKEN_2022_PROGRAM_ID,
+            stakeProgram: StakeProgram.programId,
+            systemProgram: SystemProgram.programId,
+            associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
+        };
+
+        return this.program.methods.claimWithdraw().accounts(accounts).instruction();
+    }
+
+    /**
+     * Estimate ready time for target epoch using recent slot time.
+     */
+    private async estimateEpochEta(targetEpoch: bigint): Promise<{ etaMs: number; readyAtMs: number }> {
+        const conn = this.connection;
+        const epochInfo = await conn.getEpochInfo();
+        const schedule = await conn.getEpochSchedule();
+        const currentEpoch = BigInt(epochInfo.epoch);
+
+        if (targetEpoch <= currentEpoch) {
+            const now = Date.now();
+            return { etaMs: 0, readyAtMs: now };
+        }
+
+        let slotTimeSec = 0.4;
+        try {
+            const samples = await conn.getRecentPerformanceSamples(1);
+            if (samples?.length) {
+                const s = samples[0];
+                slotTimeSec = s.numSlots > 0 ? s.samplePeriodSecs / s.numSlots : slotTimeSec;
+            }
+        } catch (_) {
+            // ignore
+        }
+
+        const slotsPerEpoch = BigInt(schedule.slotsPerEpoch);
+        const slotsRemainingInCurrent = slotsPerEpoch - BigInt(epochInfo.slotIndex);
+        const epochsRemaining = targetEpoch - currentEpoch - BigInt(1);
+        const slotsRemaining =
+            (epochsRemaining > 0 ? epochsRemaining * slotsPerEpoch : BigInt(0)) +
+            slotsRemainingInCurrent;
+
+        const etaSeconds = Number(slotsRemaining) * slotTimeSec;
+        const etaMs = Math.max(0, Math.round(etaSeconds * 1000));
+        return { etaMs, readyAtMs: Date.now() + etaMs };
+    }
+}