@wireio/stake 0.1.2 → 0.1.69

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

@@ -1,12 +1,8 @@
 import { AnchorProvider, Program } from '@coral-xyz/anchor';
 import { PublicKey } from '@solana/web3.js';
 
-import { SolanaProgramService } from '../program';
-import type { ValidatorLeaderboard } from '../../../assets/solana/types/validator_leaderboard';
-import {
-    deriveLeaderboardStatePda,
-    deriveValidatorRecordPda,
-} from '../constants';
+import { SolanaProgramService, ValidatorLeaderboardClientIdl } from '../program';
+import { LeaderboardState, ValidatorRecord } from '../types';
 
 /**
  * Simple read client for the validator_leaderboard program.
@@ -14,15 +10,17 @@ import {
  * Adjust account names/fields to match your IDL (state, validatorRecord, etc).
  */
 export class LeaderboardClient {
-    private program: Program<ValidatorLeaderboard>;
+    private program: Program<ValidatorLeaderboardClientIdl>;
 
-    constructor(private provider: AnchorProvider) {
-        const svc = new SolanaProgramService(provider);
-        this.program = svc.getProgram('validatorLeaderboard');
+    constructor(
+        private readonly provider: AnchorProvider,
+        private readonly pgs: SolanaProgramService
+    ) {
+        this.program = pgs.getProgram('validatorLeaderboard');
     }
 
-    async getState(): Promise<any | null> {
-        const pda = deriveLeaderboardStatePda();
+    async getState(): Promise<LeaderboardState | null> {
+        const pda = this.pgs.deriveLeaderboardStatePda();
         try {
             // Assumes account name "leaderboardState"
             return await this.program.account.leaderboardState.fetch(pda);
@@ -31,8 +29,8 @@ export class LeaderboardClient {
         }
     }
 
-    async getValidatorRecord(voteAccount: PublicKey): Promise<any | null> {
-        const pda = deriveValidatorRecordPda(voteAccount);
+    async getValidatorRecord(voteAccount: PublicKey): Promise<ValidatorRecord | null> {
+        const pda = this.pgs.deriveValidatorRecordPda(voteAccount);
         try {
             // Assumes account name "validatorRecord"
             return await this.program.account.validatorRecord.fetchNullable(pda);
@@ -42,18 +40,62 @@ export class LeaderboardClient {
     }
 
     /**
-     * Convenience helper to fetch and sort top validators by score.
-     * Assumes `validatorRecord` has a numeric `score` field in the IDL.
+     * Convenience helper to fetch and return top validators ordered
+     * by the on-chain leaderboard scores.
+     *
+     * Uses:
+     *  - `leaderboardState.scores`
+     *  - `leaderboardState.sortedIndices`
+     *  - `validatorRecord.registryIndex`
+     *
+     * Fallback: if leaderboardState can't be fetched, we sort by
+     * `creditsObserved` descending.
      */
-    async getTopValidators(limit = 20): Promise<any[]> {
-        const records = await (this.program.account as any).validatorRecord.all();
-        const sorted = (records as Array<{ publicKey: PublicKey; account: any }>).sort(
-            (a, b) => {
-                const sa = BigInt(a.account.score?.toString?.() ?? '0');
-                const sb = BigInt(b.account.score?.toString?.() ?? '0');
-                return sb > sa ? 1 : sb < sa ? -1 : 0;
-            },
-        );
-        return sorted.slice(0, limit);
+    async getTopValidators(limit = 20): Promise<ValidatorRecord[]> {
+        // Try to use the leaderboard state first
+        try {
+            const leaderboardPda = this.pgs.deriveLeaderboardStatePda();
+            const leaderboard: LeaderboardState 
+                = await this.program.account.leaderboardState.fetch(leaderboardPda);
+
+            const all = await this.program.account.validatorRecord.all();
+            const byIndex = new Map<number, ValidatorRecord>();
+
+            for (const r of all) {
+                const vr = r.account;
+                byIndex.set(vr.registryIndex, vr);
+            }
+
+            const max = Math.min(
+                limit,
+                leaderboard.numValidators,
+                leaderboard.sortedIndices.length,
+            );
+
+            const top: ValidatorRecord[] = [];
+            for (let i = 0; i < max; i++) {
+                const idx = leaderboard.sortedIndices[i];
+                const rec = byIndex.get(idx);
+                if (rec) {
+                    top.push(rec);
+                }
+            }
+
+            return top;
+        } catch (e) {
+            // Fallback: no leaderboardState available, sort by creditsObserved.
+            const all = await this.program.account.validatorRecord.all();
+
+            all.sort((a, b) => {
+                const va = a.account;
+                const vb = b.account;
+                const ca = va.creditsObserved;
+                const cb = vb.creditsObserved;
+                // BN.cmp: -1 if a < b, 0 if equal, 1 if a > b
+                return cb.cmp(ca);
+            });
+
+            return all.slice(0, limit).map(r => r.account);
+        }
     }
 }

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

@@ -0,0 +1,342 @@
+import { AnchorProvider, BN, Program } from '@coral-xyz/anchor';
+import {
+    PublicKey,
+    SystemProgram,
+    TransactionInstruction,
+} from '@solana/web3.js';
+import {
+    ASSOCIATED_TOKEN_PROGRAM_ID,
+    TOKEN_2022_PROGRAM_ID,
+} from '@solana/spl-token';
+
+import {
+    OutpostAccounts,
+    buildOutpostAccounts,
+    deriveDefaultWireAccount,
+    safeFetch,
+} from '../utils';
+
+import {
+    OutpostWireStateSnapshot,
+    SharesPreview,
+    TrancheState,
+    WalletLike,
+} from '../types';
+import { INDEX_SCALE } from '../constants';
+import { LiqsolCoreClientIdl, SolanaProgramService } from '../program';
+
+/**
+ * OutpostClient
+ *
+ * Read-only + preview helper for:
+ *  - Outpost config + per-user pretokens
+ *  - Tranche ladder snapshot
+ *  - Pretoken preview math
+ *
+ * Write helpers:
+ *  - buildStakeIx   → liqsol_core::synd
+ *  - buildUnstakeIx → liqsol_core::desynd
+ *
+ * All PDAs / ATAs are sourced via buildOutpostAccounts, which is kept
+ * in sync with the on-chain PDAs and capital-staking Wire utils.
+ */
+export class OutpostClient {
+    private readonly program: Program<LiqsolCoreClientIdl>;
+
+    constructor(
+        private readonly provider: AnchorProvider,
+        private readonly pgs: SolanaProgramService,
+    ) {
+        this.program = pgs.getProgram('liqsolCore');
+    }
+
+    get connection() {
+        return this.provider.connection;
+    }
+
+    get wallet(): WalletLike {
+        return this.provider.wallet as unknown as WalletLike;
+    }
+
+    /**
+     * Build all outpost-related PDAs / ATAs for a given user.
+     * Defaults to the connected wallet.
+     */
+    async buildAccounts(user?: PublicKey): Promise<OutpostAccounts> {
+        const userPk = user ?? this.wallet.publicKey;
+        if (!userPk) {
+            throw new Error('OutpostClient.buildAccounts: wallet not connected');
+        }
+        return buildOutpostAccounts(this.connection, userPk, this.pgs);
+    }
+
+    /**
+     * Internal helper: get raw token balance (BN) for a given ATA.
+     */
+    private async getTokenBalance(ata: PublicKey): Promise<BN> {
+        const bal = await this.connection.getTokenAccountBalance(ata);
+        return new BN(bal.value.amount);
+    }
+
+    /**
+     * Fetch an OutpostAccount, handling legacy accounts that pre-date the
+     * three trailing Option<u64> fields.  If the normal decode throws a
+     * RangeError we re-fetch the raw data, pad it to the expected size
+     * (zeros → Option::None for each missing field), and let Anchor's
+     * coder decode the padded buffer.
+     */
+    private async fetchOutpostAccount(address: PublicKey) {
+        try {
+            return await this.program.account.outpostAccount.fetchNullable(address);
+        } catch (e) {
+            if (!(e instanceof RangeError)) throw e;
+
+            const info = await this.connection.getAccountInfo(address);
+            if (!info) return null;
+
+            // 3 × Option<u64> encoded as 1-byte tag (0x00 = None) = 3 bytes
+            // when present (Some) each is 9 bytes, but None is just 0x00
+            const EXPECTED_SIZE = info.data.length + 3;
+            const padded = Buffer.alloc(EXPECTED_SIZE);
+            info.data.copy(padded);
+            // trailing bytes are already 0x00 → Option::None for each field
+
+            return this.program.coder.accounts.decode(
+                'outpostAccount',
+                padded,
+            );
+        }
+    }
+
+    /**
+     * Fetch the core "Wire state" for Outpost / pretokens for a given user.
+     */
+    async fetchWireState(user?: PublicKey): Promise<OutpostWireStateSnapshot> {
+        const userPk = user ?? this.wallet.publicKey;
+        if (!userPk) throw new Error('OutpostClient.fetchWireState: wallet not connected');
+
+        const pdas = await this.buildAccounts(userPk);
+        const [
+            globalState,
+            outpostAccount,
+            distributionState,
+            userPretokenRecord,
+            trancheState,
+            liqsolPoolBalance,
+            userLiqsolBalance,
+        ] = await Promise.all([
+            safeFetch(this.program.account.globalState.fetch(pdas.globalState), 'globalState'),
+            safeFetch(this.fetchOutpostAccount(pdas.outpostAccount), 'outpostAccount'),
+            safeFetch(this.program.account.distributionState.fetchNullable(pdas.distributionState), 'distributionState'),
+            safeFetch(this.program.account.userPretokenRecord.fetchNullable(pdas.userPretokenRecord), 'userPretokenRecord'),
+            safeFetch(this.program.account.trancheState.fetchNullable(pdas.trancheState), 'trancheState'),
+            safeFetch(this.getTokenBalance(pdas.liqsolPoolAta), 'liqsolPoolAta'),
+            safeFetch(this.getTokenBalance(pdas.userAta), 'userAta'),
+        ]);
+
+        return {
+            globalState,
+            outpostAccount,
+            distributionState,
+            trancheState,
+            userPretokenRecord,
+            liqsolPoolBalance,
+            userLiqsolBalance,
+        };
+    }
+
+
+
+    // -------------------------------------------------------------------------
+    // Outpost stake / unstake builders (syndicate_liqsol_to_wire / desynd)
+    // -------------------------------------------------------------------------
+
+    /**
+     * Build the `syndicate_liqsol_to_wire` (stake) instruction:
+     *   user liqSOL ATA → liqSOL pool ATA, bridged to the Wire chain.
+     *
+     * @param amountLamports  Amount of liqSOL to stake (in lamports / base units).
+     * @param user            Solana signer. Defaults to the connected wallet.
+     * @param wireAccount     Wire chain recipient account name. Defaults to the
+     *                        canonical name derived from the user's public key via
+     *                        `deriveDefaultWireAccount`.
+     */
+    async buildStakeIx(
+        amountLamports: bigint,
+        user: PublicKey = this.wallet.publicKey,
+        wireAccount?: string,
+    ): Promise<TransactionInstruction> {
+        if (!user) {
+            throw new Error('OutpostClient.buildStakeIx: wallet not connected');
+        }
+
+        const a = await this.buildAccounts(user);
+        const recipient = wireAccount ?? deriveDefaultWireAccount(user);
+
+        return this.program.methods
+            .syndicateLiqsolToWire(recipient, new BN(amountLamports.toString()))
+            .accounts({
+                user,
+                liqsolMint: a.liqsolMint,
+                distributionState: a.distributionState,
+                globalState: a.globalState,
+                userAta: a.userAta,
+                senderUserRecord: a.userUserRecord,
+                poolAuthority: a.poolAuthority,
+                liqsolPoolAta: a.liqsolPoolAta,
+                poolUserRecord: a.liqsolPoolUserRecord,
+                bridgeState: a.bridgeState,
+                extraAccountMetaList: a.extraAccountMetaList,
+                liqsolCoreProgram: this.pgs.PROGRAM_IDS.LIQSOL_CORE,
+                transferHookProgram: this.pgs.PROGRAM_IDS.TRANSFER_HOOK,
+                bucketAuthority: a.bucketAuthority,
+                bucketTokenAccount: a.bucketTokenAccount,
+                bucketUserRecord: a.bucketUserRecord,
+                tokenProgram: TOKEN_2022_PROGRAM_ID,
+                associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
+                systemProgram: SystemProgram.programId,
+                globalConfig: a.globalConfig,
+                oppEpochState: a.oppEpochState,
+                pendingAttestations: a.pendingAttestations,
+            })
+            .instruction();
+    }
+
+    /**
+     * Build the `desynd` (unstake / desync) instruction:
+     *   liqSOL pool ATA → user liqSOL ATA
+     *
+     * When Wire is in PostLaunch mode this instruction emits a `DesyncRequest`
+     * OPP attestation and does NOT immediately return tokens.  The Wire chain
+     * relay picks up the attestation, and an admin subsequently executes
+     * `complete_withdraw` to deliver the tokens to the user.
+     *
+     * In PreLaunch mode the tokens are returned directly.
+     */
+    async buildUnstakeIx(
+        amountLamports: bigint,
+        user?: PublicKey,
+    ): Promise<TransactionInstruction> {
+        const userPk = user ?? this.wallet.publicKey;
+        if (!userPk) {
+            throw new Error('OutpostClient.buildUnstakeIx: wallet not connected');
+        }
+
+        const a = await this.buildAccounts(userPk);
+
+        return this.program.methods
+            .desynd(new BN(amountLamports.toString()))
+            .accounts({
+                user: userPk,
+                liqsolMint: a.liqsolMint,
+                globalState: a.globalState,
+                distributionState: a.distributionState,
+                userAta: a.userAta,
+                poolAuthority: a.poolAuthority,
+                bucketAuthority: a.bucketAuthority,
+                bucketTokenAccount: a.bucketTokenAccount,
+                bucketUserRecord: a.bucketUserRecord,
+                senderUserRecord: a.liqsolPoolUserRecord,
+                receiverUserRecord: a.userUserRecord,
+                extraAccountMetaList: a.extraAccountMetaList,
+                liqsolCoreProgram: this.pgs.PROGRAM_IDS.LIQSOL_CORE,
+                transferHookProgram: this.pgs.PROGRAM_IDS.TRANSFER_HOOK,
+                liqsolPoolAta: a.liqsolPoolAta,
+                outpostAccount: a.outpostAccount,
+                tokenProgram: TOKEN_2022_PROGRAM_ID,
+                systemProgram: SystemProgram.programId,
+                associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
+                globalConfig: a.globalConfig,
+                oppEpochState: a.oppEpochState,
+                pendingAttestations: a.pendingAttestations,
+                pretokenPurchaseHistory: a.pretokenPurchaseHistory,
+            })
+            .instruction();
+    }
+
+    // -------------------------------------------------------------------------
+    // Pretoken preview helper (unchanged)
+    // -------------------------------------------------------------------------
+
+    /**
+     * Local preview for "how many pretokens would I get for this liqSOL
+     * amount at the current tranche price and SOL/USD price?"
+     *
+     *   SCALE = 1e8
+     *   usdValue = solAmountLamports * solPriceUsd / 1e9
+     *   pretokens = usdValue * SCALE / pretokenPriceUsd
+     *
+     * All values are BN integers; solPriceUsd and pretokenPriceUsd are 1e8 scaled.
+     */
+    previewPretokens(params: {
+        liqsolAmountLamports: BN;
+        solPriceUsd: BN; // 1e8 scale
+        trancheState: TrancheState;
+    }): SharesPreview {
+        const { liqsolAmountLamports, solPriceUsd, trancheState } = params;
+
+        // Current tranche price in USD (1e8 scale)
+        const pretokenPriceUsd = new BN(
+            trancheState.currentTranchePriceUsd.toString(),
+        );
+
+        const SCALE = new BN('100000000'); // 1e8
+
+        // usdValue = (lamports * solPriceUsd) / 1e9
+        const usdValue = liqsolAmountLamports
+            .mul(solPriceUsd)
+            .div(new BN(1_000_000_000));
+
+        const estimatedPretokens = usdValue.mul(SCALE).div(pretokenPriceUsd);
+
+        return {
+            liqsolAmountLamports,
+            solPriceUsd,
+            pretokenPriceUsd,
+            estimatedPretokens,
+        };
+    }
+
+    /**
+     * Convert liqSOL tokens (lamports) → Outpost “shares”, rounding UP
+     * when there is any remainder.
+     *
+     * This matches the on-chain logic and the capital-staking helper:
+     *
+     *   INDEX_SCALE = 1e12
+     *   numerator   = amount * INDEX_SCALE
+     *   shares      = numerator / currentIndex
+     *   remainder   = numerator % currentIndex
+     *   if remainder > 0 → shares + 1
+     */
+    static tokensToShares(amount: BN, currentIndex: BN): BN {
+        const numerator = amount.mul(new BN(INDEX_SCALE));
+        const shares = numerator.div(currentIndex);
+        const remainder = numerator.mod(currentIndex);
+        return remainder.eqn(0) ? shares : shares.addn(1);
+    }
+
+    /**
+     * Format a 1e8-scaled integer (e.g. USD price, pretokens, etc.)
+     * into a fixed 8-decimal string.
+     *
+     * Examples:
+     *   0          -> "0.00000000"
+     *   1          -> "0.00000001"
+     *   100000000  -> "1.00000000"
+     *   123456789  -> "1.23456789"
+     */
+    static formatScale8(value: BN): string {
+        const decimals = 8;
+        const valueStr = value.toString();
+
+        if (valueStr.length <= decimals) {
+            const padding = '0'.repeat(decimals - valueStr.length);
+            return `0.${padding}${valueStr}`;
+        }
+
+        const intPart = valueStr.slice(0, valueStr.length - decimals);
+        const decPart = valueStr.slice(valueStr.length - decimals);
+        return `${intPart}.${decPart}`;
+    }
+}

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

@@ -0,0 +1,214 @@
+import { AnchorProvider, BN, Program } from '@coral-xyz/anchor';
+import type { TransactionInstruction, Connection } from '@solana/web3.js';
+import { PublicKey, SystemProgram } from '@solana/web3.js';
+import {
+    TOKEN_2022_PROGRAM_ID,
+    ASSOCIATED_TOKEN_PROGRAM_ID,
+} from '@solana/spl-token';
+
+import {
+    buildOutpostAccounts,
+    type OutpostAccounts,
+} from '../utils';
+
+import { LiqsolCoreClientIdl, SolanaProgramService } from '../program';
+
+import {
+    GlobalState,
+    PriceHistory,
+    TrancheState,
+    WalletLike,
+    OutpostAccount,
+    UserPretokenRecord,
+} from '../types';
+
+import {
+    CHAINLINK_FEED,
+    CHAINLINK_PROGRAM,
+} from '../constants';
+
+export class TokenClient {
+    private readonly program: Program<LiqsolCoreClientIdl>;
+
+    get wallet(): WalletLike {
+        return this.provider.wallet;
+    }
+
+    get connection(): Connection {
+        return this.provider.connection;
+    }
+
+    constructor(
+        private readonly provider: AnchorProvider,
+        private readonly pgs: SolanaProgramService
+    ) {
+        this.program = pgs.getProgram('liqsolCore');
+    }
+
+    // ---------------------------------------------------------------------------
+    // Account helpers
+    // ---------------------------------------------------------------------------
+
+    async getAccounts(user: PublicKey): Promise<OutpostAccounts> {
+        return buildOutpostAccounts(this.provider.connection, user, this.pgs);
+    }
+
+    async fetchGlobalState(): Promise<GlobalState> {
+        const { globalState } = await this.getAccounts(this.wallet.publicKey);
+        return this.program.account.globalState.fetch(globalState);
+    }
+
+    async fetchTrancheState(): Promise<TrancheState> {
+        const { trancheState } = await this.getAccounts(this.wallet.publicKey);
+        return this.program.account.trancheState.fetch(trancheState);
+    }
+
+    /**
+     * Fetch the per-user Outpost account (old "wire receipt").
+     * Returns null if the user has never interacted with Outpost.
+     */
+    async fetchOutpostAccount(user: PublicKey): Promise<OutpostAccount | null> {
+        const { outpostAccount } = await this.getAccounts(user);
+        return this.program.account.outpostAccount.fetchNullable(outpostAccount);
+    }
+
+    /**
+     * Fetch the per-user pretoken purchase record.
+     * Returns null if the user has never purchased pretokens.
+     */
+    async fetchUserPretokenRecord(
+        user: PublicKey,
+    ): Promise<UserPretokenRecord | null> {
+        const { userPretokenRecord } = await this.getAccounts(user);
+        return this.program.account.userPretokenRecord.fetchNullable(
+            userPretokenRecord,
+        );
+    }
+
+    // ---------------------------------------------------------------------------
+    // Instruction builders (no send / confirm)
+    // ---------------------------------------------------------------------------
+
+    /**
+     * Build a pretoken `purchase` instruction using liqSOL from the user’s ATA.
+     *
+     * This mirrors capital-staking `executePurchase` wiring:
+     * - amountLamports: liqSOL amount (raw token-2022 units, not SOL)
+     */
+    async buildPurchaseIx(
+        amountLamports: bigint,
+        user = this.wallet.publicKey,
+    ): Promise<TransactionInstruction> {
+        console.log('build purchase for', user.toBase58());
+        
+        const a = await this.getAccounts(user);
+
+        const extraAccountMetaList = this.pgs.deriveExtraAccountMetaListPda(a.liqsolMint);
+        const liqsolCoreProgram = this.pgs.PROGRAM_IDS.LIQSOL_CORE;
+        const transferHookProgram = this.pgs.PROGRAM_IDS.TRANSFER_HOOK;
+
+        return this.program.methods
+            .purchase(new BN(amountLamports.toString()))
+            .accounts({
+                user: a.user,
+                liqsolMint: a.liqsolMint,
+                globalState: a.globalState,
+                distributionState: a.distributionState,
+
+                // buyer’s liqSOL
+                buyerAta: a.userAta,
+
+                // pool / bucket context
+                poolAuthority: a.poolAuthority,
+                bucketAuthority: a.bucketAuthority,
+                bucketTokenAccount: a.bucketTokenAccount,
+                bucketUserRecord: a.bucketUserRecord,
+
+                // distribution userRecords (token-account keyed)
+                senderUserRecord: a.userUserRecord,
+                receiverUserRecord: a.liqsolPoolUserRecord,
+
+                // transfer-hook wiring
+                extraAccountMetaList,
+                liqsolCoreProgram,
+                transferHookProgram,
+
+                // pool + outpost + tranche
+                liqsolPoolAta: a.liqsolPoolAta,
+                outpostAccount: a.outpostAccount,
+                trancheState: a.trancheState,
+                userPretokenRecord: a.userPretokenRecord,
+
+                // Chainlink pricing
+                chainlinkFeed: a.chainLinkFeed ?? CHAINLINK_FEED,
+                chainlinkProgram: a.chainLinkProgram ?? CHAINLINK_PROGRAM,
+
+                tokenProgram: TOKEN_2022_PROGRAM_ID,
+                associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
+                systemProgram: SystemProgram.programId,
+
+                pretokenPurchaseHistory: a.pretokenPurchaseHistory,
+
+                globalConfig: a.globalConfig,
+                oppEpochState: a.oppEpochState, 
+                pendingAttestations: a.pendingAttestations
+            })
+            .instruction();
+    }
+
+    // NOTE:
+    // - There is no longer `purchaseWithSol` in the IDL - SOL → liqSOL happens
+    //   through the deposit / liqSOL minting path, not directly in pretokens.
+    // - `purchaseFromYield` is an operator-facing / protocol flow and you
+    //   indicated you’ll trigger it from Wire infra, so we don’t expose a
+    //   client helper here for now.
+
+    // ---------------------------------------------------------------------------
+    // Price helpers (SOL/USD via priceHistory account)
+    // ---------------------------------------------------------------------------
+
+    async getSolPriceUsdSafe(): Promise<{ price?: bigint; timestamp?: number }> {
+        try {
+            const price = await this.getSolPriceUsd();
+            // current priceHistory account has no timestamp; keep optional
+            return { price, timestamp: undefined };
+        } catch {
+            return { price: undefined, timestamp: undefined };
+        }
+    }
+
+    /**
+     * Fetch latest SOL/USD price (1e8 scale) from liqsol_core.priceHistory.
+     * Uses the ring-buffer semantics from capital-staking.
+     */
+    async getSolPriceUsd(): Promise<bigint> {
+        const priceHistoryPda = this.pgs.derivePriceHistoryPda();
+        const history = (await this.program.account.priceHistory.fetch(
+            priceHistoryPda,
+        )) as PriceHistory;
+
+        const { prices, nextIndex, count, windowSize } = history;
+
+        if (!prices || prices.length === 0 || !count) {
+            throw new Error('Price history is empty - no SOL price available');
+        }
+
+        const capacity = prices.length || windowSize;
+        if (!capacity) {
+            throw new Error(
+                'Price history capacity is zero - check account layout',
+            );
+        }
+
+        const lastIndex = nextIndex === 0 ? capacity - 1 : nextIndex - 1;
+        const latest = prices[lastIndex];
+
+        if (!BN.isBN(latest)) {
+            throw new Error(
+                'Latest price entry is not a BN - check IDL/decoder',
+            );
+        }
+
+        return BigInt(latest.toString());
+    }
+}