documentation for recovery of emergency phase (#9989)

* documentation for recovery of emergency phase

* Update frame/election-provider-multi-phase/src/lib.rs

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

* Update frame/election-provider-multi-phase/src/lib.rs

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

Co-authored-by: Alexander Popiak <alexander.popiak@parity.io>

substrate/frame/election-provider-multi-phase/src/lib.rs

@@ -67,11 +67,11 @@
 //! origin can not bail out in any way, if their solution is queued.
 //!
 //! Upon the end of the signed phase, the solutions are examined from best to worse (i.e. `pop()`ed
-//! until drained). Each solution undergoes an expensive `Pallet::feasibility_check`, which
-//! ensures the score claimed by this score was correct, and it is valid based on the election data
-//! (i.e. votes and candidates). At each step, if the current best solution passes the feasibility
-//! check, it is considered to be the best one. The sender of the origin is rewarded, and the rest
-//! of the queued solutions get their deposit back and are discarded, without being checked.
+//! until drained). Each solution undergoes an expensive `Pallet::feasibility_check`, which ensures
+//! the score claimed by this score was correct, and it is valid based on the election data (i.e.
+//! votes and candidates). At each step, if the current best solution passes the feasibility check,
+//! it is considered to be the best one. The sender of the origin is rewarded, and the rest of the
+//! queued solutions get their deposit back and are discarded, without being checked.
 //!
 //! The following example covers all of the cases at the end of the signed phase:
 //!
@@ -121,17 +121,35 @@
 //!
 //! If, for any of the below reasons:
 //!
-//! 1. No signed or unsigned solution submitted & Fallback is `None` or failed
-//! 2. Internal error
+//! 1. No **signed** or **unsigned** solution submitted, and no successful [`Config::Fallback`] is
+//!    provided
+//! 2. Any other unforeseen internal error
 //!
 //! A call to `T::ElectionProvider::elect` is made, and `Ok(_)` cannot be returned, then the pallet
 //! proceeds to the [`Phase::Emergency`]. During this phase, any solution can be submitted from
-//! [`Config::ForceOrigin`], without any checking. Once submitted, the forced solution is kept in
-//! [`QueuedSolution`] until the next call to `T::ElectionProvider::elect`, where it is returned and
-//! [`Phase`] goes back to `Off`.
+//! [`Config::ForceOrigin`], without any checking, via [`Pallet::set_emergency_election_result`]
+//! transaction. Hence, `[`Config::ForceOrigin`]` should only be set to a trusted origin, such as
+//! the council or root. Once submitted, the forced solution is kept in [`QueuedSolution`] until the
+//! next call to `T::ElectionProvider::elect`, where it is returned and [`Phase`] goes back to
+//! `Off`.
 //!
 //! This implies that the user of this pallet (i.e. a staking pallet) should re-try calling
-//! `T::ElectionProvider::elect` in case of error until `OK(_)` is returned.
+//! `T::ElectionProvider::elect` in case of error, until `OK(_)` is returned.
+//!
+//! To generate an emergency solution, one must only provide one argument: [`Supports`]. This is
+//! essentially a collection of elected winners for the election, and voters who support them. The
+//! supports can be generated by any means. In the simplest case, it could be manual. For example,
+//! in the case of massive network failure or misbehaviour, [`Config::ForceOrigin`] might decide to
+//! select only a small number of emergency winners (which would greatly restrict the next validator
+//! set, if this pallet is used with `pallet-staking`). If the failure is for other technical
+//! reasons, then a simple and safe way to generate supports is using the staking-miner binary
+//! provided in the Polkadot repository. This binary has a subcommand named `emergency-solution`
+//! which is capable of connecting to a live network, and generating appropriate `supports` using a
+//! standard algorithm, and outputting the `supports` in hex format, ready for submission. Note that
+//! while this binary lives in the Polkadot repository, this particular subcommand of it can work
+//! against any substrate based-chain.
+//!
+//! See the `staking-miner` documentation in the Polkadot repository for more information.
 //!
 //! ## Feasible Solution (correct solution)
 //!
@@ -146,16 +164,16 @@
 //!
 //! ## Accuracy
 //!
-//! The accuracy of the election is configured via
-//! [`SolutionAccuracyOf`] which is the accuracy that the submitted solutions must adhere to.
+//! The accuracy of the election is configured via [`SolutionAccuracyOf`] which is the accuracy that
+//! the submitted solutions must adhere to.
 //!
 //! Note that the accuracy is of great importance. The offchain solution should be as small as
 //! possible, reducing solutions size/weight.
 //!
 //! ## Error types
 //!
-//! This pallet provides a verbose error system to ease future debugging and debugging. The
-//! overall hierarchy of errors is as follows:
+//! This pallet provides a verbose error system to ease future debugging and debugging. The overall
+//! hierarchy of errors is as follows:
 //!
 //! 1. [`pallet::Error`]: These are the errors that can be returned in the dispatchables of the
 //!    pallet, either signed or unsigned. Since decomposition with nested enums is not possible
@@ -173,6 +191,9 @@
 //!
 //! ## Future Plans
 //!
+//! **Emergency-phase recovery script**: This script should be taken out of staking-miner in
+//! polkadot and ideally live in `substrate/utils/frame/elections`.
+//!
 //! **Challenge Phase**. We plan on adding a third phase to the pallet, called the challenge phase.
 //! This is a phase in which no further solutions are processed, and the current best solution might
 //! be challenged by anyone (signed or unsigned). The main plan here is to enforce the solution to