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,19 +22,18 @@ 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)
+- [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 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)
+- [User-Deposited Transactions](#user-deposited-transactions)
   - [Deposit Contract](#deposit-contract)
     - [Address Aliasing](#address-aliasing)
     - [Deposit Feed Contract: Reference Implementation](#deposit-feed-contract-reference-implementation)

specs/exec-engine.md

@@ -4,16 +4,15 @@
 <!-- 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 processing](#deposited-transaction-processing)
   - [Deposited transaction boundaries](#deposited-transaction-boundaries)
-  - [Engine API](#engine-api)
+- [Engine API](#engine-api)
   - [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1)
     - [Extended PayloadAttributesV1](#extended-payloadattributesv1)
   - [`engine_newPayloadV1`](#engine_newpayloadv1)
   - [`engine_getPayloadV1`](#engine_getpayloadv1)
-  - [Networking](#networking)
-  - [Sync](#sync)
+- [Networking](#networking)
+- [Sync](#sync)
   - [Happy-path sync](#happy-path-sync)
   - [Worst-case sync](#worst-case-sync)
 

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)
+- [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)
+- [Protocol Guarantees](#protocol-guarantees)
+- [Network Participants](#network-participants)
   - [Users](#users)
   - [Sequencers](#sequencers)
   - [Verifiers](#verifiers)
-  - [Key Interaction Diagrams](#key-interaction-diagrams)
+- [Key Interaction Diagrams](#key-interaction-diagrams)
   - [Depositing and Sending Transactions](#depositing-and-sending-transactions)
   - [Withdrawing](#withdrawing)
-  - [Next Steps](#next-steps)
+- [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 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)
+- [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,13 +4,12 @@
 <!-- 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)
+- [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)
+- [Key Interactions In Depth](#key-interactions-in-depth)
   - [Deposits](#deposits)
   - [Block Derivation](#block-derivation)
     - [Overview](#overview)

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,13 +9,12 @@
 <!-- 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)
+- [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)
+- [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,8 +29,7 @@ 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)
+- [P2P configuration](#p2p-configuration)
   - [Identification](#identification)
   - [Discv5](#discv5)
     - [Structure](#structure)
@@ -51,7 +50,7 @@ and are adopted by several other blockchains, most notably the [L1 consensus lay
     - [Heartbeat and parameters](#heartbeat-and-parameters)
     - [Topic configuration](#topic-configuration)
     - [Topic validation](#topic-validation)
-  - [Gossip Topics](#gossip-topics)
+- [Gossip Topics](#gossip-topics)
   - [`blocks`](#blocks)
     - [Block encoding](#block-encoding)
     - [Block signatures](#block-signatures)

specs/withdrawals.md

@@ -33,18 +33,17 @@ finalization.
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Withdrawals](#withdrawals)
-  - [Withdrawal Flow](#withdrawal-flow)
+- [Withdrawal Flow](#withdrawal-flow)
   - [On L2](#on-l2)
   - [On L1](#on-l1)
-  - [The L2ToL1MessagePasser Contract](#the-l2tol1messagepasser-contract)
+- [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)
+- [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)
+- [Summary of Definitions](#summary-of-definitions)
   - [Constants](#constants)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->