Emergency pallets update (#758)

Author: Dinonard

docs/learn/governance/img/19_Emergency/01_emergency.png

@@ -153,10 +153,10 @@ In case the token holder votes correspond to the _winning_ side, their tokens wi
 | Minimum Public Referendum Deposit        | 10 SBY                    | 1000 ASTR               |
 | Simple Majority Proposal Origin          | 1/2 Main Council          | 2/3 Main Council        |
 | Super Majority Against Proposal Origin   | Unanimous Main Council    | Unanimous Main Council  |
-| Fast Track Origin                        | 1/2 Technical Committee   | 2/3 Technical Committee |
-| Instant Track Origin                     | Unanimous Technical Committee | Unanimous Technical Committee |
+| Fast Track Origin                        | 1/2 Tech Committee   | 2/3 Tech Committee |
+| Instant Track Origin                     | Unanimous Tech Committee | Unanimous Tech Committee |
 | Referendum Cancellation Origin           | 1/2 Main Council          | 2/3 Main Council        |
-| Public Proposal Cancellation Origin      | 1/2 Technical Committee   | 2/3 Technical Committee |
+| Public Proposal Cancellation Origin      | 1/2 Tech Committee   | 2/3 Tech Committee |
 
 #### Conviction Voting
 
@@ -239,34 +239,37 @@ To check the current number of members, it is best to refer to the on-chain data
 
 These parameters are related to the _dApp staking_ logic.
 
-| Parameter Name                          | Shibuya                  | Astar                    |
-| --------------------------------------- | ------------------------ | ------------------------ |
-| dApp Register Origin                    | 1/2 Community Council    | 2/3 Community Council    |
-| dApp Unregister Origin                  | 4/5 Community Council    | 4/5 Community Council    |
-| Community Council Staking Operations    | 1/2 Community Council    | 2/3 Community Council    |
+| Parameter Name                          | Shibuya                  | Astar                                       |
+| --------------------------------------- | ------------------------ | ------------------------------------------- |
+| dApp Register Origin                    | 1/2 Community Council    | 2/3 Community Council                       |
+| dApp Unregister Origin                  | 4/5 Community Council    | 4/5 Community Council                       |
+| Community Council Staking Operations    | 1/2 Community Council    | 2/3 Community Council                       |
+| dApp Staking Maintenance Mode Origin    | 1/2 Tech Committee  | 1/2 Tech Committee or 2/3 Main Council      |
 
 ### Emergency Maintenance Pallets
 
 #### Safe Mode
 
-The **SafeMode** pallet introduces an emergency STOP mechanism for the chain, restricting operations to a predefined set of permitted calls (only system calls). This mechanism is especially useful during chain anomalies or attacks. The `Technical Committee` can force-enter or exit _Safe Mode_. The _dApp staking_ maintenance mode is triggered when entering/exiting **Safe Mode**.
+The **SafeMode** pallet introduces an emergency STOP mechanism for the chain, restricting operations to a predefined set of permitted calls Operations like balance & asset transfer, smart contract calls, dApp staking operations aren't allowed. This mechanism is intended for severe situations like critical bugs or attacks. Both the `Tech Committee` and the `MainCouncil` can force-enter or exit _Safe Mode_. The _dApp staking_ maintenance mode is enabled/disabled when entering/exiting **Safe Mode**.
+
+The _safe mode_ has a limited duration, but can be extended as many time as needed. However, it's not possible to put the entire chain into _safe mode_ indefinitely.
 
 These parameters are related to the _Safe Mode_ logic.
 
-| Parameter Name                          | Shibuya                  | Astar                    |
-| --------------------------------------- | ------------------------ | ------------------------ |
-| Enter Duration                          | 4 hours                  | TBD                      |
-| Extend Duration                         | 2 hours                  | TBD                      |
-| Force Enter Origin                      | 1/2 Technical Committee  | TBD                      |
-| Force Exit Origin                       | 2/3 Technical Committee  | TBD                      |
+| Parameter Name     | Shibuya                                      | Astar                                        |
+| ------------------ | -------------------------------------------- | -------------------------------------------- |
+| Enter Duration     | 4 hours                                      | 12 hours                                     |
+| Extend Duration    | 2 hours                                      | 4 hours                                      |
+| Force Enter Origin | 1/2 Tech Committee or 2/3 Main Council  | 1/2 Tech Committee or 2/3 Main Council  |
+| Force Exit Origin  | 1/2 Tech Committee or 2/3 Main Council  | 1/2 Tech Committee or 2/3 Main Council  |
 
 #### Tx Pause
 
-The **TxPause** pallet provides the ability to pause specific transaction calls dynamically. This feature is useful for mitigating issues with specific modules or calls without halting the entire chain. The `Technical Committee` can pause and resume individual calls dynamically as needed.
+The **TxPause** pallet provides the ability to pause specific transaction calls dynamically. This feature is useful for mitigating issues with specific modules or calls without halting the entire chain. This should be preferred to **SafeMode** in most cases as it is more precise & flexible. Both the `Tech Committee` and the `MainCouncil` can pause and resume individual calls dynamically as needed.
 
 These parameters are related to the _Tx Pause_ logic.
 
-| Parameter Name                          | Shibuya                  | Astar                    |
-| --------------------------------------- | ------------------------ | ------------------------ |
-| Pause Origin                            | 1/2 Technical Committee  | TBD                      |
-| Unpause Origin                          | 1/2 Technical Committee  | TBD                      |
+| Parameter Name | Shibuya                                     | Astar                                       |
+|----------------|---------------------------------------------|---------------------------------------------|
+| Pause Origin   | 1/2 Tech Committee or 2/3 Main Council | 1/2 Tech Committee or 2/3 Main Council |
+| Unpause Origin | 1/2 Tech Committee or 2/3 Main Council | 1/2 Tech Committee or 2/3 Main Council |

docs/learn/governance/img/19_Emergency/02_emergency.png

@@ -88,6 +88,55 @@ The _pallet-collective-proxy_ is a special pallet that allows calls to be made o
 * `Treasury->proposeSpend` - proposes the spending of the main on-chain treasury funds (requires a deposit)
 * `CommunityTreasury->proposeSpend` - proposes the spending of the community treasury funds (requires a deposit)
 
+### Emergency Situations
+
+The following functions aren't tied to any specific actor, but at the moment of writing this guide, they are only callable by the `Technical Committee` or the `Main Council`.
+
+#### Safe Mode
+
+Intended to put the entire chain into _safe mode_, prohibiting any non-critical user transactions. This should only be used in case of a critical bug or vulnerability that needs to be fixed immediately.
+
+* `SafeMode->forceEnter` - puts the chain into _safe mode_, preventing any non-critical transactions.
+* `SafeMode->forceExtend` - extends the _safe mode_ duration, allowing more time for the fix to be implemented. Can be used repeatedly to extend the _safe mode_ duration by a fixed amount.
+* `SafeMode->forceExit` - exits the _safe mode_.
+
+#### Tx Pause
+
+Intended to prohibit specific extrinsic calls. Similar to _safe mode_ but more precise & flexible. Caller is required to precisely specify pallet name (as integrated in the runtime) and the extrinsic call.
+
+Integrated pallet names are defined in the runtime code, but can also be checked in `polkadot-js app` when selecting an extrinsic or state query. However, when checking the app, user needs to be aware that the first letter should be capitalized. For example, using the following image:
+
+<Figure caption="Emergency - 1" src={require('/docs/learn/governance/img/19_Emergency/01_emergency.png').default } width="100%" />
+
+we can observe pallets **assets** & **balances** but their actual names are **Assets** & **Balances**. This is important to note because if incorrect pallet name is specified, the call won't be properly filtered nor will the runtime inform the user that the call doesn't exist.
+
+For the 2nd part, the extrinsic call name, it must be specified in _snake_case_. 
+
+This is exactly how it's defined in the pallet code, but the name can also be found using the `polkadot-js app`. When a pallet is selected under extrinsic selection, all extrinsic calls are listed but in _camelCase_. For example, using the following image:
+
+<Figure caption="Emergency - 2" src={require('/docs/learn/governance/img/19_Emergency/02_emergency.png').default } width="100%" />
+
+we can observe that pallet `Balances` has calls like `burn`, `forceTransfer` or `transferAll`. Transforming these into _snake_case_ we get `burn` (unchanged), `force_transfer` and `transfer_all`.
+
+The pallet has only two calls.
+
+* `TxPause->pause`
+* `TxPause->unpause`
+
+Using all of the information presented so far, a few examples how these calls can be used:
+
+* **TxPause->pause("Balances", "transfer_all")**
+* **TxPause->pause("DappStaking", "claim_unlocked")**
+* **TxPause->pause("Assets", "transfer_keep_alive")**
+
+### dApp Staking
+
+dApp staking has a `maintenance mode` which essentially disables all possible interactions with the pallet, and prevents eras from advancing (to prevent any further storage modifications). It can be enabled either by the `Tech Committee` or by the `Main Council`.
+
+It's intended to be used when the dApp staking protocol has become compromised due to a bug or an attack.
+
+* `DappStaking->maintenanceMode`
+
 ## User Guide
 
 :::note

docs/learn/governance/index.md

@@ -67,4 +67,4 @@
     "node": ">=22.x"
   },
   "packageManager": "[email protected]"
-}
+}