From b3859cae32d5bcaae7bcad6265bcefdf7b746fef Mon Sep 17 00:00:00 2001 From: Michael de Hoog Date: Sat, 11 Jan 2025 14:06:53 -1000 Subject: [PATCH] Jovian consensus nonces --- specs/protocol/ecotone/l1-attributes.md | 6 +- specs/protocol/isthmus/overview.md | 2 +- specs/protocol/jovian/configurability.md | 31 ++++++ specs/protocol/jovian/deposits.md | 27 +++++ specs/protocol/jovian/derivation.md | 71 +++++++++++++ specs/protocol/jovian/exec-engine.md | 24 +++++ specs/protocol/jovian/l1-attributes.md | 100 ++++++++++++++++++ specs/protocol/jovian/overview.md | 11 ++ .../bytecode/jovian-l1-block-deployment.txt | 1 + 9 files changed, 269 insertions(+), 4 deletions(-) create mode 100644 specs/protocol/jovian/configurability.md create mode 100644 specs/protocol/jovian/deposits.md create mode 100644 specs/protocol/jovian/derivation.md create mode 100644 specs/protocol/jovian/exec-engine.md create mode 100644 specs/protocol/jovian/l1-attributes.md create mode 100644 specs/static/bytecode/jovian-l1-block-deployment.txt 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/overview.md b/specs/protocol/isthmus/overview.md index 62f1abf49..061d165ae 100644 --- a/specs/protocol/isthmus/overview.md +++ b/specs/protocol/isthmus/overview.md @@ -27,7 +27,7 @@ This document is not finalized and should be considered experimental. - [EIP-7623](https://eips.ethereum.org/EIPS/eip-7623) - [EIP-6110](https://eips.ethereum.org/EIPS/eip-6110) - [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685) -- [L2ToL1MessagePasser Storage Root in Header](./exec-engine.md##l2tol1messagepasser-storage-root-in-header) +- [L2ToL1MessagePasser Storage Root in Header](./exec-engine.md#l2tol1messagepasser-storage-root-in-header) - [Operator Fee](./exec-engine.md#operator-fee) ## Consensus Layer diff --git a/specs/protocol/jovian/configurability.md b/specs/protocol/jovian/configurability.md new file mode 100644 index 000000000..961cc51a4 --- /dev/null +++ b/specs/protocol/jovian/configurability.md @@ -0,0 +1,31 @@ +# Configurability + + + +**Table of Contents** + +- [Overview](#overview) +- [`SystemConfig`](#systemconfig) + - [`ConfigUpdate`](#configupdate) + + + +## Overview + +The `version` argument of the `ConfigUpdate` event CAN now +include a nonce, and has been renamed `nonceAndVersion`. + +## `SystemConfig` + +### `ConfigUpdate` + +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` argument is either `uint256(0)`, or +`uint256(nonce << 128 | version)`, where `version` is `1` and `nonce` increments +by `1` for each `ConfigUpdate` event emitted. diff --git a/specs/protocol/jovian/deposits.md b/specs/protocol/jovian/deposits.md new file mode 100644 index 000000000..3536de97b --- /dev/null +++ b/specs/protocol/jovian/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/jovian/derivation.md b/specs/protocol/jovian/derivation.md new file mode 100644 index 000000000..64304a517 --- /dev/null +++ b/specs/protocol/jovian/derivation.md @@ -0,0 +1,71 @@ +# Derivation + + + +**Table of Contents** + +- [Network upgrade automation transactions](#network-upgrade-automation-transactions) + - [Jovian](#jovian) + - [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. + +### Jovian + +The Jovian 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 Jovian 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/jovian-l1-block-deployment.txt)) +- `sourceHash`: `0xbb1a656f65401240fac3db12e7a79ebb954b11e62f7626eb11691539b798d3bf`, + computed with the "Upgrade-deposited" type, with `intent = "Jovian: L1 Block Deployment" + +This results in the Jovian 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 "Jovian: L1 Block Deployment")) +# 0xbb1a656f65401240fac3db12e7a79ebb954b11e62f7626eb11691539b798d3bf +``` + +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 +`0xea1f176e3bcab831c781395fca0974d470ea540e602c230b471814fb43883e74`. diff --git a/specs/protocol/jovian/exec-engine.md b/specs/protocol/jovian/exec-engine.md new file mode 100644 index 000000000..2d53023ca --- /dev/null +++ b/specs/protocol/jovian/exec-engine.md @@ -0,0 +1,24 @@ +# L2 Execution Engine + + + +**Table of Contents** + +- [Fees](#fees) + - [L1-Cost fees (L1 Fee Vault)](#l1-cost-fees-l1-fee-vault) + - [Jovian L1-Cost fee changes](#jovian-l1-cost-fee-changes) + + + +## Fees + +### L1-Cost fees (L1 Fee Vault) + +#### Jovian L1-Cost fee changes + +The data passed to the `L1Block` contract changes as part of the Jovian hard fork. +The L1-Cost function doesn't change, however the parsing of the data may need to +change as the 4-byte signature changes and the calldata now contains 2 additional +`uint64` nonce variables. + +See [L1 attributes override](./l1-attributes.md#overview) for more information. diff --git a/specs/protocol/jovian/l1-attributes.md b/specs/protocol/jovian/l1-attributes.md new file mode 100644 index 000000000..a14598bd0 --- /dev/null +++ b/specs/protocol/jovian/l1-attributes.md @@ -0,0 +1,100 @@ +# Jovian L1 Attributes + + + +**Table of Contents** + +- [Overview](#overview) +- [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract) + - [Jovian L1Block upgrade](#jovian-l1block-upgrade) + + + +## Overview + +On the Jovian activation block, and if Jovian is not activated at Genesis, +the L1 Attributes Transaction includes a call to `setL1BlockValuesEcotone()` +because the L1 Attributes transaction precedes the [Jovian Upgrade Transactions][jovian-upgrade-txs], +meaning that `setL1BlockValuesJovian` is not guaranteed to exist yet. + +Every subsequent L1 Attributes transaction should include a call to the `setL1BlockValuesJovian()` function. +There are two additional `uint64` fields for the consensus nonces packed into calldata. +The overall calldata layout is as follows: + +[jovian-upgrade-txs]: derivation.md#network-upgrade-automation-transactions + +| Input arg | Type | Calldata bytes | Segment | +| ----------------- | ------- |----------------| ------- | +| {0x3db6be2b} | | 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 Jovian activation block, the Jovian L1 attributes are first used. + +The pre-Jovian values are migrated over 1:1. +Blocks after the Jovian activation block contain all pre-Jovian 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 `SystemConfigJovian` and +`OptimismPortalJovian` 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`. + +### Jovian L1Block upgrade + +The L1 Attributes Predeployed contract, `L1Block.sol`, is upgraded as part of the Jovian 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 Jovian activation: + - `setL1BlockValuesEcotone` is called, following the Ecotone L1 attributes rules. +- At the Jovian activation block: + - `setL1BlockValuesEcotone` function MUST be called, except if activated at genesis. + The contract is upgraded later in this block, to support `setL1BlockValuesJovian`. +- After the Jovian activation: + - `setL1BlockValuesEcotone` function is deprecated and MUST never be called. + - `setL1BlockValuesJovian` MUST be called with the new Jovian attributes. diff --git a/specs/protocol/jovian/overview.md b/specs/protocol/jovian/overview.md index 07194e8ef..a51849bf3 100644 --- a/specs/protocol/jovian/overview.md +++ b/specs/protocol/jovian/overview.md @@ -6,6 +6,7 @@ - [Execution Layer](#execution-layer) - [Consensus Layer](#consensus-layer) +- [Smart Contracts](#smart-contracts) @@ -13,4 +14,14 @@ This document is not finalized and should be considered experimental. ## Execution Layer +- [L1-Cost function changes](./exec-engine.md#jovian-l1-cost-fee-changes) + ## Consensus Layer + +- [Config update nonces](./configurability.md) +- [Deposit nonces](./deposits.md) +- [Derivation processing of nonces](./derivation.md) + +## Smart Contracts + +- [L1Block](./l1-attributes.md) diff --git a/specs/static/bytecode/jovian-l1-block-deployment.txt b/specs/static/bytecode/jovian-l1-block-deployment.txt new file mode 100644 index 000000000..29e9b0730 --- /dev/null +++ b/specs/static/bytecode/jovian-l1-block-deployment.txt @@ -0,0 +1 @@ +0x608060405234801561001057600080fd5b50610b8c806100206000396000f3fe608060405234801561001057600080fd5b506004361061018d5760003560e01c806371cfaa3f116100e3578063c59859181161008c578063e591b28211610066578063e591b28214610387578063e81b2c6d146103a9578063f8206140146103b257600080fd5b8063c59859181461034b578063d84447151461036b578063de35f5cb1461037357600080fd5b80638b239f73116100bd5780638b239f73146103195780639e8c496614610322578063b80777ea1461032b57600080fd5b806371cfaa3f146102d257806374dd5eab146102e55780638381f58a1461030557600080fd5b8063440a5e20116101455780635cf249691161011f5780635cf249691461026b57806364ca23ef1461027457806368d5dca6146102a157600080fd5b8063440a5e201461021957806354fd4d5014610221578063550fcdc91461026357600080fd5b8063213268491161017657806321326849146101c35780633db6be2b146101db5780634397dfef146101e357600080fd5b8063015d8eb91461019257806309bd5a60146101a7575b600080fd5b6101a56101a03660046109f7565b6103bb565b005b6101b060025481565b6040519081526020015b60405180910390f35b6101cb6104fa565b60405190151581526020016101ba565b6101a5610539565b6101eb610543565b6040805173ffffffffffffffffffffffffffffffffffffffff909316835260ff9091166020830152016101ba565b6101a5610557565b60408051808201909152600581527f312e362e3000000000000000000000000000000000000000000000000000000060208201525b6040516101ba9190610a69565b6102566105ae565b6101b060015481565b6003546102889067ffffffffffffffff1681565b60405167ffffffffffffffff90911681526020016101ba565b6003546102bd9068010000000000000000900463ffffffff1681565b60405163ffffffff90911681526020016101ba565b6101a56102e0366004610adc565b6105bd565b6008546102889068010000000000000000900467ffffffffffffffff1681565b6000546102889067ffffffffffffffff1681565b6101b060055481565b6101b060065481565b6000546102889068010000000000000000900467ffffffffffffffff1681565b6003546102bd906c01000000000000000000000000900463ffffffff1681565b610256610672565b6008546102889067ffffffffffffffff1681565b60405173deaddeaddeaddeaddeaddeaddeaddeaddead000181526020016101ba565b6101b060045481565b6101b060075481565b3373deaddeaddeaddeaddeaddeaddeaddeaddead000114610462576040517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152603b60248201527f4c31426c6f636b3a206f6e6c7920746865206465706f7369746f72206163636f60448201527f756e742063616e20736574204c3120626c6f636b2076616c7565730000000000606482015260840160405180910390fd5b6000805467ffffffffffffffff98891668010000000000000000027fffffffffffffffffffffffffffffffff00000000000000000000000000000000909116998916999099179890981790975560019490945560029290925560038054919094167fffffffffffffffffffffffffffffffffffffffffffffffff00000000000000009190911617909255600491909155600555600655565b600080610505610543565b5073ffffffffffffffffffffffffffffffffffffffff1673eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee141592915050565b61054161067c565b565b60008061054e6106dc565b90939092509050565b73deaddeaddeaddeaddeaddeaddeaddeaddead000133811461058157633cc50b456000526004601cfd5b60043560801c60035560143560801c60005560243560015560443560075560643560025560843560045550565b60606105b861075d565b905090565b3373deaddeaddeaddeaddeaddeaddeaddeaddead00011461060a576040517f3cc50b4500000000000000000000000000000000000000000000000000000000815260040160405180910390fd5b6106168484848461081e565b604080518381526020810183905260ff85169173ffffffffffffffffffffffffffffffffffffffff8716917f10e43c4d58f3ef4edae7c1ca2e7f02d46b2cadbcc046737038527ed8486ffeb0910160405180910390a350505050565b60606105b86108f0565b73deaddeaddeaddeaddeaddeaddeaddeaddead00013381146106a657633cc50b456000526004601cfd5b60043560801c60035560143560801c60005560243560015560443560075560643560025560843560045560a43560801c60085550565b6000808061071261070e60017f04adb1412b2ddc16fcc0d4538d5c8f07cf9c83abecc6b41f6f69037b708fbcec610b41565b5490565b73ffffffffffffffffffffffffffffffffffffffff81169350905082610751575073eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee92601292509050565b60a081901c9150509091565b606060006107696106dc565b5090507fffffffffffffffffffffffff111111111111111111111111111111111111111273ffffffffffffffffffffffffffffffffffffffff8216016107e257505060408051808201909152600381527f4554480000000000000000000000000000000000000000000000000000000000602082015290565b61081861081361070e60017fa48b38a4b44951360fbdcbfaaeae5ed6ae92585412e9841b70ec72ed8cd05764610b41565b6109a6565b91505090565b61088461084c60017f04adb1412b2ddc16fcc0d4538d5c8f07cf9c83abecc6b41f6f69037b708fbcec610b41565b74ff000000000000000000000000000000000000000060a086901b1673ffffffffffffffffffffffffffffffffffffffff8716179055565b6108b76108b260017f657c3582c29b3176614e3a33ddd1ec48352696a04e92b3c0566d72010fa8863d610b41565b839055565b6108ea6108e560017fa48b38a4b44951360fbdcbfaaeae5ed6ae92585412e9841b70ec72ed8cd05764610b41565b829055565b50505050565b606060006108fc6106dc565b5090507fffffffffffffffffffffffff111111111111111111111111111111111111111273ffffffffffffffffffffffffffffffffffffffff82160161097557505060408051808201909152600581527f4574686572000000000000000000000000000000000000000000000000000000602082015290565b61081861081361070e60017f657c3582c29b3176614e3a33ddd1ec48352696a04e92b3c0566d72010fa8863d610b41565b60405160005b82811a156109bc576001016109ac565b80825260208201838152600082820152505060408101604052919050565b803567ffffffffffffffff811681146109f257600080fd5b919050565b600080600080600080600080610100898b031215610a1457600080fd5b610a1d896109da565b9750610a2b60208a016109da565b96506040890135955060608901359450610a4760808a016109da565b979a969950949793969560a0850135955060c08501359460e001359350915050565b600060208083528351808285015260005b81811015610a9657858101830151858201604001528201610a7a565b81811115610aa8576000604083870101525b50601f017fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe016929092016040019392505050565b60008060008060808587031215610af257600080fd5b843573ffffffffffffffffffffffffffffffffffffffff81168114610b1657600080fd5b9350602085013560ff81168114610b2c57600080fd5b93969395505050506040820135916060013590565b600082821015610b7a577f4e487b7100000000000000000000000000000000000000000000000000000000600052601160045260246000fd5b50039056fea164736f6c634300080f000a \ No newline at end of file