Merge branch 'main' into dependabot/npm_and_yarn/vitest/coverage-v8-1…

….3.1
taikoxyz · Feb 29, 2024 · a3afbe2 · a3afbe2
2 parents d10962c + b0ce62e
commit a3afbe2
Show file tree

Hide file tree

Showing 127 changed files with 2,893 additions and 3,075 deletions.
diff --git a/.github/workflows/protocol.yml b/.github/workflows/protocol.yml
@@ -25,7 +25,9 @@ jobs:
 
       - name: Install Foundry
         uses: foundry-rs/foundry-toolchain@v1
-
+        with:
+          version: nightly-85b4872377bf85c3180e49956a82fded49daff10
+
       - name: Install pnpm dependencies
         uses: ./.github/actions/install-pnpm-dependencies
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -29,26 +29,53 @@ Because we squash all of the changes into a single commit, please try to keep th
 
 For example, `feat(scope): description of feature` should only impact the `scope` package. If your change is a global one, you can use `feat: description of feature`, for example.
 
-### Source code comments
+### Source code comments (NatSpec)
 
 Follow the [NatSpec format](https://docs.soliditylang.org/en/latest/natspec-format.html) for documenting smart contract source code. Please adhere to a few additional standards:
 
+#### Contract header
+
+All contracts should have at the top, and nothing else (minimum viable documentation):
+
+```
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.24;
+```
+
+All contracts should have, preceding their declaration, at minimum:
+
+```
+/// @title A title
+/// @custom:security-contact [email protected]
+```
+
+#### Single tag
+
+Always use a single tag, for example do not do this:
+
+```
+/// @dev Here is a dev comment.
+/// @dev Here is another dev comment.
+```
+
+Instead, combine them into a single comment.
+
 #### Comment style
 
 Choose `///` over `/** */` for multi-line NatSpec comments for consistency. All NatSpec comments should use `///` instead of `/** */`. Additional explanatory comments should use `//`, even for multi-line comments.
 
 #### Notice tag
 
-Omit the usage of `@notice` and let the compiler automatically pick it up to save column space. For example, this:
+Explicitly use `@notice`, don't let the compiler pick it up automatically:
 
 ```
-/// @notice This is a notice.
+/// This is a notice.
 ```
 
 becomes this:
 
 ```
-/// This is a notice.
+/// @notice This is a notice.
 ```
 
 #### Annotation indentation
@@ -166,9 +193,50 @@ 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. Thus, you should mention a statement like so:
+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:
 
 ```solidity
 /// @notice See the documentation in {IProverPool}

diff --git a/packages/protocol/audit/quill_audits_taiko_smart_contract_audit_report.pdf b/packages/protocol/audit/quill_audits_taiko_smart_contract_audit_report.pdf
diff --git a/packages/protocol/contracts/L1/ITaikoL1.sol b/packages/protocol/contracts/L1/ITaikoL1.sol
@@ -1,48 +1,34 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 import "./TaikoData.sol";
 
+/// @title ITaikoL1
+/// @custom:security-contact [email protected]
 interface ITaikoL1 {
     /// @notice Proposes a Taiko L2 block.
-    /// @param params Block parameters, currently an encoded BlockParams object.
-    /// @param txList txList data if calldata is used for DA.
-    /// @return meta The metadata of the proposed L2 block.
-    /// @return depositsProcessed The Ether deposits processed.
+    /// @param _params Block parameters, currently an encoded BlockParams object.
+    /// @param _txList txList data if calldata is used for DA.
+    /// @return meta_ The metadata of the proposed L2 block.
+    /// @return deposits_ The Ether deposits processed.
     function proposeBlock(
-        bytes calldata params,
-        bytes calldata txList
+        bytes calldata _params,
+        bytes calldata _txList
     )
         external
         payable
-        returns (
-            TaikoData.BlockMetadata memory meta,
-            TaikoData.EthDeposit[] memory depositsProcessed
-        );
+        returns (TaikoData.BlockMetadata memory meta_, TaikoData.EthDeposit[] memory deposits_);
 
     /// @notice Proves or contests a block transition.
-    /// @param blockId The index of the block to prove. This is also used to
+    /// @param _blockId The index of the block to prove. This is also used to
     /// select the right implementation version.
-    /// @param input An abi-encoded (BlockMetadata, Transition, TierProof)
-    /// tuple.
-    function proveBlock(uint64 blockId, bytes calldata input) external;
+    /// @param _input An abi-encoded (TaikoData.BlockMetadata, TaikoData.Transition,
+    /// TaikoData.TierProof) tuple.
+    function proveBlock(uint64 _blockId, bytes calldata _input) external;
 
     /// @notice Verifies up to a certain number of blocks.
-    /// @param maxBlocksToVerify Max number of blocks to verify.
-    function verifyBlocks(uint64 maxBlocksToVerify) external;
+    /// @param _maxBlocksToVerify Max number of blocks to verify.
+    function verifyBlocks(uint64 _maxBlocksToVerify) external;
 
     /// @notice Gets the configuration of the TaikoL1 contract.
     /// @return Config struct containing configuration parameters.

diff --git a/packages/protocol/contracts/L1/TaikoData.sol b/packages/protocol/contracts/L1/TaikoData.sol
@@ -1,22 +1,10 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 /// @title TaikoData
 /// @notice This library defines various data structures used in the Taiko
 /// protocol.
+/// @custom:security-contact [email protected]
 library TaikoData {
     /// @dev Struct holding Taiko configuration parameters. See {TaikoConfig}.
     struct Config {
@@ -190,16 +178,16 @@ library TaikoData {
     /// @dev Struct holding the state variables for the {TaikoL1} contract.
     struct State {
         // Ring buffer for proposed blocks and a some recent verified blocks.
-        mapping(uint64 blockId_mod_blockRingBufferSize => Block) blocks;
+        mapping(uint64 blockId_mod_blockRingBufferSize => Block blk) blocks;
         // Indexing to transition ids (ring buffer not possible)
         mapping(uint64 blockId => mapping(bytes32 parentHash => uint32 transitionId)) transitionIds;
         // Ring buffer for transitions
         mapping(
             uint64 blockId_mod_blockRingBufferSize
-                => mapping(uint32 transitionId => TransitionState)
+                => mapping(uint32 transitionId => TransitionState ts)
             ) transitions;
         // Ring buffer for Ether deposits
-        mapping(uint256 depositId_mod_ethDepositRingBufferSize => uint256) ethDeposits;
+        mapping(uint256 depositId_mod_ethDepositRingBufferSize => uint256 depositAmount) ethDeposits;
         // Reusable blobs
         mapping(bytes32 blobHash => uint256 since) reusableBlobs;
         SlotA slotA; // slot 6

diff --git a/packages/protocol/contracts/L1/TaikoErrors.sol b/packages/protocol/contracts/L1/TaikoErrors.sol
@@ -1,43 +1,28 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 /// @title TaikoErrors
-/// @notice This abstract contract provides custom error declartions used in
+/// @notice This abstract contract provides custom error declarations used in
 /// the Taiko protocol. Each error corresponds to specific situations where
 /// exceptions might be thrown.
+/// @dev The errors defined here must match the definitions in the corresponding
+/// L1 libraries.
+/// @custom:security-contact [email protected]
 abstract contract TaikoErrors {
-    // NOTE: The following custom errors must match the definitions in
-    // `L1/libs/*.sol`.
     error L1_ALREADY_CONTESTED();
     error L1_ALREADY_PROVED();
     error L1_ASSIGNED_PROVER_NOT_ALLOWED();
     error L1_BLOB_FOR_DA_DISABLED();
     error L1_BLOB_NOT_FOUND();
     error L1_BLOB_NOT_REUSEABLE();
-    error L1_BLOB_NOT_USED();
     error L1_BLOB_REUSE_DISALBED();
     error L1_BLOCK_MISMATCH();
-    error L1_CHAIN_DATA_NOT_RELAYED();
     error L1_INVALID_BLOCK_ID();
     error L1_INVALID_CONFIG();
     error L1_INVALID_ETH_DEPOSIT();
     error L1_INVALID_HOOK();
     error L1_INVALID_PARAM();
     error L1_INVALID_PAUSE_STATUS();
-    error L1_INVALID_PROOF();
     error L1_INVALID_PROVER();
     error L1_INVALID_TIER();
     error L1_INVALID_TRANSITION();
@@ -55,5 +40,4 @@ abstract contract TaikoErrors {
     error L1_UNAUTHORIZED();
     error L1_UNEXPECTED_PARENT();
     error L1_UNEXPECTED_TRANSITION_ID();
-    error L1_UNEXPECTED_TRANSITION_TIER();
 }
diff --git a/packages/protocol/contracts/L1/TaikoEvents.sol b/packages/protocol/contracts/L1/TaikoEvents.sol
@@ -1,17 +1,4 @@
 // SPDX-License-Identifier: MIT
-//  _____     _ _         _         _
-// |_   _|_ _(_) |_____  | |   __ _| |__ ___
-//   | |/ _` | | / / _ \ | |__/ _` | '_ (_-<
-//   |_|\__,_|_|_\_\___/ |____\__,_|_.__/__/
-//
-//   Email: [email protected]
-//   Website: https://taiko.xyz
-//   GitHub: https://github.com/taikoxyz
-//   Discord: https://discord.gg/taikoxyz
-//   Twitter: https://twitter.com/taikoxyz
-//   Blog: https://mirror.xyz/labs.taiko.eth
-//   Youtube: https://www.youtube.com/@taikoxyz
-
 pragma solidity 0.8.24;
 
 import "./TaikoData.sol";
@@ -22,6 +9,7 @@ import "./TaikoData.sol";
 /// Ethereum deposit processes.
 /// @dev The events defined here must match the definitions in the corresponding
 /// L1 libraries.
+/// @custom:security-contact [email protected]
 abstract contract TaikoEvents {
     /// @dev Emitted when a block is proposed.
     /// @param blockId The ID of the proposed block.
@@ -57,6 +45,11 @@ abstract contract TaikoEvents {
     );
 
     /// @dev Emitted when a block transition is proved or re-proved.
+    /// @param blockId The ID of the proven block.
+    /// @param tran The verified transition.
+    /// @param prover The prover address.
+    /// @param validityBond The validity bond amount.
+    /// @param tier The tier ID of the proof.
     event TransitionProved(
         uint256 indexed blockId,
         TaikoData.Transition tran,
@@ -66,6 +59,11 @@ abstract contract TaikoEvents {
     );
 
     /// @dev Emitted when a block transition is contested.
+    /// @param blockId The ID of the proven block.
+    /// @param tran The verified transition.
+    /// @param contester The contester address.
+    /// @param contestBond The contesting bond amount.
+    /// @param tier The tier ID of the proof.
     event TransitionContested(
         uint256 indexed blockId,
         TaikoData.Transition tran,
@@ -75,9 +73,11 @@ abstract contract TaikoEvents {
     );
 
     /// @dev Emitted when a blob is cached for reuse.
+    /// @param blobHash The blobHash cached.
     event BlobCached(bytes32 blobHash);
 
     /// @dev Emitted when proving has been paused
+    /// @param paused True if paused, false if unpaused.
     event ProvingPaused(bool paused);
 
     /// @dev Emitted when an Ethereum deposit is made.