Skip to main content

Module 0x3::iota_system

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

The simplest and one that doesn't involve a real upgrade is to just add dynamic fields to the extra_fields field of IotaSystemStateV1 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 IotaSystemStateV1 type, we need to ship a new framework that does the following:

  1. Define a new IotaSystemStatetype (e.g. IotaSystemStateV2).
  2. Define a data migration function that migrates the old (e.g. IotaSystemStateV1) to the new one (e.g. IotaSystemStateV2).
  3. Replace all uses of IotaSystemStateV1 with IotaSystemStateV2 in both iota_system.move and iota_system_state_inner.move, with the exception of the iota_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 iota/tests/framework_upgrades/mock_iota_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 IotaSystemState struct type that matches the new Move type, and implement the IotaSystemStateTrait.
  6. Update the IotaSystemState struct to include the new version as a new enum variant.
  7. Update the get_iota_system_state function to handle the new version. To test that the upgrade will be successful, we need to modify iota_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 ValidatorV1 to the new one (i.e. ValidatorV2).
  3. Replace all uses of ValidatorV1 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 IotaSystemStateV1 without upgrading ValidatorV1, but not the other way around. And when we only upgrade IotaSystemStateV1, the version of ValidatorV1 in the wrapper will not be updated, and hence may become inconsistent with the version of IotaSystemStateV1. This is fine as long as we don't use the ValidatorV1 version to determine the IotaSystemStateV1 version, or vice versa.
use 0x1::option;
use 0x2::balance;
use 0x2::coin;
use 0x2::dynamic_field;
use 0x2::iota;
use 0x2::object;
use 0x2::system_admin_cap;
use 0x2::table;
use 0x2::transfer;
use 0x2::tx_context;
use 0x2::vec_map;
use 0x3::iota_system_state_inner;
use 0x3::staking_pool;
use 0x3::validator;
use 0x3::validator_cap;

Resource IotaSystemState​

struct IotaSystemState has key
Fields
id: object::UID
version: u64

Constants​

const ENotSystemAddress: u64 = 0;
const EWrongInnerVersion: u64 = 1;

Function create​

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

public(friend) fun create(id: object::UID, iota_treasury_cap: iota::IotaTreasuryCap, validators: vector<validator::ValidatorV1>, storage_fund: balance::Balance<iota::IOTA>, protocol_version: u64, epoch_start_timestamp_ms: u64, parameters: iota_system_state_inner::SystemParametersV1, iota_system_admin_cap: system_admin_cap::IotaSystemAdminCap, ctx: &mut tx_context::TxContext)
Implementation
public(package) fun create(
id: UID,
iota_treasury_cap: IotaTreasuryCap,
validators: vector<ValidatorV1>,
storage_fund: Balance<IOTA>,
protocol_version: u64,
epoch_start_timestamp_ms: u64,
parameters: SystemParametersV1,
iota_system_admin_cap: IotaSystemAdminCap,
ctx: &mut TxContext,
) {
let system_state = iota_system_state_inner::create(
iota_treasury_cap,
validators,
storage_fund,
protocol_version,
epoch_start_timestamp_ms,
parameters,
iota_system_admin_cap,
ctx,
);
let version = iota_system_state_inner::genesis_system_state_version();
let mut self = IotaSystemState {
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 iota_address and authority_pubkey_bytes. To produce a valid PoP, run [fn test_proof_of_possession].

public entry fun request_add_validator_candidate(wrapper: &mut iota_system::IotaSystemState, authority_pubkey_bytes: vector<u8>, network_pubkey_bytes: vector<u8>, protocol_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>, gas_price: u64, commission_rate: u64, ctx: &mut tx_context::TxContext)
Implementation
public entry fun request_add_validator_candidate(
wrapper: &mut IotaSystemState,
authority_pubkey_bytes: vector<u8>,
network_pubkey_bytes: vector<u8>,
protocol_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>,
gas_price: u64,
commission_rate: u64,
ctx: &mut TxContext,
) {
let self = load_system_state_mut(wrapper);
self.request_add_validator_candidate(
authority_pubkey_bytes,
network_pubkey_bytes,
protocol_pubkey_bytes,
proof_of_possession,
name,
description,
image_url,
project_url,
net_address,
p2p_address,
primary_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 iota_system::IotaSystemState, ctx: &mut tx_context::TxContext)
Implementation
public entry fun request_remove_validator_candidate(
wrapper: &mut IotaSystemState,
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 iota_system::IotaSystemState, ctx: &mut tx_context::TxContext)
Implementation
public entry fun request_add_validator(
wrapper: &mut IotaSystemState,
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 iota_address in the validator). At the end of the epoch, the validator object will be returned to the iota_address of the validator.

public entry fun request_remove_validator(wrapper: &mut iota_system::IotaSystemState, ctx: &mut tx_context::TxContext)
Implementation
public entry fun request_remove_validator(
wrapper: &mut IotaSystemState,
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 iota_system::IotaSystemState, cap: &validator_cap::UnverifiedValidatorOperationCap, new_gas_price: u64)
Implementation
public entry fun request_set_gas_price(
wrapper: &mut IotaSystemState,
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 iota_system::IotaSystemState, cap: &validator_cap::UnverifiedValidatorOperationCap, new_gas_price: u64)
Implementation
public entry fun set_candidate_validator_gas_price(
wrapper: &mut IotaSystemState,
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 iota_system::IotaSystemState, new_commission_rate: u64, ctx: &mut tx_context::TxContext)
Implementation
public entry fun request_set_commission_rate(
wrapper: &mut IotaSystemState,
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 iota_system::IotaSystemState, new_commission_rate: u64, ctx: &mut tx_context::TxContext)
Implementation
public entry fun set_candidate_validator_commission_rate(
wrapper: &mut IotaSystemState,
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 iota_system::IotaSystemState, stake: coin::Coin<iota::IOTA>, validator_address: address, ctx: &mut tx_context::TxContext)
Implementation
public entry fun request_add_stake(
wrapper: &mut IotaSystemState,
stake: Coin<IOTA>,
validator_address: address,
ctx: &mut TxContext,
) {
let staked_iota = request_add_stake_non_entry(wrapper, stake, validator_address, ctx);
transfer::public_transfer(staked_iota, ctx.sender());
}

Function request_add_stake_non_entry​

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

public fun request_add_stake_non_entry(wrapper: &mut iota_system::IotaSystemState, stake: coin::Coin<iota::IOTA>, validator_address: address, ctx: &mut tx_context::TxContext): staking_pool::StakedIota
Implementation
public fun request_add_stake_non_entry(
wrapper: &mut IotaSystemState,
stake: Coin<IOTA>,
validator_address: address,
ctx: &mut TxContext,
): StakedIota {
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 iota_system::IotaSystemState, stakes: vector<coin::Coin<iota::IOTA>>, stake_amount: option::Option<u64>, validator_address: address, ctx: &mut tx_context::TxContext)
Implementation
public entry fun request_add_stake_mul_coin(
wrapper: &mut IotaSystemState,
stakes: vector<Coin<IOTA>>,
stake_amount: option::Option<u64>,
validator_address: address,
ctx: &mut TxContext,
) {
let self = load_system_state_mut(wrapper);
let staked_iota = self.request_add_stake_mul_coin(stakes, stake_amount, validator_address, ctx);
transfer::public_transfer(staked_iota, ctx.sender());
}

Function request_withdraw_stake​

Withdraw stake from a validator's staking pool.

public entry fun request_withdraw_stake(wrapper: &mut iota_system::IotaSystemState, staked_iota: staking_pool::StakedIota, ctx: &mut tx_context::TxContext)
Implementation
public entry fun request_withdraw_stake(
wrapper: &mut IotaSystemState,
staked_iota: StakedIota,
ctx: &mut TxContext,
) {
let withdrawn_stake = request_withdraw_stake_non_entry(wrapper, staked_iota, ctx);
transfer::public_transfer(withdrawn_stake.into_coin(ctx), ctx.sender());
}

Function request_withdraw_stake_non_entry​

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

public fun request_withdraw_stake_non_entry(wrapper: &mut iota_system::IotaSystemState, staked_iota: staking_pool::StakedIota, ctx: &mut tx_context::TxContext): balance::Balance<iota::IOTA>
Implementation
public fun request_withdraw_stake_non_entry(
wrapper: &mut IotaSystemState,
staked_iota: StakedIota,
ctx: &mut TxContext,
) : Balance<IOTA> {
let self = load_system_state_mut(wrapper);
self.request_withdraw_stake(staked_iota, 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 iota_system::IotaSystemState, cap: &validator_cap::UnverifiedValidatorOperationCap, reportee_addr: address)
Implementation
public entry fun report_validator(
wrapper: &mut IotaSystemState,
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 iota_system::IotaSystemState, cap: &validator_cap::UnverifiedValidatorOperationCap, reportee_addr: address)
Implementation
public entry fun undo_report_validator(
wrapper: &mut IotaSystemState,
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 iota_system::IotaSystemState, ctx: &mut tx_context::TxContext)
Implementation
public entry fun rotate_operation_cap(
self: &mut IotaSystemState,
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 iota_system::IotaSystemState, name: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_validator_name(
self: &mut IotaSystemState,
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 iota_system::IotaSystemState, description: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_validator_description(
self: &mut IotaSystemState,
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 iota_system::IotaSystemState, image_url: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_validator_image_url(
self: &mut IotaSystemState,
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 iota_system::IotaSystemState, project_url: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_validator_project_url(
self: &mut IotaSystemState,
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 iota_system::IotaSystemState, network_address: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_validator_next_epoch_network_address(
self: &mut IotaSystemState,
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 iota_system::IotaSystemState, network_address: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_candidate_validator_network_address(
self: &mut IotaSystemState,
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 iota_system::IotaSystemState, p2p_address: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_validator_next_epoch_p2p_address(
self: &mut IotaSystemState,
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 iota_system::IotaSystemState, p2p_address: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_candidate_validator_p2p_address(
self: &mut IotaSystemState,
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 primary address. The change will only take effects starting from the next epoch.

public entry fun update_validator_next_epoch_primary_address(self: &mut iota_system::IotaSystemState, primary_address: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_validator_next_epoch_primary_address(
self: &mut IotaSystemState,
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 primary address.

public entry fun update_candidate_validator_primary_address(self: &mut iota_system::IotaSystemState, primary_address: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_candidate_validator_primary_address(
self: &mut IotaSystemState,
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_authority_pubkey​

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

public entry fun update_validator_next_epoch_authority_pubkey(self: &mut iota_system::IotaSystemState, authority_pubkey: vector<u8>, proof_of_possession: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_validator_next_epoch_authority_pubkey(
self: &mut IotaSystemState,
authority_pubkey: vector<u8>,
proof_of_possession: vector<u8>,
ctx: &TxContext,
) {
let self = load_system_state_mut(self);
self.update_validator_next_epoch_authority_pubkey(authority_pubkey, proof_of_possession, ctx)
}

Function update_candidate_validator_authority_pubkey​

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

public entry fun update_candidate_validator_authority_pubkey(self: &mut iota_system::IotaSystemState, authority_pubkey: vector<u8>, proof_of_possession: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_candidate_validator_authority_pubkey(
self: &mut IotaSystemState,
authority_pubkey: vector<u8>,
proof_of_possession: vector<u8>,
ctx: &TxContext,
) {
let self = load_system_state_mut(self);
self.update_candidate_validator_authority_pubkey(authority_pubkey, proof_of_possession, ctx)
}

Function update_validator_next_epoch_protocol_pubkey​

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

public entry fun update_validator_next_epoch_protocol_pubkey(self: &mut iota_system::IotaSystemState, protocol_pubkey: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_validator_next_epoch_protocol_pubkey(
self: &mut IotaSystemState,
protocol_pubkey: vector<u8>,
ctx: &TxContext,
) {
let self = load_system_state_mut(self);
self.update_validator_next_epoch_protocol_pubkey(protocol_pubkey, ctx)
}

Function update_candidate_validator_protocol_pubkey​

Update candidate validator's public key of protocol key.

public entry fun update_candidate_validator_protocol_pubkey(self: &mut iota_system::IotaSystemState, protocol_pubkey: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_candidate_validator_protocol_pubkey(
self: &mut IotaSystemState,
protocol_pubkey: vector<u8>,
ctx: &TxContext,
) {
let self = load_system_state_mut(self);
self.update_candidate_validator_protocol_pubkey(protocol_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 iota_system::IotaSystemState, network_pubkey: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_validator_next_epoch_network_pubkey(
self: &mut IotaSystemState,
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 iota_system::IotaSystemState, network_pubkey: vector<u8>, ctx: &tx_context::TxContext)
Implementation
public entry fun update_candidate_validator_network_pubkey(
self: &mut IotaSystemState,
network_pubkey: vector<u8>,
ctx: &TxContext,
) {
let self = load_system_state_mut(self);
self.update_candidate_validator_network_pubkey(network_pubkey, ctx)
}

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 iota_system::IotaSystemState, pool_id: &object::ID): &table::Table<u64, staking_pool::PoolTokenExchangeRate>
Implementation
public fun pool_exchange_rates(
wrapper: &mut IotaSystemState,
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 iota_system::IotaSystemState): vector<address>
Implementation
public fun active_validator_addresses(wrapper: &mut IotaSystemState): vector<address> {
let self = load_system_state(wrapper);
self.active_validator_addresses()
}

Function load_iota_system_admin_cap​

Returns the IOTA system admin capability reference.

public(friend) fun load_iota_system_admin_cap(self: &mut iota_system::IotaSystemState): &system_admin_cap::IotaSystemAdminCap
Implementation
public(package) fun load_iota_system_admin_cap(self: &mut IotaSystemState): &IotaSystemAdminCap {
self.load_system_state().iota_system_admin_cap()
}

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. Mint or burn IOTA tokens depending on whether the validator target reward is greater or smaller than the computation reward.
  4. Distribute the target reward to the validators.
  5. Burn any leftover rewards.
  6. Update all validators.
fun advance_epoch(validator_target_reward: u64, storage_charge: balance::Balance<iota::IOTA>, computation_reward: balance::Balance<iota::IOTA>, wrapper: &mut iota_system::IotaSystemState, new_epoch: u64, next_protocol_version: u64, storage_rebate: u64, non_refundable_storage_fee: u64, reward_slashing_rate: u64, epoch_start_timestamp_ms: u64, ctx: &mut tx_context::TxContext): balance::Balance<iota::IOTA>
Implementation
fun advance_epoch(
validator_target_reward: u64,
storage_charge: Balance<IOTA>,
computation_reward: Balance<IOTA>,
wrapper: &mut IotaSystemState,
new_epoch: u64,
next_protocol_version: u64,
storage_rebate: u64,
non_refundable_storage_fee: u64,
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<IOTA> {
let self = load_system_state_mut(wrapper);
// ValidatorV1 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,
validator_target_reward,
storage_charge,
computation_reward,
storage_rebate,
non_refundable_storage_fee,
reward_slashing_rate,
epoch_start_timestamp_ms,
ctx,
);
storage_rebate
}

Function load_system_state​

fun load_system_state(self: &mut iota_system::IotaSystemState): &iota_system_state_inner::IotaSystemStateV1
Implementation
fun load_system_state(self: &mut IotaSystemState): &IotaSystemStateV1 {
load_inner_maybe_upgrade(self)
}

Function load_system_state_mut​

fun load_system_state_mut(self: &mut iota_system::IotaSystemState): &mut iota_system_state_inner::IotaSystemStateV1
Implementation
fun load_system_state_mut(self: &mut IotaSystemState): &mut IotaSystemStateV1 {
load_inner_maybe_upgrade(self)
}

Function load_inner_maybe_upgrade​

fun load_inner_maybe_upgrade(self: &mut iota_system::IotaSystemState): &mut iota_system_state_inner::IotaSystemStateV1
Implementation
fun load_inner_maybe_upgrade(self: &mut IotaSystemState): &mut IotaSystemStateV1 {
let inner: &mut IotaSystemStateV1 = 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 iota_system::IotaSystemState): vec_map::VecMap<address, u64>
Implementation

Function get_total_iota_supply​

Returns the total iota supply.

public fun get_total_iota_supply(wrapper: &mut iota_system::IotaSystemState): u64
Implementation
public fun get_total_iota_supply(wrapper: &mut IotaSystemState): u64 {
let self = load_system_state(wrapper);
self.get_total_iota_supply()
}