@wireio/stake 1.0.0 → 1.0.69

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
@@ -11,7 +11,7 @@ export const CONTRACT_NAMES = [
     "DepositManager",
     "WithdrawalVault",
     "StakingModule",
-    "YieldOracle",
+    // "YieldOracle",
 
     //Outpost contracts
     "OutpostManagerAuthority",
@@ -90,7 +90,17 @@ export interface WithdrawnStakeEvent {
 export interface WithdrawnStakeResult extends Result {
     /** Parsed WithdrawnStake event, if present */
     withdrawnstake?: WithdrawnStakeEvent;
+}
+
+export interface DepositAndStakeResult extends Result {
+    /** Parsed Staked event, if present */
+    staked?: StakedEvent;
+}
+
+export interface DepositAndPurchaseResult extends Result {
+}
 
+export interface UnstakeAndWithdrawResult extends Result {
 }
 
 export interface SharesBurnedEvent {
@@ -99,15 +109,34 @@ 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 {
+    user: string;
+    amount: BigNumber;
+}
+
+// Unified withdraw receipt type is defined centrally in src/types.ts
+export type WithdrawReceipt = UnifiedWithdrawReceipt;
+
+
+
+export interface ValidatorDepositedEvent {
+    sender: string;
+    amount: BigNumber;
+    shares: BigNumber
+}

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

@@ -0,0 +1,377 @@
+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> {
+        const program: any = this.program;
+        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 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();
+    }
+
+    async buildRegisterUserIx(
+        user = this.wallet.publicKey,
+    ): Promise<TransactionInstruction> {
+        const program: any = this.program;
+        if (!user) throw new Error('ConvertClient.buildRegisterUserIx: wallet not connected');
+
+        const liqsolMint = this.pgs.deriveLiqsolMintPda();
+        const distributionState = this.pgs.deriveDistributionStatePda();
+        const bucketAuthority = this.pgs.deriveBucketAuthorityPda();
+        const userAta = getAssociatedTokenAddressSync(liqsolMint, user, true, TOKEN_2022_PROGRAM_ID);
+        const userRecord = this.pgs.deriveUserRecordPda(userAta);
+        const bucketTokenAccount = getAssociatedTokenAddressSync(
+            liqsolMint,
+            bucketAuthority,
+            true,
+            TOKEN_2022_PROGRAM_ID,
+        );
+
+        return program.methods
+            .registerUser()
+            .accounts({
+                payer: user,
+                userAta,
+                userRecord,
+                distributionState,
+                bucketAuthority,
+                bucketTokenAccount,
+                systemProgram: SystemProgram.programId,
+            })
+            .instruction();
+    }
+
+    /**
+     * Build a withdraw-request instruction (liqSOL burn -> NFT receipt).
+     */
+    async buildWithdrawTx(
+        amount: bigint,
+        user = this.wallet.publicKey,
+    ): Promise<TransactionInstruction> {
+        const program: any = this.program;
+        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 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 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 program: any = this.program;
+        const globalPda = this.pgs.deriveWithdrawGlobalPda();
+        const globalAcct: GlobalAccount = await 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 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 program: any = this.program;
+        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 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(60);
+            if (samples?.length) {
+                const valid = samples.filter(s => s.numSlots > 0);
+                if (valid.length) {
+                    slotTimeSec = valid.reduce((sum, s) => sum + s.samplePeriodSecs / s.numSlots, 0) / valid.length;
+                }
+            }
+        } 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 };
+    }
+}

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

@@ -1,19 +1,13 @@
 import { AnchorProvider, Program, BN } from '@coral-xyz/anchor';
-import { PublicKey } from '@solana/web3.js';
-
-import { SolanaProgramService } from '../program';
-import type { LiqsolCore } from '../../../assets/solana/types/liqsol_core';
-import {
-    deriveDistributionStatePda,
-    deriveGlobalConfigPda,
-    deriveLiqsolMintPda,
-    derivePayRateHistoryPda,
-    deriveUserRecordPda,
-} from '../constants';
+import { PublicKey, SystemProgram, TransactionInstruction } from '@solana/web3.js';
+
+import { LiqsolCoreClientIdl, SolanaProgramService } from '../program';
 import type { DistributionState, DistributionUserRecord, GlobalConfig, PayRateEntry, PayRateHistory } from '../types';
 import { getAssociatedTokenAddressSync, TOKEN_2022_PROGRAM_ID } from '@solana/spl-token';
 import { ceilDiv } from '../utils';
 
+const INDEX_SCALE_BN = new BN('1000000000000');
+
 /**
  * Distribution client – wraps the distribution portion of the liqsol_core
  * program in the *new* shares-only model.
@@ -33,26 +27,38 @@ import { ceilDiv } from '../utils';
  *  - DistributionState + UserRecord track *shares* for yield.
  */
 export class DistributionClient {
-    private program: Program<LiqsolCore>;
+    private program: Program<LiqsolCoreClientIdl>;
 
-    constructor(private provider: AnchorProvider) {
-        const svc = new SolanaProgramService(provider);
-        this.program = svc.getProgram('liqsolCore');
+    constructor(
+        private readonly provider: AnchorProvider,
+        private readonly pgs: SolanaProgramService
+    ) {
+        this.program = pgs.getProgram('liqsolCore');
     }
 
     get connection() {
         return this.provider.connection;
     }
 
+    private async getTokenBalance(ata: PublicKey): Promise<BN> {
+        try {
+            const bal = await this.connection.getTokenAccountBalance(ata);
+            return new BN(bal.value.amount);
+        } catch {
+            return new BN(0);
+        }
+    }
+
     /**
      * Fetch the global distribution state account.
      *
      * IDL account name: "distributionState"
      */
     async getDistributionState(): Promise<DistributionState | null> {
-        const pda = deriveDistributionStatePda();
+        const pda = this.pgs.deriveDistributionStatePda();
+        const program: any = this.program;
         try {
-            return await this.program.account.distributionState.fetch(pda);
+            return await program.account.distributionState.fetch(pda);
         } catch {
             return null;
         }
@@ -65,10 +71,11 @@ export class DistributionClient {
      * IDL account name: "payRateHistory"
      */
     async getPayRateHistory(): Promise<PayRateHistory | null> {
-        const pda = derivePayRateHistoryPda();
+        const pda = this.pgs.derivePayRateHistoryPda();
+        const program: any = this.program;
         try {
             // Anchor types map directly onto our PayRateHistory TS type
-            return (await this.program.account.payRateHistory.fetch(
+            return (await program.account.payRateHistory.fetch(
                 pda,
             )) as PayRateHistory;
         } catch {
@@ -82,11 +89,12 @@ export class DistributionClient {
      * IDL account name: "globalConfig"
      */
     async getGlobalConfig(): Promise<GlobalConfig | null> {
-        const pda = deriveGlobalConfigPda();
+        const pda = this.pgs.deriveGlobalConfigPda();
+        const program: any = this.program;
         try {
-            return (await this.program.account.globalConfig.fetch(
+            return (await program.account.globalConfig.fetch(
                 pda,
-            ));
+            )) as GlobalConfig;
         } catch {
             return null;
         }
@@ -99,19 +107,20 @@ export class DistributionClient {
     async getUserRecord(
         ownerOrAta: PublicKey,
     ): Promise<DistributionUserRecord | null> {
-        const liqsolMint = deriveLiqsolMintPda();
+        const program: any = this.program;
+        const liqsolMint = this.pgs.deriveLiqsolMintPda();
 
         // 1) Try treating ownerOrAta as a WALLET: derive its liqSOL ATA, then userRecord.
         try {
             const ata = getAssociatedTokenAddressSync(
                 liqsolMint,
                 ownerOrAta,
-                false,
+                true,
                 TOKEN_2022_PROGRAM_ID,
             );
-            const pdaFromWallet = deriveUserRecordPda(ata);
+            const pdaFromWallet = this.pgs.deriveUserRecordPda(ata);
             const recFromWallet =
-                await this.program.account.userRecord.fetchNullable(pdaFromWallet);
+                await program.account.userRecord.fetchNullable(pdaFromWallet);
             if (recFromWallet) {
                 return recFromWallet;
             }
@@ -121,8 +130,8 @@ export class DistributionClient {
 
         // 2) Fallback: treat ownerOrAta as already being the TOKEN ACCOUNT.
         try {
-            const pdaFromAta = deriveUserRecordPda(ownerOrAta);
-            return await this.program.account.userRecord.fetchNullable(pdaFromAta);
+            const pdaFromAta = this.pgs.deriveUserRecordPda(ownerOrAta);
+            return await program.account.userRecord.fetchNullable(pdaFromAta);
         } catch {
             return null;
         }
@@ -167,6 +176,109 @@ export class DistributionClient {
         return { shares: userShares, totalShares, ratio };
     }
 
+    /**
+     * Compute claimable liqSOL for a wallet:
+     * claimable = max(0, entitled - actual)
+     * entitled = floor(shares * syncedIndex / 1e12)
+     *
+     * `syncedIndex` mirrors on-chain `sync_index` behavior by incorporating any
+     * unsynced bucket delta (bucket_balance - last_bucket_balance).
+     */
+    async getClaimableLiqsol(user: PublicKey): Promise<BN> {
+        const liqsolMint = this.pgs.deriveLiqsolMintPda();
+        const bucketAuthority = this.pgs.deriveBucketAuthorityPda();
+
+        const userAta = getAssociatedTokenAddressSync(
+            liqsolMint,
+            user,
+            true,
+            TOKEN_2022_PROGRAM_ID,
+        );
+        const bucketTokenAccount = getAssociatedTokenAddressSync(
+            liqsolMint,
+            bucketAuthority,
+            true,
+            TOKEN_2022_PROGRAM_ID,
+        );
+
+        const [distributionState, userRecord, actualBalance, bucketBalance] = await Promise.all([
+            this.getDistributionState(),
+            this.getUserRecord(user),
+            this.getTokenBalance(userAta),
+            this.getTokenBalance(bucketTokenAccount),
+        ]);
+
+        if (!distributionState || !userRecord) {
+            return new BN(0);
+        }
+
+        let syncedIndex = new BN(distributionState.currentIndex.toString());
+        const totalShares = new BN(distributionState.totalShares.toString());
+        const lastBucketBalance = new BN(distributionState.lastBucketBalance.toString());
+
+        if (totalShares.gt(new BN(0)) && bucketBalance.gt(lastBucketBalance)) {
+            const delta = bucketBalance.sub(lastBucketBalance);
+            const indexDelta = delta.mul(INDEX_SCALE_BN).div(totalShares);
+            if (indexDelta.gt(new BN(0))) {
+                syncedIndex = syncedIndex.add(indexDelta);
+            }
+        }
+
+        const shares = new BN(userRecord.shares.toString());
+        const entitled = shares.mul(syncedIndex).div(INDEX_SCALE_BN);
+
+        if (entitled.lte(actualBalance)) {
+            return new BN(0);
+        }
+        return entitled.sub(actualBalance);
+    }
+
+    /**
+     * Build claim_rewards instruction for a wallet.
+     */
+    async buildClaimRewardsIx(user: PublicKey): Promise<TransactionInstruction> {
+        const program: any = this.program;
+        const liqsolMint = this.pgs.deriveLiqsolMintPda();
+        const distributionState = this.pgs.deriveDistributionStatePda();
+        const bucketAuthority = this.pgs.deriveBucketAuthorityPda();
+
+        const userAta = getAssociatedTokenAddressSync(
+            liqsolMint,
+            user,
+            true,
+            TOKEN_2022_PROGRAM_ID,
+        );
+        const bucketTokenAccount = getAssociatedTokenAddressSync(
+            liqsolMint,
+            bucketAuthority,
+            true,
+            TOKEN_2022_PROGRAM_ID,
+        );
+
+        const userRecord = this.pgs.deriveUserRecordPda(userAta);
+        const bucketUserRecord = this.pgs.deriveUserRecordPda(bucketTokenAccount);
+        const extraAccountMetaList = this.pgs.deriveExtraAccountMetaListPda(liqsolMint);
+
+        return program.methods
+            .claimRewards()
+            .accounts({
+                user,
+                userAta,
+                userRecord,
+                bucketUserRecord,
+                distributionState,
+                extraAccountMetaList,
+                liqsolCoreProgram: this.pgs.PROGRAM_IDS.LIQSOL_CORE,
+                transferHookProgram: this.pgs.PROGRAM_IDS.TRANSFER_HOOK,
+                liqsolMint,
+                bucketAuthority,
+                bucketTokenAccount,
+                tokenProgram: TOKEN_2022_PROGRAM_ID,
+                systemProgram: SystemProgram.programId
+            })
+            .instruction();
+    }
+
     /**
      * Compute an average scaled pay rate over the most recent `windowSize`
      * valid entries in the pay-rate history circular buffer.
@@ -248,4 +360,4 @@ export class DistributionClient {
         // Same behavior as the dashboard: use a ceiling-like average
         return ceilDiv(sum, new BN(valid));
     }
-}
+}