Module 0x3::staking_pool
- Resource
StakingPool
- Struct
PoolTokenExchangeRate
- Resource
StakedSui
- Constants
- Function
new
- Function
request_add_stake
- Function
request_withdraw_stake
- Function
withdraw_from_principal
- Function
unwrap_staked_sui
- Function
deposit_rewards
- Function
process_pending_stakes_and_withdraws
- Function
process_pending_stake_withdraw
- Function
process_pending_stake
- Function
withdraw_rewards
- Function
activate_staking_pool
- Function
deactivate_staking_pool
- Function
sui_balance
- Function
pool_id
- Function
staked_sui_amount
- Function
stake_activation_epoch
- Function
is_preactive
- Function
is_inactive
- Function
split
- Function
split_staked_sui
- Function
join_staked_sui
- Function
is_equal_staking_metadata
- Function
pool_token_exchange_rate_at_epoch
- Function
pending_stake_amount
- Function
pending_stake_withdraw_amount
- Function
exchange_rates
- Function
sui_amount
- Function
pool_token_amount
- Function
is_preactive_at_epoch
- Function
get_sui_amount
- Function
get_token_amount
- Function
initial_exchange_rate
- Function
check_balance_invariants
use 0x1::option;
use 0x1::u64;
use 0x2::bag;
use 0x2::balance;
use 0x2::object;
use 0x2::sui;
use 0x2::table;
use 0x2::transfer;
use 0x2::tx_context;
Resource StakingPool
A staking pool embedded in each validator struct in the system state object.
struct StakingPool has store, key
Fields
Struct PoolTokenExchangeRate
Struct representing the exchange rate of the stake pool token to SUI.
struct PoolTokenExchangeRate has copy, drop, store
Fields
Resource StakedSui
A self-custodial object holding the staked SUI tokens.
struct StakedSui has store, key
Fields
Constants
const EActivationOfInactivePool: u64 = 16;
const EDeactivationOfInactivePool: u64 = 11;
const EDelegationOfZeroSui: u64 = 17;
const EDelegationToInactivePool: u64 = 10;
const EDestroyNonzeroBalance: u64 = 5;
const EIncompatibleStakedSui: u64 = 12;
const EInsufficientPoolTokenBalance: u64 = 0;
const EInsufficientRewardsPoolBalance: u64 = 4;
const EInsufficientSuiTokenBalance: u64 = 3;
const EPendingDelegationDoesNotExist: u64 = 8;
const EPoolAlreadyActive: u64 = 14;
const EPoolNotPreactive: u64 = 15;
const EStakedSuiBelowThreshold: u64 = 18;
const ETokenBalancesDoNotMatchExchangeRate: u64 = 9;
const ETokenTimeLockIsSome: u64 = 6;
const EWithdrawAmountCannotBeZero: u64 = 2;
const EWithdrawalInSameEpoch: u64 = 13;
const EWrongDelegation: u64 = 7;
const EWrongPool: u64 = 1;
StakedSui objects cannot be split to below this amount.
const MIN_STAKING_THRESHOLD: u64 = 1000000000;
Function new
Create a new, empty staking pool.
public(friend) fun new(ctx: &mut tx_context::TxContext): staking_pool::StakingPool
Implementation
Function request_add_stake
Request to stake to a staking pool. The stake starts counting at the beginning of the next epoch,
public(friend) fun request_add_stake(pool: &mut staking_pool::StakingPool, stake: balance::Balance<sui::SUI>, stake_activation_epoch: u64, ctx: &mut tx_context::TxContext): staking_pool::StakedSui
Implementation
Function request_withdraw_stake
Request to withdraw the given stake plus rewards from a staking pool. Both the principal and corresponding rewards in SUI are withdrawn. A proportional amount of pool token withdraw is recorded and processed at epoch change time.
public(friend) fun request_withdraw_stake(pool: &mut staking_pool::StakingPool, staked_sui: staking_pool::StakedSui, ctx: &tx_context::TxContext): balance::Balance<sui::SUI>
Implementation
Function withdraw_from_principal
Withdraw the principal SUI stored in the StakedSui object, and calculate the corresponding amount of pool tokens using exchange rate at staking epoch. Returns values are amount of pool tokens withdrawn and withdrawn principal portion of SUI.
public(friend) fun withdraw_from_principal(pool: &staking_pool::StakingPool, staked_sui: staking_pool::StakedSui): (u64, balance::Balance<sui::SUI>)
Implementation
Function unwrap_staked_sui
fun unwrap_staked_sui(staked_sui: staking_pool::StakedSui): balance::Balance<sui::SUI>
Implementation
Function deposit_rewards
Called at epoch advancement times to add rewards (in SUI) to the staking pool.
public(friend) fun deposit_rewards(pool: &mut staking_pool::StakingPool, rewards: balance::Balance<sui::SUI>)
Implementation
Function process_pending_stakes_and_withdraws
public(friend) fun process_pending_stakes_and_withdraws(pool: &mut staking_pool::StakingPool, ctx: &tx_context::TxContext)
Implementation
Function process_pending_stake_withdraw
Called at epoch boundaries to process pending stake withdraws requested during the epoch. Also called immediately upon withdrawal if the pool is inactive.
fun process_pending_stake_withdraw(pool: &mut staking_pool::StakingPool)
Implementation
Function process_pending_stake
Called at epoch boundaries to process the pending stake.
public(friend) fun process_pending_stake(pool: &mut staking_pool::StakingPool)
Implementation
Function withdraw_rewards
This function does the following:
- Calculates the total amount of SUI (including principal and rewards) that the provided pool tokens represent at the current exchange rate.
- Using the above number and the given principal_withdraw_amount, calculates the rewards portion of the stake we should withdraw.
- Withdraws the rewards portion from the rewards pool at the current exchange rate. We only withdraw the rewards portion because the principal portion was already taken out of the staker's self custodied StakedSui.
fun withdraw_rewards(pool: &mut staking_pool::StakingPool, principal_withdraw_amount: u64, pool_token_withdraw_amount: u64, epoch: u64): balance::Balance<sui::SUI>
Implementation
Function activate_staking_pool
Called by validator module to activate a staking pool.
public(friend) fun activate_staking_pool(pool: &mut staking_pool::StakingPool, activation_epoch: u64)
Implementation
Function deactivate_staking_pool
Deactivate a staking pool by setting the deactivation_epoch. After this pool deactivation, the pool stops earning rewards. Only stake withdraws can be made to the pool.
public(friend) fun deactivate_staking_pool(pool: &mut staking_pool::StakingPool, deactivation_epoch: u64)
Implementation
Function sui_balance
public fun sui_balance(pool: &staking_pool::StakingPool): u64
Implementation
Function pool_id
public fun pool_id(staked_sui: &staking_pool::StakedSui): object::ID
Implementation
Function staked_sui_amount
public fun staked_sui_amount(staked_sui: &staking_pool::StakedSui): u64
Implementation
Function stake_activation_epoch
public fun stake_activation_epoch(staked_sui: &staking_pool::StakedSui): u64
Implementation
Function is_preactive
Returns true if the input staking pool is preactive.
public fun is_preactive(pool: &staking_pool::StakingPool): bool
Implementation
Function is_inactive
Returns true if the input staking pool is inactive.
public fun is_inactive(pool: &staking_pool::StakingPool): bool
Implementation
Function split
Split StakedSui self to two parts, one with principal split_amount, and the remaining principal is left in self. All the other parameters of the StakedSui like stake_activation_epoch or pool_id remain the same.
public fun split(self: &mut staking_pool::StakedSui, split_amount: u64, ctx: &mut tx_context::TxContext): staking_pool::StakedSui
Implementation
Function split_staked_sui
Split the given StakedSui to the two parts, one with principal split_amount, transfer the newly split part to the sender address.
public entry fun split_staked_sui(stake: &mut staking_pool::StakedSui, split_amount: u64, ctx: &mut tx_context::TxContext)
Implementation
Function join_staked_sui
Consume the staked sui other and add its value to self. Aborts if some of the staking parameters are incompatible (pool id, stake activation epoch, etc.)
public entry fun join_staked_sui(self: &mut staking_pool::StakedSui, other: staking_pool::StakedSui)
Implementation
Function is_equal_staking_metadata
Returns true if all the staking parameters of the staked sui except the principal are identical
public fun is_equal_staking_metadata(self: &staking_pool::StakedSui, other: &staking_pool::StakedSui): bool
Implementation
Function pool_token_exchange_rate_at_epoch
public fun pool_token_exchange_rate_at_epoch(pool: &staking_pool::StakingPool, epoch: u64): staking_pool::PoolTokenExchangeRate
Implementation
Function pending_stake_amount
Returns the total value of the pending staking requests for this staking pool.
public fun pending_stake_amount(staking_pool: &staking_pool::StakingPool): u64
Implementation
Function pending_stake_withdraw_amount
Returns the total withdrawal from the staking pool this epoch.
public fun pending_stake_withdraw_amount(staking_pool: &staking_pool::StakingPool): u64
Implementation
Function exchange_rates
public(friend) fun exchange_rates(pool: &staking_pool::StakingPool): &table::Table<u64, staking_pool::PoolTokenExchangeRate>
Implementation
Function sui_amount
public fun sui_amount(exchange_rate: &staking_pool::PoolTokenExchangeRate): u64
Implementation
Function pool_token_amount
public fun pool_token_amount(exchange_rate: &staking_pool::PoolTokenExchangeRate): u64
Implementation
Function is_preactive_at_epoch
Returns true if the provided staking pool is preactive at the provided epoch.
fun is_preactive_at_epoch(pool: &staking_pool::StakingPool, epoch: u64): bool
Implementation
Function get_sui_amount
fun get_sui_amount(exchange_rate: &staking_pool::PoolTokenExchangeRate, token_amount: u64): u64
Implementation
Function get_token_amount
fun get_token_amount(exchange_rate: &staking_pool::PoolTokenExchangeRate, sui_amount: u64): u64
Implementation
Function initial_exchange_rate
fun initial_exchange_rate(): staking_pool::PoolTokenExchangeRate
Implementation
Function check_balance_invariants
fun check_balance_invariants(pool: &staking_pool::StakingPool, epoch: u64)