update README

README.md

@@ -1,16 +1,83 @@
 # Spectre
-Spectre is a ZK-based block header oracle protocol based on Altair fork light-client sync protocol.
+
+Spectre is a Zero-Knowledge (ZK) coprocessor designed to offload intensive computations from the resource-limited execution layer of target chains. Iit offers a trust-minimized method for verifying block headers, adhering to the consensus rules of the originating chain.
+
+The type of outsourced computation is specific to the arithmetic circuits. For Spectre, its primary function is to verify the Ethereum LightClient protocol introduced in the Altair hardfork.
 
 ## Requirements
-- `build-essential clang pkg-config libssl-dev`
+- Rust `1.73.0-nightly`
+- Packages `build-essential` `clang` `pkg-config` `libssl-dev`
+- [Foundry](https://book.getfoundry.sh/getting-started/installation)
+- [Just](https://just.systems/man/en/)
+
+## Technical details
+
+Spectre prover utilizes the Halo2 proving stack ([`privacy-scaling-explorations/halo2`](https://github.com/privacy-scaling-explorations/halo2) fork).
+
+Circuits are implemented with the [`halo2-lib`](https://github.com/axiom-crypto/halo2-lib) circuit development framework. This library contains a number of non-trivial optimization tricks, while its readable SDK prevents most of the soundness bugs and improves auditability. Our team has contributed a number of features back to the halo2-lib repository, containing some foundational cryptographic primitives powering Ethereum consensus.
+
+Verifier contracts for consensus proofs are auto-generated via the [`privacy-scaling-explorations/snark-verifier`](https://github.com/privacy-scaling-explorations/snark-verifier). We aslo support [`privacy-scaling-explorations/halo2-solidity-verifier`](https://github.com/privacy-scaling-explorations/halo2-solidity-verifier) behind `experimental` flag. Supplemental contract logic has been introduced exclusively to manage intermediary states during proof verifications.
+
+## Usage
+
+### Setup circuits
+
+#### Step circuit
+
+```shell
+cargo run -r -- circuit sync-step-compressed -k 20 -p ./build/sync_step_20.pkey -K 23 -P ./build/sync_step_verifier_23.pkey -L 19 setup
+```
+Flags `-k` and `-K` are circuit degrees for first and aggregation (compression) stage respectively. `-L` is the number lookup bits used in aggregation stage.
+
+#### Committee update circuit
+
+```shell
+cargo run -r -- circuit committee-update -k 20 -p ./build/committee_update_20.pkey -K 24 -P ./build/committee_update_verifier_20.pkey setup
+```
 
-## Deploying contracts
+Alternatively, you can use `just` recipes as shown below.
+
+```shell
+just setup-step-compressed testnet
+just setup-committee-update testnet
+```
+
+### Generates verifier contracts
+
+#### Step proof
+
+```shell
+cargo run -r -- circuit sync-step-compressed -p ./build/sync_step_20.pkey -P ./build/sync_step_verifier_23.pkey gen-verifier -o ./contracts/snark-verifiers/sync_step_verifier.sol
+```
+
+#### Committee update proof
+
+```shell
+cargo run -r -- circuit committee-update -p ./build/committee_update_20.pkey -P ./build/committee_update_verifier_24.pkey gen-verifier -o ./contracts/snark-verifiers/committee_update_verifier.sol
+```
+
+Or use `just` recipes as shown below.
+
+```shell
+just gen-verifier-step-compressed testnet
+just gen-verifier-committee-update testnet
+```
+
+### Deploying contracts
 
 Just scripts are provided to deploy the contracts either to a local testnet, or public networks.
 
 For either make a copy of the `.env.example` file called `.env`. Set the `INITIAL_SYNC_PERIOD`, `INITIAL_COMMITTEE_POSEIDON` and `SLOTS_PER_PERIOD` variables according to the network you want Spectre to act as a light-client for and the starting point.
 
-### Deploying locally
+To get the `INITIAL_COMMITTEE_POSEIDON` value, run:
+
+```shell
+cargo run -r -- utils committee-poseidon --beacon-api https://lodestar-sepolia.chainsafe.io
+```
+
+`--beacon-api` is a URL of the RPC of the targeted Beacon chain.
+
+#### Deploying locally
 
 1. Start a local anvil instance with:
 
@@ -24,7 +91,7 @@ anvil
 just deploy-contracts-local
 ```
 
-### Deploying to a public network
+#### Deploying to a public network
 
 1. Obtain the required gas token and obtain the private key for the deployer account. Set the `DEPLOYER_PRIVATE_KEY` in the `.env` file.
 2. Obtain a public RPC URL for the network and set the variable `<NETWORK>_RPC_URL` in the `.env` file (If using Infura this will require an API key)
@@ -35,3 +102,11 @@ just deploy-contracts <NETWORK>
 ```
 
 where `<NETWORK>` is one of `["GOERLI", "SEPOLIA", "MAINNET"]`.
+
+### Running the prover
+
+Prover is accessible via JSON RPC interface. To start it, run:
+
+```shell
+cargo run -r -- rpc --port 3000
+```

prover/src/args.rs

@@ -150,6 +150,7 @@ pub enum Spec {
 
 #[derive(Clone, clap::Subcommand)]
 pub enum UtilsCmd {
+    /// Get `INITIAL_SYNC_PERIOD`, `INITIAL_COMMITTEE_POSEIDON` for contracts deployment.
     CommitteePoseidon {
         /// Beacon API URL
         #[clap(long, short)]

prover/src/utils.rs

@@ -2,7 +2,7 @@
 // Code: https://github.com/ChainSafe/Spectre
 // SPDX-License-Identifier: LGPL-3.0-only
 
-use std::{ops::Deref, sync::Arc};
+use std::{env, ops::Deref, sync::Arc};
 
 use beacon_api_client::{BlockId, VersionedValue};
 use ethereum_consensus_types::LightClientBootstrap;
@@ -39,7 +39,7 @@ pub(crate) async fn utils_cli(method: UtilsCmd) -> eyre::Result<()> {
             };
 
             let sync_period = bootstrap.header.beacon.slot / (32 * 256);
-            print!("{} \n", sync_period);
+            print!("Sync period: {} \n", sync_period);
             let pubkeys_uncompressed = bootstrap
                 .current_sync_committee
                 .pubkeys
@@ -52,12 +52,12 @@ pub(crate) async fn utils_cli(method: UtilsCmd) -> eyre::Result<()> {
                 .pubkeys
                 .hash_tree_root()
                 .unwrap();
-            println!("ssz root: {:?}", hex::encode(ssz_root.deref()));
+            println!("SSZ root: {:?}", hex::encode(ssz_root.deref()));
 
             let mut committee_poseidon =
                 poseidon_committee_commitment_from_uncompressed(&pubkeys_uncompressed).to_bytes();
             committee_poseidon.reverse();
-            println!("poseidon commitment: {}", hex::encode(committee_poseidon));
+            println!("Poseidon commitment: {}", hex::encode(committee_poseidon));
 
             Ok(())
         }