From f1f667338bc9d1a8408b38c4e4d03596dba6621d Mon Sep 17 00:00:00 2001 From: fakedev9999 Date: Fri, 17 Jan 2025 09:31:02 -0800 Subject: [PATCH 1/4] docs: improve op-succinct book --- book/SUMMARY.md | 2 +- book/architecture.md | 75 +++++++++++++++++++++++++++++++++++--------- book/introduction.md | 26 +++++++++++++-- 3 files changed, 85 insertions(+), 18 deletions(-) diff --git a/book/SUMMARY.md b/book/SUMMARY.md index 954d75f6..02e44cba 100644 --- a/book/SUMMARY.md +++ b/book/SUMMARY.md @@ -16,7 +16,7 @@ - [Toggle Optimistic Mode](./advanced/toggle-optimistic.md) - [Kurtosis](./advanced/kurtosis.md) - [Upgrade to a new `op-succinct` version](./advanced/upgrade.md) -- [`OPSuccinctL2OutputOracle`](./contracts/intro.md) +- [Contracts](./contracts/intro.md) - [Configuration](./contracts/configuration.md) - [Deploy](./contracts/deploy.md) - [Upgrade Contract](./contracts/upgrade.md) diff --git a/book/architecture.md b/book/architecture.md index 20331245..44c1e304 100644 --- a/book/architecture.md +++ b/book/architecture.md @@ -1,25 +1,72 @@ # Architecture -## Prerequisites +## System Overview -Every OP Stack rollup is composed of four main components. +OP Succinct enhances OP Stack rollups by adding zero-knowledge proof capabilities while maintaining compatibility with existing OP Stack components. This document explains both the standard OP Stack components and the additional OP Succinct components that enable proving blocks. -- `op-geth`: Takes transactions from users and uses them to generate blocks and execute blocks. -- `op-batcher`: Batches transactions from users and submits them to the L1. -- `op-node`: Reads batch data from L1 and uses it to drive `op-geth` in non-sequencer mode to perform state transitions. -- `op-proposer`: Posts an output root to L1 at regular intervals, which captures the L2 state so withdrawals can be processed. +## Standard OP Stack Components -You can read more about the components in the [OP Stack Specification](https://specs.optimism.io/). +Every OP Stack rollup consists of four main components that continue to function as normal with OP Succinct: -## OP Succinct +- `op-geth`: The execution engine that: + - Processes user transactions + - Generates and executes blocks + - Maintains the L2 state +- `op-batcher`: The transaction bundler that: + - Collects user transactions + - Batches them efficiently + - Submits batches to L1 for data availability +- `op-node`: The derivation engine that: + - Reads batch data from L1 + - Generates payload attributes + - Passes payload attributes to `op-geth` to perform state transitions +- `op-proposer`: The state commitment component that: + - Posts output roots to L1 at regular intervals + - Capturing the L2 state and enabling withdrawal processing -OP Succinct is a lightweight upgrade to the OP Stack that allows the chain to progress only with ZK-proven blocks, while keeping the other components (`op-geth`, `op-batcher`, and `op-node`) unchanged. Deploying OP Succinct requires deploying one contract, `OPSuccinctL2OutputOracle`, and spinning up a lightweight modification to the `op-proposer` that requests proofs to be submitted to the L1 contract. +For more details on these components, refer to the [OP Stack Specification](https://specs.optimism.io/). -Here is a high-level overview of the new components that are introduced in OP Succinct: +## OP Succinct Extensions -- **Range Program.** A program that derives and executes batches of blocks. The program is written in Rust and designed to be executed inside the zkVM. -- **Aggregation Program.** Aggregates proofs of range programs to reduce on-chain verification costs. This program is also written in Rust and designed to be executed inside the zkVM. -- **OP Succinct L2 Output Oracle.** A solidity smart contract that contains an array of L2 state outputs, where each output is a commit to the state of the L2 chain. This [contract](https://github.com/ethereum-optimism/optimism/blob/3e68cf018d8b9b474e918def32a56d1dbf028d83/packages/contracts-bedrock/src/L1/L2OutputOracle.sol) already exists in Optimism's original system but is modified to verify proofs as the authentication mechanism. -- **OP Succinct Proposer.** Observes the posted batches on L1 and controls the proving of the range and aggregation programs. +OP Succinct adds ZK-proving capabilities over blocks through a lightweight upgrade to `op-proposer` with several core components. No changes are needed to `op-geth`, `op-batcher`, or `op-node`. + +### Core Components + +1. **Range Program** + - Written in Rust for the zkVM + - Derives and executes batches of blocks + - Generates proofs of correct execution + +2. **Aggregation Program** + - Written in Rust for the zkVM + - Aggregates multiple range program proofs + - Reduces on-chain verification costs + +3. **OP Succinct L2 Output Oracle** + - Modified version of the original [L2OutputOracle contract](https://github.com/ethereum-optimism/optimism/blob/3e68cf018d8b9b474e918def32a56d1dbf028d83/packages/contracts-bedrock/src/L1/L2OutputOracle.sol) + - Stores array of L2 state outputs + - Modified to verify ZK proofs to accept output proposals + +4. **OP Succinct Proposer** + - Orchestrates the proving pipeline + - Monitors L1 for posted batches + - Manages proof generation and submission using the range and aggregation programs + +### Data Flow ![OP Succinct Architecture](./assets/op-succinct-proposer-architecture.jpg) + +1. User transactions are processed by standard OP Stack components +2. The range program generates proofs for batches of transactions +3. The aggregation program combines these proofs for on-chain verification efficiency +4. The OP Succinct Proposer submits L2 state outputs to L1 with ZK proofs +5. The L2 Output Oracle verifies the ZK proofs and accepts valid output proposals + +## Deployment Requirements + +To upgrade an existing OP Stack rollup to a fully type-1 ZK rollup using OP Succinct: + +1. Deploy the `OPSuccinctL2OutputOracle` contract +2. Configure and start the OP Succinct Proposer instead of the standard `op-proposer` + +This minimal change set ensures a smooth transition while leveraging the security benefits of ZK proofs. diff --git a/book/introduction.md b/book/introduction.md index 6a166360..9da1f632 100644 --- a/book/introduction.md +++ b/book/introduction.md @@ -1,13 +1,33 @@ # OP Succinct -*Documentation for OP Succinct users and developers.* +*Documentation for OP Stack rollup operators and developers looking to upgrade to a Type-1 ZK rollup.* -OP Succinct transforms any OP Stack rollup into a [fully type-1 ZK rollup](https://vitalik.eth.limo/general/2022/08/04/zkevm.html) using SP1. OP Succinct provides: +## Overview + +OP Succinct transforms any OP Stack rollup into a [fully type-1 ZK rollup](https://vitalik.eth.limo/general/2022/08/04/zkevm.html) using SP1. This means your rollup can benefit from the security of zero-knowledge proofs while maintaining compatibility with the OP Stack ecosystem. + +### Key Benefits - **1 hour finality** secured by ZKPs, a dramatic improvement over the 7-day withdrawal window of standard OP Stack rollups. - **Unlimited customization** for rollup modifications in pure Rust and easy maintainability. - **Cost-effective proving** with an average cost of proving only fractions of cent per transaction (with an expected 5-10x improvement by EOY), thanks to SP1's blazing fast performance. +## Getting Started + +1. Check the [Prerequisites](./quick-start/prerequisites.md) to ensure your environment is ready +2. Run the [Cost Estimator](./quick-start/cost-estimator.md) to understand resource requirements +3. Try [OP Succinct in Mock Mode](./quick-start/mock.md) for development +4. Deploy [OP Succinct in Full Mode](./quick-start/full.md) for production + +## Support and Community + All of this has been possible thanks to close collaboration with the core team at [OP Labs](https://www.oplabs.co/). -**Reach out [today](https://docs.google.com/forms/d/e/1FAIpQLSd2Yil8TrU54cIuohH1WvDvbxTusyqh5rsDmMAtGC85-Arshg/viewform?ref=https://succinctlabs.github.io/op-succinct/) if you want a Type-1 zkEVM rollup powered by SP1 (either a new rollup or a conversion from an optimistic rollup).** +**Ready to upgrade your rollup? [Contact us](https://docs.google.com/forms/d/e/1FAIpQLSd2Yil8TrU54cIuohH1WvDvbxTusyqh5rsDmMAtGC85-Arshg/viewform?ref=https://succinctlabs.github.io/op-succinct/) to get started with a Type-1 zkEVM rollup powered by SP1.** + +## Documentation Structure + +- **Quick Start**: Get up and running quickly with basic setup and configuration +- **Advanced**: Detailed guides for production deployment and maintenance +- **Contracts**: `OPSuccinctL2OutputOracle` contract documentation and deployment guides +- **FAQ & Troubleshooting**: Common issues and their solutions From c6a768660a379b2ceed765efabbda144bf62600e Mon Sep 17 00:00:00 2001 From: fakedev9999 Date: Mon, 20 Jan 2025 17:03:35 -0800 Subject: [PATCH 2/4] docs: apply comments --- book/architecture.md | 28 ++++++++++++++-------------- book/introduction.md | 16 ++++++++-------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/book/architecture.md b/book/architecture.md index 44c1e304..a7e390eb 100644 --- a/book/architecture.md +++ b/book/architecture.md @@ -2,11 +2,13 @@ ## System Overview -OP Succinct enhances OP Stack rollups by adding zero-knowledge proof capabilities while maintaining compatibility with existing OP Stack components. This document explains both the standard OP Stack components and the additional OP Succinct components that enable proving blocks. +OP Succinct transforms any OP Stack chain into a fully validity-proven rollup with a lightweight upgrade that maintains compatibility with existing OP Stack components. + +This document explains the standard OP Stack components and the lightweight modifications OP Succinct adds to enable proving blocks with zero-knowledge proofs using [SP1](https://docs.succinct.xyz/docs/introduction). ## Standard OP Stack Components -Every OP Stack rollup consists of four main components that continue to function as normal with OP Succinct: +Every OP Stack rollup consists of four main components: - `op-geth`: The execution engine that: - Processes user transactions @@ -28,17 +30,15 @@ For more details on these components, refer to the [OP Stack Specification](http ## OP Succinct Extensions -OP Succinct adds ZK-proving capabilities over blocks through a lightweight upgrade to `op-proposer` with several core components. No changes are needed to `op-geth`, `op-batcher`, or `op-node`. +OP Succinct enables OP Stack blocks to be proven with SP1 through a lightweight upgrade to op-proposer and the on-chain contract that tracks valid L2 state roots. No changes are needed to `op-geth`, `op-batcher`, or `op-node`. ### Core Components -1. **Range Program** - - Written in Rust for the zkVM +1. **[Range Program](../programs/range/src/main.rs)** - Derives and executes batches of blocks - Generates proofs of correct execution -2. **Aggregation Program** - - Written in Rust for the zkVM +2. **[Aggregation Program](../programs/aggregation/src/main.rs)** - Aggregates multiple range program proofs - Reduces on-chain verification costs @@ -56,17 +56,17 @@ OP Succinct adds ZK-proving capabilities over blocks through a lightweight upgra ![OP Succinct Architecture](./assets/op-succinct-proposer-architecture.jpg) -1. User transactions are processed by standard OP Stack components -2. The range program generates proofs for batches of transactions -3. The aggregation program combines these proofs for on-chain verification efficiency -4. The OP Succinct Proposer submits L2 state outputs to L1 with ZK proofs -5. The L2 Output Oracle verifies the ZK proofs and accepts valid output proposals +1. User transactions are processed by standard OP Stack components. +2. The range program generates proofs for batches of transactions. +3. The aggregation program combines these proofs for on-chain verification efficiency. +4. The OP Succinct Proposer submits L2 state outputs to L1 with ZK proofs. +5. The L2 Output Oracle verifies the ZK proofs and accepts valid output proposals. ## Deployment Requirements To upgrade an existing OP Stack rollup to a fully type-1 ZK rollup using OP Succinct: -1. Deploy the `OPSuccinctL2OutputOracle` contract -2. Configure and start the OP Succinct Proposer instead of the standard `op-proposer` +1. Deploy the `OPSuccinctL2OutputOracle` contract. +2. Configure and start the OP Succinct Proposer instead of the standard `op-proposer`. This minimal change set ensures a smooth transition while leveraging the security benefits of ZK proofs. diff --git a/book/introduction.md b/book/introduction.md index 9da1f632..0f091d8d 100644 --- a/book/introduction.md +++ b/book/introduction.md @@ -14,10 +14,10 @@ OP Succinct transforms any OP Stack rollup into a [fully type-1 ZK rollup](https ## Getting Started -1. Check the [Prerequisites](./quick-start/prerequisites.md) to ensure your environment is ready -2. Run the [Cost Estimator](./quick-start/cost-estimator.md) to understand resource requirements -3. Try [OP Succinct in Mock Mode](./quick-start/mock.md) for development -4. Deploy [OP Succinct in Full Mode](./quick-start/full.md) for production +1. Check the [Prerequisites](./quick-start/prerequisites.md) to ensure your environment is ready. +2. Run the [Cost Estimator](./quick-start/cost-estimator.md) to understand the resource requirements for proving. +3. Try [OP Succinct in Mock Mode](./quick-start/mock.md) for development. +4. Deploy [OP Succinct in Full Mode](./quick-start/full.md) for production. ## Support and Community @@ -27,7 +27,7 @@ All of this has been possible thanks to close collaboration with the core team a ## Documentation Structure -- **Quick Start**: Get up and running quickly with basic setup and configuration -- **Advanced**: Detailed guides for production deployment and maintenance -- **Contracts**: `OPSuccinctL2OutputOracle` contract documentation and deployment guides -- **FAQ & Troubleshooting**: Common issues and their solutions +- **Quick Start**: Get up and running quickly with basic setup and configuration. +- **Advanced**: Detailed guides for production deployment and maintenance. +- **Contracts**: `OPSuccinctL2OutputOracle` contract documentation and deployment guides. +- **FAQ & Troubleshooting**: Common issues and their solutions. From 94512cf97e1c4208dfe940e81735182254c7b91e Mon Sep 17 00:00:00 2001 From: fakedev9999 Date: Mon, 20 Jan 2025 17:06:15 -0800 Subject: [PATCH 3/4] docs: update link to programs To fixs `Linking outside of the "root" directory is forbidden` error. --- book/architecture.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/architecture.md b/book/architecture.md index a7e390eb..ab8fcf63 100644 --- a/book/architecture.md +++ b/book/architecture.md @@ -34,11 +34,11 @@ OP Succinct enables OP Stack blocks to be proven with SP1 through a lightweight ### Core Components -1. **[Range Program](../programs/range/src/main.rs)** +1. **[Range Program](/programs/range/src/main.rs)** - Derives and executes batches of blocks - Generates proofs of correct execution -2. **[Aggregation Program](../programs/aggregation/src/main.rs)** +2. **[Aggregation Program](/programs/aggregation/src/main.rs)** - Aggregates multiple range program proofs - Reduces on-chain verification costs From 4cc8d5a310d784bf18a9ddd5e2857b397246e86e Mon Sep 17 00:00:00 2001 From: fakedev9999 Date: Mon, 20 Jan 2025 17:18:11 -0800 Subject: [PATCH 4/4] docs: ignore mdbook check for links `File not found` error occurs. Link with relative path, but ignore `Linking outside of the "root" directory is forbidden`. --- book/architecture.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/architecture.md b/book/architecture.md index ab8fcf63..5c0a0e11 100644 --- a/book/architecture.md +++ b/book/architecture.md @@ -34,11 +34,11 @@ OP Succinct enables OP Stack blocks to be proven with SP1 through a lightweight ### Core Components -1. **[Range Program](/programs/range/src/main.rs)** +1. **[Range Program](/programs/range/src/main.rs)** - Derives and executes batches of blocks - Generates proofs of correct execution -2. **[Aggregation Program](/programs/aggregation/src/main.rs)** +2. **[Aggregation Program](/programs/aggregation/src/main.rs)** - Aggregates multiple range program proofs - Reduces on-chain verification costs