Improving comments and some names (#211)

* Add missing interface function, and reorder funcs to match impl

* Replace '@inheritdoc' with actual docs

* Rename FraudContributor file with Abs prefix

* fix imports and interface visibility

* uncomment function to fix build process

* Update contracts/optimistic-ethereum/OVM/chain/OVM_CanonicalTransactionChain.sol

Co-authored-by: ben-chain <[email protected]>

* rename BaseCrossDomainManager to indicate abstract status

* fix return comment

* Add missing override kw

Co-authored-by: ben-chain <[email protected]>

Author: maurelian

contracts/optimistic-ethereum/OVM/bridge/OVM_BaseCrossDomainMessenger.sol renamed to contracts/optimistic-ethereum/OVM/bridge/Abs_BaseCrossDomainMessenger.sol

@@ -3,21 +3,21 @@ pragma solidity >0.5.0 <0.8.0;
 pragma experimental ABIEncoderV2;
 
 /* Interface Imports */
-import { iOVM_BaseCrossDomainMessenger } from "../../iOVM/bridge/iOVM_BaseCrossDomainMessenger.sol";
+import { iAbs_BaseCrossDomainMessenger } from "../../iOVM/bridge/iAbs_BaseCrossDomainMessenger.sol";
 
 /* Library Imports */
 import { Lib_ReentrancyGuard } from "../../libraries/utils/Lib_ReentrancyGuard.sol";
 
 /**
- * @title OVM_BaseCrossDomainMessenger
+ * @title Abs_BaseCrossDomainMessenger
  * @dev The Base Cross Domain Messenger is an abstract contract providing the interface and common functionality used in the
  * L1 and L2 Cross Domain Messengers. It can also serve as a template for developers wishing to implement a custom bridge 
  * contract to suit their needs.
  *
  * Compiler used: defined by child contract
  * Runtime target: defined by child contract
  */
-abstract contract OVM_BaseCrossDomainMessenger is iOVM_BaseCrossDomainMessenger, Lib_ReentrancyGuard {
+abstract contract Abs_BaseCrossDomainMessenger is iAbs_BaseCrossDomainMessenger, Lib_ReentrancyGuard {
 
     /**********************
      * Contract Variables *

contracts/optimistic-ethereum/OVM/bridge/OVM_L1CrossDomainMessenger.sol

@@ -15,7 +15,7 @@ import { iOVM_CanonicalTransactionChain } from "../../iOVM/chain/iOVM_CanonicalT
 import { iOVM_StateCommitmentChain } from "../../iOVM/chain/iOVM_StateCommitmentChain.sol";
 
 /* Contract Imports */
-import { OVM_BaseCrossDomainMessenger } from "./OVM_BaseCrossDomainMessenger.sol";
+import { Abs_BaseCrossDomainMessenger } from "./Abs_BaseCrossDomainMessenger.sol";
 
 /**
  * @title OVM_L1CrossDomainMessenger
@@ -26,7 +26,7 @@ import { OVM_BaseCrossDomainMessenger } from "./OVM_BaseCrossDomainMessenger.sol
  * Compiler used: solc
  * Runtime target: EVM
  */
-contract OVM_L1CrossDomainMessenger is iOVM_L1CrossDomainMessenger, OVM_BaseCrossDomainMessenger, Lib_AddressResolver {
+contract OVM_L1CrossDomainMessenger is iOVM_L1CrossDomainMessenger, Abs_BaseCrossDomainMessenger, Lib_AddressResolver {
 
     /***************
      * Constructor *

contracts/optimistic-ethereum/OVM/bridge/OVM_L2CrossDomainMessenger.sol

@@ -12,16 +12,17 @@ import { iOVM_L1MessageSender } from "../../iOVM/precompiles/iOVM_L1MessageSende
 import { iOVM_L2ToL1MessagePasser } from "../../iOVM/precompiles/iOVM_L2ToL1MessagePasser.sol";
 
 /* Contract Imports */
-import { OVM_BaseCrossDomainMessenger } from "./OVM_BaseCrossDomainMessenger.sol";
+import { Abs_BaseCrossDomainMessenger } from "./Abs_BaseCrossDomainMessenger.sol";
 
 /**
  * @title OVM_L2CrossDomainMessenger
- * @dev The L2 Cross Domain Messenger contract sends messages from L2 to L1, and is the entry point for L2 messages sent via the L1 Cross Domain Messenger.
+ * @dev The L2 Cross Domain Messenger contract sends messages from L2 to L1, and is the entry point
+ * for L2 messages sent via the L1 Cross Domain Messenger.
  * 
  * Compiler used: optimistic-solc
  * Runtime target: OVM
   */
-contract OVM_L2CrossDomainMessenger is iOVM_L2CrossDomainMessenger, OVM_BaseCrossDomainMessenger, Lib_AddressResolver {
+contract OVM_L2CrossDomainMessenger is iOVM_L2CrossDomainMessenger, Abs_BaseCrossDomainMessenger, Lib_AddressResolver {
 
     /***************
      * Constructor *

contracts/optimistic-ethereum/OVM/chain/OVM_CanonicalTransactionChain.sol

@@ -86,6 +86,7 @@ contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_Ad
      * @return Reference to the batch storage container.
      */
     function batches()
+        override
         public
         view
         returns (
@@ -102,6 +103,7 @@ contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_Ad
      * @return Reference to the queue storage container.
      */
     function queue()
+        override
         public
         view
         returns (
@@ -114,7 +116,8 @@ contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_Ad
     }
 
     /**
-     * @inheritdoc iOVM_CanonicalTransactionChain
+     * Retrieves the total number of elements submitted.
+     * @return _totalElements Total submitted elements.
      */
     function getTotalElements()
         override
@@ -129,7 +132,8 @@ contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_Ad
     }
 
     /**
-     * @inheritdoc iOVM_CanonicalTransactionChain
+     * Retrieves the total number of batches submitted.
+     * @return _totalBatches Total submitted batches.
      */
     function getTotalBatches()
         override
@@ -143,7 +147,8 @@ contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_Ad
     }
 
     /**
-     * @inheritdoc iOVM_CanonicalTransactionChain
+     * Returns the index of the next element to be enqueued.
+     * @return Index for the next queue element.
      */
     function getNextQueueIndex()
         override
@@ -158,7 +163,9 @@ contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_Ad
     }
 
     /**
-     * @inheritdoc iOVM_CanonicalTransactionChain
+     * Gets the queue element at a particular index.
+     * @param _index Index of the queue element to access.
+     * @return _element Queue element at the given index.
      */
     function getQueueElement(
         uint256 _index
@@ -189,7 +196,8 @@ contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_Ad
     }
 
     /**
-     * @inheritdoc iOVM_CanonicalTransactionChain
+     * Get the number of queue elements which have not yet been included.
+     * @return Number of pending queue elements.
      */
     function getNumPendingQueueElements()
         override
@@ -202,8 +210,10 @@ contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_Ad
         return getQueueLength() - getNextQueueIndex();
     }
 
-    /**
-     * @inheritdoc iOVM_CanonicalTransactionChain
+   /**
+     * Retrieves the length of the queue, including
+     * both pending and canonical transactions.
+     * @return Length of the queue.
      */
     function getQueueLength()
         override
@@ -220,7 +230,10 @@ contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_Ad
     }
 
     /**
-     * @inheritdoc iOVM_CanonicalTransactionChain
+     * Adds a transaction to the queue.
+     * @param _target Target L2 contract to send the transaction to.
+     * @param _gasLimit Gas limit for the enqueued L2 transaction.
+     * @param _data Transaction data.
      */
     function enqueue(
         address _target,
@@ -297,7 +310,8 @@ contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_Ad
     }
 
     /**
-     * @inheritdoc iOVM_CanonicalTransactionChain
+     * Appends a given number of queued transactions as a single batch.
+     * @param _numQueuedTransactions Number of transactions to append.
      */
     function appendQueueBatch(
         uint256 _numQueuedTransactions
@@ -347,7 +361,12 @@ contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_Ad
     }
 
     /**
-     * @inheritdoc iOVM_CanonicalTransactionChain
+     * Allows the sequencer to append a batch of transactions.
+     * @dev This function uses a custom encoding scheme for efficiency reasons.
+     * .param _shouldStartAtElement Specific batch we expect to start appending to.
+     * .param _totalElementsToAppend Total number of batch elements we expect to append.
+     * .param _contexts Array of batch contexts.
+     * .param _transactionDataFields Array of raw transaction data.
      */
     function appendSequencerBatch()
         override
@@ -480,7 +499,12 @@ contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_Ad
     }
 
     /**
-     * @inheritdoc iOVM_CanonicalTransactionChain
+     * Verifies whether a transaction is included in the chain.
+     * @param _transaction Transaction to verify.
+     * @param _txChainElement Transaction chain element corresponding to the transaction.
+     * @param _batchHeader Header of the batch the transaction was included in.
+     * @param _inclusionProof Inclusion proof for the provided transaction chain element.
+     * @return True if the transaction exists in the CTC, false if not.
      */
     function verifyTransaction(
         Lib_OVMCodec.Transaction memory _transaction,

contracts/optimistic-ethereum/OVM/execution/OVM_ExecutionManager.sol

@@ -20,16 +20,16 @@ import { OVM_DeployerWhitelist } from "../precompiles/OVM_DeployerWhitelist.sol"
 
 /**
  * @title OVM_ExecutionManager
- * @dev The Execution Manager (EM) is the core of our OVM implementation, and provides a sandboxed 
- * environment allowing us to execute OVM transactions deterministically on either Layer 1 or 
- * Layer 2. 
+ * @dev The Execution Manager (EM) is the core of our OVM implementation, and provides a sandboxed
+ * environment allowing us to execute OVM transactions deterministically on either Layer 1 or
+ * Layer 2.
  * The EM's run() function is the first function called during the execution of any
- * transaction on L2. 
- * For each context-dependent EVM operation the EM has a function which implements a corresponding 
+ * transaction on L2.
+ * For each context-dependent EVM operation the EM has a function which implements a corresponding
  * OVM operation, which will read state from the State Manager contract.
- * The EM relies on the Safety Checker to verify that code deployed to Layer 2 does not contain any 
+ * The EM relies on the Safety Checker to verify that code deployed to Layer 2 does not contain any
  * context-dependent operations.
- * 
+  * 
  * Compiler used: solc
  * Runtime target: EVM
  */

contracts/optimistic-ethereum/OVM/execution/OVM_StateManager.sol

@@ -10,10 +10,10 @@ import { iOVM_StateManager } from "../../iOVM/execution/iOVM_StateManager.sol";
 
 /**
  * @title OVM_StateManager
- * @dev The State Manager contract holds all storage values for contracts in the OVM. It can only be written to by the 
+ * @dev The State Manager contract holds all storage values for contracts in the OVM. It can only be written to by the
  * the Execution Manager and State Transitioner. It runs on L1 during the setup and execution of a fraud proof.
- * The same logic runs on L2, but has been implemented as a precompile in the L2 go-ethereum client 
- * (see https://github.com/ethereum-optimism/go-ethereum/blob/master/core/vm/ovm_state_manager.go)
+ * The same logic runs on L2, but has been implemented as a precompile in the L2 go-ethereum client
+ * (see https://github.com/ethereum-optimism/go-ethereum/blob/master/core/vm/ovm_state_manager.go).
  * 
  * Compiler used: solc
  * Runtime target: EVM

contracts/optimistic-ethereum/OVM/precompiles/OVM_ETH.sol

@@ -6,7 +6,6 @@ import { Lib_AddressResolver } from "../../libraries/resolver/Lib_AddressResolve
 
 /* Interface Imports */
 import { iOVM_ERC20 } from "../../iOVM/precompiles/iOVM_ERC20.sol";
-import { iOVM_BaseCrossDomainMessenger } from "../../iOVM/bridge/iOVM_BaseCrossDomainMessenger.sol";
 
 /**
  * @title OVM_ETH

contracts/optimistic-ethereum/OVM/verification/OVM_FraudContributor.sol renamed to contracts/optimistic-ethereum/OVM/verification/Abs_FraudContributor.sol

@@ -6,7 +6,7 @@ import { Lib_AddressResolver } from "../../libraries/resolver/Lib_AddressResolve
 
 /// Minimal contract to be inherited by contracts consumed by users that provide
 /// data for fraud proofs
-abstract contract OVM_FraudContributor is Lib_AddressResolver {
+abstract contract Abs_FraudContributor is Lib_AddressResolver {
     /// Decorate your functions with this modifier to store how much total gas was
     /// consumed by the sender, to reward users fairly
     modifier contributesToFraudProof(bytes32 preStateRoot, bytes32 txHash) {

contracts/optimistic-ethereum/OVM/verification/OVM_FraudVerifier.sol

@@ -15,7 +15,7 @@ import { iOVM_StateCommitmentChain } from "../../iOVM/chain/iOVM_StateCommitment
 import { iOVM_CanonicalTransactionChain } from "../../iOVM/chain/iOVM_CanonicalTransactionChain.sol";
 
 /* Contract Imports */
-import { OVM_FraudContributor } from "./OVM_FraudContributor.sol";
+import { Abs_FraudContributor } from "./Abs_FraudContributor.sol";
 
 
 
@@ -28,7 +28,7 @@ import { OVM_FraudContributor } from "./OVM_FraudContributor.sol";
  * Compiler used: solc
  * Runtime target: EVM
  */
-contract OVM_FraudVerifier is Lib_AddressResolver, OVM_FraudContributor, iOVM_FraudVerifier {
+contract OVM_FraudVerifier is Lib_AddressResolver, Abs_FraudContributor, iOVM_FraudVerifier {
 
     /*******************************************
      * Contract Variables: Internal Accounting *

contracts/optimistic-ethereum/OVM/verification/OVM_StateTransitioner.sol

@@ -21,12 +21,12 @@ import { iOVM_StateManager } from "../../iOVM/execution/iOVM_StateManager.sol";
 import { iOVM_StateManagerFactory } from "../../iOVM/execution/iOVM_StateManagerFactory.sol";
 
 /* Contract Imports */
-import { OVM_FraudContributor } from "./OVM_FraudContributor.sol";
+import { Abs_FraudContributor } from "./Abs_FraudContributor.sol";
 
 /**
  * @title OVM_StateTransitioner
- * @dev The State Transitioner coordinates the execution of a state transition during the evaluation of a 
- * fraud proof. It feeds verified input to the Execution Manager's run(), and controls a State Manager (which is 
+ * @dev The State Transitioner coordinates the execution of a state transition during the evaluation of a
+ * fraud proof. It feeds verified input to the Execution Manager's run(), and controls a State Manager (which is
  * uniquely created for each fraud proof).
  * Once a fraud proof has been initialized, this contract is provided with the pre-state root and verifies
  * that the OVM storage slots committed to the State Mangager are contained in that state
@@ -37,7 +37,7 @@ import { OVM_FraudContributor } from "./OVM_FraudContributor.sol";
  * Compiler used: solc
  * Runtime target: EVM
  */
-contract OVM_StateTransitioner is Lib_AddressResolver, OVM_FraudContributor, iOVM_StateTransitioner {
+contract OVM_StateTransitioner is Lib_AddressResolver, Abs_FraudContributor, iOVM_StateTransitioner {
 
     /*******************
      * Data Structures *