update documentation

runtime/common/src/fees.rs

@@ -14,12 +14,26 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with Duniter-v2S. If not, see <https://www.gnu.org/licenses/>.
 
-// In the deployed fees model, a mapping of 5 (5cG) corresponds to a base extrinsic weight,
-// achieved through a 1-dimensional polynomial. Additionally, 1 (1cG) corresponds to an extrinsic length of 100 bytes.
-//
-// For testing purposes, we adopt a human-predictable weight system that remains invariant to the chosen fees model for release.
-// This involves setting a constant weight_to_fee equal to 1 and a constant length_to_fee set to 0, resulting in each extrinsic costing 2 (2cG).
-
+/// In our deployed fee model, users will not pay any fees if blockchain usage remains below a
+/// specified threshold, and fees are applied based on transaction weight and length once this
+/// threshold is exceeded, helping to prevent spamming attacks.
+///
+/// When the current block's weight and length are below the targeted thresholds, no fees are charged,
+/// as the weight-to-fee conversion results in zero. Once the block's weight and length exceed these
+/// targets, the weight-to-fee conversion maps 5 (5cG) to a base extrinsic weight.
+/// Additionally, a fee is applied based on the length of the extrinsic and is mapped linearly:
+/// 1_000 (10G) corresponds to an extrinsic length of 3.5 kilobytes and will be applied only if the extrinsic
+/// exceeds 256 bytes or if the block target in weight or length is surpassed.
+///
+/// To further deter abuse, if the previous block's weight or length  the target thresholds,
+/// the chain increases the fees by multiplying the transaction weight with a `FeeMultiplier`. For each
+/// consecutive block that exceeds the targets, this multiplier increases by one. If the targets are
+/// not reached, the multiplier decreases by one. The `FeeMultiplier` ranges from 1 (normal usage) to
+/// `MaxMultiplier`, where heavy usage causes a number `MaxMultiplier` of consecutive blocks to exceed targets.
+///
+/// For testing purposes, a simplified, human-predictable weight system is used. This test model sets
+/// a constant `weight_to_fee` of 1 and a `length_to_fee` of 0, making each extrinsic cost 2 (2cG),
+/// and can be activated with the #[cfg(feature = "constant-fees")] feature.
 pub use frame_support::weights::{Weight, WeightToFee};
 use pallet_transaction_payment::{Multiplier, MultiplierUpdate};
 use sp_arithmetic::traits::{BaseArithmetic, Unsigned};