Regression testing and readability additions for reward curve log2 (#5610)

Co-Authored-By: thiolliere <gui.thiolliere@gmail.com>

substrate/frame/staking/reward-curve/src/lib.rs

@@ -268,10 +268,14 @@ impl INPoS {
 		}
 	}
 
+	// calculates x from:
+	// y = i_0 + (i_ideal * x_ideal - i_0) * 2^((x_ideal - x)/d)
+	// See web3 docs for the details
 	fn compute_opposite_after_x_ideal(&self, y: u32) -> u32 {
 		if y == self.i_0 {
 			return u32::max_value();
 		}
+		// Note: the log term calculated here represents a per_million value
 		let log = log2(self.i_ideal_times_x_ideal - self.i_0, y - self.i_0);
 
 		let term: u32 = ((self.d as u64 * log as u64) / 1_000_000).try_into().unwrap();

substrate/frame/staking/reward-curve/src/log.rs

@@ -1,48 +1,65 @@
 use std::convert::TryInto;
 
-/// Return Per-million value.
+/// Simple u32 power of 2 function - simply uses a bit shift
+macro_rules! pow2 {
+	($n:expr) => {
+		1_u32 << $n
+	}
+}
+
+/// Returns the k_th per_million taylor term for a log2 function
+fn taylor_term(k: u32, y_num: u128, y_den: u128) -> u32 {
+	let _2_div_ln_2: u128 = 2_885_390u128;
+
+	if k == 0 {
+		(_2_div_ln_2 * (y_num).pow(1) / (y_den).pow(1)).try_into().unwrap()
+	} else {
+		let mut res = _2_div_ln_2 * (y_num).pow(3) / (y_den).pow(3);
+		for _ in 1..k {
+			res = res * (y_num).pow(2) / (y_den).pow(2);
+		}
+		res /= 2 * k as u128 + 1;
+
+		res.try_into().unwrap()
+	}
+}
+
+/// Performs a log2 operation using a rational fraction
+///
+/// result = log2(p/q) where p/q is bound to [1, 1_000_000]
+/// Where:
+/// * q represents the numerator of the rational fraction input
+/// * p represents the denominator of the rational fraction input
+/// * result represents a per-million output of log2
 pub fn log2(p: u32, q: u32) -> u32 {
-	assert!(p >= q);
+	assert!(p >= q); // keep p/q bound to [1, inf)
 	assert!(p <= u32::max_value()/2);
 
 	// This restriction should not be mandatory. But function is only tested and used for this.
 	assert!(p <= 1_000_000);
 	assert!(q <= 1_000_000);
 
+	// log2(1) = 0
 	if p == q {
 		return 0
 	}
 
+	// find the power of 2 where q * 2^n <= p < q * 2^(n+1)
 	let mut n = 0u32;
-	while !(p >= (1u32 << n)*q) || !(p < (1u32 << (n+1))*q) {
+	while !(p >= pow2!(n) * q) || !(p < pow2!(n + 1) * q) {
 		n += 1;
+		assert!(n < 32); // cannot represent 2^32 in u32
 	}
-	assert!(p < (1u32 << (n+1)) * q);
+	assert!(p < pow2!(n + 1) * q);
 
-	let y_num: u32 = (p - (1u32 << n) * q).try_into().unwrap();
-	let y_den: u32 = (p + (1u32 << n) * q).try_into().unwrap();
-
-	let _2_div_ln_2 = 2_885_390u32;
-
-	let taylor_term = |k: u32| -> u32 {
-		if k == 0 {
-			(_2_div_ln_2 as u128 * (y_num as u128).pow(1) / (y_den as u128).pow(1))
-				.try_into().unwrap()
-		} else {
-			let mut res = _2_div_ln_2 as u128 * (y_num as u128).pow(3) / (y_den as u128).pow(3);
-			for _ in 1..k {
-				res = res * (y_num as u128).pow(2) / (y_den as u128).pow(2);
-			}
-			res /= 2 * k as u128 + 1;
-
-			res.try_into().unwrap()
-		}
-	};
+	let y_num: u32 = (p - pow2!(n) * q).try_into().unwrap();
+	let y_den: u32 = (p + pow2!(n) * q).try_into().unwrap();
 
+	// Loop through each Taylor series coefficient until it reaches 10^-6
 	let mut res = n * 1_000_000u32;
 	let mut k = 0;
 	loop {
-		let term = taylor_term(k);
+		let term = taylor_term(k, y_num.into(), y_den.into());
 		if term == 0 {
 			break
 		}
@@ -68,3 +85,43 @@ fn test_log() {
 		}
 	}
 }
+
+#[test]
+#[should_panic]
+fn test_log_p_must_be_greater_than_q() {
+	let p: u32 = 1_000;
+	let q: u32 = 1_001;
+	let _ = log2(p, q);
+}
+
+#[test]
+#[should_panic]
+fn test_log_p_upper_bound() {
+	let p: u32 = 1_000_001;
+	let q: u32 = 1_000_000;
+	let _ = log2(p, q);
+}
+
+#[test]
+#[should_panic]
+fn test_log_q_limit() {
+	let p: u32 = 1_000_000;
+	let q: u32 = 0;
+	let _ = log2(p, q);
+}
+
+#[test]
+fn test_log_of_one_boundary() {
+	let p: u32 = 1_000_000;
+	let q: u32 = 1_000_000;
+	assert_eq!(log2(p, q), 0);
+}
+
+#[test]
+fn test_log_of_largest_input() {
+	let p: u32 = 1_000_000;
+	let q: u32 = 1;
+	let expected = 19_931_568;
+	let tolerance = 100;
+	assert!((log2(p, q) as i32 - expected as i32).abs() < tolerance);
+}