aftermath-ts-sdk
Version:
Aftermath TypeScript SDK
241 lines • 10.8 kB
TypeScript
import { Apr, Balance, CallerConfig, CoinType, CoinsToDecimals, CoinsToPrice, ObjectId, SuiAddress, Timestamp } from "../../types";
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: {
rewardCoinType: CoinType;
emissionScheduleMs: Timestamp;
emissionRate: bigint;
}[];
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;
emissionRate: bigint;
emissionDelayTimestampMs: Timestamp;
rewardCoinType: CoinType;
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;
rewardCoinType: CoinType;
}[];
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;
/**
* 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