Defensive Programming in Substrate Reference Document

docs/mermaid/integer_operation_decision.mmd

@@ -0,0 +1,7 @@
+flowchart LR
+    CH["Checked"]
+    ST["Saturated"]
+    CH-->NEED["The user needs to know that the operation failed - and why"]
+    CH-->DOUBT["Unsure whether this operation could fail/overflow"]
+    ST-->SILENT["Silently reaching upper/lower bound will not result in any damage"]
+    ST-->REASON["In all reasonable circumstances, the number will not overflow, but safety is still desired"]

docs/sdk/Cargo.toml

@@ -81,6 +81,13 @@ sp-api = { path = "../../substrate/primitives/api" }
 sp-core = { path = "../../substrate/primitives/core" }
 sp-keyring = { path = "../../substrate/primitives/keyring" }
 sp-runtime = { path = "../../substrate/primitives/runtime" }
+sp-arithmetic = { path = "../../substrate/primitives/arithmetic" }
+
+# Misc pallet dependencies
+pallet-referenda = { path = "../../substrate/frame/referenda" }
+pallet-broker = { path = "../../substrate/frame/broker" }
+pallet-babe = { path = "../../substrate/frame/babe" }
+
 sp-offchain = { path = "../../substrate/primitives/offchain" }
 sp-version = { path = "../../substrate/primitives/version" }
 

docs/sdk/src/guides/your_first_pallet/mod.rs

@@ -105,8 +105,8 @@
 //! This macro will call `.into()` under the hood.
 #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", transfer_better)]
 //!
-//! Moreover, you will learn in the [Safe Defensive Programming
-//! section](crate::reference_docs::safe_defensive_programming) that it is always recommended to use
+//! Moreover, you will learn in the [Defensive Programming
+//! section](crate::reference_docs::defensive_programming) that it is always recommended to use
 //! safe arithmetic operations in your runtime. By using [`frame::traits::CheckedSub`], we can not
 //! only take a step in that direction, but also improve the error handing and make it slightly more
 //! ergonomic.
@@ -294,7 +294,7 @@
 //! The following topics where used in this guide, but not covered in depth. It is suggested to
 //! study them subsequently:
 //!
-//! - [`crate::reference_docs::safe_defensive_programming`].
+//! - [`crate::reference_docs::defensive_programming`].
 //! - [`crate::reference_docs::frame_origin`].
 //! - [`crate::reference_docs::frame_runtime_types`].
 //! - The pallet we wrote in this guide was using `dev_mode`, learn more in

docs/sdk/src/reference_docs/mod.rs

@@ -47,8 +47,7 @@ pub mod transaction_extensions;
 pub mod frame_origin;
 
 /// Learn about how to write safe and defensive code in your FRAME runtime.
-// TODO: @CrackTheCode016 https://github.com/paritytech/polkadot-sdk-docs/issues/44
-pub mod safe_defensive_programming;
+pub mod defensive_programming;
 
 /// Learn about composite enums and other runtime level types, such as "RuntimeEvent" and
 /// "RuntimeCall".

substrate/primitives/arithmetic/Cargo.toml

@@ -27,6 +27,7 @@ scale-info = { version = "2.10.0", default-features = false, features = ["derive
 serde = { features = ["alloc", "derive"], optional = true, workspace = true }
 static_assertions = "1.1.0"
 sp-std = { path = "../std", default-features = false }
+docify = "0.2.7"
 
 [dev-dependencies]
 criterion = "0.4.0"

substrate/primitives/arithmetic/src/fixed_point.rs

@@ -16,6 +16,33 @@
 // limitations under the License.
 
 //! Decimal Fixed Point implementations for Substrate runtime.
+//! Similar to types that implement [`PerThing`](crate::per_things), these are also
+//! fixed-point types, however, they are able to represent larger fractions:
+#![doc = docify::embed!("./src/lib.rs", fixed_u64)]
+//!
+//! ### Fixed Point Types in Practice
+//!
+//! If one needs to exceed the value of one (1), then
+//! [`FixedU64`](FixedU64) (and its signed and `u128` counterparts) can be utilized.
+//! Take for example this very rudimentary pricing mechanism, where we wish to calculate the demand
+//! / supply to get a price for some on-chain compute:
+#![doc = docify::embed!(
+	"./src/lib.rs",
+	fixed_u64_block_computation_example
+)]
+//!
+//! For a much more comprehensive example, be sure to look at the source for broker (the "coretime")
+//! pallet.
+//!
+//! #### Fixed Point Types in Practice
+//!
+//! Just as with [`PerThing`](PerThing), you can also perform regular mathematical
+//! expressions:
+#![doc = docify::embed!(
+	"./src/lib.rs",
+	fixed_u64_operation_example
+)]
+//!
 
 use crate::{
 	helpers_128bit::{multiply_by_rational_with_rounding, sqrt},

substrate/primitives/arithmetic/src/lib.rs

@@ -98,7 +98,7 @@ where
 	fn tcmp(&self, other: &T, threshold: T) -> Ordering {
 		// early exit.
 		if threshold.is_zero() {
-			return self.cmp(other)
+			return self.cmp(other);
 		}
 
 		let upper_bound = other.saturating_add(threshold);
@@ -203,12 +203,12 @@ where
 
 	// Nothing to do here.
 	if count.is_zero() {
-		return Ok(Vec::<T>::new())
+		return Ok(Vec::<T>::new());
 	}
 
 	let diff = targeted_sum.max(sum) - targeted_sum.min(sum);
 	if diff.is_zero() {
-		return Ok(input.to_vec())
+		return Ok(input.to_vec());
 	}
 
 	let needs_bump = targeted_sum > sum;
@@ -251,7 +251,7 @@ where
 				min_index += 1;
 				min_index %= count;
 			}
-			leftover -= One::one()
+			leftover -= One::one();
 		}
 	} else {
 		// must decrease the stakes a bit. decrement from the max element. index of maximum is now
@@ -285,7 +285,7 @@ where
 				if output_with_idx[max_index].1 <= threshold {
 					max_index = max_index.checked_sub(1).unwrap_or(count - 1);
 				}
-				leftover -= One::one()
+				leftover -= One::one();
 			} else {
 				max_index = max_index.checked_sub(1).unwrap_or(count - 1);
 			}
@@ -297,7 +297,7 @@ where
 		targeted_sum,
 		"sum({:?}) != {:?}",
 		output_with_idx,
-		targeted_sum,
+		targeted_sum
 	);
 
 	// sort again based on the original index.
@@ -353,7 +353,7 @@ mod normalize_tests {
 			vec![
 				Perbill::from_parts(333333334),
 				Perbill::from_parts(333333333),
-				Perbill::from_parts(333333333),
+				Perbill::from_parts(333333333)
 			]
 		);
 
@@ -364,7 +364,7 @@ mod normalize_tests {
 			vec![
 				Perbill::from_parts(316666668),
 				Perbill::from_parts(383333332),
-				Perbill::from_parts(300000000),
+				Perbill::from_parts(300000000)
 			]
 		);
 	}
@@ -375,13 +375,13 @@ mod normalize_tests {
 		// could have a situation where the sum cannot be calculated in the inner type. Calculating
 		// using the upper type of the per_thing should assure this to be okay.
 		assert_eq!(
-			vec![PerU16::from_percent(40), PerU16::from_percent(40), PerU16::from_percent(40),]
+			vec![PerU16::from_percent(40), PerU16::from_percent(40), PerU16::from_percent(40)]
 				.normalize(PerU16::one())
 				.unwrap(),
 			vec![
 				PerU16::from_parts(21845), // 33%
 				PerU16::from_parts(21845), // 33%
-				PerU16::from_parts(21845), // 33%
+				PerU16::from_parts(21845)  // 33%
 			]
 		);
 	}
@@ -425,6 +425,88 @@ mod normalize_tests {
 	}
 }
 
+#[cfg(test)]
+mod per_and_fixed_examples {
+	use super::*;
+
+	#[docify::export]
+	#[test]
+	fn percent_mult() {
+		let percent = Percent::from_rational(5u32, 100u32); // aka, 5%
+		let five_percent_of_100 = percent * 100u32; // 5% of 100 is 5.
+		assert_eq!(five_percent_of_100, 5)
+	}
+	#[docify::export]
+	#[test]
+	fn perbill_example() {
+		let p = Perbill::from_percent(80);
+		// 800000000 bil, or a representative of 0.800000000.
+		// Precision is in the billions place.
+		assert_eq!(p.deconstruct(), 800000000);
+	}
+
+	#[docify::export]
+	#[test]
+	fn percent_example() {
+		let percent = Percent::from_rational(190u32, 400u32);
+		assert_eq!(percent.deconstruct(), 47);
+	}
+
+	#[docify::export]
+	#[test]
+	fn fixed_u64_block_computation_example() {
+		// Calculate a very rudimentary on-chain price from supply / demand
+		// Supply: Cores available per block
+		// Demand: Cores being ordered per block
+		let price = FixedU64::from_rational(5u128, 10u128);
+
+		// 0.5 DOT per core
+		assert_eq!(price, FixedU64::from_float(0.5));
+
+		// Now, the story has changed - lots of demand means we buy as many cores as there
+		// available.  This also means that price goes up! For the sake of simplicity, we don't care
+		// about who gets a core - just about our very simple price model
+
+		// Calculate a very rudimentary on-chain price from supply / demand
+		// Supply: Cores available per block
+		// Demand: Cores being ordered per block
+		let price = FixedU64::from_rational(19u128, 10u128);
+
+		// 1.9 DOT per core
+		assert_eq!(price, FixedU64::from_float(1.9));
+	}
+
+	#[docify::export]
+	#[test]
+	fn fixed_u64() {
+		// The difference between this and perthings is perthings operates within the relam of [0,
+		// 1] In cases where we need > 1, we can used fixed types such as FixedU64
+
+		let rational_1 = FixedU64::from_rational(10, 5); //" 200%" aka 2.
+		let rational_2 = FixedU64::from_rational_with_rounding(5, 10, Rounding::Down); // "50%" aka 0.50...
+
+		assert_eq!(rational_1, (2u64).into());
+		assert_eq!(rational_2.into_perbill(), Perbill::from_float(0.5));
+	}
+
+	#[docify::export]
+	#[test]
+	fn fixed_u64_operation_example() {
+		let rational_1 = FixedU64::from_rational(10, 5); // "200%" aka 2.
+		let rational_2 = FixedU64::from_rational(8, 5); // "160%" aka 1.6.
+
+		let addition = rational_1 + rational_2;
+		let multiplication = rational_1 * rational_2;
+		let division = rational_1 / rational_2;
+		let subtraction = rational_1 - rational_2;
+
+		assert_eq!(addition, FixedU64::from_float(3.6));
+		assert_eq!(multiplication, FixedU64::from_float(3.2));
+		assert_eq!(division, FixedU64::from_float(1.25));
+		assert_eq!(subtraction, FixedU64::from_float(0.4));
+	}
+}
+
 #[cfg(test)]
 mod threshold_compare_tests {
 	use super::*;
@@ -437,15 +519,15 @@ mod threshold_compare_tests {
 		let e = Perbill::from_percent(10).mul_ceil(b);
 
 		// [115 - 11,5 (103,5), 115 + 11,5 (126,5)] is all equal
-		assert_eq!(103u32.tcmp(&b, e), Ordering::Equal);
-		assert_eq!(104u32.tcmp(&b, e), Ordering::Equal);
-		assert_eq!(115u32.tcmp(&b, e), Ordering::Equal);
-		assert_eq!(120u32.tcmp(&b, e), Ordering::Equal);
-		assert_eq!(126u32.tcmp(&b, e), Ordering::Equal);
-		assert_eq!(127u32.tcmp(&b, e), Ordering::Equal);
-
-		assert_eq!(128u32.tcmp(&b, e), Ordering::Greater);
-		assert_eq!(102u32.tcmp(&b, e), Ordering::Less);
+		assert_eq!((103u32).tcmp(&b, e), Ordering::Equal);
+		assert_eq!((104u32).tcmp(&b, e), Ordering::Equal);
+		assert_eq!((115u32).tcmp(&b, e), Ordering::Equal);
+		assert_eq!((120u32).tcmp(&b, e), Ordering::Equal);
+		assert_eq!((126u32).tcmp(&b, e), Ordering::Equal);
+		assert_eq!((127u32).tcmp(&b, e), Ordering::Equal);
+
+		assert_eq!((128u32).tcmp(&b, e), Ordering::Greater);
+		assert_eq!((102u32).tcmp(&b, e), Ordering::Less);
 	}
 
 	#[test]
@@ -455,15 +537,15 @@ mod threshold_compare_tests {
 		let e = Perbill::from_parts(100) * b;
 
 		// [115 - 11,5 (103,5), 115 + 11,5 (126,5)] is all equal
-		assert_eq!(103u32.tcmp(&b, e), 103u32.cmp(&b));
-		assert_eq!(104u32.tcmp(&b, e), 104u32.cmp(&b));
-		assert_eq!(115u32.tcmp(&b, e), 115u32.cmp(&b));
-		assert_eq!(120u32.tcmp(&b, e), 120u32.cmp(&b));
-		assert_eq!(126u32.tcmp(&b, e), 126u32.cmp(&b));
-		assert_eq!(127u32.tcmp(&b, e), 127u32.cmp(&b));
-
-		assert_eq!(128u32.tcmp(&b, e), 128u32.cmp(&b));
-		assert_eq!(102u32.tcmp(&b, e), 102u32.cmp(&b));
+		assert_eq!((103u32).tcmp(&b, e), (103u32).cmp(&b));
+		assert_eq!((104u32).tcmp(&b, e), (104u32).cmp(&b));
+		assert_eq!((115u32).tcmp(&b, e), (115u32).cmp(&b));
+		assert_eq!((120u32).tcmp(&b, e), (120u32).cmp(&b));
+		assert_eq!((126u32).tcmp(&b, e), (126u32).cmp(&b));
+		assert_eq!((127u32).tcmp(&b, e), (127u32).cmp(&b));
+
+		assert_eq!((128u32).tcmp(&b, e), (128u32).cmp(&b));
+		assert_eq!((102u32).tcmp(&b, e), (102u32).cmp(&b));
 	}
 
 	#[test]

substrate/primitives/arithmetic/src/per_things.rs

@@ -15,6 +15,42 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Types that implement [`PerThing`](PerThing) can be used as a floating-point alternative for
+//! numbers that operate within the realm of `[0, 1]`. The primary types may you encounter in
+//! Substrate would be the following:
+//! - [`Percent`](Percent) - parts of one hundred.
+//! - [`Permill`](Permill) - parts of a million.
+//! - [`Perbill`](Perbill) - parts of a billion.
+//!
+//! In use, you may see them being used as follows:
+//!
+//! > **[`Perbill`](Perbill), parts of a billion**
+#![doc = docify::embed!("./src/lib.rs", perbill_example)]
+//! > **[`Percent`](Percent), parts of a hundred**
+#![doc = docify::embed!("./src/lib.rs", percent_example)]
+//!
+//! Note that `Percent` is represented as a _rounded down_, fixed point
+//! number (see the example above). Unlike primitive types, types that implement
+//! [`PerThing`](PerThing) will also not overflow, and are therefore safe to use.
+//! They adopt the same behavior that a saturated calculation would provide, meaning that if one is
+//! to go over "100%", it wouldn't overflow, but simply stop at the upper or lower bound.
+//!
+//! For use cases which require precision beyond the range of `[0, 1]`, there are fixed-point types
+//! which can be used.
+//!
+//! Each of these can be used to construct and represent ratios within our runtime.
+//! You will find types like [`Perbill`](Perbill) being used often in pallet
+//! development.  `pallet_referenda` is a good example of a pallet which makes good use of fixed
+//! point arithmetic, as it relies on representing various curves and thresholds relating to
+//! governance.
+//!
+//! #### Fixed Point Arithmetic with [`PerThing`](PerThing)
+//!
+//! As stated, one can also perform mathematics using these types directly. For example, finding the
+//! percentage of a particular item:
+
+#![doc = docify::embed!("./src/lib.rs", percent_mult)]
+
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};