Added an example program to derive constraints on shielded reward parameters.

Author: murisi

crates/core/src/token.rs

@@ -512,8 +512,8 @@ impl DenominatedAmount {
         }
     }
 
-    /// Attempt to increase the precision of an amount. Can fail
-    /// if the resulting amount does not fit into 256 bits.
+    /// Return an equivalent denominated amount with the given denomination. Can
+    /// fail if the resulting amount does not fit into 256 bits.
     pub fn increase_precision(
         self,
         denom: Denomination,
@@ -534,8 +534,43 @@ impl DenominatedAmount {
             .ok_or(AmountParseError::PrecisionOverflow)
     }
 
+    /// Return the closest denominated amount with the given denomination and
+    /// the error.
+    pub fn approximate(
+        self,
+        denom: Denomination,
+    ) -> Result<(Self, Self), AmountParseError> {
+        if denom.0 < self.denom.0 {
+            // Divide numerator and denominator by a power of 10
+            let amount = self.amount.raw_amount();
+            #[allow(clippy::arithmetic_side_effects)]
+            let (quot, rem) = Uint::from(10)
+                .checked_pow(Uint::from(self.denom.0 - denom.0))
+                .and_then(|scaling| {
+                    amount.checked_div(scaling).zip(amount.checked_rem(scaling))
+                })
+                .ok_or(AmountParseError::PrecisionOverflow)?;
+            let approx = Self {
+                amount: quot.into(),
+                denom,
+            };
+            let error = Self {
+                amount: rem.into(),
+                denom: self.denom,
+            };
+            Ok((approx, error))
+        } else {
+            // Multiply numerator and denominator by a power of 10
+            let error = Self {
+                amount: 0.into(),
+                denom: self.denom,
+            };
+            self.increase_precision(denom).map(|x| (x, error))
+        }
+    }
+
     /// Create a new [`DenominatedAmount`] with the same underlying
-    /// amout but a new denomination.
+    /// amount but a new denomination.
     pub fn redenominate(self, new_denom: u8) -> Self {
         Self {
             amount: self.amount,
@@ -590,6 +625,38 @@ impl DenominatedAmount {
         })
     }
 
+    /// Checked division computed to the given precission. Returns `None` on
+    /// overflow.
+    pub fn checked_div_precision(
+        &self,
+        rhs: DenominatedAmount,
+        denom: Denomination,
+    ) -> Option<Self> {
+        #[allow(clippy::arithmetic_side_effects)]
+        let pow = i16::from(rhs.denom.0) + i16::from(denom.0)
+            - i16::from(self.denom.0);
+        if pow < 0 {
+            return None;
+        }
+        let amount = Uint::from(10).checked_pow(Uint::from(pow)).and_then(
+            |scaling| {
+                scaling.checked_mul_div(
+                    self.amount.raw_amount(),
+                    rhs.amount.raw_amount(),
+                )
+            },
+        )?;
+        Some(Self {
+            amount: amount.0.into(),
+            denom,
+        })
+    }
+
+    /// Checked division. Returns `None` on overflow.
+    pub fn checked_div(&self, rhs: DenominatedAmount) -> Option<Self> {
+        self.checked_div_precision(rhs, self.denom)
+    }
+
     /// Returns the significand of this number
     pub const fn amount(&self) -> Amount {
         self.amount

examples/Cargo.toml

@@ -16,6 +16,10 @@ version.workspace = true
 name = "generate-txs"
 path = "generate_txs.rs"
 
+[[example]]
+name = "shielded-rewards"
+path = "shielded_rewards.rs"
+
 [[example]]
 name = "tx-schema"
 path = "tx_schema.rs"

examples/shielded_rewards.rs

@@ -0,0 +1,281 @@
+use std::io::Write;
+
+use namada_core::dec::Dec;
+use namada_core::token::DenominatedAmount;
+
+const DEFAULT_NATIVE_CODE: &str = "NAM";
+const DEFAULT_NATIVE_DECIMALS: u8 = 6;
+const DEFAULT_INCENT_CODE: &str = "OSMO";
+const DEFAULT_INCENT_DECIMALS: u8 = 6;
+const DEFAULT_MASP_EPOCHS_PER_YEAR: u64 = 365;
+const DEFAULT_INFLATION_THRESHOLD: &str = "0.01";
+const KP_GAIN_DECIMALS: u8 = 6;
+const MAX_REWARD_RATE_THRESHOLD_DECIMALS: u8 = 75;
+
+/// Computes bounds on inflation, token precision, and nominal proportional gain
+/// sufficient to yield non-zero rewards
+pub fn main() -> std::io::Result<()> {
+    let stdin = std::io::stdin();
+
+    // Let Y be the total MASP epochs per year
+    print!("MASP epochs per year ({}): ", DEFAULT_MASP_EPOCHS_PER_YEAR);
+    std::io::stdout().flush()?;
+    let mut masp_epochs_per_year = String::new();
+    stdin.read_line(&mut masp_epochs_per_year)?;
+    let masp_epochs_per_year = masp_epochs_per_year.trim();
+    let masp_epochs_per_year = if masp_epochs_per_year.is_empty() {
+        DEFAULT_MASP_EPOCHS_PER_YEAR
+    } else {
+        masp_epochs_per_year
+            .parse::<u64>()
+            .map_err(std::io::Error::other)?
+    };
+
+    // Get the currency code for the native token
+    print!("Native token currency code ({}): ", DEFAULT_NATIVE_CODE);
+    std::io::stdout().flush()?;
+    let mut native_code = String::new();
+    stdin.read_line(&mut native_code)?;
+    let native_code = native_code.trim();
+    let native_code = if native_code.is_empty() {
+        DEFAULT_NATIVE_CODE
+    } else {
+        native_code
+    };
+
+    // Get the decimal places for the native token
+    print!(
+        "Native token decimal places ({}): ",
+        DEFAULT_NATIVE_DECIMALS
+    );
+    std::io::stdout().flush()?;
+    let mut native_decimals = String::new();
+    stdin.read_line(&mut native_decimals)?;
+    let native_decimals = native_decimals.trim();
+    let native_decimals = if native_decimals.is_empty() {
+        DEFAULT_NATIVE_DECIMALS
+    } else {
+        native_decimals
+            .parse::<u8>()
+            .map_err(std::io::Error::other)?
+    };
+
+    // Let S be the total supply of NAM
+    print!("Native token supply in {}: ", native_code);
+    std::io::stdout().flush()?;
+    let mut native_supply = String::new();
+    stdin.read_line(&mut native_supply)?;
+    let native_supply = native_supply
+        .trim()
+        .parse::<DenominatedAmount>()
+        .map_err(std::io::Error::other)?;
+    let native_supply = native_supply
+        .increase_precision(native_decimals.into())
+        .map_err(std::io::Error::other)?;
+
+    // Get the currency code for the incentivised token
+    print!(
+        "Incentivised token currency code ({}): ",
+        DEFAULT_INCENT_CODE
+    );
+    std::io::stdout().flush()?;
+    let mut incent_code = String::new();
+    stdin.read_line(&mut incent_code)?;
+    let incent_code = incent_code.trim();
+    let incent_code = if incent_code.is_empty() {
+        DEFAULT_INCENT_CODE
+    } else {
+        incent_code
+    };
+
+    // Get the decimal places of the incentivised token
+    print!(
+        "Incentivised token decimal places ({}): ",
+        DEFAULT_INCENT_DECIMALS
+    );
+    std::io::stdout().flush()?;
+    let mut incent_decimals = String::new();
+    stdin.read_line(&mut incent_decimals)?;
+    let incent_decimals = incent_decimals.trim();
+    let incent_decimals = if incent_decimals.is_empty() {
+        DEFAULT_INCENT_DECIMALS
+    } else {
+        incent_decimals
+            .parse::<u8>()
+            .map_err(std::io::Error::other)?
+    };
+
+    // Let X be the target amount of TOK locked in the MASP
+    print!("Target locked amount in {}: ", incent_code);
+    std::io::stdout().flush()?;
+    let mut lock_target = String::new();
+    stdin.read_line(&mut lock_target)?;
+    let lock_target = lock_target
+        .trim()
+        .parse::<DenominatedAmount>()
+        .map_err(std::io::Error::other)?;
+    let lock_target = lock_target
+        .increase_precision(incent_decimals.into())
+        .map_err(std::io::Error::other)?;
+
+    // Let M be the desired minimum amount of TOK required to get rewards
+    print!("Incentivisation threshold in {}: ", incent_code);
+    std::io::stdout().flush()?;
+    let mut incent_threshold = String::new();
+    stdin.read_line(&mut incent_threshold)?;
+    let incent_threshold = incent_threshold
+        .trim()
+        .parse::<DenominatedAmount>()
+        .map_err(std::io::Error::other)?;
+    let incent_threshold = incent_threshold
+        .increase_precision(incent_decimals.into())
+        .map_err(std::io::Error::other)?;
+
+    // It must be the case that X/I <= M. Or equivalently I >= X/M.
+    let min_inflation = lock_target.amount().raw_amount()
+        / incent_threshold.amount().raw_amount();
+    let min_inflation =
+        DenominatedAmount::new(min_inflation.into(), native_decimals.into());
+    println!(
+        "Inflation must be more than {} {} to realize non-zero rewards for \
+         users holding more than {} {} in a pool holding {} {}.",
+        min_inflation,
+        native_code,
+        incent_threshold,
+        incent_code,
+        lock_target,
+        incent_code
+    );
+    print!("Inflation (>= {}) in {}: ", min_inflation, native_code);
+    std::io::stdout().flush()?;
+
+    // Let I be the computed amount of uNAM inflation in a single round of the
+    // mechanism due to the incentivised token TOK.
+    let mut inflation = String::new();
+    stdin.read_line(&mut inflation)?;
+    let inflation = inflation
+        .trim()
+        .parse::<DenominatedAmount>()
+        .map_err(std::io::Error::other)?;
+    let inflation = inflation
+        .increase_precision(native_decimals.into())
+        .map_err(std::io::Error::other)?;
+
+    // A necessary condition for there to be inflation is that floor(I*P/X)>=1.
+    let min_precision =
+        lock_target.amount().raw_amount() / inflation.amount().raw_amount();
+    // A necessary condition for users holding more than the threshold to get
+    // rewards is that P<=M.
+    let max_precision = incent_threshold.amount().raw_amount();
+    println!(
+        "At an inflation of {} {}, the precision must be between {} and {} in \
+         order to realize non-zero rewards.",
+        inflation, native_code, min_precision, max_precision
+    );
+
+    // Let P be the precision of the token TOK
+    print!("Precision ([{}, {}]): ", min_precision, max_precision);
+    std::io::stdout().flush()?;
+    let mut precision = String::new();
+    stdin.read_line(&mut precision)?;
+    let precision = precision
+        .trim()
+        .parse::<Dec>()
+        .map_err(std::io::Error::other)?;
+    println!(
+        "Users holding at least {} {} in the shielded pool will receive \
+         rewards.",
+        precision, incent_code
+    );
+
+    // It must be that S*C/Y >= I, which implies that the reward rate
+    // C >= (I*Y)/S
+    let inflation_per_year = inflation
+        .checked_mul(DenominatedAmount::new(
+            masp_epochs_per_year.into(),
+            0.into(),
+        ))
+        .ok_or(std::io::Error::other(
+            "unable to compute inflation per year",
+        ))?;
+    let max_reward_rate_threshold = inflation_per_year
+        .checked_div_precision(
+            native_supply,
+            MAX_REWARD_RATE_THRESHOLD_DECIMALS.into(),
+        )
+        .ok_or(std::io::Error::other(
+            "unable to divide inflation by native supply",
+        ))?;
+    println!(
+        "The maximum reward rate must exceed {} for it to be possible to \
+         achieve an inflation of {} {}.",
+        max_reward_rate_threshold, inflation, native_code
+    );
+
+    // Let C be the maximum reward rate for the token TOK
+    print!("Maximum reward rate (>= {}): ", max_reward_rate_threshold);
+    std::io::stdout().flush()?;
+    let mut maximum_reward_rate = String::new();
+    stdin.read_line(&mut maximum_reward_rate)?;
+    let maximum_reward_rate = maximum_reward_rate
+        .trim()
+        .parse::<DenominatedAmount>()
+        .map_err(std::io::Error::other)?;
+
+    // Let T be the threshold such that shielded rewards are guaranteed when E
+    // exceeds T
+    print!(
+        "Locked amount tolerance as proportion of target ({}): ",
+        DEFAULT_INFLATION_THRESHOLD
+    );
+    std::io::stdout().flush()?;
+    let mut inflation_threshold = String::new();
+    stdin.read_line(&mut inflation_threshold)?;
+    let inflation_threshold = inflation_threshold.trim();
+    let inflation_threshold = if inflation_threshold.is_empty() {
+        DEFAULT_INFLATION_THRESHOLD
+            .parse::<DenominatedAmount>()
+            .map_err(std::io::Error::other)?
+    } else {
+        inflation_threshold
+            .parse::<DenominatedAmount>()
+            .map_err(std::io::Error::other)?
+    };
+    let inflation_threshold = lock_target
+        .checked_mul(inflation_threshold)
+        .ok_or(std::io::Error::other(
+            "unable to multiply lock target by inflation threshold",
+        ))?
+        .approximate(native_decimals.into())
+        .map_err(std::io::Error::other)?
+        .0;
+
+    // Setting KP_nom >= (I*Y)/(C*T) makes the control value exceed I since it
+    // implies KP_nom*(C/Y)*T >= I which implies KP_nom*(C/Y)*E >= I
+    let nominal_proportional_gain_threshold = inflation_per_year
+        .redenominate(0)
+        .checked_div_precision(
+            maximum_reward_rate
+                .checked_mul(inflation_threshold.redenominate(0))
+                .ok_or(std::io::Error::other(
+                    "unable to multiply maximum reward rate by inflation \
+                     threshold",
+                ))?,
+            KP_GAIN_DECIMALS.into(),
+        )
+        .ok_or(std::io::Error::other(
+            "unable to multiply maximum reward rate by inflation threshold",
+        ))?;
+    println!(
+        "Under the assumption that the locked amount is more than {} {} less \
+         than the target and the error derivative is non-positive, a nominal \
+         proportional gain exceeding {} is sufficient to achieve inflation \
+         exceeding {} {}",
+        inflation_threshold,
+        incent_code,
+        nominal_proportional_gain_threshold,
+        inflation,
+        native_code
+    );
+    Ok(())
+}