@wireio/stake 0.0.6 → 0.1.1

package/src/networks/solana/utils.ts

@@ -1,122 +1,551 @@
-// src/solana/utils.ts
-import { AnchorProvider, Program } from '@coral-xyz/anchor'
-import { PublicKey } from '@solana/web3.js'
-import { getAssociatedTokenAddressSync, TOKEN_2022_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID } from '@solana/spl-token'
+// src/networks/solana/utils.ts
+
+import { Program, BN, AnchorProvider } from '@coral-xyz/anchor';
+
 import {
-    DEPOSIT_PROGRAM_ID,
-    DISTRIBUTION_PROGRAM_ID,
-    STAKE_CONTROLLER_PROGRAM_ID,
-    VALIDATOR_LEADERBOARD_PROGRAM_ID,
-    LIQSOL_MINT_ADDRESS,
-    DepositIDL,
-    Deposit
-} from './constants'
-
-// -- Program factories ------------------------------------------------------
+    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,
+} from './constants';
+
+import liqsolCoreIDL from '../../assets/solana/idl/liqsol_core.json';
+
+// -----------------------------------------------------------------------------
+// Read-only liqsol_core Program helper
+// -----------------------------------------------------------------------------
+
+let _liqsolCoreProgram: Program | null = null;
+
+export function getLiqsolCoreProgram(
+    connection: Connection,
+): Program {
+    if (_liqsolCoreProgram && _liqsolCoreProgram.provider.connection === connection) {
+        return _liqsolCoreProgram;
+    }
+
+    // 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 };
+
+    const provider = new AnchorProvider(connection, wallet, {
+        commitment: 'confirmed',
+    });
+
+    const program = new Program(
+        liqsolCoreIDL,
+        provider,
+    ) as Program;
+
+    _liqsolCoreProgram = program;
+    return program;
+}
+
+// -----------------------------------------------------------------------------
+// Deposit accounts bundle
+// -----------------------------------------------------------------------------
+
+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;
+}
+
 /**
- * Create an Anchor Program client for the Deposit program
+ * Build a complete DepositAccounts set for a given user, matching the
+ * on-chain PDAs used by the liqSOL core program.
+ *
+ * The optional `seed` lets you make deposit flows replayable/deterministic.
+ * If omitted, a random u32 seed is generated.
  */
-export function getDepositProgram(provider: AnchorProvider): Program<Deposit> {
-    // Ensure the IDL has the correct program address
-    const idlWithAddress = {
-        ...JSON.parse(JSON.stringify(DepositIDL)),
-        address: DEPOSIT_PROGRAM_ID.toString(),
+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();
+
+    const userAta = await getAssociatedTokenAddress(
+        liqsolMint,
+        user,
+        false,
+        TOKEN_2022_PROGRAM_ID,
+    );
+
+    const bucketTokenAccount = await getAssociatedTokenAddress(
+        liqsolMint,
+        bucketAuthority,
+        true,
+        TOKEN_2022_PROGRAM_ID,
+    );
+
+    // -------------------------------------------------------------
+    // Ephemeral stake
+    // -------------------------------------------------------------
+    const seed = Math.floor(Math.random() * 2 ** 32);
+    const ephemeralSeed = `ephemeral_${seed}`;
+    const ephemeralStake = await deriveEphemeralStakeAddress(user, ephemeralSeed);
+
+    // `connection` is currently unused, but we keep it in the signature
+    // so this helper can evolve to preflight/validate accounts if needed.
+    void connection;
+
+    return {
+        user,
+        depositAuthority,
+        liqsolMint,
+        liqsolMintAuthority,
+        userAta,
+        stakeControllerVault,
+        stakeControllerReservePool,
+        stakeControllerState,
+        payoutState,
+        bucketAuthority,
+        bucketTokenAccount,
+        distributionState,
+        userRecord,
+        payRateHistory,
+        ephemeralStake,
+        ephemeralSeed,
+    };
+}
+
+// -----------------------------------------------------------------------------
+// Balance + state getters (UI-friendly)
+// -----------------------------------------------------------------------------
+
+export async function getUserLiqSolBalance(
+    connection: Connection,
+    user: PublicKey,
+): Promise<number> {
+    const liqsolMint = deriveLiqsolMintPda();
+    const ata = await getAssociatedTokenAddress(
+        liqsolMint,
+        user,
+        false,
+        TOKEN_2022_PROGRAM_ID,
+    );
+
+    try {
+        const bal = await connection.getTokenAccountBalance(ata);
+        return Number(bal.value.amount); // raw lamports, not decimals-adjusted
+    } catch {
+        return 0;
     }
-    return new Program(idlWithAddress as any, provider) as Program<Deposit>
 }
 
-// (Other program factories can go here if needed)
+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,
+    );
 
-// -- PDA derivation helpers ------------------------------------------------
-export function deriveDepositAuthorityPDA(
-    programId: PublicKey = DEPOSIT_PROGRAM_ID
-): [PublicKey, number] {
-    return PublicKey.findProgramAddressSync(
-        [Buffer.from('program_authority')],
-        programId
-    )
+    try {
+        const bal = await connection.getTokenAccountBalance(ata);
+        return Number(bal.value.amount);
+    } catch {
+        return 0;
+    }
 }
 
-export function deriveLiqsolMintAuthorityPDA(
-    programId: PublicKey = LIQSOL_MINT_ADDRESS
-): [PublicKey, number] {
-    return PublicKey.findProgramAddressSync(
-        [Buffer.from('mint_authority')],
-        programId
-    )
+export async function getReservePoolBalance(
+    connection: Connection,
+): Promise<number> {
+    const reservePool = deriveReservePoolPda();
+    try {
+        const lamports = await connection.getBalance(reservePool);
+        return lamports;
+    } catch {
+        return 0;
+    }
 }
 
-export function deriveStakeControllerVaultPDA(): [PublicKey, number] {
-    return PublicKey.findProgramAddressSync(
-        [Buffer.from('vault')],
-        STAKE_CONTROLLER_PROGRAM_ID
-    )
+/**
+ * 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;
 }
 
-export function deriveStakeControllerReservePoolPDA(): [PublicKey, number] {
-    return PublicKey.findProgramAddressSync(
-        [Buffer.from('reserve_pool')],
-        STAKE_CONTROLLER_PROGRAM_ID
-    )
+/**
+ * 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;
 }
 
-export function deriveStakeControllerStatePDA(): [PublicKey, number] {
-    return PublicKey.findProgramAddressSync(
-        [Buffer.from('stake_controller')],
-        STAKE_CONTROLLER_PROGRAM_ID
-    )
+/**
+ * Raw account info for a user's distribution user_record.
+ */
+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 deriveDistributionStatePDA(): [PublicKey, number] {
-    return PublicKey.findProgramAddressSync(
-        [Buffer.from('distribution_state')],
-        DISTRIBUTION_PROGRAM_ID
-    )
+// -----------------------------------------------------------------------------
+// Pay-rate & fee utilities (on-chain compatible)
+// -----------------------------------------------------------------------------
+
+export async function getAveragePayRate(
+    connection: Connection,
+    lookback: number = DEFAULT_PAY_RATE_LOOKBACK,
+): Promise<bigint> {
+    const program = getLiqsolCoreProgram(connection);
+    const payRateHistoryPda = derivePayRateHistoryPda();
+
+    try {
+        const anyProgram = program as any;
+        const payRateHistoryAccount = await anyProgram.account.payRateHistory.fetch(
+            payRateHistoryPda,
+        );
+
+        const entries: any[] = payRateHistoryAccount.entries ?? [];
+        const totalEntriesAdded = Number(
+            payRateHistoryAccount.totalEntriesAdded ?? 0,
+        );
+        const currentIndex: number = payRateHistoryAccount.currentIndex ?? 0;
+        const maxEntries: number =
+            payRateHistoryAccount.maxEntries ?? entries.length;
+
+        if (!entries.length) {
+            return DEFAULT_AVERAGE_PAY_RATE;
+        }
+
+        const entriesToFetch = Math.min(lookback, maxEntries, entries.length);
+
+        let idx: number;
+        if (totalEntriesAdded === 0) {
+            idx = 0;
+        } else if (currentIndex === 0) {
+            idx = maxEntries - 1;
+        } else {
+            idx = currentIndex - 1;
+        }
+
+        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);
+                }
+            }
+
+            if (totalEntriesAdded === 0) {
+                idx = (idx + 1) % maxEntries;
+            } else {
+                idx = idx === 0 ? maxEntries - 1 : idx - 1;
+            }
+        }
+
+        if (validCount === BigInt(0)) {
+            return DEFAULT_AVERAGE_PAY_RATE;
+        }
+
+        return sum / validCount;
+    } catch (err) {
+        // Fallback to default when history missing/unavailable
+        return DEFAULT_AVERAGE_PAY_RATE;
+    }
 }
+/**
+ * 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);
 
-export function deriveUserRecordPDA(
-    user: PublicKey
-): [PublicKey, number] {
-    return PublicKey.findProgramAddressSync(
-        [Buffer.from('user_record'), user.toBuffer()],
-        DISTRIBUTION_PROGRAM_ID
-    )
+    return {
+        feeLamports: fee,
+        userLiqSolLamports: userLiqSol,
+        bucketLiqSolLamports: bucketLiqSol,
+        reserveIncreaseLamports: reserveIncrease,
+    };
 }
 
-export function deriveLeaderboardHeadPDA(): [PublicKey, number] {
-    return PublicKey.findProgramAddressSync(
-        [Buffer.from('leaderboard_head')],
-        VALIDATOR_LEADERBOARD_PROGRAM_ID
-    )
+// -----------------------------------------------------------------------------
+// Epoch / scheduling helpers
+// -----------------------------------------------------------------------------
+
+export type EpochSnapshot = {
+    epoch: number;
+    slot: number;
+    firstSlot: number;
+    slotsInEpoch: number;
+    slotMs: number;
+};
+
+export async function getEpochSnapshot(
+    connection: Connection,
+): Promise<EpochSnapshot> {
+    const info = await connection.getEpochInfo();
+
+    // Fallback slot time
+    let slotTimeMs = Number(process.env.SLOT_TIME_MS_FALLBACK ?? 400);
+
+    try {
+        const samples = await connection.getRecentPerformanceSamples(16);
+        if (samples.length) {
+            const avgMs =
+                samples.reduce(
+                    (acc, s) => acc + (s.samplePeriodSecs * 1000) / s.numSlots,
+                    0,
+                ) / samples.length;
+            if (isFinite(avgMs) && avgMs > 0) {
+                slotTimeMs = avgMs;
+            }
+        }
+    } catch {
+        // ignore; keep fallback
+    }
+
+    return {
+        epoch: info.epoch,
+        slot: info.slotIndex,
+        firstSlot: info.absoluteSlot - info.slotIndex,
+        slotsInEpoch: info.slotsInEpoch,
+        slotMs: slotTimeMs,
+    };
 }
 
-export function deriveValidatorRecordPDA(
-    voteAccount: PublicKey
-): [PublicKey, number] {
-    return PublicKey.findProgramAddressSync(
-        [Buffer.from('validator_record'), voteAccount.toBuffer()],
-        VALIDATOR_LEADERBOARD_PROGRAM_ID
-    )
+export function msToEpochEnd(snapshot: EpochSnapshot): number {
+    const remainingSlots = snapshot.slotsInEpoch - snapshot.slot;
+    return remainingSlots * snapshot.slotMs;
 }
 
-export function deriveTop10CachePDA(): [PublicKey, number] {
-    return PublicKey.findProgramAddressSync(
-        [Buffer.from('top_10_cache')],
-        VALIDATOR_LEADERBOARD_PROGRAM_ID
-    )
+/**
+ * Generic "execute around epoch boundaries" helper:
+ *
+ * - If current progress is within [early, late], run immediately.
+ * - If too early, sleep until `early` percentage into the epoch.
+ * - If too late, sleep until `early` percentage into the *next* epoch.
+ *
+ * This is generic; you can wrap any instruction builder in here (including
+ * deposit flows) without baking in program-specific logic.
+ */
+export async function scheduledInstruction<T>(
+    connection: Connection,
+    config: ScheduleConfig,
+    instruction: () => Promise<T>,
+): Promise<T> {
+    const early = config.early ?? 0.10;
+    const late = config.late ?? 0.90;
+
+    const snapshot = await getEpochSnapshot(connection);
+    const progress = snapshot.slot / snapshot.slotsInEpoch;
+
+    // Case 1: Already in safe zone
+    if (progress >= early && progress <= late) {
+        return instruction();
+    }
+
+    // Case 2: Early in epoch → wait until `early`
+    if (progress < early) {
+        const targetSlot = snapshot.slotsInEpoch * early;
+        const slotsRemaining = targetSlot - snapshot.slot;
+        const msToWait = slotsRemaining * snapshot.slotMs;
+
+        console.log(
+            `Epoch early (${(progress * 100).toFixed(
+                2,
+            )}%). Sleeping ${(msToWait / 1000).toFixed(1)}s until ${early * 100
+            }%...`,
+        );
+
+        await sleep(Math.max(1000, msToWait));
+        return instruction();
+    }
+
+    // Case 3: Late in epoch → wait for next epoch + early window
+    const msToNextEpoch = msToEpochEnd(snapshot);
+    const earlyWaitTime = snapshot.slotsInEpoch * early * snapshot.slotMs;
+    const totalWaitTime = msToNextEpoch + earlyWaitTime + 1000;
+
+    console.log(
+        `Epoch late (${(progress * 100).toFixed(
+            2,
+        )}%). Sleeping ${(totalWaitTime / 1000).toFixed(
+            1,
+        )}s until next epoch + ${early * 100}%...`,
+    );
+
+    await sleep(totalWaitTime);
+    return instruction();
 }
 
-// -- SPL Token helper -------------------------------------------------------
-export function getUserLiqsolATA(
-    user: PublicKey
-): PublicKey {
-    return getAssociatedTokenAddressSync(
-        LIQSOL_MINT_ADDRESS,
-        user,
-        false,
-        TOKEN_2022_PROGRAM_ID,
-        ASSOCIATED_TOKEN_PROGRAM_ID
-    )
+
+// -----------------------------------------------------------------------------
+// Generic helpers (used in tests + can be useful in apps)
+// -----------------------------------------------------------------------------
+
+export function getErrorMessage(error: any): string {
+    return (
+        error?.error?.errorCode?.code ||
+        error?.error?.errorMessage ||
+        error?.message ||
+        ''
+    );
+}
+
+export function generateRandomDepositAmount(
+    minSol = 2,
+    maxSol = 100,
+): BN {
+    const randomSol = Math.random() * (maxSol - minSol) + minSol;
+    return new BN(solToLamports(randomSol));
+}
+
+export function generateTestKeypair(): Keypair {
+    return Keypair.generate();
+}
+
+export async function airdropSol(
+    connection: Connection,
+    publicKey: PublicKey,
+    amountSol: number,
+): Promise<void> {
+    const lamports = solToLamports(amountSol);
+    const sig = await connection.requestAirdrop(publicKey, lamports);
+    await connection.confirmTransaction(sig, 'confirmed');
+}
+
+export async function waitForConfirmation(
+    connection: Connection,
+    signature: string,
+): Promise<void> {
+    await connection.confirmTransaction(signature, 'confirmed');
+}
+
+export function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Simple helper used in tests: wait until safe zone, no-op.
+ */
+export async function waitUntilSafeToExecuteFunction(
+    connection: Connection,
+    config: ScheduleConfig = {},
+): Promise<void> {
+    await scheduledInstruction(connection, config, async () => {
+        // no-op
+        return;
+    });
+}
+
+export interface ScheduleConfig {
+    early?: number; // fraction of epoch, default 0.10
+    late?: number;  // fraction of epoch, default 0.90
 }
 
-// seedToPID(seed: string): PublicKey 

package/src/scripts/fetch-artifacts.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+set -e
+
+# Define variables
+IDL_ZIP_URL="https://bucket.gitgo.app/solana/idl.zip"
+TYPES_ZIP_URL="https://bucket.gitgo.app/solana/types.zip"
+DEST_DIR="$(dirname "$0")/../assets/solana"
+TMP_DIR="$(mktemp -d)"
+
+# Download the zip files
+curl -L "$IDL_ZIP_URL" -o "$TMP_DIR/idl.zip"
+curl -L "$TYPES_ZIP_URL" -o "$TMP_DIR/types.zip"
+
+# Create destination directory if it doesn't exist
+mkdir -p "$DEST_DIR"
+
+# Unzip into the destination directory
+unzip -o "$TMP_DIR/idl.zip" -d "$DEST_DIR"
+unzip -o "$TMP_DIR/types.zip" -d "$DEST_DIR"
+
+# Clean up
+rm -rf "$TMP_DIR"
+
+echo "IDL and types files fetched and extracted to $DEST_DIR"

package/src/scripts/tsconfig.json

@@ -0,0 +1,17 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "module": "commonjs",
+        "target": "es2019",
+        "moduleResolution": "node",
+        "types": [
+            "node"
+        ],
+        "isolatedModules": false
+    },
+    "include": [
+        "./**/*",
+        "../networks/**/*",
+        "../assets/**/*"
+    ]
+}