Merge branch 'master' into 74-lookup-compatibility

README.md

@@ -1,91 +1,136 @@
-# EVM Placeholder Proof System Verifier 
+# EVM Placeholder proof system verifier 
 
 [![Discord](https://img.shields.io/discord/969303013749579846.svg?logo=discord&style=flat-square)](https://discord.gg/KmTAEjbmM3)
 [![Telegram](https://img.shields.io/badge/Telegram-2CA5E0?style=flat-square&logo=telegram&logoColor=dark)](https://t.me/nilfoundation)
 [![Twitter](https://img.shields.io/twitter/follow/nil_foundation)](https://twitter.com/nil_foundation)
 
-This repository contains the smart contracts for validating zero knowledge proofs 
-generated in placeholder proof system in EVM. 
+An application for in-EVM validation of zero-knowledge proofs generated
+with
+the [Placeholder proof system](https://nil.foundation/blog/post/placeholder-proofsystem).
 
 ## Dependencies
 
 - [Hardhat](https://hardhat.org/)
-- [nodejs](https://nodejs.org/en/) >= 16.0
+- [Node.js](https://nodejs.org/) - Hardhat requires an LTS version of Node.js; as of September 2023 it's v18
 
+## Contract Addresses
 
-## Clone
+| Network      | Address |
+| ----------- | ----------- |
+| Sepolia      | [`0x489dbc0762b3d9bd9843db11eecd2a177d84ba2b`](https://sepolia.etherscan.io/address/0x489dbc0762b3d9bd9843db11eecd2a177d84ba2b)      |
+
+## Installing with npm
+
+You can install the package via `npm` from the command line:
+
+```bash
+npm install @nilfoundation/[email protected]
+```
+
+or add it to the `package.json` file manually:
+
+```json
+"@nilfoundation/evm-placeholder-verification": "1.1.1"
 ```
+
+## Contributing
+
+Clone the project from GitHub:
+
+```bash
 git clone [email protected]:NilFoundation/evm-placeholder-verification.git
+```
+
+After that, navigate to the `evm-placeholder-verification` directory:
+
+```bash
 cd evm-placeholder-verification
 ```
 
 ## Install dependency packages
-```
+
+```bash
 npm i
 ```
 
 ## Compile contracts
-```
+
+```bash
 npx hardhat compile
 ```
 
 ## Deploy
 
-Launch a local-network using the following
-```
+Launch a local network using the following command:
+
+```bash
 npx hardhat node
 ```
 
-To deploy to test environment (ex: Ganache)
-```
-npx hardhat deploy  --network localhost 
+Don't close the terminal and don't finish this process, the Hardhat node should be
+running for the next steps.
+
+To deploy to a test environment (Ganache, for example), run the following
+from another terminal:
+
+```bash
+npx hardhat deploy --network localhost
 ```
 
-Hardhat re-uses old deployments, to force re-deploy add the `--reset` flag above
+Hardhat reuses old deployments by default; to force re-deploy,
+add the `--reset` flag to the command.
+
+## Testing
+
+Tests are located in the `test` directory.
+To run tests:
+
+```bash
+npx hardhat test # Execute tests
+REPORT_GAS=true npx hardhat test # Test with gas reporting
+```
 
-## Verification of zkLLVM circtuit compiler output
+## Local verification of zkLLVM circuit compiler output
 
-zkLLVM compiler prepares circuits in form of instantiated contracts, which have to be deployed to the blockchain.
+[zkLLVM compiler](https://github.com/NilFoundation/zkllvm) prepares circuits
+as instantiated contracts that can be deployed to a blockchain.
 
-Once you got zkLLVM output - put a circuit directory it under `contracts/zkllvm`. The folder should contain following files:
+Once you get zkLLVM output, create a circuit directory under `contracts/zkllvm` for your output.
+That directory should contain the following files:
 
 ```
-* proof.bin -- placeholder proof file
-* circuit_params.json -- parameters file in JSON format
-* public_input.json -- public input file in JSON format
-* linked_libs_list.json -- list of external libraries, have to be deployed for gate argument computation.
-* gate_argument.sol, gate0.sol, ... gateN.sol -- solidity files with gate argument computation
+* proof.bin — Placeholder proof file
+* circuit_params.json — parameters file
+* public_input.json — file with public input
+* linked_libs_list.json — list of external libraries that have to be deployed for gate argument computation
+* gate_argument.sol, gate0.sol, ... gateN.sol — Solidity files with gate argument computation
 ```
 
-If all the files are in place - you can deploy the circuit verifier to the blockchain and verify the proofs.
+If all these files are in place, you can deploy the verifier app and verify the proofs.
 You only need to deploy the verifier once, and then you can verify as many proofs as you want.
 
-Deploy contracts
-```
+Deploying the contracts:
+
+```bash
 npx hardhat deploy
 ```
 
-If you've put the circuit under, let's say, `contracts/zkllvm/circuit-name` directory, you can verify the proofs with the following command:
-```
-npx hardhat verify-circuit-proof --test circuit-name
-```
+If you've put the files under, let's say, `contracts/zkllvm/circuit-name` directory,
+you can verify the proofs with the following:
 
-To verify all circuits from `contracts/zkllvm` directory:
-```
-npx hardhat verify-circuit-proof-all
+```bash
+npx hardhat verify-circuit-proof --test circuit-name
 ```
 
-## Testing
-
-Tests are located in `test` directory. To run tests:
+To verify all circuits from `contracts/zkllvm` directory, run:
 
-```
-npx hardhat test #Execute tests
-REPORT_GAS=true npx hardhat test # Test with gas reporting
+```bash
+npx hardhat verify-circuit-proof-all
 ```
 
 ## Community
 
-Issue reports are preferred to be done with Github Issues in here: https://github.com/NilFoundation/evm-placeholder-verification/issues.
+Submit your issue reports to the project's [Github Issues](https://github.com/NilFoundation/evm-placeholder-verification/issues).
 
-Usage and development questions are preferred to be asked in a Telegram chat: https://t.me/nilfoundation or in Discord (https://discord.gg/KmTAEjbmM3)
+Join us on our [Discord server](https://discord.gg/KmTAEjbmM3) or in our [Telegram chat](https://t.me/nilfoundation)
+and ask your questions about the verifier's usage and development.