@wireio/stake 0.1.0 → 0.1.1

package/lib/stake.d.ts

@@ -1,18 +1,12 @@
+import * as _wireio_core from '@wireio/core';
 import { PublicKey, ExternalNetwork, ChainID } from '@wireio/core';
 import { BaseSignerWalletAdapter } from '@solana/wallet-adapter-base';
-import { PublicKey as PublicKey$1, Transaction, VersionedTransaction, Connection, TransactionSignature, Signer as Signer$1, TransactionInstruction } from '@solana/web3.js';
-import { ethers, Signer, Contract } from 'ethers';
+import * as _solana_web3_js from '@solana/web3.js';
+import { PublicKey as PublicKey$1, Transaction, VersionedTransaction, TokenAmount, Connection, TransactionSignature, Keypair } from '@solana/web3.js';
+import { ethers, BigNumberish, BigNumber, Signer, Contract } from 'ethers';
 import { JsonFragment } from '@ethersproject/abi';
 import { ErrorDescription } from '@ethersproject/abi/lib/interface';
-import { AnchorProvider, Program } from '@coral-xyz/anchor';
-export { ASSOCIATED_TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID } from '@solana/spl-token';
-
-/**
- * Static utility functions for working with Wire Network Staking Protocol.
- *
- * @module utils
- */
-declare const hi: (name: string) => string;
+import { AnchorProvider, Program, BN } from '@coral-xyz/anchor';
 
 interface IStakingClient {
     pubKey: PublicKey;
@@ -40,7 +34,7 @@ interface Portfolio {
     extras?: Record<string, any>;
 }
 type BalanceView = {
-    amount: bigint;
+    amount: BigNumberish;
     decimals: number;
     symbol?: string;
     ata?: PublicKey$1;
@@ -66,53 +60,96 @@ declare class Staker {
     setChain(chainID: ChainID): boolean;
 }
 
-declare class EthereumStakingClient {
+declare class EthereumStakingClient implements IStakingClient {
     private config;
     readonly pubKey: PublicKey;
     private readonly provider;
     private readonly signer;
-    private readonly contract;
+    private readonly contractService;
+    get contract(): {
+        Stake: ethers.Contract;
+        LiqEth: ethers.Contract;
+        DepositManager: ethers.Contract;
+        LiqEthMint: ethers.Contract;
+        LiqEthBurn: ethers.Contract;
+        LiqEthTreasury: ethers.Contract;
+        LiqEthCommon: ethers.Contract;
+        RewardsERC20: ethers.Contract;
+        ValidatorBalanceVerifier: ethers.Contract;
+        Yield: ethers.Contract;
+        Accounting: ethers.Contract;
+        StakingModule: ethers.Contract;
+        WithdrawalQueue: ethers.Contract;
+        WithdrawalVault: ethers.Contract;
+    };
+    get network(): _wireio_core.ExternalNetwork;
     constructor(config: StakerConfig);
-    /** Submit a deposit; returns the transaction hash */
-    deposit(amount: number): Promise<string>;
-    /** (Optional) dry-run via eth_call */
-    simulateDeposit(amount: number): Promise<any>;
+    /**
+     * Deposit native ETH into the liqETH protocol via DepositManager.
+     * @param amount  Amount in wei (or something convertible to BigNumber).
+     *                Keep this as a bigint / string in the caller; avoid JS floats.
+     * @returns transaction hash
+     */
+    deposit(amount: number | string | bigint | BigNumber): Promise<string>;
+    /**
+     * Simulate a deposit via callStatic.
+     *
+     * Useful for pre-flight checks; will throw with the same revert
+     * reason as a real tx if it would fail.
+     */
+    simulateDeposit(amount: number | string | bigint | BigNumber): Promise<void>;
+    private performDeposit;
+    /**
+     * Build, sign, and submit a single transaction that:
+     *  - Corrects other users (if needed) to free available balance, then
+     *  - Registers the caller’s untracked liqSOL.
+     *
+     * @param amount  Optional: register a smaller amount than your full untracked balance.
+     * @returns signature string
+     */
+    register(amount?: bigint): Promise<string>;
+    /**
+     * Resolve the user's ETH + liqETH balances.
+     *
+     * native  = ETH in wallet
+     * actual  = liqETH token balance (ERC-20)
+     * tracked = liqETH tracked balance (protocol/accounting view)
+     */
+    getPortfolio(): Promise<Portfolio>;
 }
 
-declare const CONTRACT_NAMES: readonly ["Stake"];
+declare const CONTRACT_NAMES: readonly ["Stake", "LiqEth", "DepositManager", "LiqEthMint", "LiqEthBurn", "LiqEthTreasury", "LiqEthCommon", "RewardsERC20", "ValidatorBalanceVerifier", "Yield", "Accounting", "StakingModule", "WithdrawalQueue", "WithdrawalVault"];
 type ContractName = typeof CONTRACT_NAMES[number];
 type AddressBook = Record<ContractName, string>;
+interface DepositEvent {
+    user: string;
+    netEth: BigNumber;
+    fee: BigNumber;
+    shares: BigNumber;
+}
+interface DepositResult {
+    /** EVM transaction hash */
+    txHash: string;
+    /** Full receipt, if you want it */
+    receipt: ethers.providers.TransactionReceipt;
+    /** Parsed Deposited event, if present */
+    deposited?: DepositEvent;
+}
 
 type types$1_AddressBook = AddressBook;
 declare const types$1_CONTRACT_NAMES: typeof CONTRACT_NAMES;
 type types$1_ContractName = ContractName;
+type types$1_DepositEvent = DepositEvent;
+type types$1_DepositResult = DepositResult;
 declare namespace types$1 {
   export { types$1_CONTRACT_NAMES as CONTRACT_NAMES };
-  export type { types$1_AddressBook as AddressBook, types$1_ContractName as ContractName };
+  export type { types$1_AddressBook as AddressBook, types$1_ContractName as ContractName, types$1_DepositEvent as DepositEvent, types$1_DepositResult as DepositResult };
 }
 
 /**
  * @module EthereumContractService
  *
  * Provides a unified service for interacting with Ethereum smart contracts using ethers.js.
- *
- * This module includes:
- * - ABI imports for ERC20, ERC721, and ERC1155 token standards.
- * - Address book and contract configuration types.
- * - A service class for managing contract instances, interfaces, and utility methods for read/write access.
- * - Utility for decoding custom errors and events using a combined interface of all known ABIs.
- *
- * @remarks
- * - Update the `ADDRESSES` and `CONTRACTS` objects to match your deployment.
- * - The service supports both read-only and write-enabled contract handles, depending on the presence of a signer.
- * - The `omniInterface` property allows decoding of errors and events across all included ABIs.
- *
- * @example
- * ```typescript
- * const service = new EthereumContractService({ provider, signer });
- * const stakeContract = service.getContract('Stake');
- * const address = service.getAddress('Stake');
- * ```
  */
 
 declare const ERC20Abi: ({
@@ -298,69 +335,64 @@ declare class EthereumContractService {
     getInterface(name: ContractName): ethers.utils.Interface;
     /** Get live Contract instance */
     getContract(name: ContractName): ethers.Contract;
-    /** A unified Interface containing all ABIs (addresses + extra decoding-only)
-     *  to parse custom errors or events. */
+    /** A unified Interface containing all ABIs to parse custom errors or events. */
     get omniInterface(): ethers.utils.Interface;
     /** Decode a revert or custom error payload */
     parseError(revertData: string): ErrorDescription;
 }
 
 type SolanaTransaction = Transaction | VersionedTransaction;
-/** Raw mismatch row (per user with a userRecord) */
-type MismatchCandidate = {
-    /** Wallet that owns the ATA (decoded from token account) */
-    owner: PublicKey$1;
-    /** user_record PDA */
-    userRecordPda: PublicKey$1;
-    /** user’s ATA for liqSOL */
+type UserRecord = {
     userAta: PublicKey$1;
-    /** protocol tracked balance (u64) */
-    tracked: bigint;
-    /** actual on-chain token balance (u64) */
+    trackedBalance: bigint;
+    claimBalance: bigint;
+    lastClaimTimestamp: bigint;
+    bump: number;
+};
+type DistributionState = {
+    liqsolMint: PublicKey$1;
+    availableBalance: bigint;
+    totalTrackedBalance: bigint;
+    bump: number;
+};
+type ParsedAccountInfo = {
+    extensions: Array<{
+        extension: string;
+    }>;
+    isNative: boolean;
+    mint: string;
+    owner: string;
+    state: string;
+    tokenAmount: TokenAmount;
+};
+interface MismatchCandidate {
+    owner: PublicKey$1;
     actual: bigint;
-    /** tracked - actual (positive means “freeable”) */
+    tracked: bigint;
     delta: bigint;
-};
-/** Output when choosing candidates to free liquidity */
-type CorrectionPlan = {
-    /** selected candidates sorted by delta desc */
-    selected: MismatchCandidate[];
-    /** total delta we’ll free by correcting selected */
-    willFree: bigint;
-    /** how much still missing after selection (0 if we can meet the target) */
+}
+interface CorrectRegisterPlan {
     deficit: bigint;
-};
-/** What the builder returns to your caller/UI */
-type CorrectAndRegisterBuild = {
-    /** The ready-to-send transaction (if buildable) */
-    transaction?: Transaction;
-    /** True if the tx can succeed with current state */
+    willFree: bigint;
+    selected: MismatchCandidate[];
+}
+interface CorrectRegisterBuildResult {
+    needToRegister: boolean;
     canSucceed: boolean;
-    /** Explanation if not buildable */
     reason?: string;
-    /** Current liqSOL mint; useful for UI */
-    liqsolMint: PublicKey$1;
-    /** Amount you need to register (actual - tracked if positive) */
-    needToRegister: bigint;
-    /** Distribution “availableBalance” before this action */
-    availableBefore: bigint;
-    /** Candidates we scanned (already sorted by delta desc) */
-    candidates: MismatchCandidate[];
-    /** Subset we’d correct (maybe empty) */
-    plan: CorrectionPlan;
-    /** Convenience for caller */
-    accounts: {
-        selfUserRecordPda: PublicKey$1;
-        selfUserAta: PublicKey$1;
-    };
-};
+    transaction?: Transaction;
+    plan: CorrectRegisterPlan;
+}
 
-type types_CorrectAndRegisterBuild = CorrectAndRegisterBuild;
-type types_CorrectionPlan = CorrectionPlan;
+type types_CorrectRegisterBuildResult = CorrectRegisterBuildResult;
+type types_CorrectRegisterPlan = CorrectRegisterPlan;
+type types_DistributionState = DistributionState;
 type types_MismatchCandidate = MismatchCandidate;
+type types_ParsedAccountInfo = ParsedAccountInfo;
 type types_SolanaTransaction = SolanaTransaction;
+type types_UserRecord = UserRecord;
 declare namespace types {
-  export type { types_CorrectAndRegisterBuild as CorrectAndRegisterBuild, types_CorrectionPlan as CorrectionPlan, types_MismatchCandidate as MismatchCandidate, types_SolanaTransaction as SolanaTransaction };
+  export type { types_CorrectRegisterBuildResult as CorrectRegisterBuildResult, types_CorrectRegisterPlan as CorrectRegisterPlan, types_DistributionState as DistributionState, types_MismatchCandidate as MismatchCandidate, types_ParsedAccountInfo as ParsedAccountInfo, types_SolanaTransaction as SolanaTransaction, types_UserRecord as UserRecord };
 }
 
 declare class SolanaStakingClient implements IStakingClient {
@@ -370,6 +402,7 @@ declare class SolanaStakingClient implements IStakingClient {
     anchor: AnchorProvider;
     private depositClient;
     private distributionClient;
+    private leaderboardClient;
     get solPubKey(): PublicKey$1;
     get network(): ExternalNetwork;
     constructor(config: StakerConfig);
@@ -383,8 +416,9 @@ declare class SolanaStakingClient implements IStakingClient {
     /**
      * Optional: fetch your Distribution program user record
      * (often contains per-user deposit/claim state).
+     * @returns UserRecord or null
      */
-    getUserRecord(): Promise<any | null>;
+    getUserRecord(): Promise<UserRecord | null>;
     getProtocolFee(): void;
     /**
      * Build, sign, and submit a single transaction that:
@@ -417,496 +451,297 @@ interface TxResult {
 }
 
 /**
- * Program IDL in camelCase format in order to be used in JS/TS.
+ * ---------------------------------------------------------------------------
+ *  PROGRAM IDS
+ * ---------------------------------------------------------------------------
  *
- * Note that this is only a type helper and is not the actual IDL. The original
- * IDL can be found at `target/idl/deposit.json`.
+ * These should match:
+ *  - `metadata.address` in your Anchor IDLs under src/assets/solana/idl/*.json
+ *  - The program IDs printed by your deploy scripts
  */
-type Deposit = {
-    "address": "GqksbjX3r7SHZ5e8c6nFyPecZNnBSUTYHbF8U2YDb5Qf";
-    "metadata": {
-        "name": "deposit";
-        "version": "0.1.0";
-        "spec": "0.1.0";
-        "description": "Created with Anchor";
-    };
-    "instructions": [
-        {
-            "name": "deposit";
-            "discriminator": [
-                242,
-                35,
-                198,
-                137,
-                82,
-                225,
-                242,
-                182
-            ];
-            "accounts": [
-                {
-                    "name": "user";
-                    "writable": true;
-                    "signer": true;
-                },
-                {
-                    "name": "programAuthority";
-                    "writable": true;
-                    "pda": {
-                        "seeds": [
-                            {
-                                "kind": "const";
-                                "value": [
-                                    112,
-                                    114,
-                                    111,
-                                    103,
-                                    114,
-                                    97,
-                                    109,
-                                    95,
-                                    97,
-                                    117,
-                                    116,
-                                    104,
-                                    111,
-                                    114,
-                                    105,
-                                    116,
-                                    121
-                                ];
-                            }
-                        ];
-                    };
-                },
-                {
-                    "name": "systemProgram";
-                    "address": "11111111111111111111111111111111";
-                },
-                {
-                    "name": "tokenProgram";
-                },
-                {
-                    "name": "associatedTokenProgram";
-                    "address": "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
-                },
-                {
-                    "name": "stakeControllerProgram";
-                    "address": "4Ab1SwV6RPUN5Btnf95qvQCyNVR3iHnXjnMYaKsgimTp";
-                },
-                {
-                    "name": "liqsolProgram";
-                },
-                {
-                    "name": "payRateHistory";
-                },
-                {
-                    "name": "stakeProgram";
-                    "address": "Stake11111111111111111111111111111111111111";
-                },
-                {
-                    "name": "distributionProgram";
-                    "address": "26LF4typrWwBapujpvUPFpdfs4pBb6RwcWoBBy7Awf5j";
-                },
-                {
-                    "name": "liqsolMint";
-                    "writable": true;
-                },
-                {
-                    "name": "userAta";
-                    "writable": true;
-                    "pda": {
-                        "seeds": [
-                            {
-                                "kind": "account";
-                                "path": "user";
-                            },
-                            {
-                                "kind": "account";
-                                "path": "tokenProgram";
-                            },
-                            {
-                                "kind": "account";
-                                "path": "liqsolMint";
-                            }
-                        ];
-                        "program": {
-                            "kind": "const";
-                            "value": [
-                                140,
-                                151,
-                                37,
-                                143,
-                                78,
-                                36,
-                                137,
-                                241,
-                                187,
-                                61,
-                                16,
-                                41,
-                                20,
-                                142,
-                                13,
-                                131,
-                                11,
-                                90,
-                                19,
-                                153,
-                                218,
-                                255,
-                                16,
-                                132,
-                                4,
-                                142,
-                                123,
-                                216,
-                                219,
-                                233,
-                                248,
-                                89
-                            ];
-                        };
-                    };
-                },
-                {
-                    "name": "liqsolMintAuthority";
-                },
-                {
-                    "name": "reservePool";
-                    "writable": true;
-                },
-                {
-                    "name": "vault";
-                    "writable": true;
-                },
-                {
-                    "name": "ephemeralStake";
-                    "writable": true;
-                },
-                {
-                    "name": "controllerState";
-                    "writable": true;
-                },
-                {
-                    "name": "globalStakeInfo";
-                    "writable": true;
-                },
-                {
-                    "name": "bucketAuthority";
-                    "pda": {
-                        "seeds": [
-                            {
-                                "kind": "const";
-                                "value": [
-                                    108,
-                                    105,
-                                    113,
-                                    115,
-                                    111,
-                                    108,
-                                    95,
-                                    98,
-                                    117,
-                                    99,
-                                    107,
-                                    101,
-                                    116
-                                ];
-                            }
-                        ];
-                        "program": {
-                            "kind": "account";
-                            "path": "stakeControllerProgram";
-                        };
-                    };
-                },
-                {
-                    "name": "bucketTokenAccount";
-                    "docs": [
-                        "The bucket's associated token account"
-                    ];
-                    "writable": true;
-                },
-                {
-                    "name": "userRecord";
-                    "writable": true;
-                },
-                {
-                    "name": "distributionState";
-                    "writable": true;
-                },
-                {
-                    "name": "instructionsSysvar";
-                    "address": "Sysvar1nstructions1111111111111111111111111";
-                },
-                {
-                    "name": "clock";
-                    "address": "SysvarC1ock11111111111111111111111111111111";
-                },
-                {
-                    "name": "stakeHistory";
-                    "address": "SysvarStakeHistory1111111111111111111111111";
-                },
-                {
-                    "name": "rent";
-                    "address": "SysvarRent111111111111111111111111111111111";
-                }
-            ];
-            "args": [
-                {
-                    "name": "amount";
-                    "type": "u64";
-                },
-                {
-                    "name": "seed";
-                    "type": "u32";
-                }
-            ];
-        }
-    ];
-    "errors": [
-        {
-            "code": 6000;
-            "name": "depositTooSmall";
-            "msg": "Deposit amount is below minimum required";
-        },
-        {
-            "code": 6001;
-            "name": "notInitialized";
-            "msg": "Deposit Router not initialized";
-        },
-        {
-            "code": 6002;
-            "name": "invalidAuthority";
-            "msg": "Invalid authority";
-        },
-        {
-            "code": 6003;
-            "name": "insufficientFunds";
-            "msg": "Insufficient funds";
-        },
-        {
-            "code": 6004;
-            "name": "overflow";
-            "msg": "Arithmetic overflow";
-        },
-        {
-            "code": 6005;
-            "name": "calculationFailure";
-            "msg": "Calculation failure";
-        },
-        {
-            "code": 6006;
-            "name": "nothingToMint";
-            "msg": "Cannot mint zero tokens";
-        },
-        {
-            "code": 6007;
-            "name": "invalidAccount";
-            "msg": "Invalid account provided";
-        },
-        {
-            "code": 6008;
-            "name": "insufficientFundsForStake";
-            "msg": "Insufficient funds remaining after reserving fees to proceed with staking";
-        },
-        {
-            "code": 6009;
-            "name": "unauthorizedProgram";
-            "msg": "Unauthorized program attempting to call this instruction";
-        }
-    ];
+declare const PROGRAM_IDS: {
+    readonly LIQSOL_CORE: PublicKey$1;
+    readonly LIQSOL_TOKEN: PublicKey$1;
+    readonly VALIDATOR_LEADERBOARD: PublicKey$1;
 };
+declare const LIQSOL_CORE: PublicKey$1;
+declare const LIQSOL_TOKEN: PublicKey$1;
+declare const VALIDATOR_LEADERBOARD: PublicKey$1;
+/**
+ * ---------------------------------------------------------------------------
+ *  PDA SEEDS (must match on-chain programs)
+ * ---------------------------------------------------------------------------
+ *
+ * These strings are baked into the on-chain programs and are already used in
+ * your test utils. We centralize them here so all clients share them.
+ */
+declare const PDA_SEEDS: {
+    readonly DEPOSIT_AUTHORITY: "deposit_authority";
+    readonly VAULT: "vault";
+    readonly RESERVE_POOL: "reserve_pool";
+    readonly STAKE_CONTROLLER_STATE: "stake_controller";
+    readonly PAYOUT_STATE: "payout-state";
+    readonly LIQSOL_MINT: "liqsol_mint";
+    readonly LIQSOL_MINT_AUTHORITY: "mint_authority";
+    readonly BUCKET_AUTHORITY: "liqsol_bucket";
+    readonly DISTRIBUTION_STATE: "distribution_state";
+    readonly USER_RECORD: "user_record";
+    readonly PAY_RATE_HISTORY: "pay_rate_history";
+    readonly LEADERBOARD_STATE: "leaderboard_state";
+    readonly VALIDATOR_RECORD: "validator";
+    readonly GLOBAL_STAKE_INFO: "global_stake_info";
+};
+/**
+ * Helpers for PDA derivation so clients don’t duplicate logic.
+ */
+declare const deriveLiqsolMintPda: () => PublicKey$1;
+declare const deriveLiqsolMintAuthorityPda: () => PublicKey$1;
+declare const deriveDepositAuthorityPda: () => PublicKey$1;
+declare const deriveVaultPda: () => PublicKey$1;
+declare const deriveReservePoolPda: () => PublicKey$1;
+declare const deriveStakeControllerStatePda: () => PublicKey$1;
+declare const derivePayoutStatePda: () => PublicKey$1;
+declare const deriveBucketAuthorityPda: () => PublicKey$1;
+declare const deriveDistributionStatePda: () => PublicKey$1;
+declare const deriveUserRecordPda: (user: PublicKey$1) => PublicKey$1;
+declare const derivePayRateHistoryPda: () => PublicKey$1;
+declare const deriveLeaderboardStatePda: () => PublicKey$1;
+declare const deriveValidatorRecordPda: (voteAccount: PublicKey$1) => PublicKey$1;
+/**
+* Stake controller vault PDA (reserve pool SOL vault).
+* This is the same as VAULT, but named more explicitly for SDK callers.
+*/
+declare const deriveStakeControllerVaultPda: () => PublicKey$1;
+/**
+ * Ephemeral stake account address used per-deposit.
+ * On-chain convention: seed = `ephemeral_<u32>` under StakeProgram.programId.
+ */
+declare const deriveEphemeralStakeAddress: (user: PublicKey$1, seed: any) => Promise<PublicKey$1>;
+/**
+ * ---------------------------------------------------------------------------
+ *  ECONOMICS & MATH CONSTANTS
+ * ---------------------------------------------------------------------------
+ */
+declare const PAY_RATE_SCALE_FACTOR: bigint;
+declare const DEFAULT_AVERAGE_PAY_RATE: bigint;
+declare const DEFAULT_PAY_RATE_LOOKBACK = 5;
+declare const EPHEMERAL_RENT_EXEMPTION = 2282880;
+declare const LAMPORTS_PER_SOL = 1000000000;
+declare const lamportsToSol: (lamports: number | bigint) => number;
+declare const solToLamports: (sol: number) => number;
+/**
+ * ---------------------------------------------------------------------------
+ *  CLUSTER / ENVIRONMENT CONFIG (optional but handy)
+ * ---------------------------------------------------------------------------
+ */
+type SolanaCluster = 'localnet' | 'devnet' | 'mainnet';
 
-declare const DEPOSIT_PROGRAM_ID: PublicKey$1;
-declare const STAKE_CONTROLLER_PROGRAM_ID: PublicKey$1;
-declare const VALIDATOR_LEADERBOARD_PROGRAM_ID: PublicKey$1;
-declare const LIQSOL_TOKEN_PROGRAM_ID: PublicKey$1;
-declare const DISTRIBUTION_PROGRAM_ID: PublicKey$1;
-declare const YIELD_ORACLE_PROGRAM_ID: PublicKey$1;
-declare const MIN_SOL_TO_PARTICIPATE = 1000000000;
-declare const LIQSOL_MINT_ADDRESS: PublicKey$1;
-
-/** Create Anchor Program client for the Deposit program (with correct address) */
-declare const getDepositProgram: (provider: AnchorProvider) => Program<Deposit>;
-declare const deriveDepositAuthorityPDA: () => [PublicKey$1, number];
-declare const deriveLiqsolMintPDA: () => [PublicKey$1, number];
-/** ✅ FIXED: this must be derived with the LiqSOL token **program id**, not the mint address */
-declare const deriveLiqsolMintAuthorityPDA: () => [PublicKey$1, number];
-declare const deriveStakeControllerVaultPDA: () => [PublicKey$1, number];
-declare const deriveStakeControllerReservePoolPDA: () => [PublicKey$1, number];
-declare const deriveStakeControllerStatePDA: () => [PublicKey$1, number];
-declare const deriveGlobalStakeInfoPDA: () => [PublicKey$1, number];
-declare const deriveBucketAuthorityPDA: () => [PublicKey$1, number];
-declare const derivePayRateHistoryPDA: () => [PublicKey$1, number];
-declare const deriveDistributionStatePDA: () => [PublicKey$1, number];
-declare const deriveUserRecordPDA: (user: PublicKey$1) => [PublicKey$1, number];
-declare const deriveLeaderboardHeadPDA: () => [PublicKey$1, number];
-declare const deriveValidatorRecordPDA: (voteAccount: PublicKey$1) => [PublicKey$1, number];
-declare const deriveTop10CachePDA: () => [PublicKey$1, number];
-declare const deriveStakeControllerAuthorityPDA: () => [PublicKey$1, number];
-/** User’s liqSOL ATA (Token-2022) */
-declare const getUserLiqsolATA: (user: PublicKey$1) => PublicKey$1;
-
+declare function getLiqsolCoreProgram(connection: Connection): Program;
+interface DepositAccounts {
+    user: PublicKey$1;
+    depositAuthority: PublicKey$1;
+    liqsolMint: PublicKey$1;
+    liqsolMintAuthority: PublicKey$1;
+    userAta: PublicKey$1;
+    stakeControllerVault: PublicKey$1;
+    stakeControllerReservePool: PublicKey$1;
+    stakeControllerState: PublicKey$1;
+    payoutState: PublicKey$1;
+    bucketAuthority: PublicKey$1;
+    bucketTokenAccount: PublicKey$1;
+    distributionState: PublicKey$1;
+    userRecord: PublicKey$1;
+    payRateHistory: PublicKey$1;
+    ephemeralStake: PublicKey$1;
+    ephemeralSeed: string;
+}
+/**
+ * Build a complete DepositAccounts set for a given user, matching the
+ * on-chain PDAs used by the liqSOL core program.
+ *
+ * The optional `seed` lets you make deposit flows replayable/deterministic.
+ * If omitted, a random u32 seed is generated.
+ */
+declare function buildDepositAccounts(connection: Connection, user: PublicKey$1): Promise<DepositAccounts>;
+declare function getUserLiqSolBalance(connection: Connection, user: PublicKey$1): Promise<number>;
+declare function getBucketLiqSolBalance(connection: Connection): Promise<number>;
+declare function getReservePoolBalance(connection: Connection): Promise<number>;
+/**
+ * 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).
+ */
+declare function getStakeControllerStateRaw(connection: Connection): Promise<Uint8Array | null>;
+/**
+ * Raw account info for the payout-state account.
+ */
+declare function getPayoutStateRaw(connection: Connection): Promise<Uint8Array | null>;
+/**
+ * Raw account info for a user's distribution user_record.
+ */
+declare function getUserRecordRaw(connection: Connection, user: PublicKey$1): Promise<Uint8Array | null>;
+declare function getAveragePayRate(connection: Connection, lookback?: number): Promise<bigint>;
+/**
+ * On-chain fee formula:
+ *   fee = (average_pay_rate * 4 * deposit_amount_lamports) / 10^12
+ */
+declare function calculateExpectedFee(depositAmountLamports: BN, averagePayRate: BN): BN;
 /**
- * DepositClient: builds, simulates, and sends deposit txns matching the latest IDL.
+ * 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
  */
+declare function previewDepositEffects(params: {
+    depositAmountLamports: BN;
+    averagePayRate: BN;
+    rentExemptionLamports?: number;
+}): {
+    feeLamports: BN;
+    userLiqSolLamports: BN;
+    bucketLiqSolLamports: BN;
+    reserveIncreaseLamports: BN;
+};
+type EpochSnapshot = {
+    epoch: number;
+    slot: number;
+    firstSlot: number;
+    slotsInEpoch: number;
+    slotMs: number;
+};
+declare function getEpochSnapshot(connection: Connection): Promise<EpochSnapshot>;
+declare function msToEpochEnd(snapshot: EpochSnapshot): number;
+/**
+ * Generic "execute around epoch boundaries" helper:
+ *
+ * - If current progress is within [early, late], run immediately.
+ * - If too early, sleep until `early` percentage into the epoch.
+ * - If too late, sleep until `early` percentage into the *next* epoch.
+ *
+ * This is generic; you can wrap any instruction builder in here (including
+ * deposit flows) without baking in program-specific logic.
+ */
+declare function scheduledInstruction<T>(connection: Connection, config: ScheduleConfig, instruction: () => Promise<T>): Promise<T>;
+declare function getErrorMessage(error: any): string;
+declare function generateRandomDepositAmount(minSol?: number, maxSol?: number): BN;
+declare function generateTestKeypair(): Keypair;
+declare function airdropSol(connection: Connection, publicKey: PublicKey$1, amountSol: number): Promise<void>;
+declare function waitForConfirmation(connection: Connection, signature: string): Promise<void>;
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Simple helper used in tests: wait until safe zone, no-op.
+ */
+declare function waitUntilSafeToExecuteFunction(connection: Connection, config?: ScheduleConfig): Promise<void>;
+interface ScheduleConfig {
+    early?: number;
+    late?: number;
+}
+
 declare class DepositClient {
     private provider;
-    private programs;
+    private program;
     constructor(provider: AnchorProvider);
-    /**
-     * Build the deposit transaction (compute-budget bump + deposit Ix).
-     * Returns the Transaction and the derived ephemeral stake pubkey.
-     */
-    buildDepositTx(user: PublicKey$1, amount: number): Promise<{
+    buildDepositTx(user: PublicKey$1, lamports: number): Promise<{
         transaction: Transaction;
-        ephemeralStakePubkey: PublicKey$1;
-    }>;
-    /** Simulate a transaction (dry-run). */
-    simulate(tx: Transaction): Promise<{
-        err: any;
-        unitsConsumed: number;
+        ephemeralStake: PublicKey$1;
     }>;
-    /** Build + send. Returns confirmed signature. */
-    deposit(user: PublicKey$1, amount: number, signers?: Signer$1[]): Promise<TransactionSignature>;
 }
 
+/**
+ * Distribution client – wraps the distribution portion of the liqsol_core
+ * program. Responsible for:
+ *  - Reading DistributionState + UserRecord
+ *  - Computing mismatch candidates (tracked > actual)
+ *  - Building a "correct then register" transaction for the caller
+ *
+ * Aligned with the on-chain `update_user` script:
+ *   - Single `updateUser()` entrypoint that:
+ *       * Can create userRecord if missing
+ *       * Reconciles tracked vs actual using user, userAta, bucket, pay-rate
+ */
 declare class DistributionClient {
     private provider;
-    private programs;
+    private program;
     constructor(provider: AnchorProvider);
-    /** Anchor Program<Distribution> (address comes from SolanaProgramService) */
-    private get program();
-    /**
-     * Fetch Distribution global state.
-     */
-    getDistributionState(): Promise<any>;
+    get connection(): _solana_web3_js.Connection;
     /**
-     * Fetch a user’s UserRecord or null if it doesn’t exist yet.
+     * Fetch the global distribution state account.
      */
-    getUserRecord(user: PublicKey$1): Promise<any | null>;
+    getDistributionState(): Promise<DistributionState | null>;
     /**
-     * Read protocol-tracked balance for a user (from userRecord).
-     * Returns (amount, decimals).
-     * @default decimals=9
+     * Fetch a user's distribution userRecord (or null if missing).
      */
-    getTrackedBalance(user: PublicKey$1): Promise<{
-        amount: bigint;
-        decimals: number;
-    }>;
-    /**
-     * Read *actual* liqSOL token balance (ATA) for a user.
-     * If user has no ATA yet, returns 0.
-     * @returns { amount, decimals, ata }
-     */
-    getActualBalance(user: PublicKey$1): Promise<{
-        amount: bigint;
-        decimals: number;
-        ata: PublicKey$1;
-    }>;
+    getUserRecord(user: PublicKey$1): Promise<UserRecord | null>;
     /**
-     * Register / Update a user’s record.
-     * - If updating someone else, pass their pubkey as `targetUser` and let the connected wallet be `authority`.
-     * - Optionally pass an explicit `authorityUser` if you need to override (must be the connected wallet).
-     * Returns the tx signature.
+     * Helper: get actual liqSOL balances for all token holders.
+     *
+     * Returns a map: owner (base58) -> actual balance (BigInt)
      */
+    private getActualBalancesByOwner;
     /**
-     * Register / Update a user’s record with the connected wallet as authority.
-     * Keeps a single source of truth via `prepareUpdateUser()`.
+     * Helper: get tracked balances from all userRecord accounts,
+     * keyed by *actual wallet owner*, not the userRecord PDA.
+     *
+     * userRecord struct:
+     *  - userAta: pubkey
+     *  - trackedBalance: u64
+     *  - claimBalance: u64
+     *  - lastClaimTimestamp: i64
+     *  - bump: u8
      */
-    updateUser(targetUser: PublicKey$1): Promise<string>;
-    /** Build-only variant (returns the IX) so you can batch. */
-    buildUpdateUserIx(targetUser: PublicKey$1): Promise<TransactionInstruction>;
+    private getTrackedBalances;
     /**
-     * Claim rewards for a user.
-     * @returns tx signature
+     * Discover all mismatch candidates where tracked > actual.
+     *
+     * - actual balances are derived from token accounts for the liqSOL mint
+     * - tracked balances come from Distribution.userRecord
      */
-    claimRewards(user: PublicKey$1): Promise<string>;
+    private deriveMismatchCandidates;
     /**
-     * Withdraw liqSOL (amount in base units; e.g. 1e9 = 1 liqSOL).
-     * @returns tx signature
+     * Canonical helper to build an `updateUser` instruction for a given user,
+     * matching the standalone update-user.ts script.
      */
-    withdraw(user: PublicKey$1, amount: bigint | number): Promise<string>;
-    /** Single prep path used by both send & build. */
-    private prepareUpdateUser;
+    private buildUpdateUserIx;
     /**
-     * Build a single transaction that:
-     *  1) If self mismatch < 0 → just correct self (single updateUser).
-     *  2) Else (mismatch > 0) → correct top candidates (if needed) to free “available” balance
-     *     and then register self (updateUser).
+     * Build the "correct & register" transaction.
+     *
+     * - Fetches DistributionState + all userRecords + token holders
+     * - Computes caller's untracked amount (actual - tracked)
+     * - If DistributionState.availableBalance already covers that, we only
+     *   send updateUser(caller).
+     * - Otherwise we select top mismatch candidates until their freed deltas
+     *   cover the shortfall, then build updateUser(target) for each,
+     *   followed by updateUser(caller).
      *
-     * It refuses to build if it can’t free enough to cover the full positive untracked amount
-     * (since updateUser has no partial-amount arg).
+     * NOTE:
+     *  - This no longer uses a separate updateSpecificUser; the single
+     *    updateUser entrypoint accepts any `user` as long as authority/payer
+     *    are valid, per your script.
      */
     buildCorrectRegisterTx(opts?: {
-        /** optional override of computed mismatch; may be positive (register) or negative (self-correct) */
         amount?: bigint;
-        /** optionally pass pre-fetched candidates to avoid re-reading on UI flows */
-        preloadCandidates?: MismatchCandidate[];
-    }): Promise<CorrectAndRegisterBuild>;
-    /**
-     * Fetch all distribution user records and turn them into mismatch candidates:
-     * rows where `tracked > actual` (delta > 0). Sorted by largest delta first.
-     *
-     * NOTE: This reads each user’s token account (`getAccount`) to recover
-     * the owner and actual balance — simpler and reliable for Token-2022 ATAs.
-     */
-    fetchMismatchCandidates(): Promise<MismatchCandidate[]>;
-    /**
-     * Given a required amount to free (in base units), choose the
-     * smallest prefix of candidates (already sorted desc) that can cover it.
-     */
-    chooseCandidatesFor(required: bigint, candidates: MismatchCandidate[]): CorrectionPlan;
+        maxCandidates?: number;
+    }): Promise<CorrectRegisterBuildResult>;
 }
 
-declare class ValidatorLeaderboardClient {
+/**
+ * Simple read client for the validator_leaderboard program.
+ *
+ * Adjust account names/fields to match your IDL (state, validatorRecord, etc).
+ */
+declare class LeaderboardClient {
     private provider;
-    private programs;
+    private program;
     constructor(provider: AnchorProvider);
-    /** Anchor Program<ValidatorLeaderboard> via ProgramService */
-    private get program();
-    /** Initialize the leaderboard head account. */
-    buildInitializeIx(authority: PublicKey$1): Promise<TransactionInstruction>;
+    getState(): Promise<any | null>;
+    getValidatorRecord(voteAccount: PublicKey$1): Promise<any | null>;
     /**
-     * Upsert/update a validator record and (optionally) reposition it in the linked list.
-     * Any of insertAfter/insertBefore/currentPrev/currentNext can be omitted.
+     * Convenience helper to fetch and sort top validators by score.
+     * Assumes `validatorRecord` has a numeric `score` field in the IDL.
      */
-    buildUpdateValidatorIx(params: {
-        registrant: PublicKey$1;
-        voteAccount: PublicKey$1;
-        vpp: number;
-        insertAfter?: PublicKey$1;
-        insertBefore?: PublicKey$1;
-        currentPrev?: PublicKey$1;
-        currentNext?: PublicKey$1;
-    }): Promise<TransactionInstruction>;
-    /** Update the Top-10 cache. Requires exactly 10 validator vote accounts. */
-    buildUpdateTop10CacheIx(params: {
-        authority: PublicKey$1;
-        top10Validators: PublicKey$1[];
-    }): Promise<TransactionInstruction>;
-    buildInitializeTx(authority: PublicKey$1): Promise<Transaction>;
-    buildUpdateValidatorTx(params: {
-        registrant: PublicKey$1;
-        voteAccount: PublicKey$1;
-        vpp: number;
-        insertAfter?: PublicKey$1;
-        insertBefore?: PublicKey$1;
-        currentPrev?: PublicKey$1;
-        currentNext?: PublicKey$1;
-    }): Promise<Transaction>;
-    buildUpdateTop10CacheTx(params: {
-        authority: PublicKey$1;
-        top10Validators: PublicKey$1[];
-    }): Promise<Transaction>;
-    /** Traverse the linked-list leaderboard, returning vote accounts in order. */
-    getLeaderboard(): Promise<PublicKey$1[]>;
-    /** Fetch a single validator record (or null if it doesn't exist). */
-    getValidatorRecord(voteAccount: PublicKey$1): Promise<any | null>;
+    getTopValidators(limit?: number): Promise<any[]>;
 }
 
-export { ADDRESSES, CONTRACTS, DEPOSIT_PROGRAM_ID, DISTRIBUTION_PROGRAM_ID, DepositClient, DistributionClient, ERC1155Abi, ERC20Abi, ERC721Abi, types$1 as ETH, EthereumContractService, EthereumStakingClient, LIQSOL_MINT_ADDRESS, LIQSOL_TOKEN_PROGRAM_ID, MIN_SOL_TO_PARTICIPATE, types as SOL, STAKE_CONTROLLER_PROGRAM_ID, SolanaStakingClient, Staker, VALIDATOR_LEADERBOARD_PROGRAM_ID, ValidatorLeaderboardClient, YIELD_ORACLE_PROGRAM_ID, deriveBucketAuthorityPDA, deriveDepositAuthorityPDA, deriveDistributionStatePDA, deriveGlobalStakeInfoPDA, deriveLeaderboardHeadPDA, deriveLiqsolMintAuthorityPDA, deriveLiqsolMintPDA, derivePayRateHistoryPDA, deriveStakeControllerAuthorityPDA, deriveStakeControllerReservePoolPDA, deriveStakeControllerStatePDA, deriveStakeControllerVaultPDA, deriveTop10CachePDA, deriveUserRecordPDA, deriveValidatorRecordPDA, getDepositProgram, getUserLiqsolATA, hi };
-export type { BalanceView, ContractConfig, ContractOptions, Contracts, IStakingClient, Portfolio, StakerConfig, TxResult };
+export { ADDRESSES, 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, PAY_RATE_SCALE_FACTOR, PDA_SEEDS, PROGRAM_IDS, types as SOL, SolanaStakingClient, Staker, VALIDATOR_LEADERBOARD, airdropSol, buildDepositAccounts, calculateExpectedFee, deriveBucketAuthorityPda, deriveDepositAuthorityPda, deriveDistributionStatePda, deriveEphemeralStakeAddress, deriveLeaderboardStatePda, deriveLiqsolMintAuthorityPda, deriveLiqsolMintPda, derivePayRateHistoryPda, derivePayoutStatePda, deriveReservePoolPda, deriveStakeControllerStatePda, deriveStakeControllerVaultPda, deriveUserRecordPda, deriveValidatorRecordPda, deriveVaultPda, 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, DepositAccounts, EpochSnapshot, IStakingClient, Portfolio, ScheduleConfig, SolanaCluster, StakerConfig, TxResult };