From 3efcfe760b1e2554103f2e87cab3f6a32381768e Mon Sep 17 00:00:00 2001 From: isabelle Date: Tue, 6 Aug 2024 12:03:17 -0400 Subject: [PATCH 1/4] add darwin to upgrades page --- .../technology/overview/scroll-upgrades.mdx | 103 ++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/src/content/docs/en/technology/overview/scroll-upgrades.mdx b/src/content/docs/en/technology/overview/scroll-upgrades.mdx index 306579649..e2dd9d222 100644 --- a/src/content/docs/en/technology/overview/scroll-upgrades.mdx +++ b/src/content/docs/en/technology/overview/scroll-upgrades.mdx @@ -19,6 +19,109 @@ The following contracts are used to initiate upgrades and execute upgrades after You can join our [Telegram channel for technical updates](https://t.me/scroll_tech_updates), which includes future upgrade announcements and on-chain operation events. +## Darwin Upgrade + +### Overview + +This upgrade will reduce gas fees by 34% by using a single aggregated proof for multiple batches, eliminating the need to finalize each batch individually. + +- Darwin uses a new [V3 batch codec](https://github.com/scroll-tech/da-codec/tree/main/encoding/codecv3). +- In addition to the previous notions of `chunk` and `batch`, we have introduced a new concept called `bundle`. + - `Chunk`: A unit of zkEVM proving, consisting of a list of L2 blocks. + - `Batch`: A collection of chunks encoded into one EIP-4844 blob, serving as the unit of Data Availability. + - `Bundle`: A series of batches that functions as the unit of finalization. + + The main difference compared to Curie is that Scroll will now finalize multiple batches using a single aggregated bundle proof. + +- The on-chain bundle proof verifier uses a new public input layout. + +### Timeline + +- **Scroll Sepolia** + - Network Upgrade: August 14th, 2024 +- **Scroll Mainnet** + - Upgrade Initiation: August 5th, 2024 + - Timelock Completion & Upgrade: August 21st, 2024 + +### Technical Details + +#### Contract Changes + +*Note: Since the previous Curie upgrade, we have migrated the Scroll contracts to a new repo at [scroll-contracts](https://github.com/scroll-tech/scroll-contracts).* + +The code changes for this upgrade are implemented in [this PR](https://github.com/scroll-tech/scroll-contracts/pull/4). The key changes are as follows: + +- We have introduced a new `BatchHeaderV3Codec`. +- We have changed how messages are processed in the `L1MessageQueue` contract. Prior to Darwin, we would process messages when a batch is finalized. After Darwin, most of this processing is moved to the commit step. +- We have introduced a new public input format for bundle proofs. This is implemented in a new contract `IZkEvmVerifierV2`, which is in turn added to `MultipleVersionRollupVerifier`. +- In the `ScrollChain` contract `version=3` batches will now be committed through a new function called `commitBatchWithBlobProof`. Bundles will be finalized using a new function called `finalizeBundleWithProof`. + +See the contract [release notes](https://github.com/scroll-tech/scroll-contracts/releases/tag/v1.0.0) for more information. + +#### Node Changes + +The new node version is `v5.6.0`. See the [release notes](https://github.com/scroll-tech/go-ethereum/releases/tag/scroll-v5.6.0) for more information. + +The main changes are: + +- Implementation of timestamp-based hard forks. +- Processing V3 batch codec in rollup-verifier. + +#### zkEVM circuit changes + +The new version of zkevm circuits is `v0.12.0`. See [here](https://github.com/scroll-tech/zkevm-circuits/releases/tag/v0.12.0) for the release log. + +We have introduced a `RecursionCircuit` that will bundle multiple sequential batches by recursively aggregating the SNARKs from the `BatchCircuit` (previously `AggregationCircuit`). The previously 5 layer proving system is now 7 layers as we introduce: + +- 6th Layer (layer5): `RecursionCircuit` that recursively aggregates `BatchCircuit` SNARKs. +- 7th Layer (layer6): `CompressionCircuit` that compresses the `RecursionCircuit` SNARK and produce an EVM-verifiable validity proof. + +The public input to the `BatchCircuit` is now context-aware of the “previous” `batch`, which allows us to implement the recursion scheme we adopted (described [here](https://scrollzkp.notion.site/Upgrade-4-Darwin-Documentation-05a3ecb59e9d4f288254701f8c888173) in-depth). + +#### Audits + +- TrailofBits: coming soon! + +### Compatibility + +#### Sequencer and Follower Nodes (l2geth) + +This upgrade does not alter the state transition function and is therefore backward-compatible. However, we strongly recommend node operators to upgrade to [v5.6.0](https://github.com/scroll-tech/go-ethereum/releases/tag/scroll-v5.6.0). + +#### Dapps and Indexers + +There are some major changes to how we commit and finalize batches after Darwin. + +- Batches will be encoded using the new [V3 batch codec](https://github.com/scroll-tech/da-codec/tree/main/encoding/codecv3). This version adds two new fields: + 1. `lastBlockTimestamp` (the timestamp of the last block in this batch). + 2. `blobDataProof` (the KZG challenge point evaluation proof). + + This version removes `skippedL1MessageBitmap`. There will be no changes to how the blob data is encoded and compressed. +- Batches will be committed using the `commitBatchWithBlobProof` function (instead of the previous `commitBatch`). + + New function signature: + + ```solidity + function commitBatchWithBlobProof(uint8 _version, bytes calldata _parentBatchHeader, bytes[] memory _chunks, bytes calldata _skippedL1MessageBitmap, bytes calldata _blobDataProof) + ``` + +- Batches will be finalized using the `finalizeBundleWithProof` function (instead of the previous `finalizeBatchWithProof4844`). + + New function signature: + + ```solidity + function finalizeBundleWithProof(bytes calldata _batchHeader, bytes32 _postStateRoot, bytes32 _withdrawRoot, bytes calldata _aggrProof) + ``` + +- The semantics of the `FinalizeBatch` event will change: It will now mean that all batches between the last finalized batch and the event’s `_batchIndex` have been finalized. The event’s stateRoot and withdrawRoot values belong to the last finalized batch in the bundle. Finalized roots for intermediate batches are no longer available. + + The semantics of the `CommitBatch` and `RevertBatch` events will not change. + +Recommendations: + +- Indexers that decode committed batch data should be adjusted to use the new codec and the new function signature. +- Indexers that track batch finalization status should be adjusted to consider the new event semantics. + ## Curie Upgrade ### Overview From 67e38c76d7c8b14052e8b33a57c300a46af74daa Mon Sep 17 00:00:00 2001 From: isabelle Date: Tue, 6 Aug 2024 12:34:37 -0400 Subject: [PATCH 2/4] update codec --- .../docs/en/technology/chain/rollup.mdx | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/src/content/docs/en/technology/chain/rollup.mdx b/src/content/docs/en/technology/chain/rollup.mdx index e74177540..515f20f1d 100644 --- a/src/content/docs/en/technology/chain/rollup.mdx +++ b/src/content/docs/en/technology/chain/rollup.mdx @@ -123,8 +123,48 @@ This section describes the codec of three data structures in the Rollup contract The latest update to the codec was introduced in the [Bernoulli upgrade](/technology/overview/scroll-upgrades#bernoulli-upgrade). +darwin bernoulli archimedes + + + #### `BatchHeader` Codec + + | Field | Bytes | Type | Offset | Description | + | ------------------------ | ------- | ----------- | ------ | --------------------------------------------------------------- | + | `version` | 1 | `uint8` | 0 | The batch header version | + | `batchIndex` | 8 | `uint64` | 1 | The index of the batch | + | `l1MessagePopped` | 8 | `uint64` | 9 | The number of L1 messages popped in the batch | + | `totalL1MessagePopped` | 8 | `uint64` | 17 | The number of total L1 messages popped after the batch | + | `dataHash` | 32 | `bytes32` | 25 | The data hash of the batch | + | `blobVersionedHash` | 32 | `bytes32` | 57 | The versioned hash of the blob with this batch’s data | + | `parentBatchHash` | 32 | `bytes32` | 89 | The parent batch hash | + | `lastBlockTimestamp` | 8 | `uint64` | 121 | The timestamp of the last block in this batch | + | `blobDataProof` | 64 | `bytes32[2]` | 129 | The KZG challenge point evaluation proof | + + #### `Chunk` Codec + + | Field | Bytes | Type | Offset | Description | + | ---------------- | ------- | -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | + | `numBlocks` | 1 | `uint8` | 0 | The number of blocks in the chunk | + | `block[0]` | 60 | `BlockContext` | 1 | The block information of the 1st block | + | ... | ... | ... | ... | ... | + | `block[i]` | 60 | `BlockContext` | `60*i+1` | The block information of `i+1`-th block | + | ... | ... | ... | ... | ... | + | `block[n-1]` | 60 | `BlockContext` | `60*n-59` | The block information of the last block | + + #### `BlockContext` Codec + + | Field | Bytes | Type | Offset | Description | + | ----------------- | ----- | --------- | ------ | ----------------------------------------------------------------------------------- | + | `blockNumber` | 8 | `uint64` | 0 | The block number | + | `timestamp` | 8 | `uint64` | 8 | The block time | + | `baseFee` | 32 | `uint256` | 16 | The base fee of this block. Currently, it is always 0, because we disable EIP-1559. | + | `gasLimit` | 8 | `uint64` | 48 | The gas limit of this block | + | `numTransactions` | 2 | `uint16` | 56 | The number of transactions in this block, including both L1 & L2 txs | + | `numL1Messages` | 2 | `uint16` | 58 | The number of L1 messages in this block + + From 421dfbc4205f2f13ddac802d2f2e5a330520716b Mon Sep 17 00:00:00 2001 From: isabelle Date: Tue, 6 Aug 2024 12:38:43 -0400 Subject: [PATCH 3/4] update contract function --- src/content/docs/en/technology/chain/rollup.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/technology/chain/rollup.mdx b/src/content/docs/en/technology/chain/rollup.mdx index 515f20f1d..e65bb6e35 100644 --- a/src/content/docs/en/technology/chain/rollup.mdx +++ b/src/content/docs/en/technology/chain/rollup.mdx @@ -52,18 +52,19 @@ The rollup process can be broken down into three phases: transaction execution, ## Commit Transaction -The Commit Transaction submits the block information and transaction data to L1 for data availability. The transaction includes the parent batch header, chunk data, and a bitmap of skipped L1 messages. The parent batch header designates the previous batch that this batch links to. The parent batch must be committed before; otherwise, the transaction will be reverted. See the `commitBatch` function signature below. +The Commit Transaction submits the block information and transaction data to L1 for data availability. The transaction includes the parent batch header, chunk data, and a bitmap of skipped L1 messages. The parent batch header designates the previous batch that this batch links to. The parent batch must be committed before; otherwise, the transaction will be reverted. See the `commitBatchWithBlobProof` function signature below. ```solidity -function commitBatch( +function commitBatchWithBlobProof( uint8 version, bytes calldata parentBatchHeader, bytes[] memory chunks, - bytes calldata skippedL1MessageBitmap -) external override OnlySequencer + bytes calldata skippedL1MessageBitmap, + bytes calldata blobDataProof +) external; ``` -After the `commitBatch` function verifies the parent batch is committed before, it constructs the batch header of the batch and stores the hash of the batch header in the `ScrollChain` contract. +After the `commitBatchWithBlobProof` function verifies the parent batch is committed before, it constructs the batch header of the batch and stores the hash of the batch header in the `ScrollChain` contract. ```solidity mapping(uint256 => bytes32) public committedBatches; @@ -85,7 +86,7 @@ chunk.dataHash := keccak(blockContext[0] || ... || blockContext[k-1] || , where `block.l1TxHashes` are the concatenated transaction hashes of the L1 transactions in this block and `block.l2TxHashes` are the concatenated transaction hashes of the L2 transactions in this block. Note that the transaction hashes of L1 transactions are not uploaded by the rollup node, but instead directly loaded from the `L1MessageQueue` contract given the index range of included L1 messages in this block. The L2 transaction hashes are calculated from the RLP-encoded bytes in the `l2Transactions` field in the [`Chunk`](#Chunk-Codec). -In addition, the `commitBatch` function contains a bitmap of skipped L1 messages. Unfortunately, this is due to the problem of proof overflow. If the L1 transaction corresponding to an L1 message exceeds the circuit capacity limit, we won't be able to generate a valid proof for this transaction and thus cannot finalize it on L1. Scroll is working actively to eliminate the proof overflow problem through upgrades to our proving system. +In addition, the `commitBatchWithBlobProof` function contains a bitmap of skipped L1 messages. Unfortunately, this is due to the problem of proof overflow. If the L1 transaction corresponding to an L1 message exceeds the circuit capacity limit, we won't be able to generate a valid proof for this transaction and thus cannot finalize it on L1. Scroll is working actively to eliminate the proof overflow problem through upgrades to our proving system. ## Finalize Transaction From da9a82b94178b92d72b6fb9cbba52dcdbc9b97b7 Mon Sep 17 00:00:00 2001 From: isabelle Date: Tue, 6 Aug 2024 12:41:30 -0400 Subject: [PATCH 4/4] update node guide --- .../docs/en/developers/guides/running-a-scroll-node.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/developers/guides/running-a-scroll-node.mdx b/src/content/docs/en/developers/guides/running-a-scroll-node.mdx index 0e003820e..9fa2b9663 100644 --- a/src/content/docs/en/developers/guides/running-a-scroll-node.mdx +++ b/src/content/docs/en/developers/guides/running-a-scroll-node.mdx @@ -18,7 +18,7 @@ For most developers, using [our official RPC endpoint](/en/developers/developer- We recommend using the latest release at https://github.com/scroll-tech/go-ethereum/releases. The required version for Scroll Mainnet is `scroll-v5.5.0` or higher, and for Scroll Sepolia it is `scroll-v5.4.2` or higher. If you'd like to keep up with new node releases, go to https://github.com/scroll-tech/go-ethereum, click on **Watch**, **Custom**, and make sure that **Releases** is selected. -For the remainder of this guide, `VERSION` will denote the version tag. For example, `scroll-v5.5.0`. +For the remainder of this guide, `VERSION` will denote the version tag. For example, `scroll-v5.6.0`. ### Hardware Requirements @@ -118,7 +118,7 @@ Running the node in Docker might have a significant impact on node performance. --http --http.addr "0.0.0.0" --http.port 8545 --http.api "eth,net,web3,debug,scroll" \ --l1.endpoint "$L2GETH_L1_ENDPOINT" --rollup.verify ``` - For Scroll Sepolia, set the chain ID to 534351. + For Scroll Sepolia, set the chain ID to 534351 and use `--scroll-sepolia` instead of `--scroll`. 2. In a separate shell, you can now attach to `l2geth`.