aftermath-ts-sdk 1.2.63 → 1.2.64-docs.1

package/dist/packages/farms/farmsStakingPool.d.ts

@@ -2,44 +2,158 @@ import { Apr, Balance, CallerConfig, CoinType, CoinsToDecimals, CoinsToPrice, Ob
 import { Caller } from "../../general/utils/caller";
 import { ApiFarmsGrantOneTimeAdminCapBody, FarmOwnerOrOneTimeAdminCap, FarmsMultiplier, FarmsStakingPoolObject, FarmsStakingPoolRewardCoin, FarmsVersion } from "./farmsTypes";
 import { AftermathApi } from "../../general/providers";
+/**
+ * The `FarmsStakingPool` class represents a staking pool (also referred
+ * to as a "vault" in some contexts). It allows reading details about
+ * emission schedules, reward tokens, stake coin type, and lock durations,
+ * as well as constructing transactions to stake, harvest, and mutate the
+ * pool parameters if the user has the correct admin privileges.
+ */
 export declare class FarmsStakingPool extends Caller {
     stakingPool: FarmsStakingPoolObject;
     private readonly Provider?;
+    /**
+     * Creates a `FarmsStakingPool` instance based on on-chain pool data.
+     *
+     * @param stakingPool - The on-chain data object describing the pool.
+     * @param config - An optional `CallerConfig` for network settings.
+     * @param Provider - An optional `AftermathApi` for transaction building.
+     */
     constructor(stakingPool: FarmsStakingPoolObject, config?: CallerConfig, Provider?: AftermathApi | undefined);
+    /**
+     * Fetches the total value locked (TVL) for this staking pool alone.
+     *
+     * @returns A `number` representing this pool's TVL in USD (or another currency).
+     *
+     * @example
+     * ```typescript
+     * const poolTvl = await someFarmsPool.getTVL();
+     * console.log(poolTvl);
+     * ```
+     */
     getTVL(): Promise<number>;
+    /**
+     * Fetches the total value locked (TVL) of the reward coins in this specific staking pool.
+     *
+     * @returns A `number` representing this pool's reward TVL.
+     *
+     * @example
+     * ```typescript
+     * const rewardTvl = await someFarmsPool.getRewardsTVL();
+     * console.log(rewardTvl);
+     * ```
+     */
     getRewardsTVL(): Promise<number>;
+    /**
+     * Retrieves the version of this staking pool (1 or 2).
+     */
     version: () => FarmsVersion;
+    /**
+     * Lists all reward coin types offered by this staking pool.
+     *
+     * @returns An array of `CoinType` strings.
+     */
     rewardCoinTypes: () => CoinType[];
+    /**
+     * Lists all reward coin types for which this pool currently has a non-zero actual reward balance.
+     *
+     * @returns An array of `CoinType` strings that have > 0 actual rewards.
+     */
     nonZeroRewardCoinTypes: () => CoinType[];
+    /**
+     * Retrieves the on-chain record for a specific reward coin type in this pool.
+     *
+     * @param inputs - Contains the `coinType` to look up.
+     * @throws If the specified coinType is not found in `rewardCoins`.
+     * @returns A `FarmsStakingPoolRewardCoin` object.
+     */
     rewardCoin: (inputs: {
         coinType: CoinType;
     }) => FarmsStakingPoolRewardCoin;
+    /**
+     * Computes the maximum lock duration (in ms) that remains valid in this staking pool,
+     * factoring in the current time and the pool's emission end.
+     *
+     * @returns The maximum possible lock duration in milliseconds, or 0 if the pool is effectively closed.
+     */
     maxLockDurationMs: () => number;
+    /**
+     * Calculates and applies newly emitted rewards for each reward coin in this pool,
+     * updating the `rewardsAccumulatedPerShare`. This simulates the on-chain
+     * `emitRewards` logic.
+     *
+     * @example
+     * ```typescript
+     * someFarmsPool.emitRewards();
+     * // The pool's rewardsAccumulatedPerShare fields are now updated.
+     * ```
+     */
     emitRewards: () => void;
+    /**
+     * Computes an approximate APR for a specific reward coin, based on the current
+     * emission rate, coin price, pool TVL, and the lock multiplier range. This assumes
+     * maximum lock multiplier for the final APR result.
+     *
+     * @param inputs - Includes the `coinType`, its `price` and `decimals`, plus the total `tvlUsd` in the pool.
+     * @returns A numeric APR (0.05 = 5%).
+     */
     calcApr: (inputs: {
         coinType: CoinType;
         price: number;
         decimals: number;
         tvlUsd: number;
     }) => Apr;
+    /**
+     * Computes the total APR contributed by all reward coin types in this pool, summing
+     * up the individual APR for each coin type. This also assumes max lock multiplier.
+     *
+     * @param inputs - Contains price data (`coinsToPrice`), decimal data (`coinsToDecimals`), and the total TVL in USD.
+     * @returns The sum of all coin APRs (0.10 = 10%).
+     */
     calcTotalApr: (inputs: {
         coinsToPrice: CoinsToPrice;
         coinsToDecimals: CoinsToDecimals;
         tvlUsd: number;
     }) => Apr;
+    /**
+     * Given a lock duration in ms, calculates the lock multiplier to be used by staked positions.
+     * This function clamps the input duration between the pool's `minLockDurationMs` and
+     * `maxLockDurationMs`.
+     *
+     * @param inputs - An object containing the `lockDurationMs` for which to calculate a multiplier.
+     * @returns A `FarmsMultiplier` (bigint) representing the scaled factor (1.0 = 1e9 if using fixedOneB).
+     */
     calcMultiplier: (inputs: {
         lockDurationMs: number;
     }) => FarmsMultiplier;
+    /**
+     * Builds a transaction to stake tokens into this pool, optionally locking them.
+     *
+     * @param inputs - Contains `stakeAmount`, `lockDurationMs`, `walletAddress`, and optional sponsorship.
+     * @returns A transaction object (or bytes) that can be signed and executed to create a staked position.
+     */
     getStakeTransaction(inputs: {
         stakeAmount: Balance;
         lockDurationMs: Timestamp;
         walletAddress: SuiAddress;
         isSponsoredTx?: boolean;
     }): Promise<import("@mysten/sui/transactions").Transaction>;
+    /**
+     * Builds a transaction to harvest rewards from multiple staked positions in this pool.
+     *
+     * @param inputs - Contains `stakedPositionIds`, the `walletAddress`, and optionally any others.
+     * @returns A transaction that can be signed and executed to claim rewards from multiple positions.
+     */
     getHarvestRewardsTransaction(inputs: {
         stakedPositionIds: ObjectId[];
         walletAddress: SuiAddress;
     }): Promise<import("@mysten/sui/transactions").Transaction>;
+    /**
+     * Builds a transaction to increase the emission rate (or schedule) for specific reward coins.
+     *
+     * @param inputs - Contains the `ownerCapId` that authorizes changes, plus an array of `rewards` with new emission details.
+     * @returns A transaction to be signed and executed by the owner cap holder.
+     */
     getIncreaseRewardsEmissionsTransaction(inputs: {
         ownerCapId: ObjectId;
         rewards: {
@@ -49,12 +163,32 @@ export declare class FarmsStakingPool extends Caller {
         }[];
         walletAddress: SuiAddress;
     }): Promise<import("@mysten/sui/transactions").Transaction>;
+    /**
+     * Builds a transaction to update the pool's minimum stake amount, only authorized by the `ownerCapId`.
+     *
+     * @param inputs - Contains the new `minStakeAmount`, the `ownerCapId`, and the calling `walletAddress`.
+     * @returns A transaction that can be signed and executed to change the minimum stake requirement.
+     */
     getUpdateMinStakeAmountTransaction(inputs: {
         ownerCapId: ObjectId;
         minStakeAmount: bigint;
         walletAddress: SuiAddress;
     }): Promise<import("@mysten/sui/transactions").Transaction>;
+    /**
+     * Builds a transaction granting a one-time admin cap to another address, allowing them to perform specific
+     * one-time administrative actions (like initializing a reward).
+     *
+     * @param inputs - Body containing the `ownerCapId`, the `recipientAddress`, and the `rewardCoinType`.
+     * @returns A transaction to be executed by the current pool owner.
+     */
     getGrantOneTimeAdminCapTransaction(inputs: ApiFarmsGrantOneTimeAdminCapBody): import("@mysten/sui/transactions").Transaction;
+    /**
+     * Builds a transaction to initialize a new reward coin in this pool, specifying the amount, emission rate,
+     * and schedule parameters. This can be done by either the `ownerCapId` or a `oneTimeAdminCapId`.
+     *
+     * @param inputs - Contains emission info (rate, schedule) and which cap is used (`ownerCapId` or `oneTimeAdminCapId`).
+     * @returns A transaction object for the reward initialization.
+     */
     getInitializeRewardTransaction(inputs: {
         rewardAmount: Balance;
         emissionScheduleMs: Timestamp;
@@ -64,6 +198,13 @@ export declare class FarmsStakingPool extends Caller {
         walletAddress: SuiAddress;
         isSponsoredTx?: boolean;
     } & FarmOwnerOrOneTimeAdminCap): Promise<import("@mysten/sui/transactions").Transaction>;
+    /**
+     * Builds a transaction to add more reward coins (top-up) to an existing reward
+     * coin configuration, either as the owner or via a one-time admin cap.
+     *
+     * @param inputs - Contains an array of reward objects, each specifying amount and coin type.
+     * @returns A transaction that can be signed and executed to increase the reward distribution pool.
+     */
     getTopUpRewardsTransaction(inputs: {
         rewards: {
             rewardAmount: Balance;
@@ -72,10 +213,29 @@ export declare class FarmsStakingPool extends Caller {
         walletAddress: SuiAddress;
         isSponsoredTx?: boolean;
     } & FarmOwnerOrOneTimeAdminCap): Promise<import("@mysten/sui/transactions").Transaction>;
+    /**
+     * Updates `rewardsAccumulatedPerShare` by distributing `rewardsToEmit` among
+     * the total staked amount with multiplier. This mimics on-chain distribution logic.
+     *
+     * @param inputs - Contains the `rewardsToEmit` and which `rewardCoinIndex` to update.
+     */
     private increaseRewardsAccumulatedPerShare;
-    private rewardsRemaining;
+    /**
+     * Computes how many rewards to emit based on the time since `lastRewardTimestamp` and
+     * the pool's emission schedule, clamped by the total `rewardsRemaining`.
+     */
     private calcRewardsToEmit;
+    /**
+     * Calculates how many tokens were emitted between two timestamps (Tm and Tn) for a given reward coin,
+     * based on the discrete `emissionRate` and `emissionSchedulesMs`.
+     *
+     * @param inputs - Contains `timestampTm`, `timestampTn`, and the relevant `rewardCoin`.
+     * @returns The total number of tokens emitted in that time window.
+     */
     private calcRewardsEmittedFromTimeTmToTn;
+    /**
+     * Provides access to the farm-specific provider methods for building transactions.
+     */
     private useProvider;
 }
 //# sourceMappingURL=farmsStakingPool.d.ts.map

package/dist/packages/farms/farmsStakingPool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"farmsStakingPool.d.ts","sourceRoot":"","sources":["../../../src/packages/farms/farmsStakingPool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"farmsStakingPool.d.ts","sourceRoot":"","sources":["../../../src/packages/farms/farmsStakingPool.ts"],"names":[],"mappings":"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"}