feat(iota-framework): replace storage_fund with storage deposits

crates/iota-framework/docs/iota-system/genesis.md

@@ -367,7 +367,7 @@ all the information we need in the system.
     } = token_distribution_schedule;
 
     <b>let</b> subsidy_fund = iota_supply.split(stake_subsidy_fund_micros);
-    <b>let</b> <a href="storage_fund.md#0x3_storage_fund">storage_fund</a> = <a href="../iota-framework/balance.md#0x2_balance_zero">balance::zero</a>();
+    <b>let</b> storage_fund = <a href="../iota-framework/balance.md#0x2_balance_zero">balance::zero</a>();
 
     // Create all the `Validator` structs
     <b>let</b> <b>mut</b> validators = <a href="../move-stdlib/vector.md#0x1_vector">vector</a>[];
@@ -459,7 +459,7 @@ all the information we need in the system.
         iota_system_state_id,
         iota_treasury_cap,
         validators,
-        <a href="storage_fund.md#0x3_storage_fund">storage_fund</a>,
+        storage_fund,
         genesis_chain_parameters.protocol_version,
         genesis_chain_parameters.chain_start_timestamp_ms,
         system_parameters,

crates/iota-framework/docs/iota-system/iota_system.md

@@ -167,7 +167,7 @@ Create a new IotaSystemState object and make it shared.
 This function will be called only once in genesis.
 
 
-<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="iota_system.md#0x3_iota_system_create">create</a>(id: <a href="../iota-framework/object.md#0x2_object_UID">object::UID</a>, iota_treasury_cap: <a href="../iota-framework/coin.md#0x2_coin_TreasuryCap">coin::TreasuryCap</a>&lt;<a href="../iota-framework/iota.md#0x2_iota_IOTA">iota::IOTA</a>&gt;, validators: <a href="../move-stdlib/vector.md#0x1_vector">vector</a>&lt;<a href="validator.md#0x3_validator_Validator">validator::Validator</a>&gt;, <a href="storage_fund.md#0x3_storage_fund">storage_fund</a>: <a href="../iota-framework/balance.md#0x2_balance_Balance">balance::Balance</a>&lt;<a href="../iota-framework/iota.md#0x2_iota_IOTA">iota::IOTA</a>&gt;, protocol_version: u64, epoch_start_timestamp_ms: u64, parameters: <a href="iota_system_state_inner.md#0x3_iota_system_state_inner_SystemParameters">iota_system_state_inner::SystemParameters</a>, <a href="stake_subsidy.md#0x3_stake_subsidy">stake_subsidy</a>: <a href="stake_subsidy.md#0x3_stake_subsidy_StakeSubsidy">stake_subsidy::StakeSubsidy</a>, ctx: &<b>mut</b> <a href="../iota-framework/tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
+<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="iota_system.md#0x3_iota_system_create">create</a>(id: <a href="../iota-framework/object.md#0x2_object_UID">object::UID</a>, iota_treasury_cap: <a href="../iota-framework/coin.md#0x2_coin_TreasuryCap">coin::TreasuryCap</a>&lt;<a href="../iota-framework/iota.md#0x2_iota_IOTA">iota::IOTA</a>&gt;, validators: <a href="../move-stdlib/vector.md#0x1_vector">vector</a>&lt;<a href="validator.md#0x3_validator_Validator">validator::Validator</a>&gt;, <a href="storage_deposits.md#0x3_storage_deposits">storage_deposits</a>: <a href="../iota-framework/balance.md#0x2_balance_Balance">balance::Balance</a>&lt;<a href="../iota-framework/iota.md#0x2_iota_IOTA">iota::IOTA</a>&gt;, protocol_version: u64, epoch_start_timestamp_ms: u64, parameters: <a href="iota_system_state_inner.md#0x3_iota_system_state_inner_SystemParameters">iota_system_state_inner::SystemParameters</a>, <a href="stake_subsidy.md#0x3_stake_subsidy">stake_subsidy</a>: <a href="stake_subsidy.md#0x3_stake_subsidy_StakeSubsidy">stake_subsidy::StakeSubsidy</a>, ctx: &<b>mut</b> <a href="../iota-framework/tx_context.md#0x2_tx_context_TxContext">tx_context::TxContext</a>)
 </code></pre>
 
 
@@ -180,7 +180,7 @@ This function will be called only once in genesis.
     id: UID,
     iota_treasury_cap: TreasuryCap&lt;IOTA&gt;,
     validators: <a href="../move-stdlib/vector.md#0x1_vector">vector</a>&lt;Validator&gt;,
-    <a href="storage_fund.md#0x3_storage_fund">storage_fund</a>: Balance&lt;IOTA&gt;,
+    <a href="storage_deposits.md#0x3_storage_deposits">storage_deposits</a>: Balance&lt;IOTA&gt;,
     protocol_version: u64,
     epoch_start_timestamp_ms: u64,
     parameters: SystemParameters,
@@ -190,7 +190,7 @@ This function will be called only once in genesis.
     <b>let</b> system_state = <a href="iota_system_state_inner.md#0x3_iota_system_state_inner_create">iota_system_state_inner::create</a>(
         iota_treasury_cap,
         validators,
-        <a href="storage_fund.md#0x3_storage_fund">storage_fund</a>,
+        <a href="storage_deposits.md#0x3_storage_deposits">storage_deposits</a>,
         protocol_version,
         epoch_start_timestamp_ms,
         parameters,

crates/iota-framework/docs/iota-system/iota_system_state_inner.md

@@ -57,8 +57,7 @@ title: Module `0x3::iota_system_state_inner`
 -  [Function `validator_staking_pool_id`](#0x3_iota_system_state_inner_validator_staking_pool_id)
 -  [Function `validator_staking_pool_mappings`](#0x3_iota_system_state_inner_validator_staking_pool_mappings)
 -  [Function `get_reporters_of`](#0x3_iota_system_state_inner_get_reporters_of)
--  [Function `get_storage_fund_total_balance`](#0x3_iota_system_state_inner_get_storage_fund_total_balance)
--  [Function `get_storage_fund_object_rebates`](#0x3_iota_system_state_inner_get_storage_fund_object_rebates)
+-  [Function `get_storage_deposits_total_balance`](#0x3_iota_system_state_inner_get_storage_deposits_total_balance)
 -  [Function `pool_exchange_rates`](#0x3_iota_system_state_inner_pool_exchange_rates)
 -  [Function `active_validator_addresses`](#0x3_iota_system_state_inner_active_validator_addresses)
 -  [Function `extract_coin_balance`](#0x3_iota_system_state_inner_extract_coin_balance)
@@ -79,7 +78,7 @@ title: Module `0x3::iota_system_state_inner`
 <b>use</b> <a href="../iota-framework/vec_set.md#0x2_vec_set">0x2::vec_set</a>;
 <b>use</b> <a href="stake_subsidy.md#0x3_stake_subsidy">0x3::stake_subsidy</a>;
 <b>use</b> <a href="staking_pool.md#0x3_staking_pool">0x3::staking_pool</a>;
-<b>use</b> <a href="storage_fund.md#0x3_storage_fund">0x3::storage_fund</a>;
+<b>use</b> <a href="storage_deposits.md#0x3_storage_deposits">0x3::storage_deposits</a>;
 <b>use</b> <a href="validator.md#0x3_validator">0x3::validator</a>;
 <b>use</b> <a href="validator_cap.md#0x3_validator_cap">0x3::validator_cap</a>;
 <b>use</b> <a href="validator_set.md#0x3_validator_set">0x3::validator_set</a>;
@@ -293,7 +292,7 @@ The top-level object containing all information of the Iota system.
  Contains all information about the validators.
 </dd>
 <dt>
-<code><a href="storage_fund.md#0x3_storage_fund">storage_fund</a>: <a href="storage_fund.md#0x3_storage_fund_StorageFund">storage_fund::StorageFund</a></code>
+<code><a href="storage_deposits.md#0x3_storage_deposits">storage_deposits</a>: <a href="storage_deposits.md#0x3_storage_deposits_StorageDeposits">storage_deposits::StorageDeposits</a></code>
 </dt>
 <dd>
  The storage fund.
@@ -431,7 +430,7 @@ Uses SystemParametersV2 as the parameters.
  Contains all information about the validators.
 </dd>
 <dt>
-<code><a href="storage_fund.md#0x3_storage_fund">storage_fund</a>: <a href="storage_fund.md#0x3_storage_fund_StorageFund">storage_fund::StorageFund</a></code>
+<code><a href="storage_deposits.md#0x3_storage_deposits">storage_deposits</a>: <a href="storage_deposits.md#0x3_storage_deposits_StorageDeposits">storage_deposits::StorageDeposits</a></code>
 </dt>
 <dd>
  The storage fund.
@@ -775,7 +774,7 @@ This function will be called only once in genesis.
         system_state_version: <a href="iota_system_state_inner.md#0x3_iota_system_state_inner_genesis_system_state_version">genesis_system_state_version</a>(),
         iota_treasury_cap,
         validators,
-        <a href="storage_fund.md#0x3_storage_fund">storage_fund</a>: <a href="storage_fund.md#0x3_storage_fund_new">storage_fund::new</a>(initial_storage_fund),
+        <a href="storage_deposits.md#0x3_storage_deposits">storage_deposits</a>: <a href="storage_deposits.md#0x3_storage_deposits_new">storage_deposits::new</a>(initial_storage_fund),
         parameters,
         reference_gas_price,
         validator_report_records: <a href="../iota-framework/vec_map.md#0x2_vec_map_empty">vec_map::empty</a>(),
@@ -862,7 +861,7 @@ This function will be called only once in genesis.
         system_state_version: _,
         iota_treasury_cap,
         validators,
-        <a href="storage_fund.md#0x3_storage_fund">storage_fund</a>,
+        <a href="storage_deposits.md#0x3_storage_deposits">storage_deposits</a>,
         parameters,
         reference_gas_price,
         validator_report_records,
@@ -891,7 +890,7 @@ This function will be called only once in genesis.
         system_state_version: 2,
         iota_treasury_cap,
         validators,
-        <a href="storage_fund.md#0x3_storage_fund">storage_fund</a>,
+        <a href="storage_deposits.md#0x3_storage_deposits">storage_deposits</a>,
         parameters: <a href="iota_system_state_inner.md#0x3_iota_system_state_inner_SystemParametersV2">SystemParametersV2</a> {
             epoch_duration_ms,
             stake_subsidy_start_epoch,
@@ -2114,8 +2113,8 @@ gas coins.
     self.safe_mode_non_refundable_storage_fee = 0;
 
     <b>let</b> total_validators_stake = self.validators.total_stake();
-    <b>let</b> storage_fund_balance = self.<a href="storage_fund.md#0x3_storage_fund">storage_fund</a>.total_balance();
-    <b>let</b> total_stake = storage_fund_balance + total_validators_stake;
+    <b>let</b> storage_deposits_balance = self.<a href="storage_deposits.md#0x3_storage_deposits">storage_deposits</a>.total_balance();
+    <b>let</b> total_stake = storage_deposits_balance + total_validators_stake;
 
     <b>let</b> storage_charge = storage_reward.value();
     <b>let</b> computation_charge = computation_reward.value();
@@ -2138,7 +2137,7 @@ gas coins.
     <b>let</b> total_stake_u128 = total_stake <b>as</b> u128;
     <b>let</b> computation_charge_u128 = computation_charge <b>as</b> u128;
 
-    <b>let</b> storage_fund_reward_amount = storage_fund_balance <b>as</b> u128 * computation_charge_u128 / total_stake_u128;
+    <b>let</b> storage_fund_reward_amount = storage_deposits_balance <b>as</b> u128 * computation_charge_u128 / total_stake_u128;
     <b>let</b> <b>mut</b> storage_fund_reward = computation_reward.split(storage_fund_reward_amount <b>as</b> u64);
 
     self.epoch = self.epoch + 1;
@@ -2179,7 +2178,7 @@ gas coins.
 
     self.iota_treasury_cap.supply_mut().decrease_supply(leftover_staking_rewards);
     <b>let</b> refunded_storage_rebate =
-        self.<a href="storage_fund.md#0x3_storage_fund">storage_fund</a>.<a href="iota_system_state_inner.md#0x3_iota_system_state_inner_advance_epoch">advance_epoch</a>(
+        self.<a href="storage_deposits.md#0x3_storage_deposits">storage_deposits</a>.<a href="iota_system_state_inner.md#0x3_iota_system_state_inner_advance_epoch">advance_epoch</a>(
             storage_reward,
             storage_rebate_amount,
             non_refundable_storage_fee_amount,
@@ -2193,7 +2192,7 @@ gas coins.
             total_stake: new_total_stake,
             storage_charge,
             storage_rebate: storage_rebate_amount,
-            storage_fund_balance: self.<a href="storage_fund.md#0x3_storage_fund">storage_fund</a>.total_balance(),
+            storage_fund_balance: self.<a href="storage_deposits.md#0x3_storage_deposits">storage_deposits</a>.total_balance(),
             stake_subsidy_amount,
             total_gas_fees: computation_charge,
             total_stake_rewards_distributed: computation_reward_distributed + storage_fund_reward_distributed,
@@ -2450,13 +2449,13 @@ Returns all the validators who are currently reporting <code>addr</code>
 
 </details>
 
-<a name="0x3_iota_system_state_inner_get_storage_fund_total_balance"></a>
+<a name="0x3_iota_system_state_inner_get_storage_deposits_total_balance"></a>
 
-## Function `get_storage_fund_total_balance`
+## Function `get_storage_deposits_total_balance`
 
 
 
-<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="iota_system_state_inner.md#0x3_iota_system_state_inner_get_storage_fund_total_balance">get_storage_fund_total_balance</a>(self: &<a href="iota_system_state_inner.md#0x3_iota_system_state_inner_IotaSystemStateInnerV2">iota_system_state_inner::IotaSystemStateInnerV2</a>): u64
+<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="iota_system_state_inner.md#0x3_iota_system_state_inner_get_storage_deposits_total_balance">get_storage_deposits_total_balance</a>(self: &<a href="iota_system_state_inner.md#0x3_iota_system_state_inner_IotaSystemStateInnerV2">iota_system_state_inner::IotaSystemStateInnerV2</a>): u64
 </code></pre>
 
 
@@ -2465,32 +2464,8 @@ Returns all the validators who are currently reporting <code>addr</code>
 <summary>Implementation</summary>
 
 
-<pre><code><b>public</b>(package) <b>fun</b> <a href="iota_system_state_inner.md#0x3_iota_system_state_inner_get_storage_fund_total_balance">get_storage_fund_total_balance</a>(self: &<a href="iota_system_state_inner.md#0x3_iota_system_state_inner_IotaSystemStateInnerV2">IotaSystemStateInnerV2</a>): u64 {
-    self.<a href="storage_fund.md#0x3_storage_fund">storage_fund</a>.total_balance()
-}
-</code></pre>
-
-
-
-</details>
-
-<a name="0x3_iota_system_state_inner_get_storage_fund_object_rebates"></a>
-
-## Function `get_storage_fund_object_rebates`
-
-
-
-<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="iota_system_state_inner.md#0x3_iota_system_state_inner_get_storage_fund_object_rebates">get_storage_fund_object_rebates</a>(self: &<a href="iota_system_state_inner.md#0x3_iota_system_state_inner_IotaSystemStateInnerV2">iota_system_state_inner::IotaSystemStateInnerV2</a>): u64
-</code></pre>
-
-
-
-<details>
-<summary>Implementation</summary>
-
-
-<pre><code><b>public</b>(package) <b>fun</b> <a href="iota_system_state_inner.md#0x3_iota_system_state_inner_get_storage_fund_object_rebates">get_storage_fund_object_rebates</a>(self: &<a href="iota_system_state_inner.md#0x3_iota_system_state_inner_IotaSystemStateInnerV2">IotaSystemStateInnerV2</a>): u64 {
-    self.<a href="storage_fund.md#0x3_storage_fund">storage_fund</a>.total_object_storage_rebates()
+<pre><code><b>public</b>(package) <b>fun</b> <a href="iota_system_state_inner.md#0x3_iota_system_state_inner_get_storage_deposits_total_balance">get_storage_deposits_total_balance</a>(self: &<a href="iota_system_state_inner.md#0x3_iota_system_state_inner_IotaSystemStateInnerV2">IotaSystemStateInnerV2</a>): u64 {
+    self.<a href="storage_deposits.md#0x3_storage_deposits">storage_deposits</a>.total_balance()
 }
 </code></pre>
 

crates/iota-framework/docs/iota-system/storage_deposits.md

@@ -0,0 +1,143 @@
+---
+title: Module `0x3::storage_deposits`
+---
+
+
+
+-  [Struct `StorageDeposits`](#0x3_storage_deposits_StorageDeposits)
+-  [Function `new`](#0x3_storage_deposits_new)
+-  [Function `advance_epoch`](#0x3_storage_deposits_advance_epoch)
+-  [Function `total_balance`](#0x3_storage_deposits_total_balance)
+
+
+<pre><code><b>use</b> <a href="../iota-framework/balance.md#0x2_balance">0x2::balance</a>;
+<b>use</b> <a href="../iota-framework/iota.md#0x2_iota">0x2::iota</a>;
+</code></pre>
+
+
+
+<a name="0x3_storage_deposits_StorageDeposits"></a>
+
+## Struct `StorageDeposits`
+
+Struct representing the storage fund, containing two <code>Balance</code>s:
+- <code>storage_balance</code> has the invariant that it's the sum of <code>storage_rebate</code> of
+all objects currently stored on-chain. To maintain this invariant, the only inflow of this
+balance is storage charges collected from transactions, and the only outflow is storage rebates
+of transactions.
+
+
+<pre><code><b>struct</b> <a href="storage_deposits.md#0x3_storage_deposits_StorageDeposits">StorageDeposits</a> <b>has</b> store
+</code></pre>
+
+
+
+<details>
+<summary>Fields</summary>
+
+
+<dl>
+<dt>
+<code>storage_balance: <a href="../iota-framework/balance.md#0x2_balance_Balance">balance::Balance</a>&lt;<a href="../iota-framework/iota.md#0x2_iota_IOTA">iota::IOTA</a>&gt;</code>
+</dt>
+<dd>
+
+</dd>
+</dl>
+
+
+</details>
+
+<a name="0x3_storage_deposits_new"></a>
+
+## Function `new`
+
+Called by <code><a href="iota_system.md#0x3_iota_system">iota_system</a></code> at genesis time.
+
+
+<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="storage_deposits.md#0x3_storage_deposits_new">new</a>(initial_balance: <a href="../iota-framework/balance.md#0x2_balance_Balance">balance::Balance</a>&lt;<a href="../iota-framework/iota.md#0x2_iota_IOTA">iota::IOTA</a>&gt;): <a href="storage_deposits.md#0x3_storage_deposits_StorageDeposits">storage_deposits::StorageDeposits</a>
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b>(package) <b>fun</b> <a href="storage_deposits.md#0x3_storage_deposits_new">new</a>(initial_balance: Balance&lt;IOTA&gt;) : <a href="storage_deposits.md#0x3_storage_deposits_StorageDeposits">StorageDeposits</a> {
+    <a href="storage_deposits.md#0x3_storage_deposits_StorageDeposits">StorageDeposits</a> {
+        // At the beginning there's no <a href="../iota-framework/object.md#0x2_object">object</a> in the storage yet
+        storage_balance: initial_balance,
+    }
+}
+</code></pre>
+
+
+
+</details>
+
+<a name="0x3_storage_deposits_advance_epoch"></a>
+
+## Function `advance_epoch`
+
+Called by <code><a href="iota_system.md#0x3_iota_system">iota_system</a></code> at epoch change times to process the inflows and outflows of storage fund.
+
+
+<pre><code><b>public</b>(<b>friend</b>) <b>fun</b> <a href="storage_deposits.md#0x3_storage_deposits_advance_epoch">advance_epoch</a>(self: &<b>mut</b> <a href="storage_deposits.md#0x3_storage_deposits_StorageDeposits">storage_deposits::StorageDeposits</a>, storage_charges: <a href="../iota-framework/balance.md#0x2_balance_Balance">balance::Balance</a>&lt;<a href="../iota-framework/iota.md#0x2_iota_IOTA">iota::IOTA</a>&gt;, storage_rebate_amount: u64, _non_refundable_storage_fee_amount: u64): <a href="../iota-framework/balance.md#0x2_balance_Balance">balance::Balance</a>&lt;<a href="../iota-framework/iota.md#0x2_iota_IOTA">iota::IOTA</a>&gt;
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b>(package) <b>fun</b> <a href="storage_deposits.md#0x3_storage_deposits_advance_epoch">advance_epoch</a>(
+    self: &<b>mut</b> <a href="storage_deposits.md#0x3_storage_deposits_StorageDeposits">StorageDeposits</a>,
+    storage_charges: Balance&lt;IOTA&gt;,
+    storage_rebate_amount: u64,
+    //TODO: try the way <b>to</b> configure
+    _non_refundable_storage_fee_amount: u64,
+) : Balance&lt;IOTA&gt; {
+    // The storage charges for the epoch come from the storage rebate of the new objects created
+    // and the new storage rebates of the objects modified during the epoch so we put the charges
+    // into `storage_balance`.
+    self.storage_balance.join(storage_charges);
+
+    // `storage_rebates` <b>include</b> the already refunded rebates of deleted objects and <b>old</b> rebates of modified objects and
+    // should be taken out of the `storage_balance`.
+    <b>let</b> storage_rebate = self.storage_balance.split(storage_rebate_amount);
+
+    // The storage rebate <b>has</b> already been returned <b>to</b> individual transaction senders' gas coins
+    // so we <b>return</b> the <a href="../iota-framework/balance.md#0x2_balance">balance</a> <b>to</b> be burnt at the very end of epoch change.
+    storage_rebate
+}
+</code></pre>
+
+
+
+</details>
+
+<a name="0x3_storage_deposits_total_balance"></a>
+
+## Function `total_balance`
+
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="storage_deposits.md#0x3_storage_deposits_total_balance">total_balance</a>(self: &<a href="storage_deposits.md#0x3_storage_deposits_StorageDeposits">storage_deposits::StorageDeposits</a>): u64
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="storage_deposits.md#0x3_storage_deposits_total_balance">total_balance</a>(self: &<a href="storage_deposits.md#0x3_storage_deposits_StorageDeposits">StorageDeposits</a>): u64 {
+    self.storage_balance.value()
+}
+</code></pre>
+
+
+
+</details>