diff --git a/About_EZKL/Commands.md b/About_EZKL/Commands.md index 181bde5..16139c8 100644 --- a/About_EZKL/Commands.md +++ b/About_EZKL/Commands.md @@ -81,7 +81,7 @@ Along with our SRS and circuit parameters, we need two other elements to generat Run this command to set up your proving and verifying keys: ```bash -ezkl setup -M network.ezkl --srs-path=17.srs --settings-path=settings.json +ezkl setup -M network.ezkl --srs-path=17.srs ``` You should now have files called `vk.key` and `pk.key` in the root of your project. You can also specify different paths for these outputs with `--vk-path=altvk.key --pk-path=altpk.key` @@ -130,7 +130,7 @@ Note that these are not the only operations that can be performed by `ezkl`. You When you're testing a model, you may not want to run `setup` and `prove` with each iteration. `ezkl` provides a simple alternative with `mock`, where you can convert your model to constraints and run the inputs tosee if a proof can be generated. This saves time when testing new iterations of models with potential issues. Here is the command for `mock`: ```bash -ezkl mock -M network.ezkl --witness witness.json --settings-path=settings.json +ezkl mock -M network.ezkl --witness witness.json ``` Mock is basically checking that constraints that your model has been translated into are satisfied, without doing any of the subsequent cryptographic heavy lifting to produce a proof. diff --git a/FAQ.md b/FAQ.md index 125d6f7..b43c07d 100644 --- a/FAQ.md +++ b/FAQ.md @@ -2,78 +2,110 @@ icon: question order: -99999999 --- -![](../assets/copter.png) +![](../assets/copter.png) + # FAQ + ### What programming languages and frameworks does ezkl support? -`ezkl` is a command line tool, and a library that can be used from Rust or Python. You may want to use Python to create a neural network and export it. Though ezkl is built with Rust, you do not need to use Rust except possibly for installation. + +`ezkl` is a command line tool, and a library that can be used from Rust or Python. You may want to use Python to create a neural network and export it. Though ezkl is built with Rust, you do not need to use Rust except possibly for installation. ### Do I need to know Rust before getting started with ezkl? -No, Rust is not a requirement to use the library. As long as you have the ONNX file and proper input & output format of the model, you can use `ezkl`. +No, Rust is not a requirement to use the library. As long as you have the ONNX file and proper input & output format of the model, you can use `ezkl`. # Technical + ### Why is the gen-srs step slow? + Generating a structured reference string takes a considerable amount of time and memory. Make sure your machine has enough memory available and wait for the process to finish. Alternatively, download a pre-generated srs. ### Can I use ezkl with other machine learning frameworks like TensorFlow, PyTorch, or Scikit-learn? + All `ezkl` requires is an onnx file and a JSON configuration of mock inputs and outputs of the neural network. At this time, it works best with PyTorch. ### How fast is ezkl? + We believe that `ezkl` is the fastest zkml package available, and we are working hard every day to make it faster. Feel free to run `cargo bench` on your machine to see what the benchmarks are for your hardware. ### Do I need to deploy a verifier smart contract to use ezkl? + No, we recently integrated a [WASM verifier](https://github.com/zkonduit/ezkl/pull/219) that you can use to verify proofs from your web application. You can also use the EVM verifier to verify proofs locally, or the command line `ezkl verify` command. -# Errors: +# Errors + ### Error: VerifyError -A VerifyError is thrown when the Mock prover fails, often due to a mismatched shape problem in the model. Please verify that your input.json inputs and outputs match those of your .onnx file. + +A VerifyError is thrown when the Mock prover fails, often due to a mismatched shape problem in the model. Please verify that your input.json inputs and outputs match those of your .onnx file. ### Error: DimMismatch -A DimMismatch error is thrown when there is a mismatch in the lengths of the tensor operands during circuit construction. + +A DimMismatch error is thrown when there is a mismatch in the lengths of the tensor operands during circuit construction. + ### Error: LookupInstantiation + This error is thrown when there is an error during the creation of a lookup table + ### Error: TableAlreadyAssigned + A TableAlreadyAssigned Error is thrown when `ezkl` attempts to initialize a lookup table that has already been initialized + ### Error: UnsupportedOp + An UnsupportedOp Error is thrown when there is an operation in the ONNX file that `ezkl` cannot yet handle. Please look at the supported operations under src/circuit/ops to get an idea of what operations `ezkl` can handle. + ### Error: PyValueError + This is a pyo3 error that occurs when a data type fails to be extracted from Python to Rust. Please make sure you are passing the correct data types when utilizing the python bindings. + ### Error: InvalidLookupInputs -InvalidLookupInputs is thrown when the wrong inputs were passed to a lookup node. + +InvalidLookupInputs is thrown when the wrong inputs were passed to a lookup node. + ### Error: InvalidDims + InvalidDims is thrown when there is a shape mismatch in circuit construction. Invalid dimensions were used for a node with the given index and description. + ### Error: WrongMethod + This error means that the wrong method was called to configure a node with the given index and description + ### Error: MissingNode + MissingNode is thrown when a requested node is missing in the graph with the given index + ### Error: OpMismatch + OpMismatch is thrown when an unsupported method was called on a node with the given index and description + ### Error: UnsupportedOp + UnsupportedOp is thrown when there is an operation in the onnx graph that isn't supported by `ezkl` + ### Error: MissingParams -MissingParams is thrown when a node has missing parameters; please check the parameters in your model's operations -### Error: MisformedParams -MisformedParams is thrown when a node has misformed parameters; the error can stem from erroneous padding height and width dimensions, wrong kernel / data format, dilations that are not uint type, and more. -### Error: Visibility -This error is typically thrown when no public variables are passed to the circuit configuration function -### Error: NonConstantDiv -`ezkl` only supports divisions by constants -### Error: NonConstantPower -`ezkl` only supports constant exponents -### Error: RescalingError -This error is thrown when attempting to rescale inputs for an operation -### Error: ModelLoad -This error is thrown when a model fails to load; please check your onnx file for missing connections / unsupported layers. We suggest using [Netron](https://netron.app/) to view onnx files. +MissingParams is thrown when a node has missing parameters; please check the parameters in your model's operations +### Error: MisformedParams +MisformedParams is thrown when a node has misformed parameters; the error can stem from erroneous padding height and width dimensions, wrong kernel / data format, dilations that are not uint type, and more. +### Error: Visibility +This error is typically thrown when no public variables are passed to the circuit configuration function +### Error: NonConstantDiv +`ezkl` only supports divisions by constants +### Error: NonConstantPower +`ezkl` only supports constant exponents +### Error: RescalingError +This error is thrown when attempting to rescale inputs for an operation +### Error: ModelLoad +This error is thrown when a model fails to load; please check your onnx file for missing connections / unsupported layers. We suggest using [Netron](https://netron.app/) to view onnx files. diff --git a/Getting_Started.md b/Getting_Started.md index 5be26c6..6671c1a 100644 --- a/Getting_Started.md +++ b/Getting_Started.md @@ -4,30 +4,37 @@ order: 95 --- ### Installing EZKL + To use `ezkl` in Python, just `pip install ezkl`. You will generally also need `onnx` installed if you are exporting models, and Pytorch, Tensorflow, or similar if you are creating models. `ezkl` uses your system `solc` Solidity compiler, so you may need to tweak it using svm-rs or solc-select, particularly if you are targeting a specific hardfork. -To use the cli, download a [release binary](https://github.com/zkonduit/ezkl/releases) from GitHub. If you want the latest build, you can also install from source. - +To use the cli, download a [release binary](https://github.com/zkonduit/ezkl/releases) from GitHub. If you want the latest build, you can also install from source. ### Building from source πŸ”¨ + Ezkl is built in rust. First [install rust](https://www.rust-lang.org/tools/install), then download the repo and enter the directory + ```bash git clone git@github.com:zkonduit/ezkl.git cd ezkl ``` + After which you may build and install the library + ```bash cargo install --force --path . ``` If you want to build manually with cargo build, be sure to use the release flag as the debug build will result in slow proofs + ```bash cargo build --release --bin ezkl ``` + > Note: To render your model circuits, you'll need to compile `ezkl` with the `render` feature (`cargo build --features render --bin ezkl`). This enables the `render-circuit` command which can create `.png` representations of the compiled circuits. You'll also need to install the `libexpat1-dev` and `libfreetype6-dev` libraries on Debian systems (there are equivalents for MacOS as well). --------- + ##### Rust docs πŸ“– Use `cargo doc --open` to compile and open the Rust documentation for `ezkl` in your default browser. diff --git a/Python_bindings.md b/Python_bindings.md index df627d0..88183fe 100644 --- a/Python_bindings.md +++ b/Python_bindings.md @@ -13,16 +13,17 @@ python >>> import ezkl ``` + lets you use `ezkl` directly from Python. [Here is a colab notebook](https://colab.research.google.com/drive/1XuXNKqH7axOelZXyU3gpoTOCvFetIsKu?usp=sharing) that shows how to produce and verify a proof from Python. When installing `ezkl` with pip, you may want to use a virtualenv. Some virtualenv management solutions for python includes `venv`, `pipenv`, `conda`, and `poetry`. - ### development -Python bindings are built for `ezkl` using [PyO3](https://pyo3.rs) and [Maturin](https://github.com/PyO3/maturin). -To test the development Python bindings you will need to install [Python3](https://realpython.com/installing-python/). +Python bindings are built for `ezkl` using [PyO3](https://pyo3.rs) and [Maturin](https://github.com/PyO3/maturin). + +To test the development Python bindings you will need to install [Python3](https://realpython.com/installing-python/). Note, `ezkl` is only supported for `Python>=3.7`, this installs the [pyezkl build](https://github.com/zkonduit/pyezkl) which contains Python specific functions that the [Rust bindings on the main ezkl repository do not implement](https://github.com/zkonduit/ezkl). @@ -45,11 +46,13 @@ With a solidity version manager you are then able to change solidity versions in #### 3. Try out EZKL Examples in the repository with a Jupyter Notebook Clone the pyezkl repository. + ```bash git clone https://github.com/zkonduit/pyezkl.git ``` Install jupyter and start the jupyter notebook + ```bash pip install jupyter jupyter notebook @@ -57,12 +60,12 @@ jupyter notebook Navigate to the [ezkl_demo.ipynb](https://github.com/zkonduit/pyezkl/blob/main/examples/ezkl_demo.ipynb) file which is located in the examples folder. It contains a minimal setup for running ezkl within python. - ### Developmental python bindings Setting up the development python bindings can be an involved process. #### ezkl repository + In the event that you may want to use the developmental bindings on the main `ezkl` repository, you can clone and build the [main ezkl repository written in rust](https://github.com/zkonduit/ezkl) instead. ```bash @@ -124,7 +127,6 @@ pip install ezkl_lib-0.1.0-cp37-abi3-manylinux_2_35_x86_64.whl If you would like to then use the development version of [pyezkl](https://github.com/zkonduit/pyezkl) with the developmental bindings at [ezkl](https://github.com/zkonduit/ezkl), you will need to setup pyezkl too. - Clone the pyezkl repository in a separate directory if you haven't done so already. ```bash @@ -134,6 +136,7 @@ git clone https://github.com/zkonduit/pyezkl.git We will use `poetry` for the pyezkl repository. [Install poetry by following the instructions provided](https://python-poetry.org/docs/). You will also need to deactivate any existing virtualenv. + ```bash deactivate ``` @@ -147,6 +150,7 @@ poetry shell # activates the virtual environment for poetry ``` Navigate to the ezkl repository and install the wheel that you have built. + ```bash cd ezkl/target/wheels pip install ezkl_lib-version-pythontype-abi3-osversion-processor.whl @@ -163,6 +167,7 @@ pip install ./dist/ezkl-version-py3-none-any.whl ``` If successful, you should be able to run python in your `poetry` environment and call the functions. + ``` python >>> import ezkl @@ -170,7 +175,8 @@ python ``` ### API Reference -![](../assets/library.png) + +![](../assets/library.png) This reference details function, modules, and objects included in both `ezkl` and `ezkl_lib`. Note that `ezkl` is a superset of `ezkl_lib` so functions contained within `ezkl_lib` will be contained in `ezkl`. @@ -178,7 +184,6 @@ Note that `ezkl` is a superset of `ezkl_lib` so functions contained within `ezkl #### Utilities - ##### `export` **Description** @@ -219,16 +224,15 @@ The `ezkl_lib.forward` function is used for the forward operation to quantize in The function raises an error if neither `input_shape` nor `input_array` are provided, or if both are provided but `input_shape` doesn't match the shape of `input_array`. **Example** + ```python ``` - ### `ezkl_lib` #### Command Bindings - ##### `PyRunArgs` **Description** @@ -267,14 +271,12 @@ For integer fields, you are able to use default Python integers. Fields marked with the `#[pyo3(get, set)]` attribute can be accessed (read or modified) directly from Python. - ##### `table` **Description** For more information refer to [Table](./About_EZKL/Commands.md#table) - **Parameters** `model (required)`: This is a string representing the file path of the ONNX model to be loaded. @@ -299,7 +301,6 @@ except Exception as e: print(f"An error occurred: {e}") ``` - ##### `gen_srs` **Description** @@ -327,7 +328,6 @@ ezkl.gen_srs("path/to/save/params", 17) print("SRS generation successful.") ``` - ##### `gen-witness` **Description** @@ -363,7 +363,6 @@ except Exception as e: print(f"An error occurred: {e}") ``` - ##### `mock` **Description** @@ -400,7 +399,6 @@ except Exception as e: print(f"An error occurred: {e}") ``` - ##### `setup` **Description** @@ -453,7 +451,6 @@ except Exception as e: print(f"An error occurred: {e}") ``` - ##### `prove` **Description** @@ -515,14 +512,12 @@ except Exception as e: print(f"An error occurred: {e}") ``` - ##### `verify` **Description** For more information visit [Verify](./About_EZKL/Commands.md#verify) - **Parameters** `proof_path (required)`: A string representing the file path where the proof will be loaded from. @@ -564,7 +559,6 @@ except Exception as e: print(f"An error occurred: {e}") ``` - ##### `aggregate` **Description** @@ -619,7 +613,6 @@ res = ezkl_lib.aggregate( "unsafe" ``` - ##### `verify_aggr` **Description** @@ -680,7 +673,6 @@ More information can be found in [Verifying On Chain](Verifying_On-Chain.md). `sol_code_path (optional)`: A string representing the file path where the Solidity code for the verifier will be saved. - **Returns** If the EVM compatible verifier is successfully generated and saved, it will return `True`. If an error occurs at any stage, it will return an `IOError` or `RuntimeError`. @@ -709,7 +701,6 @@ assert os.path.isfile(deployment_code_path) assert os.path.isfile(sol_code_path) ``` - ##### `verify_evm` **Description** @@ -750,7 +741,6 @@ res = ezkl.verify_evm( assert res == True ``` - ##### `create_evm_verifier_aggr` **Description** @@ -858,7 +848,6 @@ res = ezkl_lib.verify_aggr( assert res == True ``` - ##### `print_proof_hex` **Description** diff --git a/README.md b/README.md index ea0a549..13b1cbe 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,15 @@ # ezkl-docs + Documentation site for [ezkl](https://github.com/zkonduit/ezkl) Link to live documentation [here](https://docs.ezkl.xyz/) ## Running a local version + You can run the retype site locally when reviewing and editing. Each page gets an edit button and you can edit and save right there, or use your favorite editor and it will be auto-reloaded. This will create a copy of the site at localhost:5000 + ``` cd ezkl-docs npm install retypeapp --global diff --git a/Security.md b/Security.md index 44da7b0..8a4db70 100644 --- a/Security.md +++ b/Security.md @@ -4,6 +4,7 @@ order: -100 --- # Security + Zero knowledge machine learning, particularly in blockchain applications, is still a nascent field and should be used with caution. Because there have not yet been many production-ready projects, the potential attack vectors include both the usual and the mostly theoretical or unknown. `ezkl` has not been audited and we make no guarantees on its security. Moreover, zkml is just one component of an overall cryptosystem, and that system as a whole has to be carefully thought out. Neural networks are not by themselves adequate hash functions; the whole point is that they are susceptible to differentiation! @@ -11,23 +12,27 @@ Moreover, zkml is just one component of an overall cryptosystem, and that system Here are a few more things to worry about. ### AI/ML Security -There are several types of adversarial attacks on neural networks. [Gaussian Noise Injection](https://paperswithcode.com/paper/asymmetric-heavy-tails-and-implicit-bias-in), [Data poisoning](https://paperswithcode.com/task/data-poisoning), [Membership Inference Attacks](https://paperswithcode.com/paper/membership-inference-attacks-on-machine) (MIAs), and more are attack vectors that adversaries can use to corrupt your outputs. MIAs and others like it are especially hazardous when the aim of using zkml is to keep the model and its training data private. -Adversarial Training involves training your model with adversarial data so that edge cases are expected and accounted for. [CleverHans](https://github.com/cleverhans-lab/cleverhans) is a useful tool for discovering potential vulnerabilities in your model. For best security results, have an idea of the overall threat model of your neural net and its potential inputs. +There are several types of adversarial attacks on neural networks. [Gaussian Noise Injection](https://paperswithcode.com/paper/asymmetric-heavy-tails-and-implicit-bias-in), [Data poisoning](https://paperswithcode.com/task/data-poisoning), [Membership Inference Attacks](https://paperswithcode.com/paper/membership-inference-attacks-on-machine) (MIAs), and more are attack vectors that adversaries can use to corrupt your outputs. MIAs and others like it are especially hazardous when the aim of using zkml is to keep the model and its training data private. + +Adversarial Training involves training your model with adversarial data so that edge cases are expected and accounted for. [CleverHans](https://github.com/cleverhans-lab/cleverhans) is a useful tool for discovering potential vulnerabilities in your model. For best security results, have an idea of the overall threat model of your neural net and its potential inputs. ### ZK Security -The goal of zero knowledge proof systems is to construct complete, sound proofs. Completeness is the highly probable assurance that any valid proof will verify. Soundness is the quality of the verifier (or parties representing the verifier) knowing that if a proof passes, it is more than likely a true statement. In some cases, such as those in [underconstrained circuits](https://eprint.iacr.org/2023/512.pdf), bad proofs can be generated that fool the verifier into passing a false statement. In this case, the vulnerability is not in the machine learning model itself, but in the SNARK constructed by `ezkl`. -`ezkl` is a compiler, so eventually should be less susceptible to such issues than a hand-written circuit, but it is still under active development. +The goal of zero knowledge proof systems is to construct complete, sound proofs. Completeness is the highly probable assurance that any valid proof will verify. Soundness is the quality of the verifier (or parties representing the verifier) knowing that if a proof passes, it is more than likely a true statement. In some cases, such as those in [underconstrained circuits](https://eprint.iacr.org/2023/512.pdf), bad proofs can be generated that fool the verifier into passing a false statement. In this case, the vulnerability is not in the machine learning model itself, but in the SNARK constructed by `ezkl`. -Please reach out directly to let us know of any soundess issues you encounter. +`ezkl` is a compiler, so eventually should be less susceptible to such issues than a hand-written circuit, but it is still under active development. +Please reach out directly to let us know of any soundess issues you encounter. ###### Fuzzing + `ezkl` supports fuzzing over your model's edge inputs to test for potential vulnerabilities. Use your `input.json` and `network.onnx` files to run: + ```bash ezkl fuzz -D input.json -M network.onnx --transcript=evm --num-runs 10 ``` -Be sure to replace `num-runs` with the amount of fuzz testing rounds you want to do along with other parameters you are using to generate your circuit. -Thank you for using `ezkl`; please contact us if you have any comments on this documentation. \ No newline at end of file +Be sure to replace `num-runs` with the amount of fuzz testing rounds you want to do along with other parameters you are using to generate your circuit. + +Thank you for using `ezkl`; please contact us if you have any comments on this documentation. diff --git a/Verifying_On-Chain.md b/Verifying_On-Chain.md index a7b61b7..2b6f146 100644 --- a/Verifying_On-Chain.md +++ b/Verifying_On-Chain.md @@ -7,17 +7,20 @@ order: 7 To verify on-chain, generate a verifier smart contract after performing setup. You can use the example from Commands, or create it by copying over a network and input file (assuming the ezkl repo is in your home directory): + ```bash cp ~/ezkl/examples/onnx/4l_relu_conv_fc/network.onnx ./ cp ~/ezkl/examples/onnx/4l_relu_conv_fc/input.json ./ ``` + then create the setup + ```bash ezkl gen-settings -M network.onnx ezkl calibrate-settings -M network.onnx -D input.json --target resources ezkl get-srs -S settings.json -ezkl compile-model -M network.onnx -S settings.json --compiled-model network.ezkl -ezkl setup -M network.ezkl --srs-path=kzg.srs --settings-path=settings.json +ezkl compile-circuit -M network.onnx -S settings.json --compiled-circuit network.ezkl +ezkl setup -M network.ezkl --srs-path=kzg.srs ``` Now we use this setup to create an EVM verifier, which would be deployed on-chain. @@ -28,17 +31,17 @@ ezkl create-evm-verifier --srs-path=kzg.srs --vk-path vk.key --sol-code-path ver ``` ```bash -ezkl gen-witness -D input.json -M network.ezkl --settings-path=settings.json -ezkl prove --transcript=evm --witness witness.json -M network.ezkl --proof-path model.pf --pk-path pk.key --srs-path=kzg.srs --settings-path=settings.json +ezkl gen-witness -D input.json -M network.ezkl +ezkl prove --witness witness.json -M network.ezkl --proof-path model.pf --pk-path pk.key --srs-path=kzg.srs ``` ```bash # install anvil if you haven't already -cargo install --git https://github.com/foundry-rs/foundry --profile local --locked foundry-cli anvil +cargo install --git https://github.com/foundry-rs/foundry --profile local --locked anvil ``` ```bash -# spin up a local EVM through anvil +# spin up a local EVM through anvil in a separate terminal anvil -p 3030 ``` @@ -49,10 +52,10 @@ ezkl deploy-evm-verifier --addr-path=addr.txt --rpc-url=http://127.0.0.1:3030 -- ```bash # verify (EVM), make sure to copy the address stored in addr.txt and paste it into the addr param -ezkl verify-evm --proof-path model.pf --addr=*paste address in addr.txt here* --rpc-url=http://127.0.0.1:3030 +ezkl verify-evm --proof-path model.pf --addr=$(cat addr.txt) --rpc-url=http://127.0.0.1:3030 ``` -Note that the `.sol` file above can be deployed and composed with other Solidity contracts, via a `verify()` function. +Note that the `.sol` file above can be deployed and composed with other Solidity contracts, via a `verify()` function. #### Aggregation @@ -61,6 +64,7 @@ Note that the `.sol` file above can be deployed and composed with other Solidity The above pipeline can also be run using proof aggregation to reduce the final proof size and the size and execution cost of the on-chain verifier. A sample pipeline for doing so would be as follows. Grab a smaller model. + ```bash cp ~/ezkl/examples/onnx/1l_relu/network.onnx ./ cp ~/ezkl/examples/onnx/1l_relu/input.json ./ @@ -68,7 +72,7 @@ cp ~/ezkl/examples/onnx/1l_relu/input.json ./ ```bash # Generate a new SRS. We use 20 since aggregation requires larger circuits (more commonly 23+). -ezkl gen-srs --logrows 20 --srs-path=20.srs +ezkl get-srs --logrows 20 --srs-path=20.srs ``` ```bash @@ -78,19 +82,21 @@ ezkl calibrate-settings -M network.onnx -D input.json --target resources ``` Set up the first proof. + ```bash # Set up a new circuit -ezkl compile-model -M network.onnx -S settings.json --compiled-model network.ezkl -ezkl setup -M network.ezkl --srs-path=20.srs --vk-path=vk.key --pk-path=pk.key --settings-path=settings.json +ezkl compile-circuit -M network.onnx -S settings.json --compiled-circuit network.ezkl +ezkl setup -M network.ezkl --srs-path=20.srs --vk-path=vk.key --pk-path=pk.key ``` ```bash # Single proof -> single proof we are going to feed into aggregation circuit. (Mock)-verifies + verifies natively as sanity check -ezkl gen-witness -D input.json -M network.ezkl --settings-path=settings.json -ezkl prove --transcript=poseidon --strategy=accum -W witness.json -M network.ezkl --proof-path first.pf --srs-path=20.srs --pk-path=pk.key --settings-path=settings.json +ezkl gen-witness -D input.json -M network.ezkl +ezkl prove --proof-type=for-aggr -W witness.json -M network.ezkl --proof-path first.pf --srs-path=20.srs --pk-path=pk.key ``` Setup the aggregate proof. + ```bash ezkl setup-aggregate --sample-snarks first.pf --srs-path 20.srs --logrows 20 ``` @@ -117,23 +123,25 @@ ezkl deploy-evm-verifier --addr-path=addr.txt --rpc-url=http://127.0.0.1:3030 -- ```bash # verify (EVM), make sure to copy the address stored in addr.txt and paste it into the addr param -ezkl verify-evm --proof-path proof_aggr.proof --addr=*paste address in addr.txt here* --rpc-url=http://127.0.0.1:3030 +ezkl verify-evm --proof-path proof_aggr.proof --addr=$(cat addr.txt) --rpc-url=http://127.0.0.1:3030 ``` Also note that this may require a local [solc](https://docs.soliditylang.org/en/v0.8.17/installing-solidity.html) installation. You can follow the SolidityLang instructions linked above, or you can use [svm-rs](https://github.com/alloy-rs/svm-rs) to install solc. Here's how: Install svm-rs: + ```bash cargo install svm-rs ``` Install a recent Solidity version (we use 0.8.20 in our implementation): + ```bash svm install 0.8.20 ``` Verify your Solidity version: + ```bash solc --version ``` - diff --git a/default.md b/default.md index 97cbcd4..c69dfc0 100644 --- a/default.md +++ b/default.md @@ -6,6 +6,7 @@ order: 100 # What is EZKL? ## EZKL makes zero-knowledge easier + `ezkl` takes a high-level description of your program and sets up a zero-knowledge prover and verifier. Our focus is on programs that are expressed as [pytorch](https://pytorch.org/docs/stable/index.html) AI/ML models and other computational graphs. After setup, the prover can prove statements such as the following. > "I ran this publicly available neural network on some private data and it produced this output" @@ -16,7 +17,7 @@ order: 100 These proofs can be trusted by anyone with a copy of the verifier, and verified directly on Ethereum and compatible chains. `ezkl` can be used directly from Python; [see this colab notebook](https://colab.research.google.com/github/zkonduit/ezkl/blob/main/examples/notebooks/simple_demo.ipynb) and the python bindings docs. It can also be used from the command line. -`ezkl` can prove an MNIST-sized inference in less than a second and under 180mb of memory and verify it on the Ethereum Virtual Machine (or on the command line, or in the browser using wasm). +`ezkl` can prove an MNIST-sized inference in less than a second and under 180mb of memory and verify it on the Ethereum Virtual Machine (or on the command line, or in the browser using wasm). You can install the Python version with `pip install ezkl`. @@ -26,28 +27,31 @@ For more details on how to use `ezkl`, we invite you to explore the docs and che ---------------------- - ## Zero-knowledge proofs -A zero-knowledge proof is a programmable digital signature. In a traditional digital signature scheme, we have a secret key, a public message, and a signature algorithm that was set up in advance and everyone knows. These are applied to the inputs to produce a signature and a public message, which is then verified by a counterparty (such as a blockchain). -![](../assets/before.png) + +A zero-knowledge proof is a programmable digital signature. In a traditional digital signature scheme, we have a secret key, a public message, and a signature algorithm that was set up in advance and everyone knows. These are applied to the inputs to produce a signature and a public message, which is then verified by a counterparty (such as a blockchain). +![](../assets/before.png) A zero-knowledge proof allows us to replace the secret key and public message with arbitrary private and public inputs, and it lets us run any program we like on them, not just a fixed signature algorithm. -![](../assets/after.png) +![](../assets/after.png) Just as with a digital signature, there are three parties: one to define the setup, one to prove, and one to verify. ## The life cycle of a proof -There are three steps in the life of an ezkl proof: Setup, Prove, and Verify. Each step is generally performed by a different party. +There are three steps in the life of an ezkl proof: Setup, Prove, and Verify. Each step is generally performed by a different party. -### Setup -Setup is invoked with `ezkl setup` at the cli or `ezkl.setup()` in Python. It defines what consitutes a proof and how that proof will be verified, setting the rules of the game. Setup is performed by the application developer, who then deploys the resulting artifacts to production. +### Setup + +Setup is invoked with `ezkl setup` at the cli or `ezkl.setup()` in Python. It defines what constitutes a proof and how that proof will be verified, setting the rules of the game. Setup is performed by the application developer, who then deploys the resulting artifacts to production. The inputs to setup are: + - the model (as an onnx file) - the structured reference string which is a common, public piece of cryptographic data shared among proof setups of the same size - various flags, settings, and options for tuning and added functionality The outputs of setup are: + - the proving key - the verification key, and - the circuit settings: serialized flags, settings, and options, and a few numbers that describe the shape of the resulting circuit. @@ -69,9 +73,11 @@ res = ezkl.setup( ``` ### Prove -Prove, invoked with `ezkl prove` at the cli or `ezkl.prove()` in Python, is called by the prover, often on the client. The prover is making a claim that it knows some inputs (which might include model parameters), such that when the model (chosen during setup) is run on them, produces certain outputs. The prove command computes a cryptographic proof of that claim, which can then be believed by any verifier. + +Prove, invoked with `ezkl prove` at the cli or `ezkl.prove()` in Python, is called by the prover, often on the client. The prover is making a claim that it knows some inputs (which might include model parameters), such that when the model (chosen during setup) is run on them, produces certain outputs. The prove command computes a cryptographic proof of that claim, which can then be believed by any verifier. The inputs to prove are: + - the witness data for the claim: an (input, output) pair $(x,y)$ such that model(input) = output (this pair can be produced from $x$ using the `gen-witness` command) - the model (as a compiled model file, made from an onnx file) - the proving key @@ -79,6 +85,7 @@ The inputs to prove are: - the circuit settings. The outputs of prove are: + - the proof file. ```python @@ -96,8 +103,8 @@ res = ezkl.prove( ) ``` +### Verify -### Verify `ezkl` can produce an EVM verifier contract which takes only the proof as input, and this is the normal use case. ```python @@ -126,17 +133,17 @@ res = ezkl.verify_evm( Verification can also be invoked with `ezkl verify` at the cli, `ezkl.verify()` in Python, or with WASM. It checks the correctness of the cryptographic proof produced by the prover. The inputs to (non-EVM) verify are: + - the proof file - the verification key - the circuit settings, and - the structured reference string - ---------------------- ## Contributing 🌎 -If you're interested in contributing and are unsure where to start, reach out to one of the maintainers on our [Telegram group](https://t.me/+QRzaRvTPIthlYWMx) or our [Discord](https://discord.gg/mqgdwdSgzA). +If you're interested in contributing and are unsure where to start, reach out to one of the maintainers on our [Telegram group](https://t.me/+QRzaRvTPIthlYWMx) or our [Discord](https://discord.gg/mqgdwdSgzA). More broadly: @@ -145,4 +152,3 @@ More broadly: - See currently open issues for ideas on how to contribute. - For PRs we use the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) naming convention. - diff --git a/library.md b/library.md index 9a81ed9..656558e 100644 --- a/library.md +++ b/library.md @@ -3,11 +3,10 @@ icon: book order: -9 --- -### Talks to watch +### Talks to watch [Dante and Jason - Zero-Knowledge Machine Learning with EZKL in Autonomous Worlds](https://www.youtube.com/watch?v=tp22vStPVG8) - [![](../assets/edconthumb.png)](https://www.youtube.com/watch?v=b8WwlHFBXfs) [Jason Morton - What Is Unlocked by Practical Zero-Knowledge Proofs? | EDCON 2023 Montenegro](https://www.youtube.com/watch?v=b8WwlHFBXfs) @@ -18,15 +17,14 @@ Empower - coming soon ETH Denver talks - coming soon -[Jason Morton - Zero-Knowledge Machine Learning 6 Jan 2023 | ZK SYMPOSIUM](https://www.youtube.com/watch?v=7rxNN4mcOgI) +[Jason Morton - Zero-Knowledge Machine Learning 6 Jan 2023 | ZK SYMPOSIUM](https://www.youtube.com/watch?v=7rxNN4mcOgI) -[Jason Morton - Zero-Knowledge Machine Learning 16 Nov 2022 | ZkProof Tel Aviv](https://www.youtube.com/watch?v=r-tlqdO1bRs) +[Jason Morton - Zero-Knowledge Machine Learning 16 Nov 2022 | ZkProof Tel Aviv](https://www.youtube.com/watch?v=r-tlqdO1bRs) [Jason Morton - Zero-Knowledge Machine Learning 15 Sep 2022 | DEVCON Bogota](https://www.youtube.com/watch?v=s9IfxTMq4ks) [Jason Morton - Zero-Knowledge Machine Learning | Stanford Science of Blockchain Conference 2 Sept 2022](https://www.youtube.com/watch?v=a66iUDRvgWU) - ### Blog posts [Constraint efficiency](https://hackmd.io/@dantecamuto/BJrWEdGU3) @@ -35,10 +33,8 @@ ETH Denver talks - coming soon - ### EZKL in the press and blogs - [Spectral Finance: The State of Zero-Knowledge Machine Learning (zkML), 6 June 2023](https://blog.spectral.finance/the-state-of-zero-knowledge-machine-learning-zkml) [Fortune: A brief history of zero-knowledge proofs, the buzzy mathematical technique that’s taken crypto by storm, 5 June 2023](https://fortune.com/crypto/2023/06/05/zero-knowledge-proofs-history-zk-rollups-cryptography-zcash/) @@ -56,5 +52,3 @@ ETH Denver talks - coming soon [Worldcoin: An introduction to zero-knowledge machine learning (ZKML) 22 Feb 2023](https://worldcoin.org/blog/engineering/intro-to-zkml) - -