Natspec legacy contracts update (#3799)

* Add natspec params and returns where missing

* Improved natspec

* remove space

Co-authored-by: Casper Belier <casper@blocklab.nl;casperbelier@hotmail.com>
Co-authored-by: Mark Tyneway <mark.tyneway@gmail.com>

packages/contracts/contracts/L1/rollup/CanonicalTransactionChain.sol

@@ -96,6 +96,8 @@ contract CanonicalTransactionChain is ICanonicalTransactionChain, Lib_AddressRes
     /**
      * Allows the Burn Admin to update the parameters which determine the amount of gas to burn.
      * The value of enqueueL2GasPrepaid is immediately updated as well.
+     * @param _l2GasDiscountDivisor The ratio of the cost of L1 gas to the cost of L2 gas
+     * @param _enqueueGasCost The approximate cost of calling the enqueue function
      */
     function setGasParams(uint256 _l2GasDiscountDivisor, uint256 _enqueueGasCost)
         external
@@ -416,6 +418,8 @@ contract CanonicalTransactionChain is ICanonicalTransactionChain, Lib_AddressRes
      * Parses the batch context from the extra data.
      * @return Total number of elements submitted.
      * @return Index of the next queue element.
+     * @return Timestamp for the last transaction
+     * @return Block number for the last transaction.
      */
     function _getBatchExtraData()
         internal

packages/contracts/contracts/L1/rollup/IStateCommitmentChain.sol

@@ -62,6 +62,7 @@ interface IStateCommitmentChain {
      * @param _element Hash of the element to verify a proof for.
      * @param _batchHeader Header of the batch in which the element was included.
      * @param _proof Merkle inclusion proof for the element.
+     * @return _verified Whether or not the batch inclusion proof is verified.
      */
     function verifyStateCommitment(
         bytes32 _element,

packages/contracts/contracts/L1/rollup/StateCommitmentChain.sol

@@ -34,6 +34,8 @@ contract StateCommitmentChain is IStateCommitmentChain, Lib_AddressResolver {
 
     /**
      * @param _libAddressManager Address of the Address Manager.
+     * @param _fraudProofWindow Number of seconds until fraud proof is in the finalized state.
+     * @param _sequencerPublishWindow Number of seconds that the sequencer is exclusively allowed to post state roots.
      */
     constructor(
         address _libAddressManager,

packages/contracts/contracts/L1/verification/BondManager.sol

@@ -20,10 +20,7 @@ contract BondManager is IBondManager, Lib_AddressResolver {
     constructor(address _libAddressManager) Lib_AddressResolver(_libAddressManager) {}
 
     /**
-     * Checks whether a given address is properly collateralized and can perform actions within
-     * the system.
-     * @param _who Address to check.
-     * @return true if the address is properly collateralized, false otherwise.
+     * @inheritdoc IBondManager
      */
     // slither-disable-next-line external-function
     function isCollateralized(address _who) public view returns (bool) {

packages/contracts/contracts/L1/verification/IBondManager.sol

@@ -9,5 +9,11 @@ interface IBondManager {
      * Public Functions *
      ********************/
 
+    /**
+     * Checks whether a given address is properly collateralized and can perform actions within
+     * the system.
+     * @param _who Address to check.
+     * @return true if the address is properly collateralized, false otherwise.
+     */
     function isCollateralized(address _who) external view returns (bool);
 }

packages/contracts/contracts/L2/messaging/IL2ERC20Bridge.sol

@@ -50,7 +50,7 @@ interface IL2ERC20Bridge {
      * @dev initiate a withdraw of some tokens to the caller's account on L1
      * @param _l2Token Address of L2 token where withdrawal was initiated.
      * @param _amount Amount of the token to withdraw.
-     * param _l1Gas Unused, but included for potential forward compatibility considerations.
+     * @param _l1Gas Unused, but included for potential forward compatibility considerations.
      * @param _data Optional data to forward to L1. This data is provided
      *        solely as a convenience for external contracts. Aside from enforcing a maximum
      *        length, these contracts provide no guarantees about its content.
@@ -67,7 +67,7 @@ interface IL2ERC20Bridge {
      * @param _l2Token Address of L2 token where withdrawal is initiated.
      * @param _to L1 adress to credit the withdrawal to.
      * @param _amount Amount of the token to withdraw.
-     * param _l1Gas Unused, but included for potential forward compatibility considerations.
+     * @param _l1Gas Unused, but included for potential forward compatibility considerations.
      * @param _data Optional data to forward to L1. This data is provided
      *        solely as a convenience for external contracts. Aside from enforcing a maximum
      *        length, these contracts provide no guarantees about its content.

packages/contracts/contracts/L2/messaging/L2CrossDomainMessenger.sol

@@ -33,6 +33,9 @@ contract L2CrossDomainMessenger is IL2CrossDomainMessenger {
      * Constructor *
      ***************/
 
+    /**
+     * @param _l1CrossDomainMessenger Address of the L1 CrossDomainMessenger
+     */
     constructor(address _l1CrossDomainMessenger) {
         l1CrossDomainMessenger = _l1CrossDomainMessenger;
     }

packages/contracts/contracts/L2/predeploys/OVM_L2ToL1MessagePasser.sol

@@ -23,8 +23,7 @@ contract OVM_L2ToL1MessagePasser is iOVM_L2ToL1MessagePasser {
      ********************/
 
     /**
-     * Passes a message to L1.
-     * @param _message Message to pass to L1.
+     * @inheritdoc iOVM_L2ToL1MessagePasser
      */
     // slither-disable-next-line external-function
     function passMessageToL1(bytes memory _message) public {

packages/contracts/contracts/L2/predeploys/iOVM_L1BlockNumber.sol

@@ -9,5 +9,8 @@ interface iOVM_L1BlockNumber {
      * Public Functions *
      ********************/
 
+    /**
+     * @return Block number of L1
+     */
     function getL1BlockNumber() external view returns (uint256);
 }

packages/contracts/contracts/L2/predeploys/iOVM_L2ToL1MessagePasser.sol

@@ -15,5 +15,9 @@ interface iOVM_L2ToL1MessagePasser {
      * Public Functions *
      ********************/
 
+    /**
+     * Passes a message to L1.
+     * @param _message Message to pass to L1.
+     */
     function passMessageToL1(bytes calldata _message) external;
 }