spec: derivation spec rework (#2855)

* batch derivation spec draft

* add diagrams, fix recovery-from-reorg wording

* update spec to cover channel ID timestamp

* specs: update batch derivation diagrams

* simplified overview draft + greatly expand glossary

* section on batch submission an encoding

* stages explanation

* edit resetting part of the spec

* rework pipeline description (& more)

* incorporate review feedback

* recover lost change

* rework payload attributes derivation section

* specs: toc fix

* specs: misc lint fixes

* specs/meta: toc fix
Co-authored-by: protolambda <proto@protolambda.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

specs/bridges.md

@@ -4,9 +4,8 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Standard Bridges](#standard-bridges)
-  - [Token Depositing](#token-depositing)
-  - [Upgradability](#upgradability)
+- [Token Depositing](#token-depositing)
+- [Upgradability](#upgradability)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 

specs/deposits.md

@@ -22,22 +22,21 @@ with the authorization and validation conditions on L2.
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Deposits](#deposits)
-  - [The Deposited Transaction Type](#the-deposited-transaction-type)
-    - [Source hash computation](#source-hash-computation)
-    - [Kinds of Deposited Transactions](#kinds-of-deposited-transactions)
-    - [Validation and Authorization of Deposited Transactions](#validation-and-authorization-of-deposited-transactions)
-    - [Execution](#execution)
-      - [Nonce Handling](#nonce-handling)
-  - [L1 Attributes Deposited Transaction](#l1-attributes-deposited-transaction)
-  - [Special Accounts on L2](#special-accounts-on-l2)
-    - [L1 Attributes Depositor Account](#l1-attributes-depositor-account)
-    - [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract)
-      - [L1 Attributes Predeployed Contract: Reference Implementation](#l1-attributes-predeployed-contract-reference-implementation)
-  - [User-Deposited Transactions](#user-deposited-transactions)
-    - [Deposit Contract](#deposit-contract)
-      - [Address Aliasing](#address-aliasing)
-      - [Deposit Feed Contract: Reference Implementation](#deposit-feed-contract-reference-implementation)
+- [The Deposited Transaction Type](#the-deposited-transaction-type)
+  - [Source hash computation](#source-hash-computation)
+  - [Kinds of Deposited Transactions](#kinds-of-deposited-transactions)
+  - [Validation and Authorization of Deposited Transactions](#validation-and-authorization-of-deposited-transactions)
+  - [Execution](#execution)
+    - [Nonce Handling](#nonce-handling)
+- [L1 Attributes Deposited Transaction](#l1-attributes-deposited-transaction)
+- [Special Accounts on L2](#special-accounts-on-l2)
+  - [L1 Attributes Depositor Account](#l1-attributes-depositor-account)
+  - [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract)
+    - [L1 Attributes Predeployed Contract: Reference Implementation](#l1-attributes-predeployed-contract-reference-implementation)
+- [User-Deposited Transactions](#user-deposited-transactions)
+  - [Deposit Contract](#deposit-contract)
+    - [Address Aliasing](#address-aliasing)
+    - [Deposit Feed Contract: Reference Implementation](#deposit-feed-contract-reference-implementation)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 

specs/exec-engine.md

@@ -4,18 +4,17 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [L2 Execution Engine](#l2-execution-engine)
-  - [Deposited transaction processing](#deposited-transaction-processing)
-    - [Deposited transaction boundaries](#deposited-transaction-boundaries)
-  - [Engine API](#engine-api)
-    - [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1)
-      - [Extended PayloadAttributesV1](#extended-payloadattributesv1)
-    - [`engine_newPayloadV1`](#engine_newpayloadv1)
-    - [`engine_getPayloadV1`](#engine_getpayloadv1)
-  - [Networking](#networking)
-  - [Sync](#sync)
-    - [Happy-path sync](#happy-path-sync)
-    - [Worst-case sync](#worst-case-sync)
+- [Deposited transaction processing](#deposited-transaction-processing)
+  - [Deposited transaction boundaries](#deposited-transaction-boundaries)
+- [Engine API](#engine-api)
+  - [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1)
+    - [Extended PayloadAttributesV1](#extended-payloadattributesv1)
+  - [`engine_newPayloadV1`](#engine_newpayloadv1)
+  - [`engine_getPayloadV1`](#engine_getpayloadv1)
+- [Networking](#networking)
+- [Sync](#sync)
+  - [Happy-path sync](#happy-path-sync)
+  - [Worst-case sync](#worst-case-sync)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 

specs/guaranteed-gas-market.md

@@ -4,10 +4,9 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Guaranteed Gas Fee Market](#guaranteed-gas-fee-market)
-  - [Gas Stipend](#gas-stipend)
-  - [Limiting Guaranteed Gas](#limiting-guaranteed-gas)
-  - [Rationale for burning L1 Gas](#rationale-for-burning-l1-gas)
+- [Gas Stipend](#gas-stipend)
+- [Limiting Guaranteed Gas](#limiting-guaranteed-gas)
+- [Rationale for burning L1 Gas](#rationale-for-burning-l1-gas)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 

specs/introduction.md

@@ -4,21 +4,20 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Introduction](#introduction)
-  - [Foundations](#foundations)
-    - [What is Ethereum scalability?](#what-is-ethereum-scalability)
-    - [What is an Optimistic Rollup?](#what-is-an-optimistic-rollup)
-    - [What is EVM Equivalence?](#what-is-evm-equivalence)
-    - [🎶 All together now 🎶](#-all-together-now-)
-  - [Protocol Guarantees](#protocol-guarantees)
-  - [Network Participants](#network-participants)
-    - [Users](#users)
-    - [Sequencers](#sequencers)
-    - [Verifiers](#verifiers)
-  - [Key Interaction Diagrams](#key-interaction-diagrams)
-    - [Depositing and Sending Transactions](#depositing-and-sending-transactions)
-    - [Withdrawing](#withdrawing)
-  - [Next Steps](#next-steps)
+- [Foundations](#foundations)
+  - [What is Ethereum scalability?](#what-is-ethereum-scalability)
+  - [What is an Optimistic Rollup?](#what-is-an-optimistic-rollup)
+  - [What is EVM Equivalence?](#what-is-evm-equivalence)
+  - [🎶 All together now 🎶](#-all-together-now-)
+- [Protocol Guarantees](#protocol-guarantees)
+- [Network Participants](#network-participants)
+  - [Users](#users)
+  - [Sequencers](#sequencers)
+  - [Verifiers](#verifiers)
+- [Key Interaction Diagrams](#key-interaction-diagrams)
+  - [Depositing and Sending Transactions](#depositing-and-sending-transactions)
+  - [Withdrawing](#withdrawing)
+- [Next Steps](#next-steps)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 

specs/messengers.md

@@ -4,13 +4,12 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Cross Domain Messengers](#cross-domain-messengers)
-  - [Message Passing](#message-passing)
-  - [Upgradability](#upgradability)
-  - [Message Versioning](#message-versioning)
-    - [Message Version 0](#message-version-0)
-    - [Message Version 1](#message-version-1)
-  - [Backwards Compatibility Notes](#backwards-compatibility-notes)
+- [Message Passing](#message-passing)
+- [Upgradability](#upgradability)
+- [Message Versioning](#message-versioning)
+  - [Message Version 0](#message-version-0)
+  - [Message Version 1](#message-version-1)
+- [Backwards Compatibility Notes](#backwards-compatibility-notes)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 

specs/meta/devnet.md

 # Bedrock Local Devnet Setup
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Bedrock Local Devnet Setup](#bedrock-local-devnet-setup)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 You can spin up a local devnet via `docker-compose`.
 For convenience, we have defined `make` targets to start and stop the devnet with a single command.
 To run the devnet, you will need `docker` and `docker-compose` installed.

specs/meta/versioning.md

 # Versioning
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Go modules](#go-modules)
+  - [versioning process](#versioning-process)
+- [Typescript](#typescript)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Go modules
 
 Go modules that are currently versioned:

specs/overview.md

@@ -4,19 +4,18 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Optimism Overview](#optimism-overview)
-  - [Architecture Design Goals](#architecture-design-goals)
-  - [Components](#components)
-    - [L1 Components](#l1-components)
-    - [L2 Components](#l2-components)
-    - [Transaction/Block Propagation](#transactionblock-propagation)
-  - [Key Interactions In Depth](#key-interactions-in-depth)
-    - [Deposits](#deposits)
-    - [Block Derivation](#block-derivation)
-      - [Overview](#overview)
-      - [Epochs and the Sequencing Window](#epochs-and-the-sequencing-window)
-      - [Block Derivation Loop](#block-derivation-loop)
-    - [Engine API](#engine-api)
+- [Architecture Design Goals](#architecture-design-goals)
+- [Components](#components)
+  - [L1 Components](#l1-components)
+  - [L2 Components](#l2-components)
+  - [Transaction/Block Propagation](#transactionblock-propagation)
+- [Key Interactions In Depth](#key-interactions-in-depth)
+  - [Deposits](#deposits)
+  - [Block Derivation](#block-derivation)
+    - [Overview](#overview)
+    - [Epochs and the Sequencing Window](#epochs-and-the-sequencing-window)
+    - [Block Derivation Loop](#block-derivation-loop)
+  - [Engine API](#engine-api)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 

specs/predeploys.md

@@ -4,21 +4,20 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Predeploys](#predeploys)
-  - [Overview](#overview)
-  - [OVM\_L2ToL1MessagePasser](#ovm_l2tol1messagepasser)
-  - [OVM\_DeployerWhitelist](#ovm_deployerwhitelist)
-  - [OVM\_ETH](#ovm_eth)
-  - [WETH9](#weth9)
-  - [L2CrossDomainMessenger](#l2crossdomainmessenger)
-  - [L2StandardBridge](#l2standardbridge)
-  - [SequencerFeeVault](#sequencerfeevault)
-  - [OptimismMintableERC20Factory](#OptimismMintableERC20Factory)
-  - [L1BlockNumber](#l1blocknumber)
-  - [OVM\_GasPriceOracle](#ovm_gaspriceoracle)
-  - [Reserved System Address 1](#reserved-system-address-1)
-  - [Reserved System Address 2](#reserved-system-address-2)
-  - [L1Block](#l1block)
+- [Overview](#overview)
+- [OVM\_L2ToL1MessagePasser](#ovm%5C_l2tol1messagepasser)
+- [OVM\_DeployerWhitelist](#ovm%5C_deployerwhitelist)
+- [OVM\_ETH](#ovm%5C_eth)
+- [WETH9](#weth9)
+- [L2CrossDomainMessenger](#l2crossdomainmessenger)
+- [L2StandardBridge](#l2standardbridge)
+- [SequencerFeeVault](#sequencerfeevault)
+- [OptimismMintableERC20Factory](#optimismmintableerc20factory)
+- [L1BlockNumber](#l1blocknumber)
+- [OVM\_GasPriceOracle](#ovm%5C_gaspriceoracle)
+- [Reserved System Address 1](#reserved-system-address-1)
+- [Reserved System Address 2](#reserved-system-address-2)
+- [L1Block](#l1block)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 

specs/proposals.md

@@ -9,14 +9,13 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [L2 Output Root Proposals Specification](#l2-output-root-proposals-specification)
-  - [Proposing L2 Output Commitments](#proposing-l2-output-commitments)
-  - [L2 Output Commitment Construction](#l2-output-commitment-construction)
-  - [L2 Output Oracle Smart Contract](#l2-output-oracle-smart-contract)
-  - [Security Considerations](#security-considerations)
-    - [L1 Reorgs](#l1-reorgs)
-  - [Summary of Definitions](#summary-of-definitions)
-    - [Constants](#constants)
+- [Proposing L2 Output Commitments](#proposing-l2-output-commitments)
+- [L2 Output Commitment Construction](#l2-output-commitment-construction)
+- [L2 Output Oracle Smart Contract](#l2-output-oracle-smart-contract)
+- [Security Considerations](#security-considerations)
+  - [L1 Reorgs](#l1-reorgs)
+- [Summary of Definitions](#summary-of-definitions)
+  - [Constants](#constants)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 

specs/rollup-node-p2p.md

@@ -29,35 +29,34 @@ and are adopted by several other blockchains, most notably the [L1 consensus lay
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Rollup-node P2P interface](#rollup-node-p2p-interface)
-  - [P2P configuration](#p2p-configuration)
-    - [Identification](#identification)
-    - [Discv5](#discv5)
-      - [Structure](#structure)
-    - [LibP2P](#libp2p)
-      - [Transport](#transport)
-      - [Dialing](#dialing)
-      - [NAT](#nat)
-      - [Peer management](#peer-management)
-      - [Transport security](#transport-security)
-      - [Protocol negotiation](#protocol-negotiation)
-      - [Identify](#identify)
-      - [Ping](#ping)
-      - [Multiplexing](#multiplexing)
-      - [GossipSub](#gossipsub)
-        - [Content-based message identification](#content-based-message-identification)
-        - [Message compression and limits](#message-compression-and-limits)
-        - [Message ID computation](#message-id-computation)
-      - [Heartbeat and parameters](#heartbeat-and-parameters)
-      - [Topic configuration](#topic-configuration)
-      - [Topic validation](#topic-validation)
-  - [Gossip Topics](#gossip-topics)
-    - [`blocks`](#blocks)
-      - [Block encoding](#block-encoding)
-      - [Block signatures](#block-signatures)
-      - [Block validation](#block-validation)
-        - [Block processing](#block-processing)
-        - [Block topic scoring parameters](#block-topic-scoring-parameters)
+- [P2P configuration](#p2p-configuration)
+  - [Identification](#identification)
+  - [Discv5](#discv5)
+    - [Structure](#structure)
+  - [LibP2P](#libp2p)
+    - [Transport](#transport)
+    - [Dialing](#dialing)
+    - [NAT](#nat)
+    - [Peer management](#peer-management)
+    - [Transport security](#transport-security)
+    - [Protocol negotiation](#protocol-negotiation)
+    - [Identify](#identify)
+    - [Ping](#ping)
+    - [Multiplexing](#multiplexing)
+    - [GossipSub](#gossipsub)
+      - [Content-based message identification](#content-based-message-identification)
+      - [Message compression and limits](#message-compression-and-limits)
+      - [Message ID computation](#message-id-computation)
+    - [Heartbeat and parameters](#heartbeat-and-parameters)
+    - [Topic configuration](#topic-configuration)
+    - [Topic validation](#topic-validation)
+- [Gossip Topics](#gossip-topics)
+  - [`blocks`](#blocks)
+    - [Block encoding](#block-encoding)
+    - [Block signatures](#block-signatures)
+    - [Block validation](#block-validation)
+      - [Block processing](#block-processing)
+      - [Block topic scoring parameters](#block-topic-scoring-parameters)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 

specs/withdrawals.md

@@ -33,19 +33,18 @@ finalization.
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Withdrawals](#withdrawals)
-  - [Withdrawal Flow](#withdrawal-flow)
-    - [On L2](#on-l2)
-    - [On L1](#on-l1)
-  - [The L2ToL1MessagePasser Contract](#the-l2tol1messagepasser-contract)
-    - [Addresses are not Aliased on Withdrawals](#addresses-are-not-aliased-on-withdrawals)
-  - [The Optimism Portal Contract](#the-optimism-portal-contract)
-  - [Withdrawal Verification and Finalization](#withdrawal-verification-and-finalization)
-  - [Security Considerations](#security-considerations)
-    - [Key Properties of Withdrawal Verification](#key-properties-of-withdrawal-verification)
-    - [Handling Successfully Verified Messages That Fail When Relayed](#handling-successfully-verified-messages-that-fail-when-relayed)
-  - [Summary of Definitions](#summary-of-definitions)
-    - [Constants](#constants)
+- [Withdrawal Flow](#withdrawal-flow)
+  - [On L2](#on-l2)
+  - [On L1](#on-l1)
+- [The L2ToL1MessagePasser Contract](#the-l2tol1messagepasser-contract)
+  - [Addresses are not Aliased on Withdrawals](#addresses-are-not-aliased-on-withdrawals)
+- [The Optimism Portal Contract](#the-optimism-portal-contract)
+- [Withdrawal Verification and Finalization](#withdrawal-verification-and-finalization)
+- [Security Considerations](#security-considerations)
+  - [Key Properties of Withdrawal Verification](#key-properties-of-withdrawal-verification)
+  - [Handling Successfully Verified Messages That Fail When Relayed](#handling-successfully-verified-messages-that-fail-when-relayed)
+- [Summary of Definitions](#summary-of-definitions)
+  - [Constants](#constants)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->