From 33a586c08c218f9e53055312b33226618fdcdf9a Mon Sep 17 00:00:00 2001
From: Bogdan Kovtun <psirex48@gmail.com>
Date: Tue, 24 Dec 2024 04:21:08 +0400
Subject: [PATCH] Add NatSpec graphs for state transitions and proposal
 lifecycle

---
 contracts/EmergencyProtectedTimelock.sol      | 23 +++++++++++++++----
 .../DualGovernanceStateTransitions.sol        | 20 +++++++++++++++-
 2 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/contracts/EmergencyProtectedTimelock.sol b/contracts/EmergencyProtectedTimelock.sol
index 6790b963..43aa7a85 100644
--- a/contracts/EmergencyProtectedTimelock.sol
+++ b/contracts/EmergencyProtectedTimelock.sol
@@ -12,10 +12,25 @@ import {TimelockState} from "./libraries/TimelockState.sol";
 import {ExecutableProposals} from "./libraries/ExecutableProposals.sol";
 import {EmergencyProtection} from "./libraries/EmergencyProtection.sol";
 
-/// @title EmergencyProtectedTimelock
-/// @dev A timelock contract with emergency protection functionality. The contract allows for submitting, scheduling,
-///     and executing proposals, while providing emergency protection features to prevent unauthorized execution during
-///     emergency situations.
+/// @notice Timelock contract facilitating the submission, scheduling, and execution of governance proposals.
+///     It provides time-limited Emergency Protection to prevent the execution of proposals submitted by
+///     a compromised or misbehaving (including those caused by code vulnerabilities) governance entity.
+/// @dev The proposal lifecycle:
+///
+///                                         afterSubmitDelay          afterScheduleDelay
+///                                              passed                     passed
+///     ┌──────────┐            ┌───────────┐              ┌───────────┐             ╔══════════╗
+///     │ NotExist ├ submit() ─>│ Submitted ├ schedule() ─>│ Scheduled ├ execute() ─>║ Executed ║
+///     └──────────┘            └────────┬──┘              └──┬────────┘             ╚══════════╝
+///                                  cancelAllNonExecutedProposals()
+///                                      │   ╔═══════════╗    │
+///                                      └──>║ Cancelled ║<───┘
+///                                          ╚═══════════╝
+///
+///     The afterSubmit and afterSchedule delays must be configured appropriately to provide the Emergency Activation
+///     Committee sufficient time to activate Emergency Mode if a malicious proposal has been submitted or was
+///     unexpectedly scheduled for execution due to governance capture or a vulnerability in the governance contract.
+///     While Emergency Mode is active, the execution of proposals is restricted to the Emergency Execution Committee.
 contract EmergencyProtectedTimelock is IEmergencyProtectedTimelock {
     using TimelockState for TimelockState.Context;
     using ExecutableProposals for ExecutableProposals.Context;
diff --git a/contracts/libraries/DualGovernanceStateTransitions.sol b/contracts/libraries/DualGovernanceStateTransitions.sol
index b7b78dc5..3fb7ece9 100644
--- a/contracts/libraries/DualGovernanceStateTransitions.sol
+++ b/contracts/libraries/DualGovernanceStateTransitions.sol
@@ -8,7 +8,25 @@ import {DualGovernanceConfig} from "./DualGovernanceConfig.sol";
 import {State, DualGovernanceStateMachine} from "./DualGovernanceStateMachine.sol";
 
 /// @title Dual Governance State Transitions Library
-/// @notice Library containing the transitions logic for the Dual Governance system
+/// @notice Library containing the transition logic for the Dual Governance system.
+/// @dev The graph of the state transitions:
+///
+///        ┌─────────────┐     ┌──────────────────┐
+///        │    Normal   ├────>│  VetoSignalling  │<───────┐
+///     ┌─>│  [SUB, EXE] │     │      [SUB]       │<────┐  │
+///     │  └─────────────┘     │ ┌──────────────┐ │     │  │
+///     │                   ┌──┼─┤ Deactivation ├─┼──┐  │  │
+///     │                   │  │ │     [ ]      │ │  │  │  │
+///     │                   │  │ └──────────────┘ │  │  │  │
+///     │                   │  └──────────────────┘  │  │  │
+///     │  ┌──────────────┐ │     ┌──────────┐       │  │  │
+///     └──┤ VetoCooldown │<┘     │ RageQuit │<──────┘  │  │
+///        │     [EXE]    │<──────┤   [SUB]  │<─────────┘  │
+///        └──────┬───────┘       └──────────┘             │
+///               └────────────────────────────────────────┘
+///
+///     SUB - Allows proposals submission while the state is active.
+///     EXE - Allows scheduling proposals for execution while the state is active.
 library DualGovernanceStateTransitions {
     using DualGovernanceConfig for DualGovernanceConfig.Context;