From 5aca751a9e84a77069e2ab52d5d62ba081b77dc3 Mon Sep 17 00:00:00 2001
From: Hugo Trentesaux <hugo@trentesaux.fr>
Date: Sun, 19 Feb 2023 18:50:02 +0100
Subject: [PATCH] more doc
---
pallets/certification/src/lib.rs | 7 +++++++
pallets/certification/src/types.rs | 4 ++++
pallets/universal-dividend/src/lib.rs | 21 ++++++++++++++++++++-
3 files changed, 31 insertions(+), 1 deletion(-)
diff --git a/pallets/certification/src/lib.rs b/pallets/certification/src/lib.rs
index 57a1d7e3c..7099ab19a 100644
--- a/pallets/certification/src/lib.rs
+++ b/pallets/certification/src/lib.rs
@@ -269,6 +269,7 @@ pub mod pallet {
#[pallet::call]
impl<T: Config<I>, I: 'static> Pallet<T, I> {
+ /// add a certification without checks (only root)
#[pallet::weight(1_000_000_000)]
pub fn force_add_cert(
origin: OriginFor<T>,
@@ -355,6 +356,7 @@ pub mod pallet {
Self::do_add_cert(block_number, issuer, receiver)
}
+ /// remove a certification (only root)
#[pallet::weight(1_000_000_000)]
pub fn del_cert(
origin: OriginFor<T>,
@@ -366,6 +368,7 @@ pub mod pallet {
Ok(().into())
}
+ /// remove all certifications received by an identity (only root)
#[pallet::weight(1_000_000_000)]
pub fn remove_all_certs_received_by(
origin: OriginFor<T>,
@@ -382,6 +385,7 @@ pub mod pallet {
// INTERNAL FUNCTIONS //
impl<T: Config<I>, I: 'static> Pallet<T, I> {
+ /// perform cert add
fn do_add_cert(
block_number: T::BlockNumber,
issuer: T::IdtyIndex,
@@ -438,6 +442,7 @@ pub mod pallet {
Ok(().into())
}
+ /// remove the certifications due to expire on the given block
fn prune_certifications(block_number: T::BlockNumber) -> Weight {
let mut total_weight = Weight::zero();
@@ -449,6 +454,7 @@ pub mod pallet {
total_weight
}
+ /// perform the certification removal
fn remove_cert_inner(
issuer: T::IdtyIndex,
receiver: T::IdtyIndex,
@@ -505,6 +511,7 @@ pub mod pallet {
}
}
+// implement setting next_issuable_on for certification period
impl<T: Config<I>, I: 'static> SetNextIssuableOn<T::BlockNumber, T::IdtyIndex> for Pallet<T, I> {
fn set_next_issuable_on(idty_index: T::IdtyIndex, next_issuable_on: T::BlockNumber) -> Weight {
<StorageIdtyCertMeta<T, I>>::mutate_exists(idty_index, |cert_meta_opt| {
diff --git a/pallets/certification/src/types.rs b/pallets/certification/src/types.rs
index 4ab2c51cd..7eadcabc5 100644
--- a/pallets/certification/src/types.rs
+++ b/pallets/certification/src/types.rs
@@ -20,10 +20,14 @@ use codec::{Decode, Encode};
use frame_support::pallet_prelude::*;
use scale_info::TypeInfo;
+/// certification metadata attached to an identity
#[derive(Encode, Decode, Clone, Copy, PartialEq, Eq, RuntimeDebug, TypeInfo)]
pub struct IdtyCertMeta<BlockNumber: Default> {
+ /// count issued certifications
pub issued_count: u32,
+ /// block before which identity not allowed to issue a new certification
pub next_issuable_on: BlockNumber,
+ /// number of certifications received
pub received_count: u32,
}
diff --git a/pallets/universal-dividend/src/lib.rs b/pallets/universal-dividend/src/lib.rs
index 41992650d..73d5af1eb 100644
--- a/pallets/universal-dividend/src/lib.rs
+++ b/pallets/universal-dividend/src/lib.rs
@@ -254,7 +254,9 @@ pub mod pallet {
// INTERNAL FUNCTIONS //
impl<T: Config> Pallet<T> {
+ /// create universal dividend
fn create_ud(members_count: BalanceOf<T>) {
+ // get current value of UD and monetary mass
let ud_amount = <CurrentUd<T>>::get();
let monetary_mass = <MonetaryMass<T>>::get();
@@ -263,9 +265,14 @@ pub mod pallet {
core::mem::replace(next_ud_index, next_ud_index.saturating_add(1))
});
+ // compute the new monetary mass
let new_monetary_mass =
monetary_mass.saturating_add(ud_amount.saturating_mul(members_count));
+
+ // update the storage value of the monetary mass
MonetaryMass::<T>::put(new_monetary_mass);
+
+ // emit an event to inform blockchain users that the holy UNIVERSAL DIVIDEND was created
Self::deposit_event(Event::NewUdCreated {
amount: ud_amount,
index: ud_index,
@@ -273,6 +280,8 @@ pub mod pallet {
monetary_mass: new_monetary_mass,
});
}
+
+ /// claim all due universal dividend at a time
fn do_claim_uds(who: &T::AccountId) -> DispatchResultWithPostInfo {
T::MembersStorage::try_mutate_exists(who, |maybe_first_eligible_ud| {
if let Some(FirstEligibleUd(Some(ref mut first_ud_index))) = maybe_first_eligible_ud
@@ -304,6 +313,8 @@ pub mod pallet {
}
})
}
+
+ /// like balance.transfer, but give an amount in UD
fn do_transfer_ud(
origin: OriginFor<T>,
dest: <T::Lookup as StaticLookup>::Source,
@@ -321,11 +332,14 @@ pub mod pallet {
)?;
Ok(().into())
}
+
+ /// reevaluate the value of the universal dividend
fn reeval_ud(members_count: BalanceOf<T>) {
+ // get current value and monetary mass
let ud_amount = <CurrentUd<T>>::get();
-
let monetary_mass = <MonetaryMass<T>>::get();
+ // compute new value
let new_ud_amount = Self::reeval_ud_formula(
ud_amount,
T::SquareMoneyGrowthRate::get(),
@@ -336,6 +350,7 @@ pub mod pallet {
),
);
+ // update the storage value and the history of past reevals
CurrentUd::<T>::put(new_ud_amount);
PastReevals::<T>::mutate(|past_reevals| {
if past_reevals.len() == T::MaxPastReeval::get() as usize {
@@ -352,6 +367,8 @@ pub mod pallet {
members_count,
});
}
+
+ /// formula for Universal Dividend reevaluation
fn reeval_ud_formula(
ud_t: BalanceOf<T>,
c_square: Perbill,
@@ -406,6 +423,8 @@ pub mod pallet {
pub fn init_first_eligible_ud() -> FirstEligibleUd {
CurrentUdIndex::<T>::get().into()
}
+ /// function to call when removing a member
+ /// auto-claims UDs
pub fn on_removed_member(first_ud_index: UdIndex, who: &T::AccountId) -> Weight {
let current_ud_index = CurrentUdIndex::<T>::get();
if first_ud_index < current_ud_index {
--
GitLab