Add descriptive comments above the contract declaration for all 'non-abstract contracts' (#200)

* Add header comments

* Add header comments on 3 more contracts

* Add todo tag to all complete contracts

* Update contracts/optimistic-ethereum/OVM/execution/OVM_SafetyChecker.sol
Co-authored-by: ben-chain <ben@pseudonym.party>

* Update contracts/optimistic-ethereum/OVM/execution/OVM_SafetyChecker.sol
Co-authored-by: ben-chain <ben@pseudonym.party>

* Update contracts/optimistic-ethereum/OVM/execution/OVM_SafetyChecker.sol
Co-authored-by: ben-chain <ben@pseudonym.party>

* save notes

* save

* Add last of the header comments

* Update contracts/optimistic-ethereum/OVM/bridge/OVM_L1CrossDomainMessenger.sol
Co-authored-by: ben-chain <ben@pseudonym.party>

* Update contracts/optimistic-ethereum/OVM/bridge/OVM_L2CrossDomainMessenger.sol
Co-authored-by: ben-chain <ben@pseudonym.party>

* Update contracts/optimistic-ethereum/OVM/execution/OVM_ExecutionManager.sol
Co-authored-by: ben-chain <ben@pseudonym.party>

* Update contracts/optimistic-ethereum/OVM/precompiles/OVM_L1MessageSender.sol
Co-authored-by: ben-chain <ben@pseudonym.party>

* remove Execution Env field from headers

* Clarify comment

* Improve comments on Lib_SafeExecutionManagerWrapper

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

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

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

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

* Update contracts/optimistic-ethereum/OVM/precompiles/OVM_ProxySequencerEntrypoint.sol

* Update contracts/optimistic-ethereum/OVM/verification/OVM_StateTransitioner.sol
Co-authored-by: ben-chain <ben@pseudonym.party>

packages/contracts/contracts/optimistic-ethereum/OVM/accounts/OVM_ECDSAContractAccount.sol

@@ -13,6 +13,12 @@ import { Lib_SafeMathWrapper } from "../../libraries/wrappers/Lib_SafeMathWrappe
 
 /**
  * @title OVM_ECDSAContractAccount
+ * @dev The ECDSA Contract Account can be used as the implementation for a ProxyEOA deployed by the
+ * ovmCREATEEOA operation. It enables backwards compatibility with Ethereum's Layer 1, by 
+ * providing eth_sign and EIP155 formatted transaction encodings.
+ *
+ * Compiler used: solc
+ * Runtime target: OVM
  */
 contract OVM_ECDSAContractAccount is iOVM_ECDSAContractAccount {
 

packages/contracts/contracts/optimistic-ethereum/OVM/accounts/OVM_ProxyEOA.sol

@@ -9,6 +9,12 @@ import { Lib_SafeExecutionManagerWrapper } from "../../libraries/wrappers/Lib_Sa
 
 /**
  * @title OVM_ProxyEOA
+ * @dev The Proxy EOA contract uses a delegate call to execute the logic in an implementation contract.
+ * In combination with the logic implemented in the ECDSA Contract Account, this enables a form of upgradable 
+ * 'account abstraction' on layer 2. 
+ * 
+ * Compiler used: solc
+ * Runtime target: OVM
  */
 contract OVM_ProxyEOA {
 

packages/contracts/contracts/optimistic-ethereum/OVM/bridge/OVM_BaseCrossDomainMessenger.sol

@@ -10,6 +10,12 @@ import { Lib_ReentrancyGuard } from "../../libraries/utils/Lib_ReentrancyGuard.s
 
 /**
  * @title OVM_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 {
 

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

@@ -19,7 +19,12 @@ import { OVM_BaseCrossDomainMessenger } from "./OVM_BaseCrossDomainMessenger.sol
 
 /**
  * @title OVM_L1CrossDomainMessenger
- * @dev This contract lives on L1. It sends L1->L2 messages into L2, and relays L2->L1 messages from L2 to their target on L1.
+ * @dev The L1 Cross Domain Messenger contract sends messages from L1 to L2, and relays messages from L2 onto L1. 
+ * In the event that a message sent from L1 to L2 is rejected for exceeding the L2 epoch gas limit, it can be resubmitted 
+ * via this contract's replay function. 
+ *
+ * Compiler used: solc
+ * Runtime target: EVM
  */
 contract OVM_L1CrossDomainMessenger is iOVM_L1CrossDomainMessenger, OVM_BaseCrossDomainMessenger, Lib_AddressResolver {
 

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

@@ -16,8 +16,10 @@ import { OVM_BaseCrossDomainMessenger } from "./OVM_BaseCrossDomainMessenger.sol
 
 /**
  * @title OVM_L2CrossDomainMessenger
- * @dev L2 CONTRACT (COMPILED)
- * This contract lives on L2. It sends messages to L1, and relays them from L1.
+ * @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 {
 

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

@@ -19,6 +19,16 @@ import { OVM_ExecutionManager } from "../execution/OVM_ExecutionManager.sol";
 
 /**
  * @title OVM_CanonicalTransactionChain
+ * @dev The Canonical Transaction Chain (CTC) contract is an append-only log of transactions
+ * which must be applied to the rollup state. It defines the ordering of rollup transactions by
+ * writing them to the 'CTC:batches' instance of the Chain Storage Container.
+ * The CTC also allows any account to 'enqueue' an L2 transaction, which will require that the Sequencer
+ * will eventually append it to the rollup state.
+ * If the Sequencer does not include an enqueued transaction within the 'force inclusion period',
+ * then any account may force it to be included by calling appendQueueBatch().
+ *
+ * Compiler used: solc
+ * Runtime target: EVM
  */
 contract OVM_CanonicalTransactionChain is iOVM_CanonicalTransactionChain, Lib_AddressResolver {
 

packages/contracts/contracts/optimistic-ethereum/OVM/chain/OVM_ChainStorageContainer.sol

@@ -10,6 +10,17 @@ import { iOVM_ChainStorageContainer } from "../../iOVM/chain/iOVM_ChainStorageCo
 
 /**
  * @title OVM_ChainStorageContainer
+ * @dev The Chain Storage Container provides its owner contract with read, write and delete functionality. 
+ * This provides gas efficiency gains by enabling it to overwrite storage slots which can no longer be used
+ * in a fraud proof due to the fraud window having passed, and the associated chain state or 
+ * transactions being finalized.
+ * Three disctint Chain Storage Containers will be deployed on Layer 1:
+ * 1. Stores transaction batches for the Canonical Transaction Chain
+ * 2. Stores queued transactions for the Canonical Transaction Chain
+ * 3. Stores chain state batches for the State Commitment Chain
+ *
+ * Compiler used: solc
+ * Runtime target: EVM
  */
 contract OVM_ChainStorageContainer is iOVM_ChainStorageContainer, Lib_AddressResolver {
 

packages/contracts/contracts/optimistic-ethereum/OVM/chain/OVM_StateCommitmentChain.sol

@@ -19,6 +19,13 @@ import '@openzeppelin/contracts/math/SafeMath.sol';
 
 /**
  * @title OVM_StateCommitmentChain
+ * @dev The State Commitment Chain (SCC) contract contains a list of proposed state roots which
+ * Proposers assert to be a result of each transaction in the Canonical Transaction Chain (CTC). 
+ * Elements here have a 1:1 correspondence with transactions in the CTC, and should be the unique
+ * state root calculated off-chain by applying the canonical transactions one by one.
+ *
+ * Compiler used: solc
+ * Runtime target: EVM
  */
 contract OVM_StateCommitmentChain is iOVM_StateCommitmentChain, Lib_AddressResolver {
 

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

@@ -20,6 +20,18 @@ 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. 
+ * 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 
+ * 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 
+ * context-dependent operations.
+ * 
+ * Compiler used: solc
+ * Runtime target: EVM
  */
 contract OVM_ExecutionManager is iOVM_ExecutionManager, Lib_AddressResolver {
 
@@ -155,6 +167,7 @@ contract OVM_ExecutionManager is iOVM_ExecutionManager, Lib_AddressResolver {
         // OVM_StateManager (expected to be an OVM_StateTransitioner). We can revert here because
         // this would make the `run` itself invalid.
         require(
+            // This method may return false during fraud proofs, but always returns true in L2 nodes' State Manager precompile.
             ovmStateManager.isAuthenticated(msg.sender),
             "Only authenticated addresses in ovmStateManager can call this function"
         );
@@ -310,8 +323,8 @@ contract OVM_ExecutionManager is iOVM_ExecutionManager, Lib_AddressResolver {
     }
 
     /**
-     * @notice Specifies what L1 EOA, if any, sent this transaction.
-     * @return _l1TxOrigin Address of the EOA which send the tx into L2 from L1.
+     * @notice Specifies which L1 account, if any, sent this transaction by calling enqueue().
+     * @return _l1TxOrigin Address of the account which sent the tx into L2 from L1.
      */
     function ovmL1TXORIGIN()
         override

packages/contracts/contracts/optimistic-ethereum/OVM/execution/OVM_SafetyChecker.sol

@@ -6,6 +6,16 @@ import { iOVM_SafetyChecker } from "../../iOVM/execution/iOVM_SafetyChecker.sol"
 
 /**
  * @title OVM_SafetyChecker
+ * @dev  The Safety Checker verifies that contracts deployed on L2 do not contain any
+ * "unsafe" operations. An operation is considered unsafe if it would access state variables which
+ * are specific to the environment (ie. L1 or L2) in which it is executed, as this could be used
+ * to "escape the sandbox" of the OVM, resulting in non-deterministic fraud proofs. 
+ * That is, an attacker would be able to "prove fraud" on an honestly applied transaction.
+ * Note that a "safe" contract requires opcodes to appear in a particular pattern;
+ * omission of "unsafe" opcodes is necessary, but not sufficient.
+ *
+ * Compiler used: solc
+ * Runtime target: EVM
  */
 contract OVM_SafetyChecker is iOVM_SafetyChecker {
 

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

@@ -10,6 +10,13 @@ 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 
+ * 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)
+ * 
+ * Compiler used: solc
+ * Runtime target: EVM
  */
 contract OVM_StateManager is iOVM_StateManager {
 
@@ -63,10 +70,11 @@ contract OVM_StateManager is iOVM_StateManager {
      **********************/
 
     /**
-     * Simple authentication, this contract should only be accessible to the owner or to the
-     * OVM_ExecutionManager during the transaction execution process.
+     * Simple authentication, this contract should only be accessible to the owner (which is expected to be the State Transitioner during `PRE_EXECUTION` 
+     * or the OVM_ExecutionManager during transaction execution.
      */
     modifier authenticated() {
+        // owner is the State Transitioner
         require(
             msg.sender == owner || msg.sender == ovmExecutionManager,
             "Function can only be called by authenticated addresses"

packages/contracts/contracts/optimistic-ethereum/OVM/execution/OVM_StateManagerFactory.sol

@@ -10,6 +10,11 @@ import { OVM_StateManager } from "./OVM_StateManager.sol";
 
 /**
  * @title OVM_StateManagerFactory
+ * @dev The State Manager Factory is called by a State Transitioner's init code, to create a new 
+ * State Manager for use in the Fraud Verification process.
+ * 
+ * Compiler used: solc
+ * Runtime target: EVM
  */
 contract OVM_StateManagerFactory is iOVM_StateManagerFactory {
 

packages/contracts/contracts/optimistic-ethereum/OVM/precompiles/OVM_DeployerWhitelist.sol

@@ -10,7 +10,13 @@ import { Lib_SafeExecutionManagerWrapper } from "../../libraries/wrappers/Lib_Sa
 
 /**
  * @title OVM_DeployerWhitelist
- * @dev L2 CONTRACT (NOT COMPILED)
+ * @dev The Deployer Whitelist is a temporary predeploy used to provide additional safety during the
+ * initial phases of our mainnet roll out. It is owned by the Optimism team, and defines accounts
+ * which are allowed to deploy contracts on Layer2. The Execution Manager will only allow an 
+ * ovmCREATE or ovmCREATE2 operation to proceed if the deployer's address whitelisted.
+ * 
+ * Compiler used: solc
+ * Runtime target: OVM
  */
 contract OVM_DeployerWhitelist is iOVM_DeployerWhitelist {
 

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

@@ -10,7 +10,11 @@ import { iOVM_BaseCrossDomainMessenger } from "../../iOVM/bridge/iOVM_BaseCrossD
 
 /**
  * @title OVM_ETH
- * @dev L2 CONTRACT (COMPILED)
+ * @dev The ETH predeploy provides an ERC20 interface for ETH deposited to Layer 2. Note that 
+ * unlike on Layer 1, Layer 2 accounts do not have a balance field.
+ * 
+ * Compiler used: optimistic-solc
+ * Runtime target: OVM
  */
 contract OVM_ETH is iOVM_ERC20, Lib_AddressResolver {
 

packages/contracts/contracts/optimistic-ethereum/OVM/precompiles/OVM_L1MessageSender.sol

@@ -7,7 +7,18 @@ import { iOVM_ExecutionManager } from "../../iOVM/execution/iOVM_ExecutionManage
 
 /**
  * @title OVM_L1MessageSender
- * @dev L2 CONTRACT (NOT COMPILED)
+ * @dev The L1MessageSender is a predeploy contract running on L2. During the execution of cross 
+ * domain transaction from L1 to L2, it returns the address of the L1 account (either an EOA or
+ * contract) which sent the message to L2 via the Canonical Transaction Chain's `enqueue()` 
+ * function.
+ * 
+ * This contract exclusively serves as a getter for the ovmL1TXORIGIN operation. This is necessary 
+ * because there is no corresponding operation in the EVM which the the optimistic solidity compiler 
+ * can be replaced with a call to the ExecutionManager's ovmL1TXORIGIN() function.
+ *
+ * 
+ * Compiler used: solc
+ * Runtime target: OVM
  */
 contract OVM_L1MessageSender is iOVM_L1MessageSender {
 
@@ -26,6 +37,7 @@ contract OVM_L1MessageSender is iOVM_L1MessageSender {
             address _l1MessageSender
         )
     {
+        // Note that on L2 msg.sender (ie. evmCALLER) will always be the Execution Manager 
         return iOVM_ExecutionManager(msg.sender).ovmL1TXORIGIN();
     }
 }

packages/contracts/contracts/optimistic-ethereum/OVM/precompiles/OVM_L2ToL1MessagePasser.sol

@@ -6,7 +6,13 @@ import { iOVM_L2ToL1MessagePasser } from "../../iOVM/precompiles/iOVM_L2ToL1Mess
 
 /**
  * @title OVM_L2ToL1MessagePasser
- * @dev L2 CONTRACT (COMPILED)
+ * @dev The L2 to L1 Message Passer is a utility contract which facilitate an L1 proof of the 
+ * of a message on L2. The L1 Cross Domain Messenger performs this proof in its
+ * _verifyStorageProof function, which verifies the existence of the transaction hash in this 
+ * contract's `sentMessages` mapping.
+ * 
+ * Compiler used: solc
+ * Runtime target: EVM
  */
 contract OVM_L2ToL1MessagePasser is iOVM_L2ToL1MessagePasser {
 

packages/contracts/contracts/optimistic-ethereum/OVM/precompiles/OVM_ProxySequencerEntrypoint.sol

@@ -6,6 +6,12 @@ import { Lib_SafeExecutionManagerWrapper } from "../../libraries/wrappers/Lib_Sa
 
 /**
  * @title OVM_ProxySequencerEntrypoint 
+ * @dev The Proxy Sequencer Entrypoint is a predeployed proxy to the implementation of the 
+ * Sequencer Entrypoint. This will enable the Optimism team to upgrade the Sequencer Entrypoint 
+ * contract.
+ * 
+ * Compiler used: solc
+ * Runtime target: OVM
  */
 contract OVM_ProxySequencerEntrypoint {
 

packages/contracts/contracts/optimistic-ethereum/OVM/precompiles/OVM_SequencerEntrypoint.sol

@@ -9,6 +9,14 @@ import { Lib_SafeExecutionManagerWrapper } from "../../libraries/wrappers/Lib_Sa
 
 /**
  * @title OVM_SequencerEntrypoint
+ * @dev The Sequencer Entrypoint is a predeploy which, despite its name, can in fact be called by 
+ * any account. It accepts a more efficient compressed calldata format, which it decompresses and 
+ * encodes to the standard EIP155 transaction format.
+ * This contract is the implementation referenced by the Proxy Sequencer Entrypoint, thus enabling
+ * the Optimism team to upgrade the decompression of calldata from the Sequencer.
+ * 
+ * Compiler used: solc
+ * Runtime target: OVM
  */
 contract OVM_SequencerEntrypoint {
 

packages/contracts/contracts/optimistic-ethereum/OVM/verification/OVM_BondManager.sol

@@ -10,6 +10,13 @@ import { iOVM_FraudVerifier } from "../../iOVM/verification/iOVM_FraudVerifier.s
 
 /**
  * @title OVM_BondManager
+ * @dev The Bond Manager contract handles deposits in the form of an ERC20 token from bonded 
+ * Proposers. It also handles the accounting of gas costs spent by a Verifier during the course of a
+ * fraud proof. In the event of a successful fraud proof, the fraudulent Proposer's bond is slashed, 
+ * and the Verifier's gas costs are refunded.
+ * 
+ * Compiler used: solc
+ * Runtime target: EVM
  */
 contract OVM_BondManager is iOVM_BondManager, Lib_AddressResolver {
 

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

@@ -17,6 +17,17 @@ import { iOVM_CanonicalTransactionChain } from "../../iOVM/chain/iOVM_CanonicalT
 /* Contract Imports */
 import { OVM_FraudContributor } from "./OVM_FraudContributor.sol";
 
+
+
+/**
+ * @title OVM_FraudVerifier
+ * @dev The Fraud Verifier contract coordinates the entire fraud proof verification process. 
+ * If the fraud proof was successful it prunes any state batches from State Commitment Chain
+ * which were published after the fraudulent state root.
+ * 
+ * Compiler used: solc
+ * Runtime target: EVM
+ */
 contract OVM_FraudVerifier is Lib_AddressResolver, OVM_FraudContributor, iOVM_FraudVerifier {
 
     /*******************************************

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

@@ -25,6 +25,17 @@ import { OVM_FraudContributor } from "./OVM_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 
+ * 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
+ * This contract controls the State Manager and Execution Manager, and uses them to calculate the
+ * post-state root by applying the transaction. The Fraud Verifier can then check for fraud by comparing
+ * the calculated post-state root with the proposed post-state root.
+ * 
+ * Compiler used: solc
+ * Runtime target: EVM
  */
 contract OVM_StateTransitioner is Lib_AddressResolver, OVM_FraudContributor, iOVM_StateTransitioner {
 

packages/contracts/contracts/optimistic-ethereum/OVM/verification/OVM_StateTransitionerFactory.sol

@@ -15,6 +15,11 @@ import { OVM_StateTransitioner } from "./OVM_StateTransitioner.sol";
 
 /**
  * @title OVM_StateTransitionerFactory
+ * @dev The State Transitioner Factory is used by the Fraud Verifier to create a new State 
+ * Transitioner during the initialization of a fraud proof.
+ * 
+ * Compiler used: solc
+ * Runtime target: EVM
  */
 contract OVM_StateTransitionerFactory is iOVM_StateTransitionerFactory, Lib_AddressResolver {
 

packages/contracts/contracts/optimistic-ethereum/libraries/wrappers/Lib_SafeExecutionManagerWrapper.sol

@@ -3,6 +3,12 @@ pragma solidity >0.5.0 <0.8.0;
 
 /**
  * @title Lib_SafeExecutionManagerWrapper
+ * @dev The Safe Execution Manager Wrapper provides functions which facilitate writing OVM safe 
+ * code using the standard solidity compiler, by routing all its operations through the Execution 
+ * Manager.
+ * 
+ * Compiler used: solc
+ * Runtime target: OVM
  */
 library Lib_SafeExecutionManagerWrapper {
 
@@ -11,7 +17,7 @@ library Lib_SafeExecutionManagerWrapper {
      **********************/
 
     /**
-     * Makes an ovmCALL and performs all the necessary safety checks.
+     * Performs a safe ovmCALL.
      * @param _gasLimit Gas limit for the call.
      * @param _target Address to call.
      * @param _calldata Data to send to the call.
@@ -42,7 +48,7 @@ library Lib_SafeExecutionManagerWrapper {
     }
 
     /**
-     * Makes an ovmCALL and performs all the necessary safety checks.
+     * Performs a safe ovmDELEGATECALL.
      * @param _gasLimit Gas limit for the call.
      * @param _target Address to call.
      * @param _calldata Data to send to the call.
@@ -73,7 +79,7 @@ library Lib_SafeExecutionManagerWrapper {
     }
 
     /**
-     * Performs an ovmCREATE and the necessary safety checks.
+     * Performs a safe ovmCREATE call.
      * @param _gasLimit Gas limit for the creation.
      * @param _bytecode Code for the new contract.
      * @return _contract Address of the created contract.
@@ -99,7 +105,7 @@ library Lib_SafeExecutionManagerWrapper {
     }
 
     /**
-     * Performs an ovmEXTCODESIZE and the necessary safety checks.
+     * Performs a safe ovmEXTCODESIZE call.
      * @param _contract Address of the contract to query the size of.
      * @return _EXTCODESIZE Size of the requested contract in bytes.
      */