Merge pull request ethereum-optimism#117 from ethereum-optimism/ns/co…

…nsistent-rollup-spec

Make rollup node spec consistent with deposit spec

specs/deposits.md

@@ -4,10 +4,13 @@
 [transaction-type]: /glossary.md#transaction-type
 [derivation]:  /glossary.md#L2-chain-derivation
 [execution-engine]: /glossary.md#execution-engine
+[deposits]: /glossary.md#deposits
+[L1 attributes deposit]: /glossary.md#l1-attributes-deposit
+[transaction deposits]: /glossary.md#transaction-deposits
 
-Deposits are transactions which are initiated on L1, and executed on L2. This document outlines a new
-[transaction type][transaction-type] for deposits. It also describes how deposits are initiated on
-L1, along with the authorization and validation conditions on L2.
+[Deposits] are transactions which are initiated on L1, and executed on L2. This document outlines a
+new [transaction type][transaction-type] for deposits. It also describes how deposits are initiated
+on L1, along with the authorization and validation conditions on L2.
 
 ## The Deposit Transaction Type
 
@@ -16,7 +19,8 @@ L1, along with the authorization and validation conditions on L2.
 Deposit transactions have the following notable distinctions from existing transaction types:
 
 1. They are derived from Layer 1 blocks, and must be included as part of the protocol.
-2. They do not include signature validation (see [L1 transaction deposits][l1-transaction-deposits] for the rationale).
+2. They do not include signature validation (see [L1 transaction deposits][l1-transaction-deposits]
+   for the rationale).
 
 We define a new [EIP-2718] compatible transaction type with the prefix `0x7E`, and the following
 fields (rlp encoded in the order they appear here):
@@ -59,12 +63,13 @@ modifications to L1 client software and complexity in general.
 [authorization]: #validation-and-authorization-of-deposit-transaction-types
 
 As noted above, the deposit transaction type does not include a signature for validation. Rather,
-authorization is handled by the [L2 chain Derivation][derivation] process, which when
-correctly processed will only derive transactions with a `from` address attested to
-by the logs of the [L1 deposit feed contract][deposit-feed-contract].
+authorization is handled by the [L2 chain Derivation][derivation] process, which when correctly
+processed will only derive transactions with a `from` address attested to by the logs of the [L1
+deposit feed contract][deposit-feed-contract].
 
-In the event a deposit transaction is included which is not derived by the [execution engine][execution-engine]
-using the correct derivation algorithm, the resulting state transition would be invalid.
+In the event a deposit transaction is included which is not derived by the [execution
+engine][execution-engine] using the correct derivation algorithm, the resulting state transition
+would be invalid.
 
 ### Execution
 
@@ -99,7 +104,8 @@ tooling (such as wallets and block explorers).
 
 [l1-attributes-deposit]: #l1-attributes-deposit
 
-This is a deposit transaction sent to the [L1 attributes predeploy][predeploy] contract.
+An [L1 attributes deposit] is a deposit transaction sent to the [L1 attributes predeploy][predeploy]
+contract.
 
 This transaction MUST have the following values:
 
@@ -110,8 +116,9 @@ This transaction MUST have the following values:
 3. `mint` is `0`
 4. `value` is `0`
 5. `gasLimit` is set to the maximum available.
-6. `data` is an [ABI] encoded call to the [L1 attributes predeploy][predeploy] contract's `setL1BlockValues()`
-   function with correct values associated with the corresponding L1 block.
+6. `data` is an [ABI] encoded call to the [L1 attributes predeploy][predeploy] contract's
+   `setL1BlockValues()` function with correct values associated with the corresponding L1 block (cf.
+   [reference implementation][l1-attrib-ref-implem]).
 
    <!-- TODO: Define how this account pays gas on these transactions. -->
 
@@ -148,6 +155,8 @@ The contract has the following solidity interface, and can be interacted with ac
 
 #### L1 Attributes: Reference Implementation
 
+[l1-attrib-ref-implem]: #l1-attributes--reference-implementation
+
 A reference implementation of the L1 Attributes predeploy contract can be found in [L1Block.sol].
 
 [L1Block.sol]: /packages/contracts/contracts/L1Block.sol
@@ -161,8 +170,8 @@ The bytecode to add to the genesis file will be located in the `deployedBytecode
 
 [l1-transaction-deposits]: #l1-transaction-deposits
 
-L1 transaction deposits are [deposit transactions][deposit-transaction-type] generated by the
-[L2 Chain Derivation][derivation] process. The values of each transaction are determined by the
+L1 [transaction deposits] are [deposit transactions][deposit-transaction-type] generated by the [L2
+Chain Derivation][derivation] process. The values of each transaction are determined by the
 corresponding `TransactionDeposited` event emitted by the [deposit feed
 contract][deposit-feed-contract] on L1.
 
@@ -188,7 +197,8 @@ The deposit feed handles two special cases:
 
 1. A contract creation deposit, which is indicated by setting the `isCreation` flag to `true`.
    In the event that the `to` address is non-zero, the contract will revert.
-2. A call from a contract account, in which case the `from` value is transformed to its L2 [alias][address-aliasing].
+2. A call from a contract account, in which case the `from` value is transformed to its L2
+   [alias][address-aliasing].
 
 > **TODO** Define if/how ETH withdrawals occur.
 
@@ -197,10 +207,10 @@ The deposit feed handles two special cases:
 [address-aliasing]: #address-aliasing
 
 If the caller is not a contract, the address will be ed by adding
-`0x1111000000000000000000000000000000001111`. This prevents attacks in which a contract on L1
-has the same address as a contract on L2 but doesn't have the same code. We can safely ignore
-this for EOAs because they're guaranteed to have the same "code" (i.e. no code at all). This also
-makes it possible for users to interact with contracts on L2 even when the Sequencer is down.
+`0x1111000000000000000000000000000000001111`. This prevents attacks in which a contract on L1 has
+the same address as a contract on L2 but doesn't have the same code. We can safely ignore this for
+EOAs because they're guaranteed to have the same "code" (i.e. no code at all). This also makes it
+possible for users to interact with contracts on L2 even when the Sequencer is down.
 
 #### Deposit Feed: Reference Implementation
 

specs/glossary.md

@@ -20,9 +20,10 @@
   - [L2 Chain Derivation](#l2-chain-derivation)
   - [L2 Derivation Inputs](#l2-derivation-inputs)
   - [Payload Attributes](#payload-attributes)
-  - [L1 Attributes Transaction](#l1-attributes-transaction)
-  - [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract)
   - [Deposits](#deposits)
+  - [L1 Attributes Deposit](#l1-attributes-deposit)
+  - [Transaction Deposit](#transaction-deposit)
+  - [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract)
   - [Deposit Transaction Type](#deposit-transaction-type)
   - [Deposit Feed Contract](#deposit-feed-contract)
 - [Execution Engine Concepts](#execution-engine-concepts)
@@ -186,46 +187,67 @@ cf. [Execution Engine Specification](exec-engine.md)
 Payload attributes were historically called "L2 block inputs" in the L2 spec and you might still hear some people using
 this term.
 
-## L1 Attributes Transaction
+## Deposits
 
-[l1-attributes-tx]: /glossary.md#l1-attributes-transaction
+[deposits]: /glossary.md#deposits
 
-A transaction with an Optimism-specific transaction type, that is used to register the L1 block attributes
-(number, timestamp, ...) on L2.
+A deposit is an L2 transaction derived from an L1 block.
 
-The L1 attributes for a given L1 block can be read on L2 from the [L1 Attributes Predeployed
-Contract][l1-attr-predeploy].
+There are two kinds of deposits:
 
-cf. [L1 attributes transaction format](/rollup-node.md#payload-transaction-format) (in the section on [payload
-attributes])
+- [L1 Attributes Deposit][l1-attribute-tx], which submit the L1 block's attributes to the [L1 Attributes Predeployed
+  Contract][l1-attr-predeploy].
+- [Transaction Deposits][tx-deposits], which are transaction that have been submitted on L1, via a transaction sent to
+the [deposit feed contract][deposit-feed].
 
-> **TODO** We might want to move this the format spec to the execution engine.
+While transaction deposits are notably (but not only) used to "deposit" (bridge) ETH and tokens to L2, the word
+*deposit* should be understood as "a transaction *deposited* to L2 from L1".
 
-> **TODO** We might wish to make this a "normal transaction" if deposits end up
-> not carrying a signature.
+The term *deposit* performs the double duty of referring to both:
 
-## L1 Attributes Predeployed Contract
+1. The transaction information submitted on L1 to the [deposit feed contract][deposit-feed]. This is a kind of [L2
+   derivation input][deriv-input].
+2. The actual L2 transaction derived from this L1 input.
 
-[l1-attr-predeploy]: /glossary.md#l1-attributes-predeployed-contract
+Deposits are specified in the [deposits specification][deposits-spec].
 
-A [predeployed contract][predeploy] on L2 that can be used to retrieve the L1 block attributes of L1 blocks with a given
-block number or a given block hash.
+[deposits-spec]: deposits.md
 
-cf. [L1 Attributes Predeployed Contract Specification](TODO)
+## L1 Attributes Deposit
 
-> **TODO LINK** L1 attributes predeployed contract spec
+[l1-attributes-deposit]: /glossary.md#l1-attributes-deposit
 
-## Deposits
+A [deposit][deposits] that is used to register the L1 block attributes (number, timestamp, ...) on L2 via a call to the
+[L1 Attributes Predeployed Contract][l1-attr-predeploy]. That contract can then be used to read the the attributes of
+the L1 block corresponding to the current L2 block.
 
-[deposits]: /glossary.md#deposits
+L1 attributes deposits are specified in the [L1 Attributes Deposit][l1-attributes-tx-spec] section of the deposits
+specification.
+
+[l1-attributes-tx-spec]: deposits.md#l1-attributes-deposit
 
-A deposit is an L2 transaction that has been submitted on L1, via a transaction sent to the [deposit feed
+## Transaction Deposits
+
+[tx-deposits]: #transaction-deposits
+
+These [deposits] are transaction that have been submitted on L1, via a transaction sent to the [deposit feed
 contract][deposit-feed].
 
-While deposits are notably (but not only) used to "deposit" (bridge) ETH and tokens to L2, the word *deposit* should be
-understood as "a transaction *deposited* to L2".
+Transaction deposits are specified in the [Transaction Deposits][tx-deposits-spec] section of the deposits
+specification.
+
+[tx-deposits-spec]: deposits.md#l1-transaction-deposits
+
+## L1 Attributes Predeployed Contract
+
+[l1-attr-predeploy]: /glossary.md#l1-attributes-predeployed-contract
 
-Deposits are one kind of [L2 derivation input][deriv-input].
+A [predeployed contract][predeploy] on L2 that can be used to retrieve the L1 block attributes of L1 blocks with a given
+block number or a given block hash.
+
+cf. [L1 Attributes Predeployed Contract Specification](TODO)
+
+> **TODO LINK** L1 attributes predeployed contract spec
 
 ## Deposit Transaction Type