Class FarmsStakingPool

constructor

• new FarmsStakingPool(
      stakingPool: FarmsStakingPoolObject,
      config?: CallerConfig,
      api?: AftermathApi,
  ): FarmsStakingPool

  Creates a FarmsStakingPool instance from normalized pool data.

  Parameters

  • stakingPool: FarmsStakingPoolObject

    Normalized pool data returned by a farm object read.

  • Optionalconfig: CallerConfig

    Optional network and API-host configuration for TVL reads.

  • Optionalapi: AftermathApi

    Optional provider required by transaction builders.

  Returns FarmsStakingPool

Optional Readonlyapi

stakingPool

calcApr

• calcApr(
      inputs: {
          coinType: string;
          decimals: number;
          price: number;
          tvlUsd: number;
      },
  ): number

  Computes an approximate APR for one reward coin.

  The calculation annualizes the current discrete emission rate, converts the rate to USD with price and decimals, divides by tvlUsd, and assumes the pool's maximum lock multiplier. It returns zero when the price or TVL is not positive, emissions have not started or have ended, or the actual reward balance is below one emission amount.

  Parameters

  • inputs: { coinType: string; decimals: number; price: number; tvlUsd: number }

    Includes the coinType, its price and decimals, plus the total tvlUsd in the pool.

  Returns number

  APR as a decimal fraction, such as 0.05 for 5%.

calcMultiplier

• calcMultiplier(inputs: { lockDurationMs: number }): bigint

  Calculates the lock multiplier for a duration in milliseconds.

  The duration is clamped to the pool's minimum and maximum. The result is linearly interpolated between 1.0 and maxLockMultiplier; if the pool's minimum and maximum durations are equal, the result is 1.0.

  Parameters

  • inputs: { lockDurationMs: number }

    An object containing the lockDurationMs for which to calculate a multiplier.

  Returns bigint

  An 18-decimal fixed-point FarmsMultiplier; 1e18n represents 1.0.

calcTotalApr

• calcTotalApr(
      inputs: {
          coinsToDecimals: CoinsToDecimals;
          coinsToPrice: CoinsToPrice;
          tvlUsd: number;
      },
  ): number

  Computes the sum of the approximate APR for every reward coin in the pool. Each component uses the maximum lock multiplier and the supplied price and decimal maps.

  Parameters

  • inputs: { coinsToDecimals: CoinsToDecimals; coinsToPrice: CoinsToPrice; tvlUsd: number }

    Contains price data (coinsToPrice), decimal data (coinsToDecimals), and the total TVL in USD.

  Returns number

  The combined APR as a decimal fraction, such as 0.10 for 10%.

emitRewards

• emitRewards(): void

  Applies completed emission intervals to this local pool view.

  The method updates rewardsAccumulatedPerShare and each reward's last checkpoint. It emits nothing when the pool has no stake, waits until a full interval has elapsed, and caps emission at rewardsRemaining. It does not fetch fresh pool data or submit a transaction.

  Returns void

  Example

  someFarmsPool.emitRewards();
  // The pool's rewardsAccumulatedPerShare fields are now updated.
  Copy

getGrantOneTimeAdminCapTransaction

• getGrantOneTimeAdminCapTransaction(
      inputs: ApiFarmsGrantOneTimeAdminCapBody,
  ): Transaction

  Builds a transaction granting a one-time admin capability to another address.

  The capability is scoped to the pool and reward coin supplied in inputs. Only the current owner can grant it.

  Parameters

  • inputs: ApiFarmsGrantOneTimeAdminCapBody

    Owner capability, recipient, reward coin type, and signing wallet.

  Returns Transaction

  An unsigned transaction to be executed by the pool owner.

  Throws

  An error if no AftermathApi instance was provided.

getHarvestRewardsTransaction

• getHarvestRewardsTransaction(
      inputs: { stakedPositionIds: string[]; walletAddress: string },
  ): Promise<Transaction>

  Builds a version-aware transaction to harvest rewards from multiple positions.

  The reward coin types are derived from nonZeroRewardCoinTypes() and the pool's stake coin type and ID are added automatically.

  Parameters

  • inputs: { stakedPositionIds: string[]; walletAddress: string }

    Position object IDs and the signing wallet address.

  Returns Promise<Transaction>

  An unsigned transaction that can be signed and executed.

  Throws

  An error if no AftermathApi instance was provided.

getIncreaseRewardsEmissionsTransaction

• getIncreaseRewardsEmissionsTransaction(
      inputs: {
          ownerCapId: string;
          rewards: {
              emissionRate: bigint;
              emissionScheduleMs: number;
              rewardCoinType: string;
          }[];
          walletAddress: string;
      },
  ): Promise<Transaction>

  Builds a version-aware transaction to increase emission schedules for reward coins.

  The on-chain contract requires the owner capability and rejects updates that do not increase the configured emissions.

  Parameters

  • inputs: {
        ownerCapId: string;
        rewards: {
            emissionRate: bigint;
            emissionScheduleMs: number;
            rewardCoinType: string;
        }[];
        walletAddress: string;
    }

    Owner capability, reward emission updates, and signing wallet.

  Returns Promise<Transaction>

  An unsigned transaction to be signed by the owner-cap holder.

  Throws

  An error if no AftermathApi instance was provided.

getInitializeRewardTransaction

• getInitializeRewardTransaction(
      inputs: {
          emissionDelayTimestampMs: number;
          emissionRate: bigint;
          emissionScheduleMs: number;
          isSponsoredTx?: boolean;
          rewardAmount: bigint;
          rewardCoinType: string;
          walletAddress: string;
      } & FarmOwnerOrOneTimeAdminCap,
  ): Promise<Transaction>

  Builds a version-aware transaction to initialize a new reward coin in this pool.

  The reward amount and rate are in the reward coin's base units. The schedule and delay timestamps are in milliseconds. V1 and V2 choose different Move entry points, and V2 can consume a one-time admin capability.

  Parameters

  • inputs: {
        emissionDelayTimestampMs: number;
        emissionRate: bigint;
        emissionScheduleMs: number;
        isSponsoredTx?: boolean;
        rewardAmount: bigint;
        rewardCoinType: string;
        walletAddress: string;
    } & FarmOwnerOrOneTimeAdminCap

    Reward amount, emission settings, reward type, authorizing capability, and wallet.

  Returns Promise<Transaction>

  An unsigned transaction for reward initialization.

  Throws

  An error if no AftermathApi instance was provided.

getRemoveRewardsTransaction

• getRemoveRewardsTransaction(
      inputs: {
          ownerCapId: string;
          rewards: { rewardAmount: bigint; rewardCoinType: string }[];
          walletAddress: string;
      },
  ): Transaction

  Builds a transaction to remove (withdraw) undistributed reward coins from the staking pool for one or more reward coin types in a single call.

  Only the pool owner (via ownerCapId) can remove rewards. One-time admin caps are not permitted for removals. This operation reduces the pool’s remaining undistributed reward balances; it does not affect rewards already accrued/claimed by stakers.

  Versioning:

  • V1 → calls buildRemoveStakingPoolRewardTxV1
  • V2 → calls buildRemoveStakingPoolRewardTxV2

  The effective stakingPoolId and stakeCoinType always come from this instance's stakingPool.

  Parameters

  • inputs: {
        ownerCapId: string;
        rewards: { rewardAmount: bigint; rewardCoinType: string }[];
        walletAddress: string;
    }

    Parameters for reward removal.

    • ownerCapId: string

      Object ID of the pool OwnerCap that authorizes the removal.

    • rewards: { rewardAmount: bigint; rewardCoinType: string }[]

      Array of removal entries. Each entry specifies:

      • rewardCoinType: Coin type to withdraw.
      • rewardAmount: Amount to withdraw (base units).

    • walletAddress: string

      Address that will sign/submit the transaction.

  Returns Transaction

  A transaction object ready to sign and execute that removes the specified undistributed rewards for each entry in inputs.rewards.

  Throws

  An error if no AftermathApi instance was provided.

getRewardsTVL

• getRewardsTVL(abortSignal?: AbortSignal): Promise<number>

  Fetches the total value locked (TVL) of the reward coins in this specific staking pool.

  Parameters

  • OptionalabortSignal: AbortSignal

    Optional signal that cancels the API request.

  Returns Promise<number>

  A number representing this pool's reward TVL.

  Example

  const rewardTvl = await someFarmsPool.getRewardsTVL();
  console.log(rewardTvl);
  Copy

getSetMaxLockDurationMsTransaction

• getSetMaxLockDurationMsTransaction(
      inputs: {
          lockDurationMs: bigint;
          ownerCapId: string;
          walletAddress: string;
      },
  ): Transaction

  Builds a V2 transaction to set the pool's maximum lock duration.

  lockDurationMs is in milliseconds. The owner capability must authorize the mutation. V1 pools do not expose this entry point.

  Parameters

  • inputs: { lockDurationMs: bigint; ownerCapId: string; walletAddress: string }

    Owner capability, new duration, and signing wallet.

  Returns Transaction

  An unsigned transaction that can be signed and executed.

  Throws

  Error when this is a V1 pool or no AftermathApi is available.

getSetMinLockDurationMsTransaction

• getSetMinLockDurationMsTransaction(
      inputs: {
          lockDurationMs: bigint;
          ownerCapId: string;
          walletAddress: string;
      },
  ): Transaction

  Builds a V2 transaction to set the pool's minimum lock duration.

  lockDurationMs is in milliseconds. The owner capability must authorize the mutation. V1 pools do not expose this entry point.

  Parameters

  • inputs: { lockDurationMs: bigint; ownerCapId: string; walletAddress: string }

    Owner capability, new duration, and signing wallet.

  Returns Transaction

  An unsigned transaction that can be signed and executed.

  Throws

  Error when this is a V1 pool or no AftermathApi is available.

getStakeTransaction

• getStakeTransaction(
      inputs: {
          isSponsoredTx?: boolean;
          lockDurationMs: number;
          stakeAmount: bigint;
          walletAddress: string;
      },
  ): Promise<Transaction>

  Builds a version-aware transaction to stake tokens into this pool.

  The pool ID and stake coin type come from this.stakingPool. The requested duration is in milliseconds, and the amount is in stake-coin base units. V1 and V2 builders are selected from version().

  Parameters

  • inputs: {
        isSponsoredTx?: boolean;
        lockDurationMs: number;
        stakeAmount: bigint;
        walletAddress: string;
    }

    Principal, lock duration, sender address, and optional sponsorship.

  Returns Promise<Transaction>

  An unsigned transaction that can be signed and executed.

  Throws

  An error if no AftermathApi instance was provided.

  Example

  const tx = await pool.getStakeTransaction({
  	 stakeAmount: 1_000_000n,
  	 lockDurationMs: 604_800_000,
  	 walletAddress: "0x<address>",
  });
  Copy

getTopUpRewardsTransaction

• getTopUpRewardsTransaction(
      inputs: {
          isSponsoredTx?: boolean;
          rewards: { rewardAmount: bigint; rewardCoinType: string }[];
          walletAddress: string;
      } & FarmOwnerOrOneTimeAdminCap,
  ): Promise<Transaction>

  Builds a version-aware transaction to add balances to existing reward coins.

  Each amount is in the corresponding reward coin's base units. The owner or one-time admin capability must authorize the operation.

  Parameters

  • inputs: {
        isSponsoredTx?: boolean;
        rewards: { rewardAmount: bigint; rewardCoinType: string }[];
        walletAddress: string;
    } & FarmOwnerOrOneTimeAdminCap

    Reward top-ups, authorizing capability, and signing wallet.

  Returns Promise<Transaction>

  An unsigned transaction that can be signed and executed.

  Throws

  An error if no AftermathApi instance was provided.

getTVL

• getTVL(abortSignal?: AbortSignal): Promise<number>

  Fetches the total value locked (TVL) for this staking pool alone.

  Parameters

  • OptionalabortSignal: AbortSignal

    Optional signal that cancels the API request.

  Returns Promise<number>

  A number representing this pool's TVL in the API's reporting currency.

  Example

  const poolTvl = await someFarmsPool.getTVL();
  console.log(poolTvl);
  Copy

getUpdateMinStakeAmountTransaction

• getUpdateMinStakeAmountTransaction(
      inputs: {
          minStakeAmount: bigint;
          ownerCapId: string;
          walletAddress: string;
      },
  ): Promise<Transaction>

  Builds a transaction to update the pool's minimum stake amount.

  The amount is in stake-coin base units, and the owner capability must authorize the mutation.

  Parameters

  • inputs: { minStakeAmount: bigint; ownerCapId: string; walletAddress: string }

    New minimum amount, owner capability, and signing wallet.

  Returns Promise<Transaction>

  An unsigned transaction that can be signed and executed.

  Throws

  An error if no AftermathApi instance was provided.

isRelaxedLockEnforcement

• isRelaxedLockEnforcement(): boolean

  Returns whether this pool uses relaxed lock enforcement.

  The on-chain contract permits relaxed-lock principal withdrawals while the position is locked and applies its relaxed-lock reward rules.

  Returns boolean

isStrictLockEnforcement

• isStrictLockEnforcement(): boolean

  Returns whether this pool uses strict lock enforcement.

  A strictly locked position must reach its unlock time, or the pool must be forcibly opened, before principal can be withdrawn.

  Returns boolean

maxLockDurationMs

• maxLockDurationMs(): number

  Computes the maximum lock duration that remains valid in this pool.

  The result is the smaller of the configured maximum and the time until emission ends. It uses Date.now() and returns zero after emissions end.

  Returns number

  The maximum possible lock duration in milliseconds, or 0 if the pool is effectively closed.

nonZeroRewardCoinTypes

• nonZeroRewardCoinTypes(): string[]

  Lists reward coin types that can currently be included in harvest inputs.

  A reward is included only when its actual pool balance is positive and at least one emission amount is available.

  Returns string[]

  An array of eligible CoinType strings.

rewardCoin

• rewardCoin(inputs: { coinType: string }): FarmsStakingPoolRewardCoin

  Retrieves the local record for a specific reward coin type in this pool.

  Parameters

  • inputs: { coinType: string }

    Contains the coinType to look up.

  Returns FarmsStakingPoolRewardCoin

  The matching FarmsStakingPoolRewardCoin record.

  Throws

  Error with "Invalid coin type" when the pool has no matching reward record.

rewardCoinTypes

• rewardCoinTypes(): string[]

  Lists all reward coin types offered by this staking pool.

  Returns string[]

  An array of CoinType strings.

version

• version(): FarmsVersion

  Retrieves the version of this staking pool (1 or 2).

  Returns FarmsVersion