Skip to main content

Module sui_system::staking_pool

use std::address;
use std::ascii;
use std::bcs;
use std::internal;
use std::option;
use std::string;
use std::type_name;
use std::u128;
use std::u64;
use std::vector;
use sui::accumulator;
use sui::accumulator_settlement;
use sui::address;
use sui::bag;
use sui::balance;
use sui::bcs;
use sui::coin;
use sui::config;
use sui::deny_list;
use sui::dynamic_field;
use sui::dynamic_object_field;
use sui::event;
use sui::funds_accumulator;
use sui::hash;
use sui::hex;
use sui::object;
use sui::party;
use sui::protocol_config;
use sui::sui;
use sui::table;
use sui::transfer;
use sui::tx_context;
use sui::types;
use sui::url;
use sui::vec_map;
use sui::vec_set;

Struct StakingPool​

A staking pool embedded in each validator struct in the system state object.

public struct StakingPool has key, store
Click to open
Fields
id: sui::object::UID
activation_epoch: std::option::Option<u64>
The epoch at which this pool became active.
The value is None if the pool is pre-active and Some(<epoch_number>) if active or inactive.
deactivation_epoch: std::option::Option<u64>
The epoch at which this staking pool ceased to be active. None = {pre-active, active}, Some(<epoch_number>) if in-active, and it was de-activated at epoch <epoch_number>.
sui_balance: u64
The total number of SUI tokens in this pool, including the SUI in the rewards_pool, as well as in all the principal in the StakedSui object, updated at epoch boundaries.
rewards_pool: sui::balance::Balance<sui::sui::SUI>
The epoch stake rewards will be added here at the end of each epoch.
pool_token_balance: u64
Total number of pool tokens issued by the pool.
exchange_rates: sui::table::Table<u64, sui_system::staking_pool::PoolTokenExchangeRate>
Exchange rate history of previous epochs. Key is the epoch number.
The entries start from the activation_epoch of this pool and contains exchange rates at the beginning of each epoch, i.e., right after the rewards for the previous epoch have been deposited into the pool.
pending_stake: u64
Pending stake amount for this epoch, emptied at epoch boundaries.
pending_total_sui_withdraw: u64
Pending stake withdrawn during the current epoch, emptied at epoch boundaries.
This includes both the principal and rewards SUI withdrawn.
pending_pool_token_withdraw: u64
Pending pool token withdrawn during the current epoch, emptied at epoch boundaries.
extra_fields: sui::bag::Bag
Any extra fields that's not defined statically.

Struct PoolTokenExchangeRate​

Struct representing the exchange rate of the stake pool token to SUI.

public struct PoolTokenExchangeRate has copy, drop, store
Click to open
Fields

Struct StakedSui​

A self-custodial object holding the staked SUI tokens.

public struct StakedSui has key, store
Click to open
Fields
id: sui::object::UID
pool_id: sui::object::ID
ID of the staking pool we are staking with.
stake_activation_epoch: u64
The epoch at which the stake becomes active.
principal: sui::balance::Balance<sui::sui::SUI>
The staked SUI tokens.

Struct FungibleStakedSui​

An alternative to StakedSui that holds the pool token amount instead of the SUI balance.
StakedSui objects can be converted to FungibleStakedSuis after the initial warmup period.
The advantage of this is that you can now merge multiple StakedSui objects from different activation epochs into a single FungibleStakedSui object.

public struct FungibleStakedSui has key, store
Click to open
Fields
id: sui::object::UID
pool_id: sui::object::ID
ID of the staking pool we are staking with.
value: u64
The pool token amount.

Struct FungibleStakedSuiData​

Holds useful information

public struct FungibleStakedSuiData has key, store
Click to open
Fields
id: sui::object::UID
total_supply: u64
fungible_staked_sui supply
principal: sui::balance::Balance<sui::sui::SUI>
principal balance. Rewards are withdrawn from the reward pool

Struct FungibleStakedSuiDataKey​

public struct FungibleStakedSuiDataKey has copy, drop, store

Struct UnderflowSuiBalance​

Holds the amount of SUI that was underflowed when withdrawing from the pool post safe mode. Cleaned up in the same transaction.

public struct UnderflowSuiBalance has copy, drop, store

Constants​

StakedSui objects cannot be split to below this amount.

const MIN_STAKING_THRESHOLD: u64 = 1000000000;

const EInsufficientPoolTokenBalance: u64 = 0;

const EWrongPool: u64 = 1;

const EWithdrawAmountCannotBeZero: u64 = 2;

const EInsufficientSuiTokenBalance: u64 = 3;

const EInsufficientRewardsPoolBalance: u64 = 4;

const EDestroyNonzeroBalance: u64 = 5;

const ETokenTimeLockIsSome: u64 = 6;

const EWrongDelegation: u64 = 7;

const EPendingDelegationDoesNotExist: u64 = 8;

const ETokenBalancesDoNotMatchExchangeRate: u64 = 9;

const EDelegationToInactivePool: u64 = 10;

const EDeactivationOfInactivePool: u64 = 11;

const EIncompatibleStakedSui: u64 = 12;

const EWithdrawalInSameEpoch: u64 = 13;

const EPoolAlreadyActive: u64 = 14;

const EPoolPreactiveOrInactive: u64 = 15;

const EActivationOfInactivePool: u64 = 16;

const EDelegationOfZeroSui: u64 = 17;

const EStakedSuiBelowThreshold: u64 = 18;

const ECannotMintFungibleStakedSuiYet: u64 = 19;

const EInvariantFailure: u64 = 20;

Function new​

Create a new, empty staking pool.

public(package) fun new(ctx: &mut sui::tx_context::TxContext): sui_system::staking_pool::StakingPool

Function request_add_stake​

Request to stake to a staking pool. The stake starts counting at the beginning of the next epoch,

public(package) fun request_add_stake(pool: &mut sui_system::staking_pool::StakingPool, stake: sui::balance::Balance<sui::sui::SUI>, stake_activation_epoch: u64, ctx: &mut sui::tx_context::TxContext): sui_system::staking_pool::StakedSui

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(package) fun request_withdraw_stake(pool: &mut sui_system::staking_pool::StakingPool, staked_sui: sui_system::staking_pool::StakedSui, ctx: &sui::tx_context::TxContext): sui::balance::Balance<sui::sui::SUI>

Function redeem_fungible_staked_sui​

public(package) fun redeem_fungible_staked_sui(pool: &mut sui_system::staking_pool::StakingPool, fungible_staked_sui: sui_system::staking_pool::FungibleStakedSui, ctx: &sui::tx_context::TxContext): sui::balance::Balance<sui::sui::SUI>

Function calculate_fungible_staked_sui_withdraw_amount​

written in separate function so i can test with random values returns (principal_withdraw_amount, rewards_withdraw_amount)

fun calculate_fungible_staked_sui_withdraw_amount(latest_exchange_rate: sui_system::staking_pool::PoolTokenExchangeRate, fungible_staked_sui_value: u64, fungible_staked_sui_data_principal_amount: u64, fungible_staked_sui_data_total_supply: u64): (u64, u64)

Function convert_to_fungible_staked_sui​

Convert the given staked SUI to an FungibleStakedSui object

public(package) fun convert_to_fungible_staked_sui(pool: &mut sui_system::staking_pool::StakingPool, staked_sui: sui_system::staking_pool::StakedSui, ctx: &mut sui::tx_context::TxContext): sui_system::staking_pool::FungibleStakedSui

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(package) fun withdraw_from_principal(pool: &sui_system::staking_pool::StakingPool, staked_sui: sui_system::staking_pool::StakedSui): (u64, sui::balance::Balance<sui::sui::SUI>)

Function unwrap_staked_sui​

fun unwrap_staked_sui(staked_sui: sui_system::staking_pool::StakedSui): sui::balance::Balance<sui::sui::SUI>

Function deposit_rewards​

Called at epoch advancement times to add rewards (in SUI) to the staking pool.

public(package) fun deposit_rewards(pool: &mut sui_system::staking_pool::StakingPool, rewards: sui::balance::Balance<sui::sui::SUI>)

Function process_pending_stakes_and_withdraws​

public(package) fun process_pending_stakes_and_withdraws(pool: &mut sui_system::staking_pool::StakingPool, ctx: &sui::tx_context::TxContext)

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 sui_system::staking_pool::StakingPool)

Function process_pending_stake​

Called at epoch boundaries to process the pending stake.

public(package) fun process_pending_stake(pool: &mut sui_system::staking_pool::StakingPool)

Function withdraw_rewards​

This function does the following:

  1. Calculates the total amount of SUI (including principal and rewards) that the provided pool tokens represent at the current exchange rate.
  2. Using the above number and the given principal_withdraw_amount, calculates the rewards portion of the stake we should withdraw.
  3. 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 sui_system::staking_pool::StakingPool, principal_withdraw_amount: u64, pool_token_withdraw_amount: u64, epoch: u64): sui::balance::Balance<sui::sui::SUI>

Function activate_staking_pool​

Called by validator module to activate a staking pool.

public(package) fun activate_staking_pool(pool: &mut sui_system::staking_pool::StakingPool, activation_epoch: u64)

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(package) fun deactivate_staking_pool(pool: &mut sui_system::staking_pool::StakingPool, deactivation_epoch: u64)

Function sui_balance​

public fun sui_balance(pool: &sui_system::staking_pool::StakingPool): u64

Function pool_id​

public fun pool_id(staked_sui: &sui_system::staking_pool::StakedSui): sui::object::ID

Function fungible_staked_sui_pool_id​

public fun fungible_staked_sui_pool_id(fungible_staked_sui: &sui_system::staking_pool::FungibleStakedSui): sui::object::ID

Function staked_sui_amount​

Returns the principal amount of StakedSui.

public fun staked_sui_amount(staked_sui: &sui_system::staking_pool::StakedSui): u64

Function stake_activation_epoch​

Returns the activation epoch of StakedSui.

public fun stake_activation_epoch(staked_sui: &sui_system::staking_pool::StakedSui): u64

Function is_preactive​

Returns true if the input staking pool is preactive.

public fun is_preactive(pool: &sui_system::staking_pool::StakingPool): bool

Function activation_epoch​

Returns the activation epoch of the StakingPool. For validator candidates, or pending validators, the value returned is None. For active validators, the value is the epoch before the validator was activated.

public(package) fun activation_epoch(pool: &sui_system::staking_pool::StakingPool): std::option::Option<u64>

Function is_inactive​

Returns true if the input staking pool is inactive.

public fun is_inactive(pool: &sui_system::staking_pool::StakingPool): bool

Function fungible_staked_sui_value​

public fun fungible_staked_sui_value(fungible_staked_sui: &sui_system::staking_pool::FungibleStakedSui): u64

Function split_fungible_staked_sui​

public fun split_fungible_staked_sui(fungible_staked_sui: &mut sui_system::staking_pool::FungibleStakedSui, split_amount: u64, ctx: &mut sui::tx_context::TxContext): sui_system::staking_pool::FungibleStakedSui

Function join_fungible_staked_sui​

public fun join_fungible_staked_sui(self: &mut sui_system::staking_pool::FungibleStakedSui, other: sui_system::staking_pool::FungibleStakedSui)

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 sui_system::staking_pool::StakedSui, split_amount: u64, ctx: &mut sui::tx_context::TxContext): sui_system::staking_pool::StakedSui

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 sui_system::staking_pool::StakedSui, split_amount: u64, ctx: &mut sui::tx_context::TxContext)

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 sui_system::staking_pool::StakedSui, other: sui_system::staking_pool::StakedSui)

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: &sui_system::staking_pool::StakedSui, other: &sui_system::staking_pool::StakedSui): bool

Function pool_token_exchange_rate_at_epoch​

public fun pool_token_exchange_rate_at_epoch(pool: &sui_system::staking_pool::StakingPool, epoch: u64): sui_system::staking_pool::PoolTokenExchangeRate

Function pending_stake_amount​

Returns the total value of the pending staking requests for this staking pool.

public fun pending_stake_amount(staking_pool: &sui_system::staking_pool::StakingPool): u64

Function pending_stake_withdraw_amount​

Returns the total withdrawal from the staking pool this epoch.

public fun pending_stake_withdraw_amount(staking_pool: &sui_system::staking_pool::StakingPool): u64

Function exchange_rates​

public(package) fun exchange_rates(pool: &sui_system::staking_pool::StakingPool): &sui::table::Table<u64, sui_system::staking_pool::PoolTokenExchangeRate>

Function sui_amount​

public fun sui_amount(exchange_rate: &sui_system::staking_pool::PoolTokenExchangeRate): u64

Function pool_token_amount​

public fun pool_token_amount(exchange_rate: &sui_system::staking_pool::PoolTokenExchangeRate): u64

Function is_preactive_at_epoch​

Returns true if the provided staking pool is preactive at the provided epoch.

fun is_preactive_at_epoch(pool: &sui_system::staking_pool::StakingPool, epoch: u64): bool

Function get_sui_amount​

fun get_sui_amount(exchange_rate: &sui_system::staking_pool::PoolTokenExchangeRate, token_amount: u64): u64

Function get_token_amount​

fun get_token_amount(exchange_rate: &sui_system::staking_pool::PoolTokenExchangeRate, sui_amount: u64): u64

Function initial_exchange_rate​

fun initial_exchange_rate(): sui_system::staking_pool::PoolTokenExchangeRate

Function check_balance_invariants​

fun check_balance_invariants(pool: &sui_system::staking_pool::StakingPool, epoch: u64)

Macro function mul_div​

macro fun mul_div($a: u64, $b: u64, $c: u64): u64

Function calculate_rewards​

public(package) fun calculate_rewards(pool: &sui_system::staking_pool::StakingPool, staked_sui: &sui_system::staking_pool::StakedSui, current_epoch: u64): u64