@wireio/stake 0.2.3 → 0.2.4

package/lib/stake.d.ts

@@ -31,7 +31,11 @@ interface IStakingClient {
      *  - `TrancheSnapshot` when the chain supports pretoken/tranches
      *  - `null` if this chain has no WIRE/pretoken integration
      */
-    getTrancheSnapshot(): Promise<TrancheSnapshot | null>;
+    getTrancheSnapshot(options?: {
+        chainID?: ChainID;
+        windowBefore?: number;
+        windowAfter?: number;
+    }): Promise<TrancheSnapshot | null>;
     /**  */
     getBuyQuote(amount: bigint, asset: PurchaseAsset): Promise<PurchaseQuote>;
 }
@@ -58,23 +62,53 @@ type BalanceView = {
     symbol: string;
     ata?: PublicKey$1;
 };
+interface TrancheLadderItem {
+    /** On-chain tranche id, 0-based (0,1,2,...) */
+    id: number;
+    /** Total capacity for this tranche (pretokens, 1e8 scale) */
+    capacity: bigint;
+    /** Sold amount in this tranche (1e8 scale) */
+    sold: bigint;
+    /** Remaining = capacity - sold (1e8 scale) */
+    remaining: bigint;
+    /** Price for this tranche in USD (1e8 scale) */
+    priceUsd: bigint;
+}
 /**
- * Program-global prelaunch WIRE / tranche state for a single chain.
- *
- * All integer values are raw on-chain integers:
- *  - `currentTranchePriceUsd`: 1e8 USD
- *  - supplies / warrants / shares: 1e8 WIRE units (per liqsol_core/ETH analog)
- *  - index: same scale the program uses (INDEX_SCALE = 1e12 on Solana today)
+ * Unified pretoken/tranche snapshot for any chain.
+ * ETH / other chains just fill the same shape from their own contracts.
  */
 interface TrancheSnapshot {
     chainID: ChainID;
-    totalShares: bigint;
+    /** Global share index (1e12 on Sol today; other chains can use their own scale) */
     currentIndex: bigint;
-    currentTrancheNumber: bigint;
+    /** Total accounting shares (wire pretoken “shares”) */
+    totalShares: bigint;
+    /** Current tranche id as stored on chain (0-based) */
+    currentTranche: number;
+    /** Current tranche price in USD (1e8 scale) */
+    currentPriceUsd: bigint;
+    /** Optional min/max bounds for price validation (1e8 scale) */
+    minPriceUsd?: bigint;
+    maxPriceUsd?: bigint;
+    /** Tranche curve config (per-chain) */
+    supplyGrowthBps: number;
+    priceGrowthBps: number;
+    /** Current tranche supply state (1e8 scale) */
     currentTrancheSupply: bigint;
+    initialTrancheSupply: bigint;
     totalWarrantsSold: bigint;
-    currentTranchePriceUsd: bigint;
+    /** Native token → USD price if available (SOL/USD, ETH/USD, etc, 1e8 scale) */
+    nativePriceUsd?: bigint;
+    /** Optional timestamp (sec) for the last recorded native price */
+    nativePriceTimestamp?: number;
+    /**
+     * Local window of tranche “rows” centered around current.
+     * Used directly by the frontend for ladder graphs.
+     */
+    ladder: TrancheLadderItem[];
 }
+/** Purchase asset selection used by staking client(s) */
 declare enum PurchaseAsset {
     SOL = "SOL",
     LIQSOL = "LIQSOL",
@@ -85,8 +119,10 @@ declare enum PurchaseAsset {
 interface PurchaseQuote {
     purchaseAsset: PurchaseAsset;
     amountIn: bigint;
+    /** Expected pretoken “shares” (pretokens) and decimals */
     wireShares: bigint;
     wireDecimals: number;
+    /** Current price + notional in USD (1e8 scale) */
     wirePriceUsd: bigint;
     notionalUsd: bigint;
 }
@@ -581,6 +617,17 @@ declare namespace types {
   export type { types_CorrectRegisterBuildResult as CorrectRegisterBuildResult, types_CorrectRegisterPlan as CorrectRegisterPlan, types_DistributionState as DistributionState, types_GlobalState as GlobalState, types_MismatchCandidate as MismatchCandidate, types_OutpostWireStateSnapshot as OutpostWireStateSnapshot, types_ParsedAccountInfo as ParsedAccountInfo, types_PriceHistory as PriceHistory, types_SharesPreview as SharesPreview, types_SolanaTransaction as SolanaTransaction, types_TrancheState as TrancheState, types_UserRecord as UserRecord, types_UserWarrantRecord as UserWarrantRecord, types_WalletLike as WalletLike, types_WireReceipt as WireReceipt };
 }
 
+/**
+ * Solana implementation of IStakingClient.
+ *
+ * Responsibilities:
+ *  - Wire together liqSOL deposit/withdraw
+ *  - Outpost stake/unstake
+ *  - Prelaunch WIRE (pretokens) buy flows
+ *  - Unified portfolio + tranche snapshot + buy quotes
+ *
+ * This class composes lower-level clients; it does not know about UI.
+ */
 declare class SolanaStakingClient implements IStakingClient {
     private config;
     pubKey: PublicKey;
@@ -595,77 +642,110 @@ declare class SolanaStakingClient implements IStakingClient {
     get network(): ExternalNetwork;
     constructor(config: StakerConfig);
     /**
-     * Deposit SOL into liqSOL protocol (liqsol_core deposit flow).
-     * @param amountLamports Amount of SOL to deposit (smallest unit)
-     * @return Transaction signature
+     * Deposit native SOL into liqSOL (liqsol_core::deposit).
+     * Handles tx build, sign, send, and confirmation.
      */
     deposit(amountLamports: bigint): Promise<string>;
     /**
      * Withdraw SOL from liqSOL protocol.
-     * (Wire up once you have DepositClient.buildWithdrawTx or equivalent.)
+     * NOTE: placeholder until a withdraw flow is implemented in DepositClient.
      */
-    withdraw(amountLamports: bigint): Promise<string>;
+    withdraw(_amountLamports: bigint): Promise<string>;
     /**
      * Stake liqSOL into Outpost (liqSOL -> pool).
-     * Matches deposit flow: build -> prepare -> sign -> send/confirm.
-     * @param amountLamports Amount of liqSOL to stake (smallest unit)
+     * Ensures user ATA exists, then stakes via outpostClient.
      */
     stake(amountLamports: bigint): Promise<string>;
     /**
      * Unstake liqSOL from Outpost (pool -> liqSOL).
-     * Matches deposit flow: build -> prepare -> sign -> send/confirm.
-     * @param amountLamports Amount of liqSOL principal to unstake (smallest unit)
+     * Mirrors stake() but calls withdrawStake.
      */
     unstake(amountLamports: bigint): Promise<string>;
-    /** Buy pretoken (warrants) using specified asset.
-     * @param amount Amount in smallest units (lamports / wei / token units).
-     *               Required for SOL / LIQSOL / ETH / LIQETH.
-     *               Ignored for YIELD (the program uses tracked yield).
-     * @param purchaseAsset Asset used to buy pretoken.
-     * @returns Transaction signature
+    /**
+     * Buy prelaunch WIRE “pretokens” using a supported asset.
+     *
+     * - SOL: uses purchase_with_sol
+     * - LIQSOL: uses purchase_with_liqsol
+     * - YIELD: uses purchase_warrants_from_yield
+     *
+     * ETH / LIQETH are not valid on Solana.
      */
     buy(amountLamports: bigint, purchaseAsset: PurchaseAsset): Promise<string>;
     /**
-     * native = SOL in wallet
-     * liq    = liqSOL token balance (from Token-2022 ATA)
-     * staked = Outpost staked liqSOL principal (from wireReceipt.stakedLiqsol)
-     * tracked = liqSOL tracked balance (from Distribution.userRecord)
-     * wire   = prelaunch WIRE “shares” (UserWarrantRecord.totalWarrantsPurchased, 1e8)
+     * Aggregate view of the user’s balances on Solana:
+     *  - native: SOL wallet balance
+     *  - liq: liqSOL token balance (Token-2022 ATA)
+     *  - staked: Outpost-staked liqSOL principal
+     *  - tracked: distribution program trackedBalance (liqSOL)
+     *  - wire: total prelaunch WIRE shares (warrants/pretokens, 1e8)
+     *  - extras: useful internal addresses and raw state for debugging/UX
      */
     getPortfolio(): Promise<Portfolio>;
     /**
-     * Program-level prelaunch WIRE / tranche snapshot for Solana.
-     * Uses the same OutpostWireStateSnapshot primitive as getPortfolio().
+     * Unified, chain-agnostic tranche snapshot for Solana.
+     *
+     * Uses:
+     *  - liqsol_core.globalState (currentIndex, totalShares, etc.)
+     *  - liqsol_core.trancheState (price, supply, total sold, etc.)
+     *  - Chainlink/PriceHistory for SOL/USD (via TokenClient.getSolPriceUsdSafe)
+     *
+     * windowBefore/windowAfter control how many ladder rows we precompute
+     * around the current tranche for UI, but you can pass nothing if you
+     * only need current tranche info.
      */
-    getTrancheSnapshot(): Promise<TrancheSnapshot | null>;
-    getBuyQuote(amount: bigint, purchaseAsset: PurchaseAsset): Promise<PurchaseQuote>;
+    getTrancheSnapshot(options?: {
+        chainID?: ChainID;
+        windowBefore?: number;
+        windowAfter?: number;
+    }): Promise<TrancheSnapshot>;
     /**
-     * Exact warrant math reused from your old utils, just phrased in terms
-     * of already-computed USD notional:
+     * Approximate prelaunch WIRE quote for a given amount & asset.
      *
-     *   expectedWarrants = (notionalUsd * 1e8) / wirePriceUsd
+     * Uses TrancheSnapshot + SOL/USD price for:
+     *  - SOL: amount is lamports
+     *  - LIQSOL: amount is liqSOL base units (decimals = 9)
+     *  - YIELD: amount is treated as SOL lamports-equivalent of yield
      *
-     * where:
-     *   - notionalUsd, wirePriceUsd are 1e8-scaled USD
-     *   - result is 1e8-scaled WIRE "shares"
+     * NOTE: On-chain rounding may differ slightly (this is UI-only).
+     */
+    getBuyQuote(amount: bigint, asset: PurchaseAsset, opts?: {
+        chainID?: ChainID;
+    }): Promise<PurchaseQuote>;
+    /**
+     * Convenience helper to fetch the distribution userRecord for the current user.
+     * Used by balance-correction flows and debugging.
      */
-    private calculateExpectedWarrants;
     getUserRecord(): Promise<UserRecord | null>;
+    /**
+     * Run the "correct & register" flow on Solana:
+     *  - builds the minimal transaction (maybe multi-user) to reconcile liqSOL
+     *  - signs and sends the transaction if it can succeed
+     */
     correctBalance(amount?: bigint): Promise<string>;
+    /**
+     * Send a signed transaction over HTTP RPC and wait for confirmation.
+     * Throws if the transaction fails.
+     */
     private sendAndConfirmHttp;
+    /**
+     * Sign a single Solana transaction using the connected wallet adapter.
+     */
     signTransaction(tx: SolanaTransaction): Promise<SolanaTransaction>;
+    /**
+     * Generic "fire and forget" send helper if the caller already
+     * prepared and signed the transaction.
+     */
     sendTransaction(signed: SolanaTransaction): Promise<TransactionSignature>;
+    /**
+     * Attach recent blockhash + fee payer to a transaction.
+     * Required before signing and sending.
+     */
     prepareTx(tx: Transaction): Promise<{
         tx: Transaction;
         blockhash: string;
         lastValidBlockHeight: number;
     }>;
 }
-interface TxResult {
-    signature: string;
-    slot: number;
-    confirmed: boolean;
-}
 
 /**
  * ---------------------------------------------------------------------------
@@ -5209,6 +5289,47 @@ type LiqsolCore = {
     ];
 };
 
+/** BN | bigint -> bigint helper (keeps code readable) */
+declare function toBigint(x: any): bigint;
+/**
+ * Convert token amount -> shares using the same rule as on-chain tests:
+ * shares = ceil(amount * INDEX_SCALE / currentIndex)
+ */
+declare function tokensToShares(amount: bigint, currentIndex: bigint): bigint;
+/**
+ * Build a local tranche ladder around the current tranche
+ * using only on-chain config + current state.
+ *
+ * Rules (from liqsol_core tests):
+ *  - past tranches are fully sold
+ *  - current tranche has (initial - currentSupply) sold
+ *  - future tranches start with 0 sold
+ *  - supply/price grow by supplyGrowthBps/priceGrowthBps per tranche
+ */
+declare function buildSolanaTrancheLadder(options: {
+    currentTranche: number;
+    initialTrancheSupply: bigint;
+    currentTrancheSupply: bigint;
+    totalWarrantsSold: bigint;
+    currentPriceUsd: bigint;
+    supplyGrowthBps: number;
+    priceGrowthBps: number;
+    windowBefore?: number;
+    windowAfter?: number;
+}): TrancheLadderItem[];
+/**
+ * Turn raw liqsol_core accounts into a chain-agnostic TrancheSnapshot for SOL.
+ * All math stays here; TokenClient just wires accounts + connection.
+ */
+declare function buildSolanaTrancheSnapshot(options: {
+    chainID: ChainID;
+    globalState: GlobalState;
+    trancheState: TrancheState;
+    solPriceUsd?: bigint;
+    nativePriceTimestamp?: number;
+    ladderWindowBefore?: number;
+    ladderWindowAfter?: number;
+}): TrancheSnapshot;
 declare function getLiqsolCoreProgram(connection: Connection): Program<LiqsolCore>;
 declare function getUserLiqSolBalance(connection: Connection, user: PublicKey$1): Promise<number>;
 declare function getBucketLiqSolBalance(connection: Connection): Promise<number>;
@@ -5532,58 +5653,29 @@ declare class OutpostClient {
     private getTokenBalanceSafe;
 }
 
-/**
- * Client for interacting with the Pretoken (Outpost) program on Solana.
- *
- * Provides account fetching and instruction building for pretoken operations.
- * Does NOT send or confirm transactions; keeps SDK composable.
- *
- * TODO: Update to $WIRE Token implementation Post-Launch
- */
 declare class TokenClient {
     private readonly provider;
     private readonly program;
     get wallet(): WalletLike;
     constructor(provider: AnchorProvider);
-    /**
-     * Single source of truth for outpost/pretoken accounts.
-     * Uses your existing PDA + ATA derivations in buildOutpostAccounts().
-     */
     getAccounts(user: PublicKey$1): Promise<OutpostAccounts>;
-    /**
-     * Lightweight, UI-friendly snapshot fetchers.
-     * (No decoding assumptions beyond what Anchor already provides.)
-     */
     fetchGlobalState(): Promise<GlobalState>;
     fetchTrancheState(): Promise<TrancheState>;
     fetchWireReceipt(user: PublicKey$1): Promise<WireReceipt>;
     fetchUserWarrantRecord(user: PublicKey$1): Promise<UserWarrantRecord>;
-    /**
-     * purchase_with_sol(amount u64)
-     *
-     * amountLamports is bigint to match your SDK convention.
-     */
     buildPurchaseWithSolIx(amountLamports: bigint, user?: PublicKey$1): Promise<TransactionInstruction>;
-    /**
-     * purchase_with_liqsol(amount u64)
-     *
-     * amount is liqSOL *raw base units* (Token-2022 amount).
-     */
     buildPurchaseWithLiqsolIx(amountLamports: bigint, user?: PublicKey$1): Promise<TransactionInstruction>;
-    /**
-     * purchase_warrants_from_yield()
-     *
-     * No amount arg; it consumes tracked yield according to on-chain rules.
-     */
     buildPurchaseFromYieldIx(user?: PublicKey$1): Promise<TransactionInstruction>;
+    getSolPriceUsdSafe(): Promise<{
+        price?: bigint;
+        timestamp?: number;
+    }>;
     /**
-     * Fetch the SOL price in 1e8 USD units from liqsol_core.priceHistory.
-     *
-     * This uses the same ring-buffer semantics as the on-chain program:
-     * the latest price is the entry just before `nextIndex`.
+     * Fetch latest SOL/USD price (1e8 scale) from liqsol_core.priceHistory.
+     * Uses the ring-buffer semantics from earlier SDK code.
      */
-    getSolPriceUsd(): Promise<BN>;
+    getSolPriceUsd(): Promise<bigint>;
 }
 
-export { ADDRESSES, CHAINLINK_FEED, CHAINLINK_PROGRAM, CONTRACTS, DEFAULT_AVERAGE_PAY_RATE, DEFAULT_PAY_RATE_LOOKBACK, DepositClient, DistributionClient, EPHEMERAL_RENT_EXEMPTION, ERC1155Abi, ERC20Abi, ERC721Abi, types$1 as ETH, EthereumContractService, EthereumStakingClient, LAMPORTS_PER_SOL, LIQSOL_CORE, LIQSOL_TOKEN, LeaderboardClient, OutpostClient, PAY_RATE_SCALE_FACTOR, PDA_SEEDS, PROGRAM_IDS, PurchaseAsset, types as SOL, SolanaStakingClient, Staker, TokenClient, VALIDATOR_LEADERBOARD, airdropSol, buildOutpostAccounts, calculateExpectedFee, deriveBarConfigPda, deriveBondLevelPda, deriveBondedActorPda, deriveBucketAuthorityPda, deriveDepositAuthorityPda, deriveDistributionStatePda, deriveEphemeralStakeAddress, deriveLeaderboardStatePda, deriveLiqsolMintAuthorityPda, deriveLiqsolMintPda, deriveOutpostGlobalStatePda, deriveOutpostPoolAuthorityPda, derivePayRateHistoryPda, derivePayoutStatePda, derivePoolUserRecordPda, derivePriceHistoryPda, deriveReservePoolPda, deriveSolBucketPda, deriveStakeControllerStatePda, deriveStakeControllerVaultPda, deriveTrancheStatePda, deriveUserRecordPda, deriveUserUserRecordPda, deriveUserWarrantRecordPda, deriveValidatorRecordPda, deriveVaultPda, deriveWireReceiptPda, generateRandomDepositAmount, generateTestKeypair, getAveragePayRate, getBucketLiqSolBalance, getEpochSnapshot, getErrorMessage, getLiqsolCoreProgram, getPayoutStateRaw, getReservePoolBalance, getStakeControllerStateRaw, getUserLiqSolBalance, getUserRecordRaw, lamportsToSol, msToEpochEnd, previewDepositEffects, scheduledInstruction, sleep, solToLamports, waitForConfirmation, waitUntilSafeToExecuteFunction };
-export type { BalanceView, ContractConfig, ContractOptions, Contracts, EpochSnapshot, IStakingClient, OutpostAccounts, Portfolio, PurchaseQuote, ScheduleConfig, StakerConfig, TrancheSnapshot, TxResult };
+export { ADDRESSES, CHAINLINK_FEED, CHAINLINK_PROGRAM, CONTRACTS, DEFAULT_AVERAGE_PAY_RATE, DEFAULT_PAY_RATE_LOOKBACK, DepositClient, DistributionClient, EPHEMERAL_RENT_EXEMPTION, ERC1155Abi, ERC20Abi, ERC721Abi, types$1 as ETH, EthereumContractService, EthereumStakingClient, LAMPORTS_PER_SOL, LIQSOL_CORE, LIQSOL_TOKEN, LeaderboardClient, OutpostClient, PAY_RATE_SCALE_FACTOR, PDA_SEEDS, PROGRAM_IDS, PurchaseAsset, types as SOL, SolanaStakingClient, Staker, TokenClient, VALIDATOR_LEADERBOARD, airdropSol, buildOutpostAccounts, buildSolanaTrancheLadder, buildSolanaTrancheSnapshot, calculateExpectedFee, deriveBarConfigPda, deriveBondLevelPda, deriveBondedActorPda, deriveBucketAuthorityPda, deriveDepositAuthorityPda, deriveDistributionStatePda, deriveEphemeralStakeAddress, deriveLeaderboardStatePda, deriveLiqsolMintAuthorityPda, deriveLiqsolMintPda, deriveOutpostGlobalStatePda, deriveOutpostPoolAuthorityPda, derivePayRateHistoryPda, derivePayoutStatePda, derivePoolUserRecordPda, derivePriceHistoryPda, deriveReservePoolPda, deriveSolBucketPda, deriveStakeControllerStatePda, deriveStakeControllerVaultPda, deriveTrancheStatePda, deriveUserRecordPda, deriveUserUserRecordPda, deriveUserWarrantRecordPda, deriveValidatorRecordPda, deriveVaultPda, deriveWireReceiptPda, generateRandomDepositAmount, generateTestKeypair, getAveragePayRate, getBucketLiqSolBalance, getEpochSnapshot, getErrorMessage, getLiqsolCoreProgram, getPayoutStateRaw, getReservePoolBalance, getStakeControllerStateRaw, getUserLiqSolBalance, getUserRecordRaw, lamportsToSol, msToEpochEnd, previewDepositEffects, scheduledInstruction, sleep, solToLamports, toBigint, tokensToShares, waitForConfirmation, waitUntilSafeToExecuteFunction };
+export type { BalanceView, ContractConfig, ContractOptions, Contracts, EpochSnapshot, IStakingClient, OutpostAccounts, Portfolio, PurchaseQuote, ScheduleConfig, StakerConfig, TrancheLadderItem, TrancheSnapshot };