Isthmus: operator fee

specs/SUMMARY.md

@@ -55,8 +55,13 @@
       - [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)
+      - [System Config](./protocol/isthmus/system-config.md)
 - [Governance]()
   - [Governance Token](./governance/gov-token.md)
 - [Experimental]()

specs/protocol/configurability.md

@@ -30,6 +30,8 @@
   - [Start block](#start-block)
   - [Superchain target](#superchain-target)
   - [Governance Token](#governance-token)
+  - [Operator Fee Scalar](#operator-fee-scalar)
+  - [Operator Fee Constant](#operator-fee-constant)
   - [Resource Config](#resource-config)
 - [Policy Parameters](#policy-parameters)
   - [Data Availability Type](#data-availability-type)
@@ -47,6 +49,7 @@
   - [Guardian address](#guardian-address)
   - [Proposer address](#proposer-address)
   - [Sequencer P2P / Unsafe head signer](#sequencer-p2p--unsafe-head-signer)
+  - [Operator Fee Manager](#operator-fee-manager)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -283,6 +286,21 @@ contracts deployed on layer 1.<br/>
 **Requirement:** Disabled<br/>
 **Notes:** Simple clear restriction.<br/>
 
+### [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:** 0 <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:** 0 <br/>
+
+Note that the operator fee scalar and constant are primarily used for non-standard configurations,
+like op-succinct, so their standard values are 0.
+
 [^chain-id-uniqueness]: The chain ID must be globally unique among all EVM chains.
 
 ### Resource Config
@@ -441,4 +459,11 @@ configuration of the permissioned dispute game.<br/>
 **Requirement:** No requirement<br/>
 **Notes:** <br/>
 
+### Operator Fee Manager
+
+**Description:** Account authorized to modify the operator fee scalar. <br/>
+**Administrator:** [System Config Owner](#admin-roles)<br/>
+**Requirement:** <br/>
+**Notes:** <br/>
+
 [^of-gnosis-safe-l1]: 5 of 7 GnosisSafe controlled by Optimism Foundation (OF). Mainnet and Sepolia addresses can be found at [privileged roles](https://docs.optimism.io/chain/security/privileged-roles).

specs/protocol/isthmus/configurability.md

@@ -10,11 +10,17 @@
 - [`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)
     - [Fee Vault Config](#fee-vault-config)
       - [`setBaseFeeVaultConfig`](#setbasefeevaultconfig)
       - [`setL1FeeVaultConfig`](#setl1feevaultconfig)
       - [`setSequencerFeeVaultConfig`](#setsequencerfeevaultconfig)
+      - [`setOperatorFeeVaultConfig`](#setoperatorfeevaultconfig)
 - [`OptimismPortal`](#optimismportal)
   - [Interface](#interface-1)
     - [`setConfig`](#setconfig)
@@ -25,7 +31,7 @@
 ## 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 +45,11 @@ The `ConfigType` enum represents configuration that can be modified.
 | `BASE_FEE_VAULT_CONFIG` | `uint8(1)` | Sets the Fee Vault Config for the `BaseFeeVault` |
 | `L1_FEE_VAULT_CONFIG` | `uint8(2)` | Sets the Fee Vault Config for the `L1FeeVault` |
 | `SEQUENCER_FEE_VAULT_CONFIG` | `uint8(3)` | Sets the Fee Vault Config for the `SequencerFeeVault` |
-| `L1_CROSS_DOMAIN_MESSENGER_ADDRESS` | `uint8(4)` | Sets the `L1CrossDomainMessenger` address |
-| `L1_ERC_721_BRIDGE_ADDRESS` | `uint8(5)` | Sets the `L1ERC721Bridge` address |
-| `L1_STANDARD_BRIDGE_ADDRESS` | `uint8(6)` | Sets the `L1StandardBridge` address |
-| `REMOTE_CHAIN_ID` | `uint8(7)` | Sets the chain id of the base chain |
+| `OPERATOR_FEE_VAULT_CONFIG` | `uint8(4)` | Sets the Fee Vault Config for the `OperatorFeeVault` |
+| `L1_CROSS_DOMAIN_MESSENGER_ADDRESS` | `uint8(5)` | Sets the `L1CrossDomainMessenger` address |
+| `L1_ERC_721_BRIDGE_ADDRESS` | `uint8(6)` | Sets the `L1ERC721Bridge` address |
+| `L1_STANDARD_BRIDGE_ADDRESS` | `uint8(7)` | Sets the `L1StandardBridge` address |
+| `REMOTE_CHAIN_ID` | `uint8(8)` | Sets the chain id of the base chain |
 
 ## `SystemConfig`
 
@@ -57,6 +64,7 @@ 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 |
 
 ### Initialization
 
@@ -67,19 +75,59 @@ 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`
 - `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` MAY be emitted. If it is not emitted, the `operatorFeeScalar` and
+`operatorFeeConstant` are set to 0 by default.
+
+### Modifying Operator Fee Parameters
+
+A new `SystemConfig` `UpdateType` is introduced that enables the modification of
+the `operatorFeeScalar` and `operatorFeeConstant` by the [`OperatorFeeManager`](../configurability.md#operator-fee-manager).
+
 ### 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`](../configurability.md#operator-fee-manager).
+
+```solidity
+function setOperatorFeeScalar(uint32 _operatorFeeScalar, uint64 _operatorFeeConstant)
+```
+
 #### Fee Vault Config
 
 For each `FeeVault`, there is a setter for its config. The arguments to the setter include
@@ -106,6 +154,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.

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

@@ -21,6 +21,10 @@
 - [Engine API Updates](#engine-api-updates)
   - [Update to `ExecutableData`](#update-to-executabledata)
   - [`engine_newPayloadV3` API](#engine_newpayloadv3-api)
+- [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 -->
 
@@ -141,3 +145,42 @@ Withdrawals list in the block body is encoded as an empty RLP list.
 
 Post Isthmus, `engine_newPayloadV3` will be used with the additional `ExecutionPayload` attribute. This attribute
 is omitted prior to Isthmus.
+
+## 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 parameters 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,16 @@ 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)
+- [System Config](./system-config.md)