Skip to main content

Module 0x3::sui_system

Sui System State Type Upgrade Guide SuiSystemState is a thin wrapper around SuiSystemStateInner that provides a versioned interface. The SuiSystemState object has a fixed ID 0x5, and the SuiSystemStateInner object is stored as a dynamic field. There are a few different ways to upgrade the SuiSystemStateInner type:

The simplest and one that doesn't involve a real upgrade is to just add dynamic fields to the extra_fields field of SuiSystemStateInner or any of its sub type. This is useful when we are in a rush, or making a small change, or still experimenting a new field.

To properly upgrade the SuiSystemStateInner type, we need to ship a new framework that does the following:

  1. Define a new SuiSystemStateInnertype (e.g. SuiSystemStateInnerV2).
  2. Define a data migration function that migrates the old SuiSystemStateInner to the new one (i.e. SuiSystemStateInnerV2).
  3. Replace all uses of SuiSystemStateInner with SuiSystemStateInnerV2 in both sui_system.move and sui_system_state_inner.move, with the exception of the sui_system_state_inner::create function, which should always return the genesis type.
  4. Inside load_inner_maybe_upgrade function, check the current version in the wrapper, and if it's not the latest version, call the data migration function to upgrade the inner object. Make sure to also update the version in the wrapper. A detailed example can be found in sui/tests/framework_upgrades/mock_sui_systems/shallow_upgrade. Along with the Move change, we also need to update the Rust code to support the new type. This includes:
  5. Define a new SuiSystemStateInner struct type that matches the new Move type, and implement the SuiSystemStateTrait.
  6. Update the SuiSystemState struct to include the new version as a new enum variant.
  7. Update the get_sui_system_state function to handle the new version. To test that the upgrade will be successful, we need to modify sui_system_state_production_upgrade_test test in protocol_version_tests and trigger a real upgrade using the new framework. We will need to keep this directory as old version, put the new framework in a new directory, and run the test to exercise the upgrade.

To upgrade Validator type, besides everything above, we also need to:

  1. Define a new Validator type (e.g. ValidatorV2).
  2. Define a data migration function that migrates the old Validator to the new one (i.e. ValidatorV2).
  3. Replace all uses of Validator with ValidatorV2 except the genesis creation function.
  4. In validator_wrapper::upgrade_to_latest, check the current version in the wrapper, and if it's not the latest version, call the data migration function to upgrade it. In Rust, we also need to add a new case in get_validator_from_table. Note that it is possible to upgrade SuiSystemStateInner without upgrading Validator, but not the other way around. And when we only upgrade SuiSystemStateInner, the version of Validator in the wrapper will not be updated, and hence may become inconsistent with the version of SuiSystemStateInner. This is fine as long as we don't use the Validator version to determine the SuiSystemStateInner version, or vice versa.
use 0x1::option;
use 0x2::balance;
use 0x2::coin;
use 0x2::dynamic_field;
use 0x2::object;
use 0x2::sui;
use 0x2::table;
use 0x2::transfer;
use 0x2::tx_context;
use 0x2::vec_map;
use 0x3::stake_subsidy;
use 0x3::staking_pool;
use 0x3::sui_system_state_inner;
use 0x3::validator;
use 0x3::validator_cap;

Resource SuiSystemState​

struct SuiSystemState has key
Click to open
Fields
id: object::UID
version: u64

Constants​

const ENotSystemAddress: u64 = 0;


const EWrongInnerVersion: u64 = 1;

Function create​

Create a new SuiSystemState object and make it shared. This function will be called only once in genesis.

public(friend) fun create(id: object::UID, validators: vector<validator::Validator>, storage_fund: balance::Balance<sui::SUI>, protocol_version: u64, epoch_start_timestamp_ms: u64, parameters: sui_system_state_inner::SystemParameters, stake_subsidy: stake_subsidy::StakeSubsidy, ctx: &mut tx_context::TxContext)
Click to open
Implementation
public(package) fun create(
    id: UID,
    validators: vector<Validator>,
    storage_fund: Balance<SUI>,
    protocol_version: u64,
    epoch_start_timestamp_ms: u64,
    parameters: SystemParameters,
    stake_subsidy: StakeSubsidy,
    ctx: &mut TxContext,
) {
    let system_state = sui_system_state_inner::create(
        validators,
        storage_fund,
        protocol_version,
        epoch_start_timestamp_ms,
        parameters,
        stake_subsidy,
        ctx,
    );
    let version = sui_system_state_inner::genesis_system_state_version();
    let mut self = SuiSystemState {
        id,
        version,
    };
    dynamic_field::add(&mut self.id, version, system_state);
    transfer::share_object(self);
}

Function request_add_validator_candidate​

Can be called by anyone who wishes to become a validator candidate and starts accuring delegated stakes in their staking pool. Once they have at least MIN_VALIDATOR_JOINING_STAKE amount of stake they can call request_add_validator to officially become an active validator at the next epoch. Aborts if the caller is already a pending or active validator, or a validator candidate. Note: proof_of_possession MUST be a valid signature using sui_address and protocol_pubkey_bytes. To produce a valid PoP, run [fn test_proof_of_possession].

public entry fun request_add_validator_candidate(wrapper: &mut sui_system::SuiSystemState, pubkey_bytes: vector<u8>, network_pubkey_bytes: vector<u8>, worker_pubkey_bytes: vector<u8>, proof_of_possession: vector<u8>, name: vector<u8>, description: vector<u8>, image_url: vector<u8>, project_url: vector<u8>, net_address: vector<u8>, p2p_address: vector<u8>, primary_address: vector<u8>, worker_address: vector<u8>, gas_price: u64, commission_rate: u64, ctx: &mut tx_context::TxContext)
Click to open
Implementation
public entry fun request_add_validator_candidate(
    wrapper: &mut SuiSystemState,
    pubkey_bytes: vector<u8>,
    network_pubkey_bytes: vector<u8>,
    worker_pubkey_bytes: vector<u8>,
    proof_of_possession: vector<u8>,
    name: vector<u8>,
    description: vector<u8>,
    image_url: vector<u8>,
    project_url: vector<u8>,
    net_address: vector<u8>,
    p2p_address: vector<u8>,
    primary_address: vector<u8>,
    worker_address: vector<u8>,
    gas_price: u64,
    commission_rate: u64,
    ctx: &mut TxContext,
) {
    let self = load_system_state_mut(wrapper);
    self.request_add_validator_candidate(
        pubkey_bytes,
        network_pubkey_bytes,
        worker_pubkey_bytes,
        proof_of_possession,
        name,
        description,
        image_url,
        project_url,
        net_address,
        p2p_address,
        primary_address,
        worker_address,
        gas_price,
        commission_rate,
        ctx,
    )
}

Function request_remove_validator_candidate​

Called by a validator candidate to remove themselves from the candidacy. After this call their staking pool becomes deactivate.

public entry fun request_remove_validator_candidate(wrapper: &mut sui_system::SuiSystemState, ctx: &mut tx_context::TxContext)
Click to open
Implementation
public entry fun request_remove_validator_candidate(
    wrapper: &mut SuiSystemState,
    ctx: &mut TxContext,
) {
    let self = load_system_state_mut(wrapper);
    self.request_remove_validator_candidate(ctx)
}

Function request_add_validator​

Called by a validator candidate to add themselves to the active validator set beginning next epoch. Aborts if the validator is a duplicate with one of the pending or active validators, or if the amount of stake the validator has doesn't meet the min threshold, or if the number of new validators for the next epoch has already reached the maximum.

public entry fun request_add_validator(wrapper: &mut sui_system::SuiSystemState, ctx: &mut tx_context::TxContext)
Click to open
Implementation
public entry fun request_add_validator(
    wrapper: &mut SuiSystemState,
    ctx: &mut TxContext,
) {
    let self = load_system_state_mut(wrapper);
    self.request_add_validator(ctx)
}

Function request_remove_validator​

A validator can call this function to request a removal in the next epoch. We use the sender of ctx to look up the validator (i.e. sender must match the sui_address in the validator). At the end of the epoch, the validator object will be returned to the sui_address of the validator.

public entry fun request_remove_validator(wrapper: &mut sui_system::SuiSystemState, ctx: &mut tx_context::TxContext)
Click to open
Implementation
public entry fun request_remove_validator(
    wrapper: &mut SuiSystemState,
    ctx: &mut TxContext,
) {
    let self = load_system_state_mut(wrapper);
    self.request_remove_validator(ctx)
}

Function request_set_gas_price​

A validator can call this entry function to submit a new gas price quote, to be used for the reference gas price calculation at the end of the epoch.

public entry fun request_set_gas_price(wrapper: &mut sui_system::SuiSystemState, cap: &validator_cap::UnverifiedValidatorOperationCap, new_gas_price: u64)
Click to open
Implementation
public entry fun request_set_gas_price(
    wrapper: &mut SuiSystemState,
    cap: &UnverifiedValidatorOperationCap,
    new_gas_price: u64,
) {
    let self = load_system_state_mut(wrapper);
    self.request_set_gas_price(cap, new_gas_price)
}

Function set_candidate_validator_gas_price​

This entry function is used to set new gas price for candidate validators

public entry fun set_candidate_validator_gas_price(wrapper: &mut sui_system::SuiSystemState, cap: &validator_cap::UnverifiedValidatorOperationCap, new_gas_price: u64)
Click to open
Implementation
public entry fun set_candidate_validator_gas_price(
    wrapper: &mut SuiSystemState,
    cap: &UnverifiedValidatorOperationCap,
    new_gas_price: u64,
) {
    let self = load_system_state_mut(wrapper);
    self.set_candidate_validator_gas_price(cap, new_gas_price)
}

Function request_set_commission_rate​

A validator can call this entry function to set a new commission rate, updated at the end of the epoch.

public entry fun request_set_commission_rate(wrapper: &mut sui_system::SuiSystemState, new_commission_rate: u64, ctx: &mut tx_context::TxContext)
Click to open
Implementation
public entry fun request_set_commission_rate(
    wrapper: &mut SuiSystemState,
    new_commission_rate: u64,
    ctx: &mut TxContext,
) {
    let self = load_system_state_mut(wrapper);
    self.request_set_commission_rate(new_commission_rate, ctx)
}

Function set_candidate_validator_commission_rate​

This entry function is used to set new commission rate for candidate validators

public entry fun set_candidate_validator_commission_rate(wrapper: &mut sui_system::SuiSystemState, new_commission_rate: u64, ctx: &mut tx_context::TxContext)
Click to open
Implementation
public entry fun set_candidate_validator_commission_rate(
    wrapper: &mut SuiSystemState,
    new_commission_rate: u64,
    ctx: &mut TxContext,
) {
    let self = load_system_state_mut(wrapper);
    self.set_candidate_validator_commission_rate(new_commission_rate, ctx)
}

Function request_add_stake​

Add stake to a validator's staking pool.

public entry fun request_add_stake(wrapper: &mut sui_system::SuiSystemState, stake: coin::Coin<sui::SUI>, validator_address: address, ctx: &mut tx_context::TxContext)
Click to open
Implementation
public entry fun request_add_stake(
    wrapper: &mut SuiSystemState,
    stake: Coin<SUI>,
    validator_address: address,
    ctx: &mut TxContext,
) {
    let staked_sui = request_add_stake_non_entry(wrapper, stake, validator_address, ctx);
    transfer::public_transfer(staked_sui, ctx.sender());
}

Function request_add_stake_non_entry​

The non-entry version of request_add_stake, which returns the staked SUI instead of transferring it to the sender.

public fun request_add_stake_non_entry(wrapper: &mut sui_system::SuiSystemState, stake: coin::Coin<sui::SUI>, validator_address: address, ctx: &mut tx_context::TxContext): staking_pool::StakedSui
Click to open
Implementation
public fun request_add_stake_non_entry(
    wrapper: &mut SuiSystemState,
    stake: Coin<SUI>,
    validator_address: address,
    ctx: &mut TxContext,
): StakedSui {
    let self = load_system_state_mut(wrapper);
    self.request_add_stake(stake, validator_address, ctx)
}

Function request_add_stake_mul_coin​

Add stake to a validator's staking pool using multiple coins.

public entry fun request_add_stake_mul_coin(wrapper: &mut sui_system::SuiSystemState, stakes: vector<coin::Coin<sui::SUI>>, stake_amount: option::Option<u64>, validator_address: address, ctx: &mut tx_context::TxContext)
Click to open
Implementation
public entry fun request_add_stake_mul_coin(
    wrapper: &mut SuiSystemState,
    stakes: vector<Coin<SUI>>,
    stake_amount: option::Option<u64>,
    validator_address: address,
    ctx: &mut TxContext,
) {
    let self = load_system_state_mut(wrapper);
    let staked_sui = self.request_add_stake_mul_coin(stakes, stake_amount, validator_address, ctx);
    transfer::public_transfer(staked_sui, ctx.sender());
}

Function request_withdraw_stake​

Withdraw stake from a validator's staking pool.

public entry fun request_withdraw_stake(wrapper: &mut sui_system::SuiSystemState, staked_sui: staking_pool::StakedSui, ctx: &mut tx_context::TxContext)
Click to open
Implementation
public entry fun request_withdraw_stake(
    wrapper: &mut SuiSystemState,
    staked_sui: StakedSui,
    ctx: &mut TxContext,
) {
    let withdrawn_stake = request_withdraw_stake_non_entry(wrapper, staked_sui, ctx);
    transfer::public_transfer(withdrawn_stake.into_coin(ctx), ctx.sender());
}

Function convert_to_fungible_staked_sui​

Convert StakedSui into a FungibleStakedSui object.

public fun convert_to_fungible_staked_sui(wrapper: &mut sui_system::SuiSystemState, staked_sui: staking_pool::StakedSui, ctx: &mut tx_context::TxContext): staking_pool::FungibleStakedSui
Click to open
Implementation
public fun convert_to_fungible_staked_sui(
    wrapper: &mut SuiSystemState,
    staked_sui: StakedSui,
    ctx: &mut TxContext,
): FungibleStakedSui {
    let self = load_system_state_mut(wrapper);
    self.convert_to_fungible_staked_sui(staked_sui, ctx)
}

Function redeem_fungible_staked_sui​

Convert FungibleStakedSui into a StakedSui object.

public fun redeem_fungible_staked_sui(wrapper: &mut sui_system::SuiSystemState, fungible_staked_sui: staking_pool::FungibleStakedSui, ctx: &tx_context::TxContext): balance::Balance<sui::SUI>
Click to open
Implementation
public fun redeem_fungible_staked_sui(
    wrapper: &mut SuiSystemState,
    fungible_staked_sui: FungibleStakedSui,
    ctx: &TxContext,
): Balance<SUI> {
    let self = load_system_state_mut(wrapper);
    self.redeem_fungible_staked_sui(fungible_staked_sui, ctx)
}

Function request_withdraw_stake_non_entry​

Non-entry version of request_withdraw_stake that returns the withdrawn SUI instead of transferring it to the sender.

public fun request_withdraw_stake_non_entry(wrapper: &mut sui_system::SuiSystemState, staked_sui: staking_pool::StakedSui, ctx: &mut tx_context::TxContext): balance::Balance<sui::SUI>
Click to open
Implementation
public fun request_withdraw_stake_non_entry(
    wrapper: &mut SuiSystemState,
    staked_sui: StakedSui,
    ctx: &mut TxContext,
) : Balance<SUI> {
    let self = load_system_state_mut(wrapper);
    self.request_withdraw_stake(staked_sui, ctx)
}

Function report_validator​

Report a validator as a bad or non-performant actor in the system. Succeeds if all the following are satisfied:

  1. both the reporter in cap and the input reportee_addr are active validators.
  2. reporter and reportee not the same address.
  3. the cap object is still valid. This function is idempotent.
public entry fun report_validator(wrapper: &mut sui_system::SuiSystemState, cap: &validator_cap::UnverifiedValidatorOperationCap, reportee_addr: address)
Click to open
Implementation
public entry fun report_validator(
    wrapper: &mut SuiSystemState,
    cap: &UnverifiedValidatorOperationCap,
    reportee_addr: address,
) {
    let self = load_system_state_mut(wrapper);
    self.report_validator(cap, reportee_addr)
}

Function undo_report_validator​

Undo a report_validator action. Aborts if

  1. the reportee is not a currently active validator or
  2. the sender has not previously reported the reportee_addr, or
  3. the cap is not valid
public entry fun undo_report_validator(wrapper: &mut sui_system::SuiSystemState, cap: &validator_cap::UnverifiedValidatorOperationCap, reportee_addr: address)
Click to open
Implementation
public entry fun undo_report_validator(
    wrapper: &mut SuiSystemState,
    cap: &UnverifiedValidatorOperationCap,
    reportee_addr: address,
) {
    let self = load_system_state_mut(wrapper);
    self.undo_report_validator(cap, reportee_addr)
}

Function rotate_operation_cap​

Create a new UnverifiedValidatorOperationCap, transfer it to the validator and registers it. The original object is thus revoked.

public entry fun rotate_operation_cap(self: &mut sui_system::SuiSystemState, ctx: &mut tx_context::TxContext)
Click to open
Implementation
public entry fun rotate_operation_cap(
    self: &mut SuiSystemState,
    ctx: &mut TxContext,
) {
    let self = load_system_state_mut(self);
    self.rotate_operation_cap(ctx)
}

Function update_validator_name​

Update a validator's name.

public entry fun update_validator_name(self: &mut sui_system::SuiSystemState, name: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_validator_name(
    self: &mut SuiSystemState,
    name: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_validator_name(name, ctx)
}

Function update_validator_description​

Update a validator's description

public entry fun update_validator_description(self: &mut sui_system::SuiSystemState, description: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_validator_description(
    self: &mut SuiSystemState,
    description: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_validator_description(description, ctx)
}

Function update_validator_image_url​

Update a validator's image url

public entry fun update_validator_image_url(self: &mut sui_system::SuiSystemState, image_url: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_validator_image_url(
    self: &mut SuiSystemState,
    image_url: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_validator_image_url(image_url, ctx)
}

Function update_validator_project_url​

Update a validator's project url

public entry fun update_validator_project_url(self: &mut sui_system::SuiSystemState, project_url: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_validator_project_url(
    self: &mut SuiSystemState,
    project_url: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_validator_project_url(project_url, ctx)
}

Function update_validator_next_epoch_network_address​

Update a validator's network address. The change will only take effects starting from the next epoch.

public entry fun update_validator_next_epoch_network_address(self: &mut sui_system::SuiSystemState, network_address: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_validator_next_epoch_network_address(
    self: &mut SuiSystemState,
    network_address: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_validator_next_epoch_network_address(network_address, ctx)
}

Function update_candidate_validator_network_address​

Update candidate validator's network address.

public entry fun update_candidate_validator_network_address(self: &mut sui_system::SuiSystemState, network_address: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_candidate_validator_network_address(
    self: &mut SuiSystemState,
    network_address: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_candidate_validator_network_address(network_address, ctx)
}

Function update_validator_next_epoch_p2p_address​

Update a validator's p2p address. The change will only take effects starting from the next epoch.

public entry fun update_validator_next_epoch_p2p_address(self: &mut sui_system::SuiSystemState, p2p_address: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_validator_next_epoch_p2p_address(
    self: &mut SuiSystemState,
    p2p_address: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_validator_next_epoch_p2p_address(p2p_address, ctx)
}

Function update_candidate_validator_p2p_address​

Update candidate validator's p2p address.

public entry fun update_candidate_validator_p2p_address(self: &mut sui_system::SuiSystemState, p2p_address: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_candidate_validator_p2p_address(
    self: &mut SuiSystemState,
    p2p_address: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_candidate_validator_p2p_address(p2p_address, ctx)
}

Function update_validator_next_epoch_primary_address​

Update a validator's narwhal primary address. The change will only take effects starting from the next epoch.

public entry fun update_validator_next_epoch_primary_address(self: &mut sui_system::SuiSystemState, primary_address: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_validator_next_epoch_primary_address(
    self: &mut SuiSystemState,
    primary_address: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_validator_next_epoch_primary_address(primary_address, ctx)
}

Function update_candidate_validator_primary_address​

Update candidate validator's narwhal primary address.

public entry fun update_candidate_validator_primary_address(self: &mut sui_system::SuiSystemState, primary_address: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_candidate_validator_primary_address(
    self: &mut SuiSystemState,
    primary_address: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_candidate_validator_primary_address(primary_address, ctx)
}

Function update_validator_next_epoch_worker_address​

Update a validator's narwhal worker address. The change will only take effects starting from the next epoch.

public entry fun update_validator_next_epoch_worker_address(self: &mut sui_system::SuiSystemState, worker_address: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_validator_next_epoch_worker_address(
    self: &mut SuiSystemState,
    worker_address: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_validator_next_epoch_worker_address(worker_address, ctx)
}

Function update_candidate_validator_worker_address​

Update candidate validator's narwhal worker address.

public entry fun update_candidate_validator_worker_address(self: &mut sui_system::SuiSystemState, worker_address: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_candidate_validator_worker_address(
    self: &mut SuiSystemState,
    worker_address: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_candidate_validator_worker_address(worker_address, ctx)
}

Function update_validator_next_epoch_protocol_pubkey​

Update a validator's public key of protocol key and proof of possession. The change will only take effects starting from the next epoch.

public entry fun update_validator_next_epoch_protocol_pubkey(self: &mut sui_system::SuiSystemState, protocol_pubkey: vector<u8>, proof_of_possession: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_validator_next_epoch_protocol_pubkey(
    self: &mut SuiSystemState,
    protocol_pubkey: vector<u8>,
    proof_of_possession: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_validator_next_epoch_protocol_pubkey(protocol_pubkey, proof_of_possession, ctx)
}

Function update_candidate_validator_protocol_pubkey​

Update candidate validator's public key of protocol key and proof of possession.

public entry fun update_candidate_validator_protocol_pubkey(self: &mut sui_system::SuiSystemState, protocol_pubkey: vector<u8>, proof_of_possession: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_candidate_validator_protocol_pubkey(
    self: &mut SuiSystemState,
    protocol_pubkey: vector<u8>,
    proof_of_possession: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_candidate_validator_protocol_pubkey(protocol_pubkey, proof_of_possession, ctx)
}

Function update_validator_next_epoch_worker_pubkey​

Update a validator's public key of worker key. The change will only take effects starting from the next epoch.

public entry fun update_validator_next_epoch_worker_pubkey(self: &mut sui_system::SuiSystemState, worker_pubkey: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_validator_next_epoch_worker_pubkey(
    self: &mut SuiSystemState,
    worker_pubkey: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_validator_next_epoch_worker_pubkey(worker_pubkey, ctx)
}

Function update_candidate_validator_worker_pubkey​

Update candidate validator's public key of worker key.

public entry fun update_candidate_validator_worker_pubkey(self: &mut sui_system::SuiSystemState, worker_pubkey: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_candidate_validator_worker_pubkey(
    self: &mut SuiSystemState,
    worker_pubkey: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_candidate_validator_worker_pubkey(worker_pubkey, ctx)
}

Function update_validator_next_epoch_network_pubkey​

Update a validator's public key of network key. The change will only take effects starting from the next epoch.

public entry fun update_validator_next_epoch_network_pubkey(self: &mut sui_system::SuiSystemState, network_pubkey: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_validator_next_epoch_network_pubkey(
    self: &mut SuiSystemState,
    network_pubkey: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_validator_next_epoch_network_pubkey(network_pubkey, ctx)
}

Function update_candidate_validator_network_pubkey​

Update candidate validator's public key of network key.

public entry fun update_candidate_validator_network_pubkey(self: &mut sui_system::SuiSystemState, network_pubkey: vector<u8>, ctx: &tx_context::TxContext)
Click to open
Implementation
public entry fun update_candidate_validator_network_pubkey(
    self: &mut SuiSystemState,
    network_pubkey: vector<u8>,
    ctx: &TxContext,
) {
    let self = load_system_state_mut(self);
    self.update_candidate_validator_network_pubkey(network_pubkey, ctx)
}

Function validator_address_by_pool_id​

public fun validator_address_by_pool_id(wrapper: &mut sui_system::SuiSystemState, pool_id: &object::ID): address
Click to open
Implementation
public fun validator_address_by_pool_id(wrapper: &mut SuiSystemState, pool_id: &ID): address {
    let self = load_system_state_mut(wrapper);
    self.validator_address_by_pool_id(pool_id)
}

Function pool_exchange_rates​

Getter of the pool token exchange rate of a staking pool. Works for both active and inactive pools.

public fun pool_exchange_rates(wrapper: &mut sui_system::SuiSystemState, pool_id: &object::ID): &table::Table<u64, staking_pool::PoolTokenExchangeRate>
Click to open
Implementation
public fun pool_exchange_rates(
    wrapper: &mut SuiSystemState,
    pool_id: &ID
): &Table<u64, PoolTokenExchangeRate>  {
    let self = load_system_state_mut(wrapper);
    self.pool_exchange_rates(pool_id)
}

Function active_validator_addresses​

Getter returning addresses of the currently active validators.

public fun active_validator_addresses(wrapper: &mut sui_system::SuiSystemState): vector<address>
Click to open
Implementation
public fun active_validator_addresses(wrapper: &mut SuiSystemState): vector<address> {
    let self = load_system_state(wrapper);
    self.active_validator_addresses()
}

Function advance_epoch​

This function should be called at the end of an epoch, and advances the system to the next epoch. It does the following things:

  1. Add storage charge to the storage fund.
  2. Burn the storage rebates from the storage fund. These are already refunded to transaction sender's gas coins.
  3. Distribute computation charge to validator stake.
  4. Update all validators.
fun advance_epoch(storage_reward: balance::Balance<sui::SUI>, computation_reward: balance::Balance<sui::SUI>, wrapper: &mut sui_system::SuiSystemState, new_epoch: u64, next_protocol_version: u64, storage_rebate: u64, non_refundable_storage_fee: u64, storage_fund_reinvest_rate: u64, reward_slashing_rate: u64, epoch_start_timestamp_ms: u64, ctx: &mut tx_context::TxContext): balance::Balance<sui::SUI>
Click to open
Implementation
fun advance_epoch(
    storage_reward: Balance<SUI>,
    computation_reward: Balance<SUI>,
    wrapper: &mut SuiSystemState,
    new_epoch: u64,
    next_protocol_version: u64,
    storage_rebate: u64,
    non_refundable_storage_fee: u64,
    storage_fund_reinvest_rate: u64, // share of storage fund's rewards that's reinvested
                                     // into storage fund, in basis point.
    reward_slashing_rate: u64, // how much rewards are slashed to punish a validator, in bps.
    epoch_start_timestamp_ms: u64, // Timestamp of the epoch start
    ctx: &mut TxContext,
) : Balance<SUI> {
    let self = load_system_state_mut(wrapper);
    // Validator will make a special system call with sender set as 0x0.
    assert!(ctx.sender() == @0x0, ENotSystemAddress);
    let storage_rebate = self.advance_epoch(
        new_epoch,
        next_protocol_version,
        storage_reward,
        computation_reward,
        storage_rebate,
        non_refundable_storage_fee,
        storage_fund_reinvest_rate,
        reward_slashing_rate,
        epoch_start_timestamp_ms,
        ctx,
    );

    storage_rebate
}

Function load_system_state​

fun load_system_state(self: &mut sui_system::SuiSystemState): &sui_system_state_inner::SuiSystemStateInnerV2
Click to open
Implementation
fun load_system_state(self: &mut SuiSystemState): &SuiSystemStateInnerV2 {
    load_inner_maybe_upgrade(self)
}

Function load_system_state_mut​

fun load_system_state_mut(self: &mut sui_system::SuiSystemState): &mut sui_system_state_inner::SuiSystemStateInnerV2
Click to open
Implementation
fun load_system_state_mut(self: &mut SuiSystemState): &mut SuiSystemStateInnerV2 {
    load_inner_maybe_upgrade(self)
}

Function load_inner_maybe_upgrade​

fun load_inner_maybe_upgrade(self: &mut sui_system::SuiSystemState): &mut sui_system_state_inner::SuiSystemStateInnerV2
Click to open
Implementation
fun load_inner_maybe_upgrade(self: &mut SuiSystemState): &mut SuiSystemStateInnerV2 {
    if (self.version == 1) {
      let v1: SuiSystemStateInner = dynamic_field::remove(&mut self.id, self.version);
      let v2 = v1.v1_to_v2();
      self.version = 2;
      dynamic_field::add(&mut self.id, self.version, v2);
    };

    let inner: &mut SuiSystemStateInnerV2 = dynamic_field::borrow_mut(
        &mut self.id,
        self.version
    );
    assert!(inner.system_state_version() == self.version, EWrongInnerVersion);
    inner
}

Function validator_voting_powers​

Returns the voting power of the active validators, values are voting power in the scale of 10000.

fun validator_voting_powers(wrapper: &mut sui_system::SuiSystemState): vec_map::VecMap<address, u64>
Click to open
Implementation
fun validator_voting_powers(wrapper: &mut SuiSystemState): VecMap<address, u64> {
    let self = load_system_state(wrapper);
    sui_system_state_inner::active_validator_voting_powers(self)
}