Add specs package (#514)

* chore: import specs

fix: accurately describe ovmL1TXORIGIN

more specs

* chore: rename to match structure of contracts

words

* chore: move to packages

* chore: add package.json

fix location of package.json

* docs: rename processes dir to components

words

* docs: remove empty specs dir

* docs: move sequencer into l2geth

* chore: assign code owners to specs

* chore: add prettier

* docs: polish bridge and actors section

docs: polish

* chore: add format:check script

* docs: fixup readme

* chore: fix prettier config

* fix: json linting

* chore: add changeset

* Update packages/specs/protocol/components/execution.md

* chore: move specs to root

* chore: make private, add to yarn workspaces

* Update specs/package.json
Co-authored-by: Georgios Konstantopoulos <me@gakonst.com>

* fix: formatting
Co-authored-by: Georgios Konstantopoulos <me@gakonst.com>

.changeset/slimy-tomatoes-report.md

+---
+"@eth-optimism/specs": minor
+---
+
+Add a new package to contain specs

.github/CODEOWNERS

 l2geth/                             @smartcontracts @tynes @karlfloersch
+packages/specs/l2geth/              @smartcontracts @tynes @karlfloersch
+packages/contracts/                 @smartcontracts @ben-chain @maurelian
+packages/specs/protocol/            @smartcontracts @ben-chain @maurelian
 ops/                                @tynes @karlfloersch
 packages/hardhat-ovm/               @smartcontracts
 packages/smock/                     @smartcontracts @maurelian
 packages/core-utils/                @smartcontracts @annieke @ben-chain
 packages/core-utils/src/watcher.ts  @K-Ho
-packages/contracts/                 @smartcontracts @ben-chain @maurelian
 packages/message-relayer/           @K-Ho
 packages/batch-submitter/           @annieke @karlfloersch
 packages/data-transport-layer/      @annieke

package.json

@@ -5,7 +5,8 @@
   "workspaces": [
     "packages/*",
     "l2geth",
-    "integration-tests"
+    "integration-tests",
+    "specs"
   ],
   "private": true,
   "devDependencies": {

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

@@ -317,8 +317,8 @@ contract OVM_ExecutionManager is iOVM_ExecutionManager, Lib_AddressResolver {
      *********************************/
 
     /**
-     * @notice Specifies from which L1 rollup queue this transaction originated from.
-     * @return _queueOrigin Address of the ovmL1QUEUEORIGIN within the current message context.
+     * @notice Specifies from which source (Sequencer or Queue) this transaction originated from.
+     * @return _queueOrigin Enum indicating the ovmL1QUEUEORIGIN within the current message context.
      */
     function ovmL1QUEUEORIGIN()
         override

specs/.prettierrc.json

+{}

specs/README.md

+# Optimistic Specs
+
+Welcome to Optimism's specs.
+
+Please refer to the README in each of the subdirectories for a table of contents.
+
+### Usage
+
+We provide some basic yarn scripts to ensure consistent formatting.
+
+After modifying any of the markdown files here, run `yarn format`.
+
+```bash
+yarn format
+```

specs/l2geth/README.md

+# L2 Geth Specs
+
+## Contents
+
+- [Transaction indexer](./transaction-indexer.md)
+- [Transaction ingestor](./transaction-ingestor.md)
+- [Transaction types](./transaction-types.md)

specs/l2geth/sequencer/fees.md

+# Transaction Fees Spec
+
+## Goals
+
+- Allow projects to easily query how high of a gasPrice their users need to set to get their transaction approved
+- Allow the sequencer to only accept transactions that at least cover their cost to the system (L1 calldata gas costs + L2 gas costs)
+
+## Non-goals
+
+- Minimum possible fees
+- Fee calculation that is completely automated
+- Congestion Fees
+
+## Why a separate service?
+
+N/A
+
+## Pre-launch timeline
+
+- [ ] getGasPrice endpoint in geth + rejecting underfunded txs 2 weeks before launch
+- [ ] Paying fees in Kovan -both Synthetix and Kovan by 1.5 week before launch
+- [ ] Paying fees in Mainnet 1 week before launch
+
+## Inputs & dependencies
+
+- OVM_ETH (for fee payment)
+- ETH Deposit Withdrawal Dapp
+- Seeing your L2 WETH in SNX frontend
+
+### getGasPrice(tx)
+
+- Input is tx calldata
+
+## Outputs
+
+### estimateGasPrice(tx, ?gasLimit)
+
+- returns `gasPrice` in wei to set for a given tx, taking into account the current `dataPrice` and `l2GasPrice` along with the `tx` calldata.
+
+### getDataPrice()
+
+- returns the `dataPrice` in wei (cost per zero byte). This will approximately track 4 \* l1 gasPrice
+
+### getGasPrice()
+
+- returns the gasPrice for L2 execution
+
+### validateTx
+
+- returns error message for eth_sendRawTransaction
+  - If tx is underfunded, "Error: Inadequate transaction fee. For this transaction to be accepted, set a gasPrice of \_\_ gwei"
+  - If tx has a gasLimit !== 9m, "Error: Expected a gas limit of 9m. Please set your tx gasLimit to 9m."
+
+## Internals
+
+Geth sets a dataPrice and a gasPrice internally. This can be displayed publicly on an `*.optimism.io` site.
+
+- `dataPrice` in wei is the cost per zero byte of calldata. A non-zero byte of calldata will cost `dataPrice * 4` in wei.
+- `gasPrice` in wei is the cost per unit of gas consumed during L2 execution.
+
+```
+// estimates the gas price based on a txs size and its gasLimit so gasPrice * gasLimit = intended fee
+function estimateGasPrice(tx, ?gasLimit=9000000) {
+    const dataCost = dataPrice * (tx.zeroBytes + (tx.nonZeroBytes * 4))
+    const gasCost = gasLimit * gasPrice
+    return ((gasCost + dataCost) / gasLimit)
+}
+```

specs/l2geth/transaction-types.md

+# Transaction Types
+
+This defines the serialization of the transactions that are submitted to the
+Canonical Transaction Chain.
+Transaction types are defined by the leading byte which is used as an enum. The
+purpose of a transaction type is to enable transaction compression as well as
+allowing for new types to be defined that take advantage of the account
+abstraction.
+
+## EIP155
+
+A compressed EIP155 transaction. The transaction that is signed follows
+[EIP155](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md). The type enum is `0`.
+
+| Field    | Size (bytes) |
+| -------- | ------------ |
+| Type     | 1            |
+| R        | 32           |
+| S        | 32           |
+| V        | 1            |
+| gasLimit | 3            |
+| gasPrice | 3            |
+| nonce    | 3            |
+| target   | 20           |
+| data     | variable     |
+
+The `gasPrice` must be scaled by a factor of `1,000,000` when encoding and
+decoding. This means that precision is lost and must be divisibl by 1 million.
+From a user experience perspective, the `gasPrice` must be at least 1 gwei and
+at most 16777215 gwei. A partial gwei will result in an invalid transaction.
+
+The max nonce is 16777215. Any nonces greater than that must result in an
+invalid transaction.
+
+## EthSign
+
+A compressed EIP155 transaction that uses an alternative signature hashing
+algorithm. The data is ABI encoded hashed and then signed with `eth_sign`.
+The type enum is `1`.
+
+| Field    | Size (bytes) |
+| -------- | ------------ |
+| Type     | 1            |
+| R        | 32           |
+| S        | 32           |
+| V        | 1            |
+| gasLimit | 3            |
+| gasPrice | 3            |
+| nonce    | 3            |
+| target   | 20           |
+| data     | variable     |
+
+The same `gasPrice` and `nonce` rules apply as the `EIP155` transaction.
+
+The following table shows how the fields are ABI encoded before hashing.
+
+| Field    | ABI Type |
+| -------- | -------- |
+| nonce    | uint256  |
+| gasLimit | uint256  |
+| gasPrice | uint256  |
+| chainId  | uint256  |
+| target   | address  |
+| data     | bytes    |
+
+The ABI encoded data is hashed with `keccak256` and then prepended with
+`\x19Ethereum Signed Message:\n32` before being hashed again with `keccak256`
+to create the digest that is signed with the secp256k1 private key.

specs/package.json

+{
+  "name": "@eth-optimism/specs",
+  "version": "0.1.0",
+  "license": "MIT",
+  "private": true,
+  "devDependencies": {
+    "prettier": "2.2.1"
+  },
+  "scripts": {
+    "lint:fix": "yarn prettier --write \"{l2geth,protocol}/**/*.md\"",
+    "lint": "yarn prettier --check \"{l2geth,protocol}/**/*.md\""
+  }
+}

specs/protocol/README.md

+## Optimistic Ethereum Protocol Specification
+
+This page serves as an annotated table of contents for the documents within the protocol specification.
+
+## Contents
+
+- **[Glossary](./glossary.md):** A list of definitions and abbreviations for commonly used terms.
+- **[Data Structures](./data-structures.md):** All of the Data Structures found in the Protocol are listed here, along with descriptions and validation information.
+- **[Actors and Roles](./actors-and-roles.md):** Describes the various actors within the system, and what actions they are permitted to take.
+- **components:** These pages describe the correct functioning of key processes within the protocol.
+  - [Chains](./components/chains.md): Specification of the CTC and SCC.
+  - [Execution](./components/execution.md): Specification of the EM and SM.
+  - [Fraud Proving](./components/verification.md): Specification of the Fraud Proving process.
+  - [Cross Domain Messaging](./components/bridge.md): Specification of Cross Domain Messaging components.
+  - [Cross Domain Messaging](./components/predeploys.md): Specification of Cross Domain Messaging components.

specs/protocol/actors-and-roles.md

+# Actor and Roles
+
+## Sequencer
+
+The Sequencer is a semi-privileged service provider in Optimistic Ethereum which enables instant transactions. The sequencer is given the role of assigning an order to L2 transactions, similarly to miners on L1.
+
+There is only one sequencer at a time, allowing consensus on transactions to be reached extremely rapidly. Users can send transactions to the sequencer, and (within seconds) receive confirmation that their transaction was processed and will be included in the next rollup batch. These instant confirmations have weaker security than confirmed L1 transactions, but stronger security than 0-conf L1 transactions.
+
+Once the sequencer's batch is confirmed on L1, the security is the same.
+
+### On censorship resistance
+
+In the event that a malicious Sequencer censors user's transactions, the user SHOULD `enqueue()` their transactions directly to the L1 Queue, forcing the sequencer to include them in the L2 chain within the `FORCE_INCLUSION_PERIOD`.
+
+If any transaction in the queue are more than `FORCE_INCLUSION_PERIOD` blocks old, those transactions MUST be added to the Chain before the protocol will allow the Sequencer to add any other transactions.
+
+In the event that the Sequencer stops submitting transactions entirely, the protocol will allow users to add transactions to the CTC by calling `appendQueueBatch()`
+
+### Roles
+
+- Receives new transactions from users
+- SHOULD process transactions instantly to determine an optimal ordering
+- Determines the ordering of transactions in the CTC, which MUST follow the [constraints](./processes/chains.md#properties-enforced-by-appendsequencerbatch) imposed by the `appendSequencerBatch()` function.
+- SHOULD append transactions from the CTC's `queue` within the "Force Inclusion Period".
+
+## Proposers
+
+Proposers evaluate the transactions in the CTC, and 'commit' to the resulting state by writing them to the SCC. They must deposit a bond for the privilege of this role.
+This bond will be slashed in the event of a successful fraud proof on a state root committed by the Proposer.
+
+### Roles
+
+- Process transactions from the CTC, and propose new state roots by posting them to the SCC.
+- MUST be collateralized by depositing a bond to the `OVM_BondManager` .
+
+**Future note:** The Proposer is currently identical to the Sequencer. This is expected to change.
+
+## Verifier
+
+Like Proposers, Verifiers evaluate the transactions in the CTC, in order to determine the resulting state root following each transaction.
+If a Verifier finds that a proposed state root is incorrect, they can prove fraud, and earn a reward taken from the Proposer's bond.
+
+### Roles
+
+- Read transactions from the CTC, process them, and verify the correctness of state roots in the SCC.
+- If an invalid state root is detected: initiate and complete a fraud proof.
+  - Note that multiple accounts may contribute to a fraud proof and earn the reward.
+
+## Users
+
+Any account may transact on OE.
+
+### Roles
+
+- MAY post L2 transactions via the Sequencer's RPC endpoint, to be appended in sequencer batches
+- MAY submit an L2 transaction via the CTC's queue on L1
+  - Can be used to circumvent censorship by the Sequencer
+  - Can be used to send a cross domain message from an L1 contract account.

specs/protocol/components/accounts.md

+# Accounts
+
+This document is a WIP. It is kept here to maintain a consistent structure mirroring the [implementation directory](../../../contracts/contracts/optimistic-ethereum/OVM/).
+
+<!--
+### ProxyEOAs
+
+- Created by call to ovmCREATEEOA with signature
+- `ecrecover` is used to retrieve address and deploy the trusted ProxyEOA contract, which implements a simple DelegateCall pattern there.
+
+### OVM_ECDSAContractAccount
+
+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 EIP155 formatted transaction encodings.
+
+#### Value Transfer
+
+Value transfer is currently only supported in the first call frame of a transaction on L2. -->

specs/protocol/components/bridge.md

+# Cross Domain Messaging
+
+This specification covers the sending and relaying of messages, either from L2 to L1, or L1 to L2.
+
+A high-level description I find useful to summarize the difference between the two flows is that:
+
+1. From L2 to L1, messages are validated by verifying the inclusion of the message data in a mapping in a contract on the L2 state.
+2. From L1 to L2, messages are validated simply by checking that the `ovmL1TXORIGIN` matches the expected address
+
+## Cross Domain Messengers Contracts (aka xDMs)
+
+There are two 'low level' bridge contracts (the L1 and L2 Cross Domain Messengers), which are 'paired' in the sense that they reference each other's addresses in order to validate cross domain messages.
+
+## L2 to L1 messaging flow
+
+**Starting on L2:**
+
+- Any account on L2 may call `OVM_L2CrossDomainMessenger.sendMessage()` with the information for the L1 message (aka `xDomainCalldata`)
+  - (ie. `_target`, `msg.sender`, `_message`)
+  - This data is hashed with the `messageNonce` storage variable, and the hash is store in the `sentMessages` mapping (this is not actually used AFAIK)
+  - The `messageNonce` is then incremented.
+- The `OVM_L2CrossDomainMessenger` then passes the `xDomainCalldata` to `OVM_L2ToL1MessagePasser.passMessageToL1()`
+  - the `xDomainCalldata` is hashed with `msg.sender` (ie. `ovmCaller`), and written to the `sentMessages` mapping.
+
+**Then on L1:**
+
+- The `Relayer` (and currently only the `Relayer`) may call `OVM_L1CrossDomainMessenger.relayMessage()` providing the raw message inputs and an L2 inclusion proof.
+- The validity of the message is confirmed by the following functions:
+  - `_verifyStateRootProof()`:
+    - checks that the fraud proof window has closed for the batch to which the transaction belongs.
+    - checks that the batch is stored in the `OVM_ChainStorageContainer`.
+  - `_verifyStorageProof()`:
+    - checks the proof to confirm that the message data provided is in the `OVM_L2ToL1MessagePasser.sentMessages` mapping
+    - checks that this transaction has not already been written to the `successfulMessages` mapping.
+- The address of the L2 `ovmCALLER` is then written to the `xDomainMessageSender` state variable
+  - the call is then executed, allow the `target` to query the value of the `OVM_L1CrossDomainMessenger.xDomainMessageSender` for authorization.
+- if it succeeds it is added to the `successfulMessages` and cannot be relayed again.
+- regardless of success, an entry is written to the `relayedMessages` mapping.
+
+**Then the receiver (ie. `SynthetixBridgeToOptimism`):**
+
+- Checks that the caller is the `OVM_L1CrossDomainMessenger` and that the `xDomainMessageSender` is the `synthetixBridgeToBase` on L2.
+
+## L1 to L2 messaging flow
+
+**Starting on L1:**
+
+- Any account may call the L1xDM's `sendMessage()`, specifying the details of the call that the L2xDM should make.
+- The L1xDM call `enqueue` on the CTC to add to the Transaction Queue, with the L2xDM as the `target`.
+  - The [`Transaction.data`](../data-structures.md#transaction) field should be ABI encoded to call `OVM_L2CrossDomainMessenger.relayMessage()`.
+
+**Then on L2:**
+
+- A transaction will be sent to the `OVM_L2CrossDomainMessenger`.
+- The cross-domain message is deemed valid if the `ovmL1TXORIGIN` is the `OVM_L1CrossDomainMessenger`.
+  - If not valid, execution reverts.
+- If the message is valid, the arguments are ABI encoded and keccak256 hashed to `xDomainCalldataHash`.
+- The `succesfulMessages` mapping is checked to verify that `xDomainCalldataHash` has not already been executed successfully.
+  - If an entry is found in `succesfulMessages` execution reverts.
+- A check is done to disallow calls to the `OVM_L2ToL1MessagePasser`, which would allow an attacker to spoof a withdrawal.
+  - Execution reverts if the check fails.
+  - **Future note:** The `OVM_L2ToL1MessagePasser`, and this check should be removed, in favor of putting the `sentMessages` mapping into the L2xDM.
+- The address of the L2 `ovmCALLER` is then written to the `xDomainMessageSender` state variable
+  - the call is then executed, allow the `target` to query the value of the `OVM_L1CrossDomainMessenger.xDomainMessageSender` for authorization.
+- If it succeeds it is added to the `successfulMessages`.

specs/protocol/components/execution.md

+# Execution
+
+The Optimistic Virtual Machine (OVM) provides a sandboxed execution environment built on the EVM, with the goal of guaranteeing deterministic execution which maintains agreement between L1 and L2.
+
+## Security properties and invariants
+
+- Deterministic execution; maintaining consensus of rollup state between L1 and L2.
+
+  - Corollary: L1 execution context MUST not be accessible (except in cases where the context can be guaranteed to agree with L2, ie. `GAS` is allowed, but must agree at all time during execution.
+  - Unsafe opcodes must not be deployable.
+  - It must be possible to complete the execution of a fraud proof within the L1 block gas limit.
+
+- The execution context should be ephemeral, and not persist between calls to `run()`
+  - More precisely: although the Execution Manager does hold some permanent values in storage, those values should remain constant before and after each execution. The state root of the contract should be constant.
+
+## Safety Checking
+
+In order to maintain the property of Deterministic Execution, we consider the following opcodes unsafe, and MUST prevent them from being deployed on L2.
+
+All currently unassigned opcodes which are not yet assigned in the EVM are also disallowed.
+
+**Unsafe Opcodes**
+
+- `ADDRESS`
+- `BALANCE`
+- `ORIGIN`
+- `EXTCODESIZE`
+- `EXTCODECOPY`
+- `EXTCODEHASH`
+- `BLOCKHASH`
+- `COINBASE`
+- `TIMESTAMP`
+- `NUMBER`
+- `DIFFICULTY`
+- `GASLIMIT`
+- `GASPRICE`
+- `CREATE`
+- `CREATE2`
+- `CALLCODE`
+- `DELEGATECALL`
+- `STATICCALL`
+- `SELFDESTRUCT`
+- `SELFBALANCE`
+- `SSTORE`
+- `SLOAD`
+- `CHAINID`
+- `CALLER`\*
+- `CALL`\*
+- `REVERT`\*
+
+\* The `CALLER`, `CALL`, and `REVERT` opcodes are also banned, except in the special case that they appear as part of one of the following "magic strings" of bytecode:
+
+1. `CALLER PUSH1 0x00 SWAP1 GAS CALL PC PUSH1 0x0E ADD JUMPI RETURNDATASIZE PUSH1 0x00 DUP1 RETURNDATACOPY RETURNDATASIZE PUSH1 0x00 REVERT JUMPDEST RETURNDATASIZE PUSH1 0x01 EQ ISZERO PC PUSH1 0x0a ADD JUMPI PUSH1 0x01 PUSH1 0x00 RETURN JUMPDEST`
+2. `CALLER POP PUSH1 0x00 PUSH1 0x04 GAS CALL`
+
+The first magic string MUST:
+
+**TODO**
+
+The second magic string does this:
+
+## Defining the OVM Sandbox
+
+The OVM Sandbox consists of:
+
+- The Execution Manager
+- The State Manager
+- The Safety Cache and Safety Checker
+- The
+
+## Transaction lifecycle
+
+[`TRANSACTION`s](./../data-structures.md#transaction) submitted to L2 (via Transaction Queue, Sequencer or other source) have a data-structure similar to the format of L1 Transactions.
+
+### 1. Modify to ensure the Execution Manager is called first
+
+All transactions begin as calls to the Execution Manager contract.
+
+Thus clients (the Sequencer or Verifiers) MUST modify the `Transaction` with the following modifications:
+
+1. Replace the `to` field with the Execution Manager’s address.
+2. Encode the `data` field as arguments to `run()`.
+
+```jsx
+function run(
+  Transaction _transaction,
+  address _ovmStateManager
+)
+```
+
+Where the parameters are:
+
+- `Transaction _transaction`:
+- `address _ovmStateManager`:
+
+Importantly, the `Transaction` parameter includes all the contextual information (ie. `ovmTIMESTAMP`, `ovmBLOCKNUMBER`, `ovmL1QUEUEORIGIN`, `ovmL1TXORIGIN`, `ovmGASLIMIT`) which will be made available to the execution environment.
+
+### 2. OVM Messages via the Sequencer Entrypoint
+
+For **Sequencer transactions only**, the `Transaction.entrypoint` SHOULD be the Sequencer Entrypoint (or simply Entrypoint) contract. In order to achieve this, the Sequencer MUST modify the transaction's `to` field to the address of the Entrypoint.
+
+The Entrypoint contract accepts a more efficient compressed calldata format. This is done at a low level, using the contract's fallback function, which expects an RLP-encoded EIP155 transaction as input.
+
+The Entrypoint then:
+
+- decodes the input to extract the hash, and signature of [`EIP155Transaction`](#eip155transaction).
+- calculates an address using `ecrecover()`
+- checks for the existence of a contract at that address
+  - calls `ovmCREATEEOA` to ensure the necessary 'Account' contract exists.
+- initiates an `ovmCALL` to the 'Account' contract's `execute()` function.
+
+### 3. Execution Proceeds within the Sandbox
+
+Given the guarantees provided by the SafetyChecker contract, henceforth all calls to overridden opcodes will be routed through the Execution Manager.
+
+## Exception handling within the OVM
+
+It is critical to handle different exceptions properly during execution.
+
+### Invalid transactions
+
+If a transaction (or more generally a call to `run()`) is 'invalid', the Execution Manager's run function should `RETURN` prior to initiating the first `ovmCALL`.
+
+Invalid calls to to run include calls which:
+
+- don't change the context from its default values
+- have a `_gasLimit` outside the minimum and maximum transaction gas limits
+
+### Revert
+
+Refer to Data Structures spec for a description of [`RevertFlag`](./../data-structures.md#revertflag-enum) enum fields.
+
+## Gas Considerations
+
+### Epoch limitations
+
+The OVM does not have blocks, it just maintains an ordered list of transactions. Because of this, there is no notion of a block gas limit; instead, the overall gas consumption is rate limited based on time segments, called epochs8. Before a transaction is executed, there’s a check to see if a new epoch needs to be started, and after execution its gas consumption is added on the cumulative gas used for that epoch. There is a separate gas limit per epoch for sequencer submitted transactions and “L1 to L2” transactions. Any transactions exceeding the gas limit for an epoch return early. This implies that an operator can post several transactions with varying timestamps in one on-chain batch (timestamps are defined by the sequencer, with some restrictions which we explain in the “Data Availability Batches” section).
+
+### GAS Metering
+
+Notably, the `GAS` opcode is not disallowed or overridden. This enables us to use the EVM's built in gas metering, but also creates an attack vector in the case that fees diverge on L1 and L2.
+
+An important property to maintain is that the amount of gas passed to `run()`'s first `ovmCALL` is deterministic, and that within that call-frame, the `GAS` value remains deterministic. Assuming L2 geth is in consensus with L1 geth, and no _other_ L1 context is exposed to the OVM, this property should follow.
+
+### Nuisance Gas
+
+Nuisance-gas is used to enforce an upper-bound on the net gas cost of fraud proofs, by charging a fee for any operation that increases the number of accounts and storage slots which require proving in either the pre or post-state.
+
+Nuisance-gas is initialized in `run()` to be equal to the transaction's `gasLimit`, but from then on the two values are treated independently.
+
+A nuisance gas fee is charged on the following OVM operations the first time they occur:
+
+- a new account is loaded
+  - the base fee is `MIN_NUISANCE_GAS_PER_CONTRACT = 30000`
+  - the variable fee is `NUISANCE_GAS_PER_CONTRACT_BYTE = 100`
+- a new storage slot is read from
+
+  - the fee is `NUISANCE_GAS_SLOAD = 20000`
+
+- a new storage slot is written to
+  - the fee is `NUISANCE_GAS_SSTORE = 20000`
+
+If a message tries to use more nuisance gas than allowed in the message’s context, execution reverts.

specs/protocol/components/predeploys.md

+### OVM_DeployerWhitelist
+
+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.
+
+### OVM_ETH
+
+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.
+
+### OVM_L1MessageSender
+
+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.
+
+### OVM_L2ToL1MessagePasser
+
+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.
+
+### OVM_ProxySequencerEntrypoint
+
+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.
+
+### OVM_SequencerEntrypoint
+
+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.
+
+### ERC1820Registry
+
+This contract has been included as a popular standard which MUST be deployed at a specific address using CREATE2. This is not achievable in the OVM as the bytecode will not be a perfect match.
+See EIP-1820 for more information.

specs/protocol/components/verification.md

+# Fraud Proving
+
+This document is a WIP. It is kept here to maintain a consistent structure mirroring the [implementation directory](../../../contracts/contracts/optimistic-ethereum/OVM/).

specs/protocol/glossary.md

+# Glossary
+
+The following definitions are intended only to disambiguate some of the terms and abbreviations specific to Optimistic Ethereum protocol. They are intentionally kept incomplete, as they are described in more detail elsewhere within this specification.
+
+## General concepts
+
+- **Optimistic Rollup (ORU):** A design pattern using fraud proofs to enforce security assumptions on a layer 2 blockchain.
+- **Optimistic Ethereum (OE):** Refers to the protocol described within this specification. An Optimistic Rollup implementation
+- **Optimistic Virtual Machine (OVM):** A 'containerized' virtual machine designed run on the Ethereum Virtual Machine (EVM), and mirror the functionality and behavior of the EVM.
+- **Domain:** A synchronous execution environment. Typically either the Ethereum Mainnet or Optimistic Ethereum.
+- **Layer 1 (L1):** Typically refers to the Ethereum Mainnet. More generally the base chain which provides security to L2.
+- **Layer 2 (L2):** Typically refers to the Optimistic Ethereum Rollup. More generally the chain which depends on L1 for security.
+
+## OE System Components
+
+- **Canonical Transaction Chain (CTC):** The chain of transactions executed on the Rollup chain.
+- **State Commitment Chain (SCC):** The chain of state roots resulting from the execution of each transaction.
+- **State Transitioner (ST):** During a fraud proof, this contract manages the setup of the prestate, execution of the transaction, and computation of the poststate.
+- **Execution Manager (EM)**: The contract defining the OVM operations necessary to override EVM operations.
+- **State Manager (SM):** The contract which manages a remapping of L2 to L1 addresses.
+- **Fraud Prover:** The contract used to initiate and adjudicate a fraud proof.
+- **Bond Manager:** The contract which accepts the collateral deposit required to act as a state proposer.
+- **Cross Domain Messenger (xDM):** The pair of contracts used to pass messages between L1 and L2. These contracts are sometimes referred to as the L1xDM, and L2xDM.
+
+## Implementation Specific Concepts
+
+- **The Queue** / **Enqueued Transactions:** The Queue is an append only list of transaction on layer 1. Enqueued transactions must be added to the L2 chain within the Force Inclusion Period.
+- **Force Inclusion Period:** The duration of time in which the Sequencer may still insert other transactions before an Enqueued Transaction is added to the CTC.
+- **Stale transactions:** Enqueued transactions which have not yet been added to the Canonical Transaction Chain.
+- **Batching:** The act of 'rolling up' or Merkleizing data for efficient on-chain storage, while making the data available in order to prove properties of the L2 state.
+- **Safe/Unsafe opcodes:** Unsafe opcodes are those which would return a different value when executed on L1 or L2, and thus invalidate the property of deterministic execution.
+- **Magic Strings:** The specific bytecode strings which are allowable despite containing unsafe opcodes, which force contracts to call to the Execution Manager.
+- **Source** or **Feed:** The origin of a transaction, currently either the Sequencer, or Transaction Queue.

yarn.lock

@@ -10177,16 +10177,16 @@ prepend-http@^2.0.0:
   resolved "https://registry.yarnpkg.com/prepend-http/-/prepend-http-2.0.0.tgz#e92434bfa5ea8c19f41cdfd401d741a3c819d897"
   integrity sha1-6SQ0v6XqjBn0HN/UAddBo8gZ2Jc=
 
+prettier@2.2.1, prettier@^2.1.2, prettier@^2.2.1:
+  version "2.2.1"
+  resolved "https://registry.yarnpkg.com/prettier/-/prettier-2.2.1.tgz#795a1a78dd52f073da0cd42b21f9c91381923ff5"
+  integrity sha512-PqyhM2yCjg/oKkFPtTGUojv7gnZAoG80ttl45O6x2Ug/rMJw4wcc9k6aaf2hibP7BGVCCM33gZoGjyvt9mm16Q==
+
 prettier@^1.14.2, prettier@^1.16.4, prettier@^1.19.1:
   version "1.19.1"
   resolved "https://registry.yarnpkg.com/prettier/-/prettier-1.19.1.tgz#f7d7f5ff8a9cd872a7be4ca142095956a60797cb"
   integrity sha512-s7PoyDv/II1ObgQunCbB9PdLmUcBZcnWOcxDh7O0N/UwDEsHyqkW+Qh28jW+mVuCdx7gLB0BotYI1Y6uI9iyew==
 
-prettier@^2.1.2, prettier@^2.2.1:
-  version "2.2.1"
-  resolved "https://registry.yarnpkg.com/prettier/-/prettier-2.2.1.tgz#795a1a78dd52f073da0cd42b21f9c91381923ff5"
-  integrity sha512-PqyhM2yCjg/oKkFPtTGUojv7gnZAoG80ttl45O6x2Ug/rMJw4wcc9k6aaf2hibP7BGVCCM33gZoGjyvt9mm16Q==
-
 private@^0.1.6, private@^0.1.8:
   version "0.1.8"
   resolved "https://registry.yarnpkg.com/private/-/private-0.1.8.tgz#2381edb3689f7a53d653190060fcf822d2f368ff"