diff --git a/specs/protocol/ecotone/l1-attributes.md b/specs/protocol/ecotone/l1-attributes.md index 959c4e2b5..435b315ee 100644 --- a/specs/protocol/ecotone/l1-attributes.md +++ b/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. diff --git a/specs/protocol/isthmus/configurability.md b/specs/protocol/isthmus/configurability.md index ed16365e9..e3c1e8bed 100644 --- a/specs/protocol/isthmus/configurability.md +++ b/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`. diff --git a/specs/protocol/isthmus/deposits.md b/specs/protocol/isthmus/deposits.md new file mode 100644 index 000000000..3536de97b --- /dev/null +++ b/specs/protocol/isthmus/deposits.md @@ -0,0 +1,27 @@ +# Deposits + + + +**Table of Contents** + +- [Overview](#overview) +- [User-Deposited Transactions](#user-deposited-transactions) + + + +## 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. diff --git a/specs/protocol/isthmus/derivation.md b/specs/protocol/isthmus/derivation.md new file mode 100644 index 000000000..6aa1b1ee8 --- /dev/null +++ b/specs/protocol/isthmus/derivation.md @@ -0,0 +1,71 @@ +# Derivation + + + +**Table of Contents** + +- [Network upgrade automation transactions](#network-upgrade-automation-transactions) + - [Isthmus](#isthmus) + - [L1Block Deployment](#l1block-deployment) + + + +## 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 +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`. diff --git a/specs/protocol/isthmus/l1-attributes.md b/specs/protocol/isthmus/l1-attributes.md new file mode 100644 index 000000000..29ba01d1a --- /dev/null +++ b/specs/protocol/isthmus/l1-attributes.md @@ -0,0 +1,100 @@ +# Isthmus L1 Attributes + + + +**Table of Contents** + +- [Overview](#overview) +- [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract) + - [Isthmus L1Block upgrade](#isthmus-l1block-upgrade) + + + +## 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. diff --git a/specs/static/bytecode/isthmus-l1-block-deployment.txt b/specs/static/bytecode/isthmus-l1-block-deployment.txt new file mode 100644 index 000000000..31b8094a7 --- /dev/null +++ b/specs/static/bytecode/isthmus-l1-block-deployment.txt @@ -0,0 +1 @@ +0x608060405234801561001057600080fd5b50610b8c806100206000396000f3fe608060405234801561001057600080fd5b506004361061018d5760003560e01c806371cfaa3f116100e3578063c59859181161008c578063e591b28211610066578063e591b28214610387578063e81b2c6d146103a9578063f8206140146103b257600080fd5b8063c59859181461034b578063d84447151461036b578063de35f5cb1461037357600080fd5b80638b239f73116100bd5780638b239f73146103195780639e8c496614610322578063b80777ea1461032b57600080fd5b806371cfaa3f146102d257806374dd5eab146102e55780638381f58a1461030557600080fd5b8063440a5e20116101455780635cf249691161011f5780635cf249691461026b57806364ca23ef1461027457806368d5dca6146102a157600080fd5b8063440a5e201461021957806354fd4d5014610221578063550fcdc91461026357600080fd5b806309bd5a601161017657806309bd5a60146101af57806321326849146101cb5780634397dfef146101e357600080fd5b8063015d8eb914610192578063098999be146101a7575b600080fd5b6101a56101a03660046109f7565b6103bb565b005b6101a56104fa565b6101b860025481565b6040519081526020015b60405180910390f35b6101d3610504565b60405190151581526020016101c2565b6101eb610543565b6040805173ffffffffffffffffffffffffffffffffffffffff909316835260ff9091166020830152016101c2565b6101a5610557565b60408051808201909152600581527f312e362e3000000000000000000000000000000000000000000000000000000060208201525b6040516101c29190610a69565b6102566105ae565b6101b860015481565b6003546102889067ffffffffffffffff1681565b60405167ffffffffffffffff90911681526020016101c2565b6003546102bd9068010000000000000000900463ffffffff1681565b60405163ffffffff90911681526020016101c2565b6101a56102e0366004610adc565b6105bd565b6008546102889068010000000000000000900467ffffffffffffffff1681565b6000546102889067ffffffffffffffff1681565b6101b860055481565b6101b860065481565b6000546102889068010000000000000000900467ffffffffffffffff1681565b6003546102bd906c01000000000000000000000000900463ffffffff1681565b610256610672565b6008546102889067ffffffffffffffff1681565b60405173deaddeaddeaddeaddeaddeaddeaddeaddead000181526020016101c2565b6101b860045481565b6101b860075481565b3373deaddeaddeaddeaddeaddeaddeaddeaddead000114610462576040517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152603b60248201527f4c31426c6f636b3a206f6e6c7920746865206465706f7369746f72206163636f60448201527f756e742063616e20736574204c3120626c6f636b2076616c7565730000000000606482015260840160405180910390fd5b6000805467ffffffffffffffff98891668010000000000000000027fffffffffffffffffffffffffffffffff00000000000000000000000000000000909116998916999099179890981790975560019490945560029290925560038054919094167fffffffffffffffffffffffffffffffffffffffffffffffff00000000000000009190911617909255600491909155600555600655565b61050261067c565b565b60008061050f610543565b5073ffffffffffffffffffffffffffffffffffffffff1673eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee141592915050565b60008061054e6106dc565b90939092509050565b73deaddeaddeaddeaddeaddeaddeaddeaddead000133811461058157633cc50b456000526004601cfd5b60043560801c60035560143560801c60005560243560015560443560075560643560025560843560045550565b60606105b861075d565b905090565b3373deaddeaddeaddeaddeaddeaddeaddeaddead00011461060a576040517f3cc50b4500000000000000000000000000000000000000000000000000000000815260040160405180910390fd5b6106168484848461081e565b604080518381526020810183905260ff85169173ffffffffffffffffffffffffffffffffffffffff8716917f10e43c4d58f3ef4edae7c1ca2e7f02d46b2cadbcc046737038527ed8486ffeb0910160405180910390a350505050565b60606105b86108f0565b73deaddeaddeaddeaddeaddeaddeaddeaddead00013381146106a657633cc50b456000526004601cfd5b60043560801c60035560143560801c60005560243560015560443560075560643560025560843560045560a43560801c60085550565b6000808061071261070e60017f04adb1412b2ddc16fcc0d4538d5c8f07cf9c83abecc6b41f6f69037b708fbcec610b41565b5490565b73ffffffffffffffffffffffffffffffffffffffff81169350905082610751575073eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee92601292509050565b60a081901c9150509091565b606060006107696106dc565b5090507fffffffffffffffffffffffff111111111111111111111111111111111111111273ffffffffffffffffffffffffffffffffffffffff8216016107e257505060408051808201909152600381527f4554480000000000000000000000000000000000000000000000000000000000602082015290565b61081861081361070e60017fa48b38a4b44951360fbdcbfaaeae5ed6ae92585412e9841b70ec72ed8cd05764610b41565b6109a6565b91505090565b61088461084c60017f04adb1412b2ddc16fcc0d4538d5c8f07cf9c83abecc6b41f6f69037b708fbcec610b41565b74ff000000000000000000000000000000000000000060a086901b1673ffffffffffffffffffffffffffffffffffffffff8716179055565b6108b76108b260017f657c3582c29b3176614e3a33ddd1ec48352696a04e92b3c0566d72010fa8863d610b41565b839055565b6108ea6108e560017fa48b38a4b44951360fbdcbfaaeae5ed6ae92585412e9841b70ec72ed8cd05764610b41565b829055565b50505050565b606060006108fc6106dc565b5090507fffffffffffffffffffffffff111111111111111111111111111111111111111273ffffffffffffffffffffffffffffffffffffffff82160161097557505060408051808201909152600581527f4574686572000000000000000000000000000000000000000000000000000000602082015290565b61081861081361070e60017f657c3582c29b3176614e3a33ddd1ec48352696a04e92b3c0566d72010fa8863d610b41565b60405160005b82811a156109bc576001016109ac565b80825260208201838152600082820152505060408101604052919050565b803567ffffffffffffffff811681146109f257600080fd5b919050565b600080600080600080600080610100898b031215610a1457600080fd5b610a1d896109da565b9750610a2b60208a016109da565b96506040890135955060608901359450610a4760808a016109da565b979a969950949793969560a0850135955060c08501359460e001359350915050565b600060208083528351808285015260005b81811015610a9657858101830151858201604001528201610a7a565b81811115610aa8576000604083870101525b50601f017fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe016929092016040019392505050565b60008060008060808587031215610af257600080fd5b843573ffffffffffffffffffffffffffffffffffffffff81168114610b1657600080fd5b9350602085013560ff81168114610b2c57600080fd5b93969395505050506040820135916060013590565b600082821015610b7a577f4e487b7100000000000000000000000000000000000000000000000000000000600052601160045260246000fd5b50039056fea164736f6c634300080f000a \ No newline at end of file