Merge pull request kroma-network#195 from kroma-network/docs/apply-ma…

…rkdownlint

docs: apply markdownlint

packages/contracts/README.md

@@ -68,7 +68,7 @@ We work on this repository with a combination of [Hardhat](https://hardhat.org)
 > yarn build
 ```
 
-### Tests
+### Test
 
 ```shell
 > yarn test
@@ -239,11 +239,11 @@ The parts are: `[method]_[FunctionName]_[reason]_[success]`, where:
 - `[FunctionName]` is the name of the function or higher level behavior being tested.
 - `[reason]` is an optional description for the behavior being tested.
 - `[status]` must be one of:
-    - `succeeds`: used for most happy path cases
-    - `reverts`: used for most sad path cases
-    - `works`: used for tests which include a mix of happy and sad assertions (these should be broken up if possible)
-    - `fails`: used for tests which 'fail' in some way other than reverting
-    - `benchmark`: used for tests intended to establish gas costs
+  - `succeeds`: used for most happy path cases
+  - `reverts`: used for most sad path cases
+  - `works`: used for tests which include a mix of happy and sad assertions (these should be broken up if possible)
+  - `fails`: used for tests which 'fail' in some way other than reverting
+  - `benchmark`: used for tests intended to establish gas costs
 
 #### Contract Naming Conventions
 

specs/challenge.md

@@ -5,7 +5,6 @@
 [g-l1]: glossary.md#layer-1-l1
 [g-l2]: glossary.md#layer-2-l2
 [g-l2-output]: glossary.md#l2-output-root
-[g-trusted-validator]: glossary.md#trusted-validator
 [g-validator]: glossary.md#validator
 [g-zk-fault-proof]: glossary.md#zk-fault-proof
 [g-security-council]: glossary.md#security-council
@@ -31,31 +30,31 @@
 ## Overview
 
 When a [validator][g-validator] detects that a submitted [L2 output root][g-l2-output] contains an invalid state
-transition, it can start a dispute challenge process by triggering the [Colosseum contract](#colosseum-contract). We
+transition, it can start a dispute challenge process by triggering the [Colosseum contract](#contract-interface). We
 refer to a validator who submits a dispute challenge as a "challenger" and a validator who initially submitted
 an L2 output as an "asserter." A dispute challenge entails a confrontational interaction between an asserter and a
-challenger, which persists until one of them emerges victorious. If the challenger wins, the corresponding L2 output 
+challenger, which persists until one of them emerges victorious. If the challenger wins, the corresponding L2 output
 will be deleted.
 
-A single output can be subject to multiple challenges. Challengers also need to stake their bonds equivalent to those 
-staked by asserter when submitting L2 outputs to generate challenges. Should the asserter emerge victorious in a 
-challenge, they receive the staked bonds of all the challengers as reward. On the other hand, if a challenger prevails, 
-the one who submitted the first valid ZK fault proof is given the asserter's staked bond. As a preventive measure 
-against collusion between asserters and challengers, tax is imposed. If there are any ongoing challenges, 
+A single output can be subject to multiple challenges. Challengers also need to stake their bonds equivalent to those
+staked by asserter when submitting L2 outputs to generate challenges. Should the asserter emerge victorious in a
+challenge, they receive the staked bonds of all the challengers as reward. On the other hand, if a challenger prevails,
+the one who submitted the first valid ZK fault proof is given the asserter's staked bond. As a preventive measure
+against collusion between asserters and challengers, tax is imposed. If there are any ongoing challenges,
 the challenges are canceled, and staked bonds are refunded to the respective challengers.
 
-In the ZK fault-proof challenge process, the following undeniable bug might arise, prompting the intervention of the 
+In the ZK fault-proof challenge process, the following undeniable bug might arise, prompting the intervention of the
 [Security Council][g-security-council]:
 
 - The deletion of a valid output due to two valid and contradictory zk proofs
 - The failure to delete an invalid output due to the bugs in prover/verifier or ZK completeness error
 - The deletion of a valid output due to two valid and contradictory ZK proofs
 - The failure to delete an invalid output due to the bugs in prover/verifier or ZK completeness error
 
-In the former case, the Security Council validates the legitimacy of the deleted output and, if the aforementioned 
-error is identified, dismisses the challenge and initiates a rollback of the deleted output. 
-In the latter scenario, all challengers will fail in proving the fault. In such cases, the Security Council verifies 
-the output and, if deemed invalid, delete the output forcibly. All interventions by the Security Council are executed 
+In the former case, the Security Council validates the legitimacy of the deleted output and, if the aforementioned
+error is identified, dismisses the challenge and initiates a rollback of the deleted output.
+In the latter scenario, all challengers will fail in proving the fault. In such cases, the Security Council verifies
+the output and, if deemed invalid, delete the output forcibly. All interventions by the Security Council are executed
 through multi-sig transactions.
 
 ## State Diagram
@@ -78,19 +77,19 @@ through multi-sig transactions.
 6. If the submitted proof is turned out to be invalid, the state stays at `READY_TO_PROVE` until `PROVING_TIMEOUT` is
    occurred.
 7. Otherwise, `READY_TO_PROVE` state goes to `PROVEN`, and the L2 output is deleted.
-8. The deleted output would be validated by the **[Security Council][g-security-council]** to mitigate ZK soundness 
+8. The deleted output would be validated by the **[Security Council][g-security-council]** to mitigate ZK soundness
    attack.
 9. If the deleted output was invalid, so it should have been, the Security Council do nothing.
 10. Otherwise, the **Security council** will dismiss the challenge and rollback the valid output.
 
 ## Challenge Creation
 
-Validators can initiate challenges when they suspect that an invalid output has been submitted. In their role as 
+Validators can initiate challenges when they suspect that an invalid output has been submitted. In their role as
 challengers, they start the challenge process with initial segments for interactive fault proof.
 
-> **Note** Challenges can only be initiated within the `CREATION_PERIOD` (< `FINALIZATION_PERIOD`) since the output 
-> is submitted. This restriction aims to prevent malicious challengers from deleting outputs just before finalization, 
-> causing a delay attack. 
+> **Note** Challenges can only be initiated within the `CREATION_PERIOD` (< `FINALIZATION_PERIOD`) since the output
+> is submitted. This restriction aims to prevent malicious challengers from deleting outputs just before finalization,
+> causing a delay attack.
 
 ## Bisection
 
@@ -219,24 +218,24 @@ The following is the verification process of invalid output by
 8. If the length of transaction hashes in `publicInput` is less than `MAX_TXS`, fill it with `DUMMY_HASH`.
 9. Verify the `_zkproof` using `_pair` and `publicInputHash`. The `publicInputHash` is derived from the `publicInput`
    and `stateRoot` of `srcOutputRootProof`, while `_zkproof` and `_pair` are submitted by the challenger directly.
-10. Delete the output and request validation of the challenge to [Security Council][g-security-council] if there is any 
+10. Delete the output and request validation of the challenge to [Security Council][g-security-council] if there is any
     undeniable bugs such as soundness error.
-11. If the deleted output was valid so the challenge has an undeniable bug, Security Council will 
+11. If the deleted output was valid so the challenge has an undeniable bug, Security Council will
     [dismiss](#dismiss-challenge) the challenge and roll back the output.
 
 ## Dismiss Challenge
 
 Upon a successful challenge resulting in output deletion, the Security Council will verify the genuineness of the
-deleted output(two valid contradicting ZK proofs). Given that the deletion of output introduces withdrawal delays, 
-the Security Council conducts a thorough investigation into this issue. Upon validation of the legitimate nature of the 
+deleted output(two valid contradicting ZK proofs). Given that the deletion of output introduces withdrawal delays,
+the Security Council conducts a thorough investigation into this issue. Upon validation of the legitimate nature of the
 output deletion, the Security Council will dismiss the challenge and initiate the process of output rollback.
 This can only be executed through the multi-sig transaction of the Security Council.
 
 ## Force Delete Output
 
 In the event that an undeniable bug within the ZK fault-proof system, such as a ZK completeness error, is detected, it
-becomes necessary to remove outputs deemed invalid. To address this, the Security Council is tasked with inspecting 
-outputs that have completed the bisect process but have failed the fault-proof verification. If an invalid output is 
+becomes necessary to remove outputs deemed invalid. To address this, the Security Council is tasked with inspecting
+outputs that have completed the bisect process but have failed the fault-proof verification. If an invalid output is
 submitted and is determined to be associated with an undeniable bug, the Security Council holds the authority to delete
 the output through a multi-sig transaction.
 
@@ -439,7 +438,7 @@ Colosseum contract should be deployed behind upgradable proxies.
 |-------------------------------|--------------------------------------------------------------------|-------------------|
 | `REQUIRED_BOND_AMOUNT`        | 200000000000000000 (0.2 ETH)                                       | wei               |
 | `FINALIZATION_PERIOD_SECONDS` | 604800                                                             | seconds           |
-| `CREATION_PERIOD_SECONDS`     | 518400                                                             | seconds           |           
+| `CREATION_PERIOD_SECONDS`     | 518400                                                             | seconds           |
 | `BISECTION_TIMEOUT`           | 3600                                                               | seconds           |
 | `PROVING_TIMEOUT`             | 28800                                                              | seconds           |
 | `SEGMENTS_LENGTHS`            | [9, 6, 10, 6]                                                      | array of integers |

specs/contract-upgrades.md

@@ -11,27 +11,26 @@
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-
 ## Overview
 
-[Smart contract upgrades](https://docs.openzeppelin.com/upgrades-plugins/1.x/proxies) are executed through the 
-[governance](https://docs.openzeppelin.com/contracts/4.x/api/governance) of the Security Council. The 
+[Smart contract upgrades](https://docs.openzeppelin.com/upgrades-plugins/1.x/proxies) are executed through the
+[governance](https://docs.openzeppelin.com/contracts/4.x/api/governance) of the Security Council. The
 authority to perform proxy upgrades lies with the Security Council's governor.
 
 There are two primary types of contract upgrades:
 
 - 30-Day Timelock Delay Upgrade
-- Emergency Upgrade 
-  
-Typically, when a proposal for an upgrade is approved, it undergoes a mandatory 30-day timelock delay period before 
-execution. However, in cases where an urgent upgrade is necessary due to security concerns, the Security Council 
+- Emergency Upgrade
+
+Typically, when a proposal for an upgrade is approved, it undergoes a mandatory 30-day timelock delay period before
+execution. However, in cases where an urgent upgrade is necessary due to security concerns, the Security Council
 retains the capability to conduct an emergency upgrade.
 
 ## Upgrade By Governance
 
 When an on-chain proposal for a contract upgrade is submitted by a member of Security Council, the member votes on the
 proposal during the voting period. Once a proposal is approved, the Security Council queues the proposal to the batch
-to be executed with a 30-day timelock. After the timelock delay, the upgrade can be executed. 
+to be executed with a 30-day timelock. After the timelock delay, the upgrade can be executed.
 
 ### Interface
 
@@ -92,9 +91,9 @@ to be executed with a 30-day timelock. After the timelock delay, the upgrade can
 
 ## Emergency Upgrade
 
-When an immediate upgrade is required for security concerns, the Security Council has the authority to perform an 
-emergency upgrade, which can be executed immediately once the voting period has ended. To propose an immediate upgrade 
-through governance, a member of Security Council would set the target address and value of the first transaction to be 
+When an immediate upgrade is required for security concerns, the Security Council has the authority to perform an
+emergency upgrade, which can be executed immediately once the voting period has ended. To propose an immediate upgrade
+through governance, a member of Security Council would set the target address and value of the first transaction to be
 executed.
 
 ```solidity
@@ -105,14 +104,14 @@ function queue(
         bytes32 _descriptionHash
     ) public virtual override returns (uint256) {
         // ...
-    
+
         uint256 delay = _timelock.getMinDelay();
         // Protocol for reflecting urgent decisions on proposals.
         // A zero delay is applied if the first element of the argument satisfies conditions.
         if (_targets[0] == address(0) && _values[0] == 0) {
             delay = 0;
         }
-    
+
         // ...
     }
 ```

specs/derivation.md

@@ -184,7 +184,8 @@ batches and invalid individual transactions within an otherwise valid batch are
 
 If a validator applies a state transition incorrectly and posts an [output root][g-l2-output],
 this output root will be incorrect. The incorrect output root, which will be challenged by a
-[ZK fault proof][g-zk-fault-proof], will then be replaced by a correct output root **for the existing proposer batches.**
+[ZK fault proof][g-zk-fault-proof], will then be replaced by a correct output root
+**for the existing proposer batches.**
 
 Refer to the [Batch Submission specification][batcher-spec] for more information.
 

specs/glossary.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD053 -->
 # Glossary
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
@@ -872,7 +873,7 @@ derivation then acts as a sanity check and a way to detect L1 chain [re-orgs][re
 
 In syncer mode, the rollup node performs derivation as indicated above, but is also able to "run ahead" of the L1
 chain by getting blocks directly from the proposer, in which case derivation serves to validate the proposer's
-behaviour.
+behavior.
 
 A rollup node running in syncer mode is sometimes called _a replica_.
 

specs/security-council.md

@@ -1,7 +1,6 @@
 # Security Council
 
 [g-l1]: glossary.md#layer-1-l1
-[g-l2]: glossary.md#layer-2-l2
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -14,27 +13,26 @@
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-
 ## Overview
 
-The Security Council comprises a group of trusted parties with the responsibility of safeguarding the blockchain's 
-security. They are minimally eligible for ensuring the blockchain's safety concerning the Fault Proof System, bridge 
-operations, and contract upgrades. No single member of the Security Council can unilaterally execute actions. Instead, 
+The Security Council comprises a group of trusted parties with the responsibility of safeguarding the blockchain's
+security. They are minimally eligible for ensuring the blockchain's safety concerning the Fault Proof System, bridge
+operations, and contract upgrades. No single member of the Security Council can unilaterally execute actions. Instead,
 all actions are carried out through multi-sig transaction or governance processes.
 
 ## Guardian of Fault Proof System
 
-When an undeniable bug occurs within the [ZK Fault Proof System](./glossary.md#zk-fault-proof), assets locked in 
-Layer 2 may be exposed to potential risks. To prevent this, the Security Council has the authority to rectify such 
-issues. The Security Council intervenes in cases where two valid and contradictory ZK proofs exist 
-([ZK soundness error](challenge.md#dismiss-challenge)) or fail to prove with a valid proof 
-([ZK completeness error](challenge.md#force-delete-output)). Their intervention aims to prevent invalid outputs from 
-being finalized, thereby safeguarding the assets locked in Layer 2. 
+When an undeniable bug occurs within the [ZK Fault Proof System](./glossary.md#zk-fault-proof), assets locked in
+Layer 2 may be exposed to potential risks. To prevent this, the Security Council has the authority to rectify such
+issues. The Security Council intervenes in cases where two valid and contradictory ZK proofs exist
+([ZK soundness error](challenge.md#dismiss-challenge)) or fail to prove with a valid proof
+([ZK completeness error](challenge.md#force-delete-output)). Their intervention aims to prevent invalid outputs from
+being finalized, thereby safeguarding the assets locked in Layer 2.
 
 ## Guardian of Bridge
 
 If potential threats exposing Layer 2 assets within the Bridge, the Security Council possesses the authority to promptly
-pause/unpause the bridge through a multi-sig transaction. The `GUARDIAN` in the 
+pause/unpause the bridge through a multi-sig transaction. The `GUARDIAN` in the
 [`KromaPortal.sol`](../packages/contracts/contracts/L1/KromaPortal.sol) is configured to be Security Council.
 
 ```solidity
@@ -59,10 +57,10 @@ pause/unpause the bridge through a multi-sig transaction. The `GUARDIAN` in the
 
 ## Contract Upgrades
 
-All contract upgrades deployed on [Layer 1][g-l1] are conducted by the 
-[governance of the Security Council](contract-upgrades.md#upgrade-by-governance). These upgrades are proposed by a 
-member of Security Council and are determined through the voting of these members. If a proposal passes, it typically 
+All contract upgrades deployed on [Layer 1][g-l1] are conducted by the
+[governance of the Security Council](contract-upgrades.md#upgrade-by-governance). These upgrades are proposed by a
+member of Security Council and are determined through the voting of these members. If a proposal passes, it typically
 has a 30-day timelock delay for execution.
 
-When an urgent upgrade is needed for a blockchain security, the Security Council has the authority to perform an 
+When an urgent upgrade is needed for a blockchain security, the Security Council has the authority to perform an
 [emergency upgrade](contract-upgrades.md#upgrade-by-governance).

specs/system-config.md

@@ -64,7 +64,7 @@ policy. It is not a consensus level parameter.
 
 ### `validatorRewardScalar` (`uint256`)
 
-The scalar value to distribute [transaction fees](./exec-engine.md#transaction-fees) on L2 to validators as a reward of 
+The scalar value to distribute [transaction fees](./exec-engine.md#transaction-fees) on L2 to validators as a reward of
 checkpoint output submission. The denominator is 10000.
 
 ## Writing the system config

specs/validator.md

@@ -174,8 +174,8 @@ When submitting the output, the validator must bond Ethereum for `REQUIRED_BOND_
 rewarded to the L2 `ValidatorRewardVault` contract when the output is finalized.
 
 Also, validators should stake their bond for disputing challenge. This bond will be given to the winner of the challenge
-as a reward. When this reward distributed, a [tax](./challenge.md) is imposed to prevent collusive attacks of asserter 
-and challenger. 
+as a reward. When this reward distributed, a [tax](./challenge.md) is imposed to prevent collusive attacks of asserter
+and challenger.
 
 Validator Pool Smart Contract implements the following interface: