diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml index 45c47716e..97df1d973 100644 --- a/.github/workflows/book.yml +++ b/.github/workflows/book.yml @@ -3,9 +3,12 @@ name: zkEVM mdbook on: push: branches: [develop, main] + pull_request: + branches: + - "**" jobs: - deploy: + build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 @@ -20,15 +23,24 @@ jobs: command: install args: mdbook - - name: Install mdbook-katex and mdbook-bib + - name: Install preprocessors uses: actions-rs/cargo@v1 with: command: install - args: mdbook-katex mdbook-bib + args: mdbook-katex mdbook-bib mdbook-mermaid + + - name: Initialize mermaid preprocessor + run: mdbook-mermaid install book - name: Build book run: mdbook build book + deploy: + if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop') + runs-on: ubuntu-latest + needs: build + steps: + - uses: actions/checkout@v3 - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: diff --git a/README.md b/README.md index a4d8326e4..b7bd2208e 100644 --- a/README.md +++ b/README.md @@ -28,9 +28,10 @@ EVM block proofs. Below is a simplified view of the dependency graph, including the proving system backends and the application layer defined within [zero-bin](https://github.com/0xPolygonZero/zero-bin). ```mermaid +%%{init: {'theme':'dark'}}%% flowchart LR subgraph ps [proving systems] A1{{plonky2}} diff --git a/book/.gitignore b/book/.gitignore index 7585238ef..2b1e9364a 100644 --- a/book/.gitignore +++ b/book/.gitignore @@ -1 +1,6 @@ book + +# Mermaid initialization files +# Obtained with `mdbook-mermaid install book`. +mermaid-init.js +mermaid.min.js diff --git a/book/book.toml b/book/book.toml index 33cbda21c..eb3dcc30c 100644 --- a/book/book.toml +++ b/book/book.toml @@ -20,7 +20,11 @@ create-missing = true [preprocessor.bib] bibliography = "bibliography.bib" +[preprocessor.mermaid] +command = "mdbook-mermaid" + [output.html] +additional-js = ["mermaid.min.js", "mermaid-init.js"] [output.html.print] # Disable page break diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index c2ee742bc..bdd613969 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -1,10 +1,10 @@ # Summary -[Introduction](intro.md) +[Introduction](../../README.md) - [STARK framework](framework/intro.md) - - [Cost model](framework/cost_model.md) - [Field](framework/field.md) + - [Cost model](framework/cost_model.md) - [Cross-Table Lookups](framework/ctls.md) - [Range-Checks](framework/range_check.md) - [Tables](tables/intro.md) diff --git a/book/src/intro.md b/book/src/intro.md deleted file mode 100644 index e10b99d01..000000000 --- a/book/src/intro.md +++ /dev/null @@ -1 +0,0 @@ -# Introduction diff --git a/book/src/mpt/intro.md b/book/src/mpt/intro.md index 1bb416531..25018bb84 100644 --- a/book/src/mpt/intro.md +++ b/book/src/mpt/intro.md @@ -3,7 +3,7 @@ The *EVM World state* is a representation of the different accounts at a particular time, as well as the last processed transactions together with their receipts. The world state is represented using *Merkle -Patricia Tries* (MPTs) [@@yellowpaper App. D], and there are three +Patricia Tries* (MPTs, see [Yellowpaper App. D](@@yellowpaper)), and there are three different tries: the state trie, the transaction trie and the receipt trie. @@ -17,10 +17,10 @@ inserting new nodes or deleting existing nodes. An MPT is composed of five different nodes: branch, extension, leaf, empty and digest nodes. Branch and leaf nodes might contain a payload whose format depends on the particular trie. The nodes are encoded, -primarily using RLP encoding and Hex-prefix encoding (see @@yellowpaper -App. B and C, respectively). The resulting encoding is then hashed, -following a strategy similar to that of normal Merkle trees, to generate -the trie hashes. +primarily using RLP encoding and Hex-prefix encoding (see [Yellowpaper +App. B and C](@@yellowpaper), respectively). The resulting encoding is +then hashed, following a strategy similar to that of normal Merkle trees, +to generate the trie hashes. Insertion and deletion is performed in the same way as other MPTs implementations. The only difference is for inserting extension nodes diff --git a/book/src/tables/intro.md b/book/src/tables/intro.md index afb1b4c41..8e6ac1d29 100644 --- a/book/src/tables/intro.md +++ b/book/src/tables/intro.md @@ -1 +1,42 @@ # Tables + +Our EVM statements are decomposed into several STARK tables, each corresponding to some coprocessor capable of handling specific operations, +orchestrated by a [Central Processing Unit](./cpu.md). + +Each coprocessor execution can be proven independently and concurrently, and a global check (via our [cross-table lookups](../framework/ctls.md)) +enforces consistency of values being shared across multiple coprocessors. + +Below is a depiction of the current decomposition of EVM statements execution[^1]: + +```mermaid +%%{init: {'theme':'dark'}}%% +flowchart TB + A[Arithmetic] + BP[BytePacking] + C[CPU] + + subgraph KK [ Keccak Hash ] + direction LR + K[Keccak] + KS[KeccakSponge] + K --- KS + end + + L[Logic] + M[Memory] + + subgraph MM [ zk-continuations ] + MB[MemBefore] + MA[MemAfter] + MB --- MA + end + + C --- A + C --- BP + C --- KK + C --- L + C --- M + M --- MM +``` + +[^1]: This diagram is simplified, and does not represent *all* interactions between co-processors. \ No newline at end of file