@wireio/stake 0.3.0 → 0.3.69

package/src/networks/solana/utils.ts

@@ -1,69 +1,76 @@
 import { Program, BN, AnchorProvider } from '@coral-xyz/anchor';
-
 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,
-    deriveOutpostGlobalStatePda,
-    deriveOutpostPoolAuthorityPda,
-    deriveSolBucketPda,
-    deriveTrancheStatePda,
-    deriveWireReceiptPda,
-    derivePoolUserRecordPda,
-    deriveUserUserRecordPda,
-    deriveUserWarrantRecordPda,
     CHAINLINK_FEED,
     CHAINLINK_PROGRAM,
 } from './constants';
 
-import liqsolCoreIDL from '../../assets/solana/idl/liqsol_core.json';
-import { LiqsolCore } from '../../assets/solana/types/liqsol_core';
 import { GlobalState, TrancheState } from './types';
 import { TrancheLadderItem, TrancheSnapshot } from '../../types';
 import { ChainID } from '@wireio/core';
-
+import { SolanaProgramService } from './program';
 
 // -----------------------------------------------------------------------------
 // Tranche Support
 // -----------------------------------------------------------------------------
-
-
 const INDEX_SCALE = BigInt(1_000_000_000_000); // 1e12
-const USD_SCALE = BigInt(100_000_000);         // 1e8
+const USD_SCALE = BigInt(100_000_000);       // 1e8
 const BPS = BigInt(10_000);
 
+/**
+ * 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;
+}
+
+/**
+ * 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);
+}
+
+/**
+ * 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;
+}
+
+function growPriceOnceUsd1e8(value: bigint, priceGrowthCents: number): bigint {
+    const step = priceStepUsd1e8(priceGrowthCents);
+    return value + step;
+}
+
+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;
+}
+
 /** BN | bigint -> bigint helper (keeps code readable) */
 export function toBigint(x: any): bigint {
     if (typeof x === 'bigint') return x;
@@ -84,24 +91,6 @@ export function tokensToShares(amount: bigint, currentIndex: bigint): bigint {
     return r === BigInt(0) ? q : q + BigInt(1);
 }
 
-/**
- * Apply one forward growth step: value * (BPS + growthBps) / BPS.
- * Simple integer round-half-up.
- */
-function growOnce(value: bigint, growthBps: number): bigint {
-    const g = BigInt(growthBps);
-    return (value * (BPS + g) + BPS / BigInt(2)) / BPS;
-}
-
-/**
- * Apply one backward step: value * BPS / (BPS + growthBps).
- * Also integer round-half-up.
- */
-function shrinkOnce(value: bigint, growthBps: number): bigint {
-    const g = BigInt(growthBps);
-    return (value * BPS + (BPS + g) / BigInt(2)) / (BPS + g);
-}
-
 /**
  * Build a local tranche ladder around the current tranche
  * using only on-chain config + current state.
@@ -116,10 +105,9 @@ export function buildSolanaTrancheLadder(options: {
     currentTranche: number;
     initialTrancheSupply: bigint;
     currentTrancheSupply: bigint;
-    totalPretokensSold: bigint; // informational only
-    currentPriceUsd: bigint;
+    currentPriceUsd: bigint;    // 1e8 scale
     supplyGrowthBps: number;
-    priceGrowthBps: number;
+    priceGrowthCents: number;   // e.g. 2 -> $0.02 per tranche
     windowBefore?: number;
     windowAfter?: number;
 }): TrancheLadderItem[] {
@@ -129,7 +117,7 @@ export function buildSolanaTrancheLadder(options: {
         currentTrancheSupply,
         currentPriceUsd,
         supplyGrowthBps,
-        priceGrowthBps,
+        priceGrowthCents,
         windowBefore = 5,
         windowAfter = 5,
     } = options;
@@ -140,35 +128,41 @@ export function buildSolanaTrancheLadder(options: {
     const capacity = new Map<number, bigint>();
     const price = new Map<number, bigint>();
 
-    // Seed current
+    // Seed current tranche
     capacity.set(currentTranche, initialTrancheSupply);
     price.set(currentTranche, currentPriceUsd);
 
-    // Forward (future tranches)
+    // 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, growOnce(prevCap, supplyGrowthBps));
-        price.set(id, growOnce(prevPrice, priceGrowthBps));
+
+        capacity.set(id, growSupplyOnce(prevCap, supplyGrowthBps));
+        price.set(id, growPriceOnceUsd1e8(prevPrice, priceGrowthCents));
     }
 
-    // Backward (past tranches)
+    // 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)!;
-        capacity.set(id, shrinkOnce(nextCap, supplyGrowthBps));
-        price.set(id, shrinkOnce(nextPrice, priceGrowthBps));
+
+        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);
         }
 
@@ -177,7 +171,7 @@ export function buildSolanaTrancheLadder(options: {
             capacity: cap,
             sold,
             remaining: cap - sold,
-            priceUsd: price.get(id)!,
+            priceUsd: price.get(id)!, // still 1e8 scale
         });
     }
 
@@ -209,31 +203,21 @@ export function buildSolanaTrancheSnapshot(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 priceGrowthBps = trancheState.priceGrowthBps;
-
-    const minPriceUsd = trancheState.minPriceUsd
-        ? toBigint(trancheState.minPriceUsd)
-        : undefined;
-    const maxPriceUsd = trancheState.maxPriceUsd
-        ? toBigint(trancheState.maxPriceUsd)
-        : undefined;
+    const priceGrowthCents = trancheState.priceGrowthCents;
 
     const ladder = buildSolanaTrancheLadder({
         currentTranche,
         initialTrancheSupply,
         currentTrancheSupply,
-        totalPretokensSold,
         currentPriceUsd,
         supplyGrowthBps,
-        priceGrowthBps,
+        priceGrowthCents,
         windowBefore: ladderWindowBefore,
         windowAfter: ladderWindowAfter,
     });
@@ -245,306 +229,81 @@ export function buildSolanaTrancheSnapshot(options: {
         currentTranche,
         currentPriceUsd,
         supplyGrowthBps,
-        priceGrowthBps,
+        priceGrowthCents,
+        totalPretokensSold,
         currentTrancheSupply,
         initialTrancheSupply,
-        totalPretokensSold,
         nativePriceUsd: solPriceUsd,
         nativePriceTimestamp,
         ladder,
     };
 }
 
-
-// -----------------------------------------------------------------------------
-// Read-only liqsol_core Program helper
-// -----------------------------------------------------------------------------
-
-let _liqsolCoreProgram: Program<LiqsolCore> | null = null;
-
-export function getLiqsolCoreProgram(
-    connection: Connection,
-): Program<LiqsolCore> {
-    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<LiqsolCore>;
-
-    _liqsolCoreProgram = program;
-    return program;
-}
-
-
-// -----------------------------------------------------------------------------
-// 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;
-    }
-}
-
-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,
-    );
-
-    try {
-        const bal = await connection.getTokenAccountBalance(ata);
-        return Number(bal.value.amount);
-    } catch {
-        return 0;
-    }
-}
-
-export async function getReservePoolBalance(
-    connection: Connection,
-): Promise<number> {
-    const reservePool = deriveReservePoolPda();
-    try {
-        const lamports = await connection.getBalance(reservePool);
-        return lamports;
-    } catch {
-        return 0;
-    }
-}
-
-/**
- * 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;
-}
-
-/**
- * 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;
-}
-
-/**
- * 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;
-}
-
-// -----------------------------------------------------------------------------
-// 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);
-
-    return {
-        feeLamports: fee,
-        userLiqSolLamports: userLiqSol,
-        bucketLiqSolLamports: bucketLiqSol,
-        reserveIncreaseLamports: reserveIncrease,
-    };
-}
-
 /**
  * ---------------------------------------------------------------------------
  * 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;
 
-    // Warrant / outpost
+    // Outpost / pretoken wiring
     globalState: PublicKey;
     poolAuthority: PublicKey;
     liqsolMint: PublicKey;
     liqsolPoolAta: PublicKey;
     userAta: PublicKey;
-    wireReceipt: PublicKey;
-    poolUserRecord: PublicKey;
-    userUserRecord: PublicKey;
+    outpostAccount: PublicKey;
+    userPretokenRecord: PublicKey;
+
+    // Distribution / yield context (user_record keyed by token accounts)
     distributionState: PublicKey;
-    payRateHistory: PublicKey;
     bucketAuthority: PublicKey;
     bucketTokenAccount: PublicKey;
-    solBucket: PublicKey;
+    bucketUserRecord: PublicKey;
+    liqsolPoolUserRecord: PublicKey;
+    userUserRecord: PublicKey;
+
+    // Tranche / pricing
     trancheState: PublicKey;
-    userWarrantRecord: PublicKey;
 
     // Chainlink
     chainLinkFeed: PublicKey;
     chainLinkProgram: PublicKey;
+
+    // Transfer hook extra accounts
+    extraAccountMetaList: PublicKey;
+
+    // New
+    pretokenPurchaseHistory: PublicKey;
+
+    // OPP (outpost protocol pipeline)
+    globalConfig: PublicKey;
+    oppEpochState: PublicKey;
+    pendingAttestations: PublicKey;
+    bridgeState: PublicKey;
 }
 
 export async function buildOutpostAccounts(
     connection: Connection,
     user: PublicKey,
+    pgs: SolanaProgramService,
 ): Promise<OutpostAccounts> {
-    const globalState = deriveOutpostGlobalStatePda();
-    const poolAuthority = deriveOutpostPoolAuthorityPda();
-    const liqsolMint = deriveLiqsolMintPda();
-    const distributionState = deriveDistributionStatePda();
-    const payRateHistory = derivePayRateHistoryPda();
-    const bucketAuthority = deriveBucketAuthorityPda();
-    const solBucket = deriveSolBucketPda();
-    const trancheState = deriveTrancheStatePda();
-    const wireReceipt = deriveWireReceiptPda(user);
-    const poolUserRecord = derivePoolUserRecordPda(poolAuthority);
-    const userUserRecord = deriveUserUserRecordPda(user);
-    const userWarrantRecord = deriveUserWarrantRecordPda(user);
-
+    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,
@@ -562,25 +321,44 @@ export async function buildOutpostAccounts(
     const userAta = await getAssociatedTokenAddress(
         liqsolMint,
         user,
-        false,
+        true, // allow off curve in case squadsx vault
         TOKEN_2022_PROGRAM_ID,
     );
 
+    // 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 extraAccountMetaList = pgs.deriveExtraAccountMetaListPda(liqsolMint);
+
+    const pretokenPurchaseHistory = pgs.derivePretokenPurchaseHistoryPda(poolAuthority);
+
+    // 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();
+
     // Chainlink program feeds
     let chainLinkFeed = CHAINLINK_FEED;
-    let chainLinkProgram = CHAINLINK_PROGRAM
+    let chainLinkProgram = CHAINLINK_PROGRAM;
 
     try {
-        const program = getLiqsolCoreProgram(connection);
-        const ts: TrancheState = await program.account.trancheState.fetch(trancheState);
+        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;
         }
     } catch {
         // If trancheState isn't initialized yet, we fall back to the constants.
-        // In that case, pretoken instructions will still fail, which is the correct
-        // behavior until admin initializes TrancheState on-chain.
+        // In that case, purchase instructions will still fail, which is the
+        // correct behavior until admin initializes TrancheState on-chain.
     }
 
     void connection; // reserved for future extra validation
@@ -592,21 +370,25 @@ export async function buildOutpostAccounts(
         liqsolMint,
         liqsolPoolAta,
         userAta,
-        wireReceipt,
-        poolUserRecord,
-        userUserRecord,
+        outpostAccount,
+        userPretokenRecord,
         distributionState,
-        payRateHistory,
         bucketAuthority,
         bucketTokenAccount,
-        solBucket,
+        bucketUserRecord,
+        liqsolPoolUserRecord,
+        userUserRecord,
         trancheState,
-        userWarrantRecord,
         chainLinkFeed,
         chainLinkProgram,
+        extraAccountMetaList,
+        pretokenPurchaseHistory,
+        globalConfig,
+        oppEpochState,
+        pendingAttestations,
+        bridgeState,
     };
 }
-
 // -----------------------------------------------------------------------------
 // Epoch / scheduling helpers
 // -----------------------------------------------------------------------------
@@ -782,3 +564,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;
+    }
+};