@wireio/stake 0.2.3 → 0.2.5

package/src/networks/solana/solana.ts

@@ -2,32 +2,65 @@ import {
     Commitment,
     Connection,
     ConnectionConfig,
+    LAMPORTS_PER_SOL,
     PublicKey as SolPubKey,
     Transaction,
     TransactionInstruction,
     TransactionSignature,
 } from '@solana/web3.js';
-import { AnchorProvider, BN } from '@coral-xyz/anchor';
+import { AnchorProvider } from '@coral-xyz/anchor';
 import { BaseSignerWalletAdapter } from '@solana/wallet-adapter-base';
-import { ASSOCIATED_TOKEN_PROGRAM_ID, getAssociatedTokenAddressSync, TOKEN_2022_PROGRAM_ID } from '@solana/spl-token';
+import {
+    ASSOCIATED_TOKEN_PROGRAM_ID,
+    getAssociatedTokenAddressSync,
+    TOKEN_2022_PROGRAM_ID,
+} from '@solana/spl-token';
 
-import { ChainID, ExternalNetwork, KeyType, PublicKey } from '@wireio/core';
-import { IStakingClient, Portfolio, PurchaseAsset, PurchaseQuote, StakerConfig, TrancheSnapshot } from '../../types';
+import {
+    ChainID,
+    ExternalNetwork,
+    KeyType,
+    PublicKey,
+    SolChainID,
+} from '@wireio/core';
+
+import {
+    IStakingClient,
+    Portfolio,
+    PurchaseAsset,
+    PurchaseQuote,
+    StakerConfig,
+    TrancheSnapshot,
+} from '../../types';
 
 import { DepositClient } from './clients/deposit.client';
 import { DistributionClient } from './clients/distribution.client';
+import { LeaderboardClient } from './clients/leaderboard.client';
+import { OutpostClient } from './clients/outpost.client';
+import { TokenClient } from './clients/token.client';
+
 import {
     deriveLiqsolMintPda,
     deriveReservePoolPda,
     deriveVaultPda,
 } from './constants';
+
+import { buildSolanaTrancheSnapshot } from './utils';
 import { SolanaTransaction } from './types';
-import { LeaderboardClient } from './clients/leaderboard.client';
-import { OutpostClient } from './clients/outpost.client';
-import { TokenClient } from './clients/token.client';
 
 const commitment: Commitment = 'confirmed';
 
+/**
+ * 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.
+ */
 export class SolanaStakingClient implements IStakingClient {
     public pubKey: PublicKey;
     public connection: Connection;
@@ -39,8 +72,13 @@ export class SolanaStakingClient implements IStakingClient {
     private outpostClient: OutpostClient;
     private tokenClient: TokenClient;
 
-    get solPubKey(): SolPubKey { return new SolPubKey(this.pubKey.data.array); }
-    get network() { return this.config.network; }
+    get solPubKey(): SolPubKey {
+        return new SolPubKey(this.pubKey.data.array);
+    }
+
+    get network(): ExternalNetwork {
+        return this.config.network;
+    }
 
     constructor(private config: StakerConfig) {
         const adapter = config.provider as BaseSignerWalletAdapter;
@@ -54,7 +92,10 @@ export class SolanaStakingClient implements IStakingClient {
         }
 
         const opts: ConnectionConfig = { commitment };
-        if (config.network.rpcUrls.length > 1 && config.network.rpcUrls[1].startsWith('ws')) {
+        if (
+            config.network.rpcUrls.length > 1 &&
+            config.network.rpcUrls[1].startsWith('ws')
+        ) {
             opts.wsEndpoint = config.network.rpcUrls[1];
         }
 
@@ -63,7 +104,9 @@ export class SolanaStakingClient implements IStakingClient {
             async signTransaction<T extends SolanaTransaction>(tx: T): Promise<T> {
                 return adapter.signTransaction(tx);
             },
-            async signAllTransactions<T extends SolanaTransaction>(txs: T[]): Promise<T[]> {
+            async signAllTransactions<T extends SolanaTransaction>(
+                txs: T[],
+            ): Promise<T[]> {
                 return Promise.all(txs.map((tx) => adapter.signTransaction(tx)));
             },
         };
@@ -77,77 +120,89 @@ export class SolanaStakingClient implements IStakingClient {
         this.leaderboardClient = new LeaderboardClient(this.anchor);
         this.outpostClient = new OutpostClient(this.anchor);
         this.tokenClient = new TokenClient(this.anchor);
+        this.tokenClient = new TokenClient(this.anchor);
     }
 
     // ---------------------------------------------------------------------
-    // Public IStakingClient Interface Methods
+    // IStakingClient core methods
     // ---------------------------------------------------------------------
 
     /**
-     * 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.
      */
     async deposit(amountLamports: bigint): Promise<string> {
-        if (amountLamports <= BigInt(0)) throw new Error('Deposit amount must be greater than zero.');
-        // const amount = new BN(amountLamports.toString());
+        if (amountLamports <= BigInt(0)) {
+            throw new Error('Deposit amount must be greater than zero.');
+        }
+
         const tx = await this.depositClient.buildDepositTx(amountLamports);
-        const { tx: prepared, blockhash, lastValidBlockHeight } = await this.prepareTx(tx);
+        const { tx: prepared, blockhash, lastValidBlockHeight } = await this.prepareTx(
+            tx,
+        );
         const signed = await this.signTransaction(prepared);
-        const result = await this.sendAndConfirmHttp(signed, { blockhash, lastValidBlockHeight });
-        return result.signature;
+        return await this.sendAndConfirmHttp(signed, {
+            blockhash,
+            lastValidBlockHeight,
+        });
     }
 
     /**
      * Withdraw SOL from liqSOL protocol.
-     * (Wire up once you have DepositClient.buildWithdrawTx or equivalent.)
+     * NOTE: placeholder until a withdraw flow is implemented in DepositClient.
      */
-    async withdraw(amountLamports: bigint): Promise<string> {
+    async withdraw(_amountLamports: bigint): Promise<string> {
         throw new Error('Withdraw method not yet implemented.');
     }
 
     /**
      * 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.
      */
     async stake(amountLamports: bigint): Promise<string> {
-        if (amountLamports <= BigInt(0)) throw new Error('Stake amount must be greater than zero.');
-        // const amount = new BN(amountLamports.toString());
-        const preIxs = await this.outpostClient.maybeBuildCreateUserAtaIx(this.solPubKey);
+        if (amountLamports <= BigInt(0)) {
+            throw new Error('Stake amount must be greater than zero.');
+        }
+
+        const preIxs = await this.outpostClient.maybeBuildCreateUserAtaIx(
+            this.solPubKey,
+        );
         const stakeIx = await this.outpostClient.buildStakeLiqsolIx(amountLamports);
         const tx = new Transaction().add(...preIxs, stakeIx);
+
         const prepared = await this.prepareTx(tx);
         const signed = await this.signTransaction(prepared.tx);
-        const result = await this.sendAndConfirmHttp(signed, prepared);
-        return result.signature;
+        return await this.sendAndConfirmHttp(signed, prepared);
     }
 
     /**
      * 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.
      */
     async unstake(amountLamports: bigint): Promise<string> {
-        if (amountLamports <= BigInt(0)) throw new Error('Unstake amount must be greater than zero.');
+        if (amountLamports <= BigInt(0)) {
+            throw new Error('Unstake amount must be greater than zero.');
+        }
+
         const user = this.solPubKey;
-        // const amount = new BN(amountLamports.toString());
         const preIxs = await this.outpostClient.maybeBuildCreateUserAtaIx(user);
-        const withdrawIx = await this.outpostClient.buildWithdrawStakeIx(amountLamports);
+        const withdrawIx =
+            await this.outpostClient.buildWithdrawStakeIx(amountLamports);
         const tx = new Transaction().add(...preIxs, withdrawIx);
+
         const prepared = await this.prepareTx(tx);
         const signed = await this.signTransaction(prepared.tx);
-        const result = await this.sendAndConfirmHttp(signed, prepared);
-        return result.signature;
+        return await this.sendAndConfirmHttp(signed, prepared);
     }
 
-
-    /** 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.
      */
     async buy(amountLamports: bigint, purchaseAsset: PurchaseAsset): Promise<string> {
         const user = this.solPubKey;
@@ -156,49 +211,63 @@ export class SolanaStakingClient implements IStakingClient {
 
         switch (purchaseAsset) {
             case PurchaseAsset.SOL: {
-                if (!amountLamports || amountLamports <= BigInt(0))
-                    throw new Error("SOL pretoken purchase requires a positive amount.");
-
-                ix = await this.tokenClient.buildPurchaseWithSolIx(amountLamports, user);
+                if (!amountLamports || amountLamports <= BigInt(0)) {
+                    throw new Error('SOL pretoken purchase requires a positive amount.');
+                }
+                ix = await this.tokenClient.buildPurchaseWithSolIx(
+                    amountLamports,
+                    user,
+                );
                 break;
             }
 
             case PurchaseAsset.LIQSOL: {
-                if (!amountLamports || amountLamports <= BigInt(0))
-                    throw new Error("liqSOL pretoken purchase requires a positive amount.");
-
+                if (!amountLamports || amountLamports <= BigInt(0)) {
+                    throw new Error(
+                        'liqSOL pretoken purchase requires a positive amount.',
+                    );
+                }
                 preIxs = await this.outpostClient.maybeBuildCreateUserAtaIx(user);
-                ix = await this.tokenClient.buildPurchaseWithLiqsolIx(amountLamports, user);
+                ix = await this.tokenClient.buildPurchaseWithLiqsolIx(
+                    amountLamports,
+                    user,
+                );
                 break;
             }
 
             case PurchaseAsset.YIELD: {
+                // Amount is ignored by the on-chain program; it consumes tracked yield.
                 ix = await this.tokenClient.buildPurchaseFromYieldIx(user);
                 break;
             }
 
             case PurchaseAsset.ETH:
             case PurchaseAsset.LIQETH: {
-                throw new Error("ETH / LIQETH pretoken purchases are not supported on Solana.");
+                throw new Error(
+                    'ETH / LIQETH pretoken purchases are not supported on Solana.',
+                );
             }
 
             default:
-                throw new Error(`Unsupported pretoken purchase asset: ${String(purchaseAsset)}`);
+                throw new Error(`Unsupported pretoken purchase asset: ${String(
+                    purchaseAsset,
+                )}`);
         }
 
         const tx = new Transaction().add(...preIxs, ix);
         const prepared = await this.prepareTx(tx);
         const signed = await this.signTransaction(prepared.tx);
-        const res = await this.sendAndConfirmHttp(signed, prepared);
-        return res.signature;
+        return await this.sendAndConfirmHttp(signed, prepared);
     }
 
     /**
-     * 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
      */
     async getPortfolio(): Promise<Portfolio> {
         const user = this.solPubKey;
@@ -215,35 +284,36 @@ export class SolanaStakingClient implements IStakingClient {
             ASSOCIATED_TOKEN_PROGRAM_ID,
         );
 
-        // IMPORTANT: use the SAME read primitive the outpost tests rely on
-        const [nativeLamports, actualBalResp, userRecord, snapshot] = await Promise.all([
-            this.connection.getBalance(user, "confirmed"),
-            this.connection.getTokenAccountBalance(userLiqsolAta, "confirmed").catch(() => null),
+        const [
+            nativeLamports,
+            actualBalResp,
+            userRecord,
+            snapshot,
+        ] = await Promise.all([
+            this.connection.getBalance(user, 'confirmed'),
+            this.connection
+                .getTokenAccountBalance(userLiqsolAta, 'confirmed')
+                .catch(() => null),
             this.distributionClient.getUserRecord(user).catch(() => null),
             this.outpostClient.getWireStateSnapshot(user).catch(() => null),
         ]);
 
         const LIQSOL_DECIMALS = 9;
 
-        const actualAmountStr = actualBalResp?.value?.amount ?? "0";
-
+        const actualAmountStr = actualBalResp?.value?.amount ?? '0';
         const trackedAmountStr =
-            userRecord?.trackedBalance ? userRecord.trackedBalance.toString() : "0";
+            userRecord?.trackedBalance?.toString() ?? '0';
 
-        // Snapshot is canonical; receipt may be null if user never staked/purchased
         const wireReceipt = snapshot?.wireReceipt ?? null;
         const userWarrantRecord = snapshot?.userWarrantRecord ?? null;
         const trancheState = snapshot?.trancheState ?? null;
         const globalState = snapshot?.globalState ?? null;
 
         const stakedAmountStr =
-            wireReceipt?.stakedLiqsol ? wireReceipt.stakedLiqsol.toString() : "0";
+            wireReceipt?.stakedLiqsol?.toString() ?? '0';
 
-        // Prelaunch WIRE "shares" = total warrants purchased by this user (1e8 precision)
         const wireSharesStr =
-            userWarrantRecord?.totalWarrantsPurchased
-                ? userWarrantRecord.totalWarrantsPurchased.toString()
-                : "0";
+            userWarrantRecord?.totalWarrantsPurchased?.toString() ?? '0';
 
         return {
             native: {
@@ -279,7 +349,6 @@ export class SolanaStakingClient implements IStakingClient {
                 vaultPDA: vaultPDA.toBase58(),
                 wireReceipt,
                 userWarrantRecord,
-                // global pretoken context (handy for UI + quoting)
                 globalIndex: globalState?.currentIndex?.toString(),
                 totalShares: globalState?.totalShares?.toString(),
                 currentTrancheNumber: trancheState?.currentTrancheNumber?.toString(),
@@ -290,165 +359,190 @@ export class SolanaStakingClient implements IStakingClient {
     }
 
     /**
-     * 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.
      */
-    async getTrancheSnapshot(): Promise<TrancheSnapshot | null> {
-        const snapshot = await this.outpostClient.getWireStateSnapshot(this.solPubKey);
-        const global = snapshot.globalState;
-        const tranche = snapshot.trancheState;
+    async getTrancheSnapshot(options?: {
+        chainID?: ChainID;
+        windowBefore?: number;
+        windowAfter?: number;
+    }): Promise<TrancheSnapshot> {
+        const {
+            chainID = SolChainID.WireTestnet,
+            windowBefore,
+            windowAfter,
+        } = options ?? {};
+
+        // Canonical program state
+        const [globalState, trancheState] = await Promise.all([
+            this.tokenClient.fetchGlobalState(),
+            this.tokenClient.fetchTrancheState(),
+        ]);
 
-        if (!global || !tranche) return null;
-        
-        return {
-            chainID: this.network.chainId,
-            totalShares: BigInt(global.totalShares.toString()),
-            currentIndex: BigInt(global.currentIndex.toString()),
-            currentTrancheNumber: BigInt(tranche.currentTrancheNumber.toString()),
-            currentTrancheSupply: BigInt(tranche.currentTrancheSupply.toString()),
-            totalWarrantsSold: BigInt(tranche.totalWarrantsSold.toString()),
-            currentTranchePriceUsd: BigInt(tranche.currentTranchePriceUsd.toString()),
-        };
+        // Latest SOL/USD price (1e8) + timestamp from PriceHistory
+        const { price: solPriceUsd, timestamp } =
+            await this.tokenClient.getSolPriceUsdSafe();
+
+        return buildSolanaTrancheSnapshot({
+            chainID,
+            globalState,
+            trancheState,
+            solPriceUsd,
+            nativePriceTimestamp: timestamp,
+            ladderWindowBefore: windowBefore,
+            ladderWindowAfter: windowAfter,
+        });
     }
 
-    // -------------------------------------------------------------
-    // Prelaunch WIRE quote (pretokens / warrants) – Solana side
-    // -------------------------------------------------------------
-    async getBuyQuote(amount: bigint, purchaseAsset: PurchaseAsset): Promise<PurchaseQuote> {
-        if (amount <= BigInt(0) && purchaseAsset !== PurchaseAsset.YIELD)
-            throw new Error("Buy amount must be greater than zero for non-YIELD purchases.");
+    /**
+     * Approximate prelaunch WIRE quote for a given amount & asset.
+     *
+     * 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
+     *
+     * NOTE: On-chain rounding may differ slightly (this is UI-only).
+     */
+    async getBuyQuote(
+        amount: bigint,
+        asset: PurchaseAsset,
+        opts?: { chainID?: ChainID },
+    ): Promise<PurchaseQuote> {
+        // For non-YIELD purchases we require a positive amount.
+        if (asset !== PurchaseAsset.YIELD && amount <= BigInt(0)) {
+            throw new Error('amount must be > 0 for non-YIELD purchases');
+        }
+
+        const snapshot = await this.getTrancheSnapshot({
+            chainID: opts?.chainID,
+        });
 
-        const user = this.solPubKey;
-        const snapshot = await this.outpostClient.getWireStateSnapshot(user);
-        const tranche = snapshot.trancheState;
+        const wirePriceUsd = snapshot.currentPriceUsd; // 1e8
+        const solPriceUsd = snapshot.nativePriceUsd;   // 1e8
 
-        if (!tranche) {
-            throw new Error("TrancheState not initialized; cannot quote WIRE purchase.");
+        if (!wirePriceUsd || wirePriceUsd <= BigInt(0)) {
+            throw new Error('Invalid WIRE price in tranche snapshot');
+        }
+        if (!solPriceUsd || solPriceUsd <= BigInt(0)) {
+            throw new Error('No SOL/USD price available');
         }
 
-        // WIRE pretoken price in USD (1e8 precision) from liqsol_core.TrancheState
-        const wirePriceUsd = tranche.currentTranchePriceUsd; // BN
-        const wireDecimals = 8;
+        const ONE_E9 = BigInt(LAMPORTS_PER_SOL);    // 1e9
+        const ONE_E8 = BigInt(100_000_000);         // 1e8
 
-        let notionalUsd: BN;   // 1e8 USD
-        let wireSharesBn: BN;  // 1e8 WIRE shares
+        let notionalUsd: bigint;
 
-        switch (purchaseAsset) {
+        switch (asset) {
             case PurchaseAsset.SOL: {
-                // SOL price in USD (1e8) – you wire this up in TokenClient using Chainlink / PriceHistory
-                const solPriceUsd = await this.tokenClient.getSolPriceUsd();
-
-                // amount is lamports (1e9). Convert to USD notional:
-                // usdValue = lamports * solPriceUsd / 1e9
-                notionalUsd = new BN(amount)
-                    .mul(solPriceUsd)
-                    .div(new BN(1_000_000_000)); // 10^9
-
-                wireSharesBn = this.calculateExpectedWarrants(notionalUsd, wirePriceUsd);
+                // lamports * solPriceUsd / 1e9  → 1e8 USD
+                notionalUsd = (amount * solPriceUsd) / ONE_E9;
                 break;
             }
 
             case PurchaseAsset.LIQSOL: {
-                // liqSOL price in USD (1e8). In many setups this == SOL price, but you keep it explicit.
-                const liqsolPriceUsd = await this.tokenClient.getSolPriceUsd();
-
-                // liqSOL has 9 decimals as well; treat `amount` as raw token units.
-                notionalUsd = new BN(amount)
-                    .mul(liqsolPriceUsd)
-                    .div(new BN(1_000_000_000)); // 10^9
-
-                wireSharesBn = this.calculateExpectedWarrants(notionalUsd, wirePriceUsd);
+                // liqSOL also uses 9 decimals; use same conversion.
+                notionalUsd = (amount * solPriceUsd) / ONE_E9;
                 break;
             }
 
             case PurchaseAsset.YIELD: {
-                // For purchase_warrants_from_yield, the on-chain logic effectively consumes
-                // tracked yield (claimBalance / availableBalance) at face value.
-                // You have two options for UI semantics:
-                //   - treat `amount` as a virtual SOL amount and reuse the SOL path, or
-                //   - ignore `amount` and quote based on the user's actual claimBalance.
-                //
-                // Here we keep it simple: `amount` is lamports-equivalent of SOL yield.
-                const solPriceUsd = await this.tokenClient.getSolPriceUsd();
-
-                notionalUsd = new BN(amount)
-                    .mul(solPriceUsd)
-                    .div(new BN(1_000_000_000));
-
-                wireSharesBn = this.calculateExpectedWarrants(notionalUsd, wirePriceUsd);
+                // Treat amount as lamports-equivalent of SOL yield (UI convention).
+                notionalUsd = (amount * solPriceUsd) / ONE_E9;
                 break;
             }
 
             case PurchaseAsset.ETH:
             case PurchaseAsset.LIQETH:
-                throw new Error("getBuyQuote for ETH/LIQETH is not supported on Solana.");
+                throw new Error('getBuyQuote for ETH/LIQETH is not supported on Solana');
 
             default:
-                // TS safety – should never hit for your enum
-                throw new Error(`Unsupported purchase asset: ${String(purchaseAsset)}`);
+                throw new Error(`Unsupported purchase asset: ${String(asset)}`);
         }
 
+        // WIRE shares (1e8) = (notionalUsd * 1e8) / wirePriceUsd
+        // Add a small bias to avoid truncating to 0 on tiny buys.
+        const numerator = notionalUsd * ONE_E8;
+        const wireShares =
+            numerator === BigInt(0)
+                ? BigInt(0)
+                : (numerator + wirePriceUsd - BigInt(1)) / wirePriceUsd;
+
         return {
-            purchaseAsset,
+            purchaseAsset: asset,
             amountIn: amount,
-            wireShares: BigInt(wireSharesBn.toString()),
-            wireDecimals,
-            wirePriceUsd: BigInt(wirePriceUsd.toString()), // 1e8
-            notionalUsd: BigInt(notionalUsd.toString()),   // 1e8
+            wireShares,
+            wireDecimals: 8,
+            wirePriceUsd,
+            notionalUsd,
         };
     }
 
-    // ---------------------------------------------------------------------
-    // SOL-only extras
-    // ---------------------------------------------------------------------
-
     /**
-     * Exact warrant math reused from your old utils, just phrased in terms
-     * of already-computed USD notional:
-     *
-     *   expectedWarrants = (notionalUsd * 1e8) / wirePriceUsd
-     *
-     * where:
-     *   - notionalUsd, wirePriceUsd are 1e8-scaled USD
-     *   - result is 1e8-scaled WIRE "shares"
+     * Convenience helper to fetch the distribution userRecord for the current user.
+     * Used by balance-correction flows and debugging.
      */
-    private calculateExpectedWarrants(notionalUsd: BN, wirePriceUsd: BN): BN {
-        const SCALE = new BN("100000000"); // 1e8
-        return notionalUsd.mul(SCALE).div(wirePriceUsd);
-    }
-
     async getUserRecord() {
         return this.distributionClient.getUserRecord(this.solPubKey);
     }
 
+    /**
+     * 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
+     */
     async correctBalance(amount?: bigint): Promise<string> {
         const build = await this.distributionClient.buildCorrectRegisterTx({ amount });
         if (!build.canSucceed || !build.transaction) {
             throw new Error(build.reason ?? 'Unable to build Correct&Register transaction');
         }
 
-        const { tx, blockhash, lastValidBlockHeight } = await this.prepareTx(build.transaction);
+        const { tx, blockhash, lastValidBlockHeight } = await this.prepareTx(
+            build.transaction,
+        );
         const signed = await this.signTransaction(tx);
-        const result = await this.sendAndConfirmHttp(signed, { blockhash, lastValidBlockHeight });
-        return result.signature;
+        const signature = await this.sendAndConfirmHttp(signed, {
+            blockhash,
+            lastValidBlockHeight,
+        });
+        return signature;
     }
 
     // ---------------------------------------------------------------------
     // Tx helpers
     // ---------------------------------------------------------------------
 
+    /**
+     * Send a signed transaction over HTTP RPC and wait for confirmation.
+     * Throws if the transaction fails.
+     */
     private async sendAndConfirmHttp(
         signed: SolanaTransaction,
         ctx: { blockhash: string; lastValidBlockHeight: number },
-    ): Promise<TxResult> {
-        const signature = await this.connection.sendRawTransaction(signed.serialize(), {
-            skipPreflight: false,
-            preflightCommitment: commitment,
-            maxRetries: 3,
-        });
+    ): Promise<string> {
+        const signature = await this.connection.sendRawTransaction(
+            signed.serialize(),
+            {
+                skipPreflight: false,
+                preflightCommitment: commitment,
+                maxRetries: 3,
+            },
+        );
 
         const conf = await this.connection.confirmTransaction(
-            { signature, blockhash: ctx.blockhash, lastValidBlockHeight: ctx.lastValidBlockHeight },
+            {
+                signature,
+                blockhash: ctx.blockhash,
+                lastValidBlockHeight: ctx.lastValidBlockHeight,
+            },
             commitment,
         );
 
@@ -456,29 +550,35 @@ export class SolanaStakingClient implements IStakingClient {
             throw new Error(`Transaction failed: ${JSON.stringify(conf.value.err)}`);
         }
 
-        return { signature, slot: conf.context.slot, confirmed: true };
+        return signature;
     }
 
+    /**
+     * Sign a single Solana transaction using the connected wallet adapter.
+     */
     async signTransaction(tx: SolanaTransaction): Promise<SolanaTransaction> {
         return this.anchor.wallet.signTransaction(tx);
     }
 
+    /**
+     * Generic "fire and forget" send helper if the caller already
+     * prepared and signed the transaction.
+     */
     async sendTransaction(signed: SolanaTransaction): Promise<TransactionSignature> {
         return this.anchor.sendAndConfirm(signed);
     }
 
+    /**
+     * Attach recent blockhash + fee payer to a transaction.
+     * Required before signing and sending.
+     */
     async prepareTx(
         tx: Transaction,
     ): Promise<{ tx: Transaction; blockhash: string; lastValidBlockHeight: number }> {
-        const { blockhash, lastValidBlockHeight } = await this.connection.getLatestBlockhash('confirmed');
+        const { blockhash, lastValidBlockHeight } =
+            await this.connection.getLatestBlockhash('confirmed');
         tx.recentBlockhash = blockhash;
         tx.feePayer = this.solPubKey;
         return { tx, blockhash, lastValidBlockHeight };
     }
-}
-
-export interface TxResult {
-    signature: string;
-    slot: number;
-    confirmed: boolean;
 }