doc(book): Fill up empty sections and add table diagram (#608)

* Fill up empty sections and add table diagram

* Typo

* Ignore mermaid initialization files

* Update workflow

.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:

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).
 
 <!---
-TODO: Update mermaid chard with `smt_trie` once type-2 is plugged in.
+TODO: Update mermaid chart with `smt_trie` once type-2 is plugged in.
 -->
 ```mermaid
+%%{init: {'theme':'dark'}}%%
 flowchart LR
     subgraph ps [proving systems]
     A1{{plonky2}}

book/.gitignore

@@ -1 +1,6 @@
 book
+
+# Mermaid initialization files
+# Obtained with `mdbook-mermaid install book`.
+mermaid-init.js
+mermaid.min.js

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

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)

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

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.