@wireio/stake 0.3.1 → 0.4.0

package/src/networks/solana/utils.ts

@@ -38,14 +38,12 @@ import {
     DEFAULT_PAY_RATE_LOOKBACK,
     deriveOutpostGlobalStatePda,
     deriveOutpostPoolAuthorityPda,
-    deriveSolBucketPda,
+    deriveOutpostAccountPda,
     deriveTrancheStatePda,
-    deriveWireReceiptPda,
-    derivePoolUserRecordPda,
-    deriveUserUserRecordPda,
-    deriveUserWarrantRecordPda,
+    deriveUserPretokenRecordPda,
     CHAINLINK_FEED,
     CHAINLINK_PROGRAM,
+    deriveExtraAccountMetaListPda,
 } from './constants';
 
 import liqsolCoreIDL from '../../assets/solana/idl/liqsol_core.json';
@@ -54,12 +52,10 @@ import { GlobalState, TrancheState } from './types';
 import { TrancheLadderItem, TrancheSnapshot } from '../../types';
 import { ChainID } from '@wireio/core';
 
-
 // -----------------------------------------------------------------------------
 // Tranche Support
 // -----------------------------------------------------------------------------
 
-
 const INDEX_SCALE = BigInt(1_000_000_000_000); // 1e12
 const USD_SCALE = BigInt(100_000_000);         // 1e8
 const BPS = BigInt(10_000);
@@ -116,7 +112,6 @@ export function buildSolanaTrancheLadder(options: {
     currentTranche: number;
     initialTrancheSupply: bigint;
     currentTrancheSupply: bigint;
-    totalWarrantsSold: bigint; // informational only
     currentPriceUsd: bigint;
     supplyGrowthBps: number;
     priceGrowthBps: number;
@@ -209,35 +204,25 @@ 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 totalWarrantsSold = toBigint(trancheState.totalWarrantsSold);
+    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 ladder = buildSolanaTrancheLadder({
         currentTranche,
         initialTrancheSupply,
         currentTrancheSupply,
-        totalWarrantsSold,
         currentPriceUsd,
         supplyGrowthBps,
         priceGrowthBps,
         windowBefore: ladderWindowBefore,
         windowAfter: ladderWindowAfter,
     });
-    
+
     return {
         chainID,
         currentIndex,
@@ -246,9 +231,9 @@ export function buildSolanaTrancheSnapshot(options: {
         currentPriceUsd,
         supplyGrowthBps,
         priceGrowthBps,
+        totalPretokensSold,
         currentTrancheSupply,
         initialTrancheSupply,
-        totalWarrantsSold,
         nativePriceUsd: solPriceUsd,
         nativePriceTimestamp,
         ladder,
@@ -271,7 +256,11 @@ export function getLiqsolCoreProgram(
 
     // 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 wallet: any = {
+        publicKey: tmpKeypair.publicKey,
+        signAllTransactions: async () => [],
+        signTransaction: async () => tmpKeypair,
+    };
 
     const provider = new AnchorProvider(connection, wallet, {
         commitment: 'confirmed',
@@ -368,16 +357,27 @@ export async function getPayoutStateRaw(
 
 /**
  * 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 pda = deriveUserRecordPda(user);
+    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)
 // -----------------------------------------------------------------------------
@@ -390,12 +390,12 @@ export async function getAveragePayRate(
     const payRateHistoryPda = derivePayRateHistoryPda();
 
     try {
-        const anyProgram = program as any;
+        const anyProgram = program;
         const payRateHistoryAccount = await anyProgram.account.payRateHistory.fetch(
             payRateHistoryPda,
         );
 
-        const entries: any[] = payRateHistoryAccount.entries ?? [];
+        const entries = payRateHistoryAccount.entries ?? [];
         const totalEntriesAdded = Number(
             payRateHistoryAccount.totalEntriesAdded ?? 0,
         );
@@ -448,6 +448,7 @@ export async function getAveragePayRate(
         return DEFAULT_AVERAGE_PAY_RATE;
     }
 }
+
 /**
  * On-chain fee formula:
  *   fee = (average_pay_rate * 4 * deposit_amount_lamports) / 10^12
@@ -502,30 +503,39 @@ export function previewDepositEffects(params: {
  * ---------------------------------------------------------------------------
  * 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;
 }
 
 export async function buildOutpostAccounts(
@@ -536,15 +546,14 @@ export async function buildOutpostAccounts(
     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);
 
+    // Outpost / pretoken PDAs
+    const outpostAccount = deriveOutpostAccountPda(user);
+    const userPretokenRecord = deriveUserPretokenRecordPda(user);
+
+    // ATAs
     const liqsolPoolAta = await getAssociatedTokenAddress(
         liqsolMint,
         poolAuthority,
@@ -566,21 +575,31 @@ export async function buildOutpostAccounts(
         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 extraAccountMetaList = deriveExtraAccountMetaListPda(liqsolMint);
+
     // 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 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 +611,20 @@ 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
     };
 }
-
 // -----------------------------------------------------------------------------
 // Epoch / scheduling helpers
 // -----------------------------------------------------------------------------
@@ -780,5 +798,4 @@ export async function waitUntilSafeToExecuteFunction(
 export interface ScheduleConfig {
     early?: number; // fraction of epoch, default 0.10
     late?: number;  // fraction of epoch, default 0.90
-}
-
+}

package/src/types.ts

@@ -37,30 +37,120 @@ export interface IStakingClient {
     }): Promise<TrancheSnapshot | null>;
 }
 
+/**
+ * Cross-chain portfolio view for a single account/wallet.
+ *
+ * On Solana (liqSOL + Outpost + pretokens) we fill:
+ *  - native: SOL wallet lamports
+ *  - liq:    liqSOL in user ATA
+ *  - staked: liqSOL staked into Outpost (stakedLiqsol)
+ *  - wire:   WIRE pretokens purchased (1e8 scale)
+ *  - yield:  Outpost yield view (index/shares + implied claim/yield)
+ *
+ * On other chains:
+ *  - native/liq/wire/staked can still be populated as appropriate
+ *  - yield may be undefined if no index/shares concept exists.
+ */
 export interface Portfolio {
-    /** Native balance on chain: ETH, SOL */
+    /** Native balance on chain: ETH, SOL, etc. */
     native: BalanceView;
-    /** Actual Liquid  balance of LiqETH, LiqSOL*/
+
+    /** Liquid staking token balance (LiqETH, LiqSOL, etc.). */
     liq: BalanceView;
-    /** Outpost Staked balance */
-    staked: BalanceView
-    /** Prelaunch WIRE “shares” (pretokens) */
+
+    /**
+     * Outpost-staked balance:
+     *  - On Solana: liqSOL staked via `synd` (stakedLiqsol, in lamports).
+     *  - On other chains: protocol-specific staked principal, if any.
+     */
+    staked: BalanceView;
+
+    /**
+     * Prelaunch WIRE “shares” (pretokens).
+     *  - On Solana: totalPretokensPurchased (1e8 scale).
+     *  - On other chains: analogous pretoken balance if supported.
+     */
     wire: BalanceView;
-    /** SOL ONLY!
-     * Tracked liqSOL balance from distribution program */
-    tracked?: BalanceView;
-    /** Extra PDAs and account addresses */
+
+    /**
+     * Yield / index-based view (SOL + Outpost only for now).
+     *
+     * If the connected chain doesn’t expose an index+shares model,
+     * this will be undefined.
+     */
+    yield?: YieldView;
+
+    /**
+     * Extra PDAs, account addresses, and raw state useful for debugging
+     * and advanced UI (e.g. tranche price, global index, PDAs).
+     */
     extras?: Record<string, any>;
-    /** Chain ID of the network for which this portfolio is from */
+
+    /** Chain ID of the network from which this portfolio was fetched. */
     chainID: ChainID;
 }
 
-export type BalanceView = {
-    amount: bigint; // raw on-chain integer value
-    decimals: number; // number of decimal places
-    symbol: string; // optional token symbol identifier
-    ata?: SolPubKey; // associated token account address
-};
+/**
+ * Canonical view of a single balance on a given chain.
+ *
+ * amount   – integer base units (wei, lamports, token base units)
+ * symbol   – display symbol (“SOL”, “LiqSOL”, “$WIRE”, etc.)
+ * decimals – how many decimal places to use when formatting
+ * ata      – optional SPL ATA / ERC-20 address (where applicable)
+ */
+export interface BalanceView {
+    amount: bigint;
+    symbol: string;
+    decimals: number;
+    ata?: SolPubKey;
+}
+
+/**
+ * SOL / Outpost yield view.
+ *
+ * All amounts are integers in base units (lamports for liqSOL).
+ *
+ * Math matches capital-staking:
+ *   INDEX_SCALE      = 1e12
+ *   sharesToTokens = shares * currentIndex / INDEX_SCALE
+ */
+export interface YieldView {
+    /**
+     * Current global index for the Outpost pool.
+     *  - 1e12 scale (INDEX_SCALE)
+     *  - sharesToTokens(shares) = shares * currentIndex / indexScale
+     */
+    currentIndex: bigint;
+
+    /**
+     * Fixed scale factor used for index math.
+     *  - Always 1_000_000_000_000n (1e12) on Solana Outpost.
+     */
+    indexScale: bigint;
+
+    /** Total shares outstanding in the Outpost pool (all users). */
+    totalShares: bigint;
+
+    /** User’s staked shares in the Outpost pool. */
+    userShares: bigint;
+
+    /**
+     * Total liqSOL (lamports) the user could claim right now if they fully
+     * unwound their stake:
+     *   estimatedClaimLiqsol = userShares * currentIndex / indexScale
+     */
+    estimatedClaimLiqsol: bigint;
+
+    /**
+     * Portion of estimatedClaimLiqsol that is “yield” above principal:
+     *   estimatedYieldLiqsol = max(0, estimatedClaimLiqsol - stakedLiqsol)
+     *
+     * NOTE: stakedLiqsol principal itself is surfaced separately as
+     *       Portfolio.staked.amount.
+     */
+    estimatedYieldLiqsol: bigint;
+}
+
 export interface TrancheLadderItem {
     /** On-chain tranche id, 0-based (0,1,2,...) */
     id: number;
@@ -110,10 +200,11 @@ export interface TrancheSnapshot {
     supplyGrowthBps: number; // e.g. 100 = +1% per tranche
     priceGrowthBps: number;  // e.g. 200 = +2% per tranche
 
+    totalPretokensSold: bigint;  // total pretokens sold across all tranches (1e8 scale)
+
     /** Current tranche supply state (1e8 scale) */
     currentTrancheSupply: bigint;   // remaining in current tranche
     initialTrancheSupply: bigint;   // capacity for current tranche
-    totalWarrantsSold: bigint;      // global cumulative sold (all tranches), 1e8
 
     /** Native token → USD price if available (SOL/USD, ETH/USD, etc, 1e8 scale) */
     nativePriceUsd?: bigint;