Skip to content
This repository has been archived by the owner on Apr 12, 2021. It is now read-only.

Commit

Permalink
Add descriptive comments above the contract declaration for all 'non-…
Browse files Browse the repository at this point in the history
…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 <[email protected]>

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

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

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

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

* save notes

* save

* Add last of the header comments

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

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

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

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

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

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

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

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

* 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 <[email protected]>
  • Loading branch information
maurelian and ben-chain authored Feb 4, 2021
1 parent e8bf590 commit 13b7dee
Show file tree
Hide file tree
Showing 23 changed files with 188 additions and 17 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
6 changes: 6 additions & 0 deletions contracts/optimistic-ethereum/OVM/accounts/OVM_ProxyEOA.sol
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,11 @@ 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 {

/***************
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down Expand Up @@ -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"
);
Expand Down Expand Up @@ -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
Expand Down
10 changes: 10 additions & 0 deletions contracts/optimistic-ethereum/OVM/execution/OVM_SafetyChecker.sol
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
12 changes: 10 additions & 2 deletions contracts/optimistic-ethereum/OVM/execution/OVM_StateManager.sol
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down Expand Up @@ -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"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
6 changes: 5 additions & 1 deletion contracts/optimistic-ethereum/OVM/precompiles/OVM_ETH.sol
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand All @@ -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();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,13 @@ pragma solidity >0.5.0 <0.8.0;
import { Lib_SafeExecutionManagerWrapper } from "../../libraries/wrappers/Lib_SafeExecutionManagerWrapper.sol";

/**
* @title OVM_ProxySequencerEntrypoint
* @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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

/*******************************************
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
Loading

0 comments on commit 13b7dee

Please sign in to comment.