WIP witness gen section

Author: Jiangkm3

docs/spartan_parallel.md

@@ -110,4 +110,33 @@ The discrepancy between the two versions requires additional handling of commitm
 Thus,
 $$\mathcal{C}_\text{sumcheck}(rx || ry) =  (\prod_{r\in rx_\text{pad} || ry_\text{pad}} 1 - r) \cdot \mathcal{C}_\text{commit}(rx_\text{eval} || ry_\text{comb} || ry_\text{eval})$$
 
-So the opening is performed on $(rx_\text{eval} || ry_\text{comb} || ry_\text{eval})$, and the verifier checks the result by computing and multiplying by $\prod_{r\in rx_\text{pad} || ry_\text{pad}} (1 - r)$.
+So the opening is performed on $(rx_\text{eval} || ry_\text{comb} || ry_\text{eval})$, and the verifier checks the result by computing and multiplying by $\prod_{r\in rx_\text{pad} || ry_\text{pad}} (1 - r)$.
+
+## Witness Preprocessing and Generation
+Relevant files: `examples/interface.rs` and `src/lib.rs`
+
+### Inputs from `circ_blocks`
+Relevant struct: `RunTimeKnowledge` in `examples/interface.rs`
+
+At runtime, `spartan_parallel` reads in from `circ_blocks` through the struct `RunTimeKnowledge`, which describes all the witnesses generated from the blocks:
+* `block_vars_matrix`: all the inputs, outputs, memory accesses, and intermediate computations of every block executions, grouped by type of blocks.
+* `exec_inputs`: all the inputs and outputs of every block, sorted by execution time.
+* `init_phy_mems_list`, `init_vir_mems_list`: memory accesses that sets up the initial memory state, in any order.
+* `addr_phy_mems_list`, `addr_vir_mems_list`: memory accesses throughout the program execution (including initialization), ordered by address.
+* `addr_ts_bits_list`: bit split of timestamp difference, used by memory coherence check.
+
+### Witness Preprocessing and Commitment
+Relevant file: `src/lib.rs`
+
+Apart from the witnesses provided by each block execution, the prover also needs to compute additional witnesses used by permutation and consistency checks. This includes, most notably:
+* `perm_w0 = [tau, r, r^2, ...]`: the randomness used by the random linear permutation. This value is can be efficiently generated by the verifier and does not require commitment.
+* `block_w2`, `perm_exec_w2`, `phy_mem_w2`, `vir_mem_w2`: intermediate values used to compute random linear combinations.
+* `block_w3`, `perm_exec_w3`, `phy_mem_w3`, `vir_mem_w3`: RLC and cumulative product of RLC. Each is consisted of $w3_k = [v_k, x_k, \pi_k, D_k, ri_k, ro_k]$, where
+  - $v_k$ is the valid bit, set to 0 if this particular $w3$ is a pad. If $v_k$ is 0, then every entry of $w3_k$ is 0.
+  - $x_k$ is the random linear combination of $(i_k, o_k)$, $p_k$, or $v_k$
+  - $\pi_k$ is the cumulative product $\prod_{p \geq k}x_p$, computed as $\pi_k = v_k\cdot D_k$
+  - $D_k$ is an intermediate variable: $D_k = x_k \cdot (\pi_{k+1} + (1 - v_{k+1}))$
+  - $ri_k$ and $ro_k$ are only used by register transition to record the RLC of $i_k$ and $o_k$ individually
+
+Note that all of the above witnesses have different sizes:
+*