docs: mdbook (#28)

succinctlabs · Oct 24, 2024 · 2f7c1cb · 2f7c1cb
1 parent 7880a3d
commit 2f7c1cb
Show file tree

Hide file tree

Showing 10 changed files with 304 additions and 96 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/.github/workflows/pr.yml b/.github/workflows/pr.yml
@@ -0,0 +1,40 @@
+name: PR
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches:
+      - "**"
+  merge_group:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Formatting & Clippy
+    runs-on: [runs-on, runner=16cpu-linux-arm64	, "run-id=${{ github.run_id }}"]
+    env:
+      CARGO_NET_GIT_FETCH_WITH_CLI: "true"
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          components: rustfmt
+
+      - name: Run rustfmt
+        run: cargo fmt --all -- --check
+        env:
+          CARGO_INCREMENTAL: 1
+
+      - name: Run cargo clippy
+        run: cargo clippy --all-features --all-targets -- -D warnings -A incomplete-features
+        env:
+          CARGO_INCREMENTAL: 1
diff --git a/contracts/.github/workflows/test.yml → .github/workflows/test.yml b/contracts/.github/workflows/test.yml → .github/workflows/test.yml
diff --git a/README.md b/README.md
@@ -2,100 +2,6 @@
 
 ## Overview
 
-SP1 Blobstream is an implementation of [Blobstream X](https://github.com/succinctlabs/blobstreamx) in Rust for the SP1 zkVM.
-
-- `/program`: The SP1 Blobstream program.
-- `/primitives`: Libraries for types and helper functions used in the program.
-- `/script`: Scripts for getting the contract's genesis parameters and deploying the operator to 
-    update the light client.
-- `/contracts`: The contract's source code and deployment scripts. Backwards-compatible with the
-    original BlobstreamX implementation in case we need to upgrade.
-
-
-## Deploying SP1 Blobstream
-
-### Components
-
-An SP1 Blobstream implementation has a few key components:
-- An `SP1Blobstream` contract. Contains the logic for verifying SP1 Blobstream proofs, storing the
-latest data from the Celestia chain, including the headers and data commitments. Matches the interface
-of the existing [BlobstreamX](https://github.com/succinctlabs/blobstreamx/blob/main/contracts/src/BlobstreamX.sol) contract so it can be upgraded in-place.
-- An `SP1Verifier` contract. Verifies arbitrary SP1 programs. Most chains will have canonical deployments
-upon SP1's mainnet launch. Until then, users can deploy their own `SP1Verifier` contracts to verify
-SP1 programs on their chain. The SP1 Blobstream implementation will use the `SP1Verifier` contract to verify
-the proofs of the SP1 Blobstream programs.
-- The SP1 Blobstream program. An SP1 program that verifies the transition between two Tendermint
-headers and computes the data commitment of the intermediate blocks.
-- The operator. A Rust script that fetches the latest data from a deployed `SP1Blobstream` contract and a 
-Tendermint chain, determines the block to request, requests for/generates a proof, and relays the proof to
-the `SP1Blobstream` contract.
-
-### Deployment
-
-1. To deploy an SP1 Blobstream contract for a Tendermint chain do the following.
-
-    Get the genesis parameters for the `SP1Blobstream` contract.
-
-    ```shell
-    cd script
-
-    # Example with Celestia Mocha-4 Testnet.
-    TENDERMINT_RPC_URL=https://rpc.lunaroasis.net/ cargo run --bin genesis --release
-    ```
-
-2. Deploy the `SP1Blobstream` contract with genesis parameters: `GENESIS_HEIGHT`, `GENESIS_HEADER`, and `SP1_BLOBSTREAM_PROGRAM_VKEY`.
-
-    ```shell
-    cd ../contracts
-
-    forge install
-
-    GENESIS_HEIGHT=<GENESIS_HEIGHT> GENESIS_HEADER=<GENESIS_HEADER> SP1_BLOBSTREAM_PROGRAM_VKEY=<SP1_BLOBSTREAM_PROGRAM_VKEY> forge script script/Deploy.s.sol --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --etherscan-api-key <ETHERSCAN_API_KEY> --broadcast --verify
-    ```
-
-    If you see the following error, add `--legacy` to the command.
-    ```shell
-    Error: Failed to get EIP-1559 fees    
-    ```
-3. Your deployed contract address will be printed to the terminal.
-
-    ```shell
-    == Return ==
-    0: address <SP1_BLOBSTREAM_ADDRESS>
-    ```
-
-    This will be used when you run the operator in step 5.
-
-4. Export your SP1 Prover Network configuration
-
-    ```shell
-    # Export the PRIVATE_KEY you will use to relay proofs.
-    export PRIVATE_KEY=<PRIVATE_KEY>
-
-    # Optional
-    # If you're using the Succinct network, set SP1_PROVER to "network". Otherwise, set it to "local" or "mock".
-    export SP1_PROVER={network|local|mock}
-    # Only required if SP1_PROVER is set "network".
-    export SP1_PRIVATE_KEY=<SP1_PRIVATE_KEY>
-    ```
-
-5. Run the SP1 Blobstream operator to update the LC continuously.
-
-    ```
-    cd ../script
-
-    TENDERMINT_RPC_URL=https://rpc.celestia-mocha.com/ CHAIN_ID=11155111 RPC_URL=https://ethereum-sepolia.publicnode.com/
-    CONTRACT_ADDRESS=<SP1_BLOBSTREAM_ADDRESS> cargo run --bin operator --release
-    ```
-
-## Known Limitations
-
-**Warning:** The implementation of SP1 Blobstream assumes that the number of validators is less than 
-256. This limitation is due to the use of a 256-bit bitmap to represent whether a validator has 
-signed off on a header. If the number of validators exceeds 256, the `validatorBitmap` functionality
-may not work as intended, potentially leading to an incomplete validator equivocation. 
-
-On Celestia, the number of validators is currently 100, and there are no plans to increase this number
-significantly. If it was to be increased, the signature aggregation logic in the consensus protocol
-would likely change as well, which would also necessitate a change in the SP1 Blobstream implementation.
+Implementation of zero-knowledge proof circuits for [Blobstream](https://docs.celestia.org/how-to-guides/blobstream), a Celestia's data attestation bridge in SP1.
 
+**[Docs](https://succinctlabs.github.io/sp1-blobstream)**
diff --git a/book.toml b/book.toml
@@ -0,0 +1,13 @@
+[book]
+authors = ["Ratan Kaliani"]
+language = "en"
+multilingual = false
+src = "book"
+title = "SP1 Blobstream Documentation"
+
+[build]
+build-dir = "target/book"
+
+[output.html]
+git-repository-url = "https://github.com/succinctlabs/sp1-blobstream"
+git-repository-icon = "fa-github"
diff --git a/book/SUMMARY.md b/book/SUMMARY.md
@@ -0,0 +1,6 @@
+# Summary
+
+- [Introduction](introduction.md)
+- [Deployment](deployment.md)
+- [Reproducible Builds](reproducible-builds.md)
+- [Known Limitations](limitations.md)
diff --git a/book/deployment.md b/book/deployment.md
@@ -0,0 +1,57 @@
+# Deploying SP1 Blobstream
+
+1. To deploy an SP1 Blobstream contract for a Tendermint chain do the following.
+
+    Get the genesis parameters for the `SP1Blobstream` contract.
+
+    ```shell
+    cd script
+
+    # Example with Celestia Mocha-4 Testnet.
+    TENDERMINT_RPC_URL=https://rpc.lunaroasis.net/ cargo run --bin genesis --release
+    ```
+
+2. Deploy the `SP1Blobstream` contract with genesis parameters: `GENESIS_HEIGHT`, `GENESIS_HEADER`, and `SP1_BLOBSTREAM_PROGRAM_VKEY`.
+
+    ```shell
+    cd ../contracts
+
+    forge install
+
+    GENESIS_HEIGHT=<GENESIS_HEIGHT> GENESIS_HEADER=<GENESIS_HEADER> SP1_BLOBSTREAM_PROGRAM_VKEY=<SP1_BLOBSTREAM_PROGRAM_VKEY> forge script script/Deploy.s.sol --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --etherscan-api-key <ETHERSCAN_API_KEY> --broadcast --verify
+    ```
+
+    If you see the following error, add `--legacy` to the command.
+    ```shell
+    Error: Failed to get EIP-1559 fees    
+    ```
+3. Your deployed contract address will be printed to the terminal.
+
+    ```shell
+    == Return ==
+    0: address <SP1_BLOBSTREAM_ADDRESS>
+    ```
+
+    This will be used when you run the operator in step 5.
+
+4. Export your SP1 Prover Network configuration
+
+    ```shell
+    # Export the PRIVATE_KEY you will use to relay proofs.
+    export PRIVATE_KEY=<PRIVATE_KEY>
+
+    # Optional
+    # If you're using the Succinct network, set SP1_PROVER to "network". Otherwise, set it to "local" or "mock".
+    export SP1_PROVER={network|local|mock}
+    # Only required if SP1_PROVER is set "network".
+    export SP1_PRIVATE_KEY=<SP1_PRIVATE_KEY>
+    ```
+
+5. Run the SP1 Blobstream operator to update the LC continuously.
+
+    ```
+    cd ../script
+
+    TENDERMINT_RPC_URL=https://rpc.celestia-mocha.com/ CHAIN_ID=11155111 RPC_URL=https://ethereum-sepolia.publicnode.com/
+    CONTRACT_ADDRESS=<SP1_BLOBSTREAM_ADDRESS> cargo run --bin operator --release
+    ```
diff --git a/book/introduction.md b/book/introduction.md
@@ -0,0 +1,28 @@
+# SP1 Blobstream
+
+## Overview
+
+SP1 Blobstream is an implementation of [Blobstream X](https://github.com/succinctlabs/blobstreamx) in Rust for the SP1 zkVM.
+
+- `/program`: The SP1 Blobstream program.
+- `/primitives`: Libraries for types and helper functions used in the program.
+- `/script`: Scripts for getting the contract's genesis parameters and deploying the operator to 
+    update the light client.
+- `/contracts`: The contract's source code and deployment scripts. Backwards-compatible with the
+    original BlobstreamX implementation in case we need to upgrade.
+
+## Components
+
+An SP1 Blobstream implementation has a few key components:
+- An `SP1Blobstream` contract. Contains the logic for verifying SP1 Blobstream proofs, storing the
+latest data from the Celestia chain, including the headers and data commitments. Matches the interface
+of the existing [BlobstreamX](https://github.com/succinctlabs/blobstreamx/blob/main/contracts/src/BlobstreamX.sol) contract so it can be upgraded in-place.
+- An `SP1Verifier` contract. Verifies arbitrary SP1 programs. Most chains will have canonical deployments
+upon SP1's mainnet launch. Until then, users can deploy their own `SP1Verifier` contracts to verify
+SP1 programs on their chain. The SP1 Blobstream implementation will use the `SP1Verifier` contract to verify
+the proofs of the SP1 Blobstream programs.
+- The SP1 Blobstream program. An SP1 program that verifies the transition between two Tendermint
+headers and computes the data commitment of the intermediate blocks.
+- The operator. A Rust script that fetches the latest data from a deployed `SP1Blobstream` contract and a 
+Tendermint chain, determines the block to request, requests for/generates a proof, and relays the proof to
+the `SP1Blobstream` contract.
diff --git a/book/limitations.md b/book/limitations.md
@@ -0,0 +1,10 @@
+# Known Limitations
+
+**Warning:** The implementation of SP1 Blobstream assumes that the number of validators is less than 
+256. This limitation is due to the use of a 256-bit bitmap to represent whether a validator has 
+signed off on a header. If the number of validators exceeds 256, the `validatorBitmap` functionality
+may not work as intended, potentially leading to an incomplete validator equivocation. 
+
+On Celestia, the number of validators is currently 100, and there are no plans to increase this number
+significantly. If it was to be increased, the signature aggregation logic in the consensus protocol
+would likely change as well, which would also necessitate a change in the SP1 Blobstream implementation.