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..5c0a0e11 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 transforms any OP Stack chain into a fully validity-proven rollup with a lightweight upgrade that maintains compatibility with existing OP Stack components. -- `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. +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). -You can read more about the components in the [OP Stack Specification](https://specs.optimism.io/). +## Standard OP Stack Components -## OP Succinct +Every OP Stack rollup consists of four main components: -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. +- `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 -Here is a high-level overview of the new components that are introduced in OP Succinct: +For more details on these components, refer to the [OP Stack Specification](https://specs.optimism.io/). -- **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 Extensions + +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](/programs/range/src/main.rs)** + - Derives and executes batches of blocks + - Generates proofs of correct execution + +2. **[Aggregation Program](/programs/aggregation/src/main.rs)** + - 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..0f091d8d 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 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 + 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.