@wireio/stake 0.4.3 → 0.5.1

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

@@ -42,7 +42,7 @@ import {
     deriveLiqReceiptDataPda,
     deriveGlobalConfigPda,
 } from '../constants';
-import { WalletLike } from '../types';
+import { GlobalAccount, WalletLike } from '../types';
 
 export class DepositClient {
     private program: Program<LiqsolCore>;
@@ -192,23 +192,41 @@ export class DepositClient {
         );
 
         // Distribution / balance-tracking
-        // user_record is keyed by the user’s liqSOL ATA (same convention as deposit/purchase)
+        // user_record is keyed by the user’s liqSOL ATA (same convention
+        // as deposit/purchase).
         const userRecord = deriveUserRecordPda(userAta);
         const distributionState = deriveDistributionStatePda();
 
         // Reserve + stake controller PDAs
-        const global = deriveWithdrawGlobalPda();
+        const global = deriveWithdrawGlobalPda();          // withdraw operator state
         const reservePool = deriveReservePoolPda();
         const stakeAllocationState = deriveStakeAllocationStatePda();
         const stakeMetrics = deriveStakeMetricsPda();
         const maintenanceLedger = deriveMaintenanceLedgerPda();
-        const globalConfig = deriveGlobalConfigPda();
+        const globalConfig = deriveGlobalConfigPda();      // liqSOL config / roles
 
         // -------------------------------------------------------------
         // Need nextReceiptId from withdraw global state
         // -------------------------------------------------------------
-        const globalState = await this.program.account.global.fetch(global);
-        const receiptId = (globalState.nextReceiptId as BN).toBigInt();
+        const globalAcct : GlobalAccount = await this.program.account.global.fetch(global);
+
+        const rawId = globalAcct.nextReceiptId;
+        let receiptId: bigint;
+
+        if (typeof rawId === 'bigint') {
+            // New-style IDL / accounts returning bigint directly
+            receiptId = rawId;
+        } else if (rawId != null && typeof rawId === 'object' && 'toString' in rawId) {
+            // Anchor BN / bn.js or similar – normalize through string
+            receiptId = BigInt(rawId.toString());
+        } else if (typeof rawId === 'number') {
+            // Just in case someone typed it as a JS number in tests
+            receiptId = BigInt(rawId);
+        } else {
+            throw new Error(
+                `DepositClient.buildWithdrawTx: unexpected nextReceiptId type (${typeof rawId})`,
+            );
+        }
 
         // -------------------------------------------------------------
         // NFT receipt PDAs (mint, metadata, data, ATA)
@@ -265,7 +283,7 @@ export class DepositClient {
                 associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
                 systemProgram: SystemProgram.programId,
                 rent: SYSVAR_RENT_PUBKEY,
-                globalConfig
+                globalConfig,
             })
             .instruction();
 

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

@@ -5,11 +5,14 @@ import { SolanaProgramService } from '../program';
 import type { LiqsolCore } from '../../../assets/solana/types/liqsol_core';
 import {
     deriveDistributionStatePda,
+    deriveGlobalConfigPda,
     deriveLiqsolMintPda,
+    derivePayRateHistoryPda,
     deriveUserRecordPda,
 } from '../constants';
-import type { DistributionState, DistributionUserRecord } from '../types';
+import type { DistributionState, DistributionUserRecord, GlobalConfig, PayRateEntry, PayRateHistory } from '../types';
 import { getAssociatedTokenAddressSync, TOKEN_2022_PROGRAM_ID } from '@solana/spl-token';
+import { ceilDiv } from '../utils';
 
 /**
  * Distribution client – wraps the distribution portion of the liqsol_core
@@ -55,6 +58,39 @@ export class DistributionClient {
         }
     }
 
+
+    /**
+     * Fetch the global payRateHistory account (circular buffer of scaled pay rates).
+     *
+     * IDL account name: "payRateHistory"
+     */
+    async getPayRateHistory(): Promise<PayRateHistory | null> {
+        const pda = derivePayRateHistoryPda();
+        try {
+            // Anchor types map directly onto our PayRateHistory TS type
+            return (await this.program.account.payRateHistory.fetch(
+                pda,
+            )) as PayRateHistory;
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Fetch the globalConfig account (contains depositFeeMultiplier, etc).
+     *
+     * IDL account name: "globalConfig"
+     */
+    async getGlobalConfig(): Promise<GlobalConfig | null> {
+        const pda = deriveGlobalConfigPda();
+        try {
+            return (await this.program.account.globalConfig.fetch(
+                pda,
+            ));
+        } catch {
+            return null;
+        }
+    }
     /**
      * Fetch a user's distribution userRecord (or null if missing).
      *
@@ -130,4 +166,86 @@ export class DistributionClient {
 
         return { shares: userShares, totalShares, ratio };
     }
+
+    /**
+     * Compute an average scaled pay rate over the most recent `windowSize`
+     * valid entries in the pay-rate history circular buffer.
+     *
+     * Returns a BN scaled by 1e12 (same as on-chain).
+     */
+    async getAverageScaledPayRate(windowSize = 5): Promise<BN> {
+        const history = await this.getPayRateHistory();
+        if (!history) {
+            return new BN(0);
+        }
+
+        const entries: PayRateEntry[] = history.entries ?? [];
+        if (!entries.length) {
+            return new BN(0);
+        }
+
+        const maxEntries: number =
+            typeof history.maxEntries === 'number'
+                ? history.maxEntries
+                : entries.length;
+
+        const rawTotalAdded: any = history.totalEntriesAdded ?? 0;
+        const totalAddedBn = new BN(rawTotalAdded.toString());
+
+        // No valid entries written yet
+        if (totalAddedBn.isZero()) {
+            return new BN(0);
+        }
+
+        const totalAdded = Math.min(
+            totalAddedBn.toNumber(),
+            maxEntries,
+            entries.length,
+        );
+
+        if (!totalAdded) {
+            return new BN(0);
+        }
+
+        const COUNT = Math.max(1, Math.min(windowSize, totalAdded));
+
+        const currentIndexNum = Number(history.currentIndex ?? 0);
+
+        // Most recently written entry is at currentIndex - 1 (mod maxEntries)
+        let idx =
+            currentIndexNum === 0
+                ? maxEntries - 1
+                : currentIndexNum - 1;
+
+        let sum = new BN(0);
+        let valid = 0;
+        const zero = new BN(0);
+
+        for (let i = 0; i < COUNT; i++) {
+            const entry: any = entries[idx];
+            if (entry) {
+                // Support both camelCase and snake_case (for safety)
+                const rawScaled =
+                    entry.scaledRate ??
+                    entry.scaled_rate ??
+                    0;
+
+                const rate = new BN(rawScaled.toString());
+                if (rate.gt(zero)) {
+                    sum = sum.add(rate);
+                    valid += 1;
+                }
+            }
+
+            // Walk backwards through the circular buffer
+            idx = idx === 0 ? maxEntries - 1 : idx - 1;
+        }
+
+        if (!valid) {
+            return new BN(0);
+        }
+
+        // Same behavior as the dashboard: use a ceiling-like average
+        return ceilDiv(sum, new BN(valid));
+    }
 }

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

@@ -100,34 +100,40 @@ export class OutpostClient {
 
         const pdas = await this.buildAccounts(userPk);
 
-        const [
-            globalState,
-            outpostAccount,
-            distributionState,
-            userPretokenRecord,
-            trancheState,
-        ] = await Promise.all([
-            this.program.account.globalState.fetch(pdas.globalState),
-            this.program.account.outpostAccount.fetchNullable(pdas.outpostAccount),
-            this.program.account.distributionState.fetchNullable(pdas.distributionState),
-            this.program.account.userPretokenRecord.fetchNullable(pdas.userPretokenRecord),
-            this.program.account.trancheState.fetchNullable(pdas.trancheState),
-        ]);
-
-        const [liqsolPoolBalance, userLiqsolBalance] = await Promise.all([
-            this.getTokenBalance(pdas.liqsolPoolAta),
-            this.getTokenBalance(pdas.userAta),
-        ]);
-
-        return {
-            globalState,
-            outpostAccount,
-            distributionState,
-            trancheState,
-            userPretokenRecord,
-            liqsolPoolBalance,
-            userLiqsolBalance,
-        };
+        try {
+            const [
+                globalState,
+                outpostAccount,
+                distributionState,
+                userPretokenRecord,
+                trancheState,
+            ] = await Promise.all([
+                this.program.account.globalState.fetch(pdas.globalState),
+                this.program.account.outpostAccount.fetchNullable(pdas.outpostAccount),
+                this.program.account.distributionState.fetchNullable(pdas.distributionState),
+                this.program.account.userPretokenRecord.fetchNullable(pdas.userPretokenRecord),
+                this.program.account.trancheState.fetchNullable(pdas.trancheState),
+            ]);
+
+            const [liqsolPoolBalance, userLiqsolBalance] = await Promise.all([
+                this.getTokenBalance(pdas.liqsolPoolAta),
+                this.getTokenBalance(pdas.userAta),
+            ]);
+
+            return {
+                globalState,
+                outpostAccount,
+                distributionState,
+                trancheState,
+                userPretokenRecord,
+                liqsolPoolBalance,
+                userLiqsolBalance,
+            };
+        }
+        catch (err) {
+            console.error('Error fetching Outpost wire state:', err);
+            throw err;
+        }
     }
 
     // -------------------------------------------------------------------------

package/src/networks/solana/constants.ts

@@ -89,9 +89,6 @@ export const PDA_SEEDS = {
     MINT_METADATA: 'mint_metadata',
     LIQ_RECEIPT_DATA: 'liq_receipt_data',
     WITHDRAW_MINT: 'mint',
-
-
-
 } as const;
 
 // Global Config PDA

package/src/networks/solana/solana.ts

@@ -4,10 +4,11 @@ import {
     Connection,
     ConnectionConfig,
     PublicKey as SolPubKey,
+    SystemProgram,
     Transaction,
     TransactionSignature,
 } from '@solana/web3.js';
-import { AnchorProvider } from '@coral-xyz/anchor';
+import { AnchorProvider, BN } from '@coral-xyz/anchor';
 import { BaseSignerWalletAdapter } from '@solana/wallet-adapter-base';
 import {
     ASSOCIATED_TOKEN_PROGRAM_ID,
@@ -43,11 +44,14 @@ import {
     INDEX_SCALE,
 } from './constants';
 
-import { buildSolanaTrancheSnapshot } from './utils';
-import { SolanaTransaction } from './types';
+import { buildSolanaTrancheSnapshot, ceilDiv } from './utils';
+import { GlobalConfig, PayRateEntry, SolanaTransaction } from './types';
+import { SolanaProgramService } from './program';
 
 const commitment: Commitment = 'confirmed';
 
+export const SCALE = new BN('1000000000000');
+
 /**
  * Solana implementation of IStakingClient.
  *
@@ -473,17 +477,77 @@ export class SolanaStakingClient implements IStakingClient {
     // READ-ONLY Public Methods
     // ---------------------------------------------------------------------
 
-    // Estimated total APY for staking yeild
-    getSystemAPY(): Promise<number> {
-        // TODO
-        return Promise.resolve(0);
+    // Estimated total APY for staking yield (percent, e.g. 7.23)
+    async getSystemAPY(): Promise<number> {
+        // Reuse same window as the dashboard (5 most recent valid entries)
+        const avgPayRate = await this.distributionClient.getAverageScaledPayRate(5);
+
+        if (avgPayRate.isZero()) {
+            return 0;
+        }
+
+        // 10^12, same scale used on-chain and in the dashboard
+        const SCALE = new BN('1000000000000');
+        const EPOCHS_PER_YEAR = 365; // matches DEFAULT_PAY_RATE semantics
+
+        // Safe: pay rate is well below 1e12, so .toNumber() won't overflow
+        const ratePerPeriod = avgPayRate.toNumber() / SCALE.toNumber(); // e.g. 0.0001917…
+        const apyDecimal = ratePerPeriod * EPOCHS_PER_YEAR;             // e.g. ~0.07
+        const apyPercent = apyDecimal * 100;                            // e.g. 7
+
+        return apyPercent;
     }
 
-    // Protocol fee charged for deposit from Native to LIQ
-    getDepositFee(amount: bigint): Promise<bigint> {
-        // Returning 1% for now, 
-        // TODO: fetch real fee from on-chain config
-        return Promise.resolve((amount * BigInt(1)) / BigInt(100));
+    // ---------------------------------------------
+    // Deposit fee calculation (SOL -> liqSOL)
+    // ---------------------------------------------
+
+    /**
+     * Estimate the protocol deposit fee in lamports for a given SOL amount,
+     * based on recent pay rates and globalConfig.depositFeeMultiplier.
+     *
+     * - amountLamports: deposit notional in lamports
+     * - windowSize: how many recent payRate entries to average (default 5)
+     *
+     * Returns 0n if payRateHistory or globalConfig is missing, or if
+     * there are no valid pay-rate entries yet.
+     */
+    async getDepositFee(
+        amountLamports: bigint,
+        windowSize = 5,
+    ): Promise<bigint> {
+        if (amountLamports <= BigInt(0)) {
+            return BigInt(0);
+        }
+
+        const [avgPayRate, globalConfig] : [BN, GlobalConfig] = await Promise.all([
+            this.distributionClient.getAverageScaledPayRate(windowSize),
+            this.distributionClient.getGlobalConfig(),
+        ]);
+
+        if (!globalConfig || avgPayRate.isZero()) {
+            return BigInt(0);
+        }
+
+        // depositFeeMultiplier may be BN or number depending on your type
+        const rawMultiplier = globalConfig.depositFeeMultiplier;
+        const multiplier = new BN(
+            rawMultiplier?.toString?.() ?? rawMultiplier ?? 0,
+        );
+        if (multiplier.isZero()) {
+            return BigInt(0);
+        }
+
+        const amountBn = new BN(amountLamports.toString());
+
+        // 10^12 scale (matches scaledRate / index scale)
+
+        const feeBn = ceilDiv(
+            avgPayRate.mul(multiplier).mul(amountBn),
+            SCALE,
+        );
+
+        return BigInt(feeBn.toString());
     }
 
     /**
@@ -526,6 +590,75 @@ export class SolanaStakingClient implements IStakingClient {
         });
     }
 
+    /**
+     * Estimate a conservative SOL buffer (lamports) to leave in the wallet
+     * so the user can pay fees for the current deposit and at least one
+     * more transaction, plus a bit extra for future interactions.
+     *
+     * Intended usage in UI:
+     *   const bufferLamports = await client.estimateGasBuffer();
+     *   const maxSpendable = balanceLamports > bufferLamports
+     *       ? balanceLamports - bufferLamports
+     *       : 0n;
+     *
+     * @param options.txCount          How many transactions to cover (default 2)
+     * @param options.safetyMultiplier Extra safety multiplier (default 3x)
+     * @param options.minBufferLamports Optional override minimum buffer (default ~0.01 SOL)
+     */
+    async estimateGasBuffer(options?: {
+        txCount?: number;
+        safetyMultiplier?: number;
+        minBufferLamports?: bigint;
+    }): Promise<bigint> {
+        this.ensureUser();
+
+        const payer = this.solPubKey;
+
+        // 1) Build a small dummy transaction (self-transfer of 0 lamports).
+        const dummyIx = SystemProgram.transfer({
+            fromPubkey: payer,
+            toPubkey: payer,
+            lamports: 0,
+        });
+
+        const tx = new Transaction().add(dummyIx);
+        const { blockhash } = await this.connection.getLatestBlockhash(commitment);
+        tx.recentBlockhash = blockhash;
+        tx.feePayer = payer;
+
+        // 2) Ask the cluster what it would charge in lamports for this tx.
+        const message = tx.compileMessage();
+        const feeInfo = await this.connection.getFeeForMessage(message, commitment);
+
+        // Fallback to a conservative default if RPC doesn't give a value.
+        const singleTxFeeLamports = BigInt(feeInfo.value ?? 5000);
+
+        // 3) How many txs do we want to cover?
+        //    Default: 2 (deposit + one extra operation).
+        const txCount = BigInt(options?.txCount ?? 2);
+
+        // 4) Apply a safety multiplier (default 3x to be very safe).
+        const safetyMultiplier = options?.safetyMultiplier ?? 3;
+        const safetyScaled = BigInt(Math.round(safetyMultiplier * 100)); // e.g. 300
+
+        let bufferLamports =
+            (singleTxFeeLamports *
+                txCount *
+                safetyScaled) /
+            BigInt(100);
+
+        // 5) Enforce a minimum buffer (default ~0.01 SOL).
+        const defaultMinBufferLamports = BigInt(10_000_000); // 0.01 SOL (1e9 / 100)
+        const minBufferLamports =
+            options?.minBufferLamports ?? defaultMinBufferLamports;
+
+        if (bufferLamports < minBufferLamports) {
+            bufferLamports = minBufferLamports;
+        }
+
+        return bufferLamports;
+    }
+
     // ---------------------------------------------------------------------
     // Tx helpers
     // ---------------------------------------------------------------------

package/src/networks/solana/types.ts

@@ -177,7 +177,7 @@ export interface SharesPreview {
  * - NFT withdrawal receipts
  * - Encumbered funds for pending withdrawals
  */
-export type Global = {
+export type GlobalAccount = {
     /** PDA bump */
     bump: number;
 
@@ -210,9 +210,6 @@ export type Global = {
  * - `wireState` lifecycle (preLaunch/postLaunch/refund)
  */
 export type GlobalState = {
-    /** Admin authority for pretokens/outpost config */
-    admin: PublicKey;
-
     /** Deployment timestamp (Unix, seconds) */
     deployedAt: BN;
 
@@ -271,6 +268,135 @@ export type GlobalState = {
     bump: number;
 };
 
+
+/**
+ * IDL: `globalConfig`
+ *
+ * Zero-copy global config PDA.
+ * Authority is taken from StakeControllerState, not stored here.
+ */
+export type GlobalConfig = {
+    /** PDA bump */
+    bump: number;
+
+    /** 7-byte padding (unused) */
+    padding: number[]; // u8[7]
+
+    /** Minimum SOL amount a user can deposit (lamports, u64) */
+    minUserDeposit: BN;
+
+    /** Minimum SOL amount for an unstake/withdrawal request (lamports, u64) */
+    minUnstakeRequest: BN;
+
+    /** Minimum stake delta to trigger a stake rebalance order (lamports, u64) */
+    minRebalanceStakeDelta: BN;
+
+    /** Minimum unstake delta to trigger an unstake rebalance order (lamports, u64) */
+    minRebalanceUnstakeDelta: BN;
+
+    /** Minimum transient stake to include in effective stake calculations (lamports, u64) */
+    transientThreshold: BN;
+
+    /**
+     * Minimum slots that must have elapsed in the epoch before late epoch operations can execute (u64)
+     */
+    minLateEpochSlotGate: BN;
+
+    /** Reserved u64[2] */
+    reservedU64: BN[];
+
+    /**
+     * Epochs a validator must wait in the graveyard before it is booted.
+     * This begins after the last recorded state change (u16)
+     */
+    cooldownEpochs: number;
+
+    /**
+     * Multiplier for deposit fee calculation (u16).
+     * Typically: avg_pay_rate * expected_warmup_epochs
+     */
+    depositFeeMultiplier: number;
+
+    /**
+     * Minimum VPP score required to enter the active validator set,
+     * fallback when the validator set is very small (u16)
+     */
+    minVppEntry: number;
+
+    /**
+     * VPP score threshold below which a validator is removed from active set,
+     * fallback threshold (u16)
+     */
+    minVppExit: number;
+
+    /**
+     * Max validators for "tiny" network band (uses fixed VPP thresholds) (u16)
+     */
+    tinyNetworkThreshold: number;
+
+    /**
+     * Max validators for "small" network band (uses percentile-based selection) (u16)
+     */
+    smallNetworkThreshold: number;
+
+    /**
+     * Max validators for "medium" network band (uses percentile-based selection) (u16)
+     */
+    mediumNetworkThreshold: number;
+
+    /**
+     * Fixed rank threshold to enter active set in large networks (0-indexed, u16)
+     */
+    largeNetworkEntryRank: number;
+
+    /**
+     * Fixed rank threshold to exit active set in large networks (0-indexed, u16)
+     */
+    largeNetworkExitRank: number;
+
+    /** Reserved u16[3] */
+    reservedU16: number[];
+
+    /**
+     * Percentile rank required to enter active set in small networks (u8)
+     */
+    smallNetworkEntryPercent: number;
+
+    /**
+     * Percentile rank below which validators exit in small networks (u8)
+     */
+    smallNetworkExitPercent: number;
+
+    /**
+     * Percentile rank required to enter active set in medium networks (u8)
+     */
+    mediumNetworkEntryPercent: number;
+
+    /**
+     * Percentile rank below which validators exit in medium networks (u8)
+     */
+    mediumNetworkExitPercent: number;
+
+    /** Reserved u8[2] */
+    reservedU8: number[];
+
+    /**
+     * Feature flags (u16 bitfield):
+     *  Bit 0: DepositsEnabled
+     *  Bit 1: WithdrawalsEnabled
+     *  Bit 2: ClaimWithdrawalsEnabled
+     *  Bit 3: ProcessStakeOrdersEnabled
+     *  Bit 4: ProcessUnstakeOrdersEnabled
+     *  Bit 5: ProcessPayCycleEnabled
+     *  Bit 6: RebalancingEnabled
+     *  Bits 7–15: Reserved
+     */
+    featureFlags: number;
+
+    /** Reserved flags (u16[1]) */
+    reservedFlags: number[];
+};
+
 /**
  * ============================================================
  *  Outpost / Pretoken Accounts
@@ -366,9 +492,6 @@ export type UserPretokenRecord = {
  * All price/supply fields use 8-decimal precision (SCALE = 1e8).
  */
 export type TrancheState = {
-    /** Admin authority for tranche parameters */
-    admin: PublicKey;
-
     /** Current tranche number */
     currentTrancheNumber: BN;
 
@@ -387,8 +510,8 @@ export type TrancheState = {
     /** Supply growth in basis points per tranche */
     supplyGrowthBps: number;
 
-    /** Price growth in basis points per tranche */
-    priceGrowthBps: number;
+    /** Price growth in cents per tranche (0.01 USD units) */
+    priceGrowthCents: number;
 
     /** Minimum valid SOL/USD price for Chainlink validation (8-decimal i128) */
     minPriceUsd: BN;