diff --git a/docs/api/runtime-calls.md b/docs/api/runtime-calls.md index 68c737183f1d8f5bcd74be7f2bf5c27925823891..320e6a1857da79456b7ef85bff57dca9c6b1a5cf 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 667342478644643900f109e811a5308e55ecc1e3..48bc9f68cd283b12f69b94f32606a3cff83a6d2f 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 3edf76eba9a5e7702065681758bd89966a0747f5..0000000000000000000000000000000000000000 --- 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 052d4130a4fcb68ef538d69bea94b278af3fbff9..0b06e1acfa36bb7aa42c1a2257013cdcdb03e36f 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 a84e9f9eadc0250a756b32d0bfb1cf3e24c198bb..0000000000000000000000000000000000000000 --- 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 01df9634942b863530bfe7f9fe57ee7e85e610a9..d1c3ffd014bb4f4c1cbe87206816862587dee137 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 d34bdb64604a138c1c2717b67db4e7cbba6999bc..0000000000000000000000000000000000000000 --- 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 b52e2bb084db727aa30568f5a4d90aaacc2e6006..dd6bbfe8321243772db8ada0861cfa8109c292ba 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 185e37ce5496a348698d413f9166637a41a22692..0000000000000000000000000000000000000000 --- 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 76209d0427d0cb2bcb5ede65795a0796d594ba5e..b60d1c8bb49f96b31e9a3875c29eec534bf7880d 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 80a352ff46980635c72de80029cedc324ea6da30..0000000000000000000000000000000000000000 --- 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 39775e7c42ecbefd0f8e6569dbdc3efff91ab8e9..346a8823035c4707e5f209f865bcdd05122f08f7 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 4ac1baf7bc13165d1eb323ea5ef82018492e08a3..0000000000000000000000000000000000000000 --- 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 0abf864d596aca0f4e9b26a882f3e96d6e085c53..af148aa5793c1d895bd3d3bfd754084b04cca582 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 e8da9f126f9ff87610106d9323a479af506881e1..0000000000000000000000000000000000000000 --- 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 f41a81e4693c8ebaf5cb915dda00e52b649cabd4..448df78957998081403a09e30b03f2944f4ac4d1 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 c6dc0da834a30d0766609fc20773da17e1fd3136..0000000000000000000000000000000000000000 --- 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 714d4bb09d4b85510568cc7c199ae8c0652d7d97..8fbe2a414f6d2669aef5aade2a24982ba193df3f 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 62fa734c335500b442f440ab9100beed1ebeab68..0000000000000000000000000000000000000000 --- 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 f6b30289d9ad283633cb4636a9df800abe748649..100203b822fc4cc3568c964e225535f718f37739 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 7d3f030eabb1384ae07203d6577dae0bde54b5fa..0000000000000000000000000000000000000000 --- 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 f1bff130b57d855fac2564fde450cf601bb6d416..53128793f3431a053330f7f0125d8bf2d66a65ef 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 12138fbd60ba21715edbbb1cd42ad7c477d8bbf4..0000000000000000000000000000000000000000 --- 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 159be9f870da11d576e13598a0d3d062afafa674..25e5b6d1cb929968f5c63211b36380e52702a267 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 485460de592face6a99597fef19eb952df5936d4..0000000000000000000000000000000000000000 --- 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 79772ba8c58087cafa33e00c83086fa1386bbc94..f35aed5d82d8e0a3ac8938ca280291e43998c2c2 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 8d0946772e12c530b15d43fe41738bffe1301c06..0000000000000000000000000000000000000000 --- 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 dd22408a1a7e1918bd8da529f2bd296bdd0ba916..d38e9d933d1b5b3aa6255d02eb16ae0c55fa541c 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 655534a2a74d357c3d0f856dd3e4de6493eddd44..0000000000000000000000000000000000000000 --- 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 883ed202de2797dea5737498640c1c695a598ceb..924b69a8512a987ba3b5c0ee25663d4e6819fa82 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 b7e862551d60c73dd215e25d31647c2357dfc4e0..0000000000000000000000000000000000000000 --- 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 4609384d45c083b74d8f89b2cdf8066b3fe05419..31fdbad5ce7d4db3fe0b8addf7d34af5faf99121 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 204c2a034feefc807118bd55572fc21b5c5be25c..0000000000000000000000000000000000000000 --- a/pallets/upgrade-origin/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Duniter upgrade origin pallet - -TODO \ No newline at end of file