Merge pull request #1227 from input-output-hk/reward-settings

expose the reward parameters

Author: NicolasDP

jormungandr-lib/src/interfaces/block0_configuration/DOCUMENTED_EXAMPLE.yaml

@@ -103,6 +103,42 @@ blockchain_configuration:
     # to 10000. Uncomment the following line to apply a max limit:
     # max_limit: 10000
 
+  # Set the total reward supply available for monetary creation
+  #
+  # if not set there is no monetary creation
+  # once emptied, there is no more monetary creation
+  total_reward_supply: 100000000000000
+
+  # set the reward supply consumption. These parameters will define how the
+  # total_reward_supply is consumed for the stake pool reward
+  #
+  # There's fundamentally many potential choices for how rewards are contributed back, and here's two potential valid examples:
+  #
+  # Linear formula: constant - ratio * (#epoch after epoch_start / epoch_rate)
+  # Halving formula: constant * ratio ^ (#epoch after epoch_start / epoch_rate)
+  #
+  reward_parameters:
+    halving: # or use "linear" for the linear formula
+      # In the linear formula, it represents the starting point of the contribution
+      # at #epoch=0, whereas in halving formula is used as starting constant for
+      # the calculation.
+      constant: 100
+
+      # In the halving formula, an effective value between 0.0 to 1.0 indicates a
+      # reducing contribution, whereas above 1.0 it indicate an acceleration of contribution.
+      #
+      # However in linear formula the meaning is just a scaling factor for the epoch zone
+      # (current_epoch - start_epoch / epoch_rate). Further requirement is that this ratio
+      # is expressed in fractional form (e.g. 1/2), which allow calculation in integer form.
+      ratio: "13/19"
+
+      # indicates when this contribution start. note that if the epoch is not
+      # the same or after the epoch_start, the overall contribution is zero.
+      epoch_start: 1
+
+      # the rate at which the contribution is tweaked related to epoch.
+      epoch_rate: 3
+
 # Initial state of the ledger. Each item is applied in order of this list
 initial:
   # Initial deposits present in the blockchain

jormungandr-lib/src/interfaces/block0_configuration/initial_config.rs

@@ -1,7 +1,7 @@
 use crate::{
     interfaces::{
         ActiveSlotCoefficient, BFTSlotsRatio, ConsensusLeaderId, KESUpdateSpeed, LinearFeeDef,
-        NumberOfSlotsPerEpoch, SlotDuration, TaxType, Value,
+        NumberOfSlotsPerEpoch, RewardParams, SlotDuration, TaxType, Value,
     },
     time::SecondsSinceUnixEpoch,
 };
@@ -116,7 +116,12 @@ pub struct BlockchainConfiguration {
 
     /// Set the value of the reward pot. if omitted then the reward pot is empty
     #[serde(default)]
-    pub rewards: Option<Value>,
+    pub total_reward_supply: Option<Value>,
+
+    /// The reward settings for the reward policy. No reward settings means no reward
+    /// distributed at all.
+    #[serde(default)]
+    pub reward_parameters: Option<RewardParams>,
 }
 
 impl From<BlockchainConfiguration> for ConfigParams {
@@ -166,7 +171,8 @@ impl BlockchainConfiguration {
             epoch_stability_depth: None,
             treasury: None,
             treasury_parameters: None,
-            rewards: None,
+            total_reward_supply: None,
+            reward_parameters: None,
         }
     }
 
@@ -189,7 +195,8 @@ impl BlockchainConfiguration {
         let mut kes_update_speed = None;
         let mut treasury = None;
         let mut treasury_parameters = None;
-        let mut rewards = None;
+        let mut total_reward_supply = None;
+        let mut reward_parameters = None;
         let mut per_certificate_fees = None;
 
         for param in params.iter().cloned() {
@@ -244,10 +251,12 @@ impl BlockchainConfiguration {
                 ConfigParam::TreasuryParams(param) => treasury_parameters
                     .replace(param.into())
                     .map(|_| "treasury_parameters"),
-                ConfigParam::RewardPot(param) => {
-                    rewards.replace(param.into()).map(|_| "reward-pot")
-                }
-                ConfigParam::RewardParams(_) => unimplemented!(),
+                ConfigParam::RewardPot(param) => total_reward_supply
+                    .replace(param.into())
+                    .map(|_| "total_reward_supply"),
+                ConfigParam::RewardParams(param) => reward_parameters
+                    .replace(param.into())
+                    .map(|_| "reward_parameters"),
                 ConfigParam::PerCertificateFees(param) => per_certificate_fees
                     .replace(param)
                     .map(|_| "per_certificate_fees"),
@@ -280,7 +289,8 @@ impl BlockchainConfiguration {
             max_number_of_transactions_per_block,
             treasury,
             treasury_parameters,
-            rewards,
+            total_reward_supply,
+            reward_parameters,
         })
     }
 
@@ -300,7 +310,8 @@ impl BlockchainConfiguration {
             epoch_stability_depth,
             treasury,
             treasury_parameters,
-            rewards,
+            total_reward_supply,
+            reward_parameters,
         } = self;
 
         let mut params = ConfigParams::new();
@@ -336,8 +347,12 @@ impl BlockchainConfiguration {
             params.push(ConfigParam::TreasuryParams(treasury_parameters.into()));
         }
 
-        if let Some(rewards) = rewards {
-            params.push(ConfigParam::RewardPot(rewards.into()));
+        if let Some(total_reward_supply) = total_reward_supply {
+            params.push(ConfigParam::RewardPot(total_reward_supply.into()));
+        }
+
+        if let Some(reward_parameters) = reward_parameters {
+            params.push(ConfigParam::RewardParams(reward_parameters.into()));
         }
 
         consensus_leader_ids
@@ -404,7 +419,8 @@ mod test {
                 epoch_stability_depth: Arbitrary::arbitrary(g),
                 treasury: Arbitrary::arbitrary(g),
                 treasury_parameters: Arbitrary::arbitrary(g),
-                rewards: Arbitrary::arbitrary(g),
+                total_reward_supply: Arbitrary::arbitrary(g),
+                reward_parameters: Arbitrary::arbitrary(g),
             }
         }
     }

jormungandr-lib/src/interfaces/mod.rs

@@ -10,6 +10,7 @@ mod leadership_log;
 mod linear_fee;
 mod old_address;
 mod ratio;
+mod reward_parameters;
 mod settings;
 mod stats;
 mod tax_type;
@@ -36,6 +37,7 @@ pub use self::leadership_log::{
 pub use self::linear_fee::LinearFeeDef;
 pub use self::old_address::OldAddress;
 pub use self::ratio::{ParseRatioError, Ratio};
+pub use self::reward_parameters::RewardParams;
 pub use self::settings::*;
 pub use self::stats::{NodeState, Stats};
 pub use self::tax_type::TaxType;

jormungandr-lib/src/interfaces/reward_parameters.rs

@@ -0,0 +1,170 @@
+use crate::interfaces::Ratio;
+use chain_impl_mockchain::{block::Epoch, config::RewardParams as RewardParamsStd};
+use serde::{Deserialize, Serialize};
+use std::num::NonZeroU32;
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields, rename_all = "snake_case")]
+pub enum RewardParams {
+    Linear {
+        constant: u64,
+        ratio: Ratio,
+        epoch_start: Epoch,
+        epoch_rate: NonZeroU32,
+    },
+    Halving {
+        constant: u64,
+        ratio: Ratio,
+        epoch_start: Epoch,
+        epoch_rate: NonZeroU32,
+    },
+}
+
+/* ************** Conversion *********************************** */
+
+impl From<RewardParams> for RewardParamsStd {
+    fn from(rp: RewardParams) -> Self {
+        match rp {
+            RewardParams::Linear {
+                constant,
+                ratio,
+                epoch_start,
+                epoch_rate,
+            } => RewardParamsStd::Linear {
+                constant,
+                ratio: ratio.into(),
+                epoch_start,
+                epoch_rate,
+            },
+            RewardParams::Halving {
+                constant,
+                ratio,
+                epoch_start,
+                epoch_rate,
+            } => RewardParamsStd::Halving {
+                constant,
+                ratio: ratio.into(),
+                epoch_start,
+                epoch_rate,
+            },
+        }
+    }
+}
+
+impl From<RewardParamsStd> for RewardParams {
+    fn from(rp: RewardParamsStd) -> Self {
+        match rp {
+            RewardParamsStd::Linear {
+                constant,
+                ratio,
+                epoch_start,
+                epoch_rate,
+            } => RewardParams::Linear {
+                constant,
+                ratio: ratio.into(),
+                epoch_start,
+                epoch_rate,
+            },
+            RewardParamsStd::Halving {
+                constant,
+                ratio,
+                epoch_start,
+                epoch_rate,
+            } => RewardParams::Halving {
+                constant,
+                ratio: ratio.into(),
+                epoch_start,
+                epoch_rate,
+            },
+        }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+    use quickcheck::{Arbitrary, Gen, TestResult};
+    use std::num::NonZeroU64;
+
+    impl Arbitrary for RewardParams {
+        fn arbitrary<G>(g: &mut G) -> Self
+        where
+            G: Gen,
+        {
+            if bool::arbitrary(g) {
+                Self::Linear {
+                    constant: u64::arbitrary(g),
+                    ratio: Ratio::arbitrary(g),
+                    epoch_start: Epoch::arbitrary(g),
+                    epoch_rate: NonZeroU32::new(Arbitrary::arbitrary(g))
+                        .unwrap_or(NonZeroU32::new(1).unwrap()),
+                }
+            } else {
+                Self::Halving {
+                    constant: u64::arbitrary(g),
+                    ratio: Ratio::arbitrary(g),
+                    epoch_start: Epoch::arbitrary(g),
+                    epoch_rate: NonZeroU32::new(Arbitrary::arbitrary(g))
+                        .unwrap_or(NonZeroU32::new(1).unwrap()),
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn linear_serde_yaml() {
+        const CONSTANT: u64 = 8170;
+        const RATIO_NUMERATOR: u64 = 13;
+        const RATIO_DENOMINATOR: NonZeroU64 = unsafe { NonZeroU64::new_unchecked(19) };
+        const EPOCH_START: Epoch = 2;
+        const EPOCH_RATE: NonZeroU32 = unsafe { NonZeroU32::new_unchecked(5) };
+
+        let parameters = RewardParams::Linear {
+            constant: CONSTANT,
+            ratio: Ratio::new(RATIO_NUMERATOR, RATIO_DENOMINATOR),
+            epoch_start: EPOCH_START,
+            epoch_rate: EPOCH_RATE,
+        };
+
+        assert_eq!(
+            serde_yaml::to_string(&parameters).unwrap(),
+            format!(
+                "---\nlinear:\n  constant: {}\n  ratio: {}/{}\n  epoch_start: {}\n  epoch_rate: {}",
+                CONSTANT, RATIO_NUMERATOR, RATIO_DENOMINATOR, EPOCH_START, EPOCH_RATE,
+            )
+        );
+    }
+
+    #[test]
+    fn halving_serde_yaml() {
+        const CONSTANT: u64 = 8170;
+        const RATIO_NUMERATOR: u64 = 13;
+        const RATIO_DENOMINATOR: NonZeroU64 = unsafe { NonZeroU64::new_unchecked(19) };
+        const EPOCH_START: Epoch = 2;
+        const EPOCH_RATE: NonZeroU32 = unsafe { NonZeroU32::new_unchecked(5) };
+
+        let parameters = RewardParams::Halving {
+            constant: CONSTANT,
+            ratio: Ratio::new(RATIO_NUMERATOR, RATIO_DENOMINATOR),
+            epoch_start: EPOCH_START,
+            epoch_rate: EPOCH_RATE,
+        };
+
+        assert_eq!(
+            serde_yaml::to_string(&parameters).unwrap(),
+            format!(
+                "---\nhalving:\n  constant: {}\n  ratio: {}/{}\n  epoch_start: {}\n  epoch_rate: {}",
+                CONSTANT, RATIO_NUMERATOR, RATIO_DENOMINATOR, EPOCH_START, EPOCH_RATE,
+            )
+        );
+    }
+
+    quickcheck! {
+        fn value_serde_human_readable_encode_decode(value: RewardParams) -> TestResult {
+            let s = serde_yaml::to_string(&value).unwrap();
+            let value_dec: RewardParams = serde_yaml::from_str(&s).unwrap();
+
+            TestResult::from_bool(value_dec == value)
+        }
+    }
+}