@nori-zk/ethprocessor/README.md

zkApp for verifying SP1 Helios Nori proof and storing latest execution state root on Mina

# Mina zkApp: Eth-processor

## How to build

```sh
npm run build
```

## Configuration

Env vars (create a .env file):

```
MINA_RPC_NETWORK_URL=
SENDER_PRIVATE_KEY=
ADMIN_PRIVATE_KEY=
TX_FEE=

ZKAPP_PRIVATE_KEY=
ZKAPP_ADDRESS=

NETWORK=
```

- **MINA_RPC_NETWORK_URL**: Mina network RPC endpoint URL.
- **SENDER_PRIVATE_KEY**: private key of the transaction sender.
- **ADMIN_PRIVATE_KEY**: private key for administrative control operations.
- **TX_FEE**: transaction fee to be used when submitting transactions.

- **ZKAPP_PRIVATE_KEY**: private key for the zkApp account. Will be generated by `npm run deploy` if not provided and written to `.env.nori-eth-processor`.
- **ZKAPP_ADDRESS**: deployed address of the zkApp contract. Will be generated by `npm run deploy` and written to `.env.nori-eth-processor`.

- **NETWORK**: specifies the target network (e.g., `mainnet`, `devnet`, `litenet`).

## How to Bake Integrity Hashes

When you modify your programs (`EthProcessor` or `EthVerifier`), or update any public inputs/outputs due to changes in zk programs we are dependent upon (e.g., from `proof-conversion` or `bridge-head`), you must recompile your programs and update the integrity hashes.

To do this, run:

```bash
npm run bake-vk-hashes
```

This command regenerates and updates the verification key hashes in:

```
src/integrity/<o1js-eth-program-name>.VkHash.json
```

These hashes are checked at runtime during:

- `npm run deploy`
- `npm run prove-and-submit`
- `compileContracts` (API method)

If the o1js cache is corrupted or stale — resulting in mismatched verification keys — these commands will deliberately throw an error to prevent invalid or inconsistent program states.

## How to deploy (launch a new contract)

Make sure to clear your o1js cache, if it exists already.
Setup your `.env` file in the root directory. Set `MINA_RPC_NETWORK_URL=<url>`, `NETWORK=<mainnet or devnet or litenet>` and your `SENDER_PRIVATE_KEY`.

Run `npm run deploy <storeHashInHex>`. The `<storeHashInHex>` must match the `input_store_hash` of the first store you expect as a checkpoint. After which `.env.nori-eth-processor` will have been created in the root directory of the project. You can find sensible values by running the bridge head and inspecting the checkpoint you wish the start from the proof output message directory of `sp1-helios-proof-messages/<file-with-slot-height>.json` finding the `input_store_hash` and using that as the `<storeHashInHex>` but ommiting the `0x` prefix.

```
ZKAPP_PRIVATE_KEY=...
ZKAPP_ADDRESS=...
```

Copy these to your `.env` file.

## How to submit a new converter proof

Edit the `src/proofs/sp1Proof.json` file using the output retrieved from the bridge head within the `sp1-helios-proofs` directory. Convert this proof via the `proof-conversion` repository using the `sp1ToPlonk` command. Then, update `src/proofs/p0.json` with the converted proof data retrieved from the output of the proof conversion (`<proof-data-output>.proofData`).

Note: You only need to update `nodeVk.json` from the output of the proof conversion if the proof conversion program’s VK has changed.

Each time the bridge head ZK, proof conversion ZK, EthProcessor, or EthVerifier changes, you must redeploy the Mina smart contract with `npm run deploy` after baking in your new VK hashes via `npm run bake-vk-hashes`.

Then finally: `npm run prove-and-submit`.

## How to re-deploy (updating an existing contract - WIP)

The verification key used in the deploy/redeploy command is computed from the stored zk programs directly but validated against the
integrity hashes before one is allowed to deploy / prove-and-submit.

If you need to update your store hash and verification key:

Run `npm run bake-vk-hashes`
Run `npm run deploy <storeHashInHex>`. After which `.env.nori-eth-processor` will have been created in the root directory of the project.

If you only need to update your verification key:

Run `npm run bake-vk-hashes`
Run `npm run deploy`. After which `.env.nori-eth-processor` will have been created in the root directory of the project.

```
ZKAPP_PRIVATE_KEY=...
ZKAPP_ADDRESS=...
```

Copy `.env.nori-eth-processor` values to your `.env`.

## Troubleshooting

You may experience problems with o1js's cache being stale. If you expect your projects vks have change, then remove the `~/.cache/o1js/` contents before running `npm run deploy`.

## How to run tests

Obtain your SENDER_PRIVATE_KEY environment variable:

1. `npm install -g zkapp-cli`
2. `zk lightnet start`
3. `curl localhost:8181/acquire-account`
4. Put the `sk` in your `.env` file: SENDER_PRIVATE_KEY=......
5. Put `MINA_RPC_NETWORK_URL=http://localhost:8080/graphql` in your `.env` file.
6. Put `NETWORK=lightnet` in your `.env` file.

```sh
npm run test # all tests (hangs due to multiple instances of o1js deps)
npm run test -- -t "should perform a series of proof submissions" # run a specific test
npm run testw # watch mode
```

Note tests can hang after a 3rd round of proof computation. Particularly when running multiple tests within the same context. Try running them one by one like `npm run test --t <testName>` if this this is happening to you. Or use the command below which mitigates the issue.

```sh
npm run test-ci # Runs a series of tests, as a set of processes with forceExit after each (mitigation for now). 
```

## How to run coverage

```sh
npm run coverage
```

## License

[Apache-2.0](LICENSE)