@wireio/stake 0.5.2 → 0.6.69

package/src/networks/solana/types.ts

@@ -11,8 +11,8 @@ export type SolanaTransaction = Transaction | VersionedTransaction;
 
 export type WalletLike = {
     publicKey: PublicKey;
-    signTransaction: (tx: Transaction) => Promise<Transaction>;
-    signAllTransactions?: (txs: Transaction[]) => Promise<Transaction[]>;
+    signTransaction: <T extends SolanaTransaction>(tx: T) => Promise<T>;
+    signAllTransactions?: <T extends SolanaTransaction>(txs: T[]) => Promise<T[]>;
 };
 
 export type ParsedAccountInfo = {
@@ -34,7 +34,11 @@ export type ParsedAccountInfo = {
  */
 
 export type OutpostWireStateSnapshot = {
-    globalState: GlobalState;
+    /**
+     * Global Wire/outpost state.
+     * May be null if the fetch fails.
+     */
+    globalState: GlobalState | null;
 
     /**
      * Per-user Outpost account (old “wire receipt”), or null if user
@@ -60,11 +64,11 @@ export type OutpostWireStateSnapshot = {
     userPretokenRecord: UserPretokenRecord | null;
 
     // Balances
-    /** liqSOL in the pool ATA (Token-2022 raw amount) */
-    liqsolPoolBalance: BN;
+    /** liqSOL in the pool ATA (Token-2022 raw amount), or null on fetch failure */
+    liqsolPoolBalance: BN | null;
 
-    /** liqSOL in the user’s ATA (Token-2022 raw amount) */
-    userLiqsolBalance: BN;
+    /** liqSOL in the user’s ATA (Token-2022 raw amount), or null on fetch failure */
+    userLiqsolBalance: BN | null;
 };
 
 /**
@@ -238,10 +242,10 @@ export type GlobalState = {
     currentIndex: BN;
 
     /**
-     * Last observed liqSOL pool balance
-     * used for computing incremental yield.
+     * Replaced legacy `lastPoolLiqsolBalance`
+     * with expected balance based on total shares and current index.
      */
-    lastPoolLiqsolBalance: BN;
+    expectedPoolBalance: BN;
 
     /**
      * Accumulated liqSOL yield available to the protocol
@@ -262,7 +266,7 @@ export type GlobalState = {
     roleWarmupDuration: BN;
 
     /** Wire lifecycle state (preLaunch / postLaunch / refund) */
-    wireState: WireState;
+    wireState: WireState | any;
 
     /** PDA bump */
     bump: number;
@@ -615,7 +619,7 @@ export type LeaderboardState = {
      * Per-validator scores (i64 on-chain).
      * Index corresponds to `registryIndex` in ValidatorRecord.
      */
-    scores: BN[];
+    scores: number[];
 
     /**
      * Sorted indices into `scores[]` / `voteAccounts[]`,
@@ -628,7 +632,7 @@ export type LeaderboardState = {
      * `voteAccounts[i]` is the vote account for validator with
      * `registryIndex == i`.
      */
-    voteAccounts: PublicKey[];
+    voteAccounts: { bytes: number[]; }[];
 
     /**
      * Number of active validators currently tracked in the leaderboard.
@@ -643,7 +647,7 @@ export type LeaderboardState = {
      * Reserved padding / future-proofing on-chain (u64[8]).
      * Not used by client logic, but surfaced for completeness.
      */
-    padding: BN[];
+    padding: number[];
 };
 
 /**
@@ -728,4 +732,26 @@ export type ValidatorRecord = {
      * PDA bump seed for validatorRecord.
      */
     bump: number;
-};
+};
+
+/**
+ * IDL: `receiptData`
+ *
+ * Withdrawal receipt data structure tracking pending withdrawals.
+ * Each receipt represents a user's request to withdraw liqSOL,
+ * with the withdrawal contingent on sufficient encumbered funds
+ * being available at the serviceable epoch.
+ */
+export type ReceiptData = {
+    /** Unique receipt identifier (monotonically increasing, u64) */
+    receiptId: bigint;
+
+    /** Amount of liqSOL requested for withdrawal (Token-2022 raw amount, u64) */
+    liqports: bigint;
+
+    /** Epoch at which this receipt becomes claimable (u64) */
+    epoch: bigint;
+
+    /** Flag indicating whether this receipt has been fulfilled/claimed (bool) */
+    fulfilled: boolean;
+};

package/src/networks/solana/utils.ts

@@ -1,65 +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,
-    deriveOutpostAccountPda,
-    deriveTrancheStatePda,
-    deriveUserPretokenRecordPda,
     CHAINLINK_FEED,
     CHAINLINK_PROGRAM,
-    deriveExtraAccountMetaListPda,
 } 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;
@@ -80,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.
@@ -112,9 +105,9 @@ export function buildSolanaTrancheLadder(options: {
     currentTranche: number;
     initialTrancheSupply: bigint;
     currentTrancheSupply: bigint;
-    currentPriceUsd: bigint;
+    currentPriceUsd: bigint;    // 1e8 scale
     supplyGrowthBps: number;
-    priceGrowthCents: number;
+    priceGrowthCents: number;   // e.g. 2 -> $0.02 per tranche
     windowBefore?: number;
     windowAfter?: number;
 }): TrancheLadderItem[] {
@@ -135,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, priceGrowthCents));
+
+        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, priceGrowthCents));
+
+        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);
         }
 
@@ -172,7 +171,7 @@ export function buildSolanaTrancheLadder(options: {
             capacity: cap,
             sold,
             remaining: cap - sold,
-            priceUsd: price.get(id)!,
+            priceUsd: price.get(id)!, // still 1e8 scale
         });
     }
 
@@ -240,265 +239,6 @@ export function buildSolanaTrancheSnapshot(options: {
     };
 }
 
-
-// -----------------------------------------------------------------------------
-// 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.
- *
- * NOTE: user_record is keyed by the TOKEN ACCOUNT (ATA), not the wallet.
- * Here we derive the user's liqSOL ATA and then its user_record PDA.
- */
-export async function getUserRecordRaw(
-    connection: Connection,
-    user: PublicKey,
-): Promise<Uint8Array | null> {
-    const liqsolMint = deriveLiqsolMintPda();
-    const userAta = await getAssociatedTokenAddress(
-        liqsolMint,
-        user,
-        false,
-        TOKEN_2022_PROGRAM_ID,
-    );
-    const pda = deriveUserRecordPda(userAta);
-    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;
-        const payRateHistoryAccount = await anyProgram.account.payRateHistory.fetch(
-            payRateHistoryPda,
-        );
-
-        const entries = 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
@@ -536,22 +276,32 @@ export interface OutpostAccounts {
 
     // 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 bucketAuthority = deriveBucketAuthorityPda();
-    const trancheState = deriveTrancheStatePda();
+    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 = deriveOutpostAccountPda(user);
-    const userPretokenRecord = deriveUserPretokenRecordPda(user);
+    const outpostAccount = pgs.deriveOutpostAccountPda(user);
+    const userPretokenRecord = pgs.deriveUserPretokenRecordPda(user);
 
     // ATAs
     const liqsolPoolAta = await getAssociatedTokenAddress(
@@ -571,23 +321,32 @@ 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 = deriveUserRecordPda(bucketTokenAccount);
-    const liqsolPoolUserRecord = deriveUserRecordPda(liqsolPoolAta);
-    const userUserRecord = deriveUserRecordPda(userAta);
+    const bucketUserRecord = pgs.deriveUserRecordPda(bucketTokenAccount);
+    const liqsolPoolUserRecord = pgs.deriveUserRecordPda(liqsolPoolAta);
+    const userUserRecord = pgs.deriveUserRecordPda(userAta);
 
-    const extraAccountMetaList = deriveExtraAccountMetaListPda(liqsolMint);
+    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;
 
     try {
-        const program = getLiqsolCoreProgram(connection);
+        const program = pgs.getProgram('liqsolCore');
         const ts: TrancheState =
             await program.account.trancheState.fetch(trancheState);
 
@@ -622,7 +381,12 @@ export async function buildOutpostAccounts(
         trancheState,
         chainLinkFeed,
         chainLinkProgram,
-        extraAccountMetaList
+        extraAccountMetaList,
+        pretokenPurchaseHistory,
+        globalConfig,
+        oppEpochState,
+        pendingAttestations,
+        bridgeState,
     };
 }
 // -----------------------------------------------------------------------------
@@ -805,4 +569,19 @@ export function ceilDiv(n: BN, d: BN): BN {
         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;
+    }
+};