From 0e36dedd2ea603e0376ba12ae46b8f3ed6e37119 Mon Sep 17 00:00:00 2001
From: bgallois <benjamin@gallois.cc>
Date: Wed, 6 Dec 2023 14:07:18 +0100
Subject: [PATCH] add pallet membership documentation
---
pallets/membership/README.md | 24 +++++++++++++++++++++++-
pallets/membership/src/lib.rs | 2 +-
primitives/membership/src/lib.rs | 8 ++++----
3 files changed, 28 insertions(+), 6 deletions(-)
diff --git a/pallets/membership/README.md b/pallets/membership/README.md
index ff9c1f0c6..116b2addd 100644
--- a/pallets/membership/README.md
+++ b/pallets/membership/README.md
@@ -1,3 +1,25 @@
# Duniter membership pallet
-Duniter membership is related to duniter Web of Trust and more specific than [parity membership pallet](https://github.com/paritytech/substrate/tree/master/frame/membership). It is used only internally by the identity, WoT, and distance pallets. In particular, it is adding the concept of "pending membership" which is an intermediate state where the identity is waiting to become member.
\ No newline at end of file
+Duniter membership is related to duniter Web of Trust and more specific than [parity membership pallet](https://github.com/paritytech/substrate/tree/master/frame/membership). It is used only internally by the identity, WoT, and distance pallets. In particular, it is adding the concept of "pending membership" which is an intermediate state where the identity is waiting to become member.
+
+## Main Web of Trust
+
+When used in conjunction with the main Web of Trust, the membership pallet is combined with the Duniter-WoT pallet and the identity pallet, resulting in the following functionality:
+
+- `request_membership` is automatically invoked when confirming identity and should not be called manually. It will add the identity to the pending membership.
+- `claim_membership` is automatically triggered during identity validation and should not be manually invoked. This process requires a pending membership, sufficient membership certificates, and a valid distance. Membership is granted upon successful completion of these requirements.
+- `renew_membership` requires a valid membership and a valid distance status to extend the validity period of a membership.
+- `revoke_membership` is automatically executed when a membership expires and should not be called manually.
+
+In practice, a new user creates an account, confirms identity using the `confirm_identity` call from the identity pallet, and is added to the pending membership. The user then validates it identity using the `validate_identity` call from the identity pallet, triggering a membership claim. If the certification and distance requirements are met, the identity is granted membership.
+
+## Sub Web of Trust Smith
+
+Functionality related to the Smith Web of Trust involves the following:
+
+- `request_membership` requires a validated identity for the member to be added to the pending membership.
+- `claim_membership` requires a pending membership, sufficient smith certificates, and a valid distance status for the identity to be included among the authority members.
+- `renew_membership` needs a valid membership and a valid distance status to extend the membership's validity period.
+- `revoke_membership` requires a valid origin to revoke the membership.
+
+In practice, a user must complete all steps to gain membership in the main Web Of Trust. They can then manually request smith membership using the `request_membership` call of the membership pallet. The membership can be claimed using the `claim_membership` call from the membership pallet, and if the identity meets smith certificate and distance requirements, it will be added to the authority members.
\ No newline at end of file
diff --git a/pallets/membership/src/lib.rs b/pallets/membership/src/lib.rs
index 60c346a2f..1fcd8ce74 100644
--- a/pallets/membership/src/lib.rs
+++ b/pallets/membership/src/lib.rs
@@ -176,7 +176,7 @@ pub mod pallet {
member: T::IdtyId,
expire_on: BlockNumberFor<T>,
},
- /// A pending membership request has expired.
+ /// A pending membership has expired.
PendingMembershipExpired { member: T::IdtyId },
}
diff --git a/primitives/membership/src/lib.rs b/primitives/membership/src/lib.rs
index 4fb1629f6..e362219e4 100644
--- a/primitives/membership/src/lib.rs
+++ b/primitives/membership/src/lib.rs
@@ -28,15 +28,15 @@ use scale_info::TypeInfo;
use serde::{Deserialize, Serialize};
pub enum Event<IdtyId> {
- /// A membership has acquired
+ /// A membership was acquired.
MembershipAcquired(IdtyId),
/// A membership was terminated.
MembershipTerminated(IdtyId),
- /// A membership has renewed
+ /// A membership was renewed.
MembershipRenewed(IdtyId),
- /// An identity requested membership
+ /// A pending membership request was added.
PendingMembershipAdded(IdtyId),
- /// A pending membership request has expired
+ /// A pending membership request has expired.
PendingMembershipExpired(IdtyId),
}
--
GitLab