From 6e279449460e5d31e937f2d62062c14ad5cd5068 Mon Sep 17 00:00:00 2001 From: Filip Krawczyk Date: Tue, 19 Nov 2024 20:05:12 +0100 Subject: [PATCH] README reorder --- README.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 596951c5..528ac2ad 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ Integrity is a STARK proof verifier written in cairo language and deployed on St - [Prerequisites](#prerequisites) - [Using Verifier contracts on Starknet](#using-verifier-contracts-on-starknet) +- [FactRegistry and Proxy contract](#factregistry-and-proxy-contract) - [Calls from Starknet contracts](#calls-from-starknet-contracts) - [Running locally](#running-locally) - [Creating a Proof](#creating-a-proof) @@ -52,6 +53,21 @@ This bash script internally calls `verify_proof_full_and_register_fact` function To generate split calldata, please refer to [Calldata Generator README](https://github.com/HerodotusDev/integrity-calldata-generator/blob/main/README.md). This repository also provides script for automatic transaction sending (proof verification is split into multiple transactions, for more information see [Split Verifier Architecture](#split-verifier-architecture)). +## FactRegistry and Proxy contract + +Since verifier can be configured in many ways and some parts of the logic changes with new stone versions, a contract which routes calls to the correct verifier is needed. This task is handled by FactRegistry contract that also stores data for all verified proofs. + +After proof is verified, `FactRegistered` event is emitted which contains `fact_hash`, `verification_hash`, `security_bits` and `settings`. `fact_hash` is a value that represents proven program and its output (formally `fact_hash = poseidon_hash(program_hash, output_hash)`). Remember that registration of some `fact_hash` doesn't necessary mean that it has been verified by someone with secure enough proof. You always need to check `security_bits` and `settings` which is part of `verification_hash` (formally `verification_hash = poseidon_hash(fact_hash, security_bits, settings)`). + +For more detailed and visual representation of those hash calculations, check out [Integrity Hashes Calculator](https://integrity-hashes-calculator.vercel.app/) tool. It generates all mentioned hashes for arbitrary user input and even proof JSON file. + +`FactRegistry` provides two methods for checking verified proofs: + +- `get_verification(verification_hash)` - returns fact hash, security bits and settings for given `verification_hash`. +- `get_all_verifications_for_fact_hash(fact_hash)` - returns list of all verification hashes, security bits and settings for given `fact_hash`. This method is useful for checking if given program has been verified by someone with secure enough proof. + +FactRegistry contract is trustless which means that the owner of the contract can't override or change any existing behavior, they can only add new verifiers. Proxy contract on the other hand is upgradable, so every function can be changed or removed. It has the advantage of having all future updates of the verifier logic without having to replace the address of FactRegistry contract. Proxy contract provides the same interface as FactRegistry with additional `get_fact_registry` method which returns address of FactRegistry contract. + ## Calls from Starknet contracts Since integrity is deployed on Starknet, other contracts can call FactRegistry to check whether certain proof has been verified. Integrity can be used as a dependency of your cairo1 project by including it in project's `Scarb.toml`: @@ -253,8 +269,6 @@ bash deployment/verifiers///register.sh ## Split Verifier Architecture -### Background information - Because of great complexity of the verifier compared to standard starknet contracts, we encounter some limitations enforced by starknet. The most important ones are: - Contract classhash size limit @@ -262,16 +276,3 @@ Because of great complexity of the verifier compared to standard starknet contra - Transaction steps limit To overcome these limitations, we split the verifier into multiple contracts and transactions. The biggest part of classhash size is autogenerated (e.g. [recursive autogenerated](/src/air/layouts/recursive/autogenerated.cairo)), so we extracted that part into separate contract (or many contracts in case of `starknet_with_keccak` layout), which is called automatically by the main verifier contract. On the other hand the biggest part of calldata is fri witness, so user can send subsequent chunks of fri witness in separate step transactions. - -### FactRegistry and Proxy contract - -Since verifier can be configured in many ways and some parts of the logic changes with new stone versions, a contract which routes calls to the correct verifier is needed. This task is handled by FactRegistry contract that also stores data for all verified proofs. - -After proof is verified, `FactRegistered` event is emitted which contains `fact_hash`, `verification_hash`, `security_bits` and `settings`. `fact_hash` is a value that represents proven program and its output (formally `fact_hash = poseidon_hash(program_hash, output_hash)`). Remember that registration of some `fact_hash` doesn't necessary mean that it has been verified by someone with secure enough proof. You always need to check `security_bits` and `settings` which is part of `verification_hash` (formally `verification_hash = poseidon_hash(fact_hash, security_bits, settings)`). - -`FactRegistry` provides two methods for checking verified proofs: - -- `get_verification(verification_hash)` - returns fact hash, security bits and settings for given `verification_hash`. -- `get_all_verifications_for_fact_hash(fact_hash)` - returns list of all verification hashes, security bits and settings for given `fact_hash`. This method is useful for checking if given program has been verified by someone with secure enough proof. - -FactRegistry contract is trustless which means that the owner of the contract can't override or change any existing behavior, they can only add new verifiers. Proxy contract on the other hand is upgradable, so every function can be changed or removed. It has the advantage of having all future updates of the verifier logic without having to replace the address of FactRegistry contract.