[genesis] Final supply migration and documentation (#68)

Co-authored-by: 0o-de-lally <[email protected]>

Cargo.toml

@@ -347,8 +347,3 @@ incremental = true
 # # This will be removed once our pull requests land.
 [patch.crates-io]
 serde-reflection = { git = "https://github.com/aptos-labs/serde-reflection", rev = "839aed62a20ddccf043c08961cfe74875741ccba" }
-
-[env]
-# set coin name for diem dependencies
-RUST_DIEM_COIN_MODULE = "gas_coin"
-RUST_DIEM_COIN_NAME = "LibraCoin"

framework/libra-framework/sources/ol_sources/proof_of_fee.move

@@ -86,6 +86,18 @@ module ol_framework::proof_of_fee {
     }
   }
 
+  // on a migration genesis for mainnet the genesis reward needs to be calculated
+  // from supply data.
+  public fun genesis_migrate_reward(vm: &signer, nominal_reward: u64) acquires
+  ConsensusReward {
+    if (signer::address_of(vm) != @ol_framework) return;
+
+    let state = borrow_global_mut<ConsensusReward>(@ol_framework);
+    state.nominal_reward = nominal_reward;
+    state.net_reward = nominal_reward; // just for info purposes. It gets calculated
+    // on first epoch change.
+  }
+
   public fun init(account_sig: &signer) {
 
     let acc = signer::address_of(account_sig);

tools/genesis/Makefile

@@ -14,6 +14,10 @@ RECOVERY_FILE = sample_end_user_single
 # RECOVERY_FILE = sample_rotated_auth
 endif
 
+ifndef YEARS
+YEARS = 7
+endif
+
 ifndef CHAIN
 CHAIN = testing
 endif
@@ -34,6 +38,7 @@ genesis:
 	--json-legacy ./tests/fixtures/${RECOVERY_FILE}.json \
 	--target-supply ${TARGET_SUPPLY} \
 	--target-future-uses ${FUTURE_USES} \
+	--years-escrow ${YEARS} \
 	--map-dd-to-slow 3A6C51A0B786D644590E8A21591FA8E2 \
 	--map-dd-to-slow  2B0E8325DEA5BE93D856CFDE2D0CBA12
 
@@ -45,6 +50,7 @@ wizard:
 	--json-legacy ./tests/fixtures/${RECOVERY_FILE}.json \
 	--target-supply ${TARGET_SUPPLY} \
 	--target-future-uses ${FUTURE_USES} \
+	--years-escrow ${YEARS} \
 	--map-dd-to-slow 3A6C51A0B786D644590E8A21591FA8E2 \
 	--map-dd-to-slow  2B0E8325DEA5BE93D856CFDE2D0CBA12
 
@@ -84,5 +90,6 @@ test-genesis:
 	-i ${CAROL_IP} \
 	--target-supply ${TARGET_SUPPLY} \
 	--target-future-uses ${FUTURE_USES} \
+	--years-escrow ${YEARS} \
 	--map-dd-to-slow 3A6C51A0B786D644590E8A21591FA8E2 \
 	--map-dd-to-slow 2B0E8325DEA5BE93D856CFDE2D0CBA12

tools/genesis/README.md

@@ -0,0 +1,60 @@
+## Genesis
+
+
+### Migration Math
+
+#### `--target-supply <float>` Change in denomination (split)
+
+To adjust the count of coins, and how they get split, the genesis command offers
+one input: `--target-supply`.
+
+If for example the supply will scale (pro-rata) from 2,000,000 to 100,000,000,
+then the genesis supply calculator (`set_ratios_from_settings()`) will create a split of 50 redenominated coins
+for 1 coin. Coins do not change name, no changes in ownership, and all policies
+remain the same.
+
+#### `--years-escrow <integer>` Provision an infrastructure escrow
+
+If the validators will set aside rewards for future validators this is done
+with: `--years-escrow`. If for example this argument is used, the supply
+calculator (`set_ratios_from_settings()`) will take the *remainder* of the
+`--target-future-uses` which isn't already in a community-wallet.
+
+#### `--target-future-uses <float>` Community wallet and infra escrow target percentage of network supply
+This parameter affects the expected funds available for infra-escrow pledges,
+and the daily epoch reward budget.
+
+Note: this could have been implemented as a number targetting the infra-escrow percentage
+(e.g. `target-infra-escrow`). However the user-experience of the validator at
+genesis is more difficult in this case since the community wallet numbers are
+not easily calculated in advance (it would require multiple steps with this tool).
+
+We calculate the infra-escrow budget by working backwards from one input the
+community would already have: a target for "future users" (versus end-user
+accounts).
+If for example the community expected that the combined infra-escrow and
+community wallets will represent 70% of the network as a target, we deduce that
+infra-escrow will be the remainder of `((0.70 * total supply) - (sum of community
+wallets))`.
+
+A lower amount of `--target-future-uses` means a lower amount available to
+infrastructure escrow pledges to use over the time `--years-escrow`. i.e. if
+target future uses is 55%  (`--target-future-uses 0.55`) and the community
+wallet balance is 45%, then there is
+10% of supply to be spread over 7 years (`--years-escrow 7`).
+
+Note also we derive the baseline
+daily validator rewards from those two parameters. In the example above the
+daily reward baseline equals `(10% * Total
+Supply) / 7 (years) * 100 validators (baseline) * 365 (days)`
+
+Troubleshooting. If the target percent % is below the proportion of the sum of community
+accounts the program will exit with error.
+
+
+#### `--map_dd_to_slow <list of space delimited addresses>`. Adjusting the future-uses calculator
+
+Ususally in test-cases, there may be cases that the future-uses calculator gets
+skewed because certain accounts are not in the expected state (a community
+wallet wasn't expected to exist at that point).
+