isthmus: operator fee

specs/SUMMARY.md

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

specs/protocol/holocene/exec-engine.md

@@ -97,6 +97,3 @@ historical execution, as L1 would have to be consulted for fetching the values f
 Instead, we re-use an unused field in the L1 block header as to make these parameters available, retaining the
 purity of the function that computes the next block's base fee from the chain configuration, parent block header,
 and next block timestamp.
-
-[l2-to-l1-mp]: ../../protocol/predeploys.md#L2ToL1MessagePasser
-[output-root]: ../../glossary.md#l2-output-root

specs/protocol/isthmus/configurability.md

@@ -10,22 +10,34 @@
 - [`SystemConfig`](#systemconfig)
   - [`ConfigUpdate`](#configupdate)
   - [Initialization](#initialization)
+  - [Modifying Operator Fee Parameters](#modifying-operator-fee-parameters)
   - [Interface](#interface)
+    - [Operator fee parameters](#operator-fee-parameters)
+      - [`operatorFeeScalar`](#operatorfeescalar)
+      - [`operatorFeeConstant`](#operatorfeeconstant)
+      - [`setOperatorFeeScalars`](#setoperatorfeescalars)
+      - [`setOperatorFeeManager`](#setoperatorfeemanager)
     - [Fee Vault Config](#fee-vault-config)
       - [`setBaseFeeVaultConfig`](#setbasefeevaultconfig)
       - [`setL1FeeVaultConfig`](#setl1feevaultconfig)
       - [`setSequencerFeeVaultConfig`](#setsequencerfeevaultconfig)
+      - [`setOperatorFeeVaultConfig`](#setoperatorfeevaultconfig)
 - [`OptimismPortal`](#optimismportal)
   - [Interface](#interface-1)
     - [`setConfig`](#setconfig)
     - [`upgrade`](#upgrade)
+- [Consensus Parameters](#consensus-parameters)
+  - [Operator Fee Scalar](#operator-fee-scalar)
+  - [Operator Fee Constant](#operator-fee-constant)
+- [Service Roles](#service-roles)
+  - [Operator Fee Manager](#operator-fee-manager)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Overview
 
 The `SystemConfig` and `OptimismPortal` are updated with a new flow for chain
-configurability.
+configurability. A new service role `OperatorFeeManager` is added to manage the operator fee collection.
 
 ## Constants
 
@@ -39,10 +51,11 @@ The `ConfigType` enum represents configuration that can be modified.
 | `SET_BASE_FEE_VAULT_CONFIG` | `uint8(1)` | Sets the Fee Vault Config for the `BaseFeeVault` |
 | `SET_L1_FEE_VAULT_CONFIG` | `uint8(2)` | Sets the Fee Vault Config for the `L1FeeVault` |
 | `SET_SEQUENCER_FEE_VAULT_CONFIG` | `uint8(3)` | Sets the Fee Vault Config for the `SequencerFeeVault` |
-| `SET_L1_CROSS_DOMAIN_MESSENGER_ADDRESS` | `uint8(4)` | Sets the `L1CrossDomainMessenger` address |
-| `SET_L1_ERC_721_BRIDGE_ADDRESS` | `uint8(5)` | Sets the `L1ERC721Bridge` address |
-| `SET_L1_STANDARD_BRIDGE_ADDRESS` | `uint8(6)` | Sets the `L1StandardBridge` address |
-| `SET_REMOTE_CHAIN_ID` | `uint8(7)` | Sets the chain id of the base chain |
+| `SET_OPERATOR_FEE_VAULT_CONFIG` | `uint8(4)` | Sets the Fee Vault Config for the `OperatorFeeVault` |
+| `SET_L1_CROSS_DOMAIN_MESSENGER_ADDRESS` | `uint8(5)` | Sets the `L1CrossDomainMessenger` address |
+| `SET_L1_ERC_721_BRIDGE_ADDRESS` | `uint8(6)` | Sets the `L1ERC721Bridge` address |
+| `SET_L1_STANDARD_BRIDGE_ADDRESS` | `uint8(7)` | Sets the `L1StandardBridge` address |
+| `SET_REMOTE_CHAIN_ID` | `uint8(8)` | Sets the chain id of the base chain |
 
 ## `SystemConfig`
 
@@ -57,6 +70,8 @@ The following `ConfigUpdate` event is defined where the `CONFIG_VERSION` is `uin
 | `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(uint32(_denominator))) << 32 \| uint64(uint32(_elasticity))` | Modifies the EIP-1559 denominator and elasticity |
+| `OPERATOR_FEE_PARAMS` | `uint8(5)` | `uint256(_operatorFeeScalar) << 64 \| _operatorFeeConstant` | Modifies the operator fee parameters |
+| `OPERATOR_FEE_MANAGER` | `uint8(6)` | `abi.encode(address)` | Modifies the operator fee manager |
 
 ### Initialization
 
@@ -67,19 +82,73 @@ The following actions should happen during the initialization of the `SystemConf
 - `emit ConfigUpdate.GAS_LIMIT`
 - `emit ConfigUpdate.UNSAFE_BLOCK_SIGNER`
 - `emit ConfigUpdate.EIP_1559_PARAMS`
+- `emit ConfigUpdate.OPERATOR_FEE_PARAMS`
+- `emit ConfigUpdate.OPERATOR_FEE_MANAGER`
 - `setConfig(SET_GAS_PAYING_TOKEN)`
 - `setConfig(SET_BASE_FEE_VAULT_CONFIG)`
 - `setConfig(SET_L1_FEE_VAULT_CONFIG)`
 - `setConfig(SET_SEQUENCER_FEE_VAULT_CONFIG)`
+- `setConfig(SET_OPERATOR_FEE_VAULT_CONFIG)`
 - `setConfig(SET_L1_CROSS_DOMAIN_MESSENGER_ADDRESS)`
 - `setConfig(SET_L1_ERC_721_BRIDGE_ADDRESS)`
 - `setConfig(SET_L1_STANDARD_BRIDGE_ADDRESS)`
 - `setConfig(SET_REMOTE_CHAIN_ID)`
 
 These actions MAY only be triggered if there is a diff to the value.
 
+Since the `OperatorFeeVault` is new in Isthmus, the `setConfig(SET_OPERATOR_FEE_VAULT_CONFIG)` MUST be emitted.
+
+`ConfigUpdate.OPERATOR_FEE_PARAMS` and `ConfigUpdate.OPERATOR_FEE_MANAGER` MAY be emitted. If they are not emitted,
+the `operatorFeeScalar` and `operatorFeeConstant` are set to 0 by default, and the `OperatorFeeManager`
+is set to the chain governor by default.
+
+### Modifying Operator Fee Parameters
+
+A new `SystemConfig` `UpdateType` is introduced that enables the modification of
+the `operatorFeeScalar` and `operatorFeeConstant` by the [`OperatorFeeManager`](#operator-fee-manager).
+
+Another `UpdateType` is added to modify the [`OperatorFeeManager`].
+
 ### Interface
 
+#### Operator fee parameters
+
+##### `operatorFeeScalar`
+
+This function returns the currently configured operator fee scalar.
+
+```solidity
+function operatorFeeScalar()(uint32)
+```
+
+##### `operatorFeeConstant`
+
+This function returns the currently configured operator fee constant.
+
+```solidity
+function operatorFeeConstant()(uint64)
+```
+
+##### `setOperatorFeeScalars`
+
+This function sets the `operatorFeeScalar` and `operatorFeeConstant`.
+
+This function MUST only be callable by the [`OperatorFeeManager`](#operator-fee-manager).
+
+```solidity
+function setOperatorFeeScalar(uint32 _operatorFeeScalar, uint64 _operatorFeeConstant)()
+```
+
+##### `setOperatorFeeManager`
+
+This function sets the `operatorFeeManager`.
+
+This function MUST only be callable by the chain governor.
+
+```solidity
+function setOperatorFeeManager(address _operatorFeeManager)()
+```
+
 #### Fee Vault Config
 
 For each `FeeVault`, there is a setter for its config. The arguments to the setter include
@@ -106,6 +175,12 @@ function setL1FeeVaultConfig(address,uint256,WithdrawalNetwork)
 function setSequencerFeeVaultConfig(address,uint256,WithdrawalNetwork)
 ```
 
+##### `setOperatorFeeVaultConfig`
+
+```solidity
+function setOperatorFeeVaultConfig(address,uint256,WithdrawalNetwork)
+```
+
 ## `OptimismPortal`
 
 The `OptimismPortal` is updated to emit a special system `TransactionDeposited` event.
@@ -157,3 +232,28 @@ The following fields are included:
 - `version` is `uint256(0)`
 - `opaqueData` is the tightly packed transaction data where `mint` is `0`, `value` is `0`, the `gasLimit`
    is `200_000`, `isCreation` is `false` and the `data` is the data passed into `upgrade`.
+
+## Consensus Parameters
+
+The operator fee scalar and constant are new consensus parameters, so we define standard values for them.
+
+### [Operator Fee Scalar](exec-engine.md#operator-fees)
+
+**Description:** Operator fee scalar -- used to calculate the operator fee<br/>
+**Administrator:** [Operator Fee Manager](#operator-fee-manager)<br/>
+**Requirement:** Between 0 and 0.5 * (baseFee + priorityFee) <br/>
+
+### [Operator Fee Constant](exec-engine.md#operator-fees)
+
+**Description:** Operator fee constant -- used to calculate the operator fee<br/>
+**Administrator:** [Operator Fee Manager](#operator-fee-manager)<br/>
+**Requirement:** Between 0 and 600 Gwei <br/>
+
+## Service Roles
+
+### Operator Fee Manager
+
+**Description:** Account authorized to modify the operator fee scalar. <br/>
+**Administrator:** [System Config Owner](../configurability.md#system-config)<br/>
+**Requirement:** <br/>
+**Notes:** <br/>

specs/protocol/isthmus/derivation.md

@@ -0,0 +1,25 @@
+# Isthmus L2 Chain Derivation Changes
+
+<!-- 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**
+
+- [Network upgrade automation transactions](#network-upgrade-automation-transactions)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# Network upgrade automation transactions
+
+The Isthmus hardfork activation block contains the following transactions, in this order:
+
+- L1 Attributes Transaction
+- User deposits from L1
+- Network Upgrade Transactions
+  - L1Block deployment
+  - Update L1Block Proxy ERC-1967 Implementation
+  - L1Block Enable Isthmus
+  - GasPriceOracle deployment
+  - Update GasPriceOracle Proxy ERC-1967 Implementation
+  - GasPriceOracle Enable Isthmus
+  - OptimismMintableERC20Factory deployment
+  - Update OptimismMintableERC20Factory Proxy ERC-1967 Implementation

specs/protocol/isthmus/exec-engine.md

@@ -12,6 +12,10 @@
     - [Rationale](#rationale)
     - [Forwards Compatibility Considerations](#forwards-compatibility-considerations)
     - [Client Implementation Considerations](#client-implementation-considerations)
+- [Fees](#fees)
+  - [Operator Fee](#operator-fee)
+    - [Configuring Parameters](#configuring-parameters)
+  - [Fee Vaults](#fee-vaults)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -76,3 +80,45 @@ an outbound withdrawal for a long period of time, the node may not have access t
 [`L2ToL1MessagePasser`][l2-to-l1-mp]. In this case, the client would be unable to keep consensus. However, most modern
 clients are able to at the very least reconstruct the account storage root at a given block on the fly if it does not
 directly store this information.
+
+[l2-to-l1-mp]: ../../protocol/predeploys.md#L2ToL1MessagePasser
+[output-root]: ../../glossary.md#l2-output-root
+
+## 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 `operatorFee`, which is parameterized by two scalars: the `operatorFeeScalar`
+and the `operatorFeeConstant`.
+
+### Operator Fee
+
+The operator fee, is set as follows:
+
+`operatorFee = (gasUsed * operatorFeeScalar / 1e6) + operatorFeeConstant`
+
+Where:
+
+- `gasUsed` is amount of gas used by the transaction.
+- `operatorFeeScalar` is a `uint32` scalar set by the chain operator, scaled by `1e6`.
+- `operatorFeeConstant` is a `uint64` scalar set by the chain operator.
+
+#### Configuring Parameters
+
+`operatorFeeScalar` and `operatorFeeConstant` 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 paramters can be accessed in two interchangable ways.
+
+- read from the deposited L1 attributes (`operatorFeeScalar` and `operatorFeeConstant`) of the current L2 block
+- read from the L1 Block Info contract (`0x4200000000000000000000000000000000000015`)
+  - using the respective solidity getter functions (`operatorFeeScalar`, `operatorFeeConstant`)
+  - using direct storage-reads:
+    - Operator fee scalar as big-endian `uint32` in slot `8` at offset `0`.
+    - Operator fee constant as big-endian `uint64` in slot `8` at offset `4`.
+
+### Fee Vaults
+
+These collected fees are sent to a new vault for the `operatorFee`: the [`OperatorFeeVault`](predeploys.md#operatorfeevault).
+
+Like the existing vaults, this is a hardcoded address, pointing at a pre-deployed proxy contract.
+The proxy is backed by a vault contract deployment, based on `FeeVault`, to route vault funds to L1 securely.

specs/protocol/isthmus/l1-attributes.md

@@ -0,0 +1,37 @@
+# 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 operator fee parameters.
+
+| 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       |
+| operatorFeeScalar   | uint32  | 164-167      | 6       |
+| operatorFeeConstant | uint64  | 168-175      |         |
+
+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 `operatorFeeScalar` is set to `0`.
+- The `operatorFeeConstant` is set to `0`.

specs/protocol/isthmus/overview.md

@@ -15,9 +15,15 @@ This document is not finalized and should be considered experimental.
 ## Execution Layer
 
 - [L2ToL1MessagePasser Storage Root in Header](./exec-engine.md##l2tol1messagepasser-storage-root-in-header)
+- [Operator Fee](./exec-engine.md#operator-fee)
 
 ## Consensus Layer
 
+- [Isthmus Derivation](./derivation.md#isthmus-derivation)
+- [Configurability](./configurability.md)
+
 ## Smart Contracts
 
 - [SuperchainConfig](./superchain-config.md)
+- [Predeploys](./predeploys.md)
+- [L1 Block Attributes](./l1-attributes.md)