Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Darwin upgrade #316

Merged
merged 4 commits into from
Aug 21, 2024
Merged

Darwin upgrade #316

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3efcfe7
add darwin to upgrades page
isabellewei Aug 6, 2024
67e38c7
update codec
isabellewei Aug 6, 2024
421dfbc
update contract function
isabellewei Aug 6, 2024
da9a82b
update node guide
isabellewei Aug 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/content/docs/en/developers/guides/running-a-scroll-node.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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`.

Expand Down
53 changes: 47 additions & 6 deletions src/content/docs/en/technology/chain/rollup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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

Expand Down Expand Up @@ -123,8 +124,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).

<Tabs sharedStore="upgrades" client:visible>
<Fragment slot="tab.darwin">darwin</Fragment>
<Fragment slot="tab.bernoulli">bernoulli</Fragment>
<Fragment slot="tab.archimedes">archimedes</Fragment>
<Fragment slot="panel.darwin">
<slot name="darwin" />
#### `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

</Fragment>
<Fragment slot="panel.bernoulli">
<slot name="bernoulli" />

Expand Down
103 changes: 103 additions & 0 deletions src/content/docs/en/technology/overview/scroll-upgrades.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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!
dghelm marked this conversation as resolved.
Show resolved Hide resolved

### 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
Expand Down