Merge pull request #6377 from ethereum-optimism/refcell/merkle-styling

fix(ctb): Port Merkle Libraries to Triple Slash Natspec Styling

packages/contracts-bedrock/.gas-snapshot

@@ -124,7 +124,7 @@ GasBenchMark_L1StandardBridge_Finalize:test_finalizeETHWithdrawal_benchmark() (g
 GasBenchMark_L2OutputOracle:test_proposeL2Output_benchmark() (gas: 88513)
 GasBenchMark_OptimismPortal:test_depositTransaction_benchmark() (gas: 75225)
 GasBenchMark_OptimismPortal:test_depositTransaction_benchmark_1() (gas: 75662)
-GasBenchMark_OptimismPortal:test_proveWithdrawalTransaction_benchmark() (gas: 143087)
+GasBenchMark_OptimismPortal:test_proveWithdrawalTransaction_benchmark() (gas: 143066)
 GasPriceOracle_Test:test_baseFee_succeeds() (gas: 8325)
 GasPriceOracle_Test:test_decimals_succeeds() (gas: 6167)
 GasPriceOracle_Test:test_gasPrice_succeeds() (gas: 8294)
@@ -288,26 +288,26 @@ LegacyERC20ETH_Test:test_transferFrom_doesNotExist_reverts() (gas: 12957)
 LegacyERC20ETH_Test:test_transfer_doesNotExist_reverts() (gas: 10755)
 LegacyMessagePasser_Test:test_passMessageToL1_succeeds() (gas: 34524)
 LibPosition_Test:test_pos_correctness_succeeds() (gas: 38689)
-MerkleTrie_get_Test:test_get_corruptedProof_reverts() (gas: 5736)
-MerkleTrie_get_Test:test_get_extraProofElements_reverts() (gas: 58907)
-MerkleTrie_get_Test:test_get_invalidDataRemainder_reverts() (gas: 35848)
-MerkleTrie_get_Test:test_get_invalidInternalNodeHash_reverts() (gas: 49664)
-MerkleTrie_get_Test:test_get_nonexistentKey1_reverts() (gas: 54785)
-MerkleTrie_get_Test:test_get_nonexistentKey2_reverts() (gas: 16709)
-MerkleTrie_get_Test:test_get_smallerPathThanKey1_reverts() (gas: 51418)
-MerkleTrie_get_Test:test_get_smallerPathThanKey2_reverts() (gas: 52899)
-MerkleTrie_get_Test:test_get_validProof10_succeeds() (gas: 48871)
-MerkleTrie_get_Test:test_get_validProof1_succeeds() (gas: 55996)
-MerkleTrie_get_Test:test_get_validProof2_succeeds() (gas: 65887)
-MerkleTrie_get_Test:test_get_validProof3_succeeds() (gas: 27330)
-MerkleTrie_get_Test:test_get_validProof4_succeeds() (gas: 18126)
-MerkleTrie_get_Test:test_get_validProof5_succeeds() (gas: 80722)
-MerkleTrie_get_Test:test_get_validProof6_succeeds() (gas: 69481)
-MerkleTrie_get_Test:test_get_validProof7_succeeds() (gas: 76179)
-MerkleTrie_get_Test:test_get_validProof8_succeeds() (gas: 48828)
-MerkleTrie_get_Test:test_get_validProof9_succeeds() (gas: 48828)
-MerkleTrie_get_Test:test_get_wrongKeyProof_reverts() (gas: 50740)
-MerkleTrie_get_Test:test_get_zeroBranchValueLength_reverts() (gas: 41697)
+MerkleTrie_get_Test:test_get_corruptedProof_reverts() (gas: 5733)
+MerkleTrie_get_Test:test_get_extraProofElements_reverts() (gas: 58889)
+MerkleTrie_get_Test:test_get_invalidDataRemainder_reverts() (gas: 35845)
+MerkleTrie_get_Test:test_get_invalidInternalNodeHash_reverts() (gas: 49654)
+MerkleTrie_get_Test:test_get_nonexistentKey1_reverts() (gas: 54770)
+MerkleTrie_get_Test:test_get_nonexistentKey2_reverts() (gas: 16699)
+MerkleTrie_get_Test:test_get_smallerPathThanKey1_reverts() (gas: 51403)
+MerkleTrie_get_Test:test_get_smallerPathThanKey2_reverts() (gas: 52884)
+MerkleTrie_get_Test:test_get_validProof10_succeeds() (gas: 48845)
+MerkleTrie_get_Test:test_get_validProof1_succeeds() (gas: 55970)
+MerkleTrie_get_Test:test_get_validProof2_succeeds() (gas: 65861)
+MerkleTrie_get_Test:test_get_validProof3_succeeds() (gas: 27309)
+MerkleTrie_get_Test:test_get_validProof4_succeeds() (gas: 18105)
+MerkleTrie_get_Test:test_get_validProof5_succeeds() (gas: 80701)
+MerkleTrie_get_Test:test_get_validProof6_succeeds() (gas: 69460)
+MerkleTrie_get_Test:test_get_validProof7_succeeds() (gas: 76158)
+MerkleTrie_get_Test:test_get_validProof8_succeeds() (gas: 48802)
+MerkleTrie_get_Test:test_get_validProof9_succeeds() (gas: 48802)
+MerkleTrie_get_Test:test_get_wrongKeyProof_reverts() (gas: 50730)
+MerkleTrie_get_Test:test_get_zeroBranchValueLength_reverts() (gas: 41684)
 MerkleTrie_get_Test:test_get_zeroLengthKey_reverts() (gas: 3632)
 MintManager_constructor_Test:test_constructor_succeeds() (gas: 10579)
 MintManager_mint_Test:test_mint_afterPeriodElapsed_succeeds() (gas: 148117)
@@ -346,26 +346,26 @@ OptimismPortalUpgradeable_Test:test_initialize_cannotInitImpl_reverts() (gas: 10
 OptimismPortalUpgradeable_Test:test_initialize_cannotInitProxy_reverts() (gas: 15918)
 OptimismPortalUpgradeable_Test:test_params_initValuesOnProxy_succeeds() (gas: 21774)
 OptimismPortalUpgradeable_Test:test_upgradeToAndCall_upgrading_succeeds() (gas: 180547)
-OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_ifOutputRootChanges_reverts() (gas: 177872)
-OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_ifOutputTimestampIsNotFinalized_reverts() (gas: 181325)
+OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_ifOutputRootChanges_reverts() (gas: 177851)
+OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_ifOutputTimestampIsNotFinalized_reverts() (gas: 181304)
 OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_ifWithdrawalNotProven_reverts() (gas: 41731)
-OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_ifWithdrawalProofNotOldEnough_reverts() (gas: 173269)
-OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_onInsufficientGas_reverts() (gas: 179698)
-OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_onRecentWithdrawal_reverts() (gas: 154034)
-OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_onReentrancy_reverts() (gas: 217673)
-OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_onReplay_reverts() (gas: 219411)
+OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_ifWithdrawalProofNotOldEnough_reverts() (gas: 173248)
+OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_onInsufficientGas_reverts() (gas: 179677)
+OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_onRecentWithdrawal_reverts() (gas: 154013)
+OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_onReentrancy_reverts() (gas: 217652)
+OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_onReplay_reverts() (gas: 219390)
 OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_paused_reverts() (gas: 53510)
-OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_provenWithdrawalHash_succeeds() (gas: 208846)
-OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_targetFails_fails() (gas: 8797746687696162660)
-OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_timestampLessThanL2OracleStart_reverts() (gas: 170847)
+OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_provenWithdrawalHash_succeeds() (gas: 208825)
+OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_targetFails_fails() (gas: 8797746687696162659)
+OptimismPortal_FinalizeWithdrawal_Test:test_finalizeWithdrawalTransaction_timestampLessThanL2OracleStart_reverts() (gas: 170826)
 OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_onInvalidOutputRootProof_reverts() (gas: 85690)
-OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_onInvalidWithdrawalProof_reverts() (gas: 111212)
+OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_onInvalidWithdrawalProof_reverts() (gas: 111202)
 OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_onSelfCall_reverts() (gas: 52947)
 OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_paused_reverts() (gas: 73673)
-OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_replayProveChangedOutputRootAndOutputIndex_succeeds() (gas: 294439)
-OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_replayProveChangedOutputRoot_succeeds() (gas: 227271)
-OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_replayProve_reverts() (gas: 166398)
-OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_validWithdrawalProof_succeeds() (gas: 154336)
+OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_replayProveChangedOutputRootAndOutputIndex_succeeds() (gas: 294397)
+OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_replayProveChangedOutputRoot_succeeds() (gas: 227229)
+OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_replayProve_reverts() (gas: 166377)
+OptimismPortal_FinalizeWithdrawal_Test:test_proveWithdrawalTransaction_validWithdrawalProof_succeeds() (gas: 154315)
 OptimismPortal_Test:test_constructor_succeeds() (gas: 19402)
 OptimismPortal_Test:test_depositTransaction_contractCreation_reverts() (gas: 14320)
 OptimismPortal_Test:test_depositTransaction_createWithZeroValueForContract_succeeds() (gas: 76791)

packages/contracts-bedrock/contracts/libraries/trie/SecureMerkleTrie.sol

 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/* Library Imports */
 import { MerkleTrie } from "./MerkleTrie.sol";
 
-/**
- * @title SecureMerkleTrie
- * @notice SecureMerkleTrie is a thin wrapper around the MerkleTrie library that hashes the input
- *         keys. Ethereum's state trie hashes input keys before storing them.
- */
+/// @title SecureMerkleTrie
+/// @notice SecureMerkleTrie is a thin wrapper around the MerkleTrie library that hashes the input
+///         keys. Ethereum's state trie hashes input keys before storing them.
 library SecureMerkleTrie {
-    /**
-     * @notice Verifies a proof that a given key/value pair is present in the Merkle trie.
-     *
-     * @param _key   Key of the node to search for, as a hex string.
-     * @param _value Value of the node to search for, as a hex string.
-     * @param _proof Merkle trie inclusion proof for the desired node. Unlike traditional Merkle
-     *               trees, this proof is executed top-down and consists of a list of RLP-encoded
-     *               nodes that make a path down to the target node.
-     * @param _root  Known root of the Merkle trie. Used to verify that the included proof is
-     *               correctly constructed.
-     *
-     * @return Whether or not the proof is valid.
-     */
+    /// @notice Verifies a proof that a given key/value pair is present in the Merkle trie.
+    /// @param _key   Key of the node to search for, as a hex string.
+    /// @param _value Value of the node to search for, as a hex string.
+    /// @param _proof Merkle trie inclusion proof for the desired node. Unlike traditional Merkle
+    ///               trees, this proof is executed top-down and consists of a list of RLP-encoded
+    ///               nodes that make a path down to the target node.
+    /// @param _root  Known root of the Merkle trie. Used to verify that the included proof is
+    ///               correctly constructed.
+    /// @return valid_ Whether or not the proof is valid.
     function verifyInclusionProof(
         bytes memory _key,
         bytes memory _value,
         bytes[] memory _proof,
         bytes32 _root
-    ) internal pure returns (bool) {
+    ) internal pure returns (bool valid_) {
         bytes memory key = _getSecureKey(_key);
-        return MerkleTrie.verifyInclusionProof(key, _value, _proof, _root);
+        valid_ = MerkleTrie.verifyInclusionProof(key, _value, _proof, _root);
     }
 
-    /**
-     * @notice Retrieves the value associated with a given key.
-     *
-     * @param _key   Key to search for, as hex bytes.
-     * @param _proof Merkle trie inclusion proof for the key.
-     * @param _root  Known root of the Merkle trie.
-     *
-     * @return Value of the key if it exists.
-     */
+    /// @notice Retrieves the value associated with a given key.
+    /// @param _key   Key to search for, as hex bytes.
+    /// @param _proof Merkle trie inclusion proof for the key.
+    /// @param _root  Known root of the Merkle trie.
+    /// @return value_ Value of the key if it exists.
     function get(
         bytes memory _key,
         bytes[] memory _proof,
         bytes32 _root
-    ) internal pure returns (bytes memory) {
+    ) internal pure returns (bytes memory value_) {
         bytes memory key = _getSecureKey(_key);
-        return MerkleTrie.get(key, _proof, _root);
+        value_ = MerkleTrie.get(key, _proof, _root);
     }
 
-    /**
-     * @notice Computes the hashed version of the input key.
-     *
-     * @param _key Key to hash.
-     *
-     * @return Hashed version of the key.
-     */
-    function _getSecureKey(bytes memory _key) private pure returns (bytes memory) {
-        return abi.encodePacked(keccak256(_key));
+    /// @notice Computes the hashed version of the input key.
+    /// @param _key Key to hash.
+    /// @return hash_ Hashed version of the key.
+    function _getSecureKey(bytes memory _key) private pure returns (bytes memory hash_) {
+        hash_ = abi.encodePacked(keccak256(_key));
     }
 }