style(ctb): clean up legacy comments and errs (#2953)

Cleans up comments and errors for legacy contracts. It's fine to update
the bytecode for these legacy contracts since we're really only using
them for their interfaces.

.changeset/lazy-kiwis-jog.md

+---
+'@eth-optimism/contracts-bedrock': patch
+---
+
+Clean up comments and errors for legacy contracts

packages/contracts-bedrock/.gas-snapshot

@@ -4,7 +4,7 @@ GasBenchMark_L1StandardBridge_Deposit:test_depositERC20_benchmark_0() (gas: 2518
 GasBenchMark_L1StandardBridge_Deposit:test_depositERC20_benchmark_1() (gas: 118133)
 GasBenchMark_L1StandardBridge_Deposit:test_depositETH_benchmark_0() (gas: 251901)
 GasBenchMark_L1StandardBridge_Deposit:test_depositETH_benchmark_1() (gas: 118108)
-GasBenchMark_L1StandardBridge_Finalize:test_finalizeETHWithdrawal_benchmark() (gas: 45374)
+GasBenchMark_L1StandardBridge_Finalize:test_finalizeETHWithdrawal_benchmark() (gas: 45385)
 GasBenchMark_L2OutputOracle:test_appendL2Output_benchmark() (gas: 68684)
 GasBenchMark_OptimismPortal:test_depositTransaction_benchmark() (gas: 75024)
 GasBenchMark_OptimismPortal:test_depositTransaction_benchmark_1() (gas: 35328)
@@ -45,18 +45,18 @@ L1CrossDomainMessenger_Test:test_L1MessengerTwiceSendMessage() (gas: 1275622)
 L1CrossDomainMessenger_Test:test_L1MessengerUnpause() (gas: 40924)
 L1CrossDomainMessenger_Test:test_L1MessengerXDomainSenderReverts() (gas: 24250)
 L1CrossDomainMessenger_Test:test_L1MessengerxDomainMessageSenderResets() (gas: 88950)
-L1StandardBridge_Test:test_depositERC20() (gas: 476982)
-L1StandardBridge_Test:test_depositERC20To() (gas: 479186)
+L1StandardBridge_Test:test_depositERC20() (gas: 476993)
+L1StandardBridge_Test:test_depositERC20To() (gas: 479197)
 L1StandardBridge_Test:test_depositETH() (gas: 270949)
 L1StandardBridge_Test:test_depositETHTo() (gas: 228771)
-L1StandardBridge_Test:test_finalizeERC20Withdrawal() (gas: 490577)
-L1StandardBridge_Test:test_finalizeETHWithdrawal() (gas: 64061)
-L1StandardBridge_Test:test_initialize() (gas: 26225)
-L1StandardBridge_Test:test_onlyEOADepositERC20() (gas: 22329)
+L1StandardBridge_Test:test_finalizeERC20Withdrawal() (gas: 490595)
+L1StandardBridge_Test:test_finalizeETHWithdrawal() (gas: 64116)
+L1StandardBridge_Test:test_initialize() (gas: 26236)
+L1StandardBridge_Test:test_onlyEOADepositERC20() (gas: 22340)
 L1StandardBridge_Test:test_onlyEOADepositETH() (gas: 40882)
-L1StandardBridge_Test:test_onlyL2BridgeFinalizeERC20Withdrawal() (gas: 36114)
-L1StandardBridge_Test:test_onlyPortalFinalizeERC20Withdrawal() (gas: 35478)
-L1StandardBridge_Test:test_receive() (gas: 415514)
+L1StandardBridge_Test:test_onlyL2BridgeFinalizeERC20Withdrawal() (gas: 36136)
+L1StandardBridge_Test:test_onlyPortalFinalizeERC20Withdrawal() (gas: 35489)
+L1StandardBridge_Test:test_receive() (gas: 415529)
 L2CrossDomainMessenger_Test:testCannot_L2MessengerPause() (gas: 10821)
 L2CrossDomainMessenger_Test:test_L2MessengerMessageVersion() (gas: 8388)
 L2CrossDomainMessenger_Test:test_L2MessengerPause() (gas: 31815)
@@ -159,7 +159,7 @@ ProxyAdmin_Test:test_chugsplashChangeProxyAdmin() (gas: 35647)
 ProxyAdmin_Test:test_chugsplashGetProxyAdmin() (gas: 15689)
 ProxyAdmin_Test:test_chugsplashGetProxyImplementation() (gas: 51167)
 ProxyAdmin_Test:test_chugsplashUpgrade() (gas: 48972)
-ProxyAdmin_Test:test_chugsplashUpgradeAndCall() (gas: 82334)
+ProxyAdmin_Test:test_chugsplashUpgradeAndCall() (gas: 82345)
 ProxyAdmin_Test:test_delegateResolvedChangeProxyAdmin() (gas: 34020)
 ProxyAdmin_Test:test_delegateResolvedGetProxyAdmin() (gas: 17708)
 ProxyAdmin_Test:test_delegateResolvedGetProxyImplementation() (gas: 62016)

packages/contracts-bedrock/contracts/L1/L2OutputOracle.sol

-//SPDX-License-Identifier: MIT
+// SPDX-License-Identifier: MIT
 pragma solidity 0.8.10;
 
 import {

packages/contracts-bedrock/contracts/L1/OptimismPortal.sol

-//SPDX-License-Identifier: MIT
+// SPDX-License-Identifier: MIT
 pragma solidity 0.8.10;
 
 import { Initializable } from "@openzeppelin/contracts/proxy/utils/Initializable.sol";

packages/contracts-bedrock/contracts/L2/L1Block.sol

-//SPDX-License-Identifier: MIT
+// SPDX-License-Identifier: MIT
 pragma solidity 0.8.10;
 
 /**

packages/contracts-bedrock/contracts/L2/L1BlockNumber.sol

-//SPDX-License-Identifier: MIT
+// SPDX-License-Identifier: MIT
 pragma solidity 0.8.10;
 
 import { L1Block } from "./L1Block.sol";

packages/contracts-bedrock/contracts/L2/SequencerFeeVault.sol

 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.9;
 
-/* Library Imports */
 import { PredeployAddresses } from "../libraries/PredeployAddresses.sol";
-
-/* Contract Imports */
 import { L2StandardBridge } from "./L2StandardBridge.sol";
 
 /**

packages/contracts-bedrock/contracts/legacy/AddressManager.sol

 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.9;
 
-/* External Imports */
 import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
 
 /**
+ * @custom:legacy
  * @title AddressManager
+ * @notice AddressManager is a legacy contract that was used in the old version of the Optimism
+ *         system to manage a registry of string names to addresses. We now use a more standard
+ *         proxy system instead, but this contract is still necessary for backwards compatibility
+ *         with several older contracts.
  */
 contract AddressManager is Ownable {
-    /**********
-     * Events *
-     **********/
-
+    /**
+     * @notice Emitted when an address is modified in the registry.
+     *
+     * @param name       String name being set in the registry.
+     * @param newAddress Address set for the given name.
+     * @param oldAddress Address that was previously set for the given name.
+     */
     event AddressSet(string indexed name, address newAddress, address oldAddress);
 
-    /*************
-     * Variables *
-     *************/
-
+    /**
+     * @notice Mapping of the hashes of string names to addresses.
+     */
     mapping(bytes32 => address) private addresses;
 
-    /********************
-     * Public Functions *
-     ********************/
-
     /**
-     * Changes the address associated with a particular name.
-     * @param _name String name to associate an address with.
+     * @notice Changes the address associated with a particular name.
+     *
+     * @param _name    String name to associate an address with.
      * @param _address Address to associate with the name.
      */
     function setAddress(string memory _name, address _address) external onlyOwner {
@@ -38,21 +41,21 @@ contract AddressManager is Ownable {
     }
 
     /**
-     * Retrieves the address associated with a given name.
+     * @notice Retrieves the address associated with a given name.
+     *
      * @param _name Name to retrieve an address for.
+     *
      * @return Address associated with the given name.
      */
     function getAddress(string memory _name) external view returns (address) {
         return addresses[_getNameHash(_name)];
     }
 
-    /**********************
-     * Internal Functions *
-     **********************/
-
     /**
-     * Computes the hash of a name.
+     * @notice Computes the hash of a name.
+     *
      * @param _name Name to compute a hash for.
+     *
      * @return Hash of the given name.
      */
     function _getNameHash(string memory _name) internal pure returns (bytes32) {

packages/contracts-bedrock/contracts/legacy/AddressResolver.sol

-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.9;
-
-/* Library Imports */
-import { AddressManager } from "./AddressManager.sol";
-
-/**
- * @title AddressResolver
- */
-abstract contract AddressResolver {
-    /*************
-     * Variables *
-     *************/
-
-    AddressManager public libAddressManager;
-
-    /***************
-     * Constructor *
-     ***************/
-
-    /**
-     * @param _libAddressManager Address of the AddressManager.
-     */
-    constructor(address _libAddressManager) {
-        libAddressManager = AddressManager(_libAddressManager);
-    }
-
-    /********************
-     * Public Functions *
-     ********************/
-
-    /**
-     * Resolves the address associated with a given name.
-     * @param _name Name to resolve an address for.
-     * @return Address associated with the given name.
-     */
-    function resolve(string memory _name) public view returns (address) {
-        return libAddressManager.getAddress(_name);
-    }
-}

packages/contracts-bedrock/contracts/legacy/LegacyERC20ETH.sol

 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.9;
+pragma solidity 0.8.10;
 
-/* Library Imports */
 import { PredeployAddresses } from "../libraries/PredeployAddresses.sol";
-
-/* Contract Imports */
 import { OptimismMintableERC20 } from "../universal/OptimismMintableERC20.sol";
 
 /**

packages/contracts-bedrock/contracts/legacy/ResolvedDelegateProxy.sol

@@ -4,47 +4,48 @@ pragma solidity ^0.8.9;
 import { AddressManager } from "./AddressManager.sol";
 
 /**
+ * @custom:legacy
  * @title ResolvedDelegateProxy
+ * @notice ResolvedDelegateProxy is a legacy proxy contract that makes use of the AddressManager to
+ *         resolve the implementation address. We're maintaining this contract for backwards
+ *         compatibility so we can manage all legacy proxies where necessary.
  */
 contract ResolvedDelegateProxy {
-    /*************
-     * Variables *
-     *************/
-
-    // Using mappings to store fields to avoid overwriting storage slots in the
-    // implementation contract. For example, instead of storing these fields at
-    // storage slot `0` & `1`, they are stored at `keccak256(key + slot)`.
-    // See: https://solidity.readthedocs.io/en/v0.7.0/internals/layout_in_storage.html
-    // NOTE: Do not use this code in your own contract system.
-    //      There is a known flaw in this contract, and we will remove it from the repository
-    //      in the near future. Due to the very limited way that we are using it, this flaw is
-    //      not an issue in our system.
+    /**
+     * @notice Mapping used to store the implementation name that corresponds to this contract. A
+     *         mapping was originally used as a way to bypass the same issue normally solved by
+     *         storing the implementation address in a specific storage slot that does not conflict
+     *         with any other storage slot. Generally NOT a safe solution but works as long as the
+     *         implementation does not also keep a mapping in the first storage slot.
+     */
     mapping(address => string) private implementationName;
-    mapping(address => AddressManager) private addressManager;
 
-    /***************
-     * Constructor *
-     ***************/
+    /**
+     * @notice Mapping used to store the address of the AddressManager contract where the
+     *         implementation address will be resolved from. Same concept here as with the above
+     *         mapping. Also generally unsafe but fine if the implementation doesn't keep a mapping
+     *         in the second storage slot.
+     */
+    mapping(address => AddressManager) private addressManager;
 
     /**
-     * @param _libAddressManager Address of the AddressManager.
+     * @param _addressManager  Address of the AddressManager.
      * @param _implementationName implementationName of the contract to proxy to.
      */
-    constructor(address _libAddressManager, string memory _implementationName) {
-        addressManager[address(this)] = AddressManager(_libAddressManager);
+    constructor(AddressManager _addressManager, string memory _implementationName) {
+        addressManager[address(this)] = _addressManager;
         implementationName[address(this)] = _implementationName;
     }
 
-    /*********************
-     * Fallback Function *
-     *********************/
-
+    /**
+     * @notice Fallback, performs a delegatecall to the resolved implementation address.
+     */
     fallback() external payable {
         address target = addressManager[address(this)].getAddress(
             (implementationName[address(this)])
         );
 
-        require(target != address(0), "Target address must be initialized.");
+        require(target != address(0), "ResolvedDelegateProxy: target address must be initialized");
 
         // slither-disable-next-line controlled-delegatecall
         (bool success, bytes memory returndata) = target.delegatecall(msg.data);

packages/contracts-bedrock/contracts/libraries/Burn.sol

@@ -4,7 +4,8 @@ pragma solidity 0.8.10;
 /**
  * @title Burner
  * @notice Burner self-destructs on creation and sends all ETH to itself, removing all ETH given to
- * the contract from the circulating supply.
+ *         the contract from the circulating supply. Self-destructing is the only way to remove ETH
+ *         from the circulating supply.
  */
 contract Burner {
     constructor() payable {

packages/contracts-bedrock/contracts/test/CommonTest.t.sol

@@ -186,7 +186,7 @@ contract Messenger_Initializer is L2OutputOracle_Initializer {
         vm.prank(multisig);
         addressManager.setAddress("OVM_L1CrossDomainMessenger", address(L1MessengerImpl));
         ResolvedDelegateProxy proxy = new ResolvedDelegateProxy(
-            address(addressManager),
+            addressManager,
             "OVM_L1CrossDomainMessenger"
         );
         L1Messenger = L1CrossDomainMessenger(address(proxy));

packages/contracts-bedrock/contracts/test/ProxyAdmin.t.sol

@@ -38,7 +38,7 @@ contract ProxyAdmin_Test is Test {
         // Deploy a legacy ResolvedDelegateProxy with the name `a`.
         // Whatever `a` is set to in AddressManager will be the address
         // that is used for the implementation.
-        resolved = new ResolvedDelegateProxy(address(addressManager), "a");
+        resolved = new ResolvedDelegateProxy(addressManager, "a");
 
         // Impersonate alice for setting up the admin.
         vm.startPrank(alice);