{"id":13592804,"url":"https://github.com/NilFoundation/zkllvm","last_synced_at":"2025-04-09T02:31:22.101Z","repository":{"id":65653633,"uuid":"559081430","full_name":"NilFoundation/zkLLVM","owner":"NilFoundation","description":"Zero-Knowledge Proof Systems Circuit Compiler","archived":false,"fork":false,"pushed_at":"2025-01-23T08:46:10.000Z","size":2358,"stargazers_count":308,"open_issues_count":126,"forks_count":51,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-13T08:39:13.432Z","etag":null,"topics":["compiler","llvm","proof-system","zero-knowledge"],"latest_commit_sha":null,"homepage":"https://docs.nil.foundation/zkllvm","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NilFoundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-10-29T02:17:11.000Z","updated_at":"2025-03-11T07:21:12.000Z","dependencies_parsed_at":"2024-01-17T21:54:42.158Z","dependency_job_id":"f0de1175-ea74-4b1c-abb3-86364674a9c3","html_url":"https://github.com/NilFoundation/zkLLVM","commit_stats":null,"previous_names":[],"tags_count":96,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NilFoundation%2FzkLLVM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NilFoundation%2FzkLLVM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NilFoundation%2FzkLLVM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NilFoundation%2FzkLLVM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NilFoundation","download_url":"https://codeload.github.com/NilFoundation/zkLLVM/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247965503,"owners_count":21025392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compiler","llvm","proof-system","zero-knowledge"],"created_at":"2024-08-01T16:01:13.329Z","updated_at":"2025-04-09T02:31:19.205Z","avatar_url":"https://github.com/NilFoundation.png","language":"C++","funding_links":[],"categories":["Index"],"sub_categories":["Projects"],"readme":"# zkLLVM Circuit Compiler\n\n[![build-linux](https://github.com/NilFoundation/zkllvm/actions/workflows/build_linux.yml/badge.svg?branch=master)](\nhttps://github.com/NilFoundation/zkllvm/actions/workflows/build_linux.yml)\n[![build-macos](https://github.com/NilFoundation/zkllvm/actions/workflows/build_macos.yml/badge.svg?branch=master)](\nhttps://github.com/NilFoundation/zkllvm/actions/workflows/build_macos.yml)\n\n[![Discord](https://img.shields.io/discord/969303013749579846.svg?logo=discord\u0026style=flat-square)](https://discord.gg/KmTAEjbmM3)\n[![Telegram](https://img.shields.io/badge/Telegram-2CA5E0?style=flat-square\u0026logo=telegram\u0026logoColor=dark)](https://t.me/nilfoundation)\n[![Twitter](https://img.shields.io/twitter/follow/nil_foundation)](https://twitter.com/nil_foundation)\n\nzkLLVM is a compiler from high-level programming languages into an input for provable computations protocols.\nIt can be used to generate input for any arbitrary zero-knowledge proof system or protocol, which accepts\ninput data in form of algebraic circuits It assumed to be used together with `Placeholder` proof system or\nany other arithmetization compatible with `Placeholder` proof system.\n\nEvery proof output from zkLLVM is **an in-EVM verifiable** one through the [Proof Market](https://proof.market). Use the Proof Market Toolchain repository (https://github.com/NilFoundation/proof-market-toolchain) to generate in-EVM verifiers.\n\n**Notice**: zkLLVM is **NOT** a virtual machine and has nothing to do with it. It, moreover, with its existence proves the absence of necessity in zkVMs, posing them as redundant.\n\nzkLLVM is designed as an extension to LLVM toolchain, thus supports any front end which compiles to LLVM IR. This\nenables developers to write code in native language instead of DSL's specific to other libraries.\n\nzkLLVM extends:\n1. `clang/clang++` : Compiles the program into general intermediate representation byte-code from C/C++.\n2. `rustc`: Compiles the program into general intermediate representation byte-code from Rust. (https://github.com/NilFoundation/zkllvm-rslang)\n3. `assigner` Creates the circuit execution trace (a.k.a. assignment table) and produces data, needed by the prover to produce proof.\n\nLanguages currently supported are:\n1. C/C++ (all the standards Clang 15 supports).\n2. Rust (https://github.com/NilFoundation/zkllvm-rslang).\n3. Your language suggestions are warmly welcomed in Telegram (https://t.me/nilfoundation) or on Discord (https://discord.gg/KmTAEjbmM3).\n\n## Building\n\n### Unix\n\n#### Install Dependencies\n\nInstall nix using the following command:\n\n```\ncurl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install\n```\n\nfor most cases, you want to have an incremental build:\n```\nnix develop\neval \"$configurePhase\"\neval \"$buildPhase\"\neval \"$checkPhase\"\n```\n\nonly build:\n```\nnix build -L .?submodules=1\n```\nbuild and test:\n```\nnix build -L .?submodules=1#checks.x86_64-linux.debug-tests\n```\n\n#### 1. Clone the repository\n\nClone the repository and all the submodules via:\n\n```\ngit clone --recurse-submodules https://github.com/NilFoundation/zkLLVM.git\ncd zkLLVM\n```\n\n#### **2. Configure CMake**\n\n```bash\ncmake -G \"Unix Makefiles\" -B ${ZKLLVM_BUILD:-build} -DCMAKE_BUILD_TYPE=Release .\n```\nOr use the below command instead, if you prefer Ninja build system (as we do, because Ninja works much faster).\n\n```bash\ncmake -G \"Ninja\" -B ${ZKLLVM_BUILD:-build} -DCMAKE_BUILD_TYPE=Release .\n```\n\n#### **3. Build C++ compiler**\n\nIf you are using Unix makefiles:\n```bash\nmake -C ${ZKLLVM_BUILD:-build} assigner clang -j$(nproc)\n```\nIf you are using Ninja:\n\n```bash\nninja -C ${ZKLLVM_BUILD:-build} assigner clang -j$(nproc)\n```\n\n\n#### **4. Build Rust compiler**\n\nMake sure you have [`rustc`](https://www.rust-lang.org/tools/install) with `cargo` installed first.\n\n##### **4.1 Reconfigure CMake, adding Rust tools**\n\nUnix makefiles:\n```bash\ncmake -G \"Unix Makefiles\" -B ${ZKLLVM_BUILD:-build} -DCMAKE_BUILD_TYPE=Release -DRSLANG_BUILD_EXTENDED=TRUE -DRSLANG_BUILD_TOOLS=cargo .\n```\n\nNinja:\n```bash\ncmake -G \"Ninja\" -B ${ZKLLVM_BUILD:-build} -DCMAKE_BUILD_TYPE=Release -DRSLANG_BUILD_EXTENDED=TRUE -DRSLANG_BUILD_TOOLS=cargo .\n```\n\n##### **4.2 Export path for loading LLVM libraries**\n\n```bash\nexport LD_LIBRARY_PATH=\"$LD_LIBRARY_PATH:$(pwd)/build/libs/circifier/llvm/lib\"\n```\n\n##### **4.3 Build Rust compiler and Cargo**\n\nUnix makefiles:\n```bash\nmake -C ${ZKLLVM_BUILD:-build} rslang -j$(nproc)\n```\n\nNinja:\n```bash\nninja -C ${ZKLLVM_BUILD:-build} rslang -j$(nproc)\n```\n\nAfter that you will be able to call Cargo like that:\n\n```bash\nexport RSLANG=\"$(pwd)/build/libs/rslang/build/host\"\nRUSTC=$RSLANG/stage1/bin/rustc $RSLANG/stage1-tools-bin/cargo --version\n```\n\nNote: if you want an advanced Rust compilation, you can build `zkllvm` first:\n\nUnix makefiles:\n```bash\nmake -C ${ZKLLVM_BUILD:-build} -j$(nproc)\n```\n\nNinja:\n```bash\nninja -C ${ZKLLVM_BUILD:-build} -j$(nproc)\n```\n\nAnd then use Rust default build system `x.py`.\n\n## Pre-built binaries\n\n### Rust toolchain\n\nYou can install `rslang` as another toolchain in [`rustup`](https://rustup.rs/) or as a standalone application.\nInstallation is done via `rslang-installer.py` script. It finds and downloads required release of `rslang`\nand installs it in the desired location.\n\n#### **Supported platforms**\n\n* x86-64 GNU/Linux\n\n#### **Prerequisites**\n\n* Python 3.7+\n\n#### **Installation with `rustup`**\n\n1. Install `rustup` as described on [official page](https://rustup.rs/).\n\n2. Install `rslang`:\n\nRun this in your shell:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://cdn.jsdelivr.net/gh/NilFoundation/zkllvm@master/rslang-installer.py | python - --channel nightly\n```\n\nYou can also download the `rslang-installer.py` first and then run it:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -O https://cdn.jsdelivr.net/gh/NilFoundation/zkllvm@master/rslang-installer.py\npython rslang-installer.py --channel nightly\n```\n\nNow you can use toolchain called `zkllvm` to compile with `rslang`:\n\n```bash\nrustc +zkllvm -V\n```\n\n#### **Stanalone installation**\n\nTo install `rslang` without `rustup` use `--no-rustup` argument.\nYou will need to pass `PATH` to desired installation directory.\n\n```bash\ncurl --proto '=https' --tlsv1.2 -O https://cdn.jsdelivr.net/gh/NilFoundation/zkllvm@master/rslang-installer.py\npython rslang-installer.py --no-rustup --prefix PATH\n```\n\n## Usage\n\nzkLLVM's workflow is as follows:\n\n1. **Write Circuit :** Users willing to prove some statement are supposed to implement an application in a language compatible with some frontend (C++ for now). This code will be compiled with a modified version of the `clang` compiler, which will output intermediate representation of the circuit.\n   ![compile](./docs/assets/compile.png)\n   \u003e For the most performant cryptography circuits (e.g. hashes, signatures, VDFs, proof system verifications, etc.)\n   \u003e we recommend using [=nil; Foundation's Crypto3 library](https://github.com/nilfoundation/crypto3.git).\n\n   ![compile](./docs/assets/transpile.png)\n  The circuit developer will be generating the in-EVM applications for the circuits they have created. This will enable on-chain verification of the proof.\n  The in-EVM logic consists of gate representations of the circuit. These contracts work in conjunction with the Placeholder proof validation in-EVM logic.\n  The process to transpile the circuit into smart contracts is handled by the [lorem-ipsum](https://github.com/NilFoundation/lorem-ipsum-cli)\n  project.\n\n2. **Publish Circuit/Generate Proof**: zkLLVM is tightly coupled with [=nil; Foundation's Proof Market](https://proof.market.nil.foundation). Users willing to generate a proof for the circuit, will be matched with counter-parties based on price and other conditions.\n   The circuit generated above needs to be published to proof market to enable this.\n   ![publish](./docs/assets/publish.png)\n\nTo generate a proof it is required to pass the following to the proof generator:\n\n    * Circuit : Arithmetization of the circuit.\n    * Inputs: Public (and private) inputs to circuit part of the proof request.\n\nThis generates the binary proof file. This flow is handled by the [proof market toolchain](https://github.com/NilFoundation/proof-market-toolchain) repository \u0026 documented [here](https://docs.nil.foundation/proof-market/market/user-guides/proof-producer).\n\nUsers can generate \u0026 inspect intermediate artifacts such as execution trace by running the `assigner` process. See examples below.\n\n3. **Verify Proof**: Proof can be retrieved from the proof market and verified on chain. Users can verify proof in these modes :\n   1. Offline : Tooling to support validation of off-chain proof will be added in the future.\n   2. On-chain : This flow of generating smart contracts is handled by the [lorem-ipsum](https://github.com/NilFoundation/lorem-ipsum-cli) project. A high level flow is described in the guides\n   for [circuit developer](https://docs.nil.foundation/zkllvm/manual/getting-started/circuit-generation) \u0026 [proof verifier](https://docs.nil.foundation/zkllvm/manual/getting-started/proof-verifier)\n   described above.\n    ![verify](./docs/assets/dapp_verify.png)\n\n   Above we see how a dApp can use generated verifiers on-chain by simply including verification interfaces.\n\n### Examples\n\n#### Linux\n\nUnix makefiles:\n```bash\nmake -C ${ZKLLVM_BUILD:-build} arithmetics_cpp_example -j$(nproc)\n${ZKLLVM_BUILD:-build}/bin/assigner/assigner -b ${ZKLLVM_BUILD:-build}/examples/cpp/arithmetics_cpp_example.ll -i examples/inputs/arithmetics.inp -t assignment.tbl -c circuit.crct -e pallas\n```\n\nNinja:\n```bash\nninja -C ${ZKLLVM_BUILD:-build} arithmetics_cpp_example -j$(nproc)\n${ZKLLVM_BUILD:-build}/bin/assigner/assigner -b ${ZKLLVM_BUILD:-build}/examples/cpp/arithmetics_cpp_example.ll -i examples/inputs/arithmetics.inp -t assignment.tbl -c circuit.crct -e pallas\n```\n\n#### macOS\nUnix makefiles:\n```bash\nmake -C ${ZKLLVM_BUILD:-build} arithmetics_cpp_example -j$(sysctl -n hw.logicalcpu)\n${ZKLLVM_BUILD:-build}/bin/assigner/assigner -b ${ZKLLVM_BUILD:-build}/examples/cpp/arithmetics_cpp_example.ll -i examples/inputs/arithmetics.inp -t assignment.tbl -c circuit.crct -e pallas\n```\n\nNinja:\n```bash\nninja -C ${ZKLLVM_BUILD:-build} arithmetics_cpp_example -j$(sysctl -n hw.logicalcpu)\n${ZKLLVM_BUILD:-build}/bin/assigner/assigner -b ${ZKLLVM_BUILD:-build}/examples/cpp/arithmetics_cpp_example.ll -i examples/inputs/arithmetics.inp -t assignment.tbl -c circuit.crct -e pallas\n```\n\n### Validating the circuit\n\nYou can also run the `assigner` with `--check` flag to validate the satisfiability of the circuit. If the circuit is satisfiable, the `assigner` will output the satisfying assignment in the `assignment.tbl` file. If there is an error, the `assigner` will output the error message and throw an exception via `std::abort`.\n\n#### Linux\nUnix makefiles:\n```bash\nmake -C ${ZKLLVM_BUILD:-build} arithmetics_cpp_example -j$(nproc)\n${ZKLLVM_BUILD:-build}/bin/assigner/assigner -b ${ZKLLVM_BUILD:-build}/examples/cpp/arithmetics_cpp_example.ll -i examples/inputs/arithmetics.inp -t assignment.tbl -c circuit.crct -e pallas --check\n```\n\nNinja:\n```bash\nninja -C ${ZKLLVM_BUILD:-build} arithmetics_cpp_example -j$(nproc)\n${ZKLLVM_BUILD:-build}/bin/assigner/assigner -b ${ZKLLVM_BUILD:-build}/examples/cpp/arithmetics_cpp_example.ll -i examples/inputs/arithmetics.inp -t assignment.tbl -c circuit.crct -e pallas --check\n```\n\n#### macOS\nUnix makefiles:\n```bash\nmake -C ${ZKLLVM_BUILD:-build} arithmetics_cpp_example -j$(sysctl -n hw.logicalcpu)\n${ZKLLVM_BUILD:-build}/bin/assigner/assigner -b ${ZKLLVM_BUILD:-build}/examples/cpp/arithmetics_cpp_example.ll -i examples/inputs/arithmetics.inp -t assignment.tbl -c circuit.crct -e pallas --check\n```\n\nNinja:\n```bash\nninja -C ${ZKLLVM_BUILD:-build} arithmetics_cpp_example -j$(sysctl -n hw.logicalcpu)\n${ZKLLVM_BUILD:-build}/bin/assigner/assigner -b ${ZKLLVM_BUILD:-build}/examples/cpp/arithmetics_cpp_example.ll -i examples/inputs/arithmetics.inp -t assignment.tbl -c circuit.crct -e pallas --check\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNilFoundation%2Fzkllvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNilFoundation%2Fzkllvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNilFoundation%2Fzkllvm/lists"}