docs: book tweaks (#90)

* Update README.md * Added book * chore: book tweaks * feat: more docs' * more changes * readme * cleanup * fix errors * hm * fix url * fix docker * hm --------- Co-authored-by: puma314 <[email protected]> Co-authored-by: Uma Roy <[email protected]> Co-authored-by: ratankaliani <[email protected]>
succinctlabs · Sep 2, 2024 · 1da46b4 · 1da46b4
1 parent 267fe2a
commit 1da46b4
Show file tree

Hide file tree

Showing 19 changed files with 494 additions and 89 deletions.
diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml
@@ -0,0 +1,103 @@
+# Documentation and mdbook related jobs.
+# Reference: https://github.com/paradigmxyz/reth/blob/main/.github/workflows/book.yml
+
+name: book
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+    paths:
+      - "book/**"
+  merge_group:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    name: lint
+    timeout-minutes: 60
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mdbook-linkcheck
+        run: |
+          mkdir mdbook-linkcheck
+          curl -sSL -o mdbook-linkcheck.zip https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip
+          unzip mdbook-linkcheck.zip -d ./mdbook-linkcheck
+          chmod +x $(pwd)/mdbook-linkcheck/mdbook-linkcheck
+          echo $(pwd)/mdbook-linkcheck >> $GITHUB_PATH
+
+      - name: Run linkcheck
+        run: mdbook-linkcheck --standalone
+
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+      - name: Install mdbook
+        run: |
+          mkdir mdbook
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+          echo $(pwd)/mdbook >> $GITHUB_PATH
+
+      - name: Install mdbook-template
+        run: |
+          mkdir mdbook-template
+          curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
+          echo $(pwd)/mdbook-template >> $GITHUB_PATH
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+
+      - name: Build book
+        run: mdbook build
+
+      - name: Archive artifact
+        shell: sh
+        run: |
+          chmod -c -R +rX "target/book" |
+          while read line; do
+             echo "::warning title=Invalid file permissions automatically fixed::$line"
+          done
+          tar \
+            --dereference --hard-dereference \
+            --directory "target/book" \
+            -cvf "$RUNNER_TEMP/artifact.tar" \
+            --exclude=.git \
+            --exclude=.github \
+            .
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: github-pages
+          path: ${{ runner.temp }}/artifact.tar
+          retention-days: 1
+          if-no-files-found: error
+
+  deploy:
+    # Only deploy if a push to main
+    if: github.ref_name == 'main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    needs: [lint, build]
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    timeout-minutes: 60
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/README.md b/README.md
@@ -1,38 +1,31 @@
 # op-succinct
 
-Standalone repo to use Kona & SP1 to verify OP Stack blocks.
+OP Succinct turns any OP stack rollup into a full type-1 zkEVM Rollup in 1 hour using SP1.
 
+**[Docs](https://succinctlabs.github.io/op-succinct)**
+| [Learn More](https://succinctlabs.github.io/op-succinct)
 
-## ⚠️ Work in Progress
+> [!CAUTION]
+>
+> This repository is still an active work-in-progress and is not audited or meant for production usage.
 
-**Warning**: This repository is currently a work in progress. The code and documentation are actively being developed and may be subject to significant changes. Use with caution and expect frequent updates.
+## Getting Started
 
+Today, you can already use OP Succinct to upgrade any existing OP Stack rollup to a type-1 zkEVM rollup. To get started, make sure you have [Rust](https://rustup.rs/), [Foundry](https://book.getfoundry.sh/), and [Docker](https://docs.docker.com/engine/install/) installed. Then, follow the steps in the [book]() to deploy the `ZKL2OutputOracle` contract and start the `op-succinct-proposer` service.
 
-## Overview
+## Repository Overview
 
-**`crates`**
-- `client-utils`: A suite of utilities for the client program.
-- `host-utils`: A suite of utilities for constructing the host which runs the OP Succinct program.
+The repository is organized into the following directories:
 
-**`op-succinct`**
-- `native-host`: The host program which runs the `op-succinct` program natively using `kona`.
-- `zkvm-host`: The host program which runs the `op-succinct` program in the SP1 zkVM.
-- `programs`: The programs proven in SP1.
-    - `fault-proof` and `range` are used to verifiably derive and execute single blocks
-    and batches of blocks respectively. Their binary's are first run in native mode on the `kona-host` to
-    fetch the witness data, then they use SP1 to verifiably execute the program.
-   - For `aggregation`, which is used to generate an aggregate proof for a set of batches,
-   first generate proofs for `range` programs for each batch, then use `aggregation` to
-   generate an aggregate proof.
+- `book`: The documentation for OP Succinct users and developers.
+- `contracts`: The solidity contracts for posting state roots to L1.
+- `programs`: The programs for proving the execution and derivation of the L2 state transitions and proof aggregation.
+- `proposer`: The implementation of the `op-succinct-proposer` service.
+- `scripts`: The scripts for proving and generating witnesses.
 
-## Running `op-succinct`
+## Acknowlements
 
-For instructions on how to upgrade an OP Stack chain to use ZK validity proofs, refer to the [`op-succinct` Guide](./op-succinct-proposer/TUTORIAL.md).
-
-## Estimating Cycle Counts
-
-To learn how to estimate cycle counts for a given block range, check out our [Cycle Count Guide](./zkvm-host/CYCLE_COUNT.md).
-
-## Open Source
-
-This code is open sourced under the [Apache 2.0 License](./LICENSE.txt).
+This repo could not exist without:
+* [OP Stack](https://docs.optimism.io/stack/getting-started): Modular software components for building L2 blockchains.
+* [Kona](https://github.com/anton-rs/kona/tree/main): A portable implementations of the OP Stack rollup state transition, namely the derivation pipeline and the block execution logic.
+* [SP1](https://github.com/succinctlabs/sp1): A fast, feature-complete zkVM for developers that can prove the execution of arbitrary Rust (or any LLVM-compiled) program.
diff --git a/book.toml b/book.toml
@@ -0,0 +1,17 @@
+[book]
+authors = ["Uma Roy"]
+language = "en"
+multilingual = false
+src = "book"
+title = "OP Succinct"
+description = "A book on all things SP1"
+
+[build]
+build-dir = "target/book"
+
+[preprocessor.template]
+before = ["links"]
+
+[preprocessor.index]
+
+[preprocessor.links]
diff --git a/book/SUMMARY.md b/book/SUMMARY.md
@@ -0,0 +1,10 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Architecture](./architecture.md)
+- [Getting Started](./getting-started/intro.md)
+  - [Prerequisites](./getting-started/prerequisites.md)
+  - [L2 Output Oracle](./getting-started/l2-output-oracle.md)
+  - [Proposer](./getting-started/proposer.md)
+  - [Configuration](./getting-started/configuration.md)
+- [Cost Estimator CLI Tool](./cost-estimator.md)
diff --git a/book/architecture.md b/book/architecture.md
@@ -0,0 +1,23 @@
+# Architecture
+
+## Prerequisites
+
+Every OP Stack rollup is composed of four main 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.
+
+You can read more about the components in the [OP Stack Specification](https://specs.optimism.io/).
+
+## OP Succinct
+
+OP Succinct is designed to be an upgrade that replaces the `op-proposer` component of the OP Stack and its associated on-chain contracts. This change allows the chain to progress only with ZK-proven blocks, while keeping the other components (`op-geth`, `op-batcher`, and `op-node`) unchanged.
+
+Here is a high-level overview of the new components that are introduced in OP Succinct:
+
+- **Span 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 span programs to reduce on-chain verification cost. 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 span and aggregation programs.
diff --git a/book/cost-estimator.md b/book/cost-estimator.md
@@ -0,0 +1,62 @@
+# Cycle Counts [Cost Estimator]
+
+We provide a convenient CLI tool to estimate the RISC-V cycle counts (and cost) for generating ZKPs for a range of blocks for a given rollup.
+
+## Overview
+
+First, add the following RPCs to your `.env` file for your rollup:
+
+```bash
+# L1 RPC
+L1_RPC=
+# L1 Consensus RPC
+L1_BEACON_RPC=
+# L2 Archive Node (OP-Geth)
+L2_RPC=
+```
+
+It is required that the L2 RPC is an archival node for your OP stack rollup, with the "debug_dbGet" endpoint enabled.
+
+Then run the following command:
+```shell
+RUST_LOG=info just run-multi <start_l2_block> <end_l2_block>
+```
+
+This will fetch the required data for generating a ZKP for the given block range, "execute" the
+corresponding SP1 program, and return the cycle count. Then, you can extrapolate the cycle count
+to a cost based on the cost per billion cycles.
+
+Proofs over a span batch are split into several "span proofs", which prove the validity of a section of the span batch. Then, these span proofs are aggregated into a single proof, which is submitted to the L1.
+
+## Example Block Range
+
+On OP Sepolia, generating a proof from 15840000 to 15840050 (50 blocks) takes ~1.5B cycles and takes
+~2 minutes to execute.
+
+```bash
+RUST_LOG=info just run-multi 15840000 15840050
+
+...Execution Logs...
+
++--------------------------------+---------------------------+
+| Metric                         | Value                     |
++--------------------------------+---------------------------+
+| Total Cycles                   |             1,502,329,547 |
+| Block Execution Cycles         |             1,009,112,508 |
+| Total Blocks                   |                        51 |
+| Total Transactions             |                       202 |
+| Cycles per Block               |                19,786,519 |
+| Cycles per Transaction         |                 4,995,606 |
+| Transactions per Block         |                         3 |
+| Total Gas Used                 |                52,647,751 |
+| Gas Used per Block             |                 1,032,308 |
+| Gas Used per Transaction       |                   260,632 |
++--------------------------------+---------------------------+
+```
+
+## Misc
+- For large enough block ranges, the RISC-V SP1 program will surpass the SP1 memory limit. Recommended limit is 20-30 blocks.
+- Your L2 node must have been synced for the blocks in the range you are proving. 
+   - OP Sepolia Node: Synced from block 15800000 onwards.
+   - OP Mainnet Node: Synced from block 122940000 onwards.
+
diff --git a/book/deploy/intro.md b/book/deploy/intro.md
@@ -0,0 +1 @@
+# Deploy OP Succinct
diff --git a/book/deploy/op-stack.md b/book/deploy/op-stack.md
@@ -0,0 +1 @@
+# Base OP Stack Rollup
diff --git a/contracts/README.md → book/deploy/smart-contract.md b/contracts/README.md → book/deploy/smart-contract.md
@@ -1,11 +1,24 @@
-## ZK Contracts
+# Deploy Smart Contracts
 
-The `contracts/` directory consists of two things:
+The first step in deploying OP Succinct is to deploy a Solidity smart contract that will verify ZKPs of OP derivation (OP's name for their state transition function) and contain the latest state root of your rollup.
 
-1) The `ZKL2OutputOracle.sol` contract, a diff of Optimism's `L2OutputOracle.sol` contract with the necessary changes to support ZK validity proofs.
+## Overview
+
+The `contracts/` directory has the relevant smart contracts and deployment scripts for this step. In particular, it contains:
+
+1) The `ZKL2OutputOracle.sol` contract which verifies a ZKP of OP derivation, and is a small of Optimism's `L2OutputOracle.sol` contract with the necessary changes to support ZK validity proofs.
 
 2) The `ZKUpgrader.s.sol` script, which deploys the `ZKL2OutputOracle.sol` implementation contract, upgrades an existing `L2OutputOracleProxy` to point to it, and initializes the new contract with values from `zkconfig.json`.
 
+[TODO: insert a diagram of how all the OP stack contracts interact with the ZKL2OutputOracle.sol]
+
+## Deployment
+
+### Upgrading an existing `L2OutputOracle.sol`
+
+### Deploying `ZKL2OutputOracle.sol`
+
+### ... 
 3) The `ZKDeployer.s.sol` script, which deploys the `ZKL2OutputOracle.sol` implementation contract, upgrades an existing `L2OutputOracleProxy` to point to it, and initializes the new contract with values from `zkconfig.json`.
 
 ## Deploy Fresh Proxy

diff --git a/book/deploy/zk-proposer.md b/book/deploy/zk-proposer.md
@@ -0,0 +1,54 @@
+# Deploy ZK Proposer
+
+After deploying the `ZKL2OutputOracle.sol`, the final step is to launch a "ZKP" version of the `op-proposer` that will call to [Succinct's Prover Network](TODO) to generate proofs and submit them onchain.
+
+## Deployment
+
+First, create a `.env.server` file that matches the `.env.server.example` file in the root of the `op-succinct` repo. 
+
+```bash
+cp .env.server.example .env.server
+```
+
+<!-- TODO: include more details about how to fill in the .env -->
+
+
+Then, to run the OP proposer, follow these steps:
+
+Build the server with:
+
+```bash
+docker compose build
+```
+
+Then, start the server:
+```bash
+docker compose up -d
+```
+
+To stop the server, run:
+```bash
+docker compose down
+```
+
+This launches a Docker container with a modified version of the `op-proposer` (which can be found at [our fork](https://github.com/succinctlabs/optimism/tree/zk-proposer)). 
+
+The modified `op-proposer` performs the following tasks:
+- Monitors L1 state to determine when to request a proof.
+- Requests proofs from the Kona SP1 server.
+- Once proofs have been generated for a sufficiently large range (specified by `SUBMISSION_INTERVAL` in `zkconfig.json`), aggregates batch proofs and submits them on-chain.
+
+
+## Underneath the Hood
+
+Underneath the hood, there are a very components involved in running the `op-succinct` proposer: 
+
+**`op-succinct` Server**:
+- There is a very lightweight server running with [op-succinct-proposer/bin/server.rs] that is is responsible or given a block range, it will generate the witness data for that block range by running the "native host" and then dispatch the proof request to the Succinct Prover Network.
+
+**`op-succinct` Proposer**:
+   - Runs the modified `op-proposer` binary from the Optimism repository which keeps the `ZKL2OutputOracle` contract up to date with the latest L2 state using
+   SP1 proofs.
+   - When a new L2 block is detected, the proposer requests a ZK proof from the OP Succinct Server. Once the proof is generated, it's
+   posted to the `ZKL2OutputOracle` contract.
+   - Uses a SQLite database (`proofs.db`) to keep track of processed blocks and proofs.
diff --git a/book/getting-started/configuration.md b/book/getting-started/configuration.md
@@ -0,0 +1,22 @@
+# Configuration
+
+The last step is to update your OP Stack configuration to use the new `ZKL2OutputOracle` contract managed by the `op-succinct-proposer` service.
+
+## Self-Managed OP Stack Chains
+
+If you are using a self-managed OP Stack chain, you will need to use your `ADMIN` key to update the existing `L2OutputOracle` implementation. Recall that the `L2OutputOracle` is a proxy contract that is upgradeable using the `ADMIN` key.
+
+To update the `L2OutputOracle` implementation, you can use an existing script we have in the `op-succinct` repo:
+
+```bash
+forge script script/ZKUpgrader.s.sol:ZKUpgrader \
+    --rpc-url $L1_RPC \
+    --private-key $PRIVATE_KEY \
+    --verify \
+    --verifier etherscan \
+    --etherscan-api-key $ETHERSCAN_API_KEY \
+    --broadcast \
+    --ffi
+```
+
+## RaaS Providers