@opendatalabs/vana-sdk 2.2.2 → 2.2.3-canary.5d4d0b4

package/dist/controllers/staking.d.ts

@@ -0,0 +1,404 @@
+/**
+ * Provides staking functionality for the VanaPool protocol.
+ *
+ * @remarks
+ * This controller handles interactions with VanaPool staking contracts,
+ * allowing users to query staking information such as total VANA staked,
+ * entity information, and staker positions.
+ *
+ * @category Controllers
+ * @module StakingController
+ */
+import type { ControllerContext } from "../types/controller-context";
+import type { TransactionOptions } from "../types/operations";
+import { BaseController } from "./base";
+import type { Address, Hash } from "viem";
+/**
+ * Information about a staking entity in the VanaPool protocol.
+ */
+export interface EntityInfo {
+    entityId: bigint;
+    ownerAddress: Address;
+    status: number;
+    name: string;
+    maxAPY: bigint;
+    lockedRewardPool: bigint;
+    activeRewardPool: bigint;
+    totalShares: bigint;
+    lastUpdateTimestamp: bigint;
+}
+/**
+ * Information about a staker's position in an entity.
+ */
+export interface StakerEntityInfo {
+    shares: bigint;
+    costBasis: bigint;
+    rewardEligibilityTimestamp: bigint;
+    realizedRewards: bigint;
+    vestedRewards: bigint;
+}
+/**
+ * Comprehensive staking summary for a staker in an entity.
+ */
+export interface StakerEntitySummary {
+    /** Number of shares owned by the staker */
+    shares: bigint;
+    /** Cost basis - the original VANA amount staked */
+    costBasis: bigint;
+    /** Current value of the staker's shares in VANA */
+    currentValue: bigint;
+    /** Timestamp when rewards become eligible */
+    rewardEligibilityTimestamp: bigint;
+    /** Remaining bonding time in seconds (0 if bonding period has passed) */
+    remainingBondingTime: bigint;
+    /** Whether the staker is still in the bonding period */
+    isInBondingPeriod: boolean;
+    /** Vested rewards that can be claimed without penalty */
+    vestedRewards: bigint;
+    /** Unvested rewards (pending interest = currentValue - costBasis) */
+    unvestedRewards: bigint;
+    /** Realized/withdrawn rewards (already claimed) */
+    realizedRewards: bigint;
+    /** Total earned rewards (includes vested, unvested, and realized) */
+    earnedRewards: bigint;
+}
+/**
+ * Controller for VanaPool staking operations.
+ *
+ * @remarks
+ * Provides methods to query staking information from the VanaPool contracts.
+ * This includes total VANA staked across the protocol, entity information,
+ * and individual staker positions.
+ *
+ * @example
+ * ```typescript
+ * // Get total VANA staked in the protocol
+ * const totalStaked = await vana.staking.getTotalVanaStaked();
+ * console.log(`Total staked: ${totalStaked} wei`);
+ *
+ * // Get entity information
+ * const entity = await vana.staking.getEntity(1n);
+ * console.log(`Entity name: ${entity.name}`);
+ * ```
+ *
+ * @category Controllers
+ */
+export declare class StakingController extends BaseController {
+    constructor(context: ControllerContext);
+    /**
+     * Gets the chain ID from context.
+     */
+    private getChainId;
+    /**
+     * Gets the VanaPoolEntity contract instance.
+     */
+    private getEntityContract;
+    /**
+     * Gets the VanaPoolStaking contract instance.
+     */
+    private getStakingContract;
+    /**
+     * Gets the total amount of VANA staked in the VanaPool protocol or a specific entity.
+     *
+     * @remarks
+     * When called without an entityId, this retrieves the sum of activeRewardPool
+     * across all active entities in the VanaPool protocol.
+     * When called with an entityId, this returns the activeRewardPool for that specific entity.
+     * The value is returned in wei (10^18 = 1 VANA).
+     *
+     * @param entityId - Optional entity ID to get staked amount for a specific entity
+     * @returns The total amount of VANA staked in wei
+     *
+     * @example
+     * ```typescript
+     * // Get total staked across all entities
+     * const totalStaked = await vana.staking.getTotalVanaStaked();
+     * console.log(`Total staked: ${Number(totalStaked) / 1e18} VANA`);
+     *
+     * // Get staked amount for a specific entity
+     * const entityStaked = await vana.staking.getTotalVanaStaked(1n);
+     * console.log(`Entity 1 staked: ${Number(entityStaked) / 1e18} VANA`);
+     * ```
+     */
+    getTotalVanaStaked(entityId?: bigint): Promise<bigint>;
+    /**
+     * Gets information about a specific staking entity.
+     *
+     * @param entityId - The ID of the entity to query
+     * @returns The entity information including name, APY, shares, and reward pools
+     *
+     * @example
+     * ```typescript
+     * const entity = await vana.staking.getEntity(1n);
+     * console.log(`Entity: ${entity.name}`);
+     * console.log(`Total shares: ${entity.totalShares}`);
+     * console.log(`Max APY: ${Number(entity.maxAPY) / 100}%`);
+     * ```
+     */
+    getEntity(entityId: bigint): Promise<EntityInfo>;
+    /**
+     * Gets the total number of staking entities in the protocol.
+     *
+     * @returns The count of entities
+     *
+     * @example
+     * ```typescript
+     * const count = await vana.staking.getEntitiesCount();
+     * console.log(`Total entities: ${count}`);
+     * ```
+     */
+    getEntitiesCount(): Promise<bigint>;
+    /**
+     * Gets the IDs of all active staking entities.
+     *
+     * @returns Array of active entity IDs
+     *
+     * @example
+     * ```typescript
+     * const activeIds = await vana.staking.getActiveEntities();
+     * console.log(`Active entities: ${activeIds.join(', ')}`);
+     * ```
+     */
+    getActiveEntities(): Promise<readonly bigint[]>;
+    /**
+     * Gets a staker's position in a specific entity.
+     *
+     * @param staker - The address of the staker
+     * @param entityId - The ID of the entity
+     * @returns The staker's position information
+     *
+     * @example
+     * ```typescript
+     * const position = await vana.staking.getStakerPosition(
+     *   '0x742d35...',
+     *   1n
+     * );
+     * console.log(`Shares: ${position.shares}`);
+     * console.log(`Rewards: ${position.realizedRewards}`);
+     * ```
+     */
+    getStakerPosition(staker: Address, entityId: bigint): Promise<StakerEntityInfo>;
+    /**
+     * Gets the earned rewards for a staker in an entity.
+     *
+     * @param staker - The address of the staker
+     * @param entityId - The ID of the entity
+     * @returns The earned rewards amount in wei
+     *
+     * @example
+     * ```typescript
+     * const rewards = await vana.staking.getEarnedRewards(
+     *   '0x742d35...',
+     *   1n
+     * );
+     * console.log(`Earned: ${Number(rewards) / 1e18} VANA`);
+     * ```
+     */
+    getEarnedRewards(staker: Address, entityId: bigint): Promise<bigint>;
+    /**
+     * Gets the minimum stake amount required to stake.
+     *
+     * @returns The minimum stake amount in wei
+     *
+     * @example
+     * ```typescript
+     * const minStake = await vana.staking.getMinStakeAmount();
+     * console.log(`Minimum stake: ${Number(minStake) / 1e18} VANA`);
+     * ```
+     */
+    getMinStakeAmount(): Promise<bigint>;
+    /**
+     * Gets the count of active stakers in the protocol.
+     *
+     * @returns The number of active stakers
+     *
+     * @example
+     * ```typescript
+     * const count = await vana.staking.getActiveStakersCount();
+     * console.log(`Active stakers: ${count}`);
+     * ```
+     */
+    getActiveStakersCount(): Promise<bigint>;
+    /**
+     * Gets the bonding period for staking.
+     *
+     * @returns The bonding period in seconds
+     *
+     * @example
+     * ```typescript
+     * const bondingPeriod = await vana.staking.getBondingPeriod();
+     * console.log(`Bonding period: ${bondingPeriod / 86400n} days`);
+     * ```
+     */
+    getBondingPeriod(): Promise<bigint>;
+    /**
+     * Gets the total distributed rewards for a specific entity from the subgraph.
+     *
+     * @remarks
+     * This queries the VanaPool subgraph to retrieve the cumulative `totalDistributedRewards`
+     * for a staking entity. This value represents the sum of all rewards that have been
+     * processed (moved from lockedRewardPool to activeRewardPool) minus any forfeited
+     * rewards that were returned.
+     *
+     * Requires a configured `subgraphUrl` in the Vana constructor options.
+     *
+     * @param entityId - The ID of the entity to query
+     * @param options - Optional configuration including custom subgraph URL
+     * @returns The total distributed rewards in wei
+     * @throws {BlockchainError} When subgraph URL is not configured or query fails
+     *
+     * @example
+     * ```typescript
+     * const totalRewards = await vana.staking.getTotalDistributedRewards(1n);
+     * const totalRewardsVana = Number(totalRewards) / 1e18;
+     * console.log(`Total distributed rewards: ${totalRewardsVana.toLocaleString()} VANA`);
+     * ```
+     */
+    getTotalDistributedRewards(entityId: bigint, options?: {
+        subgraphUrl?: string;
+    }): Promise<bigint>;
+    /**
+     * Gets a comprehensive staking summary for a staker in an entity.
+     *
+     * @remarks
+     * This method aggregates all relevant staking information for a staker in a single call,
+     * including staked amount, current value, bonding status, and all reward types.
+     *
+     * Reward breakdown:
+     * - `earnedRewards` = pendingInterest + vestedRewards + realizedRewards
+     * - `pendingInterest` = currentValue - costBasis (unvested appreciation)
+     * - `vestedRewards` = rewards that have vested but not yet withdrawn
+     * - `realizedRewards` = rewards already withdrawn during unstakes
+     *
+     * @param staker - The address of the staker
+     * @param entityId - The ID of the entity
+     * @returns A comprehensive summary of the staker's position
+     *
+     * @example
+     * ```typescript
+     * const summary = await vana.staking.getStakerSummary('0x742d35...', 1n);
+     * console.log(`Total staked: ${Number(summary.totalStaked) / 1e18} VANA`);
+     * console.log(`Current value: ${Number(summary.currentValue) / 1e18} VANA`);
+     * console.log(`In bonding period: ${summary.isInBondingPeriod}`);
+     * console.log(`Remaining bonding time: ${Number(summary.remainingBondingTime) / 86400} days`);
+     * console.log(`Vested rewards: ${Number(summary.vestedRewards) / 1e18} VANA`);
+     * console.log(`Unvested rewards: ${Number(summary.unvestedRewards) / 1e18} VANA`);
+     * console.log(`Realized rewards: ${Number(summary.realizedRewards) / 1e18} VANA`);
+     * console.log(`Total earned: ${Number(summary.earnedRewards) / 1e18} VANA`);
+     * ```
+     */
+    getStakerSummary(staker: Address, entityId: bigint): Promise<StakerEntitySummary>;
+    /**
+     * Stakes VANA to an entity in the VanaPool protocol.
+     *
+     * @remarks
+     * This method stakes native VANA tokens to a specified entity. The staker will receive
+     * shares in proportion to their stake amount. A bonding period applies during which
+     * rewards cannot be fully claimed without penalty.
+     *
+     * Requires a wallet client to be configured in the Vana constructor.
+     *
+     * @param params - The staking parameters
+     * @param params.entityId - The ID of the entity to stake to
+     * @param params.amount - The amount of VANA to stake (in wei, or as a string like "1.5" for 1.5 VANA)
+     * @param params.recipient - Optional recipient address for the shares (defaults to the sender)
+     * @param params.minShares - Optional minimum shares to receive (slippage protection, defaults to 0)
+     * @returns The transaction hash
+     * @throws {BlockchainError} When wallet client is not configured
+     *
+     * @example
+     * ```typescript
+     * // Stake 100 VANA to entity 1
+     * const txHash = await vana.staking.stake({
+     *   entityId: 1n,
+     *   amount: "100", // 100 VANA
+     * });
+     * console.log(`Staked! Transaction: ${txHash}`);
+     *
+     * // Stake with slippage protection
+     * const txHash2 = await vana.staking.stake({
+     *   entityId: 1n,
+     *   amount: parseEther("50"), // 50 VANA in wei
+     *   minShares: parseEther("49"), // Expect at least 49 shares
+     * });
+     * ```
+     */
+    stake(params: {
+        entityId: bigint;
+        amount: bigint | string;
+        recipient?: Address;
+        minShares?: bigint;
+    }, options?: TransactionOptions): Promise<Hash>;
+    /**
+     * Gets the maximum amount of VANA that can be unstaked in a single transaction.
+     *
+     * @remarks
+     * This calls the contract's getMaxUnstakeAmount which returns the minimum of:
+     * 1. The withdrawable VANA (costBasis if in bonding period, shareValue if eligible)
+     * 2. The entity's activeRewardPool (what the entity has available)
+     * 3. The treasury balance (what can be paid out)
+     *
+     * The limiting factor indicates what's constraining the unstake:
+     * - 0 = user shares/costBasis
+     * - 1 = activeRewardPool
+     * - 2 = treasury
+     *
+     * @param staker - The address of the staker
+     * @param entityId - The ID of the entity
+     * @returns Object containing maxVana, maxShares, limitingFactor, and isInBondingPeriod
+     *
+     * @example
+     * ```typescript
+     * const result = await vana.staking.getMaxUnstakeAmount('0x742d35...', 1n);
+     * console.log(`Max unstake: ${Number(result.maxVana) / 1e18} VANA`);
+     * console.log(`Max shares: ${result.maxShares}`);
+     * console.log(`In bonding period: ${result.isInBondingPeriod}`);
+     * ```
+     */
+    getMaxUnstakeAmount(staker: Address, entityId: bigint): Promise<{
+        maxVana: bigint;
+        maxShares: bigint;
+        limitingFactor: number;
+        isInBondingPeriod: boolean;
+    }>;
+    /**
+     * Unstakes VANA from an entity in the VanaPool protocol.
+     *
+     * @remarks
+     * This method unstakes native VANA tokens from a specified entity. The amount
+     * that can be unstaked depends on whether the staker is in the bonding period:
+     *
+     * - **During bonding period**: Only cost basis can be withdrawn; rewards are forfeited
+     * - **After bonding period**: Full current value (cost basis + rewards) can be withdrawn
+     *
+     * Use `getMaxUnstakeAmount` to determine the maximum amount that can be unstaked.
+     *
+     * Requires a wallet client to be configured in the Vana constructor.
+     *
+     * @param params - The unstaking parameters
+     * @param params.entityId - The ID of the entity to unstake from
+     * @param params.amount - The amount of VANA to unstake (in wei, or as a string like "1.5" for 1.5 VANA)
+     * @param params.maxShares - Maximum shares to burn for slippage protection (defaults to 0, no protection)
+     * @returns The transaction hash
+     * @throws {BlockchainError} When wallet client is not configured
+     *
+     * @example
+     * ```typescript
+     * // Get max unstake amount first
+     * const maxUnstake = await vana.staking.getMaxUnstakeAmount(address, 1n);
+     *
+     * // Unstake the maximum amount with slippage protection
+     * const txHash = await vana.staking.unstake({
+     *   entityId: 1n,
+     *   amount: maxUnstake.maxVana,
+     *   maxShares: maxUnstake.maxShares,
+     * });
+     * console.log(`Unstaked! Transaction: ${txHash}`);
+     * ```
+     */
+    unstake(params: {
+        entityId: bigint;
+        amount: bigint | string;
+        maxShares?: bigint;
+    }, options?: TransactionOptions): Promise<Hash>;
+}