[staking] add more comments and clean up code

crates/sui-cost/tests/snapshots/empirical_transaction_cost__good_snapshot-2.snap

@@ -4,13 +4,13 @@ expression: common_costs_estimate
 ---
 {
   "MergeCoin": {
-    "computation_cost": 5776,
-    "storage_cost": 8526,
+    "computation_cost": 5792,
+    "storage_cost": 8550,
     "storage_rebate": 0
   },
   "Publish": {
-    "computation_cost": 5764,
-    "storage_cost": 8461,
+    "computation_cost": 5781,
+    "storage_cost": 8485,
     "storage_rebate": 0
   },
   "SharedCounterAssertValue": {
@@ -29,8 +29,8 @@ expression: common_costs_estimate
     "storage_rebate": 0
   },
   "SplitCoin": {
-    "computation_cost": 5754,
-    "storage_cost": 8493,
+    "computation_cost": 5770,
+    "storage_cost": 8518,
     "storage_rebate": 0
   },
   "TransferPortionSuiCoin": {

crates/sui-cost/tests/snapshots/empirical_transaction_cost__good_snapshot.snap

@@ -4,12 +4,12 @@ expression: common_costs_actual
 ---
 {
   "MergeCoin": {
-    "computation_cost": 694,
+    "computation_cost": 696,
     "storage_cost": 32,
     "storage_rebate": 0
   },
   "Publish": {
-    "computation_cost": 750,
+    "computation_cost": 752,
     "storage_cost": 83,
     "storage_rebate": 0
   },
@@ -29,7 +29,7 @@ expression: common_costs_actual
     "storage_rebate": 15
   },
   "SplitCoin": {
-    "computation_cost": 820,
+    "computation_cost": 822,
     "storage_cost": 80,
     "storage_rebate": 0
   },

crates/sui-framework/docs/sui_system.md

@@ -218,7 +218,7 @@ The top-level object containing all information of the Sui system.
 ## Function `create`
 
 Create a new SuiSystemState object and make it shared.
-This function will be called only once in Genesis.
+This function will be called only once in genesis.
 
 
 <pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="sui_system.md#0x2_sui_system_create">create</a>(validators: <a href="">vector</a>&lt;<a href="validator.md#0x2_validator_Validator">validator::Validator</a>&gt;, sui_supply: <a href="balance.md#0x2_balance_Supply">balance::Supply</a>&lt;<a href="sui.md#0x2_sui_SUI">sui::SUI</a>&gt;, storage_fund: <a href="balance.md#0x2_balance_Balance">balance::Balance</a>&lt;<a href="sui.md#0x2_sui_SUI">sui::SUI</a>&gt;, max_validator_candidate_count: u64, min_validator_stake: u64, storage_gas_price: u64)
@@ -539,6 +539,7 @@ If the sender represents an active validator, the request will be processed at t
 
 ## Function `request_add_delegation`
 
+Add delegated stake to a validator's staking pool.
 
 
 <pre><code><b>public</b> entry <b>fun</b> <a href="sui_system.md#0x2_sui_system_request_add_delegation">request_add_delegation</a>(self: &<b>mut</b> <a href="sui_system.md#0x2_sui_system_SuiSystemState">sui_system::SuiSystemState</a>, delegate_stake: <a href="coin.md#0x2_coin_Coin">coin::Coin</a>&lt;<a href="sui.md#0x2_sui_SUI">sui::SUI</a>&gt;, validator_address: <b>address</b>, ctx: &<b>mut</b> <a href="tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
@@ -574,6 +575,7 @@ If the sender represents an active validator, the request will be processed at t
 
 ## Function `request_add_delegation_with_locked_coin`
 
+Add delegated stake to a validator's staking pool using a locked SUI coin.
 
 
 <pre><code><b>public</b> entry <b>fun</b> <a href="sui_system.md#0x2_sui_system_request_add_delegation_with_locked_coin">request_add_delegation_with_locked_coin</a>(self: &<b>mut</b> <a href="sui_system.md#0x2_sui_system_SuiSystemState">sui_system::SuiSystemState</a>, delegate_stake: <a href="locked_coin.md#0x2_locked_coin_LockedCoin">locked_coin::LockedCoin</a>&lt;<a href="sui.md#0x2_sui_SUI">sui::SUI</a>&gt;, validator_address: <b>address</b>, ctx: &<b>mut</b> <a href="tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
@@ -604,6 +606,7 @@ If the sender represents an active validator, the request will be processed at t
 
 ## Function `request_withdraw_delegation`
 
+Withdraw some portion of a delegation from a validator's staking pool.
 
 
 <pre><code><b>public</b> entry <b>fun</b> <a href="sui_system.md#0x2_sui_system_request_withdraw_delegation">request_withdraw_delegation</a>(self: &<b>mut</b> <a href="sui_system.md#0x2_sui_system_SuiSystemState">sui_system::SuiSystemState</a>, delegation: &<b>mut</b> <a href="staking_pool.md#0x2_staking_pool_Delegation">staking_pool::Delegation</a>, staked_sui: &<b>mut</b> <a href="staking_pool.md#0x2_staking_pool_StakedSui">staking_pool::StakedSui</a>, withdraw_pool_token_amount: u64, ctx: &<b>mut</b> <a href="tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)

crates/sui-framework/docs/validator.md

@@ -15,13 +15,12 @@
 -  [Function `request_withdraw_stake`](#0x2_validator_request_withdraw_stake)
 -  [Function `adjust_stake_and_gas_price`](#0x2_validator_adjust_stake_and_gas_price)
 -  [Function `request_add_delegation`](#0x2_validator_request_add_delegation)
--  [Function `increase_next_epoch_delegation`](#0x2_validator_increase_next_epoch_delegation)
 -  [Function `request_withdraw_delegation`](#0x2_validator_request_withdraw_delegation)
 -  [Function `decrease_next_epoch_delegation`](#0x2_validator_decrease_next_epoch_delegation)
 -  [Function `request_set_gas_price`](#0x2_validator_request_set_gas_price)
 -  [Function `request_set_commission_rate`](#0x2_validator_request_set_commission_rate)
--  [Function `distribute_rewards`](#0x2_validator_distribute_rewards)
--  [Function `process_pending_delegations`](#0x2_validator_process_pending_delegations)
+-  [Function `deposit_delegation_rewards`](#0x2_validator_deposit_delegation_rewards)
+-  [Function `process_pending_delegations_and_withdraws`](#0x2_validator_process_pending_delegations_and_withdraws)
 -  [Function `get_staking_pool_mut_ref`](#0x2_validator_get_staking_pool_mut_ref)
 -  [Function `metadata`](#0x2_validator_metadata)
 -  [Function `sui_address`](#0x2_validator_sui_address)
@@ -425,7 +424,7 @@ stake still satisfy the minimum requirement.
 
 ## Function `adjust_stake_and_gas_price`
 
-Process pending stake and pending withdraws.
+Process pending stake and pending withdraws, and update the gas price.
 
 
 <pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_adjust_stake_and_gas_price">adjust_stake_and_gas_price</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">validator::Validator</a>)
@@ -455,6 +454,7 @@ Process pending stake and pending withdraws.
 
 ## Function `request_add_delegation`
 
+Request to add delegation to the validator's staking pool, processed at the end of the epoch.
 
 
 <pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_request_add_delegation">request_add_delegation</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">validator::Validator</a>, delegated_stake: <a href="balance.md#0x2_balance_Balance">balance::Balance</a>&lt;<a href="sui.md#0x2_sui_SUI">sui::SUI</a>&gt;, locking_period: <a href="_Option">option::Option</a>&lt;<a href="epoch_time_lock.md#0x2_epoch_time_lock_EpochTimeLock">epoch_time_lock::EpochTimeLock</a>&gt;, delegator: <b>address</b>, ctx: &<b>mut</b> <a href="tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
@@ -476,32 +476,7 @@ Process pending stake and pending withdraws.
     <b>let</b> delegate_amount = <a href="balance.md#0x2_balance_value">balance::value</a>(&delegated_stake);
     <b>assert</b>!(delegate_amount &gt; 0, 0);
     <a href="staking_pool.md#0x2_staking_pool_request_add_delegation">staking_pool::request_add_delegation</a>(&<b>mut</b> self.delegation_staking_pool, delegated_stake, locking_period, delegator, ctx);
-
-    <a href="validator.md#0x2_validator_increase_next_epoch_delegation">increase_next_epoch_delegation</a>(self, delegate_amount);
-}
-</code></pre>
-
-
-
-</details>
-
-<a name="0x2_validator_increase_next_epoch_delegation"></a>
-
-## Function `increase_next_epoch_delegation`
-
-
-
-<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_increase_next_epoch_delegation">increase_next_epoch_delegation</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">validator::Validator</a>, amount: u64)
-</code></pre>
-
-
-
-<details>
-<summary>Implementation</summary>
-
-
-<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_increase_next_epoch_delegation">increase_next_epoch_delegation</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">Validator</a>, amount: u64) {
-    self.metadata.next_epoch_delegation = self.metadata.next_epoch_delegation + amount;
+    self.metadata.next_epoch_delegation = self.metadata.next_epoch_delegation + delegate_amount;
 }
 </code></pre>
 
@@ -513,6 +488,7 @@ Process pending stake and pending withdraws.
 
 ## Function `request_withdraw_delegation`
 
+Request to withdraw delegation from the validator's staking pool, processed at the end of the epoch.
 
 
 <pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_request_withdraw_delegation">request_withdraw_delegation</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">validator::Validator</a>, delegation: &<b>mut</b> <a href="staking_pool.md#0x2_staking_pool_Delegation">staking_pool::Delegation</a>, staked_sui: &<b>mut</b> <a href="staking_pool.md#0x2_staking_pool_StakedSui">staking_pool::StakedSui</a>, withdraw_pool_token_amount: u64, ctx: &<b>mut</b> <a href="tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
@@ -531,7 +507,7 @@ Process pending stake and pending withdraws.
     withdraw_pool_token_amount: u64,
     ctx: &<b>mut</b> TxContext,
 ) {
-    <b>let</b> withdraw_sui_amount = <a href="staking_pool.md#0x2_staking_pool_request_withdraw_stake">staking_pool::request_withdraw_stake</a>(
+    <b>let</b> withdraw_sui_amount = <a href="staking_pool.md#0x2_staking_pool_request_withdraw_delegation">staking_pool::request_withdraw_delegation</a>(
             &<b>mut</b> self.delegation_staking_pool, delegation, staked_sui, withdraw_pool_token_amount, ctx);
     <a href="validator.md#0x2_validator_decrease_next_epoch_delegation">decrease_next_epoch_delegation</a>(self, withdraw_sui_amount);
 }
@@ -545,6 +521,7 @@ Process pending stake and pending withdraws.
 
 ## Function `decrease_next_epoch_delegation`
 
+Decrement the delegation amount for next epoch. Also called by <code><a href="validator_set.md#0x2_validator_set">validator_set</a></code> when handling delegation switches.
 
 
 <pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_decrease_next_epoch_delegation">decrease_next_epoch_delegation</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">validator::Validator</a>, amount: u64)
@@ -569,6 +546,7 @@ Process pending stake and pending withdraws.
 
 ## Function `request_set_gas_price`
 
+Request to set new gas price for the next epoch.
 
 
 <pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_request_set_gas_price">request_set_gas_price</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">validator::Validator</a>, new_price: u64)
@@ -613,13 +591,14 @@ Process pending stake and pending withdraws.
 
 </details>
 
-<a name="0x2_validator_distribute_rewards"></a>
+<a name="0x2_validator_deposit_delegation_rewards"></a>
 
-## Function `distribute_rewards`
+## Function `deposit_delegation_rewards`
 
+Deposit delegations rewards into the validator's staking pool, called at the end of the epoch.
 
 
-<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_distribute_rewards">distribute_rewards</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">validator::Validator</a>, reward: <a href="balance.md#0x2_balance_Balance">balance::Balance</a>&lt;<a href="sui.md#0x2_sui_SUI">sui::SUI</a>&gt;, ctx: &<b>mut</b> <a href="tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
+<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_deposit_delegation_rewards">deposit_delegation_rewards</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">validator::Validator</a>, reward: <a href="balance.md#0x2_balance_Balance">balance::Balance</a>&lt;<a href="sui.md#0x2_sui_SUI">sui::SUI</a>&gt;)
 </code></pre>
 
 
@@ -628,24 +607,24 @@ Process pending stake and pending withdraws.
 <summary>Implementation</summary>
 
 
-<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_distribute_rewards">distribute_rewards</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">Validator</a>, reward: Balance&lt;SUI&gt;, ctx: &<b>mut</b> TxContext) {
+<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_deposit_delegation_rewards">deposit_delegation_rewards</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">Validator</a>, reward: Balance&lt;SUI&gt;) {
     self.metadata.next_epoch_delegation = self.metadata.next_epoch_delegation + <a href="balance.md#0x2_balance_value">balance::value</a>(&reward);
-    <b>let</b> reward_withdraw = <a href="staking_pool.md#0x2_staking_pool_distribute_rewards">staking_pool::distribute_rewards</a>(&<b>mut</b> self.delegation_staking_pool, reward, ctx);
-    self.metadata.next_epoch_delegation = self.metadata.next_epoch_delegation - reward_withdraw;
+    <a href="staking_pool.md#0x2_staking_pool_deposit_rewards">staking_pool::deposit_rewards</a>(&<b>mut</b> self.delegation_staking_pool, reward);
 }
 </code></pre>
 
 
 
 </details>
 
-<a name="0x2_validator_process_pending_delegations"></a>
+<a name="0x2_validator_process_pending_delegations_and_withdraws"></a>
 
-## Function `process_pending_delegations`
+## Function `process_pending_delegations_and_withdraws`
 
+Process pending delegations and withdraws, called at the end of the epoch.
 
 
-<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_process_pending_delegations">process_pending_delegations</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">validator::Validator</a>, ctx: &<b>mut</b> <a href="tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
+<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_process_pending_delegations_and_withdraws">process_pending_delegations_and_withdraws</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">validator::Validator</a>, ctx: &<b>mut</b> <a href="tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
 </code></pre>
 
 
@@ -654,8 +633,11 @@ Process pending stake and pending withdraws.
 <summary>Implementation</summary>
 
 
-<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_process_pending_delegations">process_pending_delegations</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">Validator</a>, ctx: &<b>mut</b> TxContext) {
-    <b>let</b> _sui_deposit = <a href="staking_pool.md#0x2_staking_pool_process_pending_delegations">staking_pool::process_pending_delegations</a>(&<b>mut</b> self.delegation_staking_pool, ctx);
+<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_process_pending_delegations_and_withdraws">process_pending_delegations_and_withdraws</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">Validator</a>, ctx: &<b>mut</b> TxContext) {
+    <a href="staking_pool.md#0x2_staking_pool_process_pending_delegations">staking_pool::process_pending_delegations</a>(&<b>mut</b> self.delegation_staking_pool, ctx);
+    <b>let</b> reward_withdraw_amount = <a href="staking_pool.md#0x2_staking_pool_process_pending_delegation_withdraws">staking_pool::process_pending_delegation_withdraws</a>(
+        &<b>mut</b> self.delegation_staking_pool, ctx);
+    self.metadata.next_epoch_delegation = self.metadata.next_epoch_delegation - reward_withdraw_amount;
     <b>assert</b>!(<a href="validator.md#0x2_validator_delegate_amount">delegate_amount</a>(self) == self.metadata.next_epoch_delegation, 0);
 }
 </code></pre>
@@ -668,6 +650,7 @@ Process pending stake and pending withdraws.
 
 ## Function `get_staking_pool_mut_ref`
 
+Called by <code><a href="validator_set.md#0x2_validator_set">validator_set</a></code> for handling delegation switches.
 
 
 <pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="validator.md#0x2_validator_get_staking_pool_mut_ref">get_staking_pool_mut_ref</a>(self: &<b>mut</b> <a href="validator.md#0x2_validator_Validator">validator::Validator</a>): &<b>mut</b> <a href="staking_pool.md#0x2_staking_pool_StakingPool">staking_pool::StakingPool</a>