specs: system configuration contract and derivation [bedrock] (#3831)

* specs: system configuration contract and derivation

* specs: clarify system config version 0 and receipt processing

* specs: system config grammar and wording fixes

specs/deposits.md

@@ -214,9 +214,20 @@ A predeployed contract on L2 at address `0x4200000000000000000000000000000000000
 certain block variables from the corresponding L1 block in storage, so that they may be accessed
 during the execution of the subsequent deposited transactions.
 
-Apart from the regular L1 attributes, a `sequenceNumber` attribute is stored.
-This equals the L2 block number relative to the start of the epoch, i.e. the L2 block distance to the
-L2 block height that the L1 attributes last changed, and reset to 0 at the start of a new epoch.
+The predeploy stores the following values:
+
+- L1 block attributes:
+  - `number` (`uint64`)
+  - `timestamp` (`uint64`)
+  - `basefee` (`uint256`)
+  - `hash` (`bytes32`)
+- `sequenceNumber` (`uint64`): This equals the L2 block number relative to the start of the epoch,
+  i.e. the L2 block distance to the L2 block height that the L1 attributes last changed,
+  and reset to 0 at the start of a new epoch.
+- System configurables tied to the L1 block, see [System configuration specification](./system_config.md):
+  - `batcherHash` (`bytes32`): A versioned commitment to the batch-submitter(s) currently operating.
+  - `l1FeeOverhead` (`uint256`): The L1 fee overhead to apply to L1 cost computation of transactions in this L2 block.
+  - `l1FeeScalar` (`uint256`): The L1 fee scalar to apply to L1 cost computation of transactions in this L2 block.
 
 The contract implements an authorization scheme, such that it only accepts state-changing calls from
 the [depositor account][depositor-account].

specs/derivation.md

@@ -44,6 +44,7 @@
 [g-l1-origin]: glossary.md#l1-origin
 [g-deposit-tx-type]: glossary.md#deposited-transaction-type
 [g-finalized-l2-head]: glossary.md#finalized-l2-head
+[g-system-config]: glossary.md#system-configuration
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -302,8 +303,9 @@ Unknown versions make the batcher transaction invalid (it must be ignored by the
 All frames in a batcher transaction must be parseable. If any one frame fails to parse, the all frames in the
 transaction are rejected.
 
-> **TODO** specify batcher authentication (i.e. where do we store / make available the public keys of authorize batcher
-> signers)
+Batch transactions are authenticated by verifying that the `to` address of the transaction matches the batch inbox
+address, and the `from` address matches the batch-sender address in the [system configuration][g-system-config] at the
+time of the L1 block that the transaction data is read from.
 
 ### Frame Format
 
@@ -457,6 +459,9 @@ Let's briefly describe each stage of the pipeline.
 In the *L1 Traversal* stage, we simply read the header of the next L1 block. In normal operations, these will be new
 L1 blocks as they get created, though we can also read old blocks while syncing, or in case of an L1 [re-org][g-reorg].
 
+Upon traversal of the L1 block, the [system configuration][g-system-config] copy used by the L1 retrieval stage is
+updated, such that the batch-sender authentication is always accurate to the exact L1 block that is read by the stage.
+
 ### L1 Retrieval
 
 In the *L1 Retrieval* stage, we read the block we get from the outer stage (L1 traversal), and extract data for it. In
@@ -622,6 +627,9 @@ the [`PayloadAttributes`][g-payload-attr] structure. Such a structure encodes th
 a block, as well as other block inputs (timestamp, fee recipient, etc). Payload attributes derivation is detailed in the
 section [Deriving Payload Attributes section][deriving-payload-attr] below.
 
+This stage maintains its own copy of the [system configuration][g-system-config], independent of the L1 retrieval stage.
+The system configuration is updated with L1 log events whenever the L1 epoch referenced by the batch input changes.
+
 ### Engine Queue
 
 In the *Engine Queue* stage, the previously derived `PayloadAttributes` structures are buffered and sent to the

specs/glossary.md

@@ -44,6 +44,7 @@
   - [Channel Timeout](#channel-timeout)
 - [L2 Chain Derivation](#l2-chain-derivation)
   - [L2 Derivation Inputs](#l2-derivation-inputs)
+  - [System Configuration](#system-configuration)
   - [Payload Attributes](#payload-attributes)
   - [L2 Genesis Block](#l2-genesis-block)
   - [L2 Chain Inception](#l2-chain-inception)
@@ -524,6 +525,16 @@ L2 derivation inputs include:
   - basefee
 - [deposits] (as log data)
 - [sequencer batches][sequencer-batch] (as transaction data)
+- [System configuration][system-config] updates (as log data)
+
+## System Configuration
+
+[system-config]: glossary.md#system-configuration
+
+This term refers to the collection of dynamically configurable rollup parameters maintained
+by the [`SystemConfig`](./system_config.md) contract on L1 and read by the L2 [derivation] process.
+These parameters enable keys to be rotated regularly and external cost parameters to be adjusted
+without the network upgrade overhead of a hardfork.
 
 ## Payload Attributes
 

specs/system_config.md

+# System Config
+
+<!-- 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**
+
+- [System config contents (version 0)](#system-config-contents-version-0)
+  - [`batcherHash` (`bytes32`)](#batcherhash-bytes32)
+  - [`l1FeeOverhead` and `l1FeeScalar` (`uint256,uint256`)](#l1feeoverhead-and-l1feescalar-uint256uint256)
+- [Writing the system config](#writing-the-system-config)
+- [Reading the system config](#reading-the-system-config)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+The `SystemConfig` is a contract on L1 that can emit rollup configuration changes as log events.
+The rollup [block derivation process](./derivation.md) picks up on these log events and applies the changes.
+
+## System config contents (version 0)
+
+Version 0 of the system configuration contract defines the following parameters:
+
+### `batcherHash` (`bytes32`)
+
+A versioned hash of the current authorized batcher sender(s), to rotate keys as batch-submitter.
+The first byte identifies the version.
+
+Version `0` embeds the current batch submitter ethereum address (`bytes20`) in the last 20 bytes of the versioned hash.
+
+In the future this versioned hash may become a commitment to a more extensive configuration,
+to enable more extensive redundancy and/or rotation configurations.
+
+### `l1FeeOverhead` and `l1FeeScalar` (`uint256,uint256`)
+
+The L1 fee parameters, also known as Gas Price Oracle (GPO) parameters,
+are updated in conjunction and apply new L1 costs to the L2 transactions.
+
+## Writing the system config
+
+The `SystemConfig` contract applies authentication to all writing contract functions,
+the configuration management can be configured to be any type of ethereum account or contract.
+
+On a write, an event is emitted for the change to be picked up by the L2 system,
+and a copy of the new written configuration variable is retained in L1 state to read with L1 contracts.
+
+## Reading the system config
+
+A rollup node initializes its derivation process by finding a starting point based on its past L2 chain:
+
+- When started from L2 genesis, the initial system configuration is retrieved from the rollup chain configuration.
+- When started from an existing L2 chain, a previously included L1 block is determined as derivation starting point,
+  and the system config can thus be retrieved from the last L2 block that referenced the L1 block as L1 origin:
+  - `batcherHash`, `l1FeeOverhead` and `l1FeeScalar` are retrieved from the L1 block info transaction.
+  - other future variables may also be retrieved from other contents of the L2 block, such as the header.
+
+After preparing the initial system configuration for the given L1 starting input,
+the system configuration is updated by processing all receipts from each new L1 block.
+
+The contained log events are filtered and processed as follows:
+
+- the log event contract address must match the rollup `SystemConfig` deployment
+- the first log event topic must match the ABI hash of `ConfigUpdate(uint256,uint8,bytes)`
+- the second topic determines the version. Unknown versions are critical derivation errors.
+- the third topic determines the type of update. Unknown types are critical derivation errors.
+- the remaining event data is opaque, encoded as ABI bytes (i.e. includes offset and length data),
+  and encodes the configuration update. In version `0` the following types are supported:
+  - type `0`: `batcherHash` overwrite, as `bytes32` payload.
+  - type `1`: `l1FeeOverhead` and `l1FeeScalar` overwrite, as two packed `uint256` entries.
+
+Note that individual derivation stages may be processing different L1 blocks,
+and should thus maintain individual system configuration copies,
+and apply the event-based changes as the stage traverses to the next L1 block.