Class StakingController

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

// 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}`);

Hierarchy

BaseController
- StakingController

Index

Methods

getTotalVanaStaked getEntity getEntitiesCount getActiveEntities getStakerPosition getEarnedRewards getMinStakeAmount getActiveStakersCount getBondingPeriod getTotalDistributedRewards getStakerSummary stake getMaxUnstakeAmount computeNewBondingPeriod unstake

Methods

getTotalVanaStaked

getTotalVanaStaked(entityId?: bigint): Promise<bigint>
Gets the total amount of VANA staked in the VanaPool protocol or a specific entity.
Parameters
- OptionalentityId: bigint
  Optional entity ID to get staked amount for a specific entity
Returns Promise<bigint>
The total amount of VANA staked in wei
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).
Example
```
// 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`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:160

getEntity

getEntity(entityId: bigint): Promise<EntityInfo>
Gets information about a specific staking entity.
Parameters
- entityId: bigint
  The ID of the entity to query
Returns Promise<EntityInfo>
The entity information including name, APY, shares, and reward pools
Example
```
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}%`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:195

getEntitiesCount

getEntitiesCount(): Promise<bigint>
Gets the total number of staking entities in the protocol.

Returns Promise<bigint>
The count of entities
Example
```
const count = await vana.staking.getEntitiesCount();
console.log(`Total entities: ${count}`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:224

getActiveEntities

getActiveEntities(): Promise<readonly bigint[]>
Gets the IDs of all active staking entities.

Returns Promise<readonly bigint[]>
Array of active entity IDs
Example
```
const activeIds = await vana.staking.getActiveEntities();
console.log(`Active entities: ${activeIds.join(', ')}`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:240

getStakerPosition

getStakerPosition(
staker: `0x${string}`,
entityId: bigint,
): Promise<StakerEntityInfo>
Gets a staker's position in a specific entity.
Parameters
- staker: `0x${string}`
  The address of the staker
- entityId: bigint
  The ID of the entity
Returns Promise<StakerEntityInfo>
The staker's position information
Example
```
const position = await vana.staking.getStakerPosition(
  '0x742d35...',
  1n
);
console.log(`Shares: ${position.shares}`);
console.log(`Rewards: ${position.realizedRewards}`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:262

getEarnedRewards

getEarnedRewards(staker: `0x${string}`, entityId: bigint): Promise<bigint>
Gets the earned rewards for a staker in an entity.
Parameters
- staker: `0x${string}`
  The address of the staker
- entityId: bigint
  The ID of the entity
Returns Promise<bigint>
The earned rewards amount in wei
Example
```
const rewards = await vana.staking.getEarnedRewards(
  '0x742d35...',
  1n
);
console.log(`Earned: ${Number(rewards) / 1e18} VANA`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:298

getMinStakeAmount

getMinStakeAmount(): Promise<bigint>
Gets the minimum stake amount required to stake.

Returns Promise<bigint>
The minimum stake amount in wei
Example
```
const minStake = await vana.staking.getMinStakeAmount();
console.log(`Minimum stake: ${Number(minStake) / 1e18} VANA`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:314

getActiveStakersCount

getActiveStakersCount(): Promise<bigint>
Gets the count of active stakers in the protocol.

Returns Promise<bigint>
The number of active stakers
Example
```
const count = await vana.staking.getActiveStakersCount();
console.log(`Active stakers: ${count}`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:330

getBondingPeriod

getBondingPeriod(): Promise<bigint>
Gets the bonding period for staking.

Returns Promise<bigint>
The bonding period in seconds
Example
```
const bondingPeriod = await vana.staking.getBondingPeriod();
console.log(`Bonding period: ${bondingPeriod / 86400n} days`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:346

getTotalDistributedRewards

getTotalDistributedRewards(
entityId: bigint,
options?: { subgraphUrl?: string },
): Promise<bigint>
Gets the total distributed rewards for a specific entity from the subgraph.
Parameters
- entityId: bigint
  The ID of the entity to query
- options: { subgraphUrl?: string } = {}
  Optional configuration including custom subgraph URL
Returns Promise<bigint>
The total distributed rewards in wei
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.

Throws
When subgraph URL is not configured or query fails
Example
```
const totalRewards = await vana.staking.getTotalDistributedRewards(1n);
const totalRewardsVana = Number(totalRewards) / 1e18;
console.log(`Total distributed rewards: ${totalRewardsVana.toLocaleString()} VANA`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:374

getStakerSummary

getStakerSummary(
staker: `0x${string}`,
entityId: bigint,
): Promise<StakerEntitySummary>
Gets a comprehensive staking summary for a staker in an entity.
Parameters
- staker: `0x${string}`
  The address of the staker
- entityId: bigint
  The ID of the entity
Returns Promise<StakerEntitySummary>
A comprehensive summary of the staker's position
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
Example
```
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`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:461

stake

stake(
    params: {
        entityId: bigint;
        amount: string | bigint;
        recipient?: `0x${string}`;
        minShares?: bigint;
    },
    options?: TransactionOptions,
): Promise<`0x${string}`>
Stakes VANA to an entity in the VanaPool protocol.
Parameters
- params: {
      entityId: bigint;
      amount: string | bigint;
      recipient?: `0x${string}`;
      minShares?: bigint;
  }
  The staking parameters
  - entityId: bigint
    The ID of the entity to stake to
  - amount: string | bigint
    The amount of VANA to stake (in wei, or as a string like "1.5" for 1.5 VANA)
  - Optionalrecipient?: `0x${string}`
    Optional recipient address for the shares (defaults to the sender)
  - OptionalminShares?: bigint
    Optional minimum shares to receive (slippage protection, defaults to 0)
- Optionaloptions: TransactionOptions
Returns Promise<`0x${string}`>
The transaction hash
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.

Throws
When wallet client is not configured
Example
```
// 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
});
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:592

getMaxUnstakeAmount

getMaxUnstakeAmount(
    staker: `0x${string}`,
    entityId: bigint,
): Promise<
    {
        maxVana: bigint;
        maxShares: bigint;
        limitingFactor: number;
        isInBondingPeriod: boolean;
    },
>
Gets the maximum amount of VANA that can be unstaked in a single transaction.
Parameters
- staker: `0x${string}`
  The address of the staker
- entityId: bigint
  The ID of the entity
Returns Promise<
    {
        maxVana: bigint;
        maxShares: bigint;
        limitingFactor: number;
        isInBondingPeriod: boolean;
    },
>
Object containing maxVana, maxShares, limitingFactor, and isInBondingPeriod
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
Example
```
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}`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:665

computeNewBondingPeriod

computeNewBondingPeriod(
    params: { staker: `0x${string}`; entityId: bigint; stakeAmount: bigint },
): Promise<
    {
        newEligibilityTimestamp: bigint;
        newRemainingBondingTime: bigint;
        currentEligibilityTimestamp: bigint;
        currentRemainingBondingTime: bigint;
        currentShares: bigint;
        estimatedNewShares: bigint;
        totalSharesAfter: bigint;
        bondingPeriodDuration: bigint;
        currentTimestamp: bigint;
    },
>
Computes the new bonding period end timestamp after adding stake.
Parameters
- params: { staker: `0x${string}`; entityId: bigint; stakeAmount: bigint }
  The parameters for computing the new bonding period
  - staker: `0x${string}`
    The address of the staker
  - entityId: bigint
    The ID of the entity
  - stakeAmount: bigint
    The amount of VANA to stake (in wei)
Returns Promise<
    {
        newEligibilityTimestamp: bigint;
        newRemainingBondingTime: bigint;
        currentEligibilityTimestamp: bigint;
        currentRemainingBondingTime: bigint;
        currentShares: bigint;
        estimatedNewShares: bigint;
        totalSharesAfter: bigint;
        bondingPeriodDuration: bigint;
        currentTimestamp: bigint;
    },
>
Object containing the new eligibility timestamp and related info
Remarks
When a staker adds more stake to an existing position, the reward eligibility timestamp is recalculated as a weighted average of the existing and new positions. This function allows you to preview what the new eligibility timestamp would be without executing the stake transaction.

The formula used (matching the contract):
```
newEligibility = (existingShares * existingEligibility + newShares * newEligibility) / totalShares
```
Where newEligibility for the incoming stake is currentTimestamp + bondingPeriod.
Example
```
// Preview bonding period after staking 100 VANA
const preview = await vana.staking.computeNewBondingPeriod({
  staker: '0x742d35...',
  entityId: 1n,
  stakeAmount: parseEther("100"),
});
console.log(`New eligibility: ${new Date(Number(preview.newEligibilityTimestamp) * 1000)}`);
console.log(`Remaining bonding time: ${Number(preview.newRemainingBondingTime) / 86400} days`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:723

unstake

unstake(
    params: {
        entityId: bigint;
        amount: string | bigint;
        maxShares?: bigint;
    },
    options?: TransactionOptions,
): Promise<`0x${string}`>
Unstakes VANA from an entity in the VanaPool protocol.
Parameters
- params: { entityId: bigint; amount: string | bigint; maxShares?: bigint }
  The unstaking parameters
  - entityId: bigint
    The ID of the entity to unstake from
  - amount: string | bigint
    The amount of VANA to unstake (in wei, or as a string like "1.5" for 1.5 VANA)
  - OptionalmaxShares?: bigint
    Maximum shares to burn for slippage protection (defaults to 0, no protection)
- Optionaloptions: TransactionOptions
Returns Promise<`0x${string}`>
The transaction hash
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.
Throws
When wallet client is not configured
Example
```
// 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}`);
```
- Defined in packages/vana-sdk/src/controllers/staking.ts:889

Class StakingController

Remarks

Example

Hierarchy

Index

Methods

Methods

getTotalVanaStaked

Parameters

Returns Promise<bigint>

Remarks

Example

getEntity

Parameters

Returns Promise<EntityInfo>

Example

getEntitiesCount

Returns Promise<bigint>

Example

getActiveEntities

Returns Promise<readonly bigint[]>

Example

getStakerPosition

Parameters

Returns Promise<StakerEntityInfo>

Example

getEarnedRewards

Parameters

Returns Promise<bigint>

Example

getMinStakeAmount

Returns Promise<bigint>

Example

getActiveStakersCount

Returns Promise<bigint>

Example

getBondingPeriod

Returns Promise<bigint>

Example

getTotalDistributedRewards

Parameters

Returns Promise<bigint>

Remarks

Throws

Example

getStakerSummary

Parameters

Returns Promise<StakerEntitySummary>

Remarks

Example

stake

Parameters

entityId: bigint

amount: string | bigint

Optionalrecipient?: `0x${string}`

OptionalminShares?: bigint

Returns Promise<`0x${string}`>

Remarks

Throws

Example

getMaxUnstakeAmount

Parameters

Returns Promise< { maxVana: bigint; maxShares: bigint; limitingFactor: number; isInBondingPeriod: boolean; },>

Remarks

Example

computeNewBondingPeriod

Parameters

staker: `0x${string}`

entityId: bigint

stakeAmount: bigint

Returns Promise< { newEligibilityTimestamp: bigint; newRemainingBondingTime: bigint; currentEligibilityTimestamp: bigint; currentRemainingBondingTime: bigint; currentShares: bigint; estimatedNewShares: bigint; totalSharesAfter: bigint; bondingPeriodDuration: bigint; currentTimestamp: bigint; },>

Remarks

Example

unstake

Parameters

entityId: bigint

amount: string | bigint

OptionalmaxShares?: bigint

Returns Promise<`0x${string}`>

Remarks

`Optional`recipient?: `0x${string}`

`Optional`minShares?: bigint

Returns Promise<
{
maxVana: bigint;
maxShares: bigint;
limitingFactor: number;
isInBondingPeriod: boolean;
},
>

Returns Promise<
{
newEligibilityTimestamp: bigint;
newRemainingBondingTime: bigint;
currentEligibilityTimestamp: bigint;
currentRemainingBondingTime: bigint;
currentShares: bigint;
estimatedNewShares: bigint;
totalSharesAfter: bigint;
bondingPeriodDuration: bigint;
currentTimestamp: bigint;
},
>

`Optional`maxShares?: bigint