Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
10 changes: 3 additions & 7 deletions src/content/docs/en/technology/chain/accounts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,19 +11,15 @@ whatsnext: { "Transactions": "/en/technology/chain/transactions/" }

Same as Ethereum, Scroll has two account types: Externally-owned account (EOA) and contract account that holds the smart contract and additional storage.

Scroll stores additional information of the contract bytecode in the account to facilitate the zkEVM circuit to prove the state transition more efficiently.

The account in Scroll contains the following fields:
The account structure in Scroll follows the standard Ethereum format:

- `nonce`: A counter that indicates the number of transactions sent by the sender.
- `balance`: The balance of `ETH` token in the account (unit in wei).
- `storageRoot`: The root hash of the storage trie. Since Scroll uses the [zkTrie](/technology/sequencer/zktrie) for the storage trie, the `storageRoot` stores the Poseidon hash digest in a 256-bit integer.
- `storageRoot`: The root hash of the storage trie.
- `codeHash`: The Keccak hash digest of the contract bytecode.
- `PoseidonCodeHash` (**new field**): The Poseidon hash digest of the contract bytecode in a 256-bit integer.
- `CodeSize` (**new field**): The size of the contract bytecode in bytes.

## State

The state of a blockchain is a collection of account data. The _state trie_ encodes account data and their corresponding addresses to a [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree) data structure. The root of tree, or the state of the blockchain, is a cryptographic digest of all the account data contained in the tree.

Ethereum uses a data structure called [Patricia Merkle Trie](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie/) for both the state trie and the storage trie that stores the key-value entries stored in a smart contract. In Scroll, we replace the Patricia Merkle Trie with a more zk-friendly data structure, called zkTrie, for both state trie and storage trie. At a high level, the zkTrie data structure is a sparse binary Merkle tree with the [Poseidon hash](https://eprint.iacr.org/2019/458.pdf), a zk-friendly hash function. The [zkTrie](/technology/sequencer/zktrie) document describes more details about this data structure.
Scroll uses Ethereum's [Merkle-Patricia Trie](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie/) (MPT) for both the state trie and the storage trie that stores the key-value entries in smart contracts. This ensures full compatibility with Ethereum's state proof format and tooling.
2 changes: 1 addition & 1 deletion src/content/docs/en/technology/chain/differences.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ import Aside from "../../../../../components/Aside.astro"
| `0x09` | `blake2f` | Currently not supported. |
| `0x0a` | `point evaluation` | Currently not supported. |

The remaining precompiled contracts have the same behavior as Ethereum. However, their maximum usage within a block is constrained by a limit tied to the zkEVM circuit capacity.
The remaining precompiled contracts have the same behavior as Ethereum.

## EIPs

Expand Down
1 change: 0 additions & 1 deletion src/content/docs/en/technology/chain/rollup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,6 @@ 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 `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
6 changes: 3 additions & 3 deletions src/content/docs/en/technology/chain/transactions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -83,9 +83,9 @@ After the validity proof is generated, the rollup node sends a _Finalize Transac
In Scroll, the transactions are batched in multiple tiers.

1. A group of ordered transactions are packed into a block.
2. A series of contiguous blocks are grouped into a chunk. The chunk is the base unit for proof generation of the zkEVM circuit.
2. A series of contiguous blocks are grouped into a chunk. The chunk is the base unit for proof generation.
3. A series of contiguous chunks are grouped into a batch. The batch is the base unit for data commitment and proof verification on the L1. The proof for a batch, or a _batch proof_, is an aggregated proof of the chunk proofs in this batch.

The goal for this multi-layer batching schema is to reduce the gas cost of onchain data commitment and proof verification. This approach increases the granularity of the rollup units on L1 while takes the fixed circuit capacity into consideration. As a result, batching reduces the data to be stored in the contract and amortizes the proof verification cost to more L2 transactions.
The goal for this multi-layer batching schema is to reduce the gas cost of onchain data commitment and proof verification. As a result, batching reduces the data to be stored in the contract and amortizes the proof verification cost to more L2 transactions.

Once a chunk is created, a corresponding chunk proving task will be generated and sent to a zkEVM prover. Upon the creation of a new batch, two subsequent actions occur: (a) the rollup node commits the transaction data and block information from this batch to the L1 contract, and (b) a batch proving task to aggregate chunk proofs is dispatched to an aggregator prover. The standards for proposing a chunk and a batch are detailed in the [Rollup Node](/technology/sequencer/rollup-node).
Once a chunk is created, a corresponding chunk proving task will be generated and sent to a prover. Upon the creation of a new batch, two subsequent actions occur: (a) the rollup node commits the transaction data and block information from this batch to the L1 contract, and (b) a batch proving task to aggregate chunk proofs is dispatched to an aggregator prover. The standards for proposing a chunk and a batch are detailed in the [Rollup Node](/technology/sequencer/rollup-node).
4 changes: 2 additions & 2 deletions src/content/docs/en/technology/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ As illustrated in the figure above, Scroll chain consists of three layers:

- **Settlement Layer**: provides data availability and ordering for the canonical Scroll chain, verifies validity proofs, and allows users and dapps to send messages and assets between Ethereum and Scroll. We use Ethereum as the Settlement Layer and deploy the bridge and rollup contract onto Ethereum.
- **Sequencing Layer**: contains an *Execution Node* that executes the transactions submitted to the Scroll sequencer and the transactions submitted to the L1 bridge contract and produces L2 blocks, and a *Rollup Node* that batches transactions, posts transaction data and block information to Ethereum for data availability, and submits validity proofs to Ethereum for finality.
- **Proving Layer**: consists of a pool of provers that are responsible for generating the zkEVM validity proofs that verify the correctness of L2 transactions, and a coordinator that dispatches the proving tasks to provers and relays the proofs to the Rollup Node to finalize on Ethereum.
- **Proving Layer**: consists of a pool of provers running the [OpenVM prover](/en/technology/prover/proof-generation) that generate zero-knowledge proofs verifying the correctness of L2 transactions, and a coordinator that dispatches the proving tasks to provers and relays the proofs to the Rollup Node to finalize on Ethereum.

This section of the documentation provides comprehensive information on the Scroll protocol specification, bridging protocol, sequencer, and zkEVM circuit.
This section of the documentation provides comprehensive information on the Scroll protocol specification, bridging protocol, sequencer, and proving system.

*In the remainder of this section, L1 will refer to Ethereum, while L2 will refer to Scroll.*
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Scroll has been among the pioneers of ZK technology through our EVM bytecode com
The new OpenVM prover offers numerous benefits. Prover code is easier to reason about and to audit. We can better reuse code among different components. We can also reduce proving costs and latency. Finally, the new prover will enable us to prove arbitrarily complex transactions, allowing us to remove the circuit capacity checker module that has been a major bottleneck on sequencer throughput.

##### MPT State Commitment
Scroll currently uses a zk-friendly state commitment data structure called [zktrie](https://docs.scroll.io/en/technology/sequencer/zktrie/). With the new OpenVM prover, it is now practical to prove Ethereums state structure: the [Merkle-Patricia Trie](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie), also known as MPT. Scroll is now deprecating the zktrie and adopting MPT.
Prior to this upgrade, Scroll used a custom zk-friendly state commitment data structure called zkTrie. With the new OpenVM prover, it is now practical to prove Ethereum's state structure: the [Merkle-Patricia Trie](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie), also known as MPT. Scroll has deprecated zkTrie and adopted MPT.

MPT unlocks better sequencer performance and offers better compatibility for dapps relying on L2 state proofs.

Expand Down
31 changes: 31 additions & 0 deletions src/content/docs/en/technology/prover/proof-generation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,35 @@ date: Last Modified
title: "Proof Generation"
lang: "en"
permalink: "technology/prover/proof-generation"
whatsnext: { "zkEVM Overview": "/en/technology/zkevm/zkevm-overview" }
---

import Aside from "../../../../../components/Aside.astro"

## Overview

Scroll uses the **OpenVM prover** to generate zero-knowledge proofs that validate L2 transaction execution. This system was introduced in the [Euclid upgrade](/en/technology/overview/scroll-upgrades/euclid-upgrade).

<Aside type="note" title="Proving System History">
Prior to Euclid, Scroll used custom EVM circuits that directly proved each EVM opcode. The OpenVM prover takes a general-purpose approach: it proves the execution of RISC-V programs (written in Rust) that implement EVM verification logic.
</Aside>

## Proof Aggregation

The prover uses a three-layer hierarchical aggregation:

1. **Chunk proofs**: Prove execution of individual chunks (collections of blocks)
2. **Batch proofs**: Aggregate multiple chunk proofs
3. **Bundle proofs**: Final aggregation, converted to SNARK for on-chain verification

This hierarchy reduces L1 verification costs by combining many proofs into one.

## Proving Infrastructure

The **Coordinator** dispatches proving tasks to a pool of provers, collects completed proofs, and manages aggregation. Final proofs are relayed to the Rollup Node for submission to L1.

## Learn More

- [OpenVM Repository](https://github.com/openvm-org/openvm)
- [Scroll zkVM Prover](https://github.com/scroll-tech/zkvm-prover)
- [Euclid Upgrade](/en/technology/overview/scroll-upgrades/euclid-upgrade)
38 changes: 9 additions & 29 deletions src/content/docs/en/technology/sequencer/execution-node.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,45 +35,25 @@ The following sections will introduce the main components of the execution node,
- **L1 SyncService**: Sync and store L1 messages in `l2geth` local database.
- **API layer**: Standard Ethereum RPC and p2p interfaces.
- **Transaction pool**: Mempool for L2 transactions.
- **Circuit capacity checker**: checks if a transaction or a block exceeds the circuit capacity limit.

### Circuit Capacity Checker

With Scroll's current zkEVM circuits, it is possible to construct transactions and blocks that cannot be proven because they do not fit into the zkEVM circuit. We call this *proof overflow*. To avoid this, we implemented a *circuit capacity checker* module as part of l2geth. The circuit capacity checker is used both during block creation and block validation.

During block creation, if the next transaction would lead to proof overflow, then we seal the block and leave the transaction for the next block. If a single transaction leads to proof overflow, l2geth discards it. We call this mechanism *skipping*.

Skipping L2 transactions means simply discarding them. In this case, the user needs to submit another transaction with the same nonce that does not lead to proof overflow in order to proceed.

Skipping L1 messages is a more explicit process. Both the `ScrollChain` contract on L1 and the zkEVM verify that each L1 transaction in `L1MessageQueue` was either included and executed, or skipped. While the batch encoding does not contain L1 transactions, it does include a *skip bitmap* that indicates to `ScrollChain` which L1 messages were skipped. If an L1 deposit message is skipped, the user can get their tokens refunded on L1.

<Aside type="note" title="Note">
{" "}
Proof overflow and thus skipping suggests malicious activity; for normal deposit transactions, this will never happen.
{" "}
<Aside type="note" title="Note on scroll-reth">
As announced in the [Galileo upgrade](/en/technology/overview/scroll-upgrades/galileo-upgrade), Scroll is transitioning to a new node implementation based on [Reth](https://github.com/paradigmxyz/reth). Node operators will gradually migrate from l2geth to [scroll-reth](https://github.com/scroll-tech/rollup-node).
</Aside>

As the unit of zkEVM proving is the chunk, proof overflow must be avoided for chunks as well.
This is achieved by incorporating the circuit capacity checker into the rollup-relayer to make sure that it never proposes unprovable chunks.

## Validation Rules

Scroll adds a few validation rules in addition to Ethereum's block validation rules. These new rules constrain the L2 behavior of L1 message inclusion and zkEVM circuit capacity limit.
- The [circuit capacity checker](#circuit-capacity-checker) module outlined above
verifies the block can fit into the circuit space capacity of the zkEVM circuit.
- Rules related to L1 messages:
- L1 messages in a block must be contiguous and at the front of the block.
- L1 messages in a block must be included following their order in `L1MessageQueue`, i.e., they must be included with increasing `QueueIndex`.
- L1 messages in a block must match those in the `L1MessageQueue` contract.
- Most of these rules are considered both during block creation and block validation. As a result, if the block proposer node violates any of these rules, follower nodes will reject its blocks.
Scroll adds a few validation rules in addition to Ethereum's block validation rules. These rules constrain L1 message inclusion:
- L1 messages in a block must be contiguous and at the front of the block.
- L1 messages in a block must be included following their order in `L1MessageQueue`, i.e., they must be included with increasing `QueueIndex`.
- L1 messages in a block must match those in the `L1MessageQueue` contract.

These rules are enforced both during block creation and block validation. If the block proposer node violates any of these rules, follower nodes will reject its blocks.


## Summary of Modifications

The Scroll execution node inherits most of Ethereum's behaviors. However, we needed to make some breaking changes to `l2geth` to enable more efficient proving. This section provides a non-exhaustive list of the modifications, along with their rationale.
The Scroll execution node inherits most of Ethereum's behaviors. This section provides a non-exhaustive list of the modifications, along with their rationale.

- **State and storage tree**: Ethereum uses the MPT (Merkle-Patricia Trie) as its state and contract storage data structure. This trie's structure and the fact that it uses Keccak hash would make it prohibitively expensive for ZK circuits. `l2geth` instead uses [zkTrie](/technology/sequencer/zktrie): a binary Merkle trie with Poseidon hash for its state and contract storage.
- **StateAccount**: The modification of state account is described in the [Accounts and State](/technology/chain/accounts).
- **EVM**: The modifications are described in the [EVM Differences from Ethereum](/technology/chain/differences)
- **Transaction fees**
- All fees collected on L2 are sent to a Scroll-maintained L2 fee vault contract.
Expand Down
8 changes: 2 additions & 6 deletions src/content/docs/en/technology/sequencer/rollup-node.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ date: Last Modified
title: "Rollup Node"
lang: "en"
permalink: "technology/sequencer/rollup-node"
whatsnext: { "zkTrie": "/en/technology/sequencer/zktrie/" }
whatsnext: { "Proof Generation": "/en/technology/prover/proof-generation" }
---

The rollup node is responsible for splitting up the Scroll blockchain into sections that are suitable for proving and commitment on L1. The two main units of this are *chunks* and *batches*.
Expand All @@ -22,12 +22,8 @@ Compared to the execution node, the rollup node is a much more straightforward a
It collects L2 blocks, creates chunks and batches, and submits these to L1.
In this section, we outline the main limits that the rollup node must enforce during chunk and batch creation.

Constraints on chunks:
- **No proof overflow:** Using the circuit capacity checker, we make sure to include as many blocks in a chunk that it would still not lead to proof overflow.
- **L1 payload**: Inherited constraints from batch proposer, transaction payload cannot exceed 128KB.

Constraints on batches:
- **L1 payload:** Ethereum has a hardcoded 128KB limit on transaction payload size.
- **L1 payload:** Ethereum limits the size of blob data and transaction calldata.
- **L1 commit gas:** The gas cost of committing a batch is proportional to the number of blocks and transactions in it. We must make sure that this cost does not exceed the L1 block gas limit.
- **Number of chunks:** A batch includes a number of chunks that is optimal for the aggregation prover.

Loading