From cee0b3f3fba6dd6bbfb74770bb7913d4eefbc0bc Mon Sep 17 00:00:00 2001 From: bgallois <benjamin@gallois.cc> Date: Tue, 18 Jun 2024 11:05:03 +0200 Subject: [PATCH] incode pallet description --- docs/api/runtime-calls.md | 8 ++-- docs/api/runtime-errors.md | 9 +++- pallets/authority-members/README.md | 25 ----------- pallets/authority-members/src/lib.rs | 28 ++++++++++++- pallets/certification/README.md | 8 ---- pallets/certification/src/lib.rs | 9 ++++ pallets/distance/README.md | 47 --------------------- pallets/distance/src/lib.rs | 48 ++++++++++++++++++++++ pallets/duniter-account/README.md | 15 ------- pallets/duniter-account/src/lib.rs | 15 ++++++- pallets/duniter-test-parameters/README.md | 3 -- pallets/duniter-test-parameters/src/lib.rs | 4 ++ pallets/duniter-wot/README.md | 21 ---------- pallets/duniter-wot/src/lib.rs | 32 +++++++++++++-- pallets/identity/README.md | 45 -------------------- pallets/identity/src/lib.rs | 37 +++++++++++++++++ pallets/membership/README.md | 7 ---- pallets/membership/src/lib.rs | 8 ++++ pallets/offences/README.md | 9 ---- pallets/offences/src/lib.rs | 19 +++++++++ pallets/oneshot-account/README.md | 3 -- pallets/oneshot-account/src/lib.rs | 4 ++ pallets/provide-randomness/README.md | 3 -- pallets/provide-randomness/src/lib.rs | 6 +++ pallets/quota/README.md | 31 -------------- pallets/quota/src/lib.rs | 21 ++++++++++ pallets/session-benchmarking/README.md | 4 -- pallets/session-benchmarking/src/lib.rs | 9 +++- pallets/smith-members/README.md | 3 -- pallets/smith-members/src/lib.rs | 23 +++++++++++ pallets/universal-dividend/README.md | 5 --- pallets/universal-dividend/src/lib.rs | 12 ++++++ pallets/upgrade-origin/README.md | 3 -- 33 files changed, 280 insertions(+), 244 deletions(-) delete mode 100644 pallets/authority-members/README.md delete mode 100644 pallets/certification/README.md delete mode 100644 pallets/distance/README.md delete mode 100644 pallets/duniter-account/README.md delete mode 100644 pallets/duniter-test-parameters/README.md delete mode 100644 pallets/duniter-wot/README.md delete mode 100644 pallets/identity/README.md delete mode 100644 pallets/membership/README.md delete mode 100644 pallets/offences/README.md delete mode 100644 pallets/oneshot-account/README.md delete mode 100644 pallets/provide-randomness/README.md delete mode 100644 pallets/quota/README.md delete mode 100644 pallets/session-benchmarking/README.md delete mode 100644 pallets/smith-members/README.md delete mode 100644 pallets/universal-dividend/README.md delete mode 100644 pallets/upgrade-origin/README.md diff --git a/docs/api/runtime-calls.md b/docs/api/runtime-calls.md index 68c737183..320e6a185 100644 --- a/docs/api/runtime-calls.md +++ b/docs/api/runtime-calls.md @@ -812,7 +812,7 @@ Transfer some liquid free balance to another account, in milliUD. <details><summary><code>create_identity(owner_key)</code></summary> -Taking 0.0912 % of a block. +Taking 0.0914 % of a block. ```rust owner_key: T::AccountId @@ -830,7 +830,7 @@ The origin must be allowed to create an identity. <details><summary><code>confirm_identity(idty_name)</code></summary> -Taking 0.0338 % of a block. +Taking 0.0339 % of a block. ```rust idty_name: IdtyName @@ -869,7 +869,7 @@ The origin should be the old identity owner key. <details><summary><code>revoke_identity(idty_index, revocation_key, revocation_sig)</code></summary> -Taking 0.0416 % of a block. +Taking 0.0417 % of a block. ```rust idty_index: T::IdtyIndex @@ -2261,7 +2261,7 @@ O(P) where P is the number of max proposals <details><summary><code>prune_item_identities_names(names)</code></summary> -Taking 6.0421 % of a block. +Taking 6.0424 % of a block. ```rust names: Vec<IdtyName> diff --git a/docs/api/runtime-errors.md b/docs/api/runtime-errors.md index 667342478..48bc9f68c 100644 --- a/docs/api/runtime-errors.md +++ b/docs/api/runtime-errors.md @@ -1,6 +1,6 @@ # Runtime errors -There are **189** errors from **35** pallets. +There are **190** errors from **35** pallets. <ul> <li>System - 0 @@ -972,6 +972,13 @@ Can not revoke identity that never was member. Cannot link to an inexisting account. </details> </li> +<li> +<details> +<summary> +<code>InsufficientBalance</code> - 17</summary> +Insufficient balance to create an identity. +</details> +</li> </ul> </li> <li>Membership - 42 diff --git a/pallets/authority-members/README.md b/pallets/authority-members/README.md deleted file mode 100644 index 3edf76eba..000000000 --- a/pallets/authority-members/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# Duniter authority members pallet - -In a permissioned network, we have to define the set of authorities, and among these authorities, the ones validators in the next session. That's what authority members pallet does. In practice: - -- it manages a `Members` set with some custom rules -- it implements the `SessionManager` trait from the FRAME session pallet - -## Entering the set of authorities - -To become part of Duniter authorities, one has to complete these steps: - -1. become member of the main web of trust -1. request membership to the smith sub wot -1. get enough certs to get smith membership -1. claim membership to the set of authorities - -Then one can "go online" and "go offline" to enter or leave two sessions after. - -## Some vocabulary - -*Smiths* are people allowed to forge blocks, but in details this is: - -- **smith** status required to become an authority -- **authority** status required to become validator -- **validator** status required to add blocks \ No newline at end of file diff --git a/pallets/authority-members/src/lib.rs b/pallets/authority-members/src/lib.rs index 052d4130a..0b06e1acf 100644 --- a/pallets/authority-members/src/lib.rs +++ b/pallets/authority-members/src/lib.rs @@ -14,6 +14,33 @@ // 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/>. +//! # Duniter Authority Members Pallet +//! +//! In a permissioned network, defining the set of authorities and selecting validators for the next session is crucial. +//! The authority members pallet is responsible for this. Specifically, it: +//! +//! - Manages a `Members` set with custom rules. +//! - Implements the `SessionManager` trait from the FRAME session pallet. +//! +//! ## Entering the Set of Authorities +//! +//! To become part of Duniter authorities, one must follow these steps: +//! +//! 1. Become a member of the main web of trust. +//! 2. Request membership to the smith sub web of trust. +//! 3. Obtain enough certifications to gain smith membership. +//! 4. Claim membership to the set of authorities. +//! +//! After becoming an authority, one can "go online" and "go offline" to enter or leave two sessions later. +//! +//! ## Some Vocabulary +//! +//! *Smiths* are individuals allowed to forge blocks. Specifically, this entails: +//! +//! - **Smith** status is required to become an authority. +//! - **Authority** status is required to become a validator. +//! - **Validator** status is required to add blocks. + #![cfg_attr(not(feature = "std"), no_std)] #![allow(clippy::type_complexity)] @@ -31,7 +58,6 @@ mod tests; #[cfg(feature = "runtime-benchmarks")] mod benchmarking; -//pub use impls::*; pub use pallet::*; pub use sp_staking::SessionIndex; pub use traits::*; diff --git a/pallets/certification/README.md b/pallets/certification/README.md deleted file mode 100644 index a84e9f9ea..000000000 --- a/pallets/certification/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# Duniter certification pallet - -Duniter certifications are the *edges* in the Duniter [Web of Trust](../duniter-wot/). They can have different meanings: - -- in the case of the main WoT, they mean "I have met this person IRL and trust them" (see Ğ1 Licence) -- in the case of the smith sub-WoT, they mean "I trust this person to be able to run Duniter securely" (see smith Licence) - -This pallet manages certifications creation, deletion... \ No newline at end of file diff --git a/pallets/certification/src/lib.rs b/pallets/certification/src/lib.rs index 01df96349..d1c3ffd01 100644 --- a/pallets/certification/src/lib.rs +++ b/pallets/certification/src/lib.rs @@ -14,6 +14,15 @@ // 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/>. +//! # Duniter Certification Pallet +//! +//! This pallet manages certification creation and deletion. +//! +//! Duniter certifications are the *edges* in the Duniter [Web of Trust](../duniter-wot/). They can have different meanings: +//! +//! - In the case of the main WoT, they mean "I have met this person in real life and trust them" (see Ğ1 Licence). +//! - In the case of the smith sub-WoT, they mean "I trust this person to be able to run Duniter securely" (see smith Licence). + #![cfg_attr(not(feature = "std"), no_std)] #[cfg(feature = "runtime-benchmarks")] diff --git a/pallets/distance/README.md b/pallets/distance/README.md deleted file mode 100644 index d34bdb646..000000000 --- a/pallets/distance/README.md +++ /dev/null @@ -1,47 +0,0 @@ -# Distance pallet - -The distance pallet uses results provided in a file by the `distance-oracle` offchain worker. -At some point an inherent is called to submit the results of this file to the blockchain. -The pallet then selects the median of the results (reach perbill) of an evaluation pool and fills the storage with the result status. -The status of an identity can be: - -- inexistant: distance evaluation has not been requested or has expired -- pending: distance evaluation for this identity has been requested and is waiting two evaluation periods for results -- valid: distance has been evaluated positively for this identity - -The result of the evaluation is used by `duniter-wot` pallet to determine if an identity can get / should loose membership to the web of trust. - -## Process - -Any account can request a distance evaluation for a given identity provided it has enough currency to be reserved. In this case, the distance status is marked as pending and in the next evaluation period, inherents can start to publish results. - -This is how a result is published: - -1. local worker creates a file containing the result of computation -1. inherent is created with the data from this file -1. author is registered as an evaluator -1. the result is added to the current evaluation pool -1. a flag is set to prevent other distance evaluation in the same block - -On each new evaluation period: - -1. old results set to expire at this period do expire -1. results from the current pool (previous period's result pool) are taken and for each identity - - the median of the distance results for this identity is chosen - - if the distance is ok, the distance is marked as valid - - if the distance is ko, the result for this identity is removed and reserved currency is slashed (from the account which requested the evaluation) - -Then, in other pallets, when a membership is claimed, it is possible to look if there is a valid evaluation of distance for this identity. - -## Pools - -Evaluation pools are made of two components: - -- a set of evaluators -- a vec of results - -The evaluation are separated in three pools: - -- pool number N - 1 % 3: results from the previous evaluation period used in the current one (let empty for next evaluation period) -- pool number N + 0 % 3: inherent results are added there -- pool number N + 1 % 3: identities are added there for evaluation diff --git a/pallets/distance/src/lib.rs b/pallets/distance/src/lib.rs index b52e2bb08..dd6bbfe83 100644 --- a/pallets/distance/src/lib.rs +++ b/pallets/distance/src/lib.rs @@ -14,6 +14,54 @@ // 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/>. +//! # Distance Pallet +//! +//! The distance pallet utilizes results provided in a file by the `distance-oracle` offchain worker. +//! At a some point, an inherent is called to submit the results of this file to the blockchain. +//! The pallet then selects the median of the results (reach perbill) from an evaluation pool and fills the storage with the result status. +//! The status of an identity can be: +//! +//! - **Non-existent**: Distance evaluation has not been requested or has expired. +//! - **Pending**: Distance evaluation for this identity has been requested and is awaiting results after two evaluation periods. +//! - **Valid**: Distance has been evaluated positively for this identity. +//! +//! The evaluation result is used by the `duniter-wot` pallet to determine if an identity can gain or should lose membership in the web of trust. +//! +//! ## Process +//! +//! Any account can request a distance evaluation for a given identity provided it has enough currency to reserve. In this case, the distance status is marked as pending, and in the next evaluation period, inherents can start to publish results. +//! +//! This is the process for publishing a result: +//! +//! 1. A local worker creates a file containing the computation result. +//! 2. An inherent is created with the data from this file. +//! 3. The author is registered as an evaluator. +//! 4. The result is added to the current evaluation pool. +//! 5. A flag is set to prevent other distance evaluations in the same block. +//! +//! At the start of each new evaluation period: +//! +//! 1. Old results set to expire at this period are removed. +//! 2. Results from the current pool (results from the previous period's pool) are processed, and for each identity: +//! - The median of the distance results for this identity is chosen. +//! - If the distance is acceptable, it is marked as valid. +//! - If the distance is not acceptable, the result for this identity is discarded, and reserved currency is slashed (from the account which requested the evaluation). +//! +//! Then, in other pallets, when a membership is claimed, it is possible to check if there is a valid distance evaluation for this identity. +//! +//! ## Pools +//! +//! Evaluation pools consist of two components: +//! +//! - A set of evaluators. +//! - A vector of results. +//! +//! The evaluations are divided into three pools: +//! +//! - Pool number N - 1 % 3: Results from the previous evaluation period used in the current one (emptied for the next evaluation period). +//! - Pool number N + 0 % 3: Inherent results are added here. +//! - Pool number N + 1 % 3: Identities are added here for evaluation. + #![cfg_attr(not(feature = "std"), no_std)] mod median; diff --git a/pallets/duniter-account/README.md b/pallets/duniter-account/README.md deleted file mode 100644 index 185e37ce5..000000000 --- a/pallets/duniter-account/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Duniter account pallet - -Duniter customizes the `AccountData` of the `Balances` Substrate pallet. In particular, it adds the field `linked_idty`. - -## Account creation fee - -DuniterAccount defines a creation fee that is preleved to the account one block after its creation. This fee goes to the treasury. - -## Sufficient - -DuniterAccount tweaks the substrate AccountInfo to allow identity accounts to exist without existential deposit. This allows to spare the creation fee. - -## Linked identity - -Duniter offers the possibility to link an account to an identity with the `linked_idty` field. It allows to request refund of transaction fees in `OnChargeTransaction`. \ No newline at end of file diff --git a/pallets/duniter-account/src/lib.rs b/pallets/duniter-account/src/lib.rs index 76209d042..b60d1c8bb 100644 --- a/pallets/duniter-account/src/lib.rs +++ b/pallets/duniter-account/src/lib.rs @@ -14,7 +14,20 @@ // 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/>. -// Note: refund queue mechanism is inspired from frame contract +//! # Duniter Account Pallet +//! +//! Duniter customizes the `AccountData` of the `Balances` Substrate pallet to include additional fields +//! such as `linked_idty`. +//! +//! ## Sufficiency +//! +//! DuniterAccount adjusts the Substrate `AccountInfo` to accommodate identity-linked accounts without requiring +//! an existential deposit. This flexibility helps reduce barriers to account creation. +//! +//! ## Linked Identity +//! +//! Duniter allows accounts to be linked to identities using the `linked_idty` field. This linkage facilitates +//! transaction fee refunds through the `OnChargeTransaction` mechanism. #![cfg_attr(not(feature = "std"), no_std)] diff --git a/pallets/duniter-test-parameters/README.md b/pallets/duniter-test-parameters/README.md deleted file mode 100644 index 80a352ff4..000000000 --- a/pallets/duniter-test-parameters/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Duniter test parameters - -This pallet allows ĞDev runtime to tweak parameter values instead of having it runtime constants. \ No newline at end of file diff --git a/pallets/duniter-test-parameters/src/lib.rs b/pallets/duniter-test-parameters/src/lib.rs index 39775e7c4..346a88230 100644 --- a/pallets/duniter-test-parameters/src/lib.rs +++ b/pallets/duniter-test-parameters/src/lib.rs @@ -14,6 +14,10 @@ // 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/>. +//! # Duniter Test Parameters Pallet +//! +//! This pallet allows ĞDev runtime to tweak parameter values instead of having it as runtime constants. + #![cfg_attr(not(feature = "std"), no_std)] pub use pallet::*; diff --git a/pallets/duniter-wot/README.md b/pallets/duniter-wot/README.md deleted file mode 100644 index 4ac1baf7b..000000000 --- a/pallets/duniter-wot/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# Duniter Web of Trust pallet - -Duniter WoT is at the core of its identity system and is a big improvement compared to PGP WoT. It is a dynamic directed graph whose nodes are [identities](../identity/) and edges [certifications](../certification/). - -There are two instances: - -- the main WoT, for every human -- the smith sub-WoT, for authorities - -It has both static and dynamic rules, controlling the condition to join and remain [member](../membership/). - -- static rules - - minimum number of received certifications (min indegree) - - maximum number of emited certifications (max outdegree) - - distance criterion (see distance pallet) -- dynamic rules - - time interval between two certifications - - certification duration (see certification pallet) - - membership renewal (see membership pallet) - -This pallet's main role is to check the Web of Trust rules. \ No newline at end of file diff --git a/pallets/duniter-wot/src/lib.rs b/pallets/duniter-wot/src/lib.rs index 0abf864d5..af148aa57 100644 --- a/pallets/duniter-wot/src/lib.rs +++ b/pallets/duniter-wot/src/lib.rs @@ -14,6 +14,35 @@ // 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/>. +//! # Duniter Web of Trust Pallet +//! +//! Duniter Web of Trust (WoT) lies at the heart of its identity system, representing a significant improvement over PGP Web of Trust. It functions as a dynamic directed graph where nodes are [identities](../identity/) and edges are [certifications](../certification/). +//! +//! ## Instances +//! +//! Duniter WoT consists of two distinct instances: +//! +//! - **Main WoT**: Designed for every human participant in the Duniter network. +//! - **Smith Sub-WoT**: Intended for authorities. +//! +//! ## Rules +//! +//! The Duniter WoT operates under a set of static and dynamic rules that govern membership conditions. +//! +//! ### Static Rules +//! +//! - **Minimum Received Certifications (Min Indegree)**: Specifies the minimum number of certifications an identity must receive to join the WoT. +//! - **Maximum Emitted Certifications (Max Outdegree)**: Limits the maximum number of certifications an identity can issue. +//! - **Distance Criterion**: Governed by the distance pallet, it defines the permissible distance between identities within the WoT graph. +//! +//! ### Dynamic Rules +//! +//! - **Time Interval Between Certifications**: Sets the minimum time interval required between two consecutive certifications issued by the same identity. +//! - **Certification Duration**: Managed by the certification pallet, it determines the validity duration of a certification. +//! - **Membership Renewal**: Regulates the frequency and conditions under which an identity must renew its membership within the WoT. +//! +//! This pallet is responsible for enforcing and validating the rules of the Duniter Web of Trust. It ensures compliance with both static prerequisites for joining and dynamic conditions for ongoing participation. + #![cfg_attr(not(feature = "std"), no_std)] #![allow(clippy::type_complexity)] @@ -25,9 +54,6 @@ mod tests; pub mod traits; -/*#[cfg(feature = "runtime-benchmarks")] -mod benchmarking;*/ - pub use pallet::*; use frame_support::pallet_prelude::*; diff --git a/pallets/identity/README.md b/pallets/identity/README.md deleted file mode 100644 index e8da9f126..000000000 --- a/pallets/identity/README.md +++ /dev/null @@ -1,45 +0,0 @@ -# Duniter identity pallet - -Duniter has a builtin identity system that does not work with external registrar compared to [parity identity pallet](https://github.com/paritytech/substrate/tree/master/frame/identity). - -## Duniter identity - -A Duniter identity contains: - -- its **owner key** (that can change) -- an optional **old owner key** with the date of the key change -- a **status** that can be - - unconfirmed (created by a member identity) - - unvalidated (confirmed by owner = given a name) - - member (of the main wot) - - notmember (of the main wot) - - revoked (automatically of manually) - -It also contains: - -- the block number at which it can emit its **next certification** (TODO distinguish next certification and next identity creation) -- the block number at which it can be **removed from storage** - -It also contains attached data defined by the runtime that can be for example - -- the number of the first UD it is eligible to - -### Name - -Each identity is declared with a name emited on confirmation event. Duniter keeps a list of identity names hash to ensure unicity. - -### Owner key - -The idea of the owner key is to allow the user to keep a fixed identity while changing the keys for security reasons. For example when a device with the keys might have been compromised. There is a limit to the frequency of owner key change and the old owner key can still revoke the identity for a given period. - -### Status / removable date - -The status is a temporary value allowing to prune identities before they become member. When an identity is not valiated (not member of the WoT for instance), it can be removed when the date is reached. The remove date of a validated identity is block zero. - -### Next certification - -The next certification is a rate limit to the emission of certification (and then identity creation). - -### Revokation - -Revoking an identity basically means deleting it. diff --git a/pallets/identity/src/lib.rs b/pallets/identity/src/lib.rs index f41a81e46..448df7895 100644 --- a/pallets/identity/src/lib.rs +++ b/pallets/identity/src/lib.rs @@ -14,6 +14,43 @@ // 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/>. +//! # Duniter Identity Pallet +//! +//! Duniter features a built-in identity system that does not rely on external registrars, unlike the [Parity Identity Pallet](https://github.com/paritytech/substrate/tree/master/frame/identity). +//! +//! ## Duniter Identity Structure +//! +//! A Duniter identity comprises several key components: +//! +//! ### Name +//! +//! Each identity is declared with a name emitted during the confirmation event. Duniter maintains a hashed list of identity names to ensure uniqueness. +//! +//! ### Owner Key +//! +//! The owner key allows users to maintain a fixed identity while changing keys for security reasons, such as when a device with the keys might have been compromised. Changes are subject to frequency limits, and the old owner key can still revoke the identity for a given period. +//! +//! ### Status / Removable Date +//! +//! The status is a temporary value that allows pruning of identities before they become full members: +//! - **Unconfirmed**: Created by a member identity but not yet confirmed by the owner. +//! - **Unvalidated**: Confirmed by the owner, including assignment of a name. +//! - **Member**: Part of the main Web of Trust (WoT). +//! - **NotMember**: Not part of the main WoT. +//! - **Revoked**: Automatically or manually revoked. +//! +//! An identity that is not yet validated (e.g., not a member of the WoT) can be removed when its removable date is reached. The removable date of a validated identity is set to block zero. +//! +//! ### Next Certification +//! +//! The next certification specifies the block number from which the identity can issue its next certification, acting as a rate limit for certification issuance and identity creation. +//! +//! ### Revocation +//! +//! Revoking an identity essentially means deleting it from the system. +//! +//! Additional runtime-defined data may also be attached to identities, such the number of the first Universal Dividends (UD) it is eligible to. + #![cfg_attr(not(feature = "std"), no_std)] #![allow(clippy::type_complexity)] diff --git a/pallets/membership/README.md b/pallets/membership/README.md deleted file mode 100644 index c6dc0da83..000000000 --- a/pallets/membership/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# 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. - -## Main Web of Trust - -Membership pallet manages all events related to web of trust membership of an identity. It exposes no calls to the user and its features are only available trough distance evaluation provided by distance oracle. diff --git a/pallets/membership/src/lib.rs b/pallets/membership/src/lib.rs index 714d4bb09..8fbe2a414 100644 --- a/pallets/membership/src/lib.rs +++ b/pallets/membership/src/lib.rs @@ -14,6 +14,14 @@ // 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/>. +//! # Duniter Membership Pallet +//! +//! The Duniter Membership Pallet is closely integrated with the Duniter Web of Trust (WoT) and is tailored specifically for Duniter, in contrast to the [Parity Membership Pallet](https://github.com/paritytech/substrate/tree/master/frame/membership). It operates exclusively within the Duniter ecosystem and is utilized internally by the Identity, Web of Trust, and Distance Pallets. +//! +//! ## Main Web of Trust (WoT) +//! +//! The Membership Pallet manages all aspects related to the membership of identities within the Duniter Web of Trust. Unlike traditional membership systems, it does not expose any external calls to users. Instead, its functionalities are accessible through distance evaluations provided by the Distance Oracle. + #![cfg_attr(not(feature = "std"), no_std)] #![allow(clippy::type_complexity)] diff --git a/pallets/offences/README.md b/pallets/offences/README.md deleted file mode 100644 index 62fa734c3..000000000 --- a/pallets/offences/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Duniter offences pallet - -This is a fork of the Substrate `offences` pallet that is modified to agree with the offence rules based on the `authority-member` pallet and not in the Substrate `staking` pallet. - -Duniter provides a basic way to process offences: -* On offences from `im-online` pallet, the offender disconnection is required. -* On other offences, the offender disconnection is required and the offender is required to be blacklisted and only an authorized origin can remove the offender from the blacklist. - -The offences triage is realized in the `offences` pallet and the slashing execution is done in the `authority-member` pallet. \ No newline at end of file diff --git a/pallets/offences/src/lib.rs b/pallets/offences/src/lib.rs index f6b30289d..100203b82 100644 --- a/pallets/offences/src/lib.rs +++ b/pallets/offences/src/lib.rs @@ -14,6 +14,25 @@ // 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/>. +//! # Duniter Offences Pallet +//! +//! This pallet is a fork of the Substrate `offences` pallet, customized to align with the offence rules specified by the `authority-member` pallet rather than the Substrate `staking` pallet. +//! +//! ## Offences Processing +//! +//! The Duniter Offences Pallet manages various types of offences as follows: +//! +//! - **`im-online` Pallet Offences**: Offences from the `im-online` pallet necessitate disconnection of the offender. +//! +//! - **Other Offences**: For all other offences, the pallet enforces: +//! - Disconnection of the offender. +//! - Addition of the offender to a blacklist. +//! - Authorization from a designated origin to remove offenders from the blacklist. +//! +//! ## Offences Triage and Slashing Execution +//! +//! This pallet handles the triage of offences, categorizing them based on predefined rules. The actual execution of slashing and other punitive measures is delegated to the `authority-member` pallet. + #![cfg_attr(not(feature = "std"), no_std)] #[cfg(test)] diff --git a/pallets/oneshot-account/README.md b/pallets/oneshot-account/README.md deleted file mode 100644 index 7d3f030ea..000000000 --- a/pallets/oneshot-account/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Duniter oneshot account pallet - -Duniter provides light accounts without `AccountInfo` (nonce, consumers, providers, sufficients, free, reserved, misc_frozen, fee_frozen) that can only be consumed once. This should reduce transaction weight and then fees. The use case is anonymous accounts or physical supports. \ No newline at end of file diff --git a/pallets/oneshot-account/src/lib.rs b/pallets/oneshot-account/src/lib.rs index f1bff130b..53128793f 100644 --- a/pallets/oneshot-account/src/lib.rs +++ b/pallets/oneshot-account/src/lib.rs @@ -14,6 +14,10 @@ // 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/>. +//! # Duniter Oneshot Account Pallet +//! +//! Duniter Oneshot Account Pallet introduces lightweight accounts that do not utilize `AccountInfo`, including fields like nonce, consumers, providers, sufficients, free, reserved. These accounts are designed for single-use scenarios, aiming to reduce transaction weight and associated fees. The primary use cases include anonymous transactions and physical support scenarios where lightweight and disposable accounts are beneficial. + #![cfg_attr(not(feature = "std"), no_std)] mod benchmarking; diff --git a/pallets/provide-randomness/README.md b/pallets/provide-randomness/README.md deleted file mode 100644 index 12138fbd6..000000000 --- a/pallets/provide-randomness/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Duniter provide randomness pallet - -TODO \ No newline at end of file diff --git a/pallets/provide-randomness/src/lib.rs b/pallets/provide-randomness/src/lib.rs index 159be9f87..25e5b6d1c 100644 --- a/pallets/provide-randomness/src/lib.rs +++ b/pallets/provide-randomness/src/lib.rs @@ -14,6 +14,12 @@ // 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/>. +//! # Provides Randomness Pallet +//! +//! The Provides Randomness Pallet facilitates the generation of randomness within the Duniter blockchain. +//! +//! This pallet manages randomness requests and emits events upon requesting and fulfilling randomness. + #![cfg_attr(not(feature = "std"), no_std)] #![allow(clippy::boxed_local)] diff --git a/pallets/quota/README.md b/pallets/quota/README.md deleted file mode 100644 index 485460de5..000000000 --- a/pallets/quota/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# Duniter quota pallet - -Duniter identity system allows to allocate quota and refund transaction fees when not consumed. - -## General behavior - -Quota system is plugged to transactions fees which is a rather critical aspect of substrate. -That's why in `duniter-account` pallet `OnChargeTransaction` implementation, the default behavior is preserved, and refunds are added to a queue handled in `on_idle`. - -## Path for a refund - -This is what happens on a transaction: - -- `frame-executive` calls `OnChargeTransaction` implementations -- `duniter-account` `OnChargeTransaction` implementation is called, and if an identity is linked to the account who pays the fees, `request_refund` is called -- `request_refund` implementation of `quota` pallet determines whether the fees are eligible for refund based on the identity and then call `queue_refund` -- `queue_refund` adds a refund to the `RefundQueue` which will be processed in `on_idle` -- during `on_idle`, `quota` pallet processes the refund queue within the supplied weight limit with `process_refund_queue` -- for each refund in the `RefundQueue`, `try_refund` is called -- it first tries to use quotas to refund fees with `spend_quota` -- if a certain amount of quotas has been spend, it actually performs the refund with `do_refund`, taking currency from the `RefundAccount` to give it back to the account who paid the fee - -The conditions for a refund to happen are: - -1. an identity is linked to the account who pays the fees -1. some quotas are defined for the identity and have a non-null value after update - - -## TODO - -- [ ] sanity test checking that only member identities have quota \ No newline at end of file diff --git a/pallets/quota/src/lib.rs b/pallets/quota/src/lib.rs index 79772ba8c..f35aed5d8 100644 --- a/pallets/quota/src/lib.rs +++ b/pallets/quota/src/lib.rs @@ -14,6 +14,27 @@ // 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/>. +//! # Duniter Quota Pallet +//! +//! ## Overview +//! +//! This pallet is designed to manage transaction fee refunds based on quotas allocated to identities within the Duniter identity system. Quotas are linked to transaction fees, ensuring efficient handling of fee refunds when transactions occur. +//! +//! ## Refund Mechanism +//! +//! When a transaction is processed: +//! - The `OnChargeTransaction` implementation in the `frame-executive` pallet is called. +//! - The `OnChargeTransaction` implementation in the `duniter-account` pallet checks if the paying account is linked to an identity. +//! - If linked, the `request_refund` function in the `quota` pallet evaluates the eligibility for fee refund based on the identity's quota. +//! - Eligible refunds are added to the `RefundQueue`, managed by `process_refund_queue` during the `on_idle` phase. +//! - Refunds are processed with `try_refund`, using quotas to refund fees via `spend_quota`, and then executing the refund through `do_refund` by transferring currency from the `RefundAccount` back to the paying account. +//! +//! ## Conditions for Refund +//! +//! Refunds are executed under the following conditions: +//! 1. The paying account is linked to an identity. +//! 2. Quotas are allocated to the identity and have a non-zero value after updates. + #![cfg_attr(not(feature = "std"), no_std)] pub mod traits; diff --git a/pallets/session-benchmarking/README.md b/pallets/session-benchmarking/README.md deleted file mode 100644 index 8d0946772..000000000 --- a/pallets/session-benchmarking/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# Duniter session-benchmarking pallet - -Benchmark crate for the `pallet-session` that is decoupled from the `staking-pallet` not used in Duniter. -In Duniter, the `SessionManager `and `SessionHandler` hooks are implemented in the `authority-members` pallet. \ No newline at end of file diff --git a/pallets/session-benchmarking/src/lib.rs b/pallets/session-benchmarking/src/lib.rs index dd22408a1..d38e9d933 100644 --- a/pallets/session-benchmarking/src/lib.rs +++ b/pallets/session-benchmarking/src/lib.rs @@ -14,8 +14,13 @@ // 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/>. -//! Benchmarks for the Session Pallet. -// This is separated into its own crate due to cyclic dependency issues. +//! # Duniter Session Benchmarking Pallet +//! +//! This crate provides benchmarks specifically for the `pallet-session` within Duniter. Unlike traditional setups, this implementation is decoupled from the `staking-pallet`, which is not utilized in Duniter's architecture. Instead, session management functionalities are integrated into the `authority-members` pallet. +//! +//! ## Note +//! +//! This crate is separated from the main codebase due to cyclic dependency issues, focusing solely on session-related benchmarking independent of staking-related functionalities. #![cfg_attr(not(feature = "std"), no_std)] #![cfg(feature = "runtime-benchmarks")] diff --git a/pallets/smith-members/README.md b/pallets/smith-members/README.md deleted file mode 100644 index 655534a2a..000000000 --- a/pallets/smith-members/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Duniter smith pallet - -The bridge between `identity` and `authority-members` pallet. \ No newline at end of file diff --git a/pallets/smith-members/src/lib.rs b/pallets/smith-members/src/lib.rs index 883ed202d..924b69a85 100644 --- a/pallets/smith-members/src/lib.rs +++ b/pallets/smith-members/src/lib.rs @@ -14,6 +14,29 @@ // 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/>. +//! # Duniter Smith Pallet +//! +//! The Smith pallet in Duniter serves as a bridge between the `identity` and `authority-members` pallets. +//! +//! ## Overview +//! +//! The Smith pallet manages the certification and membership status of Smiths. Smiths are identities that have met certain requirements and play a critical role in the network's operations (block authoring, distance evaluation). +//! +//! ## Key Concepts +//! +//! ### Smith Status +//! +//! The status of an identity within the Smith pallet can be one of the following: +//! - **Invited**: The identity has been invited by a Smith but has not yet accepted the invitation. +//! - **Pending**: The identity has accepted the invitation and is pending to become a full Smith. +//! - **Smith**: The identity has fulfilled the requirements and is a full-fledged Smith, eligible to perform critical network functions. +//! - **Excluded**: The identity has been removed from the Smiths set but its certifications are retained for tracking purposes. +//! +//! ### Certifications +//! +//! Certifications are crucial in determining Smith status: +//! - An identity needs a minimum number of certifications to become a Smith (`MinCertForMembership`). + #![cfg_attr(not(feature = "std"), no_std)] #[cfg(test)] diff --git a/pallets/universal-dividend/README.md b/pallets/universal-dividend/README.md deleted file mode 100644 index b7e862551..000000000 --- a/pallets/universal-dividend/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Duniter universal dividend pallet - -One of the main features of Duniter is the Universal Dividend based on the Relative Theory of Money. It is both a daily monetary creation and a measure unit. - -This pallet provides functions to create UDs and transfer an amount of currency counted in UD. It should be noted that the UD is not actually created every day on every account which would be very resource consuming but must be claimed by the member in a given extrinsic. \ No newline at end of file diff --git a/pallets/universal-dividend/src/lib.rs b/pallets/universal-dividend/src/lib.rs index 4609384d4..31fdbad5c 100644 --- a/pallets/universal-dividend/src/lib.rs +++ b/pallets/universal-dividend/src/lib.rs @@ -14,6 +14,18 @@ // 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/>. +//! # Duniter Universal Dividend Pallet +//! +//! One of Duniter's core features is the Universal Dividend (UD), which operates based on the Relative Theory of Money. The UD serves both as a daily monetary creation mechanism and a unit of measure within the Duniter ecosystem. +//! +//! ## Overview +//! +//! This pallet enables: +//! - Creation of Universal Dividends (UD) as a daily monetary issuance and measure unit. +//! - Transfer of currency denominated in UD between accounts. +//! +//! **Note**: The UD is not automatically created daily for every account due to resource constraints. Instead, members must claim their UD using a specific extrinsic. + #![cfg_attr(not(feature = "std"), no_std)] mod benchmarking; diff --git a/pallets/upgrade-origin/README.md b/pallets/upgrade-origin/README.md deleted file mode 100644 index 204c2a034..000000000 --- a/pallets/upgrade-origin/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Duniter upgrade origin pallet - -TODO \ No newline at end of file -- GitLab