Module 0x3::validator_set
- Struct
ValidatorSet
- Struct
ValidatorEpochInfoEvent
- Struct
ValidatorEpochInfoEventV2
- Struct
ValidatorJoinEvent
- Struct
ValidatorLeaveEvent
- Constants
- Function
new
- Function
request_add_validator_candidate
- Function
request_remove_validator_candidate
- Function
request_add_validator
- 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
request_set_commission_rate
- Function
advance_epoch
- Function
update_and_process_low_stake_departures
- 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
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
get_validator_mut
- Function
get_active_or_pending_or_candidate_validator_mut
- Function
get_validator_mut_with_verified_cap
- Function
get_validator_mut_with_ctx
- Function
get_validator_mut_with_ctx_including_candidates
- Function
get_validator_ref
- Function
get_active_or_pending_or_candidate_validator_ref
- Function
get_active_validator_ref
- Function
get_pending_validator_ref
- Function
verify_cap
- Function
process_pending_removals
- Function
process_validator_departure
- Function
clean_report_records_leaving_validator
- Function
process_pending_validators
- Function
sort_removal_list
- Function
process_pending_stakes_and_withdraws
- Function
calculate_total_stakes
- Function
adjust_stake_and_gas_price
- Function
compute_reward_adjustments
- Function
compute_slashed_validators
- Function
compute_unadjusted_reward_distribution
- Function
compute_adjusted_reward_distribution
- Function
distribute_reward
- Function
emit_validator_epoch_events
- Function
sum_voting_power_by_addresses
- Function
active_validators
- Function
is_validator_candidate
- Function
is_inactive_validator
- Function
active_validator_addresses
use 0x1::option;
use 0x1::vector;
use 0x2::bag;
use 0x2::balance;
use 0x2::event;
use 0x2::object;
use 0x2::priority_queue;
use 0x2::sui;
use 0x2::table;
use 0x2::table_vec;
use 0x2::transfer;
use 0x2::tx_context;
use 0x2::vec_map;
use 0x2::vec_set;
use 0x3::staking_pool;
use 0x3::validator;
use 0x3::validator_cap;
use 0x3::validator_wrapper;
use 0x3::voting_power;
Struct ValidatorSet
struct ValidatorSet has store
Fields
Struct ValidatorEpochInfoEvent
Event containing staking and rewards related information of each validator, emitted during epoch advancement.
struct ValidatorEpochInfoEvent has copy, drop
Fields
Struct ValidatorEpochInfoEventV2
V2 of ValidatorEpochInfoEvent containing more information about the validator.
struct ValidatorEpochInfoEventV2 has copy, drop
Fields
Struct ValidatorJoinEvent
Event emitted every time a new validator joins the committee. The epoch value corresponds to the first epoch this change takes place.
struct ValidatorJoinEvent has copy, drop
Fields
Struct ValidatorLeaveEvent
Event emitted every time a validator leaves the committee. The epoch value corresponds to the first epoch this change takes place.
struct ValidatorLeaveEvent has copy, drop
Fields
Constants
const MIN_STAKING_THRESHOLD: u64 = 1000000000;
const EInvalidCap: u64 = 101;
const ENotValidatorCandidate: u64 = 8;
const ACTIVE_OR_PENDING_VALIDATOR: u8 = 2;
const ACTIVE_VALIDATOR_ONLY: u8 = 1;
const ANY_VALIDATOR: u8 = 3;
const BASIS_POINT_DENOMINATOR: u128 = 10000;
const EAlreadyValidatorCandidate: u64 = 6;
const EDuplicateValidator: u64 = 2;
const EInvalidStakeAdjustmentAmount: u64 = 1;
const EMinJoiningStakeNotReached: u64 = 5;
const ENoPoolFound: u64 = 3;
const ENonValidatorInReportRecords: u64 = 0;
const ENotAPendingValidator: u64 = 12;
const ENotAValidator: u64 = 4;
const ENotActiveOrPendingValidator: u64 = 9;
const EStakingBelowThreshold: u64 = 10;
const EValidatorAlreadyRemoved: u64 = 11;
const EValidatorNotCandidate: u64 = 7;
const EValidatorSetEmpty: u64 = 13;
Function new
public(friend) fun new(init_active_validators: vector<validator::Validator>, ctx: &mut tx_context::TxContext): validator_set::ValidatorSet
Implementation
Function request_add_validator_candidate
Called by sui_system to add a new validator candidate.
public(friend) fun request_add_validator_candidate(self: &mut validator_set::ValidatorSet, validator: validator::Validator, ctx: &mut tx_context::TxContext)
Implementation
Function request_remove_validator_candidate
Called by sui_system to remove a validator candidate, and move them to inactive_validators.
public(friend) fun request_remove_validator_candidate(self: &mut validator_set::ValidatorSet, ctx: &mut tx_context::TxContext)
Implementation
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.
public(friend) fun request_add_validator(self: &mut validator_set::ValidatorSet, min_joining_stake_amount: u64, ctx: &tx_context::TxContext)
Implementation
Function assert_no_pending_or_active_duplicates
public(friend) fun assert_no_pending_or_active_duplicates(self: &validator_set::ValidatorSet, validator: &validator::Validator)
Implementation
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(friend) fun request_remove_validator(self: &mut validator_set::ValidatorSet, ctx: &tx_context::TxContext)
Implementation
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(friend) fun request_add_stake(self: &mut validator_set::ValidatorSet, validator_address: address, stake: balance::Balance<sui::SUI>, ctx: &mut tx_context::TxContext): staking_pool::StakedSui
Implementation
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(friend) fun request_withdraw_stake(self: &mut validator_set::ValidatorSet, staked_sui: staking_pool::StakedSui, ctx: &tx_context::TxContext): balance::Balance<sui::SUI>
Implementation
Function convert_to_fungible_staked_sui
public(friend) fun convert_to_fungible_staked_sui(self: &mut validator_set::ValidatorSet, staked_sui: staking_pool::StakedSui, ctx: &mut tx_context::TxContext): staking_pool::FungibleStakedSui
Implementation
Function redeem_fungible_staked_sui
public(friend) fun redeem_fungible_staked_sui(self: &mut validator_set::ValidatorSet, fungible_staked_sui: staking_pool::FungibleStakedSui, ctx: &tx_context::TxContext): balance::Balance<sui::SUI>
Implementation
Function request_set_commission_rate
public(friend) fun request_set_commission_rate(self: &mut validator_set::ValidatorSet, new_commission_rate: u64, ctx: &tx_context::TxContext)
Implementation
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(friend) fun advance_epoch(self: &mut validator_set::ValidatorSet, computation_reward: &mut balance::Balance<sui::SUI>, storage_fund_reward: &mut balance::Balance<sui::SUI>, validator_report_records: &mut vec_map::VecMap<address, vec_set::VecSet<address>>, reward_slashing_rate: u64, low_stake_threshold: u64, very_low_stake_threshold: u64, low_stake_grace_period: u64, ctx: &mut tx_context::TxContext)
Implementation
Function update_and_process_low_stake_departures
fun update_and_process_low_stake_departures(self: &mut validator_set::ValidatorSet, low_stake_threshold: u64, very_low_stake_threshold: u64, low_stake_grace_period: u64, validator_report_records: &mut vec_map::VecMap<address, vec_set::VecSet<address>>, ctx: &mut tx_context::TxContext)
Implementation
Function effectuate_staged_metadata
Effectutate pending next epoch metadata if they are staged.
fun effectuate_staged_metadata(self: &mut validator_set::ValidatorSet)
Implementation
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: &validator_set::ValidatorSet): u64
Implementation
Function total_stake
public fun total_stake(self: &validator_set::ValidatorSet): u64
Implementation
Function validator_total_stake_amount
public fun validator_total_stake_amount(self: &validator_set::ValidatorSet, validator_address: address): u64
Implementation
Function validator_stake_amount
public fun validator_stake_amount(self: &validator_set::ValidatorSet, validator_address: address): u64
Implementation
Function validator_voting_power
public fun validator_voting_power(self: &validator_set::ValidatorSet, validator_address: address): u64
Implementation
Function validator_staking_pool_id
public fun validator_staking_pool_id(self: &validator_set::ValidatorSet, validator_address: address): object::ID
Implementation
Function staking_pool_mappings
public fun staking_pool_mappings(self: &validator_set::ValidatorSet): &table::Table<object::ID, address>
Implementation
Function validator_address_by_pool_id
public fun validator_address_by_pool_id(self: &mut validator_set::ValidatorSet, pool_id: &object::ID): address
Implementation
Function pool_exchange_rates
public(friend) fun pool_exchange_rates(self: &mut validator_set::ValidatorSet, pool_id: &object::ID): &table::Table<u64, staking_pool::PoolTokenExchangeRate>
Implementation
Function next_epoch_validator_count
Get the total number of validators in the next epoch.
public(friend) fun next_epoch_validator_count(self: &validator_set::ValidatorSet): u64
Implementation
Function is_active_validator_by_sui_address
Returns true iff the address exists in active validators.
public(friend) fun is_active_validator_by_sui_address(self: &validator_set::ValidatorSet, validator_address: address): bool
Implementation
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: &validator_set::ValidatorSet, new_validator: &validator::Validator): bool
Implementation
Function is_duplicate_validator
public(friend) fun is_duplicate_validator(validators: &vector<validator::Validator>, new_validator: &validator::Validator): bool
Implementation
Function count_duplicates_vec
fun count_duplicates_vec(validators: &vector<validator::Validator>, validator: &validator::Validator): u64
Implementation
Function is_duplicate_with_pending_validator
Checks whether new_validator is duplicate with any currently pending validators.
fun is_duplicate_with_pending_validator(self: &validator_set::ValidatorSet, new_validator: &validator::Validator): bool
Implementation
Function count_duplicates_tablevec
fun count_duplicates_tablevec(validators: &table_vec::TableVec<validator::Validator>, validator: &validator::Validator): u64
Implementation
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 validator_set::ValidatorSet, validator_address: address): &mut validator::Validator
Implementation
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<validator::Validator>, validator_address: address): option::Option<u64>
Implementation
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: &table_vec::TableVec<validator::Validator>, validator_address: address): option::Option<u64>
Implementation
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<validator::Validator>, validator_addresses: &vector<address>): vector<u64>
Implementation
Function get_validator_mut
public(friend) fun get_validator_mut(validators: &mut vector<validator::Validator>, validator_address: address): &mut validator::Validator
Implementation
Function get_active_or_pending_or_candidate_validator_mut
Get mutable reference to an active or (if active does not exist) pending or (if pending and active do not exist) or candidate validator by address. Note: this function should be called carefully, only after verifying the transaction sender has the ability to modify the Validator.
fun get_active_or_pending_or_candidate_validator_mut(self: &mut validator_set::ValidatorSet, validator_address: address, include_candidate: bool): &mut validator::Validator
Implementation
Function get_validator_mut_with_verified_cap
public(friend) fun get_validator_mut_with_verified_cap(self: &mut validator_set::ValidatorSet, verified_cap: &validator_cap::ValidatorOperationCap, include_candidate: bool): &mut validator::Validator
Implementation
Function get_validator_mut_with_ctx
public(friend) fun get_validator_mut_with_ctx(self: &mut validator_set::ValidatorSet, ctx: &tx_context::TxContext): &mut validator::Validator
Implementation
Function get_validator_mut_with_ctx_including_candidates
public(friend) fun get_validator_mut_with_ctx_including_candidates(self: &mut validator_set::ValidatorSet, ctx: &tx_context::TxContext): &mut validator::Validator
Implementation
Function get_validator_ref
fun get_validator_ref(validators: &vector<validator::Validator>, validator_address: address): &validator::Validator
Implementation
Function get_active_or_pending_or_candidate_validator_ref
public(friend) fun get_active_or_pending_or_candidate_validator_ref(self: &mut validator_set::ValidatorSet, validator_address: address, which_validator: u8): &validator::Validator
Implementation
Function get_active_validator_ref
public fun get_active_validator_ref(self: &validator_set::ValidatorSet, validator_address: address): &validator::Validator
Implementation
Function get_pending_validator_ref
public fun get_pending_validator_ref(self: &validator_set::ValidatorSet, validator_address: address): &validator::Validator
Implementation
Function verify_cap
Verify the capability is valid for a Validator. If active_validator_only is true, only verify the Cap for an active validator. Otherwise, verify the Cap for au either active or pending validator.
public(friend) fun verify_cap(self: &mut validator_set::ValidatorSet, cap: &validator_cap::UnverifiedValidatorOperationCap, which_validator: u8): validator_cap::ValidatorOperationCap
Implementation
Function process_pending_removals
Process the pending withdraw requests. For each pending request, the validator is removed from validators and its staking pool is put into the inactive_validators table.
fun process_pending_removals(self: &mut validator_set::ValidatorSet, validator_report_records: &mut vec_map::VecMap<address, vec_set::VecSet<address>>, ctx: &mut tx_context::TxContext)
Implementation
Function process_validator_departure
fun process_validator_departure(self: &mut validator_set::ValidatorSet, validator: validator::Validator, validator_report_records: &mut vec_map::VecMap<address, vec_set::VecSet<address>>, is_voluntary: bool, ctx: &mut tx_context::TxContext)
Implementation
Function clean_report_records_leaving_validator
fun clean_report_records_leaving_validator(validator_report_records: &mut vec_map::VecMap<address, vec_set::VecSet<address>>, leaving_validator_addr: address)
Implementation
Function process_pending_validators
Process the pending new validators. They are activated and inserted into validators.
fun process_pending_validators(self: &mut validator_set::ValidatorSet, new_epoch: u64)
Implementation
Function sort_removal_list
Sort all the pending removal indexes.
fun sort_removal_list(withdraw_list: &mut vector<u64>)
Implementation
Function process_pending_stakes_and_withdraws
Process all active validators' pending stake deposits and withdraws.
fun process_pending_stakes_and_withdraws(validators: &mut vector<validator::Validator>, ctx: &tx_context::TxContext)
Implementation
Function calculate_total_stakes
Calculate the total active validator stake.
fun calculate_total_stakes(validators: &vector<validator::Validator>): u64
Implementation
Function adjust_stake_and_gas_price
Process the pending stake changes for each validator.
fun adjust_stake_and_gas_price(validators: &mut vector<validator::Validator>)
Implementation
Function compute_reward_adjustments
Compute both the individual reward adjustments and total reward adjustment for staking rewards as well as storage fund rewards.
fun compute_reward_adjustments(slashed_validator_indices: vector<u64>, reward_slashing_rate: u64, unadjusted_staking_reward_amounts: &vector<u64>, unadjusted_storage_fund_reward_amounts: &vector<u64>): (u64, vec_map::VecMap<u64, u64>, u64, vec_map::VecMap<u64, u64>)
Implementation
Function compute_slashed_validators
Process the validator report records of the epoch and return the addresses of the non-performant validators according to the input threshold.
fun compute_slashed_validators(self: &validator_set::ValidatorSet, validator_report_records: vec_map::VecMap<address, vec_set::VecSet<address>>): vector<address>
Implementation
Function compute_unadjusted_reward_distribution
Given the current list of active validators, the total stake and total reward, calculate the amount of reward each validator should get, without taking into account the tallying rule results. Returns the unadjusted amounts of staking reward and storage fund reward for each validator.
fun compute_unadjusted_reward_distribution(validators: &vector<validator::Validator>, total_voting_power: u64, total_staking_reward: u64, total_storage_fund_reward: u64): (vector<u64>, vector<u64>)
Implementation
Function compute_adjusted_reward_distribution
Use the reward adjustment info to compute the adjusted rewards each validator should get. Returns the staking rewards each validator gets and the storage fund rewards each validator gets. The staking rewards are shared with the stakers while the storage fund ones are not.
fun compute_adjusted_reward_distribution(validators: &vector<validator::Validator>, total_voting_power: u64, total_slashed_validator_voting_power: u64, unadjusted_staking_reward_amounts: vector<u64>, unadjusted_storage_fund_reward_amounts: vector<u64>, total_staking_reward_adjustment: u64, individual_staking_reward_adjustments: vec_map::VecMap<u64, u64>, total_storage_fund_reward_adjustment: u64, individual_storage_fund_reward_adjustments: vec_map::VecMap<u64, u64>): (vector<u64>, vector<u64>)
Implementation
Function distribute_reward
fun distribute_reward(validators: &mut vector<validator::Validator>, adjusted_staking_reward_amounts: &vector<u64>, adjusted_storage_fund_reward_amounts: &vector<u64>, staking_rewards: &mut balance::Balance<sui::SUI>, storage_fund_reward: &mut balance::Balance<sui::SUI>, ctx: &mut tx_context::TxContext)
Implementation
Function emit_validator_epoch_events
Emit events containing information of each validator for the epoch, including stakes, rewards, performance, etc.
fun emit_validator_epoch_events(new_epoch: u64, vs: &vector<validator::Validator>, pool_staking_reward_amounts: &vector<u64>, storage_fund_staking_reward_amounts: &vector<u64>, report_records: &vec_map::VecMap<address, vec_set::VecSet<address>>, slashed_validators: &vector<address>)
Implementation
Function sum_voting_power_by_addresses
Sum up the total stake of a given list of validator addresses.
public fun sum_voting_power_by_addresses(vs: &vector<validator::Validator>, addresses: &vector<address>): u64
Implementation
Function active_validators
Return the active validators in self
public fun active_validators(self: &validator_set::ValidatorSet): &vector<validator::Validator>
Implementation
Function is_validator_candidate
Returns true if the addr is a validator candidate.
public fun is_validator_candidate(self: &validator_set::ValidatorSet, addr: address): bool
Implementation
Function is_inactive_validator
Returns true if the staking pool identified by staking_pool_id is of an inactive validator.
public fun is_inactive_validator(self: &validator_set::ValidatorSet, staking_pool_id: object::ID): bool
Implementation
Function active_validator_addresses
public(friend) fun active_validator_addresses(self: &validator_set::ValidatorSet): vector<address>