Markdown linter (#1309)

* Add markdown linting - add linter default rules - adapt rules to current code - fix the code for linting to pass - add CI check fix #1243 * Fix markdown for Substrate * Fix tooling install * Fix workflow * Add documentation * Remove trailing spaces * Update .github/.markdownlint.yaml Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> * Fix mangled markdown/lists * Fix captalization issues on known words
2026-06-12 22:51:13 +00:00 · 2023-09-04 11:02:32 +02:00
parent 830fde2a60
commit a30092ab42
271 changed files with 6289 additions and 4450 deletions
@@ -14,4 +14,4 @@ api, the [`ApiExt`] trait, the [`CallApiAt`] trait and the [`ConstructRuntimeApi

 On a meta level this implies, the client calls the generated API from the client perspective.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Traits and macros for constructing application specific strongly typed crypto wrappers.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Minimal fixed point arithmetic primitives and types for runtime.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Runtime Api to help discover authorities.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 The block builder runtime api.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Substrate blockchain traits and primitives.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Primitives for Aura.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Primitives for BABE.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,7 +1,7 @@
-Common utilities for building and using consensus engines in substrate.
+Common utilities for building and using consensus engines in Substrate.

 Much of this crate is _unstable_ and thus the API is likely to undergo
 change. Implementors of traits should not rely on the interfaces to remain
 the same.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Primitives for GRANDPA integration, suitable for WASM compilation.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Primitives for Substrate Proof-of-Work (PoW) consensus.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Primitives for slots-based consensus engines.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 The main database trait, allowing Substrate to store data persistently.

-License: Apache-2.0
+License: Apache-2.0
@@ -6,4 +6,4 @@ access the node from the runtime via the runtime interfaces.

 This crate exposes the main [`Externalities`] trait.

-License: Apache-2.0
+License: Apache-2.0
@@ -14,4 +14,4 @@ A module can also just check given inherents. For using a module as inherent pro
 to be registered by the `construct_runtime!` macro. The macro documentation gives more
 information on how that is done.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
-I/O host interface for substrate runtime.
+I/O host interface for Substrate runtime.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Support code for the runtime. A set of test accounts.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,30 +1,29 @@
-A set of election algorithms to be used with a substrate runtime, typically within the staking
-sub-system. Notable implementation include:
+# sp-npos-elections

- [`seq_phragmen`]: Implements the Phragmén Sequential Method. An un-ranked, relatively fast
-  election method that ensures PJR, but does not provide a constant factor approximation of the
-  maximin problem.
- [`phragmms`]: Implements a hybrid approach inspired by Phragmén which is executed faster but
-  it can achieve a constant factor approximation of the maximin problem, similar to that of the
-  MMS algorithm.
- [`balance_solution`]: Implements the star balancing algorithm. This iterative process can push
-  a solution toward being more `balanced`, which in turn can increase its score.
+A set of election algorithms to be used with a Substrate runtime, typically within the staking sub-system. Notable
+implementation include:

-### Terminology
+- [`seq_phragmen`]: Implements the Phragmén Sequential Method. An un-ranked, relatively fast election method that
+  ensures PJR, but does not provide a constant factor approximation of the maximin problem.
+- [`phragmms`]: Implements a hybrid approach inspired by Phragmén which is executed faster but it can achieve a constant
+  factor approximation of the maximin problem, similar to that of the MMS algorithm.
+- [`balance_solution`]: Implements the star balancing algorithm. This iterative process can push a solution toward being
+  more `balanced`, which in turn can increase its score.

-This crate uses context-independent words, not to be confused with staking. This is because the
-election algorithms of this crate, while designed for staking, can be used in other contexts as
-well.
+## Terminology

-`Voter`: The entity casting some votes to a number of `Targets`. This is the same as `Nominator`
-in the context of staking. `Target`: The entities eligible to be voted upon. This is the same as
-`Validator` in the context of staking. `Edge`: A mapping from a `Voter` to a `Target`.
+This crate uses context-independent words, not to be confused with staking. This is because the election algorithms of
+this crate, while designed for staking, can be used in other contexts as well.
+
+`Voter`: The entity casting some votes to a number of `Targets`. This is the same as `Nominator` in the context of
+staking. `Target`: The entities eligible to be voted upon. This is the same as `Validator` in the context of staking.
+`Edge`: A mapping from a `Voter` to a `Target`.

 The goal of an election algorithm is to provide an `ElectionResult`. A data composed of:
- `winners`: A flat list of identifiers belonging to those who have won the election, usually
-  ordered in some meaningful way. They are zipped with their total backing stake.
- `assignment`: A mapping from each voter to their winner-only targets, zipped with a ration
-  denoting the amount of support given to that particular target.
+- `winners`: A flat list of identifiers belonging to those who have won the election, usually ordered in some meaningful
+  way. They are zipped with their total backing stake.
+- `assignment`: A mapping from each voter to their winner-only targets, zipped with a ration denoting the amount of
+  support given to that particular target.

 ```rust
 // the winners.
@@ -44,16 +43,14 @@ let election_result = ElectionResult { winners, assignments };

 ```

-The `Assignment` field of the election result is voter-major, i.e. it is from the perspective of
-the voter. The struct that represents the opposite is called a `Support`. This struct is usually
-accessed in a map-like manner, i.e. keyed by voters, therefore it is stored as a mapping called
-`SupportMap`.
+The `Assignment` field of the election result is voter-major, i.e. it is from the perspective of the voter. The struct
+that represents the opposite is called a `Support`. This struct is usually accessed in a map-like manner, i.e. keyed by
+voters, therefore it is stored as a mapping called `SupportMap`.

-Moreover, the support is built from absolute backing values, not ratios like the example above.
-A struct similar to `Assignment` that has stake value instead of ratios is called an
-`StakedAssignment`.
+Moreover, the support is built from absolute backing values, not ratios like the example above. A struct similar to
+`Assignment` that has stake value instead of ratios is called an `StakedAssignment`.


 More information can be found at: https://arxiv.org/abs/2004.12990

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 The Offchain Worker runtime api primitives.

-License: Apache-2.0
+License: Apache-2.0
@@ -7,4 +7,4 @@ given URL.
 By default, the panic handler aborts the process by calling [`std::process::exit`]. This can
 temporarily be disabled by using an [`AbortGuard`].

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Substrate RPC primitives and utilities.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,43 +1,42 @@
 Substrate runtime interface

-This crate provides types, traits and macros around runtime interfaces. A runtime interface is
-a fixed interface between a Substrate runtime and a Substrate node. For a native runtime the
-interface maps to a direct function call of the implementation. For a wasm runtime the interface
-maps to an external function call. These external functions are exported by the wasm executor
-and they map to the same implementation as the native calls.
+This crate provides types, traits and macros around runtime interfaces. A runtime interface is a fixed interface between
+a Substrate runtime and a Substrate node. For a native runtime the interface maps to a direct function call of the
+implementation. For a wasm runtime the interface maps to an external function call. These external functions are
+exported by the wasm executor and they map to the same implementation as the native calls.

 # Using a type in a runtime interface
 <!-- markdown-link-check-disable -->
-Any type that should be used in a runtime interface as argument or return value needs to
-implement [`RIType`]. The associated type [`FFIType`](https:/docs.rs/sp-runtime-interface/latest/sp_runtime_interface/trait.RIType.html#associatedtype.FFIType)
-is the type that is used in the FFI function to represent the actual type. For example `[T]` is
-represented by an `u64`. The slice pointer and the length will be mapped to an `u64` value.
-For more information see this [table](https:/docs.rs/sp-runtime-interface/latest/sp_runtime_interface/#ffi-type-and-conversion).
-The FFI function definition is used when calling from the wasm runtime into the node.
+Any type that should be used in a runtime interface as argument or return value needs to implement [`RIType`]. The
+associated type
+[`FFIType`](https:/docs.rs/sp-runtime-interface/latest/sp_runtime_interface/trait.RIType.html#associatedtype.FFIType) is
+the type that is used in the FFI function to represent the actual type. For example `[T]` is represented by an `u64`.
+The slice pointer and the length will be mapped to an `u64` value. For more information see this
+[table](https:/docs.rs/sp-runtime-interface/latest/sp_runtime_interface/#ffi-type-and-conversion). The FFI function
+definition is used when calling from the wasm runtime into the node.

 Traits are used to convert from a type to the corresponding
 [`RIType::FFIType`](https:/docs.rs/sp-runtime-interface/latest/sp_runtime_interface/trait.RIType.html#associatedtype.FFIType).
-Depending on where and how a type should be used in a function signature, a combination of the
-following traits need to be implemented:
+Depending on where and how a type should be used in a function signature, a combination of the following traits need to
+be implemented:
 <!-- markdown-link-check-enable -->
 1. Pass as function argument: [`wasm::IntoFFIValue`] and [`host::FromFFIValue`]
 2. As function return value: [`wasm::FromFFIValue`] and [`host::IntoFFIValue`]
 3. Pass as mutable function argument: [`host::IntoPreallocatedFFIValue`]

-The traits are implemented for most of the common types like `[T]`, `Vec<T>`, arrays and
-primitive types.
+The traits are implemented for most of the common types like `[T]`, `Vec<T>`, arrays and primitive types.

-For custom types, we provide the [`PassBy`](https://docs.rs/sp-runtime-interface/latest/sp_runtime_interface/pass_by#PassBy) trait and strategies that define
-how a type is passed between the wasm runtime and the node. Each strategy also provides a derive
-macro to simplify the implementation.
+For custom types, we provide the
+[`PassBy`](https://docs.rs/sp-runtime-interface/latest/sp_runtime_interface/pass_by#PassBy) trait and strategies that
+define how a type is passed between the wasm runtime and the node. Each strategy also provides a derive macro to
+simplify the implementation.

 # Performance

-To not waste any more performance when calling into the node, not all types are SCALE encoded
-when being passed as arguments between the wasm runtime and the node. For most types that
-are raw bytes like `Vec<u8>`, `[u8]` or `[u8; N]` we pass them directly, without SCALE encoding
-them in front of. The implementation of [`RIType`] each type provides more information on how
-the data is passed.
+To not waste any more performance when calling into the node, not all types are SCALE encoded when being passed as
+arguments between the wasm runtime and the node. For most types that are raw bytes like `Vec<u8>`, `[u8]` or `[u8; N]`
+we pass them directly, without SCALE encoding them in front of. The implementation of [`RIType`] each type provides more
+information on how the data is passed.

 # Declaring a runtime interface

@@ -57,9 +56,10 @@ For more information on declaring a runtime interface, see

 # FFI type and conversion

-The following table documents how values of types are passed between the wasm and
-the host side and how they are converted into the corresponding type.
+The following table documents how values of types are passed between the wasm and the host side and how they are
+converted into the corresponding type.

+<!-- markdownlint-disable MD013 -->
 | Type | FFI type | Conversion |
 |----|----|----|
 | `u8` | `u8` | `Identity` |
@@ -1,3 +1,3 @@
 Runtime Modules shared primitive types.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Substrate core types around sessions.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,4 +1,4 @@
 A crate which contains primitives that are useful for implementation that uses staking
 approaches in general. Definitions related to sessions, slashing, etc go here.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Substrate state machine implementation.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,18 +1,35 @@
+# Statement store
+
 Statement store is an off-chain data-store for signed statements accessible via RPC and OCW.

-Nodes hold a number of statements with a proof of authenticity owing to an account ID. OCWs can place items in the data-store (with valid signatures) for any accounts whose keys they control. Users can also submit pre-signed statements via RPC. Statements can also be submitted from on-chain logic through an on-chain event.
+Nodes hold a number of statements with a proof of authenticity owing to an account ID. OCWs can place items in the
+data-store (with valid signatures) for any accounts whose keys they control. Users can also submit pre-signed statements
+via RPC. Statements can also be submitted from on-chain logic through an on-chain event.

-A new system event `NewStatement` is added to the runtime. This event allows any account on-chain to declare that they want to make a statement for the store. Within the node store and for broadcasting, the statement would be accompanied with the hash of the block and index of the event within it, essentially taking the place of a real signature.
+A new system event `NewStatement` is added to the runtime. This event allows any account on-chain to declare that they
+want to make a statement for the store. Within the node store and for broadcasting, the statement would be accompanied
+with the hash of the block and index of the event within it, essentially taking the place of a real signature.

-Statements comprise an optional proof of authenticity (e.g. a signature) and a number of fields. For statements without a proof, nodes would gossip statements randomly with a rate-limiter to minimise the chance of being overrun by a misbehaving node. These will generally be disregarded by nodes unless they are gossiped by several different peers or if a peer pays for it somehow (e.g. gossiping something valuable).
+Statements comprise an optional proof of authenticity (e.g. a signature) and a number of fields. For statements without
+a proof, nodes would gossip statements randomly with a rate-limiter to minimise the chance of being overrun by a
+misbehaving node. These will generally be disregarded by nodes unless they are gossiped by several different peers or if
+a peer pays for it somehow (e.g. gossiping something valuable).

-Each field is effectively a key/value pair. Fields must be sorted and the same field type may not be repeated. Depending on which keys are present, clients may index the message for ease of retrieval.
+Each field is effectively a key/value pair. Fields must be sorted and the same field type may not be repeated. Depending
+on which keys are present, clients may index the message for ease of retrieval.

 Formally, `Statement` is equivalent to the type `Vec<Field>` and `Field` is the SCALE-encoded enumeration:
- 0: `AuthenticityProof(Proof)`: The signature of the message. For cryptography where the public key cannot be derived from the signature together with the message data, then this will also include the signer's public key. The message data is all fields of the messages fields except the signature concatenated together *without the length prefix that a `Vec` would usually imply*. This is so that the signature can be derived without needing to re-encode the statement.
- 1: `DecryptionKey([u8; 32])`: The decryption key identifier which should be used to decrypt the statement's data. In the absence of this field `Data` should be treated as not encrypted.
- 2: `Priority(u32)`: Priority specifier. Higher priority statements should be kept around at the cost of lower priority statements if multiple statements from the same sender are competing for persistence or transport. Nodes should disregard when considering unsigned statements.
- 3: `Channel([u8; 32])`: The channel identifier. Only one message of a given channel should be retained at once (the one of highest priority). Nodes should disregard when considering unsigned statements.
+- 0: `AuthenticityProof(Proof)`: The signature of the message. For cryptography where the public key cannot be derived
+  from the signature together with the message data, then this will also include the signer's public key. The message
+  data is all fields of the messages fields except the signature concatenated together *without the length prefix that a
+  `Vec` would usually imply*. This is so that the signature can be derived without needing to re-encode the statement.
+- 1: `DecryptionKey([u8; 32])`: The decryption key identifier which should be used to decrypt the statement's data. In
+  the absence of this field `Data` should be treated as not encrypted.
+- 2: `Priority(u32)`: Priority specifier. Higher priority statements should be kept around at the cost of lower priority
+  statements if multiple statements from the same sender are competing for persistence or transport. Nodes should
+  disregard when considering unsigned statements.
+- 3: `Channel([u8; 32])`: The channel identifier. Only one message of a given channel should be retained at once (the
+  one of highest priority). Nodes should disregard when considering unsigned statements.
 - 4: `Topic1([u8; 32]))`: First topic identifier.
 - 5: `Topic2([u8; 32]))`: Second topic identifier.
 - 6: `Topic3([u8; 32]))`: Third topic identifier.
@@ -25,7 +42,7 @@ Formally, `Statement` is equivalent to the type `Vec<Field>` and `Field` is the
 - 2: `Secp256k1Ecdsa { signature: [u8; 65], signer: [u8; 33] )`
 - 3: `OnChain { who: [u8; 32], block_hash: [u8; 32], event_index: u64 }`

-### Potential uses
+## Potential uses

 Potential use-cases are various and include:
 - ring-signature aggregation;
@@ -1,4 +1,4 @@
 Lowest-abstraction level for the Substrate runtime: just exports useful primitives from std
 or client/alloc to be used with any code that depends on the runtime.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Primitive types for storage related stuff.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Substrate core types and inherents for timestamps.

-License: Apache-2.0
+License: Apache-2.0
@@ -12,4 +12,4 @@ Additionally, we have a const: `WASM_TRACE_IDENTIFIER`, which holds a span name
 to signal that the 'actual' span name and target should be retrieved instead from
 the associated Fields mentioned above.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Transaction pool primitives types & Runtime API.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Utility functions to interact with Substrate's Base-16 Modified Merkle Patricia tree ("trie").

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Version module for the Substrate runtime; Provides a function that returns the runtime version.

-License: Apache-2.0
+License: Apache-2.0
@@ -1,3 +1,3 @@
 Types and traits for interfacing between the host and the wasm runtime.

-License: Apache-2.0
+License: Apache-2.0