@wireio/stake 0.3.1 → 0.4.1

package/src/networks/solana/types.ts

@@ -1,7 +1,13 @@
 import { PublicKey, TokenAmount, Transaction, VersionedTransaction } from "@solana/web3.js";
 import { BN } from '@coral-xyz/anchor';
 
-export type SolanaTransaction = Transaction | VersionedTransaction
+/**
+ * ============================================================
+ *  Common / Wallet Types
+ * ============================================================
+ */
+
+export type SolanaTransaction = Transaction | VersionedTransaction;
 
 export type WalletLike = {
     publicKey: PublicKey;
@@ -9,139 +15,594 @@ export type WalletLike = {
     signAllTransactions?: (txs: Transaction[]) => Promise<Transaction[]>;
 };
 
-export type UserRecord = {
-    userAta: PublicKey;
-    trackedBalance: bigint;       // What we think they have (for reward calculations)
-    claimBalance: bigint;         // Accumulated unclaimed rewards
-    lastClaimTimestamp: bigint;  // When they last claimed (unix timestamp)
-    bump: number;
-}
-
 export type ParsedAccountInfo = {
     extensions: Array<{ extension: string }>;
     isNative: boolean;
     mint: string;
     owner: string;
     state: string;
-    tokenAmount: TokenAmount
+    tokenAmount: TokenAmount;
 };
-export interface MismatchCandidate {
-    owner: PublicKey;
-    actual: bigint;
-    tracked: bigint;
-    delta: bigint; // tracked - actual
-}
-
-export interface CorrectRegisterPlan {
-    deficit: bigint;
-    willFree: bigint;
-    selected: MismatchCandidate[];
-}
-
-export interface CorrectRegisterBuildResult {
-    needToRegister: boolean;
-    canSucceed: boolean;
-    reason?: string;
-    transaction?: Transaction;
-    plan: CorrectRegisterPlan;
-}
 
 /**
- * Wallet interface compatible with AnchorProvider.
- * (Phantom, Solflare, Backpack, etc.)
+ * ============================================================
+ *  Wire Outpost Snapshot
+ * ============================================================
+ *
+ * This is the high-level “view model” the SDK returns after
+ * fetching all relevant on-chain accounts for a given user.
  */
+
 export type OutpostWireStateSnapshot = {
     globalState: GlobalState;
-    distributionState: DistributionState;
 
-    wireReceipt: WireReceipt | null;
+    /**
+     * Per-user Outpost account (old “wire receipt”), or null if user
+     * hasn’t interacted yet.
+     */
+    outpostAccount: OutpostAccount | null;
+
+    /**
+     * Index-based liqSOL distribution state, or null if not initialized.
+     */
+    distributionState: DistributionState | null;
+
+    /**
+     * Global tranche pricing/supply state (`trancheState`).
+     * May be null if not initialized.
+     */
     trancheState: TrancheState | null;
-    userWarrantRecord: UserWarrantRecord | null;
 
-    // balances
-    liqsolPoolBalance: BN;     // token amount in pool ATA
-    solBucketLamports: number; // lamports in sol bucket PDA
-    userLiqsolBalance: BN;     // token amount in user ATA
+    /**
+     * Per-user pretoken purchase record (`userPretokenRecord` in the IDL).
+     * May be null if the user never purchased.
+     */
+    userPretokenRecord: UserPretokenRecord | null;
+
+    // Balances
+    /** liqSOL in the pool ATA (Token-2022 raw amount) */
+    liqsolPoolBalance: BN;
+
+    /** liqSOL in the user’s ATA (Token-2022 raw amount) */
+    userLiqsolBalance: BN;
 };
 
+/**
+ * ============================================================
+ *  Core Enums / Aliases (from IDL variants)
+ * ============================================================
+ */
+
+/**
+ * `wireState` enum from IDL:
+ * - preLaunch: pretokens phase, no refunds
+ * - postLaunch: normal operation
+ * - refund: refund mode active
+ */
+export type WireState = 'preLaunch' | 'postLaunch' | 'refund';
+
+/**
+ * `role` enum from IDL:
+ * Yield operator, batch operator, underwriter, pool operator.
+ */
+export type Role =
+    | 'yieldOperator'
+    | 'batchOperator'
+    | 'underwriter'
+    | 'poolOperator';
+
+/**
+ * Validator reputation from IDL `validatorReputation`.
+ */
+export type ValidatorReputation =
+    | 'trusted'
+    | 'blacklisted'
+    | 'underPerforming';
+
+/**
+ * Validator lifecycle state from IDL `validatorState`.
+ */
+export type ValidatorState =
+    | 'warming'
+    | 'notDelegated'
+    | 'cooling'
+    | 'warm'
+    | 'readyToCool';
+
+/**
+ * ============================================================
+ *  Distribution / Index Types
+ * ============================================================
+ */
+
+/**
+ * IDL: `distributionState`
+ *
+ * Index-based distribution for liqSOL earnings.
+ * Note: this is separate from your local `UserRecord` type above.
+ */
 export type DistributionState = {
+    /** liqSOL mint (Token-2022) */
     liqsolMint: PublicKey;
-    availableBalance: bigint;
-    totalTrackedBalance: bigint;
+
+    /** Current index (scaled) */
+    currentIndex: BN;
+
+    /** Total shares across all distribution users */
+    totalShares: BN;
+
+    /** Last observed bucket balance (for incremental index updates) */
+    lastBucketBalance: BN;
+
+    /** PDA bumps and cached authorities for bucket/pool */
     bump: number;
+    bucketBump: number;
+    poolBump: number;
+    bucketAuthority: PublicKey;
+    poolAuthority: PublicKey;
+};
+
+/**
+ * IDL: `userRecord`
+ *
+ * On-chain distribution user record; tracks shares only.
+ */
+export type DistributionUserRecord = {
+    shares: BN;
+    bump: number;
+};
+
+/**
+ * Simple preview container for “how many pretokens do I get?”
+ * Matches the calculateExpectedPretokens math from capital-staking.
+ */
+export interface SharesPreview {
+    // Input
+    liqsolAmountLamports: BN;
+    solPriceUsd: BN;          // 1e8 scale
+    pretokenPriceUsd: BN;     // 1e8 scale
+    // Output
+    estimatedPretokens: BN;   // 1e8 scale
 }
+/**
+ * ============================================================
+ *  Global / GlobalState (New IDL Layout)
+ * ============================================================
+ */
 
-export type SharesPreview = {
-    amountLamports: BN;
-    currentIndex: BN;
-    indexScale: BN;
-    expectedShares: BN;
+/**
+ * IDL: `global`
+ *
+ * Withdraw operator state:
+ * - NFT withdrawal receipts
+ * - Encumbered funds for pending withdrawals
+ */
+export type Global = {
+    /** PDA bump */
+    bump: number;
+
+    /** Authority that can update serviceable epochs / receipts */
+    authority: PublicKey;
+
+    /** liqSOL mint used/burned when processing withdrawals */
+    liqsolMint: PublicKey;
+
+    /** Highest epoch which can currently be serviced/claimed */
+    serviceableEpoch: BN;
+
+    /** Total SOL encumbered (reserved for open withdrawal receipts) */
+    totalEncumberedFunds: BN;
+
+    /** Monotonic counter for generating unique receipt IDs */
+    nextReceiptId: BN;
 };
 
+/**
+ * IDL: `globalState`
+ *
+ * Wire pretokens + outpost configuration:
+ * - Admin / deployment timing
+ * - Refund delay
+ * - Total staked/purchased liqSOL via outpost
+ * - Global share accounting
+ * - Protocol shares
+ * - Role bonding requirements and warmup
+ * - `wireState` lifecycle (preLaunch/postLaunch/refund)
+ */
 export type GlobalState = {
+    /** Admin authority for pretokens/outpost config */
     admin: PublicKey;
-    dDay: boolean;
-    refundActive: boolean;
+
+    /** Deployment timestamp (Unix, seconds) */
     deployedAt: BN;
+
+    /** Delay before refunds are permitted (seconds) */
     refundDelaySeconds: BN;
+
+    /** Global pause flag (if true, most ops are disabled) */
     paused: boolean;
+
+    /** Total liqSOL staked via outpost (principal) */
     totalStakedLiqsol: BN;
+
+    /** Total liqSOL used to purchase pretokens */
     totalPurchasedLiqsol: BN;
-    totalPurchasedSol: BN;
+
+    /** Total shares issued to all users (staking + purchases) */
     totalShares: BN;
+
+    /** Total shares allocated to protocol */
+    protocolShares: BN;
+
+    /**
+     * Current share-to-liqSOL index
+     * (scaled by a fixed INDEX_SCALE constant from the program).
+     */
     currentIndex: BN;
+
+    /**
+     * Last observed liqSOL pool balance
+     * used for computing incremental yield.
+     */
     lastPoolLiqsolBalance: BN;
-    lastPoolSolBalance: BN;
-    yieldAccumulatedSolEq: BN;
+
+    /**
+     * Accumulated liqSOL yield available to the protocol
+     * (used for `purchaseFromYield`-style flows).
+     */
+    yieldAccumulatedLiqsol: BN;
+
+    /**
+     * Role principals in liqSOL; index by Role:
+     * [YieldOperator, BatchOperator, Underwriter, PoolOperator]
+     */
+    rolePrincipals: BN[];
+
+    /**
+     * Global warmup duration in seconds for newly bonded roles.
+     * Before this time passes, roles are not considered active.
+     */
+    roleWarmupDuration: BN;
+
+    /** Wire lifecycle state (preLaunch / postLaunch / refund) */
+    wireState: WireState;
+
+    /** PDA bump */
     bump: number;
-}
+};
+
+/**
+ * ============================================================
+ *  Outpost / Pretoken Accounts
+ * ============================================================
+ */
+
+/**
+ * IDL: `outpostAccount`
+ *
+ * Per-user Wire Outpost state:
+ * - Staked liqSOL + shares
+ * - Purchased liqSOL + shares
+ * - Role bonding principals and bitmap flags
+ * - Warmup timestamp
+ */
+export type OutpostAccount = {
+    /** User owner of this outpost account */
+    user: PublicKey;
+
+    /** Principal liqSOL staked via outpost */
+    stakedLiqsol: BN;
+
+    /** Shares from staking (index-based accounting) */
+    stakedShares: BN;
+
+    /** Principal liqSOL used for purchases */
+    purchasedLiqsol: BN;
+
+    /** Shares from liqSOL purchases */
+    purchasedShares: BN;
+
+    /**
+     * LiqSOL principals locked by roles:
+     * [YieldOperator, BatchOperator, Underwriter, PoolOperator]
+     */
+    bondedPrincipals: BN[];
+
+    /**
+     * Bitmap of bonded roles (bits 0–3 correspond to Role enum order).
+     */
+    bondedRoles: number;
+
+    /**
+     * Bitmap of roles that have requested unbonding (bits 0–3).
+     */
+    unbondRequested: number;
+
+    /**
+     * Warmup end time; roles are not active until this timestamp.
+     */
+    warmupEndsAt: BN;
+
+    /** PDA bump */
+    bump: number;
+};
+
+/**
+ * Backwards-compat: old name `WireReceipt` used in SDK now maps
+ * directly to the new `OutpostAccount` layout.
+ */
+export type WireReceipt = OutpostAccount;
 
-export type UserWarrantRecord = {
+/**
+ * IDL: `userPretokenRecord`
+ *
+ * Per-user pretoken purchase history:
+ * - Total SOL deposited
+ * - Total pretokens purchased (8-decimal i128)
+ * - Last tranche number & price used
+ */
+export type UserPretokenRecord = {
     user: PublicKey;
+
+    /** Total SOL deposited for pretokens (unscaled u64) */
     totalSolDeposited: BN;
-    totalWarrantsPurchased: BN;
+
+    /** Total pretokens purchased (8-decimal scaled i128) */
+    totalPretokensPurchased: BN;
+
+    /** Last tranche number used for a purchase */
     lastTrancheNumber: BN;
+
+    /** Last tranche price in USD (8-decimal scaled i128) */
     lastTranchePriceUsd: BN;
+
     bump: number;
-}
+};
 
+/**
+ * IDL: `trancheState`
+ *
+ * Global tranche configuration and pricing.
+ * 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;
+
+    /** Remaining supply in the current tranche (8-decimal i128) */
     currentTrancheSupply: BN;
+
+    /** Current tranche price in USD (8-decimal i128) */
     currentTranchePriceUsd: BN;
-    //Currently working on renaming Warrants to Warrants, 
-    // current version of sol contracts appears to still 
-    // be using warrants phrasing for this variable
-    totalWarrantsSold?: BN;
+
+    /** Total pretokens sold across all tranches (8-decimal i128) */
+    totalPretokensSold: BN;
+
+    /** Initial per-tranche supply (8-decimal i128) */
     initialTrancheSupply: BN;
+
+    /** Supply growth in basis points per tranche */
     supplyGrowthBps: number;
+
+    /** Price growth in basis points per tranche */
     priceGrowthBps: number;
+
+    /** Minimum valid SOL/USD price for Chainlink validation (8-decimal i128) */
     minPriceUsd: BN;
+
+    /** Maximum valid SOL/USD price for Chainlink validation (8-decimal i128) */
     maxPriceUsd: BN;
+
+    /** Maximum staleness in seconds for Chainlink price data */
     maxStalenessSeconds: BN;
+
+    /** Chainlink program address */
     chainlinkProgram: PublicKey;
+
+    /** Chainlink SOL/USD feed address */
     chainlinkFeed: PublicKey;
-    bump: number;
-}
 
-export type WireReceipt = {
-    user: PublicKey;
-    stakedLiqsol: BN;
-    stakedShares: BN;
-    purchasedLiqsol: BN;
-    purchasedShares: BN;
-    purchasedWithSol: BN;
-    purchasedSolShares: BN;
+    /** PDA bump */
     bump: number;
-}
+};
+
+/**
+ * ============================================================
+ *  Pay Rate / Price History
+ * ============================================================
+ */
 
+/**
+ * IDL: `payRateEntry`
+ */
+export type PayRateEntry = {
+    /** Unix timestamp for this rate sample */
+    timestamp: BN;
 
+    /** Scaled pay rate (u64; program defines scale) */
+    scaledRate: BN;
+};
+
+/**
+ * IDL: `payRateHistory`
+ *
+ * Circular buffer of recent pay rates.
+ */
+export type PayRateHistory = {
+    /** Current index in the circular buffer */
+    currentIndex: number;
+
+    /** Total entries ever added (monotonic counter) */
+    totalEntriesAdded: BN;
+
+    /** Buffer of entries (fixed-capacity on-chain) */
+    entries: PayRateEntry[];
+
+    /** Maximum entries the buffer can hold */
+    maxEntries: number;
+
+    /** PDA bump */
+    bump: number;
+};
+
+/**
+ * IDL: `priceHistory`
+ *
+ * Circular buffer of recent SOL/USD prices, 8-decimal precision.
+ */
 export type PriceHistory = {
+    /** Window size used for moving average, etc. */
     windowSize: number;
+
+    /** Recent prices (8-decimal scaled i128) */
     prices: BN[];
+
+    /** Number of valid entries in the buffer */
     count: number;
+
+    /** Index to write the next price into */
     nextIndex: number;
+
+    /** PDA bump */
     bump: number;
-}
+};
+
+/**
+ * ============================================================
+ *  Leaderboard Types
+ * ============================================================
+ */
 
+/**
+ * On-chain leaderboard snapshot.
+ *
+ * IDL account: `leaderboardState`
+ *
+ * - `scores[i]` is the numeric score for validator with registry index `i`
+ * - `sortedIndices` is a permutation of [0..N) giving indices from
+ *    highest score to lowest.
+ * - `voteAccounts[i]` is the vote account pubkey corresponding to
+ *    validator registry index `i`.
+ */
+export type LeaderboardState = {
+    /**
+     * Per-validator scores (i64 on-chain).
+     * Index corresponds to `registryIndex` in ValidatorRecord.
+     */
+    scores: BN[];
+
+    /**
+     * Sorted indices into `scores[]` / `voteAccounts[]`,
+     * typically highest score first.
+     */
+    sortedIndices: number[]; // u32 on-chain
+
+    /**
+     * Vote accounts for validators. Parallel array to `scores`.
+     * `voteAccounts[i]` is the vote account for validator with
+     * `registryIndex == i`.
+     */
+    voteAccounts: PublicKey[];
+
+    /**
+     * Number of active validators currently tracked in the leaderboard.
+     * Only the first `numValidators` entries of the arrays are meaningful.
+     */
+    numValidators: number; // u32 on-chain
+
+    /** PDA bump seed for leaderboardState. */
+    bump: number; // u8 on-chain
+
+    /**
+     * Reserved padding / future-proofing on-chain (u64[8]).
+     * Not used by client logic, but surfaced for completeness.
+     */
+    padding: BN[];
+};
+
+/**
+ * Per-validator record tying Solana vote account to
+ * Wire staking / MEV metadata.
+ *
+ * IDL account: `validatorRecord`
+ */
+export type ValidatorRecord = {
+    /**
+     * The validator's Solana vote account.
+     */
+    voteAccount: PublicKey;
+
+    /**
+     * Index into the global validator registry / leaderboard arrays.
+     * This is the index used for `scores[]`, `voteAccounts[]`, etc.
+     */
+    registryIndex: number;
+
+    /**
+     * Last observed vote credits for this validator,
+     * used for rewards / performance accounting.
+     */
+    creditsObserved: BN;
+
+    /**
+     * Historical commission values over time (e.g., per epoch).
+     * Exact semantics depend on on-chain implementation, but this is
+     * typically a ring buffer of u8/u16 basis-point values.
+     */
+    commissionHistory: number[];
+
+    /**
+     * Current index into `commissionHistory` ring buffer.
+     */
+    commissionIndex: number;
+
+    /**
+     * Last time (unix timestamp or slot-aligned time) the base
+     * commission was updated.
+     */
+    lastCommissionUpdate: BN;
+
+    /**
+     * Last epoch for which this record was updated.
+     */
+    epoch: BN;
+
+    /**
+     * Last observed slot for this validator record.
+     */
+    slot: BN;
+
+    /**
+     * Whether this validator is operated by a Wire-approved operator.
+     * Used for preferential routing / UX labeling.
+     */
+    wireOperator: boolean;
+
+    /**
+     * Current MEV commission (e.g., bps or percentage).
+     */
+    mevCommission: number;
+
+    /**
+     * Historical MEV commission values over time.
+     */
+    mevCommissionHistory: number[];
+
+    /**
+     * Current index into `mevCommissionHistory` ring buffer.
+     */
+    mevCommissionIndex: number;
+
+    /**
+     * Last time the MEV commission was updated.
+     */
+    lastMevCommissionUpdate: BN;
+
+    /**
+     * PDA bump seed for validatorRecord.
+     */
+    bump: number;
+};