incode pallet description

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>

docs/api/runtime-errors.md

 # 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

pallets/authority-members/README.md

-# 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

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::*;

pallets/certification/README.md

-# 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

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")]

pallets/distance/README.md

-# 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

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;

pallets/duniter-account/README.md

-# 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

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)]
 

pallets/duniter-test-parameters/README.md

-# Duniter test parameters
-
-This pallet allows ĞDev runtime to tweak parameter values instead of having it runtime constants.
\ No newline at end of file

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::*;

pallets/duniter-wot/README.md

-# 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

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::*;

pallets/identity/README.md

-# 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.

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)]
 

pallets/membership/README.md

-# 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.

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)]
 

pallets/offences/README.md

-# 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

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)]