doc identity

pallets/identity/src/lib.rs

@@ -312,6 +312,7 @@ pub mod pallet {
             T::OnIdtyChange::on_idty_change(idty_index, &IdtyEvent::Created { creator });
             Ok(().into())
         }
+
         /// Confirm the creation of an identity and give it a name
         ///
         /// - `idty_name`: the name uniquely associated to this identity. Must match the validation rules defined by the runtime.
@@ -355,7 +356,9 @@ pub mod pallet {
             T::OnIdtyChange::on_idty_change(idty_index, &IdtyEvent::Confirmed);
             Ok(().into())
         }
+
         #[pallet::weight(1_000_000_000)]
+        /// validate the owned identity (must meet the main wot requirements)
         pub fn validate_identity(
             origin: OriginFor<T>,
             idty_index: T::IdtyIndex,
@@ -517,6 +520,7 @@ pub mod pallet {
         }
 
         #[pallet::weight(1_000_000_000)]
+        /// remove an identity from storage
         pub fn remove_identity(
             origin: OriginFor<T>,
             idty_index: T::IdtyIndex,
@@ -533,6 +537,7 @@ pub mod pallet {
         }
 
         #[pallet::weight(1_000_000_000)]
+        /// remove identity names from storage
         pub fn prune_item_identities_names(
             origin: OriginFor<T>,
             names: Vec<IdtyName>,
@@ -547,6 +552,7 @@ pub mod pallet {
         }
 
         #[pallet::weight(1_000_000_000)]
+        /// change sufficient ref count for given key
         pub fn fix_sufficients(
             origin: OriginFor<T>,
             owner_key: T::AccountId,
@@ -625,6 +631,7 @@ pub mod pallet {
     // INTERNAL FUNCTIONS //
 
     impl<T: Config> Pallet<T> {
+        /// perform identity removal
         pub(super) fn do_remove_identity(idty_index: T::IdtyIndex) -> Weight {
             if let Some(idty_val) = Identities::<T>::get(idty_index) {
                 let _ = T::RemoveIdentityConsumers::remove_idty_consumers(idty_index);
@@ -645,6 +652,7 @@ pub mod pallet {
             }
             Weight::zero()
         }
+        /// incremental counter for identity index
         fn get_next_idty_index() -> T::IdtyIndex {
             if let Ok(next_index) = <NextIdtyIndex<T>>::try_get() {
                 <NextIdtyIndex<T>>::put(next_index.saturating_add(T::IdtyIndex::one()));
@@ -654,6 +662,7 @@ pub mod pallet {
                 T::IdtyIndex::one()
             }
         }
+        /// remove identities planned for removal at the given block if their status did not change
         fn prune_identities(block_number: T::BlockNumber) -> Weight {
             let mut total_weight = Weight::zero();
 
@@ -670,16 +679,21 @@ pub mod pallet {
     }
 }
 
+// implement getting owner key of identity index
+
 impl<T: Config> sp_runtime::traits::Convert<T::IdtyIndex, Option<T::AccountId>> for Pallet<T> {
     fn convert(idty_index: T::IdtyIndex) -> Option<T::AccountId> {
         Identities::<T>::get(idty_index).map(|idty_val| idty_val.owner_key)
     }
 }
 
+// implement StoredMap trait for this pallet
+
 impl<T> frame_support::traits::StoredMap<T::AccountId, T::IdtyData> for Pallet<T>
 where
     T: Config,
 {
+    /// get identity data for an account id
     fn get(key: &T::AccountId) -> T::IdtyData {
         if let Some(idty_index) = Self::identity_index_of(key) {
             if let Some(idty_val) = Identities::<T>::get(idty_index) {
@@ -691,6 +705,7 @@ where
             Default::default()
         }
     }
+    /// mutate an account fiven a function of its data
     fn try_mutate_exists<R, E: From<sp_runtime::DispatchError>>(
         key: &T::AccountId,
         f: impl FnOnce(&mut Option<T::IdtyData>) -> Result<R, E>,

pallets/identity/src/types.rs

@@ -23,17 +23,25 @@ use scale_info::TypeInfo;
 use serde::{Deserialize, Serialize};
 use sp_std::vec::Vec;
 
+/// events related to identity
 pub enum IdtyEvent<T: crate::Config> {
+    /// creation of a new identity by an other
     Created { creator: T::IdtyIndex },
+    /// confirmation of an identity (with a given name)
     Confirmed,
+    /// validation of an identity
     Validated,
+    /// changing the owner key of the identity
     ChangedOwnerKey { new_owner_key: T::AccountId },
+    /// removing an identity
     Removed { status: IdtyStatus },
 }
 
+/// name of the identity, ascii encoded
 #[derive(Encode, Decode, Default, Clone, PartialEq, Eq, PartialOrd, Ord, RuntimeDebug)]
 pub struct IdtyName(pub Vec<u8>);
 
+/// implement scale string typeinfo for encoding
 impl scale_info::TypeInfo for IdtyName {
     type Identity = str;
 
@@ -65,6 +73,8 @@ impl<'de> serde::Deserialize<'de> for IdtyName {
     }
 }
 
+/// status of the identity
+/// used for temporary period before validation
 #[cfg_attr(feature = "std", derive(Deserialize, Serialize))]
 #[derive(Encode, Decode, Clone, Copy, PartialEq, Eq, RuntimeDebug, TypeInfo)]
 pub enum IdtyStatus {
@@ -78,28 +88,44 @@ impl Default for IdtyStatus {
     }
 }
 
+/// identity value (as in key/value)
 #[cfg_attr(feature = "std", derive(Debug, Deserialize, Serialize))]
 #[derive(Encode, Decode, Clone, PartialEq, Eq, TypeInfo)]
 pub struct IdtyValue<BlockNumber, AccountId, IdtyData> {
+    /// data shared between pallets defined by runtime
+    /// only contains first_eligible_ud in our case
     pub data: IdtyData,
+    /// block before which creating a new identity is not allowed
     pub next_creatable_identity_on: BlockNumber,
+    /// previous owner key of this identity (optional)
     pub old_owner_key: Option<(AccountId, BlockNumber)>,
+    /// current owner key of this identity
     pub owner_key: AccountId,
+    /// block before which this identity can not be removed
+    /// used only for temporary period before validation
+    /// equals 0 for a validated identity
     pub removable_on: BlockNumber,
+    /// current status of the identity (until validation)
     pub status: IdtyStatus,
 }
 
+/// payload to define a new owner key
 #[derive(Clone, Copy, Encode, RuntimeDebug)]
 pub struct NewOwnerKeyPayload<'a, AccountId, IdtyIndex, Hash> {
+    /// hash of the genesis block
     // Avoid replay attack between networks
     pub genesis_hash: &'a Hash,
+    /// identity index
     pub idty_index: IdtyIndex,
+    /// old owner key of the identity
     pub old_owner_key: &'a AccountId,
 }
 
 #[derive(Clone, Copy, Encode, Decode, PartialEq, Eq, TypeInfo, RuntimeDebug)]
 pub struct RevocationPayload<IdtyIndex, Hash> {
+    /// hash of the genesis block
     // Avoid replay attack between networks
     pub genesis_hash: Hash,
+    /// identity index
     pub idty_index: IdtyIndex,
 }