feat: Final docs pass

.github/actions/setup/action.yml

@@ -14,13 +14,15 @@ runs:
     - name: Set env
       shell: bash
       run: |
-        echo "RUSTFLAGS=${{env.RUSTFLAGS}} --cfg tokio_unstable" | tee -a $GITHUB_ENV
+        echo "RUSTFLAGS=${{env.RUSTFLAGS}} --cfg tokio_unstable -C opt-level=3" | tee -a $GITHUB_ENV
         echo "RUST_LOG=info" | tee -a $GITHUB_ENV
     - uses: actions/setup-go@v5
       with:
         go-version: '1.22'
         cache-dependency-path: "**/go.sum"
-    - uses: dtolnay/rust-toolchain@stable
+    - uses: dtolnay/rust-toolchain@master
+      with:
+        toolchain: nightly-2024-05-31
     - uses: Swatinem/rust-cache@v2
       with:
         workspaces: "aptos -> target"

.github/workflows/bench.yml

@@ -59,7 +59,9 @@ jobs:
         uses: ./.github/actions/setup
         with:
           pull_token: ${{ secrets.REPO_TOKEN }}
-      - uses: dtolnay/rust-toolchain@nightly
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: nightly-2024-05-31
       - name: Install extra deps
         run: |
           sudo apt-get update && sudo apt-get install -y python3-pip

.github/workflows/bump-version-PR.yml

@@ -32,7 +32,9 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: nightly-2024-05-31
 
       - name: Install `tq-rs`
         run: cargo install tq-rs

aptos/core/README.md

@@ -22,19 +22,20 @@ chain. The code for this is located in the `aptos_test_utils` module.
 To run tests, we recommend the following command:
 
 ```shell
-cargo +nightly nextest run --verbose --release --profile ci --features aptos --package aptos-lc --no-capture
+cargo +nightly-2024-05-31 nextest run --verbose --release --profile ci --features aptos --package aptos-lc --no-capture
 ```
 
 This command should be run with the following environment variable:
 
-- `RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable"`:
+- `RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable -C opt-level=3"`:
     - `-C target-cpu=native`: This will ensure that the binary is optimized
       for the CPU it is running on. This is very important
       for [plonky3](https://github.com/plonky3/plonky3?tab=readme-ov-file#cpu-features) performance.
     - `--cfg tokio_unstable`: This will enable the unstable features of the
       Tokio runtime. This is necessary for aptos dependencies.
+    - `-C opt-level=3`: This turns on the maximum level of compiler optimizations.
     - This can also be configured in `~/.cargo/config.toml` instead by adding:
         ```toml
         [target.'cfg(all())']
-        rustflags = ["--cfg", "tokio_unstable", "-C", "target-cpu=native"]
-        ```
+        rustflags = ["--cfg", "tokio_unstable", "-C", "target-cpu=native", "-C", "opt-level=3"]
+        ```

aptos/docs/src/SUMMARY.md

@@ -10,6 +10,7 @@ This section goes over the high-level concept behind the Aptos Light Client.
 - [Epoch change proof](./design/epoch_change_proof.md)
 - [Inclusion proof](./design/inclusion_proof.md)
 - [Edge cases](./design/edge_cases.md)
+- [Security considerations](./design/security.md)
 
 # Components
 
@@ -36,10 +37,10 @@ This section goes over how to run the benchmarks to measure the performances of
 
 - [Overview](./benchmark/overview.md)
 - [Configuration](./benchmark/configuration.md)
-- [Benchmarks individual proofs](./benchmark/proof.md)
+- [Benchmark individual proofs](./benchmark/proof.md)
 - [E2E benchmarks](./benchmark/e2e.md)
 - [On-chain verification benchmarks](./benchmark/on_chain.md)
 
 # Miscellaneous
 
-- [Release / Hotfix process](./misc/release.md)
+- [Release / Hotfix process](./misc/release.md)

aptos/docs/src/benchmark/configuration.md

@@ -4,11 +4,23 @@ In this section we will cover the configuration that should be set to run the be
 important to run the benchmarks on proper machines, such as the one described for the Proof Server in
 the [Run the Light Client](../run/overview.md) section.
 
-## Settings
+## Requirements
+
+The requirements to run the benchmarks are the same as the ones for the client. You will need to follow
+the instructions listed [here](../run/configuration.md).
+
+## Other settings
 
 Here are the standard config variables that are worth setting for any benchmark:
 
-- `RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable"`
+- `RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable -C opt-level=3"`
+
+  This can also be configured in `~/.cargo/config.toml` by adding:
+    ```toml
+    [target.'cfg(all())']
+    rustflags = ["--cfg", "tokio_unstable", "-C", "target-cpu=native", "-C", "opt-level=3"]
+    ```
+
 - `SHARD_SIZE=4194304`
 
   The highest possible setting, giving the fewest shards. Because the compression phase dominates the timing of the
@@ -18,27 +30,25 @@ Here are the standard config variables that are worth setting for any benchmark:
 
   This disables checkpointing making proving faster at the expense of higher memory usage
 
-- `cargo +nightly`
+- `cargo +nightly-2024-05-31`
 
-  This ensures you are on a nightly toolchain, overriding the local `rust-toolchain.toml` file. Nightly allows usage
-  of AVX512 instructions which is crucial for performance.
+  This ensures you are on a nightly toolchain. Nightly allows usage of AVX512 instructions which is crucial for performance.
+  This is the same version set on `rust-toolchain.toml`. It's pinned to a specific release (`v1.80.0-nightly`) to prevent
+  unexpected issues caused by newer Rust versions.
 
 - `cargo bench --release <...>`
 
-  Or otherwise specify compiler options via `RUSTFLAGS="-Copt-level=3 lto=true <...>"` or Cargo profiles
+  Make sure to always run in release mode with `--release`. Alternatively, specify the proper compiler options via
+  `RUSTFLAGS="-C opt-level=3 <...>"`, `~/.cargo/config.toml` or Cargo profiles
 
 - `RUST_LOG=debug` _(optional)_
 
   This prints out useful Sphinx metrics, such as cycle counts, iteration speed, proof size, etc.
 
-## Requirements
-
-The requirements to run the benchmarks are the same as the ones for the client. You can find those instructions
-in [their dedicated section](../run/configuration.md).
-
 ## SNARK proofs
 
 When running any tests or benchmarks that makes Plonk proofs over BN254, the prover leverages some pre-built circuits
-artifacts. Those circuits artifacts are generated when we release new versions of Sphinx and are made avaialble on a
-remote storage. The current address for the storage can be
-found [here](https://github.com/lurk-lab/sphinx/blob/dev/prover/src/install.rs).
+artifacts. Those circuits artifacts are generated when we release new versions of Sphinx and are automatically
+downloaded on first use. The current address for downloading the artifacts can be found
+[here](https://github.com/lurk-lab/sphinx/blob/dev/prover/src/install.rs), but it should not be necessary to download
+them manually.

aptos/docs/src/benchmark/e2e.md

@@ -2,23 +2,28 @@
 
 The end-to-end benchmark is meant to benchmark the time taken to send both of the proofs generation request to the Proof
 Server, have a parallel computation happen and receive the two proofs back. This benchmark is meant to simulate the
-worst case scenario where the client has to generate two proofs in parallel.
+worst case scenario where the client has to generate two proofs in parallel. It can run the proofs in sequence if the
+benchmark is running in a single machine, to prevent resource exhaustion.
 
 The benchmark can be found in
 the [`proof-server`](https://github.com/lurk-lab/zk-light-clients/blob/dev/aptos/proof-server/benches/proof_server.rs)
 crate. It can be run with the following command:
 
 ```bash
-RUST_LOG="debug" RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable" PRIMARY_ADDR="127.0.0.1:8080" SECONDARY_ADDR="127.0.0.1:8081" cargo +nightly bench --bench proof_server
+RUST_LOG="debug" RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable -C opt-level=3" PRIMARY_ADDR="127.0.0.1:8080" SECONDARY_ADDR="127.0.0.1:8081" cargo +nightly-2024-05-31 bench --bench proof_server
 ```
 
-This benchmark will spawn the two servers locally and make two requests in parallel to them. This generates both proofs
-at the same time in the same machine. In a production setting, the two prover servers will be in different machines, and
-the two proofs will be generated in parallel.
-To run the proofs serially instead, pass the `RUN_SERIAL=1` environment variable to the test. This report times that are
-closer to a production setting where each proof is generated in parallel by a different machine.
+This benchmark will spawn the two servers locally and make two requests in sequence to them. This generates both proofs
+in the same machine, one after the other. In a production setting, the two prover servers will be in different machines,
+and the two proofs would be generated in parallel. This returns times that are closer to a production setting, without
+any resource exhaustion when generating the proofs.
 
-It measures two main metrics for each proof:
+To run the proofs in parallel even though it's running in one single machine, pass the `RUN_PARALLEL=1` environment variable
+when running the benchmark. This is not recommended as the total reported time for generating both proofs at the same time
+in the same machine will be longer than a properly configured production setting where the proofs are generated by different
+machines.
+
+The benchmark returns two main metrics for each proof:
 
 - `e2e_proving_time`: Time taken to send both request to the Proof Server and generate both proofs.
 - `inclusion_proof`:
@@ -28,18 +33,10 @@ It measures two main metrics for each proof:
     - `proving_time`: Time taken to generate the epoch change proof.
     - `request_response_proof_size`: Size of the proof returned by the server.
 
+For our [production configuration](../run/overview.md), we currently get the following results:
+
 ```json
-{
-  e2e_proving_time: 107678,
-  inclusion_proof: {
-    proving_time: 107678,
-    request_response_proof_size: 20823443
-  },
-  epoch_change_proof: {
-    proving_time: 125169,
-    request_response_proof_size: 23088485
-  }
-}
+TODO FIXME
 ```
 
 > **Note**
@@ -49,8 +46,14 @@ It measures two main metrics for each proof:
 
 ## SNARK proofs
 
-To enable SNARK proving, just pass the environment variable `SNARK=1`:
+To enable SNARK proving, just pass the environment variable `SNARK=1` when running:
 
 ```bash
-RUN_SERIAL=1 SNARK=1 RUST_LOG="debug" RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable" PRIMARY_ADDR="127.0.0.1:8080" SECONDARY_ADDR="127.0.0.1:8081" cargo +nightly bench --bench proof_server
+SNARK=1 RUST_LOG="debug" RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable -C opt-level=3" PRIMARY_ADDR="127.0.0.1:8080" SECONDARY_ADDR="127.0.0.1:8081" cargo +nightly-2024-05-31 bench --bench proof_server
+```
+
+For our [production configuration](../run/overview.md), we currently get the following results:
+
+```json
+TODO FIXME
 ```

aptos/docs/src/benchmark/on_chain.md

@@ -3,10 +3,11 @@
 Our Light Client is able to produce SNARK proofs that can be verified on-chain. This section will cover how to run the
 benchmarks for the on-chain verification.
 
-To be able to execute such tests our repository contains a project called `solidity` is based
+To be able to execute such tests the repository contains a project called `solidity` that is based
 off [Foundry](https://github.com/foundry-rs/foundry) which demonstrates the Solidity verification using so-called
 fixtures (JSON files) containing the proof data (proof itself, public values and verification key) required for running
-the verification for both epoch-change and inclusion programs.
+the verification for both epoch-change and inclusion programs. These fixtures are generated from a SNARK proof generated
+by the proof servers, but currently the fixtures generated are meant for simple testing only.
 
 The contracts used for testing can be found in the [sphinx-contracts](https://github.com/lurk-lab/sphinx-contracts)
 repository which is used as a dependency.
@@ -59,7 +60,7 @@ export the fixture file to the relevant place (`solidity/contracts/src/plonk_fix
 To run the `fixture-generator` for the inclusion program, execute the following command:
 
 ```bash
-RUST_LOG=info RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable" SHARD_SIZE=4194304 SHARD_BATCH_SIZE=0 cargo +nightly run --release --features aptos --bin generate-fixture -- --program inclusion
+RUST_LOG=info RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable -C opt-level=3" SHARD_SIZE=4194304 SHARD_BATCH_SIZE=0 cargo +nightly-2024-05-31 run --release --features aptos --bin generate-fixture -- --program inclusion
 ```
 
 > **Tips**
@@ -69,7 +70,7 @@ RUST_LOG=info RUSTFLAGS="-C target-cpu=native --cfg tokio_unstable" SHARD_SIZE=4
 > **Note**
 >
 > You might be encountering issue with updating `sphinx-contracts` Foundry dependency, in this case try manually
-> specifying accessing the submodule via SSH
+> specifying accessing the submodule via SSH like this:
 > ```
 > git config submodule.aptos/solidity/contracts/lib/sphinx-contracts.url git@github.com:lurk-lab/sphinx-contracts
-> ```
+> ```

aptos/docs/src/benchmark/overview.md

@@ -1,9 +1,10 @@
 # Benchmark proving time
 
-There are two types of benchmarks that you can run to get insight on the proving time necessary for the proof server to
-generate a proof. The first one is the proving benchmark, which is meant to measure the time it takes to generate a
-proof for a given circuit. The second one is the end-to-end benchmark, which is meant to measure the time it takes to
-generate a proof in the context of a deployed Light Client with the worst case scenario happening.
+There are two types of benchmarks that can be used to get insight on the proving time necessary for each kind of proof
+generated by the proof server. The first type will generate STARK core proofs, and represents the time it takes to
+generate and prove execution of one of the programs. The second type will generate a SNARK proof that can be verified
+on-chain, and represents the end-to-end time it takes to generate a proof that can be verified directly on-chain.
+Due to the SNARK compression, the SNARK proofs take longer to generate and require more resources.
 
-Before covering how to run each benchmark we will cover the different configurations that exist for the prover and how
-they should be set.
+The worst case latency (described [here](../design/edge_cases.md)) can be evaluated by running the end-to-end benchmark
+for each of the two proofs, and looking at the maximum of the time it took to genereate each proof.

aptos/docs/src/benchmark/proof.md

@@ -71,7 +71,7 @@ Enter benchmark name: e2e
 Run the following command:
 
 ```shell
-cargo +nightly bench --features aptos --bench execute -- <benchmark_name>
+cargo +nightly-2024-05-31 bench --features aptos --bench execute -- <benchmark_name>
 ```
 
 ## Interpreting the results
@@ -88,6 +88,7 @@ following:
 This value can be found on the following line:
 
 ```shell
+TODO FIXME
 INFO summary: cycles=63736, e2e=2506, khz=25.43, proofSize=2.66 MiB
 ```
 
@@ -99,6 +100,7 @@ CPU in kHz, and the size of the proof generated.
 In the output, you will find a section that looks like this:
 
 ```shell
+TODO FIXME
 DEBUG ┌╴read_inputs    
 DEBUG └╴9,553 cycles    
 DEBUG ┌╴verify_merkle_proof    
@@ -113,6 +115,7 @@ The proving time is an output at the end of a benchmark in the shape of the foll
 milliseconds:
 
 ```json
+TODO FIXME
 {
   ratchet_proving_time: 100000,
   merkle_proving_time: 100000
@@ -126,6 +129,7 @@ crate. They will output the same logs as the benchmarks, only the time necessary
 to generate a proof will change shape:
 
 ```shell
+TODO FIXME
 Starting generation of Merkle inclusion proof with 18 siblings...
 Proving locally
 Proving took 5.358508094s
@@ -137,7 +141,7 @@ To run the test efficiently, first install `nextest` following [its documentatio
 Ensure that you also have the previously described environment variables set, then run the following command:
 
 ```shell
-cargo +nightly nextest run --verbose --release --profile ci --features aptos --package aptos-lc --no-capture
+cargo +nightly-2024-05-31 nextest run --verbose --release --profile ci --features aptos --package aptos-lc --no-capture
 ```
 
 > **Note**
@@ -155,8 +159,3 @@ A short list of useful tests:
 - `test_execute_inclusion`: Executes the `epoch_change` program inside the zkVM but does not generate any proofs.
 - `test_prove_inclusion`: Generates and verifies a STARK proof of the `epoch_change` program.
 - `test_snark_inclusion`: Generates and verifies a SNARK proof of the `epoch_change` program.
-
-> **Note**
->
-> Any tests that generates SNARKs requires proper artifacts to be generated according to
-> the [instructions](./configuration.md).

aptos/docs/src/components/aptos_pfn.md

@@ -11,7 +11,7 @@ consensus layer, such as block header signatures.
 
 To make up for that, we forked the repository into our
 own [`lurk-lab/aptos-core`](https://github.com/lurk-lab/aptos-core). This forked repository should be the reference for
-the Aptos Full Node until the core developers of the Aptos protocol have made the necessary update.
+the Aptos Full Node until the core developers of the Aptos protocol have made the necessary updates.
 
 ## RPC endpoints
 
@@ -86,4 +86,4 @@ The only updates made to the Aptos Full Node on our forks are meant to expose tw
 
 - **ValidatorVerifier** *object*
 
-  Committee in charge of block header signature when the `LedgerInfoWithSignatures` was produced.
+  Committee in charge of block header signature when the `LedgerInfoWithSignatures` was produced.

aptos/docs/src/components/client.md

@@ -1,18 +1,24 @@
 # Client
 
 The client is the coordinator of the Light Client. It is responsible for orchestrating the communication between the
-Proof Server and the Aptos Full Node. In our current implementation it also serves as a drop-in replacement for what
-would be a verifier deployed on a destination chain.
+Proof Server and the Aptos Full Node. In our current example implementation it can also serve as a drop-in replacement
+for what an on-chain verifier would be responsible for.
 
-The client lifecycle can be divided in two phases:
+The client also demonstrates how to request data from our Aptos PFN endpoints, how to forward it to the proof servers
+using the simple binary RPC protocol, example and how to parse the received responses from the server. See
+[the source](https://github.com/lurk-lab/zk-light-clients/blob/dev/aptos/proof-server/src/bin/client.rs)
+for more details.
 
-- **Initialization**: In this phase, the client fetches the initial data from the Aptos node and
-  generates the initial state for itself and the verifier.
-- **Main Loop**: In this phase, the client listens for new data from the Aptos node and generates
-  proofs for the verifier to verify.
+The client has two phases:
+
+- **Initialization**: The client fetches the initial data from the Aptos node and generates the initial state for
+  itself and the verifier.
+- **Main Loop**: The client listens for new data from the Aptos node and generates proofs for the verifier to verify.
+  This includes new proofs for epoch changes.
 
 The current implementation of the client is specifically designed to cover the worst case scenario of having to handle
 the proofs generation in parallel. This flow happens during initialization where we prove the latest epoch change on the
 Aptos network while producing an inclusion proof for a given account at the latest block.
 
-The client currently only requests and verifies STARK proofs. The proof servers have support for generating and verifying SNARK proofs, but the bundled simple client does not yet make use of this.
+The bundled example client currently only requests and verifies STARK proofs. The proof servers have support for generating
+and verifying SNARK proofs, but the example client does not yet make use of this.