https://github.com/zksecurity/stark-evm-adapter
Adapt your STARK stone proofs for verifications on Ethereum
https://github.com/zksecurity/stark-evm-adapter
annotations evm stark stone-prover
Last synced: 4 months ago
JSON representation
Adapt your STARK stone proofs for verifications on Ethereum
- Host: GitHub
- URL: https://github.com/zksecurity/stark-evm-adapter
- Owner: zksecurity
- Created: 2023-11-02T01:18:31.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-02T21:29:23.000Z (over 1 year ago)
- Last Synced: 2025-09-14T22:36:14.771Z (5 months ago)
- Topics: annotations, evm, stark, stone-prover
- Language: Rust
- Homepage: https://zksecurity.github.io/stark-evm-adapter/stark_evm_adapter/index.html
- Size: 3.36 MB
- Stars: 17
- Watchers: 4
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# STARK-EVM adapter
[
](https://github.com/zksecurity/stark-evm-adapter)
[
](https://crates.io/crates/stark-evm-adapter)
[
](https://docs.rs/stark-evm-adapter)
[
](https://github.com/zksecurity/stark-evm-adapter/actions?query=branch%main)
stark-evm-adapter is a library that provides a set of utilities to parse and manipulate the output of the STARK [stone proof](https://github.com/starkware-libs/stone-prover).
Specifically, the library can be used to generate a "split proof", which is necessary for proofs to be verified on Ethereum.
```toml
[dependencies]
stark-evm-adapter = "0.1.3"
```
## Example
```rust
use stark_evm_adapter::annotated_proof::AnnotatedProof;
use stark_evm_adapter::annotation_parser::split_fri_merkle_statements;
// read an annotated proof
let file = std::fs::File::open("tests/fixtures/annotated_proof.json").unwrap();
let reader = std::io::BufReader::new(file);
let annotated_proof: AnnotatedProof = serde_json::from_reader(reader).unwrap();
// split the proof
let split_proofs = split_fri_merkle_statements(annotated_proof).unwrap();
println!("{}", serde_json::to_string_pretty(&split_proofs).unwrap());
// For how to submit the split proofs to the L1 EVM verifier, please refer to the demo: https://github.com/zksecurity/stark-evm-adapter/blob/8af44a0aa61c89e36a08261320f234709e99ed71/examples/verify_stone_proof.rs#L18
```
Note that the annotated proof file, `annotated_proof.json`, can be generated using this CLI tool.
## CLI
### Installation
```bash
cargo install stark_evm_adapter
```
### Usage
```bash
stark_evm_adapter --help
```
To generate an annotated proof based on the outputs of the stone-prover:
```bash
stark_evm_adapter gen-annotated-proof \
--stone-proof-file tests/fixtures/stone_proof.json \
--stone-annotation-file tests/fixtures/stone_proof_annotation.txt \
--stone-extra-annotation-file tests/fixtures/stone_proof_annotation_extra.txt \
--output annotated_proof.json
```
The annotated proof originates from 3 file outputs of the [stone-prover](https://github.com/starkware-libs/stone-prover/tree/00b274b55c82077184be4c0758f7bed18950eaba#creating-and-verifying-a-proof-of-a-cairozero-program).
* `stark_evm_adapter --stone-proof-file` comes from `cpu_air_prover --out_file` (JSON format)
* `stark_evm_adapter --stone-annotation-file` comes from `cpu_air_verifier --annotation-file` (.txt format)
* `stark_evm_adapter --stone-extra-annotation-file` comes from `cpu_air_verifier --extra-output-file` (.txt format)
Once you have this annotated proof, you can use it to generate the split proofs and submit them to the L1 EVM verifier. Please refer to the [example demo](https://github.com/zksecurity/stark-evm-adapter/blob/8af44a0aa61c89e36a08261320f234709e99ed71/examples/verify_stone_proof.rs#L18)
## Demo
You can run the demo to split the proof and submit it to the Ethereum mainnet verifier. The [existing proof](./examples/bootloader/fib_annotated_proof.json) contains an internal proof that the 10th Fibonacci number is 144.
### Using existing proof
First, install Anvil using [Foundry](https://book.getfoundry.sh/getting-started/installation)
Then, run the following command:
```bash
FORK_URL= \
ANNOTATED_PROOF=./annotated_proof.json \
FACT_TOPOLOGIES=./fact_topologies.json \
cargo run --example verify_stone_proof
```
### Generate new proof
You can create a new proof using Docker
#### Prerequisites
- Copy `objects.py` and `utils.py` for bootloader as `hidden/bootloader-objects.py` and `hidden/bootloader-utils.py`
- Copy `objects.py` and `utils.py` for simple bootloader as `hidden/simple-bootloader-objects.py` and `hidden/simple-bootloader-utils.py`
- Copy `cpu_air_prover` and `cpu_air_verifier` binaries generated from [stone-prover](https://github.com/starkware-libs/stone-prover) into the `./examples/bootloader/stone-prover` directory (Can also use the binaries from this [release](https://github.com/zksecurity/stark-evm-adapter/releases/tag/v0.1.0-alpha))
#### Customize program that is being proven
- Replace `TASK_PROGRAM_INPUT_PATH` and `TASK_PROGRAM_COMPILED_PATH` variables in `test_bootloader_fib.py` with your own program.
#### Run
First, build the docker image. This will create an annotated proof and a fact topologies file that is needed to split the proof for verifying on Ethereum:
```bash
docker build -t stark-evm-adapter .
```
Then, run the demo script:
```bash
docker run -it -e FORK_URL= -e ANNOTATED_PROOF=./examples/bootloader/gen/annotated_proof.json -e FACT_TOPOLOGIES=./examples/bootloader/gen/fact_topologies.json stark-evm-adapter
```
### Note
- Alternatively, you can use `URL` instead of `FORK_URL` env to submit transactions on-chain instead of running them on a fork.
- This example verifies proofs on [`0xd51a3d50d4d2f99a345a66971e650eea064dd8df`](https://etherscan.io/address/0xd51a3d50d4d2f99a345a66971e650eea064dd8df), which is the previous version of the verifier on Ethereum. The most recent version is [`0x9fb7F48dCB26b7bFA4e580b2dEFf637B13751942`](https://etherscan.io/address/0x9fb7F48dCB26b7bFA4e580b2dEFf637B13751942), and we are working to update this example to use the most recent version.