diff --git a/.github/actions/codecov-shared/action.yml b/.github/actions/codecov-shared/action.yml new file mode 100644 index 00000000000..886136488f6 --- /dev/null +++ b/.github/actions/codecov-shared/action.yml @@ -0,0 +1,31 @@ +name: "Shared Codecov reporting steps" +description: "Shared Codecov reporting steps" +inputs: + token: + description: "Codecov token" + required: true + files: + description: "Files to upload to Codecov" + required: false + default: "./target/coverage/lcov.info" + flags: + description: "Flags to pass to Codecov" + required: false + default: "" + name: + description: "The report name" + required: false + default: "proof-systems" +runs: + using: "composite" + steps: + - name: Upload coverage reports to Codecov + uses: codecov/codecov-action@v4 + with: + token: ${{ inputs.token }} + files: ${{ inputs.files }} + flags: ${{ inputs.flags }} + name: ${{ inputs.name }} + verbose: true + handle_no_reports_found: true + fail_ci_if_error: false diff --git a/.github/actions/coverage-summary-shared/action.yml b/.github/actions/coverage-summary-shared/action.yml new file mode 100644 index 00000000000..fd61cd647d5 --- /dev/null +++ b/.github/actions/coverage-summary-shared/action.yml @@ -0,0 +1,32 @@ +name: "Shared code coverage summary" +description: "Shared code coverage summary" +inputs: + html_file: + description: "HTML file with the coverage report" + required: false + default: "target/coverage/index.html" + shell: + description: "Shell to use" + required: false + default: "bash" +runs: + using: "composite" + steps: + - name: Add test coverage summary + run: | + echo "### Test coverage summary" >> $GITHUB_STEP_SUMMARY + # Define the HTML file + html_file="${{ inputs.html_file }}" + # Extract data for Lines, Functions, and Branches using `sed` + lines=$(sed -n '/heading">Lines/{n;n;s/.*]*>\(.*%\)<\/abbr>.*/\1/p;}' "$html_file") + functions=$(sed -n '/heading">Functions/{n;n;s/.*]*>\(.*%\)<\/abbr>.*/\1/p;}' "$html_file") + branches=$(sed -n '/heading">Branches/{n;n;s/.*]*>\(.*%\)<\/abbr>.*/\1/p;}' "$html_file") + # Compose Markdown summary table + echo "" >> $GITHUB_STEP_SUMMARY + echo "| Metric | Coverage |" >> $GITHUB_STEP_SUMMARY + echo "|-----------|----------|" >> $GITHUB_STEP_SUMMARY + echo "| Lines | $lines |" >> $GITHUB_STEP_SUMMARY + echo "| Functions | $functions |" >> $GITHUB_STEP_SUMMARY + echo "| Branches | $branches |" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + shell: ${{ inputs.shell }} diff --git a/.github/actions/ocaml-shared/action.yml b/.github/actions/ocaml-shared/action.yml new file mode 100644 index 00000000000..0ca66d56baf --- /dev/null +++ b/.github/actions/ocaml-shared/action.yml @@ -0,0 +1,15 @@ +name: "Shared OCaml setting up steps" +description: "Shared OCaml setting up steps" +inputs: + ocaml_version: + description: "OCaml version" + required: true +runs: + using: "composite" + steps: + - name: Setup OCaml ${{ inputs.ocaml_version }} + uses: ocaml/setup-ocaml@v3 + with: + ocaml-compiler: ${{ inputs.ocaml_version }} + # https://github.com/ocaml/setup-ocaml/issues/211#issuecomment-1058882386 + # disable-cache: true diff --git a/.github/actions/toolchain-shared/action.yml b/.github/actions/toolchain-shared/action.yml new file mode 100644 index 00000000000..5757d14c881 --- /dev/null +++ b/.github/actions/toolchain-shared/action.yml @@ -0,0 +1,26 @@ +name: "Shared Rust toolchain setting up steps" +description: "Shared Rust toolchain setting up steps" +inputs: + rust_toolchain_version: + description: "Rust toolchain version" + required: true + shell: + description: "Shell to use" + required: false + default: "bash" +runs: + using: "composite" + steps: + # As action-rs does not seem to be maintained anymore, building from + # scratch the environment using rustup + - name: Setup Rust toolchain ${{ inputs.rust_toolchain_version }} + run: | + curl --proto '=https' --tlsv1.2 -sSf -o rustup-init \ + https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-gnu/rustup-init + chmod +x ./rustup-init + ./rustup-init -y --default-toolchain "${{ inputs.rust_toolchain_version }}" --profile default + rm ./rustup-init + echo "$HOME/.cargo/bin" >> $GITHUB_PATH + # overwriting default rust-toolchain + echo ${{ inputs.rust_toolchain_version }} > rust-toolchain + shell: ${{ inputs.shell }} diff --git a/.github/workflows/benches.yml b/.github/workflows/benches.yml index 7fd1fe8e2ee..24924d043dd 100644 --- a/.github/workflows/benches.yml +++ b/.github/workflows/benches.yml @@ -9,47 +9,37 @@ env: OCAML_VERSION: "4.14.0" RUST_TOOLCHAIN_VERSION: "1.71" - jobs: bench: runs-on: ubuntu-latest name: Run benchmarks if: github.event.label.name == 'benchmark' steps: - - name: Checkout PR - uses: actions/checkout@v4.1.1 + - name: Checkout repository + uses: actions/checkout@v4 + with: + submodules: recursive - # as action-rs does not seem to be maintained anymore, building from - # scratch the environment using rustup - - name: Setup Rust toolchain $RUST_TOOLCHAIN_VERSION - run: - | - curl --proto '=https' --tlsv1.2 -sSf -o rustup-init \ - https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-gnu/rustup-init - chmod +x ./rustup-init - ./rustup-init -y --default-toolchain "$RUST_TOOLCHAIN_VERSION" --profile default - rm ./rustup-init - echo "$HOME/.cargo/bin" >> $GITHUB_PATH - # overwriting default rust-toolchain - echo $RUST_TOOLCHAIN_VERSION > rust-toolchain + - name: Use shared Rust toolchain setting up steps + uses: ./.github/actions/toolchain-shared + with: + rust_toolchain_version: ${{ env.RUST_TOOLCHAIN_VERSION }} - name: Install dependencies run: | set -x - cargo install cargo-criterion # criterion + cargo install cargo-criterion - - name: Setup OCaml ${{ env.OCAML_VERSION }} - uses: ocaml/setup-ocaml@v2 + - name: Use shared OCaml setting up steps + uses: ./.github/actions/ocaml-shared with: - ocaml-compiler: ${{ env.OCAML_VERSION }} - # https://github.com/ocaml/setup-ocaml/issues/211#issuecomment-1058882386 - # disable-cache: true + ocaml_version: ${{ env.OCAML_VERSION }} -# - name: Run iai bench -# run: | -# set -x -# cargo bench -p kimchi --bench proof_iai > iai_bench -# cat iai_bench + # - name: Run iai bench + # run: | + # set -x + # cargo bench -p kimchi --bench proof_iai > iai_bench + # cat iai_bench - name: Run criterion bench run: | @@ -59,7 +49,7 @@ jobs: cat criterion_bench - name: Write result in PR - uses: actions/github-script@v5 + uses: actions/github-script@v7 with: script: | const fs = require('fs'); diff --git a/.github/workflows/ci-nightly.yml b/.github/workflows/ci-nightly.yml new file mode 100644 index 00000000000..55b4106aabb --- /dev/null +++ b/.github/workflows/ci-nightly.yml @@ -0,0 +1,72 @@ +# +# This workflow is triggered by scheduler or on-demand to run all the tests with the code coverage enabled and using the self-hosted GitHub runner. +# Test coverage report is attached to the current job execution results in a form of Zip archive. +# + +name: Nightly tests with the code coverage + +on: + schedule: + - cron: "0 0 * * *" # every day at midnight + workflow_dispatch: {} + +env: + # https://doc.rust-lang.org/cargo/reference/profiles.html#release + RUSTFLAGS: -Coverflow-checks=y -Cdebug-assertions=y + # https://doc.rust-lang.org/cargo/reference/profiles.html#incremental + CARGO_INCREMENTAL: 1 + # https://nexte.st/book/pre-built-binaries.html#using-nextest-in-github-actions + CARGO_TERM_COLOR: always + # 30 MB of stack for Keccak tests + RUST_MIN_STACK: 31457280 + +jobs: + run_tests: + name: Run all tests with the code coverage + runs-on: ${{ matrix.os }} + strategy: + matrix: + rust_toolchain_version: ["1.74"] + # FIXME: currently not available for 5.0.0. + # It might be related to boxroot dependency, and we would need to bump + # up the ocaml-rs dependency + ocaml_version: ["4.14"] + os: ["hetzner-1"] + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Use shared Rust toolchain setting up steps + uses: ./.github/actions/toolchain-shared + with: + rust_toolchain_version: ${{ matrix.rust_toolchain_version }} + + - name: Use shared OCaml setting up steps + uses: ./.github/actions/ocaml-shared + with: + ocaml_version: ${{ matrix.ocaml_version }} + + - name: Install test dependencies + run: | + make install-test-deps + + - name: Run all tests with the code coverage + run: | + eval $(opam env) + make clean + make nextest-all-with-coverage + + - name: Use shared code coverage summary + uses: ./.github/actions/coverage-summary-shared + + - name: Upload the HTML test coverage report + uses: actions/upload-artifact@v4 + continue-on-error: true + if: always() + with: + if-no-files-found: ignore + name: test-coverage-html-report-${{ matrix.rust_toolchain_version }}-${{ matrix.os }} + path: target/coverage/ + retention-days: 30 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000000..788c258a34e --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,176 @@ +name: CI + +on: + pull_request: + +env: + # https://doc.rust-lang.org/cargo/reference/profiles.html#release + RUSTFLAGS: -Coverflow-checks=y -Cdebug-assertions=y + # https://doc.rust-lang.org/cargo/reference/profiles.html#incremental + CARGO_INCREMENTAL: 1 + # https://nexte.st/book/pre-built-binaries.html#using-nextest-in-github-actions + CARGO_TERM_COLOR: always + # 30 MB of stack for Keccak tests + RUST_MIN_STACK: 31457280 + +jobs: + run_mdbook: + name: Building MDBook + runs-on: ubuntu-latest + strategy: + matrix: + rust_toolchain_version: ["1.72"] + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Use shared Rust toolchain setting up steps + uses: ./.github/actions/toolchain-shared + with: + rust_toolchain_version: ${{ matrix.rust_toolchain_version }} + + - name: Build the mdbook + run: | + cd book + make deps + make build + + run_formatting: + name: Formatting + runs-on: ubuntu-latest + strategy: + matrix: + rust_toolchain_version: ["nightly"] + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Use shared Rust toolchain setting up steps + uses: ./.github/actions/toolchain-shared + with: + rust_toolchain_version: ${{ matrix.rust_toolchain_version }} + + - name: Run cargo fmt + run: | + make format + + run_checks: + name: Run checks and tests + # We run only one of the matrix options on the toffee `hetzner-1` self-hosted GitHub runner. + # Only in this configuration we enable tests with the code coverage data gathering. + runs-on: ${{ matrix.rust_toolchain_version == '1.74' && 'hetzner-1' || 'ubuntu-latest' }} + env: + RUST_TOOLCHAIN_COVERAGE_VERSION: "1.74" + strategy: + matrix: + rust_toolchain_version: ["1.71", "1.72", "1.73", "1.74"] + # FIXME: currently not available for 5.0.0. + # It might be related to boxroot dependency, and we would need to bump + # up the ocaml-rs dependency + ocaml_version: ["4.14"] + os: ["ubuntu-latest"] + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Use shared Rust toolchain setting up steps + uses: ./.github/actions/toolchain-shared + with: + rust_toolchain_version: ${{ matrix.rust_toolchain_version }} + + - name: Use shared OCaml setting up steps + uses: ./.github/actions/ocaml-shared + with: + ocaml_version: ${{ matrix.ocaml_version }} + + - name: Install markdownlint + run: | + # FIXME: 0.39.0 makes the CI fail + npm install -g markdownlint-cli@0.38.0 + + # + # Doc & Spec + # + + - name: Install cargo-spec for specifications + run: | + eval $(opam env) + cargo install --locked cargo-spec + + - name: Build the kimchi specification + run: | + cd book/specifications/kimchi + make build + + - name: Build the polynomial commitment specification + run: | + cd book/specifications/poly-commitment + make build + + - name: Check that up-to-date specification is checked in + run: | + git diff --exit-code ":(exclude)rust-toolchain" + + - name: Build cargo docs + run: | + eval $(opam env) + RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps + + # + # Coding guidelines + # + + - name: Lint (clippy) + run: | + eval $(opam env) + make lint + + # + # Build + # + + - name: Ensure that everything builds + run: | + eval $(opam env) + make + + # + # Tests + # + + - name: Install test dependencies + run: | + make install-test-deps + + - name: Run non-heavy tests without the code coverage + if: ${{ matrix.rust_toolchain_version != env.RUST_TOOLCHAIN_COVERAGE_VERSION }} + run: | + eval $(opam env) + make nextest + + - name: Run non-heavy tests with the code coverage + if: ${{ matrix.rust_toolchain_version == env.RUST_TOOLCHAIN_COVERAGE_VERSION }} + run: | + eval $(opam env) + make nextest-with-coverage + + - name: Use shared code coverage summary + if: ${{ matrix.rust_toolchain_version == env.RUST_TOOLCHAIN_COVERAGE_VERSION }} + uses: ./.github/actions/coverage-summary-shared + + - name: Use shared Codecov reporting steps + if: ${{ matrix.rust_toolchain_version == env.RUST_TOOLCHAIN_COVERAGE_VERSION }} + uses: ./.github/actions/codecov-shared + with: + token: ${{ secrets.CODECOV_TOKEN }} + + - name: Doc tests + run: | + eval $(opam env) + cargo test --all-features --release --doc diff --git a/.github/workflows/coverage.yml.disabled b/.github/workflows/coverage.yml.disabled deleted file mode 100644 index 837124ea24d..00000000000 --- a/.github/workflows/coverage.yml.disabled +++ /dev/null @@ -1,44 +0,0 @@ -name: Coverage - -on: - workflow_dispatch: - pull_request: - branches: - - master - push: - branches: - - master - -jobs: - - coverage: - name: Coverage (+nightly) - # The large timeout is to accommodate nightly builds - timeout-minutes: 60 - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4.1.1 - with: - persist-credentials: false - - - uses: actions-rs/toolchain@v1.0.7 - with: - toolchain: nightly - override: true - profile: minimal - components: llvm-tools-preview - - - name: Install cargo-llvm-cov cargo command - run: cargo install cargo-llvm-cov - - - name: Setup OCaml (because of ocaml-gen) - run: sudo apt update && sudo apt install ocaml - - - name: Generate code coverage - env: - ZEBRA_SKIP_NETWORK_TESTS: 1 - CARGO_INCREMENTAL: 0 - run: cargo llvm-cov --lcov > lcov.info - - - name: Upload coverage report to Codecov - uses: codecov/codecov-action@v2.0.3 diff --git a/.github/workflows/gh-page.yml b/.github/workflows/gh-page.yml index b4966ffc1d4..6e9b3386b91 100644 --- a/.github/workflows/gh-page.yml +++ b/.github/workflows/gh-page.yml @@ -16,29 +16,20 @@ jobs: runs-on: ubuntu-latest steps: - - name: Checkout Repository - uses: actions/checkout@v4.1.1 + - name: Checkout repository + uses: actions/checkout@v4 + with: + submodules: recursive - # as action-rs does not seem to be maintained anymore, building from - # scratch the environment using rustup - - name: Setup nightly Rust toolchain - run: - | - curl --proto '=https' --tlsv1.2 -sSf -o rustup-init \ - https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-gnu/rustup-init - chmod +x ./rustup-init - ./rustup-init -y --default-toolchain "$RUST_TOOLCHAIN_VERSION" --profile default - rm ./rustup-init - echo "$HOME/.cargo/bin" >> $GITHUB_PATH - # overwriting default rust-toolchain - echo $RUST_TOOLCHAIN_VERSION > rust-toolchain + - name: Use shared Rust toolchain setting up steps + uses: ./.github/actions/toolchain-shared + with: + rust_toolchain_version: ${{ env.RUST_TOOLCHAIN_VERSION }} - - name: Setup OCaml ${{ env.OCAML_VERSION }} - uses: ocaml/setup-ocaml@v2 + - name: Use shared OCaml setting up steps + uses: ./.github/actions/ocaml-shared with: - ocaml-compiler: ${{ env.OCAML_VERSION }} - # https://github.com/ocaml/setup-ocaml/issues/211#issuecomment-1058882386 - # disable-cache: true + ocaml_version: ${{ env.OCAML_VERSION }} # This must be the same as in the section "Generate rustdoc locally" in the README.md - name: Build Rust Documentation diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml deleted file mode 100644 index 04de561ae8f..00000000000 --- a/.github/workflows/rust.yml +++ /dev/null @@ -1,201 +0,0 @@ -name: CI - -on: - pull_request: - -env: - # https://doc.rust-lang.org/cargo/reference/profiles.html#release - RUSTFLAGS: -Coverflow-checks=y -Cdebug-assertions=y - # https://doc.rust-lang.org/cargo/reference/profiles.html#incremental - CARGO_INCREMENTAL: 1 - # https://nexte.st/book/pre-built-binaries.html#using-nextest-in-github-actions - CARGO_TERM_COLOR: always - RUST_MIN_STACK: 31457280 - # 30 MB of stack for Keccak tests - -jobs: - run_mdbook: - name: Building MDBook - runs-on: ubuntu-latest - strategy: - matrix: - rust_toolchain_version: ["1.72"] - steps: - - name: Checkout PR - uses: actions/checkout@v4.1.1 - - - name: Setup Rust toolchain ${{ matrix.rust_toolchain_version }} - run: - | - curl --proto '=https' --tlsv1.2 -sSf -o rustup-init \ - https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-gnu/rustup-init - chmod +x ./rustup-init - ./rustup-init -y --default-toolchain "${{ matrix.rust_toolchain_version }}" --profile default - rm ./rustup-init - echo "$HOME/.cargo/bin" >> $GITHUB_PATH - # overwriting default rust-toolchain - echo ${{ matrix.rust_toolchain_version }} > rust-toolchain - - - name: Build the mdbook - run: | - cd book - make deps - make build - - run_formatting: - name: Formatting - runs-on: ubuntu-latest - strategy: - matrix: - rust_toolchain_version: ["nightly"] - steps: - - name: Checkout PR - uses: actions/checkout@v4.1.1 - - - name: Setup Rust toolchain ${{ matrix.rust_toolchain_version }} - run: - | - curl --proto '=https' --tlsv1.2 -sSf -o rustup-init \ - https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-gnu/rustup-init - chmod +x ./rustup-init - ./rustup-init -y --default-toolchain "${{ matrix.rust_toolchain_version }}" --profile default - rm ./rustup-init - echo "$HOME/.cargo/bin" >> $GITHUB_PATH - # overwriting default rust-toolchain - echo ${{ matrix.rust_toolchain_version }} > rust-toolchain - - - name: Run cargo fmt - run: | - cargo fmt -- --check - - # We run only one of the matrix options on the toffee hetzner-1, - # and also only in this configuration we enable heavy tests. - run-checks-setup: - runs-on: ubuntu-latest - outputs: - runners: '{"1.71":"ubuntu-latest", "1.72": "ubuntu-latest", "1.73": "ubuntu-latest", "1.74": "hetzner-1"}' - steps: - - run: echo no-op - - - run_checks: - needs: [run-checks-setup] - - strategy: - matrix: - # FIXME: use the latest version of cargo nextest when we get rid of 1.71 - # and 1.72 - rust_toolchain_version: ["1.71", "1.72", "1.73", "1.74"] - # FIXME: currently not available for 5.0.0. - # It might be related to boxroot dependency, and we would need to bump - # up the ocaml-rs dependency - ocaml_version: ["4.14"] - - # See run-checks-setup - runs-on: ${{ fromJSON(needs.run-checks-setup.outputs.runners)[matrix.rust_toolchain_version] }} - - name: Run some basic checks and tests - steps: - - name: Checkout PR - uses: actions/checkout@v4.1.1 - - # as action-rs does not seem to be maintained anymore, building from - # scratch the environment using rustup - - name: Setup Rust toolchain ${{ matrix.rust_toolchain_version }} - run: - | - curl --proto '=https' --tlsv1.2 -sSf -o rustup-init \ - https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-gnu/rustup-init - chmod +x ./rustup-init - ./rustup-init -y --default-toolchain "${{ matrix.rust_toolchain_version }}" --profile default - rm ./rustup-init - echo "$HOME/.cargo/bin" >> $GITHUB_PATH - # overwriting default rust-toolchain - echo ${{ matrix.rust_toolchain_version }} > rust-toolchain - - - name: Setup OCaml ${{ matrix.ocaml_version }} - uses: ocaml/setup-ocaml@v2 - with: - ocaml-compiler: ${{ matrix.ocaml_version }} - # https://github.com/ocaml/setup-ocaml/issues/211#issuecomment-1058882386 - # disable-cache: true - - - name: Install markdownlint - run: | - # FIXME: 0.39.0 makes the CI fail - npm install -g markdownlint-cli@0.38.0 - - # - # Doc & Spec - # - - - name: Install cargo-spec for specifications - run: | - eval $(opam env) - cargo install --locked cargo-spec - - - name: Build the kimchi specification - run: | - cd book/specifications/kimchi - make build - - - name: Build the polynomial commitment specification - run: | - cd book/specifications/poly-commitment - make build - - - name: Check that up-to-date specification is checked in - run: | - git diff --exit-code ":(exclude)rust-toolchain" - - - name: Build cargo docs - run: | - eval $(opam env) - RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps - - # - # Coding guidelines - # - - - - name: Lint (clippy) - run: | - eval $(opam env) - cargo clippy --all-features --all-targets --tests -- -W clippy::all -D warnings - - # - # Build - # - - - name: Ensure that everything builds - run: | - eval $(opam env) - cargo build --release --all-targets --all-features - - # - # Tests - # - - # https://nexte.st/book/pre-built-binaries.html#using-nextest-in-github-actions - - name: Install nextest 0.9.67 - run: | - eval $(opam env) - # FIXME: update to 0.9.68 when we get rid of 1.71 and 1.72. - cargo install cargo-nextest@=0.9.67 --locked - - - name: Run non-heavy tests - run: | - eval $(opam env) - cargo nextest run --all-features --release --profile ci -E "not test(heavy)" - - - name: Run heavy tests - if: ${{ matrix.rust_toolchain_version == '1.74' }} - run: | - eval $(opam env) - cargo nextest run --all-features --release --profile ci -E "test(heavy)" - - - - name: Doc tests - run: | - eval $(opam env) - cargo test --all-features --release --doc diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e9c4940c6a..3f47c5c106a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,9 +4,9 @@ Here's all you need to know to start contributing to kimchi. ## Navigating the project -* [The following video](https://www.youtube.com/watch?v=WUP54nqVedc) goes over the project organization. -* The [Mina book](https://o1-labs.github.io/proof-systems/) contains specifications, rust documentation, RFCs, and explainers on the different aspects of the system. -* The [Discussion page](https://github.com/o1-labs/proof-systems/discussions) can be used to start discussions or ask questions. +- [The following video](https://www.youtube.com/watch?v=WUP54nqVedc) goes over the project organization. +- The [Mina book](https://o1-labs.github.io/proof-systems/) contains specifications, rust documentation, RFCs, and explainers on the different aspects of the system. +- The [Discussion page](https://github.com/o1-labs/proof-systems/discussions) can be used to start discussions or ask questions. ## Finding a task @@ -14,63 +14,104 @@ We have a list of easy task to start contributing. [Start over there](https://gi ## Setting up the project -Run +Make sure you have the GNU `make` utility installed since we use it to streamline various tasks. +Windows users may need to use the `WSL` to run `make` commands. +For the complete list of `make` targets, please refer to the [Makefile](Makefile). -``` -git submodule init -git submodule update +After the repository being cloned, run: + +```shell +make setup ``` -to get the version of Optimism the zkVM has been developed for. +this will also synchronize the Git submodules to get the version of Optimism the zkVM has been developed for. ### Mac & Linux -* Follow these instructions to install OCaml: https://ocaml.org/docs/install.html -* Follow these instructions to install Rust: https://rustup.rs/ +- Follow these instructions to install OCaml: +- Follow these instructions to install Rust: ### Windows Development Windows development can be done using [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install). -* Install and open WSL -* Within WSL, install OCaml using your distro's package manager. For example: `apt install opam` -* Within WSL, navigate to the project directory and run `cargo test`. If there are no failures then everything is set up correctly. + +- Install and open WSL +- Within WSL, install OCaml using your distro's package manager. For example: `apt install opam` +- Within WSL, navigate to the project directory and run `cargo test`. If there are no failures then everything is set up correctly. ## Development -To run tests: -```bash -cargo test --all-features --release +To run all tests: + +### Setting up + +```shell +make install-test-deps +``` + +### Cargo test runner + +```shell +make test-all +``` + +### Nextest test runner + +```shell +make nextest-all ``` -Takes about 5-8 minutes on a MacBook Pro (2019, 8-Core Intel Core i9, 32GB RAM). Without `--release`, more than an hour. +We also provide the `make` targets to run tests with the code coverage reporting, for example: + +```shell +make test-all-with-coverage +``` + +You can also specify an extra CLI argument to `make` to pass it to the cargo or binary, for example: + +```shell +CARGO_EXTRA_ARGS="-p poly-commitment" make test-all-with-coverage +BIN_EXTRA_ARGS="-p poly-commitment" make nextest-all-with-coverage +``` + +Note: In example above we run tests for the `poly-commitment` package only. + +We build and run tests in `--release` mode, because otherwise tests execution can last for a long time. + +To check formatting: + +```shell +make format +``` To scan for lints: -```bash -cargo clippy --all-features --tests --all-targets -- -D warnings + +```shell +make lint ``` -Note: cargo can automatically fix some lints. To do so, add `--fix` to the above command (as the first parameter). +Note: cargo can automatically fix some lints. To do so, add `--fix` to the `CARGO_EXTRA_ARGS` variable and use it with the command above like this: -Finally, to check formatting: -```bash -cargo fmt +```shell +CARGO_EXTRA_ARGS="--fix" make lint ``` -These are enforced by GitHub PR checks, so be sure to have any errors produced by the above tools fixed before pushing the code to your pull request branch. Refer to `.github/workflows` for all PR checks. +Formatting and lints are enforced by GitHub PR checks, so please be sure to have any errors produced by the above tools fixed before pushing the code to your pull request branch. +Please refer to [CI](.github/workflows/ci.yml) workflow to see all PR checks. ## Branching policy Generally, proof-systems intends to be synchronized with the mina repository (see their [README-branching.md](https://github.com/MinaProtocol/mina/blob/develop/README-branching.md)), and so its branching policy is quite similar. However several important (some, temporary) distinctions exist: - `compatible`: - - Compatible with `rampup` in `mina`. - - Mina's `compatible`, similarly to mina's `master`, does not have `proof-systems`. + - Compatible with `rampup` in `mina`. + - Mina's `compatible`, similarly to mina's `master`, does not have `proof-systems`. - `berkley`: future hardfork release, will be going out to berkeley. - This is where hotfixes go. - `develop`: matches mina's `develop`, soft fork-compatibility. - Also used by `mina/o1js-main` and `o1js/main`. - `master`: future feature work development, containing breaking changes. Anything that does not need to be released alongside mina. - - Note that `mina`'s `master` does not depend on `proof-systems` at all. + - Note that `mina`'s `master` does not depend on `proof-systems` at all. - `izmir`: next hardfork release after berkeley. - In the future: - `master`/`develop` will reverse roles and become something like gitflow. diff --git a/Makefile b/Makefile new file mode 100644 index 00000000000..3543440992b --- /dev/null +++ b/Makefile @@ -0,0 +1,116 @@ +# Variables +COVERAGE_ENV = CARGO_INCREMENTAL=0 RUSTFLAGS='-Cinstrument-coverage' LLVM_PROFILE_FILE=$(shell pwd)/target/profraw/cargo-test-%p-%m.profraw +# FIXME: In latest 0.8.19+ -t CLI argument can accept comma separated list of custom output types, hence, no need in double invocation +GRCOV_CALL = grcov ./target/profraw --binary-path ./target/release/deps/ -s . --branch --ignore-not-existing --ignore "**/tests/**" + +# Default target +all: release + +setup: + @echo "" + @echo "Syncing the Git submodules." + @echo "" + git submodule sync + git submodule update --init --recursive + @echo "" + @echo "Git submodules synced." + @echo "" + +# Install test dependencies +# https://nexte.st/book/pre-built-binaries.html#using-nextest-in-github-actions +# FIXME: update to 0.9.68 when we get rid of 1.71 and 1.72. +# FIXME: latest 0.8.19+ requires rustc 1.74+ +install-test-deps: + @echo "" + @echo "Installing the test dependencies." + @echo "" + rustup component add llvm-tools-preview + cargo install cargo-nextest@=0.9.67 --locked + cargo install grcov@=0.8.13 --locked + @echo "" + @echo "Test dependencies installed." + @echo "" + +# Clean the project +clean: + cargo clean + +# Build the project +build: + cargo build --all-targets --all-features + +# Build the project in release mode +release: + cargo build --release --all-targets --all-features + +# Test the project with non-heavy tests and using native cargo test runner +test: + cargo test --all-features --release $(CARGO_EXTRA_ARGS) -- --nocapture --skip heavy $(BIN_EXTRA_ARGS) + +test-with-coverage: + $(COVERAGE_ENV) CARGO_EXTRA_ARGS="$(CARGO_EXTRA_ARGS)" BIN_EXTRA_ARGS="$(BIN_EXTRA_ARGS)" $(MAKE) test + $(MAKE) generate-test-coverage-report + +# Test the project with heavy tests and using native cargo test runner +test-heavy: + cargo test --all-features --release $(CARGO_EXTRA_ARGS) -- --nocapture heavy $(BIN_EXTRA_ARGS) + +test-heavy-with-coverage: + $(COVERAGE_ENV) CARGO_EXTRA_ARGS="$(CARGO_EXTRA_ARGS)" BIN_EXTRA_ARGS="$(BIN_EXTRA_ARGS)" $(MAKE) test-heavy + $(MAKE) generate-test-coverage-report + +# Test the project with all tests and using native cargo test runner +test-all: + cargo test --all-features --release $(CARGO_EXTRA_ARGS) -- --nocapture $(BIN_EXTRA_ARGS) + +test-all-with-coverage: + $(COVERAGE_ENV) CARGO_EXTRA_ARGS="$(CARGO_EXTRA_ARGS)" BIN_EXTRA_ARGS="$(BIN_EXTRA_ARGS)" $(MAKE) test-all + $(MAKE) generate-test-coverage-report + +# Test the project with non-heavy tests and using nextest test runner +nextest: + cargo nextest run --all-features --release --profile ci -E "not test(heavy)" $(BIN_EXTRA_ARGS) + +nextest-with-coverage: + $(COVERAGE_ENV) BIN_EXTRA_ARGS="$(BIN_EXTRA_ARGS)" $(MAKE) nextest + $(MAKE) generate-test-coverage-report + +# Test the project with heavy tests and using nextest test runner +nextest-heavy: + cargo nextest run --all-features --release --profile ci -E "test(heavy)" $(BIN_EXTRA_ARGS) + +nextest-heavy-with-coverage: + $(COVERAGE_ENV) BIN_EXTRA_ARGS="$(BIN_EXTRA_ARGS)" $(MAKE) nextest-heavy + $(MAKE) generate-test-coverage-report + +# Test the project with all tests and using nextest test runner +nextest-all: + cargo nextest run --all-features --release --profile ci $(BIN_EXTRA_ARGS) + +nextest-all-with-coverage: + $(COVERAGE_ENV) BIN_EXTRA_ARGS="$(BIN_EXTRA_ARGS)" $(MAKE) nextest-all + $(MAKE) generate-test-coverage-report + +# Format the code +format: + cargo fmt -- --check + +# Lint the code +lint: + cargo clippy --all-features --all-targets --tests $(CARGO_EXTRA_ARGS) -- -W clippy::all -D warnings + +generate-test-coverage-report: + @echo "" + @echo "Generating the test coverage report." + @echo "" + mkdir -p ./target/coverage + GRCOV_OUTPUT_TYPE=html GRCOV_OUTPUT_PATH=./target/coverage + $(eval GRCOV_HTML_CMD=$(GRCOV_CALL) -t html -o ./target/coverage) + $(GRCOV_HTML_CMD) + $(eval GRCOV_LCOV_CMD=$(GRCOV_CALL) -t lcov -o ./target/coverage/lcov.info) + $(GRCOV_LCOV_CMD) + @echo "" + @echo "The test coverage report is available at: ./target/coverage" + @echo "" + +.PHONY: all setup install-test-deps clean build release test test-with-coverage test-heavy test-heavy-with-coverage test-all test-all-with-coverage nextest nextest-with-coverage nextest-heavy nextest-heavy-with-coverage nextest-all nextest-all-with-coverage format lint generate-test-coverage-report diff --git a/README.md b/README.md index 8e11282e144..75a40fdd1ce 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ +# Kimchi + +[![codecov](https://codecov.io/gh/o1-labs/proof-systems/graph/badge.svg?token=pl6W1FDfV0)](https://codecov.io/gh/o1-labs/proof-systems) [![CI](https://github.com/o1-labs/proof-systems/actions/workflows/rust.yml/badge.svg)](https://github.com/o1-labs/proof-systems/actions/workflows/rust.yml) [![dependency status](https://deps.rs/repo/github/o1-labs/proof-systems/status.svg?style=flat-square)](https://deps.rs/repo/github/o1-labs/proof-systems) -# Kimchi - This repository contains **kimchi**, a general-purpose zero-knowledge proof system for proving the correct execution of programs. You can read more about this project on the [Kimchi book](https://o1-labs.github.io/proof-systems), or for a lighter introduction in this [blogpost](https://minaprotocol.com/blog/kimchi-the-latest-update-to-minas-proof-system). @@ -11,7 +12,7 @@ You can read more about this project on the [Kimchi book](https://o1-labs.github ## User Warning -This project comes as is. We provide no guarantee of stability or support, as the crates closely follow the needs of the [Mina]([https://](https://github.com/minaprotocol/mina)) project. +This project comes as is. We provide no guarantee of stability or support, as the crates closely follow the needs of the [Mina](<[https://](https://github.com/minaprotocol/mina)>) project. If you use this project in a production environment, it is your responsibility to perform a security audit to ensure that the software meets your requirements. @@ -19,7 +20,7 @@ If you use this project in a production environment, it is your responsibility t At the time of this writing: -**Proving time** +### Proving time | number of gates | seconds | | :-------------: | :-----: | @@ -27,14 +28,14 @@ At the time of this writing: | 2^15 | 3.3s | | 2^16 | 6.3s | -**Verification time** +### Verification time | number of gates | seconds | | :-------------: | :-----: | | 2^15 | 0.1s | | 2^16 | 0.1s | -**Proof size** +### Proof size | number of gates | bytes | | :-------------: | :---: | @@ -45,17 +46,17 @@ At the time of this writing: The project is organized in the following way: -* [book/](book/). The mina book, RFCs, and specifications. [Available here in HTML](https://o1-labs.github.io/proof-systems). -* [curves/](curves/). The elliptic curves we use (for now just the pasta curves). -* [groupmap/](groupmap/). Used to convert elliptic curve elements to field elements. -* [hasher/](hasher/). Interfaces for mina hashing. -* [kimchi/](kimchi/). Our proof system based on PLONK. -* [poly-commitment/](poly-commitment/). Polynomial commitment code. -* [poseidon/](poseidon/). Implementation of the poseidon hash function. -* [signer/](signer/). Interfaces for mina signature schemes. -* [tools/](tools/). Various tooling to help us work on kimchi. -* [turshi/](turshi/). A Cairo runner written in rust. -* [utils/](utils/). Collection of useful functions and traits. +- [book/](book/). The mina book, RFCs, and specifications. [Available here in HTML](https://o1-labs.github.io/proof-systems). +- [curves/](curves/). The elliptic curves we use (for now just the pasta curves). +- [groupmap/](groupmap/). Used to convert elliptic curve elements to field elements. +- [hasher/](hasher/). Interfaces for mina hashing. +- [kimchi/](kimchi/). Our proof system based on PLONK. +- [poly-commitment/](poly-commitment/). Polynomial commitment code. +- [poseidon/](poseidon/). Implementation of the poseidon hash function. +- [signer/](signer/). Interfaces for mina signature schemes. +- [tools/](tools/). Various tooling to help us work on kimchi. +- [turshi/](turshi/). A Cairo runner written in rust. +- [utils/](utils/). Collection of useful functions and traits. ## Contributing @@ -65,8 +66,10 @@ Check [CONTRIBUTING.md](CONTRIBUTING.md) if you are interested in contributing t An effort is made to have the documentation being self-contained, referring to the mina book for more details when necessary. You can build the rust documentation with + -``` + +```shell rustup install nightly RUSTDOCFLAGS="--enable-index-page -Zunstable-options" cargo +nightly doc --all --no-deps ``` @@ -76,12 +79,16 @@ You can visualize the documentation by opening the file `target/doc/index.html`. ## CI -The CI will build different targets. -- [Deploy Specifications & Docs to GitHub Pages](.github/workflows/gh-page.yml). - When CI passes on master, the documentation built from the rust code will be - available [here](https://o1-labs.github.io/proof-systems/rustdoc) and the book - will be available [here](https://o1-labs.github.io/proof-systems). + +- [CI](.github/workflows/ci.yml). + This workflow ensures that the entire project builds correctly, adheres to guidelines, and passes all necessary tests. +- [Nightly tests with the code coverage](.github/workflows/ci-nightly.yml). + This workflow runs all the tests per scheduler or on-demand, generates and attaches the code coverage report to the job's execution results. +- [Benchmarks](.github/workflows/benches.yml). + This workflow runs benchmarks when a pull request is labeled with "benchmark." It sets up the Rust and OCaml environments, installs necessary tools, and executes cargo criterion benchmarks on the kimchi crate. The benchmark results are then posted as a comment on the pull request for review. +- [Deploy Specifications & Docs to GitHub Pages](.github/workflows/gh-page.yml). + When CI passes on master, the documentation built from the rust code will be available by this [link](https://o1-labs.github.io/proof-systems/rustdoc) and the book will be available by this [link](https://o1-labs.github.io/proof-systems). ## Nix for Dependencies (WIP) -If you have `nix` installed and in particular, `flakes` enabled, you can install the dependencies for these projects using nix. Simply `nix develop .` inside this directory to bring into scope `rustup`, `opam`, and `go` (along with a few other tools). You will have to manage the toolchains yourself using `rustup` and `opam`, in the current iteration. \ No newline at end of file +If you have `nix` installed and in particular, `flakes` enabled, you can install the dependencies for these projects using nix. Simply `nix develop .` inside this directory to bring into scope `rustup`, `opam`, and `go` (along with a few other tools). You will have to manage the toolchains yourself using `rustup` and `opam`, in the current iteration.