Module sui_system::validator_set

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::priority_queue;
use sui::protocol_config;
use sui::sui;
use sui::table;
use sui::table_vec;
use sui::transfer;
use sui::tx_context;
use sui::types;
use sui::url;
use sui::vec_map;
use sui::vec_set;
use sui::versioned;
use sui_system::staking_pool;
use sui_system::validator;
use sui_system::validator_cap;
use sui_system::validator_wrapper;
use sui_system::voting_power;

Struct ValidatorSet

public struct ValidatorSet has store

Click to open

Fields

total_stake: u64: Total amount of stake from all active validators at the beginning of the epoch.
Written only once per epoch, in advance_epoch function.
active_validators: vector<sui_system::validator::Validator>: The current list of active validators.
pending_active_validators: sui::table_vec::TableVec<sui_system::validator::Validator>: List of new validator candidates added during the current epoch.
They will be processed at the end of the epoch.
pending_removals: vector<u64>: Removal requests from the validators. Each element is an index pointing to active_validators.
staking_pool_mappings: sui::table::Table<sui::object::ID, address>: Mappings from staking pool's ID to the sui address of a validator.
inactive_validators: sui::table::Table<sui::object::ID, sui_system::validator_wrapper::ValidatorWrapper>: Mapping from a staking pool ID to the inactive validator that has that pool as its staking pool.
When a validator is deactivated the validator is removed from active_validators it is added to this table so that stakers can continue to withdraw their stake from it.
validator_candidates: sui::table::Table<address, sui_system::validator_wrapper::ValidatorWrapper>: Table storing preactive/candidate validators, mapping their addresses to their Validator structs.
When an address calls request_add_validator_candidate, they get added to this table and become a preactive validator.
When the candidate has met the min stake requirement, they can call request_add_validator to officially add them to the active validator set active_validators next epoch.
at_risk_validators: sui::vec_map::VecMap<address, u64>: Table storing the number of epochs during which a validator's stake has been below the low stake threshold.
extra_fields: sui::bag::Bag: Any extra fields that's not defined statically.

Struct ValidatorEpochInfoEvent

Event containing staking and rewards related information of each validator, emitted during epoch advancement.

public struct ValidatorEpochInfoEvent has copy, drop

Click to open

Fields

epoch: u64
validator_address: address
reference_gas_survey_quote: u64
stake: u64
commission_rate: u64
pool_staking_reward: u64
storage_fund_staking_reward: u64
pool_token_exchange_rate: sui_system::staking_pool::PoolTokenExchangeRate
tallying_rule_reporters: vector<address>
tallying_rule_global_score: u64

Struct ValidatorEpochInfoEventV2

V2 of ValidatorEpochInfoEvent containing more information about the validator.

public struct ValidatorEpochInfoEventV2 has copy, drop

Click to open

Fields

epoch: u64
validator_address: address
reference_gas_survey_quote: u64
stake: u64
voting_power: u64
commission_rate: u64
pool_staking_reward: u64
storage_fund_staking_reward: u64
pool_token_exchange_rate: sui_system::staking_pool::PoolTokenExchangeRate
tallying_rule_reporters: vector<address>
tallying_rule_global_score: u64

Struct ValidatorJoinEvent

Event emitted every time a new validator joins the committee.
The epoch value corresponds to the first epoch this change takes place.

public struct ValidatorJoinEvent has copy, drop

Click to open

Fields

epoch: u64
validator_address: address
staking_pool_id: sui::object::ID

Struct ValidatorLeaveEvent

Event emitted every time a validator leaves the committee.
The epoch value corresponds to the first epoch this change takes place.

public struct ValidatorLeaveEvent has copy, drop

Click to open

Fields

epoch: u64
validator_address: address
staking_pool_id: sui::object::ID
is_voluntary: bool

Struct VotingPowerAdmissionStartEpochKey

Key for the extra_fields bag to store the start epoch of allowing admission of new validators based on a minimum voting power rather than a minimum stake.

public struct VotingPowerAdmissionStartEpochKey has copy, drop, store

Constants

const ENonValidatorInReportRecords: u64 = 0;

const EInvalidStakeAdjustmentAmount: u64 = 1;

const EDuplicateValidator: u64 = 2;

const ENoPoolFound: u64 = 3;

const ENotAValidator: u64 = 4;

const EMinJoiningStakeNotReached: u64 = 5;

const EAlreadyValidatorCandidate: u64 = 6;

const EValidatorNotCandidate: u64 = 7;

const ENotValidatorCandidate: u64 = 8;

const EStakingBelowThreshold: u64 = 10;

const EValidatorAlreadyRemoved: u64 = 11;

const ENotAPendingValidator: u64 = 12;

const EValidatorSetEmpty: u64 = 13;

const EInvalidCap: u64 = 101;

const EInvalidValidatorSelector: u64 = 14;

const ACTIVE_VALIDATOR_ONLY: u8 = 1;

const ACTIVE_OR_PENDING_VALIDATOR: u8 = 2;

const ANY_VALIDATOR: u8 = 3;

const BASIS_POINT_DENOMINATOR: u64 = 10000;

const MIN_STAKING_THRESHOLD: u64 = 1000000000;

const PHASE_LENGTH: u64 = 14;

Function new

public(package) fun new(init_active_validators: vector<sui_system::validator::Validator>, ctx: &mut sui::tx_context::TxContext): sui_system::validator_set::ValidatorSet

Function request_add_validator_candidate

Called by sui_system to add a new validator candidate.

public(package) fun request_add_validator_candidate(self: &mut sui_system::validator_set::ValidatorSet, validator: sui_system::validator::Validator, ctx: &mut sui::tx_context::TxContext)

Function request_remove_validator_candidate

Called by sui_system to remove a validator candidate, and move them to inactive_validators.

public(package) fun request_remove_validator_candidate(self: &mut sui_system::validator_set::ValidatorSet, ctx: &mut sui::tx_context::TxContext)

Function request_add_validator

Called by sui_system to add a new validator to pending_active_validators, which will be processed at the end of epoch.

Aborts if the validator contains duplicate metadata values with an active or pending validator.

public(package) fun request_add_validator(self: &mut sui_system::validator_set::ValidatorSet, ctx: &sui::tx_context::TxContext)

Function can_join

Return true if a candidate validator with stake will have sufficeint voting power to join the validator set

fun can_join(self: &sui_system::validator_set::ValidatorSet, stake: u64, ctx: &sui::tx_context::TxContext): bool

Function get_voting_power_thresholds

return (min, low, very low voting power) thresholds

fun get_voting_power_thresholds(self: &sui_system::validator_set::ValidatorSet, ctx: &sui::tx_context::TxContext): (u64, u64, u64)

Function assert_no_pending_or_active_duplicates

public(package) fun assert_no_pending_or_active_duplicates(self: &sui_system::validator_set::ValidatorSet, validator: &sui_system::validator::Validator)

Function request_remove_validator

Called by sui_system, to remove a validator.
The index of the validator is added to pending_removals and will be processed at the end of epoch.
Only an active validator can request to be removed.

public(package) fun request_remove_validator(self: &mut sui_system::validator_set::ValidatorSet, ctx: &sui::tx_context::TxContext)

Function request_add_stake

Called by sui_system, to add a new stake to the validator.
This request is added to the validator's staking pool's pending stake entries, processed at the end of the epoch.
Aborts in case the staking amount is smaller than MIN_STAKING_THRESHOLD

public(package) fun request_add_stake(self: &mut sui_system::validator_set::ValidatorSet, validator_address: address, stake: sui::balance::Balance<sui::sui::SUI>, ctx: &mut sui::tx_context::TxContext): sui_system::staking_pool::StakedSui

Function request_withdraw_stake

Called by sui_system, to withdraw some share of a stake from the validator. The share to withdraw is denoted by principal_withdraw_amount. One of two things occurs in this function:

If the staked_sui is staked with an active validator, the request is added to the validator's staking pool's pending stake withdraw entries, processed at the end of the epoch.
If the staked_sui was staked with a validator that is no longer active, the stake and any rewards corresponding to it will be immediately processed.

public(package) fun request_withdraw_stake(self: &mut sui_system::validator_set::ValidatorSet, staked_sui: sui_system::staking_pool::StakedSui, ctx: &sui::tx_context::TxContext): sui::balance::Balance<sui::sui::SUI>

Function convert_to_fungible_staked_sui

public(package) fun convert_to_fungible_staked_sui(self: &mut sui_system::validator_set::ValidatorSet, staked_sui: sui_system::staking_pool::StakedSui, ctx: &mut sui::tx_context::TxContext): sui_system::staking_pool::FungibleStakedSui

Function redeem_fungible_staked_sui

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

Function advance_epoch

Update the validator set at the end of epoch.
It does the following things:

Distribute stake award.
Process pending stake deposits and withdraws for each validator (adjust_stake).
Process pending stake deposits, and withdraws.
Process pending validator application and withdraws.
At the end, we calculate the total stake for the new epoch.

public(package) fun advance_epoch(self: &mut sui_system::validator_set::ValidatorSet, computation_reward: &mut sui::balance::Balance<sui::sui::SUI>, storage_fund_reward: &mut sui::balance::Balance<sui::sui::SUI>, validator_report_records: &mut sui::vec_map::VecMap<address, sui::vec_set::VecSet<address>>, reward_slashing_rate: u64, low_stake_grace_period: u64, ctx: &mut sui::tx_context::TxContext)

Function update_validator_positions_and_calculate_total_stake

This function does the following:

removes validators from at_risk group if their voting power is above the LOW threshold
increments the number of epochs a validator has been below the LOW threshold but above the.
VERY LOW threshold
removes validators from the active set if they have been below the LOW threshold for more than low_stake_grace_period epochs
removes validators from the active set immediately if they are below the VERY LOW threshold
activates pending validators if they have sufficient voting power

fun update_validator_positions_and_calculate_total_stake(self: &mut sui_system::validator_set::ValidatorSet, low_stake_grace_period: u64, validator_report_records: &mut sui::vec_map::VecMap<address, sui::vec_set::VecSet<address>>, ctx: &mut sui::tx_context::TxContext): u64

Function effectuate_staged_metadata

Effectuate pending next epoch metadata if they are staged.

fun effectuate_staged_metadata(self: &mut sui_system::validator_set::ValidatorSet)

Function derive_reference_gas_price

Called by sui_system to derive reference gas price for the new epoch.
Derive the reference gas price based on the gas price quote submitted by each validator.
The returned gas price should be greater than or equal to 2/3 of the validators submitted gas price, weighted by stake.

public fun derive_reference_gas_price(self: &sui_system::validator_set::ValidatorSet): u64

Function total_stake

public fun total_stake(self: &sui_system::validator_set::ValidatorSet): u64

Function validator_total_stake_amount

public fun validator_total_stake_amount(self: &sui_system::validator_set::ValidatorSet, validator_address: address): u64

Function validator_stake_amount

public fun validator_stake_amount(self: &sui_system::validator_set::ValidatorSet, validator_address: address): u64

Function validator_voting_power

public fun validator_voting_power(self: &sui_system::validator_set::ValidatorSet, validator_address: address): u64

Function validator_staking_pool_id

public fun validator_staking_pool_id(self: &sui_system::validator_set::ValidatorSet, validator_address: address): sui::object::ID

Function staking_pool_mappings

public fun staking_pool_mappings(self: &sui_system::validator_set::ValidatorSet): &sui::table::Table<sui::object::ID, address>

Function validator_address_by_pool_id

public fun validator_address_by_pool_id(self: &mut sui_system::validator_set::ValidatorSet, pool_id: &sui::object::ID): address

Function pool_exchange_rates

public(package) fun pool_exchange_rates(self: &mut sui_system::validator_set::ValidatorSet, pool_id: sui::object::ID): &sui::table::Table<u64, sui_system::staking_pool::PoolTokenExchangeRate>

Function validator_by_pool_id

public(package) fun validator_by_pool_id(self: &mut sui_system::validator_set::ValidatorSet, pool_id: sui::object::ID): &sui_system::validator::Validator

Function next_epoch_validator_count

Get the total number of validators in the next epoch.

public(package) fun next_epoch_validator_count(self: &sui_system::validator_set::ValidatorSet): u64

Function is_active_validator_by_sui_address

Returns true iff the address exists in active validators.

public(package) fun is_active_validator_by_sui_address(self: &sui_system::validator_set::ValidatorSet, validator_address: address): bool

Function is_duplicate_with_active_validator

Checks whether new_validator is duplicate with any currently active validators.
It differs from is_active_validator_by_sui_address in that the former checks only the sui address but this function looks at more metadata.

fun is_duplicate_with_active_validator(self: &sui_system::validator_set::ValidatorSet, new_validator: &sui_system::validator::Validator): bool

Function is_duplicate_validator

public(package) fun is_duplicate_validator(validators: &vector<sui_system::validator::Validator>, new_validator: &sui_system::validator::Validator): bool

Function count_duplicates_vec

fun count_duplicates_vec(validators: &vector<sui_system::validator::Validator>, validator: &sui_system::validator::Validator): u64

Function is_duplicate_with_pending_validator

Checks whether new_validator is duplicate with any currently pending validators.

fun is_duplicate_with_pending_validator(self: &sui_system::validator_set::ValidatorSet, new_validator: &sui_system::validator::Validator): bool

Function count_duplicates_tablevec

fun count_duplicates_tablevec(validators: &sui::table_vec::TableVec<sui_system::validator::Validator>, validator: &sui_system::validator::Validator): u64

Function get_candidate_or_active_validator_mut

Get mutable reference to either a candidate or an active validator by address.

fun get_candidate_or_active_validator_mut(self: &mut sui_system::validator_set::ValidatorSet, validator_address: address): &mut sui_system::validator::Validator

Function find_validator

Find validator by validator_address, in validators.
Returns (true, index) if the validator is found, and the index is its index in the list.
If not found, returns (false, 0).

fun find_validator(validators: &vector<sui_system::validator::Validator>, validator_address: address): std::option::Option<u64>

Function find_validator_from_table_vec

Find validator by validator_address, in validators.
Returns (true, index) if the validator is found, and the index is its index in the list.
If not found, returns (false, 0).

fun find_validator_from_table_vec(validators: &sui::table_vec::TableVec<sui_system::validator::Validator>, validator_address: address): std::option::Option<u64>

Function get_validator_indices

Given a vector of validator addresses, return their indices in the validator set.
Aborts if any address isn't in the given validator set.

fun get_validator_indices(validators: &vector<sui_system::validator::Validator>, validator_addresses: &vector<address>): vector<u64>

Function any_validator

Get reference to validator in any state: active, pending, or candidate.

public(package) fun any_validator(self: &mut sui_system::validator_set::ValidatorSet, validator: address): &sui_system::validator::Validator

Function any_validator_mut

Get mutable reference to validator in any state: active, pending, or candidate.

public(package) fun any_validator_mut(self: &mut sui_system::validator_set::ValidatorSet, validator: address): &mut sui_system::validator::Validator

Function active_validator

Get reference to an active validator by address.

public(package) fun active_validator(self: &sui_system::validator_set::ValidatorSet, validator: address): &sui_system::validator::Validator

Function active_validator_mut

Get mutable reference to an active validator by address.

public(package) fun active_validator_mut(self: &mut sui_system::validator_set::ValidatorSet, validator: address): &mut sui_system::validator::Validator

Function pending_validator

Get reference to a pending validator by address.

public(package) fun pending_validator(self: &sui_system::validator_set::ValidatorSet, validator: address): &sui_system::validator::Validator

Function pending_validator_mut

Get mutable reference to a pending validator by address.

public(package) fun pending_validator_mut(self: &mut sui_system::validator_set::ValidatorSet, validator: address): &mut sui_system::validator::Validator

Function candidate_validator

Get mutable reference to a candidate validator by address.

public(package) fun candidate_validator(self: &mut sui_system::validator_set::ValidatorSet, validator: address): &sui_system::validator::Validator

This page has been truncated because it exceeds the maximum character limit. View the full source.

Struct ValidatorSet​

Struct ValidatorEpochInfoEvent​

Struct ValidatorEpochInfoEventV2​

Struct ValidatorJoinEvent​

Struct ValidatorLeaveEvent​

Struct VotingPowerAdmissionStartEpochKey​

Constants​

Function new​

Function request_add_validator_candidate​

Function request_remove_validator_candidate​

Function request_add_validator​

Function can_join​

Function get_voting_power_thresholds​

Function assert_no_pending_or_active_duplicates​

Function request_remove_validator​

Function request_add_stake​

Function request_withdraw_stake​

Function convert_to_fungible_staked_sui​

Function redeem_fungible_staked_sui​

Function advance_epoch​

Function update_validator_positions_and_calculate_total_stake​

Function effectuate_staged_metadata​

Function derive_reference_gas_price​

Function total_stake​

Function validator_total_stake_amount​

Function validator_stake_amount​

Function validator_voting_power​

Function validator_staking_pool_id​

Function staking_pool_mappings​

Function validator_address_by_pool_id​

Function pool_exchange_rates​

Function validator_by_pool_id​

Function next_epoch_validator_count​

Function is_active_validator_by_sui_address​

Function is_duplicate_with_active_validator​

Function is_duplicate_validator​

Function count_duplicates_vec​

Function is_duplicate_with_pending_validator​

Function count_duplicates_tablevec​

Function get_candidate_or_active_validator_mut​

Function find_validator​

Function find_validator_from_table_vec​

Function get_validator_indices​

Function any_validator​

Function any_validator_mut​

Function active_validator​

Function active_validator_mut​

Function pending_validator​

Function pending_validator_mut​

Function candidate_validator​

Struct ValidatorSet

Struct ValidatorEpochInfoEvent

Struct ValidatorEpochInfoEventV2

Struct ValidatorJoinEvent

Struct ValidatorLeaveEvent

Struct VotingPowerAdmissionStartEpochKey

Constants

Function new

Function request_add_validator_candidate

Function request_remove_validator_candidate

Function request_add_validator

Function can_join

Function get_voting_power_thresholds

Function assert_no_pending_or_active_duplicates

Function request_remove_validator

Function request_add_stake

Function request_withdraw_stake

Function convert_to_fungible_staked_sui

Function redeem_fungible_staked_sui

Function advance_epoch

Function update_validator_positions_and_calculate_total_stake

Function effectuate_staged_metadata

Function derive_reference_gas_price

Function total_stake

Function validator_total_stake_amount

Function validator_stake_amount

Function validator_voting_power

Function validator_staking_pool_id

Function staking_pool_mappings

Function validator_address_by_pool_id

Function pool_exchange_rates

Function validator_by_pool_id

Function next_epoch_validator_count

Function is_active_validator_by_sui_address

Function is_duplicate_with_active_validator

Function is_duplicate_validator

Function count_duplicates_vec

Function is_duplicate_with_pending_validator

Function count_duplicates_tablevec

Function get_candidate_or_active_validator_mut

Function find_validator

Function find_validator_from_table_vec

Function get_validator_indices

Function any_validator

Function any_validator_mut

Function active_validator

Function active_validator_mut

Function pending_validator

Function pending_validator_mut

Function candidate_validator