Reorganisation of main branch (lurk-lab#42)

* Remove e2e contract and integrative components * Update README * Add Bn256/Grumpkin curves arithmetics * Move constants (JSON) files to 'src/blocks/poseidon' path * Add optimized Poseidon library * Add Zeromorph library * Stub for e2e integration testing * chore(doc): update README for main - Repository structure - Overview of the different feature branches * chore(doc): SPDX License identifier * chore(doc): comment Bn256/Grumpkin files * chore(doc): fixed solidity doc for Bn256/Grumpkin files * chore(doc): README for Grumpkin Bn256 * chore(doc): pasta solidity doc & README * chore(doc): new doc + fix - Fix NatSpec comment order over Pallas.sol and Vesta.sol - Added Solidity comments over PoseidonNeptuneU24Optimized.sol and Sponge.sol - Added README in poseidon folder * chore(doc): doc for all cryptographic blocks - Solidity doc for all cryptographic blocks file - README in src/blocks to explain each file and their content - Fixed typo in library name * chore(doc): doc for Utilities.sol * Skip execution of e2e integration testing on main branch * chore(doc): fix fmt * Requested changes and adjustments * ci: Fail e2e tests when PR base is `main` (lurk-lab#45) * Add Sponge library that supports optimized Poseidon * chore(doc): followed review comments * chore(doc): added NatSpec comments - NatSpec for implementation of Sponge over the Optimized Poseidon library. * chore(doc): fixed fmt --------- Co-authored-by: Thomas Chataigner <[email protected]> Co-authored-by: Samuel Burnham <[email protected]>
samuelburnham · Dec 15, 2023 · acb74cd · acb74cd
1 parent 9a67892
commit acb74cd
Show file tree

Hide file tree

Showing 49 changed files with 23,249 additions and 8,119 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,55 +1,13 @@
-name: Run tests
+name: Run unit tests
 
 on:
-  push:
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
   merge_group:
   workflow_dispatch:
 
 jobs:
-  integration-tests-e2e:
-    name: E2E verification
-    # Run on merge_group and workflow_dispatch only
-    if: (github.event_name != 'push' && github.event_name != 'pull_request')  || github.event.action == 'enqueued'
-    runs-on: [self-hosted]
-    env:
-      ANVIL_PRIVATE_KEY: ${{secrets.ANVIL_PRIVATE_KEY}}
-      ANVIL_URL: ${{secrets.ANVIL_RPC_URL}}
-    strategy:
-      fail-fast: true
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          submodules: recursive
-
-      - name: Install Foundry
-        uses: foundry-rs/foundry-toolchain@v1
-        with:
-          version: nightly
-
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: 3.8
-
-      - name: Deploy main contract
-        run: |
-          echo "CONTRACT_ADDRESS=$(forge script script/Deployment.s.sol:NovaVerifierDeployer --fork-url $ANVIL_URL --private-key $ANVIL_PRIVATE_KEY --broadcast --non-interactive | sed -n 's/.*Contract Address: //p' | tail -1)" >> $GITHUB_OUTPUT
-        id: deployment
-
-      - name: Load proof and public parameters
-        run: |
-          python loader.py pp-verifier-key.json pp-compressed-snark.json ${{steps.deployment.outputs.CONTRACT_ADDRESS}} $ANVIL_URL $ANVIL_PRIVATE_KEY
-
-      - name: Check proof verification status
-        run: |
-          [[ $(cast call ${{steps.deployment.outputs.CONTRACT_ADDRESS}} "verify(uint32,uint256[],uint256[],bool)(bool)" "3" "[1]" "[0]" "true" --private-key $ANVIL_PRIVATE_KEY --rpc-url $ANVIL_URL) == true ]] && exit 0 || exit 1
-
   unit-tests:
-    strategy:
-      fail-fast: true
-
     name: Unit Tests
     runs-on: [self-hosted]
     steps:
@@ -68,8 +26,8 @@ jobs:
 
       - name: Regenerate Contracts
         run: |
-          python src/blocks/poseidon/poseidon-contract-gen.py neptune-constants-U24-pallas.json PoseidonU24Pallas > src/blocks/poseidon/PoseidonNeptuneU24pallas.sol
-          python src/blocks/poseidon/poseidon-contract-gen.py neptune-constants-U24-vesta.json PoseidonU24Vesta > src/blocks/poseidon/PoseidonNeptuneU24vesta.sol
+          python src/blocks/poseidon/poseidon-contract-gen.py src/blocks/poseidon/neptune-constants-U24-pallas.json PoseidonU24Pallas > src/blocks/poseidon/PoseidonNeptuneU24pallas.sol
+          python src/blocks/poseidon/poseidon-contract-gen.py src/blocks/poseidon/neptune-constants-U24-vesta.json PoseidonU24Vesta > src/blocks/poseidon/PoseidonNeptuneU24vesta.sol
 
       - name: Run forge fmt on re-generated contracts
         run: |

diff --git a/.github/workflows/end2end.yml b/.github/workflows/end2end.yml
@@ -1,4 +1,5 @@
-# Run integration tests when a maintainer comments `!test` on a PR
+# Run integration tests when a maintainer comments `!test` on a PR to feature branch
+# Fails when base branch is `main`, as it doesn't support e2e tests
 name: End to end integration tests
 
 on:
@@ -11,9 +12,6 @@ env:
 
 jobs:
   integration-tests-e2e:
-    strategy:
-      fail-fast: true
-
     name: E2E verification
     runs-on: [self-hosted]
     if:
@@ -22,6 +20,16 @@ jobs:
       && contains(github.event.comment.body, '!test')
       && (github.event.comment.author_association == 'MEMBER' || github.event.comment.author_association == 'OWNER')
     steps:
+      - uses: xt0rted/pull-request-comment-branch@v2
+        id: comment-branch
+
+      - name: Exit if base branch is `main`
+        if: ${{ steps.comment-branch.outputs.base_ref == 'main' }}
+        run: |
+          echo "Cannot run end2end integration tests on PR targeting `main`"
+          exit 1
+        continue-on-error: false
+
       - uses: actions/checkout@v4
         with:
           submodules: recursive
@@ -62,4 +70,4 @@ jobs:
           body: |
             End-to-end `!test` action succeeded! :rocket:
 
-            https://github.com/lurk-lab/solidity-verifier/actions/runs/${{ github.run_id }}
+            https://github.com/lurk-lab/solidity-verifier/actions/runs/${{ github.run_id }}
diff --git a/README.md b/README.md
@@ -1,8 +1,11 @@
 # solidity-verifier
 
-This repository will eventually contain Solidity implementation of Nova proving system.
+This repository contains Solidity implementation of Nova-based proving system
 
-The idea is actually to gather required cryptographic building blocks (pasta curves, Poseidon, etc.), evaluate them and check that they work as expected via test vectors provided by "trusted" Rust implementations and finally come up with working Nova verifier that can be deployed to the Filecoin network.
+The idea is actually to gather required cryptographic building blocks (Pasta / Grumpkin curve operations, Poseidon, KeccakTranscript, Sumcheck protocol, etc.) in `main` branch, 
+evaluate them and check that they work as expected via test vectors provided by "trusted" reference Rust implementation ([Arecibo](https://github.com/lurk-lab/arecibo)).
+Since reference proving system is under active development, the original end-to-end verification flow is a subject of changes, that is why, full e2e contracts are located in various branches,
+depending on the Nova cryptographic feature. See [pasta](https://github.com/lurk-lab/solidity-verifier/tree/pasta), [grumpkin](https://github.com/lurk-lab/solidity-verifier/tree/grumpkin), [zeromorph](https://github.com/lurk-lab/solidity-verifier/tree/zeromorph), [gas-optimizing](https://github.com/lurk-lab/solidity-verifier/tree/gas-optimizing) branches for more details.
 
 # Commands to play with
 
@@ -11,7 +14,7 @@ To cleanup current build artifacts:
 forge clean
 ```
 
-To build contracts:
+To build:
 ```
 forge build
 ```
@@ -21,50 +24,75 @@ To run Solidity unit-tests:
 forge test --match-path test/* -vv
 ```
 
-To run Anvil node locally (with maximum gas-limit and code-size-limit):
+More details about Foundry tooling is [here](https://book.getfoundry.sh/).
+
+# Repository structure
 
 ```
-anvil --gas-limit 18446744073709551615 --code-size-limit 18446744073709551615
+├── lib
+|   └── forge-std       # Forge standard library for testing utilities.
+├── src
+|   ├── blocks          # Cryptographic building blocks shared between all our features.
+|   └── Utilities.sol   # Mostly Mathematical building blocks such as Field operations or Polynomial-related methods. 
+└── test                # Unit test for our contracts.
 ```
 
-To deploy the e2e verification contract to locally running Anvil node (`PRIVATE_KEY` can be obtained from output of running Anvil):
+# Features
 
-```
-forge script script/Deployment.s.sol:NovaVerifierDeployer --fork-url http://127.0.0.1:8545 --private-key <PRIVATE_KEY> --broadcast
-```
+This section aims to describe the main features currently being developed and outline their specificities. It has to be
+noted that each of these branches have dedicated e2e testing, documented in their respective README.
 
-To load proof and verifier-key into the blockchain (`CONTRACT_ADDRESS` can be obtained from the output of previous step):
+## Pasta
 
-```
-python loader.py pp-verifier-key.json pp-compressed-snark.json <CONTRACT_ADDRESS> http://127.0.0.1:8545 <PRIVATE_KEY>
-```
+[Feature branch: `pasta`](https://github.com/lurk-lab/solidity-verifier/tree/pasta)
 
-To run the verification logic:
+Orignal feature branch, implementing the [Nova](https://github.com/microsoft/Nova) Verifier over
+[Pallas/Vesta (Pasta) curve cycles](https://electriccoin.co/blog/the-pasta-curves-for-halo-2-and-beyond/). The reference Nova implementation over Pasta can be found over [the lurk-lab/Nova
+repository]( https://github.com/lurk-lab/Nova/tree/solidity-verifier-pp-spartan).
 
-```
-cast call <CONTRACT_ADDRESS> "verify(uint32,uint256[],uint256[])(bool)" "3" "[1]" "[0]" --private-key <PRIVATE_KEY> --rpc-url http://127.0.0.1:8545
-```
+Development is nearly finalized but there are some compatibility checks to be run between the latest version of [Arecibo](https://github.com/lurk-lab/arecibo)
+and our solidity verifier.
 
-More details about Foundry tooling is [here](https://book.getfoundry.sh/).
+## Grumpkin
 
-P.S.: This E2E integration testing flow is enforced by Github Actions with our cloud-based Anvil node. See `integration-tests-e2e` job description from `.github/workflows/test.yml` for more details.
+[Feature branch: `grumpkin`](https://github.com/lurk-lab/solidity-verifier/tree/grumpkin)
 
-# Solidity contracts generation
+Feature branch aiming to implement our Nova Verifier over BN254/Grumpkin curve cycle instead of Pasta, to keep up with the
+development on the Rust implementation side. As for Pasta, the reference implementation can be found over [the lurk-lab/Nova
+repository]( https://github.com/lurk-lab/Nova/tree/solidity-verifier-pp-spartan).
 
-Some contracts in this repository have been generated with a help of correspondent Python scripts.
+Development is nearly finalized but there are some compatibility checks to be run between the latest version of [Arecibo](https://github.com/lurk-lab/arecibo)
+and our solidity verifier.
 
-To re-generate Poseidon contracts (for Pallas and Vesta curves) compatible to Neptune and "sharpened" for usage in Nova:
+## Zeromorph
 
-```
-python src/poseidon/poseidon-contract-gen.py neptune-constants-U24-pallas.json PoseidonU24Pallas > src/poseidon/PoseidonNeptuneU24pallas.sol
-python src/poseidon/poseidon-contract-gen.py neptune-constants-U24-vesta.json PoseidonU24Vesta > src/poseidon/PoseidonNeptuneU24vesta.sol
-```
+[Feature branch: `zeromorph`](https://github.com/lurk-lab/solidity-verifier/tree/zeromorph)
+
+The goal is to take into account the [Zeromorph](https://eprint.iacr.org/2023/917.pdf) feature done in Arecibo. Zeromorph
+impacts how we generate prover randomness at proving time, and allows us to have a new (and faster) Polynomial Commitment
+Scheme (PCS). The reference implementation for the Zeromorph feature can be found in [the Arecibo repository](https://github.com/lurk-lab/arecibo/tree/solidity-verifier-zeromorph ).
+
+The branch needs to integrate the [lastest updates pushed over Arecibo](https://github.com/lurk-lab/arecibo/pull/145) and will
+most likely need some development in Assembly to properly work.
+
+## Gas Optimization
+
+[Feature branch: `gas-optimizing`](https://github.com/lurk-lab/solidity-verifier/tree/gas-optimizing)
+
+This last branch contains development in [Assembly](https://docs.soliditylang.org/en/latest/assembly.html), leveraging 
+[Yul](https://docs.soliditylang.org/en/latest/yul.html). This development will allow optimization on gas consumption, readying
+our contracts for production. Based on the [Grumpkin feature branch](https://github.com/lurk-lab/solidity-verifier/tree/grumpkin),
+it should aim to implement a Grumpkin contract in Yul.
+
+The verification steps 1 and 2 have been implemented but the rest of the steps need to be developed.
+
+# Solidity contracts generation
+
+Poseidon contracts in this repository have been generated with a help of correspondent Python scripts.
 
-To re-generate contract-helper for correspondent step of Nova verification:
+To re-generate them (for Pallas and Vesta curves) compatible to Neptune and "sharpened" for usage in Nova:
 
 ```
-python src/verifier/step1/step1-data-contract-gen.py compressed-snark.json > src/verifier/step1/Step1Data.sol
-python src/verifier/step2/step2-data-contract-gen.py verifier-key.json compressed-snark.json > src/verifier/step2/Step2Data.sol
-python src/verifier/step3/step3-data-contract-gen.py verifier-key.json compressed-snark.json > src/verifier/step3/Step3Data.sol
-python src/verifier/step4/sumcheck-data-contract-gen.py verifier-key.json compressed-snark.json > src/verifier/step4/SumcheckData.sol
+python src/blocks/poseidon/poseidon-contract-gen.py src/blocks/poseidon/neptune-constants-U24-pallas.json PoseidonU24Pallas > src/blocks/poseidon/PoseidonNeptuneU24pallas.sol
+python src/blocks/poseidon/poseidon-contract-gen.py src/blocks/poseidon/neptune-constants-U24-vesta.json PoseidonU24Vesta > src/blocks/poseidon/PoseidonNeptuneU24vesta.sol
 ```