diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6a3e68d --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +**/.DS_Store \ No newline at end of file diff --git a/Getting Started/Installation.md b/Getting Started/Installation.md index 029014d..9ae5614 100644 --- a/Getting Started/Installation.md +++ b/Getting Started/Installation.md @@ -4,44 +4,58 @@ order: 96 --- +++ Local CLI + 1. Install the binary with the following bash script. + ```bash curl https://raw.githubusercontent.com/zkonduit/ezkl/main/install_ezkl_cli.sh | bash ``` 2. Alternatively, build from source: + ```bash git clone git@github.com:zkonduit/ezkl.git cd ezkl cargo install --force --path . ``` + For detailed options, use `ezkl --help` or `ezkl --help`. +++ Python Install EZKL using pip: + ```bash pip install ezkl ``` + You may also need to install additional dependencies: + - `onnx` for exporting models - PyTorch or TensorFlow for creating models To use EZKL in your Python code: + ```bash import ezkl ``` + +++ JavaScript Install EZKL using npm: + ```bash npm install @ezkljs/engine ``` + To use EZKL in your JavaScript code: + ```bash import { Engine } from '@ezkljs/engine'; ``` -+++ Remote CLI + ++++ Remote CLI (Lilith) 1. Install `archon` with the following script + ```bash curl https://download.ezkl.xyz/download_archon.sh | bash ``` @@ -49,16 +63,22 @@ curl https://download.ezkl.xyz/download_archon.sh | bash 2. If your system settings block the installed binary you will need to allow your system to run the binary. 3. Set the server environment variable: + ```bash export ARCHON_SERVER_URL="https://archon-v0.ezkl.xyz" ``` + 4. Test the connection: + ```bash archon ping ``` + +++ + ## Additional Notes + - While there is some support for Windows with the original `ezkl` repository, unfortunately Lilith does not work on Windows systems. - EZKL uses your system's `solc` Solidity compiler. You may need to adjust it using `svm-rs` or `solc-select`. - For rendering model circuits with EZKL, compile with the `render` feature and install required libraries (e.g., `libexpat1-dev` and `libfreetype6-dev` on Debian systems). -- For EZKL Rust documentation, use `cargo doc --open`. \ No newline at end of file +- For EZKL Rust documentation, use `cargo doc --open`. diff --git a/Getting Started/Setup.md b/Getting Started/Setup.md index 4eefaf6..d2177e2 100644 --- a/Getting Started/Setup.md +++ b/Getting Started/Setup.md @@ -2,31 +2,39 @@ icon: gear order: 95 --- + The lifecycle of an EZKL proof consists of three core components: Setup, Prove, and Verify. This page focuses on the Setup phase, which defines the rules for proof generation and verification. Recall that: + - **Setup**: Defines proof parameters and generates keys (performed by developers) - **Prove**: Generates a proof based on the setup (performed by users) - **Verify**: Checks the validity of a proof (performed by verifiers) ### Process + The setup process involves the following steps: + 1. **Generate settings**: Creates a configuration file with default parameters for the circuit. 2. **Calibrate settings (optional)**: Fine-tunes the circuit parameters to optimize for either accuracy or resource usage. 3. **Compile the model**: Converts the ONNX model into a format optimized for zero-knowledge proofs. 4. **Run setup**: Generates the cryptographic keys needed for proving and verifying. ### Parameters + To perform the setup, you'll need to provide and/or create the following: #### ONNX File For PyTorch: + ```python import torch.onnx dummy_input = torch.randn(1, 3, 224, 224) # Adjust input dimensions as needed torch.onnx.export(model, dummy_input, "network.onnx", opset_version=10) ``` + For TensorFlow: + ```python import tf2onnx @@ -34,132 +42,169 @@ onnx_model, _ = tf2onnx.convert.from_keras(model) with open("network.onnx", "wb") as f: f.write(onnx_model.SerializeToString()) ``` -#### Structured Reference String (SRS) -The SRS is a common, public piece of cryptographic data. You can download it using the EZKL CLI: -```bash -ezkl get-srs -``` + #### Configuration Options + These are defined in the `settings.json` file, which is generated and optionally calibrated during the setup process. ### Instructions + +++ Local CLI 1. Generate settings: + ```bash ezkl gen-settings ``` + This creates a settings.json file with default parameters based on your ONNX model. 2. Calibrate settings (optional): -``` bash + +```bash ezkl calibrate-settings ``` + This optimizes the settings for resource usage. You can also use `--target accuracy` to optimize for accuracy, and `--target resources` to optimize for resources. 3. Compile model: + ```bash ezkl compile-circuit ``` + This converts your ONNX model into an optimized format for zero-knowledge proofs, creating the `network.ezkl` file. 4. Run setup: + ```bash ezkl setup ``` + This generates the cryptographic keys needed for proving and verifying. +++ Python 1. Generate settings: + ```python import ezkl ezkl.gen_settings("network.onnx") ``` + This creates a `settings.json` file with default parameters based on your ONNX model. 2. Calibrate settings (optional): + ```python ezkl.calibrate_settings("network.onnx", "settings.json", target="resources") ``` + This optimizes the settings for resource usage. You can also use `target="accuracy"` to optimize for accuracy. 3. Compile model: + ```python ezkl.compile_circuit("network.onnx", "network.ezkl", "settings.json") ``` + This converts your ONNX model into an optimized format for zero-knowledge proofs, creating the `network.ezkl` file. 4. Run setup: + ```python ezkl.setup("network.ezkl", "vk.key", "pk.key", "kzg.srs") ``` + This generates the cryptographic keys needed for proving and verifying. +++ JavaScript 1. Generate settings: + ```javascript -import { Engine } from '@ezkljs/engine'; +import { Engine } from "@ezkljs/engine"; const engine = new Engine(); await engine.genSettings("network.onnx"); ``` + This creates a `settings.json` file with default parameters based on your ONNX model. 2. Calibrate settings (optional): + ```javascript -await engine.calibrateSettings("network.onnx", "settings.json", { target: "resources" }); +await engine.calibrateSettings("network.onnx", "settings.json", { + target: "resources", +}); ``` + This optimizes the settings for resource usage. You can also use `{ target: "accuracy" }` to optimize for accuracy. 3. Compile model: + ```javascript await engine.compileCircuit("network.onnx", "network.ezkl", "settings.json"); ``` + This converts your ONNX model into an optimized format for zero-knowledge proofs, creating the `network.ezkl` file. 4. Run setup: + ```javascript await engine.setup("network.ezkl", "vk.key", "pk.key", "kzg.srs"); ``` + This generates the cryptographic keys needed for proving and verifying. +++ Remote CLI (Lilith) + 1. Upload your files, + ```bash archon create-artifact -a test -i input.json -m network.onnx -c calibration.json ``` 2. Generate settings: + ```bash archon job -a test gen-settings ``` + This creates a `settings.json` file with default parameters based on your ONNX model. 3. Calibrate settings (optional): + ```bash archon job -a test calibrate-settings ``` + This optimizes the settings for resource usage. You can also use `--target accuracy` to optimize for accuracy, and `--target resources` to optimize for resources. 4. Compile model: + ```bash archon job -a test compile-circuit ``` + This converts your ONNX model into an optimized format for zero-knowledge proofs, creating the `network.ezkl` file. 4. Run setup: + ```bash archon job -a test setup ``` + This generates the cryptographic keys needed for proving and verifying. +++ + ### Outputs + The setup process will generate the following: + - `network.onnx`: model in ONNX format - `settings.json`: generated file which is optionally calibrated during the setup process - `network.ezkl`: compiled circuit created from your ONNX model in step 3. - `kzg.srs`: Structured Reference String (SRS), which you can download using `ezkl get-srs`. -- `vk.key` and `pk.key`: verification and proving keys generated during the setup process \ No newline at end of file +- `vk.key` and `pk.key`: verification and proving keys generated during the setup process diff --git a/Getting Started/Verify.md b/Getting Started/Verify.md index 478ea8c..0dee2d6 100644 --- a/Getting Started/Verify.md +++ b/Getting Started/Verify.md @@ -2,29 +2,21 @@ icon: checklist order: 93 --- + The lifecycle of an EZKL proof consists of three core components: Setup, Prove, and Verify. This page focuses on the Verify phase, which checks the validity of a proof. Recall that: + - **Setup**: Defines proof parameters and generates keys (performed by developers) - **Prove**: Generates a proof based on the setup (performed by users) - **Verify**: Checks the validity of a proof (performed by verifiers) ### Process -The verification process involves a single step, **verify proof**. This can simply be done in-program or in-browser as demonstrated below. - -However, there is the option of verification on-chain as well (for smart contract applications). Verifying proofs on-chain offers several advantages: -- **Smart Contract Integration**: On-chain verification allows other smart contracts to react to valid proofs, enabling complex decentralized applications. -- **Gas Efficiency**: While initial deployment of the verifier contract may be costly, subsequent verifications are typically much cheaper than performing the full computation on-chain. -- **Reusability**: Once deployed, the verifier contract can be used multiple times, amortizing the initial deployment cost and making it persistently accessible to other calling contracts. -- **Privacy**: On-chain verification maintains the privacy guarantees of the zero-knowledge proof, allowing for confidential data processing in public blockchains -If you are integrating with smart contracts, consider the following: -- `Verifier Contract`: The EZKL-generated verifier contract contains the logic to verify proofs. This contract should be deployed once and can be used for multiple verifications. -- `Proof Submission`: Design your smart contracts to accept proof data as input. This typically includes the proof itself and any public inputs. -- `Result Handling`: The verifier contract's verify function returns a boolean. Your contract should check this result and act accordingly. -- `Gas Optimization`: Consider implementing batched proof verification if your use case involves verifying multiple proofs in a single transaction. -- `Upgradability`: If you anticipate changes to your ML model or proof system, consider implementing upgradeable smart contracts. +The verification process involves a single step, **verify proof**. This can simply be done in-program or in-browser as demonstrated below. ### Parameters + To verify a proof, you'll need the following: + - `proof.json`: proof artifact - `vk.key`: verification key - `settings.json`: settings file @@ -33,11 +25,13 @@ To verify a proof, you'll need the following: Note that if you performed the Prove phase as instructed on the previous page, the CLI automatically pull from the correct paths and you should not have to specify the above parameters. ### Instructions for In-Program Verification + +++ Local CLI ```bash ezkl verify ``` + This verifies the zero-knowledge proof using the provided artifacts. +++ Python @@ -47,16 +41,18 @@ import ezkl ezkl.verify() ``` + This verifies the zero-knowledge proof using the provided artifacts. +++ JavaScript ```javascript -import { Engine } from '@ezkljs/engine'; +import { Engine } from "@ezkljs/engine"; const engine = new Engine(); await engine.verify(); ``` + This verifies the zero-knowledge proof using the provided artifacts. +++ Remote CLI (Lilith) @@ -64,89 +60,13 @@ This verifies the zero-knowledge proof using the provided artifacts. ```bash archon job -a test verify ``` -This verifies the zero-knowledge proof using the provided artifacts. -+++ -### Instructions for On-Chain Verification -+++ Ethereum -1. Generate Solidity verifier contract: -```bash -ezkl create-evm-verifier - -# you can also run it on the proving cluster -archon job -a test create-evm-verifier -archon download-artifact -a test -f evm_deploy.sol -``` -2. Deploy the generated contract to an Ethereum network using your preferred method (e.g., Hardhat, Truffle, or Remix). -3. Interact with the deployed contract: -```solidity -// Example Solidity contract integrating EZKL verification -contract MyContract { - IEZKLVerifier public verifier; - - constructor(address _verifierAddress) { - verifier = IEZKLVerifier(_verifierAddress); - } - - function processProof(bytes calldata proof, uint256[] calldata publicInputs) external { - bool isValid = verifier.verify(proof, publicInputs); - require(isValid, "Invalid proof"); - - // Continue with contract logic for valid proofs - // ... - } -} -``` -4. Call the `processProof` function with the EZKL-generated proof and public inputs. - -+++ EVM-Compatible Chains -The process is similar to Ethereum, so long as the chain has the XXX precompiles. Deploy the generated Solidity contract to your chosen EVM-compatible chain (e.g., Polygon, Binance Smart Chain, Avalanche) and interact with it using the chain's specific tools and SDKs. - -Example for Polygon using Web3.js: -```javascript -const Web3 = require('web3'); -const web3 = new Web3('https://polygon-rpc.com'); - -const verifierABI = [...]; // ABI of the verifier contract -const verifierAddress = '0x...'; // Address of the deployed verifier -const verifier = new web3.eth.Contract(verifierABI, verifierAddress); - -const proof = '0x...'; // Your EZKL-generated proof -const publicInputs = [...]; // Your public inputs - -verifier.methods.verify(proof, publicInputs).call() - .then(isValid => { - if (isValid) { - console.log('Proof is valid'); - // Proceed with further on-chain actions - } else { - console.log('Proof is invalid'); - } - }) - .catch(error => console.error('Verification failed:', error)); -``` -+++ Solana -Support for Solana verification is planned for future releases. Stay tuned for updates. -+++ Other -EZKL is actively working on supporting more blockchain platforms. Check the documentation or reach out to the community for the latest updates on supported chains. +This verifies the zero-knowledge proof using the provided artifacts. +++ ### Outputs + The verification result is a boolean value: + - `true`: The proof is valid. The prover has demonstrated knowledge of inputs that satisfy the circuit constraints. - `false`: The proof is invalid. This could be due to an incorrect proof or tampered input data. - -If you are attempting to read these results from a smart contract, you will need to decode the results. In Solidity, you might handle the result like this: -```solidity -IEZKLVerifier verifier = IEZKLVerifier(verifierAddress); -bool isValid = verifier.verify(proof, publicInputs); - -if (isValid) { - // Proof is valid - proceed with contract logic - emit ProofVerified(msg.sender); - // ... additional logic ... -} else { - // Proof is invalid - handle accordingly - revert("Invalid proof"); -} -``` \ No newline at end of file diff --git a/Getting Started/VerifyOnchain.md b/Getting Started/VerifyOnchain.md new file mode 100644 index 0000000..7557de4 --- /dev/null +++ b/Getting Started/VerifyOnchain.md @@ -0,0 +1,137 @@ +--- +icon: checklist +order: 93 +--- + +The lifecycle of an EZKL proof consists of three core components: Setup, Prove, and Verify. This page focuses on the Verify phase, which checks the validity of a proof. Recall that: + +- **Setup**: Defines proof parameters and generates keys (performed by developers) +- **Prove**: Generates a proof based on the setup (performed by users) +- **Verify**: Checks the validity of a proof (performed by verifiers) + +### Process + +The verification process involves a single step, **verify proof**. This can simply be done in-program or in-browser as demonstrated in the previous article. + +However, there is the option of verification on-chain as well (for smart contract applications). Verifying proofs on-chain offers several advantages: + +- **Smart Contract Integration**: On-chain verification allows other smart contracts to react to valid proofs, enabling complex decentralized applications. +- **Gas Efficiency**: While initial deployment of the verifier contract may be costly, subsequent verifications are typically much cheaper than performing the full computation on-chain. +- **Reusability**: Once deployed, the verifier contract can be used multiple times, amortizing the initial deployment cost and making it persistently accessible to other calling contracts. +- **Privacy**: On-chain verification maintains the privacy guarantees of the zero-knowledge proof, allowing for confidential data processing in public blockchains + +If you are integrating with smart contracts, consider the following: + +- `Verifier Contract`: The EZKL-generated verifier contract contains the logic to verify proofs. This contract should be deployed once and can be used for multiple verifications. +- `Proof Submission`: Design your smart contracts to accept proof data as input. This typically includes the proof itself and any public inputs. +- `Result Handling`: The verifier contract's verify function returns a boolean. Your contract should check this result and act accordingly. +- `Gas Optimization`: Consider implementing batched proof verification if your use case involves verifying multiple proofs in a single transaction. +- `Upgradability`: If you anticipate changes to your ML model or proof system, consider implementing upgradeable smart contracts. + +### Parameters + +To verify a proof, you'll need the following: + +- `proof.json`: proof artifact +- `vk.key`: verification key +- `settings.json`: settings file +- `kzg.srs`: structured Reference String (SRS) file + +Note that if you performed the Prove phase as instructed on the previous page, the CLI automatically pull from the correct paths and you should not have to specify the above parameters. + +### Instructions for On-Chain Verification + ++++ Ethereum + +1. Generate Solidity verifier contract: + +```bash +ezkl create-evm-verifier + +# you can also run it on the proving cluster +archon job -a test create-evm-verifier +archon download-artifact -a test -f evm_deploy.sol +``` + +2. Deploy the generated contract to an Ethereum network using your preferred method (e.g., Hardhat, Truffle, or Remix). +3. Interact with the deployed contract: + +```solidity +// Example Solidity contract integrating EZKL verification +contract MyContract { + IEZKLVerifier public verifier; + + constructor(address _verifierAddress) { + verifier = IEZKLVerifier(_verifierAddress); + } + + function processProof(bytes calldata proof, uint256[] calldata publicInputs) external { + bool isValid = verifier.verify(proof, publicInputs); + require(isValid, "Invalid proof"); + + // Continue with contract logic for valid proofs + // ... + } +} +``` + +4. Call the `processProof` function with the EZKL-generated proof and public inputs. + ++++ EVM-Compatible Chains +The process is similar to Ethereum, so long as the chain has the XXX precompiles. Deploy the generated Solidity contract to your chosen EVM-compatible chain (e.g., Polygon, Binance Smart Chain, Avalanche) and interact with it using the chain's specific tools and SDKs. + +Example for Polygon using Web3.js: + +```javascript +const Web3 = require('web3'); +const web3 = new Web3('https://polygon-rpc.com'); + +const verifierABI = [...]; // ABI of the verifier contract +const verifierAddress = '0x...'; // Address of the deployed verifier +const verifier = new web3.eth.Contract(verifierABI, verifierAddress); + +const proof = '0x...'; // Your EZKL-generated proof +const publicInputs = [...]; // Your public inputs + +verifier.methods.verify(proof, publicInputs).call() + .then(isValid => { + if (isValid) { + console.log('Proof is valid'); + // Proceed with further on-chain actions + } else { + console.log('Proof is invalid'); + } + }) + .catch(error => console.error('Verification failed:', error)); +``` + ++++ Solana +Support for Solana verification is planned for future releases. Stay tuned for updates. ++++ Other +EZKL is actively working on supporting more blockchain platforms. Check the documentation or reach out to the community for the latest updates on supported chains. ++++ + +### Outputs + +The verification result is a boolean value: + +- `true`: The proof is valid. The prover has demonstrated knowledge of inputs that satisfy the circuit constraints. +- `false`: The proof is invalid. This could be due to an incorrect proof or tampered input data. + +If you are attempting to read these results from a smart contract, you will need to decode the results. In Solidity, you might handle the result like this: + +```solidity +IEZKLVerifier verifier = IEZKLVerifier(verifierAddress); +bool isValid = verifier.verify(proof, publicInputs); + +if (isValid) { + // Proof is valid - proceed with contract logic + emit ProofVerified(msg.sender); + // ... additional logic ... +} else { + // Proof is invalid - handle accordingly + revert("Invalid proof"); +} +``` + +˘