Add specs for consensus event nonces (deposits + config changes)

specs/protocol/ecotone/l1-attributes.md

@@ -23,7 +23,7 @@ but are instead packed into 5 32-byte aligned segments (starting after the funct
 Each unsigned integer argument is encoded as big-endian using a number of bytes corresponding to the underlying type.
 The overall calldata layout is as follows:
 
-[ecotone-upgrade-txs]: derivation.md#network-upgrade-automation-transactions
+[ecotone-upgrade-txs]: ../derivation.md#network-upgrade-automation-transactions
 
 | Input arg         | Type    | Calldata bytes | Segment |
 | ----------------- | ------- | -------------- | ------- |
@@ -38,8 +38,8 @@ The overall calldata layout is as follows:
 | l1BlockHash       | bytes32 | 100-131        | 4       |
 | batcherHash       | bytes32 | 132-163        | 5       |
 
-Total calldata length MUST be exactly 164 bytes, implying the sixth and final segment is only
-partially filled. This helps to slow database growth as every L2 block includes a L1 Attributes
+Total calldata length MUST be exactly 164 bytes.
+This helps to slow database growth as every L2 block includes a L1 Attributes
 deposit transaction.
 
 In the first L2 block after the Ecotone activation block, the Ecotone L1 attributes are first used.

specs/protocol/isthmus/configurability.md

@@ -48,7 +48,18 @@ The `ConfigType` enum represents configuration that can be modified.
 
 ### `ConfigUpdate`
 
-The following `ConfigUpdate` event is defined where the `CONFIG_VERSION` is `uint256(0)`:
+Config updates MUST emit a `ConfigUpdate` event. The `version` argument CAN now
+include a `nonce`, and has been renamed `nonceAndVersion`.
+
+```solidity
+event ConfigUpdate(uint256 indexed nonceAndVersion, UpdateType indexed updateType, bytes data);
+```
+
+The `nonceAndVersion` value can either be `uint256(0)`, or
+`uint256(nonce << 128 | version)`, where `version` is `1` and `nonce` increments
+by `1` for each `ConfigUpdate` event emitted.
+
+The following `UpdateType`s are valid:
 
 | Name | Value | Definition | Usage |
 | ---- | ----- | --- | -- |
@@ -124,16 +135,18 @@ function setConfig(ConfigType,bytes)
 This function emits a `TransactionDeposited` event.
 
 ```solidity
-event TransactionDeposited(address indexed from, address indexed to, uint256 indexed version, bytes opaqueData);
+event TransactionDeposited(address indexed from, address indexed to, uint256 indexed nonceAndVersion, bytes opaqueData);
 ```
 
 The following fields are included:
 
 - `from` is the `DEPOSITOR_ACCOUNT`
 - `to` is `Predeploys.L1Block`
-- `version` is `uint256(0)`
+- `nonceAndVersion` is `uint256(0)`, or
+  `uint256(nonce << 128 | version)`, where `version` is `1` and `nonce` increments
+  by `1` for each `TransactionDeposited` event emitted
 - `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 `abi.encodeCall(L1Block.setConfig, (_type, _value))`
+  is `200_000`, `isCreation` is `false` and the `data` is `abi.encodeCall(L1Block.setConfig, (_type, _value))`
 
 #### `upgrade`
 
@@ -147,13 +160,15 @@ function upgrade(bytes memory _data) external
 This function emits a `TransactionDeposited` event.
 
 ```solidity
-event TransactionDeposited(address indexed from, address indexed to, uint256 indexed version, bytes opaqueData);
+event TransactionDeposited(address indexed from, address indexed to, uint256 indexed nonceAndVersion, bytes opaqueData);
 ```
 
 The following fields are included:
 
 - `from` is the `DEPOSITOR_ACCOUNT`
 - `to` is `Predeploys.ProxyAdmin`
-- `version` is `uint256(0)`
+- `nonceAndVersion` is `uint256(0)`, or
+  `uint256(nonce << 128 | version)`, where `version` is `1` and `nonce` increments
+  by `1` for each `TransactionDeposited` event emitted
 - `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`.
+  is `200_000`, `isCreation` is `false` and the `data` is the data passed into `upgrade`.

specs/protocol/isthmus/deposits.md

@@ -0,0 +1,27 @@
+# Deposits
+
+<!-- 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)
+- [User-Deposited Transactions](#user-deposited-transactions)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Overview
+
+The `version` argument of the `TransactionDeposited` event CAN now
+include a nonce, and has been renamed `nonceAndVersion`.
+
+## User-Deposited Transactions
+
+Each user deposit emits a `TransactionDeposited` event.
+
+```solidity
+event TransactionDeposited(address indexed from, address indexed to, uint256 indexed nonceAndVersion, bytes opaqueData);
+```
+
+The `nonceAndVersion` argument is either `uint256(0)`, or
+`uint256(nonce << 128 | version)`, where `version` is `1` and `nonce` increments
+by `1` for each `TransactionDeposited` event emitted.

specs/protocol/isthmus/derivation.md

@@ -0,0 +1,71 @@
+# Derivation
+
+<!-- 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)
+  - [Isthmus](#isthmus)
+    - [L1Block Deployment](#l1block-deployment)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Network upgrade automation transactions
+
+[network upgrade automation transactions]: #network-upgrade-automation-transactions
+
+Some network upgrades require automated contract changes or deployments at specific blocks.
+To automate these, without adding persistent changes to the execution-layer,
+special transactions may be inserted as part of the derivation process.
+
+### Isthmus
+
+The Isthmus hardfork activation block contains the following transactions, in this order:
+
+- L1 Attributes Transaction, using the Ecotone `setL1BlockValuesEcotone`
+- User deposits from L1
+- Network Upgrade Transactions
+  - L1Block deployment
+
+To not modify or interrupt the system behavior around gas computation, this block will not include any sequenced
+transactions by setting `noTxPool: true`.
+
+#### L1Block Deployment
+
+The `L1Block` contract is upgraded to process the new Isthmus L1 consensus nonces.
+
+A deposit transaction is derived with the following attributes:
+
+- `from`: `0x4210000000000000000000000000000000000005`
+- `to`: `null`
+- `mint`: `0`
+- `value`: `0`
+- `gasLimit`: `375,000`
+- `data`: `0x60806040523480156100105...` ([full bytecode](../../static/bytecode/isthmus-l1-block-deployment.txt))
+- `sourceHash`: `0x3b2d0821ca2411ad5cd3595804d1213d15737188ae4cbd58aa19c821a6c211bf`,
+  computed with the "Upgrade-deposited" type, with `intent = "Isthmus: L1 Block Deployment"
+
+This results in the Isthmus L1Block contract being deployed to `0x4fa2Be8cd41504037F1838BcE3bCC93bC68Ff537`, to verify:
+
+```bash
+cast compute-address --nonce=0 0x4210000000000000000000000000000000000005
+Computed Address: 0x4fa2Be8cd41504037F1838BcE3bCC93bC68Ff537
+```
+
+Verify `sourceHash`:
+
+```bash
+cast keccak $(cast concat-hex 0x0000000000000000000000000000000000000000000000000000000000000002 $(cast keccak "Isthmus: L1 Block Deployment"))
+# 0x3b2d0821ca2411ad5cd3595804d1213d15737188ae4cbd58aa19c821a6c211bf
+```
+
+Verify `data`:
+
+```bash
+git checkout <INSERT_GIT_SHA_HERE>
+pnpm clean && pnpm install && pnpm build
+jq -r ".bytecode.object" packages/contracts-bedrock/forge-artifacts/L1Block.sol/L1Block.json
+```
+
+This transaction MUST deploy a contract with the following code hash
+`0x68d031cd7a8147e7799609e42996a2b798d7c9e3dffad8960012432c146af8ad`.

specs/protocol/isthmus/l1-attributes.md

@@ -0,0 +1,100 @@
+# Isthmus L1 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)
+- [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract)
+  - [Isthmus L1Block upgrade](#isthmus-l1block-upgrade)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Overview
+
+On the Isthmus activation block, and if Isthmus is not activated at Genesis,
+the L1 Attributes Transaction includes a call to `setL1BlockValuesEcotone()`
+because the L1 Attributes transaction precedes the [Isthmus Upgrade Transactions][isthmus-upgrade-txs],
+meaning that `setL1BlockValuesIsthmus` is not guaranteed to exist yet.
+
+Every subsequent L1 Attributes transaction should include a call to the `setL1BlockValuesIsthmus()` function.
+There are two additional `uint64` fields for the consensus nonces packed into calldata.
+The overall calldata layout is as follows:
+
+[isthumus-upgrade-txs]: derivation.md#network-upgrade-automation-transactions
+
+| 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       |
+| depositNonce      | uint64  | 164-171        | 6       |
+| configUpdateNonce | uint64  | 172-179        |         |
+
+Total calldata length MUST be exactly 180 bytes, implying the sixth and final segment is only
+partially filled. This helps to slow database growth as every L2 block includes a L1 Attributes
+deposit transaction.
+
+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 `depositNonce` has the default value of 0.
+- The `configUpdateNonce` has the default value of 0.
+
+## L1 Attributes Predeployed Contract
+
+The L1 Attributes predeploy stores the following values:
+
+- L1 block attributes:
+  - `number` (`uint64`)
+  - `timestamp` (`uint64`)
+  - `basefee` (`uint256`)
+  - `hash` (`bytes32`)
+  - `blobBaseFee` (`uint256`)
+- `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][sys-config]:
+  - `batcherHash` (`bytes32`): A versioned commitment to the batch-submitter(s) currently operating.
+  - `baseFeeScalar` (`uint32`): system configurable to scale the `basefee` in the Ecotone l1 cost computation
+  - `blobBasefeeScalar` (`uint32`): system configurable to scale the `blobBaseFee` in the Ecotone l1 cost computation
+  - `depositNonce` (`uint64`): nonce that increments for every `TransactionDeposited` event on the l1
+  - `configUpdateNonce` (`uint64`): nonce that increments for every `ConfigUpdate` event on the l1
+
+Note that the `depositNonce` and `configUpdateNonce` will remain with 0 values until the relevant
+`SystemConfig` and `OptimismPortal2` contracts are upgraded on l1 to `SystemConfigIsthmus` and
+`OptimismPortalIsthmus` respectively. This MUST happen after the hardfork activation date, and
+before the next hardfork.
+
+After running `pnpm build` in the `packages/contracts-bedrock` directory, the bytecode to add to
+the genesis file will be located in the `deployedBytecode` field of the build artifacts file at
+`/packages/contracts-bedrock/forge-artifacts/L1Block.sol/L1Block.json`.
+
+### Isthmus L1Block upgrade
+
+The L1 Attributes Predeployed contract, `L1Block.sol`, is upgraded as part of the Isthmus upgrade.
+The version is incremented to `1.6.0`, and one new storage slot is introduced:
+
+- `depositNonce` (`uint64`): nonce that increments for every `TransactionDeposited` event on the l1
+- `configUpdateNonce` (`uint64`): nonce that increments for every `ConfigUpdate` event on the l1
+
+The function called by the L1 attributes transaction depends on the network upgrade:
+
+- Before the Isthmus activation:
+  - `setL1BlockValuesEcotone` is called, following the Ecotone L1 attributes rules.
+- At the Ecotone activation block:
+  - `setL1BlockValuesEcotone` function MUST be called, except if activated at genesis.
+    The contract is upgraded later in this block, to support `setL1BlockValuesIsthmus`.
+- After the Isthmus activation:
+  - `setL1BlockValuesEcotone` function is deprecated and MUST never be called.
+  - `setL1BlockValuesIsthmus` MUST be called with the new Isthmus attributes.

specs/static/bytecode/isthmus-l1-block-deployment.txt

@@ -0,0 +1 @@
+0x608060405234801561001057600080fd5b50610b8c806100206000396000f3fe608060405234801561001057600080fd5b506004361061018d5760003560e01c806371cfaa3f116100e3578063c59859181161008c578063e591b28211610066578063e591b28214610387578063e81b2c6d146103a9578063f8206140146103b257600080fd5b8063c59859181461034b578063d84447151461036b578063de35f5cb1461037357600080fd5b80638b239f73116100bd5780638b239f73146103195780639e8c496614610322578063b80777ea1461032b57600080fd5b806371cfaa3f146102d257806374dd5eab146102e55780638381f58a1461030557600080fd5b8063440a5e20116101455780635cf249691161011f5780635cf249691461026b57806364ca23ef1461027457806368d5dca6146102a157600080fd5b8063440a5e201461021957806354fd4d5014610221578063550fcdc91461026357600080fd5b806309bd5a601161017657806309bd5a60146101af57806321326849146101cb5780634397dfef146101e357600080fd5b8063015d8eb914610192578063098999be146101a7575b600080fd5b6101a56101a03660046109f7565b6103bb565b005b6101a56104fa565b6101b860025481565b6040519081526020015b60405180910390f35b6101d3610504565b60405190151581526020016101c2565b6101eb610543565b6040805173ffffffffffffffffffffffffffffffffffffffff909316835260ff9091166020830152016101c2565b6101a5610557565b60408051808201909152600581527f312e362e3000000000000000000000000000000000000000000000000000000060208201525b6040516101c29190610a69565b6102566105ae565b6101b860015481565b6003546102889067ffffffffffffffff1681565b60405167ffffffffffffffff90911681526020016101c2565b6003546102bd9068010000000000000000900463ffffffff1681565b60405163ffffffff90911681526020016101c2565b6101a56102e0366004610adc565b6105bd565b6008546102889068010000000000000000900467ffffffffffffffff1681565b6000546102889067ffffffffffffffff1681565b6101b860055481565b6101b860065481565b6000546102889068010000000000000000900467ffffffffffffffff1681565b6003546102bd906c01000000000000000000000000900463ffffffff1681565b610256610672565b6008546102889067ffffffffffffffff1681565b60405173deaddeaddeaddeaddeaddeaddeaddeaddead000181526020016101c2565b6101b860045481565b6101b860075481565b3373deaddeaddeaddeaddeaddeaddeaddeaddead000114610462576040517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152603b60248201527f4c31426c6f636b3a206f6e6c7920746865206465706f7369746f72206163636f60448201527f756e742063616e20736574204c3120626c6f636b2076616c7565730000000000606482015260840160405180910390fd5b6000805467ffffffffffffffff98891668010000000000000000027fffffffffffffffffffffffffffffffff00000000000000000000000000000000909116998916999099179890981790975560019490945560029290925560038054919094167fffffffffffffffffffffffffffffffffffffffffffffffff00000000000000009190911617909255600491909155600555600655565b61050261067c565b565b60008061050f610543565b5073ffffffffffffffffffffffffffffffffffffffff1673eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee141592915050565b60008061054e6106dc565b90939092509050565b73deaddeaddeaddeaddeaddeaddeaddeaddead000133811461058157633cc50b456000526004601cfd5b60043560801c60035560143560801c60005560243560015560443560075560643560025560843560045550565b60606105b861075d565b905090565b3373deaddeaddeaddeaddeaddeaddeaddeaddead00011461060a576040517f3cc50b4500000000000000000000000000000000000000000000000000000000815260040160405180910390fd5b6106168484848461081e565b604080518381526020810183905260ff85169173ffffffffffffffffffffffffffffffffffffffff8716917f10e43c4d58f3ef4edae7c1ca2e7f02d46b2cadbcc046737038527ed8486ffeb0910160405180910390a350505050565b60606105b86108f0565b73deaddeaddeaddeaddeaddeaddeaddeaddead00013381146106a657633cc50b456000526004601cfd5b60043560801c60035560143560801c60005560243560015560443560075560643560025560843560045560a43560801c60085550565b6000808061071261070e60017f04adb1412b2ddc16fcc0d4538d5c8f07cf9c83abecc6b41f6f69037b708fbcec610b41565b5490565b73ffffffffffffffffffffffffffffffffffffffff81169350905082610751575073eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee92601292509050565b60a081901c9150509091565b606060006107696106dc565b5090507fffffffffffffffffffffffff111111111111111111111111111111111111111273ffffffffffffffffffffffffffffffffffffffff8216016107e257505060408051808201909152600381527f4554480000000000000000000000000000000000000000000000000000000000602082015290565b61081861081361070e60017fa48b38a4b44951360fbdcbfaaeae5ed6ae92585412e9841b70ec72ed8cd05764610b41565b6109a6565b91505090565b61088461084c60017f04adb1412b2ddc16fcc0d4538d5c8f07cf9c83abecc6b41f6f69037b708fbcec610b41565b74ff000000000000000000000000000000000000000060a086901b1673ffffffffffffffffffffffffffffffffffffffff8716179055565b6108b76108b260017f657c3582c29b3176614e3a33ddd1ec48352696a04e92b3c0566d72010fa8863d610b41565b839055565b6108ea6108e560017fa48b38a4b44951360fbdcbfaaeae5ed6ae92585412e9841b70ec72ed8cd05764610b41565b829055565b50505050565b606060006108fc6106dc565b5090507fffffffffffffffffffffffff111111111111111111111111111111111111111273ffffffffffffffffffffffffffffffffffffffff82160161097557505060408051808201909152600581527f4574686572000000000000000000000000000000000000000000000000000000602082015290565b61081861081361070e60017f657c3582c29b3176614e3a33ddd1ec48352696a04e92b3c0566d72010fa8863d610b41565b60405160005b82811a156109bc576001016109ac565b80825260208201838152600082820152505060408101604052919050565b803567ffffffffffffffff811681146109f257600080fd5b919050565b600080600080600080600080610100898b031215610a1457600080fd5b610a1d896109da565b9750610a2b60208a016109da565b96506040890135955060608901359450610a4760808a016109da565b979a969950949793969560a0850135955060c08501359460e001359350915050565b600060208083528351808285015260005b81811015610a9657858101830151858201604001528201610a7a565b81811115610aa8576000604083870101525b50601f017fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe016929092016040019392505050565b60008060008060808587031215610af257600080fd5b843573ffffffffffffffffffffffffffffffffffffffff81168114610b1657600080fd5b9350602085013560ff81168114610b2c57600080fd5b93969395505050506040820135916060013590565b600082821015610b7a577f4e487b7100000000000000000000000000000000000000000000000000000000600052601160045260246000fd5b50039056fea164736f6c634300080f000a