Isthmus: operator fee

specs/SUMMARY.md

@@ -56,6 +56,13 @@
       - [Predeploys](./protocol/holocene/predeploys.md)
       - [L1 Block Attributes](./protocol/holocene/l1-attributes.md)
       - [Configurability](./protocol/holocene/configurability.md)
+    - [Isthmus](./protocol/isthmus/overview.md)
+      - [Execution Engine](./protocol/isthmus/exec-engine.md)
+      - [L1 Block Attributes](./protocol/isthmus/l1-attributes.md)
+      - [Configurability](./protocol/isthmus/configurability.md)
+      - [Predeploys](./protocol/isthmus/predeploys.md)
+      - [System Config](./protocol/isthmus/system-config.md)
+
 - [Governance]()
   - [Governance Token](./governance/gov-token.md)
 - [Experimental]()

specs/protocol/holocene/configurability.md

@@ -58,7 +58,7 @@ The following `ConfigUpdate` enum is defined where the `CONFIG_VERSION` is `uint
 | `FEE_SCALARS` | `uint8(1)` | `(uint256(0x01) << 248) \| (uint256(_blobbasefeeScalar) << 32) \| _basefeeScalar` | Modifies the fee scalars |
 | `GAS_LIMIT` | `uint8(2)` | `abi.encode(uint64 _gasLimit)` | Modifies the L2 gas limit |
 | `UNSAFE_BLOCK_SIGNER` | `uint8(3)` | `abi.encode(address)` | Modifies the account that is authorized to progress the unsafe chain |
-| `EIP_1559_PARAMS` | `uint8(4)` | `uint256(uint64(_denominator)) << 32 | uint64(_elasticity)` | Modifies the EIP-1559 denominator and elasticity |
+| `EIP_1559_PARAMS` | `uint8(4)` | `uint256(uint64(_denominator)) << 32 \| uint64(_elasticity)` | Modifies the EIP-1559 denominator and elasticity |
 
 ### Initialization
 

specs/protocol/isthmus/configurability.md

@@ -0,0 +1,24 @@
+# Configurability
+
+<!-- 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**
+
+- [`SystemConfig`](#systemconfig)
+  - [`ConfigUpdate`](#configupdate)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## `SystemConfig`
+
+### `ConfigUpdate`
+
+The following `ConfigUpdate` enum is defined where the `CONFIG_VERSION` is `uint256(1)`:
+
+| Name | Value | Definition | Usage |
+| ---- | ----- | --- | -- |
+| `BATCHER` | `uint8(0)` | `abi.encode(address)` | Modifies the account that is authorized to progress the safe chain |
+| `FEE_SCALARS` | `uint8(1)` | `(uint256(0x01) << 248) \| (uint256(_configurablefeescalar) << 128 \| (uint256(_configurablefeeconstant) << 64 \| (uint256(_blobbasefeeScalar) << 32) \| _basefeeScalar` | Modifies the fee scalars |
+| `GAS_LIMIT` | `uint8(2)` | `abi.encode(uint64 _gasLimit)` | Modifies the L2 gas limit |
+| `UNSAFE_BLOCK_SIGNER` | `uint8(3)` | `abi.encode(address)` | Modifies the account that is authorized to progress the unsafe chain |
+| `EIP_1559_PARAMS` | `uint8(4)` | `uint256(uint64(_denominator)) << 32 \| uint64(_elasticity)` | Modifies the EIP-1559 denominator and elasticity |

specs/protocol/isthmus/exec-engine.md

@@ -0,0 +1,45 @@
+# L2 Execution Engine
+
+<!-- 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**
+
+- [Fees](#fees)
+  - [Configurable fees](#configurable-fees)
+    - [Configuring scalars](#configuring-scalars)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Fees
+
+New OP stack variants have different resource consumption patterns, and thus require a more flexible
+pricing model. To enable more customizable fee structures, Isthmus adds a new component to the fee
+calculation: the `ConfigurableFee`, which is parameterized by two scalars: the `configurableFeeScalar`
+and the `configurableFeeConstant`.
+
+### Configurable fees
+
+The configurable fee is set as follows:
+
+`configurableFee = gas_used * configurableFeeScalar + configurableFeeConstant`
+
+Where:
+
+- `gas_used` is amount of gas used by the transaction.
+- `configurableFeeScalar` is a `uint64` scalar set by the chain operator.
+- `configurableFeeConstant` is a `uint64` scalar set by the chain operator.
+
+These collected fees are sent to the `SequencerFeeVault`.
+
+#### Configuring scalars
+
+`configurableFeeScalar` and `configurableFeeConstant` are loaded in a similar way to the `baseFeeScalar` and
+`blobBaseFeeScalar` used in the [`L1Fee`](../../protocol/exec-engine.md#ecotone-l1-cost-fee-changes-eip-4844-da).
+calculation. In more detail, these scalars can be accessed in two interchangable ways.
+
+- read from the deposited L1 attributes (`configurableFeeScalar` and `configurableFeeConstant`) of the current L2 block
+- read from the L1 Block Info contract (`0x4200000000000000000000000000000000000015`)
+  - using the respective solidity getter functions (`configurableFeeScalar`, `configurableFeeConstant`)
+  - using direct storage-reads:
+    - Configurable fee scalar as big-endian `uint64` in slot `3` at offset `24`.
+    - Configurable fee constant as big-endian `uint64` in slot `3` at offset `16`.

specs/protocol/isthmus/l1-attributes.md

@@ -0,0 +1,40 @@
+# L1 Block Attributes
+
+<!-- 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**
+
+- [Overview](#overview)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Overview
+
+The L1 block attributes transaction is updated to include the EIP-1559 parameters and the extra scalars
+for the `configurableFee`.
+
+| Input arg         | Type    | Calldata bytes | Segment |
+| ----------------- | ------- | -------------- | ------- |
+| {0x098999be}      |         | 0-3            | n/a     |
+| baseFeeScalar     | uint32  | 4-7            | 1       |
+| blobBaseFeeScalar | uint32  | 8-11           |         |
+| sequenceNumber    | uint64  | 12-19          |         |
+| l1BlockTimestamp  | uint64  | 20-27          |         |
+| l1BlockNumber     | uint64  | 28-35          |         |
+| basefee           | uint256 | 36-67          | 2       |
+| blobBaseFee       | uint256 | 68-99          | 3       |
+| l1BlockHash       | bytes32 | 100-131        | 4       |
+| batcherHash       | bytes32 | 132-163        | 5       |
+| eip1559Denominator   | uint64  | 164-171        | 6       |
+| eip1559Elasticity    | uint64  | 172-179        |         |
+| configurableFeeScalar  | uint64  | 180-187        |         |
+| configurableFeeConstant    | uint64  | 188-195        |         |
+
+In the first L2 block after the Isthmus activation block, the Isthmus L1 attributes are first used.
+
+The pre-Isthmus values are migrated over 1:1.
+Blocks after the Isthmus activation block contain all pre-Isthmus values 1:1,
+and also set the following new attributes:
+
+- The `configurableFeeScalar` is set to `0`.
+- The `configurableFeeConstant` is set to `0`.

specs/protocol/isthmus/overview.md

@@ -13,6 +13,10 @@ This document is not finalized and should be considered experimental.
 
 ## Execution Layer
 
+- [Configurable Fee](./exec-engine.md#fees)
+
 ## Consensus Layer
 
-- [Interop](../interop/overview.md)
+- [L1 Block Attributes](./l1-attributes.md)
+- [Configurability](./configurability.md)
+- [Interop](../../interop/overview.md)

specs/protocol/isthmus/predeploys.md

@@ -0,0 +1,36 @@
+# Overview
+
+<!-- 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**
+
+- [Predeploys](#predeploys)
+  - [L1Block](#l1block)
+    - [Interface](#interface)
+      - [`setL1BlockValuesIsthmus`](#setl1blockvaluesisthmus)
+      - [`setIsthmus`](#setisthmus)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+Since we now need to include the configurable fee scalars in the L1 Attri
+
+## Predeploys
+
+### L1Block
+
+#### Interface
+
+##### `setL1BlockValuesIsthmus`
+
+This function MUST only be callable by the `DEPOSITOR_ACCOUNT`. It is a replacement
+for `setL1BlockValuesHolocene` and its calldata is defined in [L1 Attributes](./l1-attributes.md).
+
+```function
+function setL1BlockValuesIsthmus()
+```
+
+##### `setIsthmus`
+
+This function is meant to be called once on the activation block of the isthmus network upgrade.
+It MUST only be callable by the `DEPOSITOR_ACCOUNT` once. When it is called, it MUST call
+call each getter for the network specific config and set the returndata into storage.

specs/protocol/isthmus/system-config.md

@@ -0,0 +1,39 @@
+# 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)
+  - [Scalars](#scalars)
+    - [Isthmus `scalar`, `overhead` (`uint256,uint256`) change](#isthmus-scalar-overhead-uint256uint256-change)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## System config contents (version 0)
+
+### Scalars
+
+In order to allow rollup operators to adjust the new `ConfigurableFeeScalar` and `ConfigurableFeeConstant`, a change to
+the `scalar` and `overhead` encoding is necessary.
+
+#### Isthmus `scalar`, `overhead` (`uint256,uint256`) change
+
+After Isthmus activation:
+
+- A new version to the `scalar` encoding is added. It is described as follows.
+
+\*Byte ranges are indicated with `[` (inclusive) and `)` (exclusive).
+
+- `0`: scalar-version byte
+- `[1, 32)`: depending scalar-version:
+  - Scalar-version `2`:
+    - `[1, 8)`: padding, must be zero.
+    - `[8, 16)`: big-endian `uint64`, encoding the `configurableFeeScalar`
+    - `[16, 24)`: big-endian `uint64`, encoding the `configurableFeeConstant`
+    - `[24, 28)`: big-endian `uint32`, encoding the `blobBaseFeeScalar`
+    - `[28, 32)`: big-endian `uint32`, encoding the `baseFeeScalar`
+    - This version adds the `configurableFeeScalar` and the `configurableFeeConstant`.
+
+The `configurableFeeScalar` and `configurableFeeConstant` are incorporated into the L2 through the
+[Isthmus L1 attributes deposit transaction calldata](l1-attributes.md).