@wireio/stake 0.3.1 → 0.3.69

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

@@ -1,474 +1,341 @@
 import { AnchorProvider, BN, Program } from '@coral-xyz/anchor';
 import {
-    Connection,
     PublicKey,
     SystemProgram,
-    Transaction,
     TransactionInstruction,
 } from '@solana/web3.js';
 import {
     ASSOCIATED_TOKEN_PROGRAM_ID,
     TOKEN_2022_PROGRAM_ID,
-    createAssociatedTokenAccountInstruction,
 } from '@solana/spl-token';
+
 import {
+    OutpostAccounts,
     buildOutpostAccounts,
-    getLiqsolCoreProgram,
-    getErrorMessage,
+    safeFetch,
 } from '../utils';
-import { SolanaProgramService } from '../program';
-import { LiqsolCore } from '../../../assets/solana/types/liqsol_core';
-import { WalletLike, OutpostWireStateSnapshot, SharesPreview, UserWarrantRecord, TrancheState, WireReceipt } from '../types';
+
+import {
+    OutpostWireStateSnapshot,
+    SharesPreview,
+    TrancheState,
+    WalletLike,
+} from '../types';
+import { INDEX_SCALE } from '../constants';
+import { LiqsolCoreClientIdl, SolanaProgramService } from '../program';
 
 /**
- * Minimal, user-flow focused OutpostClient.
- * - Read state
- * - Build + (optionally) send user instructions
+ * 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
  *
- * No admin/bootstrap/reset helpers by design.
+ * 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<LiqsolCore>;  
+    private readonly program: Program<LiqsolCoreClientIdl>;
 
-    // keep consistent with your tests
-    static readonly INDEX_SCALE = new BN('1000000000000');
-
-    get connection(): Connection { return this.provider.connection; }
-    get wallet(): WalletLike { return this.provider.wallet; }
-
-    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');
     }
 
-    /**
-     * Read-only Program helper (dummy wallet), useful if you want to do pure reads
-     * without requiring a wallet. Kept here as sugar for callers.
-     */
-    getReadOnlyProgram(): Program<LiqsolCore> {
-        return getLiqsolCoreProgram(this.connection);
+    get connection() {
+        return this.provider.connection;
     }
 
-    // ---------------------------------------------------------------------------
-    // General-purpose formatting + math (SDK sugar)
-    // ---------------------------------------------------------------------------
-
-    /**
-     * Same rounding logic from your tests: ceil(amount * INDEX_SCALE / currentIndex)
-     */
-    static tokensToShares(amount: BN, currentIndex: BN): BN {
-        const numerator = amount.mul(OutpostClient.INDEX_SCALE);
-        const shares = numerator.div(currentIndex);
-        const remainder = numerator.mod(currentIndex);
-        return remainder.eqn(0) ? shares : shares.addn(1);
+    get wallet(): WalletLike {
+        return this.provider.wallet as unknown as WalletLike;
     }
 
     /**
-     * UI helper: formats a BN assumed to be scale=1e8 into a decimal string.
-     * (Matches your test helper; useful for tranche price, USD price, etc.)
+     * Build all outpost-related PDAs / ATAs for a given user.
+     * Defaults to the connected wallet.
      */
-    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}`;
+    async buildAccounts(user?: PublicKey): Promise<OutpostAccounts> {
+        const userPk = user ?? this.wallet.publicKey;
+        if (!userPk) {
+            throw new Error('OutpostClient.buildAccounts: wallet not connected');
         }
-        const intPart = valueStr.slice(0, valueStr.length - decimals);
-        const decPart = valueStr.slice(valueStr.length - decimals);
-        return `${intPart}.${decPart}`;
+        return buildOutpostAccounts(this.connection, userPk, this.pgs);
     }
 
     /**
-     * Previews expected shares for a purchase/stake flow that mints shares
-     * relative to globalState.currentIndex.
+     * Internal helper: get raw token balance (BN) for a given ATA.
      */
-    async previewExpectedShares(params: {
-        amountLamports: BN;
-        user?: PublicKey; // optional; defaults to wallet.publicKey
-    }): Promise<SharesPreview> {
-        const user = params.user ?? this.wallet.publicKey;
-        const accounts = await buildOutpostAccounts(this.connection, user);
-        const globalState = await this.program.account.globalState.fetch(accounts.globalState);
-        const currentIndex = new BN(globalState.currentIndex.toString());
-        const expectedShares = OutpostClient.tokensToShares(
-            params.amountLamports,
-            currentIndex,
-        );
-
-        return {
-            amountLamports: params.amountLamports,
-            currentIndex,
-            indexScale: OutpostClient.INDEX_SCALE,
-            expectedShares,
-        };
-    }
-
-    // ---------------------------------------------------------------------------
-    // Account helpers (user-facing, not admin bootstrap)
-    // ---------------------------------------------------------------------------
-
-    /**
-     * Returns whether the user's liqSOL ATA exists.
-     * Useful for UX (show "Create token account" prompt).
-     */
-    async doesUserAtaExist(user: PublicKey = this.wallet.publicKey): Promise<boolean> {
-        const accounts = await buildOutpostAccounts(this.connection, user);
-        const info = await this.connection.getAccountInfo(accounts.userAta);
-        return !!info;
+    private async getTokenBalance(ata: PublicKey): Promise<BN> {
+        const bal = await this.connection.getTokenAccountBalance(ata);
+        return new BN(bal.value.amount);
     }
 
     /**
-     * Builds an instruction to create the user's liqSOL ATA (Token-2022).
-     * This is general-purpose sugar for any flow that needs the ATA.
+     * 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.
      */
-    async buildCreateUserAtaIx(user: PublicKey = this.wallet.publicKey): Promise<TransactionInstruction> {
-        const accounts = await buildOutpostAccounts(this.connection, user);
-
-        return createAssociatedTokenAccountInstruction(
-            this.wallet.publicKey,          // payer
-            accounts.userAta,               // ata
-            user,                           // owner
-            accounts.liqsolMint,            // mint
-            TOKEN_2022_PROGRAM_ID,
-            ASSOCIATED_TOKEN_PROGRAM_ID,
-        );
+    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,
+            );
+        }
     }
 
     /**
-     * Convenience: ensures ATA exists by returning either [] or [createATAIx].
-     * (Does NOT send; caller composes tx)
+     * Fetch the core "Wire state" for Outpost / pretokens for a given user.
      */
-    async maybeBuildCreateUserAtaIx(user: PublicKey = this.wallet.publicKey): Promise<TransactionInstruction[]> {
-        const accounts = await buildOutpostAccounts(this.connection, user);
-        const info = await this.connection.getAccountInfo(accounts.userAta);
-        if (info) return [];
-        return [await this.buildCreateUserAtaIx(user)];
-    }
-
-    // ---------------------------------------------------------------------------
-    // Reads (UI-first)
-    // ---------------------------------------------------------------------------
-
-    async getWireStateSnapshot(user: PublicKey = this.wallet.publicKey): Promise<OutpostWireStateSnapshot> {
-        const accounts = await buildOutpostAccounts(this.connection, 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,
-            wireReceipt,
+            outpostAccount,
             distributionState,
-            userWarrantRecord,
+            userPretokenRecord,
             trancheState,
-        ] = await Promise.all([
-            this.program.account.globalState.fetch(accounts.globalState),
-            this.program.account.wireReceipt.fetchNullable(accounts.wireReceipt),
-            this.program.account.distributionState.fetch(accounts.distributionState),
-            this.program.account.userWarrantRecord.fetchNullable(accounts.userWarrantRecord),
-            this.program.account.trancheState.fetchNullable(accounts.trancheState),
-        ]);
-
-        const [
             liqsolPoolBalance,
-            solBucketLamports,
             userLiqsolBalance,
         ] = await Promise.all([
-            this.getTokenBalanceSafe(accounts.liqsolPoolAta),
-            this.connection.getBalance(accounts.solBucket),
-            this.getTokenBalanceSafe(accounts.userAta),
+            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,
-            wireReceipt,
             trancheState,
-            userWarrantRecord,
+            userPretokenRecord,
             liqsolPoolBalance,
-            solBucketLamports,
             userLiqsolBalance,
         };
     }
 
-    async getWireReceipt(user: PublicKey = this.wallet.publicKey): Promise<WireReceipt | null> {
-        const accounts = await buildOutpostAccounts(this.connection, user);
-        return this.program.account.wireReceipt.fetchNullable(accounts.wireReceipt);
-    }
 
-    async getTrancheState(): Promise<TrancheState | null> {
-        const accounts = await buildOutpostAccounts(this.connection, this.wallet.publicKey);
-        return this.program.account.trancheState.fetchNullable(accounts.trancheState);
-    }
-
-    async getUserWarrantRecord(user: PublicKey = this.wallet.publicKey): Promise<UserWarrantRecord | null> {
-        const accounts = await buildOutpostAccounts(this.connection, user);
-        return this.program.account.userWarrantRecord.fetchNullable(accounts.userWarrantRecord);
-    }
 
-    // ---------------------------------------------------------------------------
-    // Instruction builders (source of truth: your test utils)
-    // ---------------------------------------------------------------------------
+    // -------------------------------------------------------------------------
+    // Outpost stake / unstake builders (syndicate_liqsol_to_wire / desynd)
+    // -------------------------------------------------------------------------
 
     /**
-     * stakeLiqsol(amount)
-     * (Outpost staking: liqSOL -> warrant pool)
+     * 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. Required.
      */
-    async buildStakeLiqsolIx(amountLamports: bigint, userPubKey = this.wallet.publicKey): Promise<TransactionInstruction> {
-        const a = await buildOutpostAccounts(this.connection, userPubKey);
-        const amount = new BN(amountLamports.toString());
+    async buildStakeIx(
+        amountLamports: bigint,
+        user: PublicKey = this.wallet.publicKey,
+        wireAccount?: string,
+    ): Promise<TransactionInstruction> {
+        if (!user) {
+            throw new Error('OutpostClient.buildStakeIx: wallet not connected');
+        }
+        if (!wireAccount?.trim()) {
+            throw new Error('OutpostClient.buildStakeIx: wireAccount is required');
+        }
+
+        const a = await this.buildAccounts(user);
 
         return this.program.methods
-            .stakeLiqsol(amount)
+            .syndicateLiqsolToWire(wireAccount.trim(), new BN(amountLamports.toString()))
             .accounts({
-                user: a.user,
+                user,
                 liqsolMint: a.liqsolMint,
+                distributionState: a.distributionState,
                 globalState: a.globalState,
                 userAta: a.userAta,
+                senderUserRecord: a.userUserRecord,
                 poolAuthority: a.poolAuthority,
                 liqsolPoolAta: a.liqsolPoolAta,
-                warrantDepositRecord: a.wireReceipt,
-                liqsolPoolUserRecord: a.poolUserRecord,
-                distributionState: a.distributionState,
-                payRateHistory: a.payRateHistory,
+                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,
-                solBucket: a.solBucket,
+                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();
     }
 
     /**
-     * withdrawStake(amount)
-     * (Outpost unstake: warrant pool -> user liqSOL)
+     * 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 buildWithdrawStakeIx(amountLamports: bigint, userPubKey = this.wallet.publicKey): Promise<TransactionInstruction> {
-        const a = await buildOutpostAccounts(this.connection, userPubKey);
-        const amount = new BN(amountLamports.toString());
+    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
-            .withdrawStake(amount)
+            .desynd(new BN(amountLamports.toString()))
             .accounts({
-                user: a.user,
+                user: userPk,
                 liqsolMint: a.liqsolMint,
                 globalState: a.globalState,
+                distributionState: a.distributionState,
                 userAta: a.userAta,
                 poolAuthority: a.poolAuthority,
-                liqsolPoolAta: a.liqsolPoolAta,
-                warrantDepositRecord: a.wireReceipt,
-                liqsolPoolUserRecord: a.poolUserRecord,
-                distributionState: a.distributionState,
-                payRateHistory: a.payRateHistory,
                 bucketAuthority: a.bucketAuthority,
                 bucketTokenAccount: a.bucketTokenAccount,
-                solBucket: a.solBucket,
-                tokenProgram: TOKEN_2022_PROGRAM_ID,
-                systemProgram: SystemProgram.programId,
-            })
-            .instruction();
-    }
-
-    /**
-     * purchaseWithLiqsol(amount)
-     */
-    async buildPurchaseWithLiqsolIx(amountLamports: bigint, userPubKey = this.wallet.publicKey): Promise<TransactionInstruction> {
-        const a = await buildOutpostAccounts(this.connection, userPubKey);
-        const amount = new BN(amountLamports.toString());
-
-        return this.program.methods
-            .purchaseWithLiqsol(amount)
-            .accounts({
-                user: a.user,
-                liqsolMint: a.liqsolMint,
-                globalState: a.globalState,
-                buyerAta: a.userAta,
-                poolAuthority: a.poolAuthority,
+                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,
-                warrantDepositRecord: a.wireReceipt,
-                liqsolPoolUserRecord: a.poolUserRecord,
-                distributionState: a.distributionState,
-                payRateHistory: a.payRateHistory,
-                bucketAuthority: a.bucketAuthority,
-                bucketTokenAccount: a.bucketTokenAccount,
-                solBucket: a.solBucket,
-                trancheState: a.trancheState,
-                userWarrantRecord: a.userWarrantRecord,
-                chainlinkFeed: a.chainLinkFeed,
-                chainlinkProgram: a.chainLinkProgram,
+                outpostAccount: a.outpostAccount,
                 tokenProgram: TOKEN_2022_PROGRAM_ID,
-                associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
                 systemProgram: SystemProgram.programId,
+                associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
+                globalConfig: a.globalConfig,
+                oppEpochState: a.oppEpochState,
+                pendingAttestations: a.pendingAttestations,
+                pretokenPurchaseHistory: a.pretokenPurchaseHistory,
             })
             .instruction();
     }
 
-    /**
-     * purchaseWithSol(amount)
-     */
-    async buildPurchaseWithSolIx(amountLamports: bigint, userPubKey = this.wallet.publicKey): Promise<TransactionInstruction> {
-        const a = await buildOutpostAccounts(this.connection, userPubKey);
-        const amount = new BN(amountLamports.toString());
-
-        return this.program.methods
-            .purchaseWithSol(amount)
-            .accounts({
-                user: a.user,
-                liqsolMint: a.liqsolMint,
-                globalState: a.globalState,
-                poolAuthority: a.poolAuthority,
-                liqsolPoolAta: a.liqsolPoolAta,
-                liqsolPoolUserRecord: a.poolUserRecord,
-                distributionState: a.distributionState,
-                payRateHistory: a.payRateHistory,
-                bucketAuthority: a.bucketAuthority,
-                bucketTokenAccount: a.bucketTokenAccount,
-                solBucket: a.solBucket,
-                warrantDepositRecord: a.wireReceipt,
-                trancheState: a.trancheState,
-                userWarrantRecord: a.userWarrantRecord,
-                chainlinkFeed: a.chainLinkFeed,
-                chainlinkProgram: a.chainLinkProgram,
-                tokenProgram: TOKEN_2022_PROGRAM_ID,
-                systemProgram: SystemProgram.programId,
-            })
-            .instruction();
-    }
+    // -------------------------------------------------------------------------
+    // Pretoken preview helper (unchanged)
+    // -------------------------------------------------------------------------
 
     /**
-     * purchaseWarrantsFromYield()
+     * 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
      *
-     * Source of truth: your test util executePurchaseFromYield (note: it passed
-     * liqsolPoolUserRecord: pdas.userUserRecord, not poolUserRecord).
+     * All values are BN integers; solPriceUsd and pretokenPriceUsd are 1e8 scaled.
      */
-    async buildPurchaseFromYieldIx(userPubKey = this.wallet.publicKey): Promise<TransactionInstruction> {
-        const a = await buildOutpostAccounts(this.connection, userPubKey);
+    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(),
+        );
 
-        return this.program.methods
-            .purchaseWarrantsFromYield()
-            .accounts({
-                user: a.user,
-                globalState: a.globalState,
-                liqsolMint: a.liqsolMint,
-                poolAuthority: a.poolAuthority,
-                liqsolPoolAta: a.liqsolPoolAta,
-                solBucket: a.solBucket,
-                liqsolPoolUserRecord: a.userUserRecord,
-                distributionState: a.distributionState,
-                payRateHistory: a.payRateHistory,
-                bucketAuthority: a.bucketAuthority,
-                bucketTokenAccount: a.bucketTokenAccount,
-                tokenProgram: TOKEN_2022_PROGRAM_ID,
-                systemProgram: SystemProgram.programId,
-                trancheState: a.trancheState,
-                userWarrantRecord: a.userWarrantRecord,
-                chainlinkFeed: a.chainLinkFeed,
-                chainlinkProgram: a.chainLinkProgram,
-            })
-            .instruction();
-    }
+        const SCALE = new BN('100000000'); // 1e8
 
-    // ---------------------------------------------------------------------------
-    // Optional send helpers (wallet-facing sugar)
-    // ---------------------------------------------------------------------------
+        // usdValue = (lamports * solPriceUsd) / 1e9
+        const usdValue = liqsolAmountLamports
+            .mul(solPriceUsd)
+            .div(new BN(1_000_000_000));
 
-    /**
-     * Builds and sends a single-instruction transaction.
-     * (Hub can ignore this and use builder methods only.)
-     */
-    async sendIx(ix: TransactionInstruction, opts?: {
-        additionalIxs?: TransactionInstruction[];
-    }): Promise<string> {
-        const tx = new Transaction();
-        if (opts?.additionalIxs?.length) {
-            tx.add(...opts.additionalIxs);
-        }
-        tx.add(ix);
+        const estimatedPretokens = usdValue.mul(SCALE).div(pretokenPriceUsd);
 
-        try {
-            const sig = await this.provider.sendAndConfirm(tx, [], { commitment: 'confirmed' });
-            return sig;
-        } catch (e: any) {
-            const msg = getErrorMessage(e);
-            throw new Error(`OutpostClient sendIx failed: ${msg}`);
-        }
+        return {
+            liqsolAmountLamports,
+            solPriceUsd,
+            pretokenPriceUsd,
+            estimatedPretokens,
+        };
     }
 
     /**
-     * Convenience: stake liqSOL and (optionally) create ATA first.
+     * 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
      */
-    async stakeLiqsol(params: {
-        amount: BN;
-        user?: PublicKey;
-        ensureAta?: boolean; // default true
-    }): Promise<string> {
-        const user = params.user ?? this.wallet.publicKey;
-        const pre: TransactionInstruction[] = [];
-        if (params.ensureAta ?? true) {
-            pre.push(...(await this.maybeBuildCreateUserAtaIx(user)));
-        }
-        const ix = await this.buildStakeLiqsolIx(params.amount, user);
-        return this.sendIx(ix, { additionalIxs: pre });
-    }
-
-    async withdrawStake(params: {
-        amount: BN;
-        user?: PublicKey;
-        ensureAta?: boolean; // default true (usually exists, but harmless)
-    }): Promise<string> {
-        const user = params.user ?? this.wallet.publicKey;
-        const pre: TransactionInstruction[] = [];
-        if (params.ensureAta ?? true) {
-            pre.push(...(await this.maybeBuildCreateUserAtaIx(user)));
-        }
-        const ix = await this.buildWithdrawStakeIx(params.amount, user);
-        return this.sendIx(ix, { additionalIxs: pre });
-    }
-
-    async purchaseWithLiqsol(params: {
-        amount: BN;
-        user?: PublicKey;
-        ensureAta?: boolean; // default true
-    }): Promise<string> {
-        const user = params.user ?? this.wallet.publicKey;
-        const pre: TransactionInstruction[] = [];
-        if (params.ensureAta ?? true) {
-            pre.push(...(await this.maybeBuildCreateUserAtaIx(user)));
-        }
-        const ix = await this.buildPurchaseWithLiqsolIx(params.amount, user);
-        return this.sendIx(ix, { additionalIxs: pre });
-    }
-
-    async purchaseWithSol(params: {
-        amount: BN;
-        user?: PublicKey;
-    }): Promise<string> {
-        const user = params.user ?? this.wallet.publicKey;
-        const ix = await this.buildPurchaseWithSolIx(params.amount, user);
-        return this.sendIx(ix);
-    }
-
-    async purchaseFromYield(params?: {
-        user?: PublicKey;
-    }): Promise<string> {
-        const user = params?.user ?? this.wallet.publicKey;
-        const ix = await this.buildPurchaseFromYieldIx(user);
-        return this.sendIx(ix);
+    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);
     }
 
-    // ---------------------------------------------------------------------------
-    // Internals
-    // ---------------------------------------------------------------------------
-
     /**
-     * Token balance helper returning BN(0) if ATA missing.
+     * 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"
      */
-    private async getTokenBalanceSafe(ata: PublicKey): Promise<BN> {
-        try {
-            const bal = await this.connection.getTokenAccountBalance(ata);
-            return new BN(bal.value.amount);
-        } catch {
-            return new BN(0);
+    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}`;
     }
-}
+}