docs(protocol,repo): add missing docstrings (taikoxyz#16184)

Co-authored-by: Daniel Wang <[email protected]>
Co-authored-by: Daniel Wang <[email protected]>

CONTRIBUTING.md

@@ -193,6 +193,47 @@ If you are referring to some struct or function within the file you can use the
 /// @notice See the struct in {TaikoData.Config}
 ```
 
+#### What to document
+
+All public interfaces (those that would be in the ABI) should be documented. This includes public state variables, functions, events, errors, etc. If it's in the ABI, it needs NatSpec.
+
+#### Ordering
+
+> Taken from the official Solidity Style Guide
+
+Contract elements should be laid out in the following order:
+
+1. Pragma statements
+2. Import statements
+3. Events
+4. Errors
+5. Interfaces
+6. Libraries
+7. Contracts
+
+Inside each contract, library or interface, use the following order:
+
+1. Type declarations
+2. State variables
+3. Events
+4. Errors
+5. Modifiers
+6. Functions
+
+Functions should be grouped according to their visibility and ordered:
+
+1. constructor
+2. receive function (if exists)
+3. fallback function (if exists)
+4. external
+5. public
+6. internal
+7. private
+
+It is preferred for state variables to follow the same ordering according to visibility as functions, shown above, but it is not required as this could affect the storage layout.
+
+Lexicographical order is preferred but also optional.
+
 #### Documenting interfaces
 
 To document the implementing contract of an interface, you cannot use `@inheritdoc`, it is not supported for contracts at the top-level. Thus, you should mention a statement like so:

packages/protocol/contracts/L1/TaikoL1.sol

@@ -20,7 +20,9 @@ import "./TaikoEvents.sol";
 /// @dev Labeled in AddressResolver as "taiko"
 /// @custom:security-contact [email protected]
 contract TaikoL1 is EssentialContract, ITaikoL1, TaikoEvents, TaikoErrors {
+    /// @notice The TaikoL1 state.
     TaikoData.State public state;
+
     uint256[50] private __gap;
 
     modifier whenProvingNotPaused() {
@@ -121,6 +123,7 @@ contract TaikoL1 is EssentialContract, ITaikoL1, TaikoEvents, TaikoErrors {
         LibDepositing.depositEtherToL2(state, getConfig(), this, recipient);
     }
 
+    /// @inheritdoc EssentialContract
     function unpause() public override {
         super.unpause(); // permission checked inside
         state.slotB.lastUnpausedAt = uint64(block.timestamp);
@@ -133,6 +136,7 @@ contract TaikoL1 is EssentialContract, ITaikoL1, TaikoEvents, TaikoErrors {
         return LibDepositing.canDepositEthToL2(state, getConfig(), amount);
     }
 
+    /// @notice See {LibProposing-isBlobReusable}.
     function isBlobReusable(bytes32 blobHash) public view returns (bool) {
         return LibProposing.isBlobReusable(state, getConfig(), blobHash);
     }

packages/protocol/contracts/L1/gov/TaikoGovernor.sol

@@ -59,12 +59,12 @@ contract TaikoGovernor is
     }
 
     /// @notice An overwrite of GovernorCompatibilityBravoUpgradeable's propose() as that one does
-    /// not checks the length of signatures equal to calldatas.
-    /// See vulnerability description here:
+    /// not check that the length of signatures equal the calldata.
+    /// @dev See vulnerability description here:
     /// https://github.com/taikoxyz/taiko-mono/security/dependabot/114
     /// See fix in OZ 4.8.3 here:
     /// https://github.com/OpenZeppelin/openzeppelin-contracts/blob/0a25c1940ca220686588c4af3ec526f725fe2582/contracts/governance/compatibility/GovernorCompatibilityBravo.sol#L72
-    /// @dev See {GovernorCompatibilityBravoUpgradeable-propose}
+    /// See {GovernorCompatibilityBravoUpgradeable-propose}
     function propose(
         address[] memory targets,
         uint256[] memory values,
@@ -84,6 +84,7 @@ contract TaikoGovernor is
         );
     }
 
+    /// @dev See {GovernorUpgradeable-supportsInterface}
     function supportsInterface(bytes4 interfaceId)
         public
         view
@@ -93,6 +94,7 @@ contract TaikoGovernor is
         return super.supportsInterface(interfaceId);
     }
 
+    /// @dev See {GovernorUpgradeable-state}
     function state(uint256 proposalId)
         public
         view
@@ -102,18 +104,21 @@ contract TaikoGovernor is
         return super.state(proposalId);
     }
 
-    // How long after a proposal is created should voting power be fixed. A
-    // large voting delay gives users time to unstake tokens if necessary.
+    /// @notice How long after a proposal is created should voting power be fixed. A
+    /// large voting delay gives users time to unstake tokens if necessary.
+    /// @return The duration of the voting delay.
     function votingDelay() public pure override returns (uint256) {
         return 7200; // 1 day
     }
 
-    // How long does a proposal remain open to votes.
+    /// @notice How long does a proposal remain open to votes.
+    /// @return The duration of the voting period.
     function votingPeriod() public pure override returns (uint256) {
         return 50_400; // 1 week
     }
 
-    // The number of votes required in order for a voter to become a proposer
+    /// @notice The number of votes required in order for a voter to become a proposer.
+    /// @return The number of votes required.
     function proposalThreshold() public pure override returns (uint256) {
         return 1_000_000_000 ether / 10_000; // 0.01% of Taiko Token
     }

packages/protocol/contracts/L1/hooks/AssignmentHook.sol

@@ -31,14 +31,18 @@ contract AssignmentHook is EssentialContract, IHook {
         uint256 tip; // A tip to L1 block builder
     }
 
-    // Max gas paying the prover. This should be large enough to prevent the
-    // worst cases for the prover. To assure a trustless relationship between
-    // the proposer and the prover it's the prover's job to make sure it can
-    // get paid within this limit.
+    /// @notice Max gas paying the prover.
+    /// @dev This should be large enough to prevent the worst cases for the prover.
+    /// To assure a trustless relationship between the proposer and the prover it's
+    /// the prover's job to make sure it can get paid within this limit.
     uint256 public constant MAX_GAS_PAYING_PROVER = 50_000;
 
     uint256[50] private __gap;
 
+    /// @notice Emitted when a block is assigned to a prover.
+    /// @param assignedProver The address of the assigned prover.
+    /// @param meta The metadata of the assigned block.
+    /// @param assignment The prover assignment.
     event BlockAssigned(
         address indexed assignedProver, TaikoData.BlockMetadata meta, ProverAssignment assignment
     );
@@ -54,6 +58,7 @@ contract AssignmentHook is EssentialContract, IHook {
         __Essential_init(_owner, _addressManager);
     }
 
+    /// @inheritdoc IHook
     function onBlockProposed(
         TaikoData.Block memory blk,
         TaikoData.BlockMetadata memory meta,
@@ -124,6 +129,11 @@ contract AssignmentHook is EssentialContract, IHook {
         emit BlockAssigned(blk.assignedProver, meta, assignment);
     }
 
+    /// @notice Hashes the prover assignment.
+    /// @param assignment The prover assignment.
+    /// @param taikoL1Address The address of the TaikoL1 contract.
+    /// @param blobHash The blob hash.
+    /// @return The hash of the prover assignment.
     function hashAssignment(
         ProverAssignment memory assignment,
         address taikoL1Address,

packages/protocol/contracts/L1/hooks/IHook.sol

@@ -6,6 +6,10 @@ import "../TaikoData.sol";
 /// @title IHook
 /// @custom:security-contact [email protected]
 interface IHook {
+    /// @notice Called when a block is proposed.
+    /// @param blk The proposed block.
+    /// @param meta The metadata of the proposed block.
+    /// @param data The data of the proposed block.
     function onBlockProposed(
         TaikoData.Block memory blk,
         TaikoData.BlockMetadata memory meta,

packages/protocol/contracts/L1/libs/LibDepositing.sol

@@ -14,10 +14,11 @@ library LibDepositing {
     using LibAddress for address payable;
     using LibMath for uint256;
 
-    // Warning: Any events defined here must also be defined in TaikoEvents.sol.
+    /// @notice Emitted when Ether is deposited.
+    /// @dev Any events defined here must also be defined in TaikoEvents.sol.
     event EthDeposited(TaikoData.EthDeposit deposit);
 
-    // Warning: Any errors defined here must also be defined in TaikoErrors.sol.
+    /// @dev Any errors defined here must also be defined in TaikoErrors.sol.
     error L1_INVALID_ETH_DEPOSIT();
 
     /// @dev Deposits Ether to Layer 2.

packages/protocol/contracts/L1/libs/LibProposing.sol

@@ -15,11 +15,19 @@ import "./LibDepositing.sol";
 library LibProposing {
     using LibAddress for address;
 
-    // According to EIP4844, each blob has up to 4096 field elements, and each
-    // field element has 32 bytes.
+    /// @notice The maximum number of bytes allowed per blob.
+    /// @dev According to EIP4844, each blob has up to 4096 field elements, and each
+    /// field element has 32 bytes.
     uint256 public constant MAX_BYTES_PER_BLOB = 4096 * 32;
 
     // Warning: Any events defined here must also be defined in TaikoEvents.sol.
+    /// @notice Emitted when a block is proposed.
+    /// @param blockId The ID of the proposed block.
+    /// @param assignedProver The address of the assigned prover.
+    /// @param livenessBond The liveness bond of the proposed block.
+    /// @param meta The metadata of the proposed block.
+    /// @param depositsProcessed The EthDeposit array about processed deposits in this proposed
+    /// block.
     event BlockProposed(
         uint256 indexed blockId,
         address indexed assignedProver,
@@ -28,6 +36,8 @@ library LibProposing {
         TaikoData.EthDeposit[] depositsProcessed
     );
 
+    /// @notice Emitted when a blob is cached.
+    /// @param blobHash The hash of the cached blob.
     event BlobCached(bytes32 blobHash);
 
     // Warning: Any errors defined here must also be defined in TaikoErrors.sol.
@@ -273,6 +283,11 @@ library LibProposing {
         });
     }
 
+    /// @notice Checks if a blob is reusable.
+    /// @param state Current TaikoData.State.
+    /// @param config The TaikoData.Config.
+    /// @param blobHash The blob hash
+    /// @return True if the blob is reusable, false otherwise.
     function isBlobReusable(
         TaikoData.State storage state,
         TaikoData.Config memory config,

packages/protocol/contracts/L1/libs/LibProving.sol

@@ -16,10 +16,19 @@ import "./LibUtils.sol";
 library LibProving {
     using LibMath for uint256;
 
+    /// @notice Keccak hash of the string "RETURN_LIVENESS_BOND".
     bytes32 public constant RETURN_LIVENESS_BOND = keccak256("RETURN_LIVENESS_BOND");
+
+    /// @notice The tier name for optimistic proofs.
     bytes32 public constant TIER_OP = bytes32("tier_optimistic");
 
     // Warning: Any events defined here must also be defined in TaikoEvents.sol.
+    /// @notice Emitted when a transition is proved.
+    /// @param blockId The block ID.
+    /// @param tran The transition data.
+    /// @param prover The prover's address.
+    /// @param validityBond The validity bond amount.
+    /// @param tier The tier of the proof.
     event TransitionProved(
         uint256 indexed blockId,
         TaikoData.Transition tran,
@@ -28,6 +37,12 @@ library LibProving {
         uint16 tier
     );
 
+    /// @notice Emitted when a transition is contested.
+    /// @param blockId The block ID.
+    /// @param tran The transition data.
+    /// @param contester The contester's address.
+    /// @param contestBond The contest bond amount.
+    /// @param tier The tier of the proof.
     event TransitionContested(
         uint256 indexed blockId,
         TaikoData.Transition tran,
@@ -36,6 +51,8 @@ library LibProving {
         uint16 tier
     );
 
+    /// @notice Emitted when proving is paused or unpaused.
+    /// @param paused The pause status.
     event ProvingPaused(bool paused);
 
     // Warning: Any errors defined here must also be defined in TaikoErrors.sol.
@@ -50,6 +67,9 @@ library LibProving {
     error L1_MISSING_VERIFIER();
     error L1_NOT_ASSIGNED_PROVER();
 
+    /// @notice Pauses or unpauses the proving process.
+    /// @param state Current TaikoData.State.
+    /// @param toPause The pause status.
     function pauseProving(TaikoData.State storage state, bool toPause) external {
         if (state.slotB.provingPaused == toPause) revert L1_INVALID_PAUSE_STATUS();
 

packages/protocol/contracts/L1/libs/LibVerifying.sol

@@ -17,6 +17,14 @@ library LibVerifying {
     using LibMath for uint256;
 
     // Warning: Any events defined here must also be defined in TaikoEvents.sol.
+    /// @notice Emitted when a block is verified.
+    /// @param blockId The block ID.
+    /// @param assignedProver The assigned prover of the block.
+    /// @param prover The actual prover of the block.
+    /// @param blockHash The block hash.
+    /// @param stateRoot The state root.
+    /// @param tier The tier of the transition used for verification.
+    /// @param contestations The number of contestations.
     event BlockVerified(
         uint256 indexed blockId,
         address indexed assignedProver,
@@ -32,6 +40,10 @@ library LibVerifying {
     error L1_INVALID_CONFIG();
     error L1_TRANSITION_ID_ZERO();
 
+    /// @notice Initializes the Taiko protocol state.
+    /// @param state The state to initialize.
+    /// @param config The configuration for the Taiko protocol.
+    /// @param genesisBlockHash The block hash of the genesis block.
     function init(
         TaikoData.State storage state,
         TaikoData.Config memory config,
@@ -230,7 +242,7 @@ library LibVerifying {
         }
     }
 
-    function _isConfigValid(TaikoData.Config memory config) private view returns (bool isValid) {
+    function _isConfigValid(TaikoData.Config memory config) private view returns (bool) {
         if (
             config.chainId <= 1 || config.chainId == block.chainid //
                 || config.blockMaxProposals == 1

packages/protocol/contracts/L1/provers/GuardianProver.sol

@@ -10,6 +10,11 @@ import "./Guardians.sol";
 contract GuardianProver is Guardians {
     uint256[50] private __gap;
 
+    /// @notice Emitted when a guardian proof is approved.
+    /// @param addr The address of the guardian.
+    /// @param blockId The block ID.
+    /// @param blockHash The block hash.
+    /// @param approved If the proof is approved.
     event GuardianApproval(
         address indexed addr, uint256 indexed blockId, bytes32 blockHash, bool approved
     );