chore: documentation for curve module (#801)

adds some docs for the curve module.

Author: Ad96el

pallets/pallet-bonded-coins/src/curves/lmsr.rs

@@ -1,3 +1,33 @@
+/// Implementation of the [Logarithmic Market Scoring Rule (LMSR)](https://mason.gmu.edu/~rhanson/mktscore.pdf) bonding curve.
+///
+/// This module provides an LMSR bonding curve implementation, which determines the cost of purchasing
+/// assets based on the liquidity parameter and the current supply of assets in the market.
+///
+/// ### Cost Function
+/// The LMSR bonding curve is defined by the equation:
+/// ```text
+/// C(s) = m * ln(Σ(e^(s_i / m)))
+/// ```
+/// Where:
+/// - `s` is the supply of all assets, represented as a vector,
+/// - `m` is the liquidity parameter of the LMSR model,
+/// - `s_i` is the supply of a single asset.
+///
+/// `C(s)` represents the accumulated cost of purchasing or selling assets up to the current supply `s`.
+///
+/// ### Incremental Cost
+/// To calculate the incremental cost of a transaction, use the formula:
+/// ```text
+/// Incremental Cost = C(s) - C(s*)
+/// ```
+/// Here:
+/// - `s*` is the supply of assets in the market before the transaction, and
+/// - `s` is the supply of assets after the transaction.
+///
+/// ### Optimization for Numerical Stability
+/// To ensure numerical stability and prevent overflow/underflow during calculations,
+/// this implementation uses the [log-sum-exp trick](https://en.wikipedia.org/wiki/LogSumExp).
+/// This technique improves precision when handling the summation and exponential terms in the cost function.
 use frame_support::ensure;
 use parity_scale_codec::{Decode, Encode, MaxEncodedLen};
 use scale_info::TypeInfo;
@@ -11,16 +41,26 @@ use substrate_fixed::{
 use super::BondingFunction;
 use crate::{PassiveSupply, Precision, LOG_TARGET};
 
+/// A struct representing the unchecked input parameters for the LMSR model. This struct is used to convert
+/// the input parameters to the correct fixed-point type.
 #[derive(Clone, Debug, Encode, Decode, PartialEq, Eq, TypeInfo, MaxEncodedLen)]
 pub struct LMSRParametersInput<Parameter> {
+	/// The liquidity parameter for the LMSR model
 	pub m: Parameter,
 }
 
+/// A struct representing the validated parameters for the LMSR model. This struct is used to store the
+/// parameters for the LMSR model and to perform calculations using the LMSR model.
 #[derive(Clone, Debug, Encode, Decode, PartialEq, Eq, TypeInfo, MaxEncodedLen)]
 pub struct LMSRParameters<Parameter> {
+	///The liquidity parameter for the LMSR model. This value must be greater than zero and unsigned.
 	pub m: Parameter,
 }
 
+/// Implementation of the TryFrom trait for `LMSRParametersInput` to convert the input parameters to
+/// the correct fixed-point type. The TryFrom implementation for `LMSRParameters` will fail if the
+/// conversion to the fixed-point type fails or if the liquidity parameter is less than or equal to
+/// zero.
 impl<I: FixedUnsigned, C: FixedSigned> TryFrom<LMSRParametersInput<I>> for LMSRParameters<C> {
 	type Error = ();
 	fn try_from(value: LMSRParametersInput<I>) -> Result<Self, Self::Error> {
@@ -35,6 +75,8 @@ where
 	Parameter: FixedSigned + PartialOrd<Precision> + From<Precision> + ToFixed,
 	<Parameter as Fixed>::Bits: Copy + ToFixed + AddAssign + BitOrAssign + ShlAssign,
 {
+	/// Calculate the logarithmic sum of the exponentials of the supply values,
+	/// using the log-sum-exp trick.
 	fn lse(&self, supply: &[Parameter]) -> Result<Parameter, ArithmeticError> {
 		// Find the maximum value in the supply for numerical stability
 		let max = supply.iter().max().ok_or_else(|| {
@@ -67,6 +109,7 @@ where
 	Parameter: FixedSigned + PartialOrd<Precision> + From<Precision> + ToFixed,
 	<Parameter as Fixed>::Bits: Copy + ToFixed + AddAssign + BitOrAssign + ShlAssign,
 {
+	/// Calculate the cost of purchasing a set of assets from the market using the LMSR model.
 	fn calculate_costs(
 		&self,
 		low: Parameter,

pallets/pallet-bonded-coins/src/curves/mod.rs

@@ -1,3 +1,10 @@
+///  Curve Module
+///
+/// This module defines various curve types and their associated parameters used in the system.
+/// It includes the following curve types:
+/// - Polynomial
+/// - SquareRoot
+/// - LMSR (Logarithmic Market Scoring Rule)
 pub(crate) mod lmsr;
 pub(crate) mod polynomial;
 pub(crate) mod square_root;
@@ -19,20 +26,29 @@ use crate::{
 	Config, CurveParameterTypeOf, PassiveSupply, Precision,
 };
 
+/// An enum representing different types of curves with their respective parameters.
+/// Used to store curve parameters and perform calculations.
 #[derive(Clone, Debug, Encode, Decode, PartialEq, Eq, TypeInfo, MaxEncodedLen)]
 pub enum Curve<Parameter> {
 	Polynomial(PolynomialParameters<Parameter>),
 	SquareRoot(SquareRootParameters<Parameter>),
 	Lmsr(LMSRParameters<Parameter>),
 }
 
+/// An enum representing input parameters for different types of curves.
+/// Used to convert into Curve.
 #[derive(Clone, Debug, Encode, Decode, PartialEq, Eq, TypeInfo, MaxEncodedLen)]
 pub enum CurveInput<Parameter> {
 	Polynomial(PolynomialParametersInput<Parameter>),
 	SquareRoot(SquareRootParametersInput<Parameter>),
 	Lmsr(LMSRParametersInput<Parameter>),
 }
 
+/// Implementation of the TryFrom trait for `CurveInput` to convert the input parameters to
+/// the correct fixed-point type. The TryFrom implementation for `Curve` will fail if the
+/// conversion to the fixed-point type fails.
+/// The conversion is done by converting the input parameters to the correct fixed-point type
+/// using the TryFrom implementation for the respective parameters type.
 impl<I, C> TryFrom<CurveInput<I>> for Curve<C>
 where
 	LMSRParameters<C>: TryFrom<LMSRParametersInput<I>>,
@@ -72,6 +88,10 @@ where
 	}
 }
 
+/// Implementation of the `BondingFunction` trait for `Curve`.
+/// The `BondingFunction` trait is used to calculate the cost of purchasing or selling assets using the curve.
+///
+/// The implementation forwards the call to the inner bonding function.
 impl<Parameter> BondingFunction<Parameter> for Curve<Parameter>
 where
 	Parameter: FixedSigned + PartialOrd<Precision> + From<Precision> + ToFixed,
@@ -87,6 +107,14 @@ where
 	}
 }
 
+/// Trait defining the bonding function for a curve.
+/// The bonding function is used to calculate the cost of purchasing or selling assets using the curve.
+/// The trait is implemented for each curve type.
+///
+/// Parameters:
+/// - `low`: The lower bound of integral.
+/// - `high`: The upper bound of integral.
+/// - `passive_supply`: The passive supply of other assets in the pool, which are not affected by the operation.
 pub trait BondingFunction<Balance> {
 	fn calculate_costs(
 		&self,
@@ -96,16 +124,19 @@ pub trait BondingFunction<Balance> {
 	) -> Result<Balance, ArithmeticError>;
 }
 
+/// Helper function to calculate the square of a fixed-point number.
 fn square<FixedType: Fixed>(x: FixedType) -> Result<FixedType, ArithmeticError> {
 	x.checked_mul(x).ok_or(ArithmeticError::Overflow)
 }
 
+/// Helper function to calculate the accumulated passive issuance.
 fn calculate_accumulated_passive_issuance<Balance: Fixed>(passive_issuance: &[Balance]) -> Balance {
 	passive_issuance
 		.iter()
 		.fold(Balance::from_num(0), |sum, x| sum.saturating_add(*x))
 }
 
+/// TODO. Implementation might change.
 pub(crate) fn convert_to_fixed<T: Config>(x: u128, denomination: u8) -> Result<CurveParameterTypeOf<T>, ArithmeticError>
 where
 	<CurveParameterTypeOf<T> as Fixed>::Bits: TryFrom<U256>, // TODO: make large integer type configurable in runtime

pallets/pallet-bonded-coins/src/curves/polynomial.rs

@@ -1,3 +1,44 @@
+/// Polynomial Bonding Curve Implementation.
+///
+/// This module provides an implementation of a polynomial bonding curve.
+/// The current implementation supports a polynomial function of order 2, with the integral precomputed for efficiency.
+///
+/// ### Cost Function
+/// The cost function is defined as:
+/// ```text
+/// c(s) = m * s^2 + n * s + o
+/// ```
+/// This function, `c(s)`, determines the price for purchasing or selling assets at any supply point `s`.
+/// The total cost of transactions is computed as the integral of `c(s)` between the start point and `s`.
+///
+/// ### Antiderivative
+/// The indefinite integral of the cost function is:
+/// ```text
+/// C(s) = (m / 3) * s^3 + (n / 2) * s^2 + o * s
+/// ```
+/// Where:
+/// - `m` is the coefficient for the quadratic term,
+/// - `n` is the coefficient for the linear term,
+/// - `o` is the constant term.
+///
+///
+/// `C(s)` represents the accumulated cost of purchasing or selling assets up to the current supply `s`.
+/// The integral between two supply points, `s*` (initial supply) and `s` (current supply), gives the incremental cost:
+/// ```text
+/// Incremental Cost = C(s) - C(s*)
+/// ```
+/// This captures the total cost for changing the supply from `s*` to `s`.
+///
+/// ### Optimization for Numerical Stability
+/// The computation of `s^3` can cause overflow in fixed-point arithmetic. To mitigate this, the calculation is factored as:
+/// ```text
+/// x^3 - y^3 = (x^2 + x * y + y^2) * (x - y)
+/// ```
+/// Where:
+/// - `x` is the upper limit of the integral,
+/// - `y` is the lower limit of the integral.
+///
+/// By breaking down the computation in this way, we reduce the risk of overflow while maintaining precision.
 use parity_scale_codec::{Decode, Encode, MaxEncodedLen};
 use scale_info::TypeInfo;
 use sp_arithmetic::ArithmeticError;
@@ -6,20 +47,50 @@ use substrate_fixed::traits::{FixedSigned, FixedUnsigned};
 use super::{calculate_accumulated_passive_issuance, square, BondingFunction};
 use crate::PassiveSupply;
 
+/// A struct representing the unchecked input parameters for a polynomial bonding curve.
+/// This struct is used to convert the input parameters to the correct fixed-point type.
+///
+/// The input struct assumes that the coefficients are precomputed according to the integral rules of the polynomial function.
+///
+/// ### Example
+///
+/// For a polynomial cost function `c(s) = 3 * s^2 + 2 * s + 2`
+///
+/// which is resulting into the antiderivative `C(s) = (3 / 3) * s^3 + (2 / 2) * s^2 + 2 * s`
+/// the input parameters would be:
+/// ```rust, ignore
+/// PolynomialParametersInput {
+///    m: 1,
+///    n: 1,
+///    o: 2,
+/// }
+/// ```
 #[derive(Clone, Debug, Encode, Decode, PartialEq, Eq, TypeInfo, MaxEncodedLen)]
 pub struct PolynomialParametersInput<Parameter> {
+	/// Coefficient for the cubic part.
 	pub m: Parameter,
+	/// Coefficient for the quadratic part.
 	pub n: Parameter,
+	/// Coefficient for the linear part.
 	pub o: Parameter,
 }
 
+/// A struct representing the validated parameters for a polynomial bonding curve.
+/// This struct is used to store the parameters for a polynomial bonding
+/// curve and to perform calculations using the polynomial bonding curve.
 #[derive(Clone, Debug, Encode, Decode, PartialEq, Eq, TypeInfo, MaxEncodedLen)]
 pub struct PolynomialParameters<Parameter> {
+	/// Coefficient for the cubic part.
 	pub m: Parameter,
+	/// Coefficient for the quadratic part.
 	pub n: Parameter,
+	/// Coefficient for the linear part.
 	pub o: Parameter,
 }
 
+/// Implementation of the TryFrom trait for `PolynomialParametersInput` to convert the input parameters to
+/// the correct fixed-point type. The TryFrom implementation for `PolynomialParameters` will fail if the
+/// conversion to the fixed-point type fails.
 impl<I: FixedUnsigned, C: FixedSigned> TryFrom<PolynomialParametersInput<I>> for PolynomialParameters<C> {
 	type Error = ();
 	fn try_from(value: PolynomialParametersInput<I>) -> Result<Self, Self::Error> {
@@ -35,6 +106,7 @@ impl<Parameter> BondingFunction<Parameter> for PolynomialParameters<Parameter>
 where
 	Parameter: FixedSigned,
 {
+	/// Calculate the cost of purchasing/selling assets using the polynomial bonding curve.
 	fn calculate_costs(
 		&self,
 		low: Parameter,

pallets/pallet-bonded-coins/src/curves/square_root.rs

@@ -1,3 +1,38 @@
+/// Square Root Bonding Curve Implementation.
+///
+/// This module provides an implementation of a square root bonding curve, with the integral precomputed for efficiency.
+///
+/// ### Cost Function
+/// The cost function is defined as:
+/// ```text
+/// c(s) = m * sqrt(s) + n
+/// ```
+/// This function, `c(s)`, determines the price for purchasing or selling assets at any supply point `s`.
+/// The total transaction cost is calculated as the integral of `c(s)` between the start point and `s`.
+///
+/// ### Antiderivative
+/// The indefinite integral of the cost function is:
+/// ```text
+/// C(s) = (2/3) * m * s^(3/2) + n * s
+/// ```
+/// Where:
+/// - `s` is the supply of assets,
+/// - `m` is the coefficient for the square root term,
+/// - `n` is the coefficient for the linear term.
+///
+/// `C(s)` represents the total cost of purchasing or selling assets up to the current supply `s`.
+/// To calculate the incremental cost of a transaction, use the formula:
+/// ```text
+/// Incremental Cost = C(s) - C(s*)
+/// ```
+/// Here, `s*` represents the initial supply before the transaction, and `s` is the supply after the transaction.
+///
+/// ### Optimization for Numerical Stability
+/// Calculating `s^(3/2)` directly can lead to overflow in fixed-point arithmetic. To mitigate this, the calculation is factored as:
+/// ```text
+/// sqrt(s^3) = sqrt(s) * s
+/// ```
+/// By expressing `s^(3/2)` as the product of `sqrt(s)` and `s`, we reduce the risk of overflow while maintaining computational precision.
 use parity_scale_codec::{Decode, Encode, MaxEncodedLen};
 use scale_info::TypeInfo;
 use sp_arithmetic::ArithmeticError;
@@ -9,18 +44,41 @@ use substrate_fixed::{
 use super::{calculate_accumulated_passive_issuance, BondingFunction};
 use crate::{PassiveSupply, Precision};
 
+/// A struct representing the unchecked input parameters for a square root bonding curve.
+/// This struct is used to convert the input parameters to the correct fixed-point type.
+///
+/// The input struct assumes that the coefficients are precomputed according to the integral rules of the square root function./// ### Example
+///
+/// For a square root cost function `c(s) = 3 * s^1/2 + 2
+///
+/// which is resulting into the antiderivative `C(s) = (6 / 3) * s^(1/2) + 2 * s`
+/// the input parameters would be:
+/// ```rust, ignore
+/// SquareRootParametersInput {
+///    m: 2,
+///    n: 2,
+/// }
+/// ```
 #[derive(Clone, Debug, Encode, Decode, PartialEq, Eq, TypeInfo, MaxEncodedLen)]
 pub struct SquareRootParametersInput<Parameter> {
+	/// Coefficient for the square root part.
 	pub m: Parameter,
+	/// Coefficient for the linear part.
 	pub n: Parameter,
 }
 
+/// A struct representing the validated parameters for a square root bonding curve.
+/// This struct is used to store the parameters for a square root bonding curve and to perform calculations using the square root bonding curve.
 #[derive(Clone, Debug, Encode, Decode, PartialEq, Eq, TypeInfo, MaxEncodedLen)]
 pub struct SquareRootParameters<Parameter> {
+	/// Coefficient for the square root part.
 	pub m: Parameter,
+	/// Coefficient for the linear part.
 	pub n: Parameter,
 }
 
+/// Implementation of the TryFrom trait for `SquareRootParametersInput` to convert the input parameters to the correct fixed-point type.
+/// The TryFrom implementation for `SquareRootParameters` will fail if the conversion to the fixed-point type fails.
 impl<I: FixedUnsigned, C: FixedSigned> TryFrom<SquareRootParametersInput<I>> for SquareRootParameters<C> {
 	type Error = ();
 	fn try_from(value: SquareRootParametersInput<I>) -> Result<Self, Self::Error> {
@@ -35,6 +93,7 @@ impl<Parameter> BondingFunction<Parameter> for SquareRootParameters<Parameter>
 where
 	Parameter: FixedSigned + PartialOrd<Precision> + From<Precision> + ToFixed,
 {
+	/// Calculate the cost of purchasing/selling assets using the square root bonding curve.
 	fn calculate_costs(
 		&self,
 		low: Parameter,