chore(protocol): improve protocol documentation (#14399)

Co-authored-by: Brechtpd <[email protected]> Co-authored-by: David <[email protected]> Co-authored-by: d1onys1us <[email protected]>
taikoxyz · Aug 11, 2023 · fbbc417 · fbbc417
1 parent fd54f13
commit fbbc417
Show file tree

Hide file tree

Showing 39 changed files with 1,015 additions and 397 deletions.
diff --git a/packages/protocol/contracts/L1/IProofVerifier.sol b/packages/protocol/contracts/L1/IProofVerifier.sol
@@ -6,14 +6,19 @@
 
 pragma solidity ^0.8.20;
 
+/**
+ * @title IProofVerifier Interface
+ * @dev Interface for the ProofVerifier contract which is responsible for
+ * verifying proofs.
+ */
 interface IProofVerifier {
     /**
-     * Verifying proof via the ProofVerifier contract. This function must throw
-     * if verificaiton fails.
+     * @notice Verify proof(s) for the given block.
+     * This function should revert if the verification fails.
      *
-     * @param blockId BlockId
-     * @param blockProofs Raw bytes of proof(s)
-     * @param instance Hashed evidence & config data
+     * @param blockId Unique identifier for the block.
+     * @param blockProofs Raw bytes representing the proof(s).
+     * @param instance Hash combining evidence and configuration data.
      */
     function verifyProofs(
         uint256 blockId,

diff --git a/packages/protocol/contracts/L1/IProverPool.sol b/packages/protocol/contracts/L1/IProverPool.sol
@@ -6,16 +6,42 @@
 
 pragma solidity ^0.8.20;
 
+/**
+ * @title IProverPool Interface
+ * @dev Interface for the ProverPool contract, which manages the assignment,
+ * release, and slashing of provers.
+ */
 interface IProverPool {
+    /**
+     * @notice Assigns a prover to a specific block.
+     *
+     * @param blockId Unique identifier for the block.
+     * @param feePerGas The fee amount per unit of gas.
+     * @return prover Address of the assigned prover.
+     * @return rewardPerGas Reward allocated per unit of gas for the prover.
+     */
     function assignProver(
         uint64 blockId,
         uint32 feePerGas
     )
         external
         returns (address prover, uint32 rewardPerGas);
 
+    /**
+     * @notice Releases a prover.
+     *
+     * @param prover Address of the prover to be released.
+     */
     function releaseProver(address prover) external;
 
+    /**
+     * @notice Penalizes a prover by burning their staked tokens.
+     *
+     * @param blockId Unique identifier for the block associated with the
+     * prover's task.
+     * @param prover Address of the prover being penalized.
+     * @param proofReward Reward initially allocated for proof validation.
+     */
     function slashProver(
         uint64 blockId,
         address prover,

diff --git a/packages/protocol/contracts/L1/ProofVerifier.sol b/packages/protocol/contracts/L1/ProofVerifier.sol
@@ -9,36 +9,48 @@ pragma solidity ^0.8.20;
 import { AddressResolver } from "../common/AddressResolver.sol";
 import { EssentialContract } from "../common/EssentialContract.sol";
 import { Proxied } from "../common/Proxied.sol";
-import { LibVerifyZKP } from "./libs/proofTypes/LibVerifyZKP.sol";
+import { LibZKPVerifier } from "./libs/verifiers/LibZKPVerifier.sol";
 import { IProofVerifier } from "./IProofVerifier.sol";
 import { LibBytesUtils } from "../thirdparty/LibBytesUtils.sol";
 
-/// @custom:security-contact [email protected]
+/**
+ * @title ProofVerifier
+ * @dev Contract for verifying proofs in the rollup.
+ */
 contract ProofVerifier is EssentialContract, IProofVerifier {
     uint256[50] private __gap;
 
     error L1_INVALID_PROOF();
 
+    /**
+     * @notice Initializes the contract with the provided address manager.
+     * @param _addressManager The address of the address manager contract.
+     */
     function init(address _addressManager) external initializer {
         EssentialContract._init(_addressManager);
     }
 
     /**
-     * Verifying proofs
+     * @notice Verifies the provided proofs.
+     * @dev Throws an error if verification fails.
      *
-     * @param blockProofs Raw bytes of proof(s)
+     * @param blockProofs Raw bytes of proof(s).
+     * @param instance Hashed evidence & config data. If set to zero, proof is
+     * assumed to be from oracle/system prover.
      */
     function verifyProofs(
-        uint256, //Can be used later when supporting different types of proofs
+        uint256, /*blockId*/
         bytes calldata blockProofs,
         bytes32 instance
     )
         external
         view
     {
-        // Not checked if oracle/system prover
+        // If instance is zero, proof is considered as from oracle/system prover
+        // and not checked.
         if (instance == 0) return;
 
+        // Validate the instance using bytes utilities.
         if (
             !LibBytesUtils.equal(
                 LibBytesUtils.slice(blockProofs, 2, 32),
@@ -57,13 +69,18 @@ contract ProofVerifier is EssentialContract, IProofVerifier {
             revert L1_INVALID_PROOF();
         }
 
+        // Extract verifier ID from the proof.
         uint16 verifierId = uint16(bytes2(blockProofs[0:2]));
 
-        // Verify ZK proof
-        LibVerifyZKP.verifyProof(
+        // Delegate to the ZKP verifier library to validate the proof.
+        LibZKPVerifier.verifyProof(
             AddressResolver(address(this)), blockProofs[2:], verifierId
         );
     }
 }
 
+/**
+ * @title ProxiedProofVerifier
+ * @dev Proxied version of the ProofVerifier contract.
+ */
 contract ProxiedProofVerifier is Proxied, ProofVerifier { }
diff --git a/packages/protocol/contracts/L1/ProverPool.sol b/packages/protocol/contracts/L1/ProverPool.sol
@@ -83,16 +83,23 @@ contract ProverPool is EssentialContract, IProverPool {
         _;
     }
 
+    /**
+     * @notice Initializes the ProverPool contract.
+     * @param _addressManager Address of the contract that manages proxy
+     * addresses.
+     */
     function init(address _addressManager) external initializer {
         EssentialContract._init(_addressManager);
     }
 
-    /// @dev Protocol specifies the current feePerGas and assigns a prover to a
-    /// block.
-    /// @param blockId The block id.
-    /// @param feePerGas The current fee per gas.
-    /// @return prover The address of the assigned prover.
-    /// @return rewardPerGas The reward per gas for the assigned prover.
+    /**
+     * @notice Protocol specifies the current feePerGas and assigns a prover to
+     * a block.
+     * @param blockId The block id.
+     * @param feePerGas The current fee per gas.
+     * @return prover The address of the assigned prover.
+     * @return rewardPerGas The reward per gas for the assigned prover.
+     */
     function assignProver(
         uint64 blockId,
         uint32 feePerGas
@@ -119,9 +126,11 @@ contract ProverPool is EssentialContract, IProverPool {
             }
         }
     }
+    /**
+     * @notice Increases the capacity of the prover by releasing a prover.
+     * @param addr The address of the prover to release.
+     */
 
-    /// @dev Increases the capacity of the prover by releasing a prover.
-    /// @param addr The address of the prover to release.
     function releaseProver(address addr) external onlyFromProtocol {
         (Staker memory staker, Prover memory prover) = getStaker(addr);
 
@@ -133,8 +142,12 @@ contract ProverPool is EssentialContract, IProverPool {
         }
     }
 
-    /// @dev Slashes a prover.
-    /// @param addr The address of the prover to slash.
+    /**
+     * @notice Slashes a prover.
+     * @param addr The address of the prover to slash.
+     * @param blockId The block id of the slashing event.
+     * @param proofReward The reward for providing the proof.
+     */
     function slashProver(
         uint64 blockId,
         address addr,
@@ -176,15 +189,12 @@ contract ProverPool is EssentialContract, IProverPool {
         }
     }
 
-    /// @notice This function is used for a staker to stake tokens for a prover.
-    /// It will also perform the logic of updating the prover's rank, possibly
-    /// moving it into the active prover pool.
-    /// @param amount The amount of Taiko tokens to stake.
-    /// @param rewardPerGas The expected reward per gas for the prover. If the
-    /// expected reward is higher (implying that the prover is less efficient),
-    /// the prover will be ranked lower.
-    /// @param maxCapacity The maximum number of blocks that a prover can
-    /// handle.
+    /**
+     * @notice Stakes tokens for a prover in the pool.
+     * @param amount The amount of Taiko tokens to stake.
+     * @param rewardPerGas The expected reward per gas for the prover.
+     * @param maxCapacity The maximum number of blocks that a prover can handle.
+     */
     function stake(
         uint64 amount,
         uint32 rewardPerGas,
@@ -205,24 +215,29 @@ contract ProverPool is EssentialContract, IProverPool {
         }
     }
 
-    /// @notice Request an exit for the staker. This will withdraw the staked
-    /// tokens and exit
-    /// prover from the pool.
+    /**
+     * @notice Request an exit for the staker. This will withdraw the staked
+     * tokens and exit the prover from the pool.
+     */
     function exit() external nonReentrant {
         _withdraw(msg.sender);
         _exit(msg.sender, true);
     }
 
-    /// @notice Withdraws staked tokens back from matured an exit.
+    /**
+     * @notice Withdraws staked tokens back from a matured exit.
+     */
     function withdraw() external nonReentrant {
         if (!_withdraw(msg.sender)) revert NO_MATURE_EXIT();
     }
 
-    /// @notice Retrieves the information of a staker and their corresponding
-    /// prover using their address.
-    /// @param addr The address of the staker.
-    /// @return staker The staker's information.
-    /// @return prover The prover's information.
+    /**
+     * @notice Retrieves the information of a staker and their corresponding
+     * prover using their address.
+     * @param addr The address of the staker.
+     * @return staker The staker's information.
+     * @return prover The prover's information.
+     */
     function getStaker(address addr)
         public
         view
@@ -236,8 +251,10 @@ contract ProverPool is EssentialContract, IProverPool {
         }
     }
 
-    /// @notice Calculates and returns the current total capacity of the pool.
-    /// @return capacity The total capacity of the pool.
+    /**
+     * @notice Calculates and returns the current total capacity of the pool.
+     * @return capacity The total capacity of the pool.
+     */
     function getCapacity() public view returns (uint256 capacity) {
         unchecked {
             for (uint256 i = 1; i <= MAX_NUM_PROVERS; ++i) {
@@ -246,10 +263,12 @@ contract ProverPool is EssentialContract, IProverPool {
         }
     }
 
-    /// @notice Retreives the current active provers and their corresponding
-    /// stakers.
-    /// @return _provers The active provers.
-    /// @return _stakers The stakers of the active provers.
+    /**
+     * @notice Retrieves the current active provers and their corresponding
+     * stakers.
+     * @return _provers The active provers.
+     * @return _stakers The stakers of the active provers.
+     */
     function getProvers()
         public
         view
@@ -263,16 +282,13 @@ contract ProverPool is EssentialContract, IProverPool {
         }
     }
 
-    /// @notice Returns the current active provers and their weights. The weight
-    /// is dependent on the:
-    /// 1. The prover's amount staked.
-    /// 2. The prover's current capacity.
-    /// 3. The prover's expected reward per gas.
-    /// 4. The protocol's current fee per gas.
-    /// @param feePerGas The protocol's current fee per gas.
-    /// @return weights The weights of the current provers in the pool.
-    /// @return erpg The effective reward per gas of the current provers in the
-    /// pool. This is smoothed out to be in range of the current fee per gas.
+    /**
+     * @notice Returns the current active provers and their weights.
+     * @param feePerGas The protocol's current fee per gas.
+     * @return weights The weights of the current provers in the pool.
+     * @return erpg The effective reward per gas of the current provers in the
+     * pool. This is smoothed out to be in range of the current fee per gas.
+     */
     function getProverWeights(uint32 feePerGas)
         public
         view
@@ -424,15 +440,13 @@ contract ProverPool is EssentialContract, IProverPool {
         pure
         returns (uint64 weight)
     {
-        unchecked {
-            if (rewardPerGas == 0) {
-                return 0;
-            }
+        if (rewardPerGas == 0) {
+            return 0;
+        }
 
-            weight = stakedAmount / rewardPerGas / rewardPerGas;
-            if (weight == 0) {
-                weight = 1;
-            }
+        weight = stakedAmount / rewardPerGas / rewardPerGas;
+        if (weight == 0) {
+            weight = 1;
         }
     }
 
@@ -464,4 +478,8 @@ contract ProverPool is EssentialContract, IProverPool {
     }
 }
 
+/**
+ * @title ProxiedProverPool
+ * @dev Proxied version of the ProverPool contract.
+ */
 contract ProxiedProverPool is Proxied, ProverPool { }