@wireio/stake 0.1.3 → 0.1.69

package/src/networks/solana/utils.ts

@@ -1,379 +1,422 @@
-// src/networks/solana/utils.ts
-
 import { Program, BN, AnchorProvider } from '@coral-xyz/anchor';
+import { keccak_256 } from '@noble/hashes/sha3';
 
 import {
     Connection,
     Keypair,
     PublicKey,
-    SystemProgram,
-    StakeProgram,
 } from '@solana/web3.js';
 import {
     TOKEN_2022_PROGRAM_ID,
-    ASSOCIATED_TOKEN_PROGRAM_ID,
     getAssociatedTokenAddress,
 } from '@solana/spl-token';
 
 import {
-    LIQSOL_CORE,
-    LIQSOL_TOKEN,
-    PAY_RATE_SCALE_FACTOR,
     DEFAULT_AVERAGE_PAY_RATE,
     EPHEMERAL_RENT_EXEMPTION,
-    LAMPORTS_PER_SOL,
-    lamportsToSol,
     solToLamports,
-    deriveDepositAuthorityPda,
-    deriveLiqsolMintPda,
-    deriveLiqsolMintAuthorityPda,
-    deriveVaultPda,
-    deriveReservePoolPda,
-    deriveStakeControllerStatePda,
-    derivePayoutStatePda,
-    deriveBucketAuthorityPda,
-    deriveDistributionStatePda,
-    deriveUserRecordPda,
-    derivePayRateHistoryPda,
-    deriveStakeControllerVaultPda,
-    deriveEphemeralStakeAddress,
     DEFAULT_PAY_RATE_LOOKBACK,
+    CHAINLINK_FEED,
+    CHAINLINK_PROGRAM,
 } from './constants';
 
-import liqsolCoreIDL from '../../assets/solana/idl/liqsol_core.json';
+import { GlobalState, TrancheState } from './types';
+import { TrancheLadderItem, TrancheSnapshot } from '../../types';
+import { ChainID } from '@wireio/core';
+import { SolanaProgramService } from './program';
 
 // -----------------------------------------------------------------------------
-// Read-only liqsol_core Program helper
+// Tranche Support
 // -----------------------------------------------------------------------------
+const INDEX_SCALE = BigInt(1_000_000_000_000); // 1e12
+const USD_SCALE = BigInt(100_000_000);       // 1e8
+const BPS = BigInt(10_000);
 
-let _liqsolCoreProgram: Program | null = null;
-
-export function getLiqsolCoreProgram(
-    connection: Connection,
-): Program {
-    if (_liqsolCoreProgram && _liqsolCoreProgram.provider.connection === connection) {
-        return _liqsolCoreProgram;
-    }
+/**
+ * Apply one forward growth step: value * (BPS + growthBps) / BPS.
+ * Simple integer round-half-up.
+ */
+function growSupplyOnce(value: bigint, growthBps: number): bigint {
+    const g = BigInt(growthBps);
+    return (value * (BPS + g) + BPS / BigInt(2)) / BPS;
+}
 
-    // Dummy wallet – we're only doing read-only account fetches here.
-    const tmpKeypair = Keypair.generate();
-    const wallet : any = { publicKey: tmpKeypair.publicKey, signAllTransactions: async () => [], signTransaction: async () => tmpKeypair };
+/**
+ * Apply one backward step: value * BPS / (BPS + growthBps).
+ * Also integer round-half-up.
+ */
+function shrinkSupplyOnce(value: bigint, growthBps: number): bigint {
+    const g = BigInt(growthBps);
+    return (value * BPS + (BPS + g) / BigInt(2)) / (BPS + g);
+}
 
-    const provider = new AnchorProvider(connection, wallet, {
-        commitment: 'confirmed',
-    });
+/**
+ * Price step is expressed in *cents*, while prices are 1e8 USD.
+ * 1 cent = 0.01 * 1e8 = 1e6, so:
+ *   step = priceGrowthCents * 1e6
+ */
+function priceStepUsd1e8(priceGrowthCents: number): bigint {
+    if (!priceGrowthCents) return BigInt(0);
+    const CENT_SCALE = USD_SCALE / BigInt(100); // 1e6
+    return BigInt(priceGrowthCents) * CENT_SCALE;
+}
 
-    const program = new Program(
-        liqsolCoreIDL,
-        provider,
-    ) as Program;
+function growPriceOnceUsd1e8(value: bigint, priceGrowthCents: number): bigint {
+    const step = priceStepUsd1e8(priceGrowthCents);
+    return value + step;
+}
 
-    _liqsolCoreProgram = program;
-    return program;
+function shrinkPriceOnceUsd1e8(value: bigint, priceGrowthCents: number): bigint {
+    const step = priceStepUsd1e8(priceGrowthCents);
+    if (step === BigInt(0)) return value;
+    if (value <= step) return BigInt(0);
+    return value - step;
 }
 
-// -----------------------------------------------------------------------------
-// Deposit accounts bundle
-// -----------------------------------------------------------------------------
+/** BN | bigint -> bigint helper (keeps code readable) */
+export function toBigint(x: any): bigint {
+    if (typeof x === 'bigint') return x;
+    if (typeof x === 'number') return BigInt(x);
+    // Anchor BN
+    return BigInt(x.toString());
+}
 
-export interface DepositAccounts {
-    user: PublicKey;
-    depositAuthority: PublicKey;
-    liqsolMint: PublicKey;
-    liqsolMintAuthority: PublicKey;
-    userAta: PublicKey;
-    stakeControllerVault: PublicKey;
-    stakeControllerReservePool: PublicKey;
-    stakeControllerState: PublicKey;
-    payoutState: PublicKey;
-    bucketAuthority: PublicKey;
-    bucketTokenAccount: PublicKey;
-    distributionState: PublicKey;
-    userRecord: PublicKey;
-    payRateHistory: PublicKey;
-    ephemeralStake: PublicKey;
-    ephemeralSeed: string;
+/**
+ * Convert token amount -> shares using the same rule as on-chain tests:
+ * shares = ceil(amount * INDEX_SCALE / currentIndex)
+ */
+export function tokensToShares(amount: bigint, currentIndex: bigint): bigint {
+    if (amount === BigInt(0)) return BigInt(0);
+    const num = amount * INDEX_SCALE;
+    const q = num / currentIndex;
+    const r = num % currentIndex;
+    return r === BigInt(0) ? q : q + BigInt(1);
 }
 
 /**
- * Build a complete DepositAccounts set for a given user, matching the
- * on-chain PDAs used by the liqSOL core program.
+ * Build a local tranche ladder around the current tranche
+ * using only on-chain config + current state.
  *
- * The optional `seed` lets you make deposit flows replayable/deterministic.
- * If omitted, a random u32 seed is generated.
+ * Rules (from liqsol_core tests):
+ *  - past tranches are fully sold
+ *  - current tranche has (initial - currentSupply) sold
+ *  - future tranches start with 0 sold
+ *  - supply/price grow by supplyGrowthBps/priceGrowthBps per tranche
  */
-export async function buildDepositAccounts(
-    connection: Connection,
-    user: PublicKey,
-): Promise<DepositAccounts> {
-    const depositAuthority = deriveDepositAuthorityPda();
-    const liqsolMint = deriveLiqsolMintPda();
-    const liqsolMintAuthority = deriveLiqsolMintAuthorityPda();
-    const stakeControllerVault = deriveStakeControllerVaultPda();
-    const stakeControllerReservePool = deriveReservePoolPda();
-    const stakeControllerState = deriveStakeControllerStatePda();
-    const payoutState = derivePayoutStatePda();
-    const bucketAuthority = deriveBucketAuthorityPda();
-    const distributionState = deriveDistributionStatePda();
-    const userRecord = deriveUserRecordPda(user);
-    const payRateHistory = derivePayRateHistoryPda();
+export function buildSolanaTrancheLadder(options: {
+    currentTranche: number;
+    initialTrancheSupply: bigint;
+    currentTrancheSupply: bigint;
+    currentPriceUsd: bigint;    // 1e8 scale
+    supplyGrowthBps: number;
+    priceGrowthCents: number;   // e.g. 2 -> $0.02 per tranche
+    windowBefore?: number;
+    windowAfter?: number;
+}): TrancheLadderItem[] {
+    const {
+        currentTranche,
+        initialTrancheSupply,
+        currentTrancheSupply,
+        currentPriceUsd,
+        supplyGrowthBps,
+        priceGrowthCents,
+        windowBefore = 5,
+        windowAfter = 5,
+    } = options;
+
+    const startId = Math.max(0, currentTranche - windowBefore);
+    const endId = currentTranche + windowAfter;
+
+    const capacity = new Map<number, bigint>();
+    const price = new Map<number, bigint>();
+
+    // Seed current tranche
+    capacity.set(currentTranche, initialTrancheSupply);
+    price.set(currentTranche, currentPriceUsd);
+
+    // Forward (future tranches): grow supply by BPS, price by +cents (linear)
+    for (let id = currentTranche + 1; id <= endId; id++) {
+        const prevCap = capacity.get(id - 1)!;
+        const prevPrice = price.get(id - 1)!;
+
+        capacity.set(id, growSupplyOnce(prevCap, supplyGrowthBps));
+        price.set(id, growPriceOnceUsd1e8(prevPrice, priceGrowthCents));
+    }
 
-    const userAta = await getAssociatedTokenAddress(
-        liqsolMint,
-        user,
-        false,
-        TOKEN_2022_PROGRAM_ID,
-    );
+    // Backward (past tranches): shrink supply by inverse BPS, price by -cents
+    for (let id = currentTranche - 1; id >= startId; id--) {
+        const nextCap = capacity.get(id + 1)!;
+        const nextPrice = price.get(id + 1)!;
 
-    const bucketTokenAccount = await getAssociatedTokenAddress(
-        liqsolMint,
-        bucketAuthority,
-        true,
-        TOKEN_2022_PROGRAM_ID,
-    );
+        capacity.set(id, shrinkSupplyOnce(nextCap, supplyGrowthBps));
+        price.set(id, shrinkPriceOnceUsd1e8(nextPrice, priceGrowthCents));
+    }
+
+    const ladder: TrancheLadderItem[] = [];
+    for (let id = startId; id <= endId; id++) {
+        const cap = capacity.get(id)!;
+
+        let sold: bigint;
+        if (id < currentTranche) {
+            // Past tranches fully sold
+            sold = cap;
+        } else if (id === currentTranche) {
+            // Current tranche: cap - remaining
+            sold = cap - currentTrancheSupply;
+        } else {
+            // Future tranches not yet opened
+            sold = BigInt(0);
+        }
+
+        ladder.push({
+            id,
+            capacity: cap,
+            sold,
+            remaining: cap - sold,
+            priceUsd: price.get(id)!, // still 1e8 scale
+        });
+    }
 
-    // -------------------------------------------------------------
-    // Ephemeral stake
-    // -------------------------------------------------------------
-    const seed = Math.floor(Math.random() * 2 ** 32);
-    const ephemeralSeed = `ephemeral_${seed}`;
-    const ephemeralStake = await deriveEphemeralStakeAddress(user, ephemeralSeed);
+    return ladder;
+}
 
-    // `connection` is currently unused, but we keep it in the signature
-    // so this helper can evolve to preflight/validate accounts if needed.
-    void connection;
+/**
+ * Turn raw liqsol_core accounts into a chain-agnostic TrancheSnapshot for SOL.
+ * All math stays here; TokenClient just wires accounts + connection.
+ */
+export function buildSolanaTrancheSnapshot(options: {
+    chainID: ChainID;
+    globalState: GlobalState;
+    trancheState: TrancheState;
+    solPriceUsd?: bigint;
+    nativePriceTimestamp?: number;
+    ladderWindowBefore?: number;
+    ladderWindowAfter?: number;
+}): TrancheSnapshot {
+    const {
+        chainID,
+        globalState,
+        trancheState,
+        solPriceUsd,
+        nativePriceTimestamp,
+        ladderWindowBefore,
+        ladderWindowAfter,
+    } = options;
+
+    const currentIndex = toBigint(globalState.currentIndex);
+    const totalShares = toBigint(globalState.totalShares);
+    const currentTranche = trancheState.currentTrancheNumber.toNumber();
+    const currentTrancheSupply = toBigint(trancheState.currentTrancheSupply);
+    const initialTrancheSupply = toBigint(trancheState.initialTrancheSupply);
+    const totalPretokensSold = toBigint(trancheState.totalPretokensSold);
+    const currentPriceUsd = toBigint(trancheState.currentTranchePriceUsd);
+    const supplyGrowthBps = trancheState.supplyGrowthBps;
+    const priceGrowthCents = trancheState.priceGrowthCents;
+
+    const ladder = buildSolanaTrancheLadder({
+        currentTranche,
+        initialTrancheSupply,
+        currentTrancheSupply,
+        currentPriceUsd,
+        supplyGrowthBps,
+        priceGrowthCents,
+        windowBefore: ladderWindowBefore,
+        windowAfter: ladderWindowAfter,
+    });
 
     return {
-        user,
-        depositAuthority,
-        liqsolMint,
-        liqsolMintAuthority,
-        userAta,
-        stakeControllerVault,
-        stakeControllerReservePool,
-        stakeControllerState,
-        payoutState,
-        bucketAuthority,
-        bucketTokenAccount,
-        distributionState,
-        userRecord,
-        payRateHistory,
-        ephemeralStake,
-        ephemeralSeed,
+        chainID,
+        currentIndex,
+        totalShares,
+        currentTranche,
+        currentPriceUsd,
+        supplyGrowthBps,
+        priceGrowthCents,
+        totalPretokensSold,
+        currentTrancheSupply,
+        initialTrancheSupply,
+        nativePriceUsd: solPriceUsd,
+        nativePriceTimestamp,
+        ladder,
     };
 }
 
-// -----------------------------------------------------------------------------
-// Balance + state getters (UI-friendly)
-// -----------------------------------------------------------------------------
+/**
+ * ---------------------------------------------------------------------------
+ * Outpost-specific helpers
+ * ---------------------------------------------------------------------------
+ *
+ * This is the SDK equivalent of `deriveWirePdas` in capital-staking tests.
+ * It aggregates all PDAs / ATAs needed for Outpost pretokens + synd/desynd.
+ */
+export interface OutpostAccounts {
+    user: PublicKey;
 
-export async function getUserLiqSolBalance(
-    connection: Connection,
-    user: PublicKey,
-): Promise<number> {
-    const liqsolMint = deriveLiqsolMintPda();
-    const ata = await getAssociatedTokenAddress(
-        liqsolMint,
-        user,
-        false,
-        TOKEN_2022_PROGRAM_ID,
-    );
+    // Outpost / pretoken wiring
+    globalState: PublicKey;
+    poolAuthority: PublicKey;
+    liqsolMint: PublicKey;
+    liqsolPoolAta: PublicKey;
+    userAta: PublicKey;
+    outpostAccount: PublicKey;
+    userPretokenRecord: PublicKey;
 
-    try {
-        const bal = await connection.getTokenAccountBalance(ata);
-        return Number(bal.value.amount); // raw lamports, not decimals-adjusted
-    } catch {
-        return 0;
-    }
-}
+    // Distribution / yield context (user_record keyed by token accounts)
+    distributionState: PublicKey;
+    bucketAuthority: PublicKey;
+    bucketTokenAccount: PublicKey;
+    bucketUserRecord: PublicKey;
+    liqsolPoolUserRecord: PublicKey;
+    userUserRecord: PublicKey;
 
-export async function getBucketLiqSolBalance(
-    connection: Connection,
-): Promise<number> {
-    const liqsolMint = deriveLiqsolMintPda();
-    const bucketAuthority = deriveBucketAuthorityPda();
-    const ata = await getAssociatedTokenAddress(
-        liqsolMint,
-        bucketAuthority,
-        true,
-        TOKEN_2022_PROGRAM_ID,
-    );
+    // Tranche / pricing
+    trancheState: PublicKey;
 
-    try {
-        const bal = await connection.getTokenAccountBalance(ata);
-        return Number(bal.value.amount);
-    } catch {
-        return 0;
-    }
-}
+    // Chainlink
+    chainLinkFeed: PublicKey;
+    chainLinkProgram: PublicKey;
 
-export async function getReservePoolBalance(
-    connection: Connection,
-): Promise<number> {
-    const reservePool = deriveReservePoolPda();
-    try {
-        const lamports = await connection.getBalance(reservePool);
-        return lamports;
-    } catch {
-        return 0;
-    }
-}
+    // Transfer hook extra accounts
+    extraAccountMetaList: PublicKey;
 
-/**
- * Raw account info for the stake_controller state (Anchor decode is left
- * to the caller so the SDK can stay IDL-agnostic at this layer).
- */
-export async function getStakeControllerStateRaw(
-    connection: Connection,
-): Promise<Uint8Array | null> {
-    const pda = deriveStakeControllerStatePda();
-    const info = await connection.getAccountInfo(pda);
-    return info?.data ?? null;
-}
+    // New
+    pretokenPurchaseHistory: PublicKey;
 
-/**
- * Raw account info for the payout-state account.
- */
-export async function getPayoutStateRaw(
-    connection: Connection,
-): Promise<Uint8Array | null> {
-    const pda = derivePayoutStatePda();
-    const info = await connection.getAccountInfo(pda);
-    return info?.data ?? null;
+    // OPP (outpost protocol pipeline)
+    globalConfig: PublicKey;
+    oppEpochState: PublicKey;
+    pendingAttestations: PublicKey;
+    bridgeState: PublicKey;
 }
 
 /**
- * Raw account info for a user's distribution user_record.
+ * Derive the canonical Wire account name for a Solana public key.
+ *
+ * The convention (matching capital-staking `defaultWireRecipientForPubkey`)
+ * is a 12-character Wire name beginning with "sol" followed by 9 characters
+ * drawn from the Wire alphabet, deterministically derived from keccak-256 of
+ * the public key bytes.
+ *
+ * This is the default wireAccount used by buildStakeIx when the caller does
+ * not supply an explicit Wire recipient.
  */
-export async function getUserRecordRaw(
-    connection: Connection,
-    user: PublicKey,
-): Promise<Uint8Array | null> {
-    const pda = deriveUserRecordPda(user);
-    const info = await connection.getAccountInfo(pda);
-    return info?.data ?? null;
+export function deriveDefaultWireAccount(user: PublicKey): string {
+    const ALPHABET = '.12345abcdefghijklmnopqrstuvwxyz';
+    const digest = Buffer.from(keccak_256(user.toBytes()));
+    let cursor = Number(digest.readBigUInt64LE(0));
+    const out = ['.', '.', '.', '.', '.', '.', '.', '.', '.', '.', '.', '.'];
+    out[0] = 's';
+    out[1] = 'o';
+    out[2] = 'l';
+    for (let i = 3; i < out.length; i++) {
+        out[i] = ALPHABET[cursor & 31];
+        cursor >>>= 5;
+    }
+    return out.join('');
 }
 
-// -----------------------------------------------------------------------------
-// Pay-rate & fee utilities (on-chain compatible)
-// -----------------------------------------------------------------------------
-
-export async function getAveragePayRate(
+export async function buildOutpostAccounts(
     connection: Connection,
-    lookback: number = DEFAULT_PAY_RATE_LOOKBACK,
-): Promise<bigint> {
-    const program = getLiqsolCoreProgram(connection);
-    const payRateHistoryPda = derivePayRateHistoryPda();
+    user: PublicKey,
+    pgs: SolanaProgramService,
+): Promise<OutpostAccounts> {
+    const globalState = pgs.deriveOutpostGlobalStatePda();
+    const poolAuthority = pgs.deriveOutpostPoolAuthorityPda();
+    const liqsolMint = pgs.deriveLiqsolMintPda();
+    const distributionState = pgs.deriveDistributionStatePda();
+    const bucketAuthority = pgs.deriveBucketAuthorityPda();
+    const trancheState = pgs.deriveTrancheStatePda();
+
+    // Outpost / pretoken PDAs
+    const outpostAccount = pgs.deriveOutpostAccountPda(user);
+    const userPretokenRecord = pgs.deriveUserPretokenRecordPda(user);
+
+    // ATAs
+    const liqsolPoolAta = await getAssociatedTokenAddress(
+        liqsolMint,
+        poolAuthority,
+        true,
+        TOKEN_2022_PROGRAM_ID,
+    );
 
-    try {
-        const anyProgram = program as any;
-        const payRateHistoryAccount = await anyProgram.account.payRateHistory.fetch(
-            payRateHistoryPda,
-        );
+    const bucketTokenAccount = await getAssociatedTokenAddress(
+        liqsolMint,
+        bucketAuthority,
+        true,
+        TOKEN_2022_PROGRAM_ID,
+    );
 
-        const entries: any[] = payRateHistoryAccount.entries ?? [];
-        const totalEntriesAdded = Number(
-            payRateHistoryAccount.totalEntriesAdded ?? 0,
-        );
-        const currentIndex: number = payRateHistoryAccount.currentIndex ?? 0;
-        const maxEntries: number =
-            payRateHistoryAccount.maxEntries ?? entries.length;
+    const userAta = await getAssociatedTokenAddress(
+        liqsolMint,
+        user,
+        true, // allow off curve in case squadsx vault
+        TOKEN_2022_PROGRAM_ID,
+    );
 
-        if (!entries.length) {
-            return DEFAULT_AVERAGE_PAY_RATE;
-        }
+    // user_record PDAs keyed by TOKEN ACCOUNTS (matches capital-staking)
+    const bucketUserRecord = pgs.deriveUserRecordPda(bucketTokenAccount);
+    const liqsolPoolUserRecord = pgs.deriveUserRecordPda(liqsolPoolAta);
+    const userUserRecord = pgs.deriveUserRecordPda(userAta);
 
-        const entriesToFetch = Math.min(lookback, maxEntries, entries.length);
+    const extraAccountMetaList = pgs.deriveExtraAccountMetaListPda(liqsolMint);
 
-        let idx: number;
-        if (totalEntriesAdded === 0) {
-            idx = 0;
-        } else if (currentIndex === 0) {
-            idx = maxEntries - 1;
-        } else {
-            idx = currentIndex - 1;
-        }
+    const pretokenPurchaseHistory = pgs.derivePretokenPurchaseHistoryPda(poolAuthority);
 
-        let sum = BigInt(0);
-        let validCount = BigInt(0);
-
-        for (let i = 0; i < entriesToFetch; i++) {
-            const entry = entries[idx];
-            if (entry && typeof entry.scaledRate !== 'undefined') {
-                const rate = BigInt(entry.scaledRate.toString());
-                if (rate > BigInt(0)) {
-                    sum += rate;
-                    validCount += BigInt(1);
-                }
-            }
+    // OPP (outpost protocol pipeline)
+    const globalConfig = pgs.deriveGlobalConfigPda();
+    const oppEpochState = pgs.deriveOppEpochStatePda();
+    const epochNumber = await pgs.fetchOppEpochNumber(connection);
+    const pendingAttestations = pgs.derivePendingAttestationsPda(epochNumber);
+    const bridgeState = pgs.deriveOppBridgeStatePda();
 
-            if (totalEntriesAdded === 0) {
-                idx = (idx + 1) % maxEntries;
-            } else {
-                idx = idx === 0 ? maxEntries - 1 : idx - 1;
-            }
-        }
+    // Chainlink program feeds
+    let chainLinkFeed = CHAINLINK_FEED;
+    let chainLinkProgram = CHAINLINK_PROGRAM;
 
-        if (validCount === BigInt(0)) {
-            return DEFAULT_AVERAGE_PAY_RATE;
+    try {
+        const program = pgs.getProgram('liqsolCore');
+        const ts: TrancheState =
+            await program.account.trancheState.fetch(trancheState);
+
+        // If on-chain config overrides are present, prefer those.
+        if (ts.chainlinkFeed && ts.chainlinkProgram) {
+            chainLinkFeed = ts.chainlinkFeed as PublicKey;
+            chainLinkProgram = ts.chainlinkProgram as PublicKey;
         }
-
-        return sum / validCount;
-    } catch (err) {
-        // Fallback to default when history missing/unavailable
-        return DEFAULT_AVERAGE_PAY_RATE;
+    } catch {
+        // If trancheState isn't initialized yet, we fall back to the constants.
+        // In that case, purchase instructions will still fail, which is the
+        // correct behavior until admin initializes TrancheState on-chain.
     }
-}
-/**
- * On-chain fee formula:
- *   fee = (average_pay_rate * 4 * deposit_amount_lamports) / 10^12
- */
-export function calculateExpectedFee(
-    depositAmountLamports: BN,
-    averagePayRate: BN,
-): BN {
-    return averagePayRate
-        .mul(new BN(4))
-        .mul(depositAmountLamports)
-        .div(new BN(1_000_000_000_000)); // 10^12
-}
 
-/**
- * Convenience helper to preview how a deposit splits between user + bucket
- * and how much goes into the reserve, assuming the simple model:
- *
- * - userLiqSol = amount - fee + EPHEMERAL_RENT_EXEMPTION
- * - bucketLiqSol = fee
- * - reserveLamports = amount + EPHEMERAL_RENT_EXEMPTION
- */
-export function previewDepositEffects(params: {
-    depositAmountLamports: BN;
-    averagePayRate: BN;
-    rentExemptionLamports?: number;
-}): {
-    feeLamports: BN;
-    userLiqSolLamports: BN;
-    bucketLiqSolLamports: BN;
-    reserveIncreaseLamports: BN;
-} {
-    const { depositAmountLamports, averagePayRate } = params;
-    const rent = new BN(
-        params.rentExemptionLamports ?? EPHEMERAL_RENT_EXEMPTION,
-    );
-
-    const fee = calculateExpectedFee(depositAmountLamports, averagePayRate);
-    const userLiqSol = depositAmountLamports.sub(fee).add(rent);
-    const bucketLiqSol = fee;
-    const reserveIncrease = depositAmountLamports.add(rent);
+    void connection; // reserved for future extra validation
 
     return {
-        feeLamports: fee,
-        userLiqSolLamports: userLiqSol,
-        bucketLiqSolLamports: bucketLiqSol,
-        reserveIncreaseLamports: reserveIncrease,
+        user,
+        globalState,
+        poolAuthority,
+        liqsolMint,
+        liqsolPoolAta,
+        userAta,
+        outpostAccount,
+        userPretokenRecord,
+        distributionState,
+        bucketAuthority,
+        bucketTokenAccount,
+        bucketUserRecord,
+        liqsolPoolUserRecord,
+        userUserRecord,
+        trancheState,
+        chainLinkFeed,
+        chainLinkProgram,
+        extraAccountMetaList,
+        pretokenPurchaseHistory,
+        globalConfig,
+        oppEpochState,
+        pendingAttestations,
+        bridgeState,
     };
 }
-
 // -----------------------------------------------------------------------------
 // Epoch / scheduling helpers
 // -----------------------------------------------------------------------------
@@ -516,7 +559,7 @@ export async function airdropSol(
     amountSol: number,
 ): Promise<void> {
     const lamports = solToLamports(amountSol);
-    const sig = await connection.requestAirdrop(publicKey, lamports);
+    const sig = await connection.requestAirdrop(publicKey, Number(lamports));
     await connection.confirmTransaction(sig, 'confirmed');
 }
 
@@ -549,3 +592,24 @@ export interface ScheduleConfig {
     late?: number;  // fraction of epoch, default 0.90
 }
 
+export function ceilDiv(n: BN, d: BN): BN {
+    if (d.isZero()) {
+        throw new Error('Division by zero in ceilDiv');
+    }
+    return n.add(d.subn(1)).div(d);
+}
+
+export function normalizeToBigInt(x: any): bigint {
+    if (typeof x === 'bigint') return x;
+    if (x != null && typeof x === 'object' && 'toString' in x) return BigInt(x.toString());
+    if (typeof x === 'number') return BigInt(x);
+    throw new Error(`normalizeToBigInt: unsupported type ${typeof x}`);
+}
+
+export const safeFetch = async <T>(promise: Promise<T>, label?: string): Promise<T | null> => {
+    try { return await promise; }
+    catch (err) {
+        console.error(`Safe Fetch Failed${label ? ` (${label})` : ''}:`,err);
+        return null;
+    }
+};