From ee2ecebca14bdab227720c9f09587fb37b9ad3a7 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Tue, 23 Jul 2024 17:45:18 +0800 Subject: [PATCH 01/18] add inbox-contract.md --- specs/experimental/inbox-contract.md | 31 ++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 specs/experimental/inbox-contract.md diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md new file mode 100644 index 000000000..abde7e16e --- /dev/null +++ b/specs/experimental/inbox-contract.md @@ -0,0 +1,31 @@ +# Inbox Contract + +## Motivation + +The batch inbox is currently an Externally Owned Account (EOA), which has both advantages and disadvantages: + +Advantages: +- Low submission gas cost due to the absence of onchain execution. +- Verification logic is moved offchain to the derivation part, protected by a fault dispute game with a correct absolute prestate. + +Disadvantage: +- Onchain verification is not possible. + + +This specification aims to allow the batch inbox to be a contract, enabling customized batch submission conditions such as: +- Requiring the batch transaction to be signed by a quorum of sequencers in a decentralized sequencing network; or +- Mandating that the batch transaction call a BLOB storage contract (e.g., EthStorage) with a long-term storage fee, which is then distributed to data nodes that prove BLOB storage over time. + +## How It Works + +The integration process consists of two primary components: +1. Replacement of the [`BatchInboxAddress`](https://github.com/ethereum-optimism/optimism/blob/db107794c0b755bc38a8c62f11c49320c95c73db/op-chain-ops/genesis/config.go#L77) with an inbox contract: The existing `BatchInboxAddress`, which currently points to an Externally Owned Account (EOA), will be replaced by a smart contract. This new inbox contract will be responsible for verifying and enforcing batch submission conditions. +2. Modification of the op-node derivation process: The op-node will be updated to exclude failed batch transactions during the derivation process. This change ensures that only successfully executed batch transactions are processed and included in the derived state. + +These modifications aim to enhance the security and efficiency of the batch submission and processing pipeline, allowing for more flexible and customizable conditions while maintaining the integrity of the derived state. + + +## Reference Implementation + +1. [example inbox contract for EthStorage](https://github.com/blockchaindevsh/es-op-batchinbox/blob/main/src/BatchInbox.sol) +2. [op-node derive changes](https://github.com/ethstorage/optimism/pull/22) \ No newline at end of file From fa2dee80d5246edf33192d81d8418f89f768983e Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Wed, 24 Jul 2024 14:27:51 +0800 Subject: [PATCH 02/18] add more details and migration process --- specs/experimental/inbox-contract.md | 38 +++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index abde7e16e..e21650185 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -18,14 +18,46 @@ This specification aims to allow the batch inbox to be a contract, enabling cust ## How It Works -The integration process consists of two primary components: +The integration process consists of four primary components: 1. Replacement of the [`BatchInboxAddress`](https://github.com/ethereum-optimism/optimism/blob/db107794c0b755bc38a8c62f11c49320c95c73db/op-chain-ops/genesis/config.go#L77) with an inbox contract: The existing `BatchInboxAddress`, which currently points to an Externally Owned Account (EOA), will be replaced by a smart contract. This new inbox contract will be responsible for verifying and enforcing batch submission conditions. -2. Modification of the op-node derivation process: The op-node will be updated to exclude failed batch transactions during the derivation process. This change ensures that only successfully executed batch transactions are processed and included in the derived state. +2. Modification of the op-node derivation process: The op-node will be updated to exclude failed batch transactions during the derivation process. This change ensures that only successfully executed batch transactions are processed and included in the derived state. +3. Modification of the op-batcher submission process: The op-batcher will be updated to resend failed batch transactions. +4. To implement this feature as an optional setting, we introduced a `UseInboxContract` boolean field in both the `DeployConfig` and `rollup.Config` structures. When `UseInboxContract` is set to false, the system maintains its previous behavior, ensuring backward compatibility. These modifications aim to enhance the security and efficiency of the batch submission and processing pipeline, allowing for more flexible and customizable conditions while maintaining the integrity of the derived state. +## Migration Process + +A new function `setBatchInbox` will be introduced to the `SystemConfig` contract, enabling dynamic updates to the [`BatchInboxAddress`](https://github.com/ethereum-optimism/optimism/blob/8b1b67021fb77d7e33118b749679480532fce976/op-node/rollup/types.go#L120): + +```solidity +/// @notice Updates the batch inbox address. Can only be called by the owner. +/// @param _batchInbox New batch inbox address. +function setBatchInbox(address _batchInbox) external onlyOwner { + _setBatchInbox(_unsafeBlockSigner); +} + +/// @notice Updates the batch inbox address. +/// @param _batchInbox New batch inbox address. +function _setBatchInbox(address _batchInbox) internal { + Storage.setAddress(BATCH_INBOX_SLOT, _batchInbox); + + bytes memory data = abi.encode(_batchInbox, _batchInbox.code.length > 0); + emit ConfigUpdate(VERSION, UpdateType.BATCH_INBOX, data); +} + +enum UpdateType { + ... + BATCH_INBOX +} +``` + +The `UseInboxContract` flag is automatically set to true for both the `op-node` and `op-batcher` components if `_batchInbox` corresponds to a valid contract address. If `_batchInbox` is not a valid contract address, the flag is set to false. + ## Reference Implementation 1. [example inbox contract for EthStorage](https://github.com/blockchaindevsh/es-op-batchinbox/blob/main/src/BatchInbox.sol) -2. [op-node derive changes](https://github.com/ethstorage/optimism/pull/22) \ No newline at end of file +2. [op-node & op-batcher changes](https://github.com/blockchaindevsh/optimism/compare/5137f3b74c6ebcac4f0f5a118b0f4909df03aec6...02e3b7248f1b590a2adf1f81488829760fa2ba03) + +TODO: implement `Migration Process` mentioned above. \ No newline at end of file From cb4affe62e214be6777f725ab35b4cfaaf4acc41 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Wed, 24 Jul 2024 23:03:52 +0800 Subject: [PATCH 03/18] update about resend --- specs/experimental/inbox-contract.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index e21650185..a3a8eaf11 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -21,7 +21,8 @@ This specification aims to allow the batch inbox to be a contract, enabling cust The integration process consists of four primary components: 1. Replacement of the [`BatchInboxAddress`](https://github.com/ethereum-optimism/optimism/blob/db107794c0b755bc38a8c62f11c49320c95c73db/op-chain-ops/genesis/config.go#L77) with an inbox contract: The existing `BatchInboxAddress`, which currently points to an Externally Owned Account (EOA), will be replaced by a smart contract. This new inbox contract will be responsible for verifying and enforcing batch submission conditions. 2. Modification of the op-node derivation process: The op-node will be updated to exclude failed batch transactions during the derivation process. This change ensures that only successfully executed batch transactions are processed and included in the derived state. -3. Modification of the op-batcher submission process: The op-batcher will be updated to resend failed batch transactions. +3. Modification of the op-batcher submission process: The op-batcher will be updated to [call `recordFailedTx`](https://github.com/blockchaindevsh/optimism/blob/02e3b7248f1b590a2adf1f81488829760fa2ba03/op-batcher/batcher/driver.go#L537) for failed batch transactions. This modification ensures that the data contained in failed transactions will be resubmitted automatically. + 1. Most failures will be detected during the [`EstimateGas`](https://github.com/ethereum-optimism/optimism/blob/8f516faf42da416c02355f9981add3137a3db190/op-service/txmgr/txmgr.go#L266) call. However, under certain race conditions, failures may occur after the transaction has been included in a block. 4. To implement this feature as an optional setting, we introduced a `UseInboxContract` boolean field in both the `DeployConfig` and `rollup.Config` structures. When `UseInboxContract` is set to false, the system maintains its previous behavior, ensuring backward compatibility. These modifications aim to enhance the security and efficiency of the batch submission and processing pipeline, allowing for more flexible and customizable conditions while maintaining the integrity of the derived state. @@ -35,7 +36,7 @@ A new function `setBatchInbox` will be introduced to the `SystemConfig` contract /// @notice Updates the batch inbox address. Can only be called by the owner. /// @param _batchInbox New batch inbox address. function setBatchInbox(address _batchInbox) external onlyOwner { - _setBatchInbox(_unsafeBlockSigner); + _setBatchInbox(_batchInbox); } /// @notice Updates the batch inbox address. From 0ff37bf677677f009b62d711f241383aeed37428 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Sun, 28 Jul 2024 11:32:54 +0800 Subject: [PATCH 04/18] update --- specs/experimental/inbox-contract.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index a3a8eaf11..1598f5912 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -1,5 +1,16 @@ # Inbox Contract + + +**Table of Contents** +- [Inbox Contract](#inbox-contract) + - [Motivation](#motivation) + - [How It Works](#how-it-works) + - [Migration Process](#migration-process) + - [How `op-node` knows the canonical batch inbox](#how-op-node-knows-the-canonical-batch-inbox) + - [How `op-batcher` knows canonical batch inbox](#how-op-batcher-knows-canonical-batch-inbox) + - [Reference Implementation](#reference-implementation) + ## Motivation The batch inbox is currently an Externally Owned Account (EOA), which has both advantages and disadvantages: @@ -20,7 +31,7 @@ This specification aims to allow the batch inbox to be a contract, enabling cust The integration process consists of four primary components: 1. Replacement of the [`BatchInboxAddress`](https://github.com/ethereum-optimism/optimism/blob/db107794c0b755bc38a8c62f11c49320c95c73db/op-chain-ops/genesis/config.go#L77) with an inbox contract: The existing `BatchInboxAddress`, which currently points to an Externally Owned Account (EOA), will be replaced by a smart contract. This new inbox contract will be responsible for verifying and enforcing batch submission conditions. -2. Modification of the op-node derivation process: The op-node will be updated to exclude failed batch transactions during the derivation process. This change ensures that only successfully executed batch transactions are processed and included in the derived state. +2. Modification of the `op-node` derivation process: The `op-node` will be updated to exclude failed batch transactions during the derivation process. This change ensures that only successfully executed batch transactions are processed and included in the derived state. 3. Modification of the op-batcher submission process: The op-batcher will be updated to [call `recordFailedTx`](https://github.com/blockchaindevsh/optimism/blob/02e3b7248f1b590a2adf1f81488829760fa2ba03/op-batcher/batcher/driver.go#L537) for failed batch transactions. This modification ensures that the data contained in failed transactions will be resubmitted automatically. 1. Most failures will be detected during the [`EstimateGas`](https://github.com/ethereum-optimism/optimism/blob/8f516faf42da416c02355f9981add3137a3db190/op-service/txmgr/txmgr.go#L266) call. However, under certain race conditions, failures may occur after the transaction has been included in a block. 4. To implement this feature as an optional setting, we introduced a `UseInboxContract` boolean field in both the `DeployConfig` and `rollup.Config` structures. When `UseInboxContract` is set to false, the system maintains its previous behavior, ensuring backward compatibility. @@ -56,6 +67,19 @@ enum UpdateType { The `UseInboxContract` flag is automatically set to true for both the `op-node` and `op-batcher` components if `_batchInbox` corresponds to a valid contract address. If `_batchInbox` is not a valid contract address, the flag is set to false. +### How `op-node` knows the canonical batch inbox + +Under normal conditions, `op-node` knows the canonical batch inbox through the derivation pipeline: +1. The `L1Traversal` componenet first identifies the L1 `SystemConfig` changes while traversing the L1 block, via [`UpdateSystemConfigWithL1Receipts`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_traversal.go#L78). This includes batcher and inbox changes. + 1. The [`ProcessSystemConfigUpdateLogEvent`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/system_config.go#L59) function will be modified to parse the newly added inbox change. +2. The `L1Retrieval` component then fetches the canonical batch inbox from the `L1Traversal` componenet and [pass](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_retrieval.go#L57) it to the `DataSourceFactory` component, via `OpenData` function, similar to how [`SystemConfig.BatcherAddr`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-service/eth/types.go#L382) is handled. + +During L2 reorganization, `op-node` knows the canonical batch inbox using the `SystemConfig` parameter of [`ResettableStage.Reset(context.Context, eth.L1BlockRef, eth.SystemConfig)`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/pipeline.go#L38) function. + +### How `op-batcher` knows canonical batch inbox + +Immediately before submitting a new batch, `op-batcher` fetches the current inbox address from L1 and submits to that address. After the transaction is successfully included in L1 at block `N`, `op-batcher` verifies that the inbox address hasn't changed at block `N`. If the address has changed, it resubmits the batch to the new address. + ## Reference Implementation 1. [example inbox contract for EthStorage](https://github.com/blockchaindevsh/es-op-batchinbox/blob/main/src/BatchInbox.sol) From fb51959460f4985041cafb9e52ec6440530a1c71 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Tue, 30 Jul 2024 00:22:12 +0800 Subject: [PATCH 05/18] more update --- specs/experimental/inbox-contract.md | 45 +++++++++++++++++++++------- 1 file changed, 35 insertions(+), 10 deletions(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index 1598f5912..b810aa7fa 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -6,9 +6,13 @@ - [Inbox Contract](#inbox-contract) - [Motivation](#motivation) - [How It Works](#how-it-works) - - [Migration Process](#migration-process) + - [Dynamic Updates](#dynamic-updates) + - [SystemConfig](#systemconfig) + - [setBatchInbox](#setbatchinbox) + - [UpdateType](#updatetype) - [How `op-node` knows the canonical batch inbox](#how-op-node-knows-the-canonical-batch-inbox) - [How `op-batcher` knows canonical batch inbox](#how-op-batcher-knows-canonical-batch-inbox) + - [Upgrade](#upgrade) - [Reference Implementation](#reference-implementation) ## Motivation @@ -27,21 +31,27 @@ This specification aims to allow the batch inbox to be a contract, enabling cust - Requiring the batch transaction to be signed by a quorum of sequencers in a decentralized sequencing network; or - Mandating that the batch transaction call a BLOB storage contract (e.g., EthStorage) with a long-term storage fee, which is then distributed to data nodes that prove BLOB storage over time. + ## How It Works -The integration process consists of four primary components: +The integration process consists of three primary components: 1. Replacement of the [`BatchInboxAddress`](https://github.com/ethereum-optimism/optimism/blob/db107794c0b755bc38a8c62f11c49320c95c73db/op-chain-ops/genesis/config.go#L77) with an inbox contract: The existing `BatchInboxAddress`, which currently points to an Externally Owned Account (EOA), will be replaced by a smart contract. This new inbox contract will be responsible for verifying and enforcing batch submission conditions. 2. Modification of the `op-node` derivation process: The `op-node` will be updated to exclude failed batch transactions during the derivation process. This change ensures that only successfully executed batch transactions are processed and included in the derived state. 3. Modification of the op-batcher submission process: The op-batcher will be updated to [call `recordFailedTx`](https://github.com/blockchaindevsh/optimism/blob/02e3b7248f1b590a2adf1f81488829760fa2ba03/op-batcher/batcher/driver.go#L537) for failed batch transactions. This modification ensures that the data contained in failed transactions will be resubmitted automatically. 1. Most failures will be detected during the [`EstimateGas`](https://github.com/ethereum-optimism/optimism/blob/8f516faf42da416c02355f9981add3137a3db190/op-service/txmgr/txmgr.go#L266) call. However, under certain race conditions, failures may occur after the transaction has been included in a block. -4. To implement this feature as an optional setting, we introduced a `UseInboxContract` boolean field in both the `DeployConfig` and `rollup.Config` structures. When `UseInboxContract` is set to false, the system maintains its previous behavior, ensuring backward compatibility. These modifications aim to enhance the security and efficiency of the batch submission and processing pipeline, allowing for more flexible and customizable conditions while maintaining the integrity of the derived state. -## Migration Process +## Dynamic Updates + +### SystemConfig + +The `SystemConfig` is the source of truth for the address of inbox. It stores information about the inbox address and passes the information to L2 as well. + +#### setBatchInbox -A new function `setBatchInbox` will be introduced to the `SystemConfig` contract, enabling dynamic updates to the [`BatchInboxAddress`](https://github.com/ethereum-optimism/optimism/blob/8b1b67021fb77d7e33118b749679480532fce976/op-node/rollup/types.go#L120): +A new function `setBatchInbox` is introduced to the `SystemConfig` contract, enabling dynamic updates to the inbox: ```solidity /// @notice Updates the batch inbox address. Can only be called by the owner. @@ -55,24 +65,35 @@ function setBatchInbox(address _batchInbox) external onlyOwner { function _setBatchInbox(address _batchInbox) internal { Storage.setAddress(BATCH_INBOX_SLOT, _batchInbox); - bytes memory data = abi.encode(_batchInbox, _batchInbox.code.length > 0); + bytes memory data = abi.encode(_batchInbox); emit ConfigUpdate(VERSION, UpdateType.BATCH_INBOX, data); } +``` + +#### UpdateType + +A new enum value `BATCH_INBOX` is added to the `UpdateType` enumeration. + +```solidity enum UpdateType { - ... + BATCHER, + GAS_CONFIG, + GAS_LIMIT, + UNSAFE_BLOCK_SIGNER, BATCH_INBOX } ``` -The `UseInboxContract` flag is automatically set to true for both the `op-node` and `op-batcher` components if `_batchInbox` corresponds to a valid contract address. If `_batchInbox` is not a valid contract address, the flag is set to false. - ### How `op-node` knows the canonical batch inbox +We define the canonical batch inbox at L2 block `n` as the batch inbox at the L1 origin of L2 block `n`. + Under normal conditions, `op-node` knows the canonical batch inbox through the derivation pipeline: 1. The `L1Traversal` componenet first identifies the L1 `SystemConfig` changes while traversing the L1 block, via [`UpdateSystemConfigWithL1Receipts`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_traversal.go#L78). This includes batcher and inbox changes. 1. The [`ProcessSystemConfigUpdateLogEvent`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/system_config.go#L59) function will be modified to parse the newly added inbox change. 2. The `L1Retrieval` component then fetches the canonical batch inbox from the `L1Traversal` componenet and [pass](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_retrieval.go#L57) it to the `DataSourceFactory` component, via `OpenData` function, similar to how [`SystemConfig.BatcherAddr`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-service/eth/types.go#L382) is handled. +3. The `FetchingAttributesBuilder` component is updated to incorporate the canonical batch inbox into the `DepositTx`, via [`L1InfoDeposit`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_block_info.go#L263). This modified `DepositTx` is subsequently used to calculate the `SystemConfig` during L2 chain reorganization. During L2 reorganization, `op-node` knows the canonical batch inbox using the `SystemConfig` parameter of [`ResettableStage.Reset(context.Context, eth.L1BlockRef, eth.SystemConfig)`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/pipeline.go#L38) function. @@ -80,9 +101,13 @@ During L2 reorganization, `op-node` knows the canonical batch inbox using the `S Immediately before submitting a new batch, `op-batcher` fetches the current inbox address from L1 and submits to that address. After the transaction is successfully included in L1 at block `N`, `op-batcher` verifies that the inbox address hasn't changed at block `N`. If the address has changed, it resubmits the batch to the new address. +## Upgrade + +Existing OP Stack instances need to upgrade the `SystemConfig` in order to use this feature. + ## Reference Implementation 1. [example inbox contract for EthStorage](https://github.com/blockchaindevsh/es-op-batchinbox/blob/main/src/BatchInbox.sol) 2. [op-node & op-batcher changes](https://github.com/blockchaindevsh/optimism/compare/5137f3b74c6ebcac4f0f5a118b0f4909df03aec6...02e3b7248f1b590a2adf1f81488829760fa2ba03) -TODO: implement `Migration Process` mentioned above. \ No newline at end of file +TODO: implement `Dynamic Updates` mentioned above. \ No newline at end of file From 79fa1a537be70520b7f99655d8b1d5edba0a860c Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Tue, 30 Jul 2024 17:51:12 +0800 Subject: [PATCH 06/18] partial fix --- specs/experimental/inbox-contract.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index b810aa7fa..6f362dde9 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -6,7 +6,7 @@ - [Inbox Contract](#inbox-contract) - [Motivation](#motivation) - [How It Works](#how-it-works) - - [Dynamic Updates](#dynamic-updates) + - [Supporting Dynamic Updates to Inbox Address](#supporting-dynamic-updates-to-inbox-address) - [SystemConfig](#systemconfig) - [setBatchInbox](#setbatchinbox) - [UpdateType](#updatetype) @@ -43,7 +43,7 @@ The integration process consists of three primary components: These modifications aim to enhance the security and efficiency of the batch submission and processing pipeline, allowing for more flexible and customizable conditions while maintaining the integrity of the derived state. -## Dynamic Updates +## Supporting Dynamic Updates to Inbox Address ### SystemConfig @@ -90,12 +90,12 @@ enum UpdateType { We define the canonical batch inbox at L2 block `n` as the batch inbox at the L1 origin of L2 block `n`. Under normal conditions, `op-node` knows the canonical batch inbox through the derivation pipeline: -1. The `L1Traversal` componenet first identifies the L1 `SystemConfig` changes while traversing the L1 block, via [`UpdateSystemConfigWithL1Receipts`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_traversal.go#L78). This includes batcher and inbox changes. +1. The `L1Traversal` component first identifies the L1 `SystemConfig` changes while traversing the L1 block, via [`UpdateSystemConfigWithL1Receipts`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_traversal.go#L78). 1. The [`ProcessSystemConfigUpdateLogEvent`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/system_config.go#L59) function will be modified to parse the newly added inbox change. 2. The `L1Retrieval` component then fetches the canonical batch inbox from the `L1Traversal` componenet and [pass](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_retrieval.go#L57) it to the `DataSourceFactory` component, via `OpenData` function, similar to how [`SystemConfig.BatcherAddr`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-service/eth/types.go#L382) is handled. -3. The `FetchingAttributesBuilder` component is updated to incorporate the canonical batch inbox into the `DepositTx`, via [`L1InfoDeposit`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_block_info.go#L263). This modified `DepositTx` is subsequently used to calculate the `SystemConfig` during L2 chain reorganization. +3. The `FetchingAttributesBuilder` component is updated to incorporate the canonical batch inbox into the `DepositTx`, via [`L1InfoDeposit`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_block_info.go#L263). This modified `DepositTx` is subsequently used to obtain the `SystemConfig` during L2 chain reorganization. -During L2 reorganization, `op-node` knows the canonical batch inbox using the `SystemConfig` parameter of [`ResettableStage.Reset(context.Context, eth.L1BlockRef, eth.SystemConfig)`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/pipeline.go#L38) function. +During L2 reorganization, `op-node` knows the canonical batch inbox using the `SystemConfig` parameter of [`ResettableStage.Reset(context.Context, eth.L1BlockRef, eth.SystemConfig)`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/pipeline.go#L38) function, where `SystemConfig` is derived from the `DepositTx` of the corresponding L2 block. ### How `op-batcher` knows canonical batch inbox From ea9b6b0d061f1d1d79b7c747b981b8e6d7fa3178 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Tue, 30 Jul 2024 18:03:18 +0800 Subject: [PATCH 07/18] optimize for `n` --- specs/experimental/inbox-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index 6f362dde9..593456c04 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -87,7 +87,7 @@ enum UpdateType { ### How `op-node` knows the canonical batch inbox -We define the canonical batch inbox at L2 block `n` as the batch inbox at the L1 origin of L2 block `n`. +We define the canonical batch inbox at a specific L2 block(denoted as `bn`) as the batch inbox corresponding to the L1 block that serves as the origin of `bn`. Under normal conditions, `op-node` knows the canonical batch inbox through the derivation pipeline: 1. The `L1Traversal` component first identifies the L1 `SystemConfig` changes while traversing the L1 block, via [`UpdateSystemConfigWithL1Receipts`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_traversal.go#L78). From ebddbec5ecb447c1311f0b5f4fbaa3d0a93bfb6a Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Tue, 30 Jul 2024 19:56:35 +0800 Subject: [PATCH 08/18] add SystemConfig.initialize section --- specs/experimental/inbox-contract.md | 30 ++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index 593456c04..d416394b8 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -9,6 +9,7 @@ - [Supporting Dynamic Updates to Inbox Address](#supporting-dynamic-updates-to-inbox-address) - [SystemConfig](#systemconfig) - [setBatchInbox](#setbatchinbox) + - [initialize](#initialize) - [UpdateType](#updatetype) - [How `op-node` knows the canonical batch inbox](#how-op-node-knows-the-canonical-batch-inbox) - [How `op-batcher` knows canonical batch inbox](#how-op-batcher-knows-canonical-batch-inbox) @@ -49,6 +50,7 @@ These modifications aim to enhance the security and efficiency of the batch subm The `SystemConfig` is the source of truth for the address of inbox. It stores information about the inbox address and passes the information to L2 as well. + #### setBatchInbox A new function `setBatchInbox` is introduced to the `SystemConfig` contract, enabling dynamic updates to the inbox: @@ -71,6 +73,34 @@ function _setBatchInbox(address _batchInbox) internal { ``` + +#### initialize + +The `SystemConfig` now emits an event when the inbox is initialized, while retaining its existing support for inbox configuration during initialization. + +```solidity +function initialize( + address _owner, + uint32 _basefeeScalar, + uint32 _blobbasefeeScalar, + bytes32 _batcherHash, + uint64 _gasLimit, + address _unsafeBlockSigner, + ResourceMetering.ResourceConfig memory _config, + address _batchInbox, + SystemConfig.Addresses memory _addresses +) + public + initializer +{ + ... + // Storage.setAddress(BATCH_INBOX_SLOT, _batchInbox); + // initialize inbox by `_setBatchInbox` so that an event is emitted. + _setBatchInbox(_batchInbox); + ... +} +``` + #### UpdateType A new enum value `BATCH_INBOX` is added to the `UpdateType` enumeration. From 2f22e44289838c26da04bdfb16fc419e8a84b459 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Tue, 30 Jul 2024 20:09:36 +0800 Subject: [PATCH 09/18] remove the term "replacement" --- specs/experimental/inbox-contract.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index d416394b8..ec1c2189b 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -36,7 +36,7 @@ This specification aims to allow the batch inbox to be a contract, enabling cust ## How It Works The integration process consists of three primary components: -1. Replacement of the [`BatchInboxAddress`](https://github.com/ethereum-optimism/optimism/blob/db107794c0b755bc38a8c62f11c49320c95c73db/op-chain-ops/genesis/config.go#L77) with an inbox contract: The existing `BatchInboxAddress`, which currently points to an Externally Owned Account (EOA), will be replaced by a smart contract. This new inbox contract will be responsible for verifying and enforcing batch submission conditions. +1. The [`BatchInboxAddress`](https://github.com/ethereum-optimism/optimism/blob/db107794c0b755bc38a8c62f11c49320c95c73db/op-chain-ops/genesis/config.go#L77) can now be set to either an Externally Owned Account (EOA) or a smart contract. When a contract is used, it assumes responsibility for verifying and enforcing batch submission conditions. 2. Modification of the `op-node` derivation process: The `op-node` will be updated to exclude failed batch transactions during the derivation process. This change ensures that only successfully executed batch transactions are processed and included in the derived state. 3. Modification of the op-batcher submission process: The op-batcher will be updated to [call `recordFailedTx`](https://github.com/blockchaindevsh/optimism/blob/02e3b7248f1b590a2adf1f81488829760fa2ba03/op-batcher/batcher/driver.go#L537) for failed batch transactions. This modification ensures that the data contained in failed transactions will be resubmitted automatically. 1. Most failures will be detected during the [`EstimateGas`](https://github.com/ethereum-optimism/optimism/blob/8f516faf42da416c02355f9981add3137a3db190/op-service/txmgr/txmgr.go#L266) call. However, under certain race conditions, failures may occur after the transaction has been included in a block. @@ -133,7 +133,7 @@ Immediately before submitting a new batch, `op-batcher` fetches the current inbo ## Upgrade -Existing OP Stack instances need to upgrade the `SystemConfig` in order to use this feature. +Existing OP Stack instances need to upgrade the `SystemConfig` and set an inbox contract in order to use this feature. ## Reference Implementation From bc70be19d249ea79cf2c8ec65f2c56ff8d329785 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Tue, 30 Jul 2024 21:48:19 +0800 Subject: [PATCH 10/18] mod definition for canonical batch inbox --- specs/experimental/inbox-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index ec1c2189b..007e37194 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -117,7 +117,7 @@ enum UpdateType { ### How `op-node` knows the canonical batch inbox -We define the canonical batch inbox at a specific L2 block(denoted as `bn`) as the batch inbox corresponding to the L1 block that serves as the origin of `bn`. +We define that the canonical batch inbox at a specific L2 block is the batch inbox of `SystemConfig` of the origin of the L2 block. Under normal conditions, `op-node` knows the canonical batch inbox through the derivation pipeline: 1. The `L1Traversal` component first identifies the L1 `SystemConfig` changes while traversing the L1 block, via [`UpdateSystemConfigWithL1Receipts`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_traversal.go#L78). From 0f0609a468437b7b0fc50195eb7db6c4970c7ab6 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Wed, 31 Jul 2024 15:30:20 +0800 Subject: [PATCH 11/18] add a section about "Inbox Sender" --- specs/experimental/inbox-contract.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index 007e37194..72a0d8082 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -14,6 +14,8 @@ - [How `op-node` knows the canonical batch inbox](#how-op-node-knows-the-canonical-batch-inbox) - [How `op-batcher` knows canonical batch inbox](#how-op-batcher-knows-canonical-batch-inbox) - [Upgrade](#upgrade) + - [Security Considerations](#security-considerations) + - [Inbox Sender](#inbox-sender) - [Reference Implementation](#reference-implementation) ## Motivation @@ -135,9 +137,17 @@ Immediately before submitting a new batch, `op-batcher` fetches the current inbo Existing OP Stack instances need to upgrade the `SystemConfig` and set an inbox contract in order to use this feature. +## Security Considerations + + +### Inbox Sender + +The inbox contract is a special contract that, if invoked by the batcher, all of its calldata / blob will be used as L2 derivation data, unless the transaction fails. In order to invoke and modify the state of the inbox contract, it is recommended to use a non-batcher sender. + + ## Reference Implementation 1. [example inbox contract for EthStorage](https://github.com/blockchaindevsh/es-op-batchinbox/blob/main/src/BatchInbox.sol) 2. [op-node & op-batcher changes](https://github.com/blockchaindevsh/optimism/compare/5137f3b74c6ebcac4f0f5a118b0f4909df03aec6...02e3b7248f1b590a2adf1f81488829760fa2ba03) -TODO: implement `Dynamic Updates` mentioned above. \ No newline at end of file +TODO: implement `Supporting Dynamic Updates to Inbox Address` mentioned above. \ No newline at end of file From b7448c1002f363c1d80fd34a36bddb21c3b8402a Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Wed, 31 Jul 2024 16:13:57 +0800 Subject: [PATCH 12/18] add section for L1Block --- specs/experimental/inbox-contract.md | 33 ++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index 72a0d8082..ae69d9880 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -11,6 +11,9 @@ - [setBatchInbox](#setbatchinbox) - [initialize](#initialize) - [UpdateType](#updatetype) + - [L1Block](#l1block) + - [batchInbox](#batchinbox) + - [setL1BlockValuesEcotone](#setl1blockvaluesecotone) - [How `op-node` knows the canonical batch inbox](#how-op-node-knows-the-canonical-batch-inbox) - [How `op-batcher` knows canonical batch inbox](#how-op-batcher-knows-canonical-batch-inbox) - [Upgrade](#upgrade) @@ -117,6 +120,31 @@ enum UpdateType { } ``` +### L1Block + +The `L1Block` stores Layer 1 (L1) related information on Layer 2 (L2). It is extended to also store the inbox address. + +#### batchInbox + +A new field `batchInbox` is added to the `L1Block`: + +```solidity + /// @notice The canonical batch inbox. + bytes32 public batchInbox; +``` + +#### setL1BlockValuesEcotone + +This function stores Layer 1 (L1) block values for Layer 2 (L2) since the Ecotone upgrade of the OP Stack. It is enhanced to also store the inbox address. + +```solidity +function setL1BlockValuesEcotone() external { + ... + sstore(batchInbox.slot, calldataload(164)) // bytes32 +} + +``` + ### How `op-node` knows the canonical batch inbox We define that the canonical batch inbox at a specific L2 block is the batch inbox of `SystemConfig` of the origin of the L2 block. @@ -135,11 +163,12 @@ Immediately before submitting a new batch, `op-batcher` fetches the current inbo ## Upgrade -Existing OP Stack instances need to upgrade the `SystemConfig` and set an inbox contract in order to use this feature. +To use this feature, existing OP Stack instances must complete two steps: +1. Upgrade the `SystemConfig` and set an inbox contract on L1. +2. Upgrade the `L1Blocck` on L2. ## Security Considerations - ### Inbox Sender The inbox contract is a special contract that, if invoked by the batcher, all of its calldata / blob will be used as L2 derivation data, unless the transaction fails. In order to invoke and modify the state of the inbox contract, it is recommended to use a non-batcher sender. From 6296a624952a3da02aed5dc123bf18fbf37361c2 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Wed, 31 Jul 2024 16:16:56 +0800 Subject: [PATCH 13/18] fix typo --- specs/experimental/inbox-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index ae69d9880..cb998fa0a 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -165,7 +165,7 @@ Immediately before submitting a new batch, `op-batcher` fetches the current inbo To use this feature, existing OP Stack instances must complete two steps: 1. Upgrade the `SystemConfig` and set an inbox contract on L1. -2. Upgrade the `L1Blocck` on L2. +2. Upgrade the `L1Block` on L2. ## Security Considerations From 7248e23a6c93053a5cae5906c8521f30b55165c0 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Fri, 2 Aug 2024 11:09:41 +0800 Subject: [PATCH 14/18] update about upgrade process --- specs/experimental/inbox-contract.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index cb998fa0a..5c88d50b8 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -167,6 +167,13 @@ To use this feature, existing OP Stack instances must complete two steps: 1. Upgrade the `SystemConfig` and set an inbox contract on L1. 2. Upgrade the `L1Block` on L2. +Note that according to the [Optimism Style Guide](https://github.com/ethereum-optimism/optimism/blob/9d31040ecf8590423adf267ad24b03bc1bf7273b/packages/contracts-bedrock/STYLE_GUIDE.md), The process for upgrading the implementation is as follows: +1. Upgrade the implementation to the `StorageSetter` contract. +2. Use that to set the initialized slot (typically slot 0) to zero. +3. Upgrade the implementation to the desired new implementation and initialize it. + +For a practical example of this process, refer to [this](https://github.com/ethereum-optimism/superchain-ops/blob/55e9520e27c7e916d8992ce351c6d5cfa8a511d8/tasks/eth/009-fp-upgrade/EXEC.md) execution document in the Optimism Superchain Operations repository. + ## Security Considerations ### Inbox Sender From eeee1785ed083eea09c87636d5a5723653a103df Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Fri, 2 Aug 2024 17:45:04 +0800 Subject: [PATCH 15/18] mod language for review --- specs/experimental/inbox-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index 5c88d50b8..f0e136086 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -122,7 +122,7 @@ enum UpdateType { ### L1Block -The `L1Block` stores Layer 1 (L1) related information on Layer 2 (L2). It is extended to also store the inbox address. +The `L1Block` stores Layer 1 (L1) related information on Layer 2 (L2). It is extended to store the dynamic inbox address. #### batchInbox From 01a41b02f448ac57b0a616041651fcd0563c6023 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Sat, 3 Aug 2024 12:35:43 +0800 Subject: [PATCH 16/18] add a section for `L1InfoDeposit` function --- specs/experimental/inbox-contract.md | 80 ++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index f0e136086..ccc4ec09f 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -11,6 +11,7 @@ - [setBatchInbox](#setbatchinbox) - [initialize](#initialize) - [UpdateType](#updatetype) + - [L1 Info Deposit Transaction](#l1-info-deposit-transaction) - [L1Block](#l1block) - [batchInbox](#batchinbox) - [setL1BlockValuesEcotone](#setl1blockvaluesecotone) @@ -120,6 +121,85 @@ enum UpdateType { } ``` +### L1 Info Deposit Transaction + +The [`L1InfoDeposit`](https://github.com/ethereum-optimism/optimism/blob/5e317379fae65b76f5a6ee27581f0e62d2fe017a/op-node/rollup/derive/l1_block_info.go#L264) function creates a L1 Info deposit transaction based on the L1 block. It is extended to add an additional `batchInbox` parameter for the [`setL1BlockValuesEcotone`](https://github.com/ethereum-optimism/optimism/blob/5e317379fae65b76f5a6ee27581f0e62d2fe017a/packages/contracts-bedrock/src/L2/L1Block.sol#L136) function after the inbox contract feature is activated. + +```golang +func L1InfoDeposit(rollupCfg *rollup.Config, sysCfg eth.SystemConfig, seqNumber uint64, block eth.BlockInfo, l2BlockTime uint64) (*types.DepositTx, error) { + ... + if isInboxForkButNotFirstBlock(rollupCfg, l2BlockTime) { + l1BlockInfo.BatchInbox = sysCfg.BatchInbox + l1BlockInfo.BlobBaseFee = block.BlobBaseFee() + if l1BlockInfo.BlobBaseFee == nil { + // The L2 spec states to use the MIN_BLOB_GASPRICE from EIP-4844 if not yet active on L1. + l1BlockInfo.BlobBaseFee = big.NewInt(1) + } + scalars, err := sysCfg.EcotoneScalars() + if err != nil { + return nil, err + } + l1BlockInfo.BlobBaseFeeScalar = scalars.BlobBaseFeeScalar + l1BlockInfo.BaseFeeScalar = scalars.BaseFeeScalar + // marshalBinaryInboxFork adds an additional `batchInbox` parameter based on marshalBinaryEcotone. + out, err := l1BlockInfo.marshalBinaryInboxFork() + if err != nil { + return nil, fmt.Errorf("failed to marshal InboxFork l1 block info: %w", err) + } + data = out + } else if isEcotoneButNotFirstBlock(rollupCfg, l2BlockTime) { + ... +} +``` + +The `marshalBinaryInboxFork` function is added to [`L1BlockInfo`](https://github.com/ethereum-optimism/optimism/blob/5e317379fae65b76f5a6ee27581f0e62d2fe017a/op-node/rollup/derive/l1_block_info.go#L41). This new function incorporates an additional `batchInbox` parameter for the [`setL1BlockValuesEcotone`](https://github.com/ethereum-optimism/optimism/blob/5e317379fae65b76f5a6ee27581f0e62d2fe017a/packages/contracts-bedrock/src/L2/L1Block.sol#L136) function: + +```golang +func (info *L1BlockInfo) marshalBinaryInboxFork() ([]byte, error) { + w := bytes.NewBuffer(make([]byte, 0, L1InfoEcotoneLen)) + if err := solabi.WriteSignature(w, L1InfoFuncEcotoneBytes4); err != nil { + return nil, err + } + if err := binary.Write(w, binary.BigEndian, info.BaseFeeScalar); err != nil { + return nil, err + } + if err := binary.Write(w, binary.BigEndian, info.BlobBaseFeeScalar); err != nil { + return nil, err + } + if err := binary.Write(w, binary.BigEndian, info.SequenceNumber); err != nil { + return nil, err + } + if err := binary.Write(w, binary.BigEndian, info.Time); err != nil { + return nil, err + } + if err := binary.Write(w, binary.BigEndian, info.Number); err != nil { + return nil, err + } + if err := solabi.WriteUint256(w, info.BaseFee); err != nil { + return nil, err + } + blobBasefee := info.BlobBaseFee + if blobBasefee == nil { + blobBasefee = big.NewInt(1) // set to 1, to match the min blob basefee as defined in EIP-4844 + } + if err := solabi.WriteUint256(w, blobBasefee); err != nil { + return nil, err + } + if err := solabi.WriteHash(w, info.BlockHash); err != nil { + return nil, err + } + // ABI encoding will perform the left-padding with zeroes to 32 bytes, matching the "batcherHash" SystemConfig format and version 0 byte. + if err := solabi.WriteAddress(w, info.BatcherAddr); err != nil { + return nil, err + } + // This is where marshalBinaryInboxFork differs from marshalBinaryEcotone + if err := solabi.WriteHash(w, info.BatchInbox); err != nil { + return nil, err + } + return w.Bytes(), nil +} +``` + ### L1Block The `L1Block` stores Layer 1 (L1) related information on Layer 2 (L2). It is extended to store the dynamic inbox address. From f47c082a92430c7085566c1a7ec1f9c5e22f4b88 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Sat, 3 Aug 2024 17:48:47 +0800 Subject: [PATCH 17/18] update upgrade section --- specs/experimental/inbox-contract.md | 52 ++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 3 deletions(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index ccc4ec09f..d01a9bddf 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -18,6 +18,9 @@ - [How `op-node` knows the canonical batch inbox](#how-op-node-knows-the-canonical-batch-inbox) - [How `op-batcher` knows canonical batch inbox](#how-op-batcher-knows-canonical-batch-inbox) - [Upgrade](#upgrade) + - [L1Block Deployment](#l1block-deployment) + - [L1Block Proxy Update](#l1block-proxy-update) + - [SystemConfig Upgrade](#systemconfig-upgrade) - [Security Considerations](#security-considerations) - [Inbox Sender](#inbox-sender) - [Reference Implementation](#reference-implementation) @@ -243,9 +246,52 @@ Immediately before submitting a new batch, `op-batcher` fetches the current inbo ## Upgrade -To use this feature, existing OP Stack instances must complete two steps: -1. Upgrade the `SystemConfig` and set an inbox contract on L1. -2. Upgrade the `L1Block` on L2. +The custom gas token upgrade is not yet defined to be part of a particular network upgrade, but it will be scheduled as part of a future hardfork. On the network upgrade block, a set of deposit transaction based upgrade transactions are deterministically generated by the derivation pipeline in the following order: + +- L1 Attributes Transaction calling `setL1BlockValuesEcotone` +- User deposits from L1 +- Network Upgrade Transactions + - L1Block deployment + - Update L1Block Proxy ERC-1967 Implementation Slot + +The deployment transactions MUST have a `from` value that has no code and has no known +private key. This is to guarantee it cannot be frontran and have its nonce modified. +If this was possible, then an attacker would be able to modify the address that the +implementation is deployed to because it is based on `CREATE` and not `CREATE2`. +This would then cause the proxy implementation set transactions to set an incorrect +implementation address, resulting in a bricked contract. The calldata is not generated +dynamically to enable deterministic upgrade transactions across all networks. + +The proxy upgrade transactions are from `address(0)` because the `Proxy` implementation +considers `address(0)` to be an admin. Going straight to the `Proxy` guarantees that +the upgrade will work because there is no guarantee that the `Proxy` is owned by the +`ProxyAdmin` and going through the `ProxyAdmin` would require stealing the identity +of its owner, which may be different on every chain. That would require adding L2 +RPC access to the derivation pipeline and make the upgrade transactions non deterministic. + +### L1Block Deployment + +- `from`: `0x4210000000000000000000000000000000000002` +- `to`: `null` +- `mint`: `0` +- `value`: `0` +- `gasLimit`: TODO +- `data`: TODO +- `sourceHash`: TODO + +### L1Block Proxy Update + +- `from`: `0x0000000000000000000000000000000000000000` +- `to`: `0x4200000000000000000000000000000000000015` +- `mint`: `0` +- `value`: `0` +- `gasLimit`: `50,000` +- `data`: TODO +- `sourceHash`: TODO + +### SystemConfig Upgrade + +Finally, upgrade the `SystemConfig` and set an inbox contract on L1. Note that according to the [Optimism Style Guide](https://github.com/ethereum-optimism/optimism/blob/9d31040ecf8590423adf267ad24b03bc1bf7273b/packages/contracts-bedrock/STYLE_GUIDE.md), The process for upgrading the implementation is as follows: 1. Upgrade the implementation to the `StorageSetter` contract. From 601763deb871fd47edb7db771ca58c8efe2eef10 Mon Sep 17 00:00:00 2001 From: blockchaindevsh Date: Sat, 3 Aug 2024 20:35:28 +0800 Subject: [PATCH 18/18] fix for review --- specs/experimental/inbox-contract.md | 46 ++++++++++++++-------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/specs/experimental/inbox-contract.md b/specs/experimental/inbox-contract.md index d01a9bddf..f37e4fdf1 100644 --- a/specs/experimental/inbox-contract.md +++ b/specs/experimental/inbox-contract.md @@ -1,29 +1,29 @@ + # Inbox Contract **Table of Contents** -- [Inbox Contract](#inbox-contract) - - [Motivation](#motivation) - - [How It Works](#how-it-works) - - [Supporting Dynamic Updates to Inbox Address](#supporting-dynamic-updates-to-inbox-address) - - [SystemConfig](#systemconfig) - - [setBatchInbox](#setbatchinbox) - - [initialize](#initialize) - - [UpdateType](#updatetype) - - [L1 Info Deposit Transaction](#l1-info-deposit-transaction) - - [L1Block](#l1block) - - [batchInbox](#batchinbox) - - [setL1BlockValuesEcotone](#setl1blockvaluesecotone) - - [How `op-node` knows the canonical batch inbox](#how-op-node-knows-the-canonical-batch-inbox) - - [How `op-batcher` knows canonical batch inbox](#how-op-batcher-knows-canonical-batch-inbox) - - [Upgrade](#upgrade) - - [L1Block Deployment](#l1block-deployment) - - [L1Block Proxy Update](#l1block-proxy-update) - - [SystemConfig Upgrade](#systemconfig-upgrade) - - [Security Considerations](#security-considerations) - - [Inbox Sender](#inbox-sender) - - [Reference Implementation](#reference-implementation) +- [Motivation](#motivation) +- [How It Works](#how-it-works) +- [Supporting Dynamic Updates to Inbox Address](#supporting-dynamic-updates-to-inbox-address) + - [SystemConfig](#systemconfig) + - [setBatchInbox](#setbatchinbox) + - [initialize](#initialize) + - [UpdateType](#updatetype) + - [L1 Info Deposit Transaction](#l1-info-deposit-transaction) + - [L1Block](#l1block) + - [batchInbox](#batchinbox) + - [setL1BlockValuesEcotone](#setl1blockvaluesecotone) + - [How `op-node` knows the canonical batch inbox](#how-op-node-knows-the-canonical-batch-inbox) + - [How `op-batcher` knows canonical batch inbox](#how-op-batcher-knows-canonical-batch-inbox) +- [Upgrade](#upgrade) + - [L1Block Deployment](#l1block-deployment) + - [L1Block Proxy Update](#l1block-proxy-update) + - [SystemConfig Upgrade](#systemconfig-upgrade) +- [Security Considerations](#security-considerations) + - [Inbox Sender](#inbox-sender) +- [Reference Implementation](#reference-implementation) ## Motivation @@ -196,7 +196,7 @@ func (info *L1BlockInfo) marshalBinaryInboxFork() ([]byte, error) { return nil, err } // This is where marshalBinaryInboxFork differs from marshalBinaryEcotone - if err := solabi.WriteHash(w, info.BatchInbox); err != nil { + if err := solabi.WriteAddress(w, info.BatchInbox); err != nil { return nil, err } return w.Bytes(), nil @@ -291,7 +291,7 @@ RPC access to the derivation pipeline and make the upgrade transactions non dete ### SystemConfig Upgrade -Finally, upgrade the `SystemConfig` and set an inbox contract on L1. +Finally, to dynamically change the inbox address, `SystemConfig` on L1 will be upgraded to accept a new inbox address. Note that according to the [Optimism Style Guide](https://github.com/ethereum-optimism/optimism/blob/9d31040ecf8590423adf267ad24b03bc1bf7273b/packages/contracts-bedrock/STYLE_GUIDE.md), The process for upgrading the implementation is as follows: 1. Upgrade the implementation to the `StorageSetter` contract.