# Mina zkApp: Eth-processor

## Exports

### Node.js api

```typescript
import { EthProcessor, MinaEthProcessorSubmitter, wait } from '@nori-zk/ethprocessor/node';
// EthProcessor: a Mina smart contract that accepts a verified, converted consensus MPT transition proof and stores state on the Mina blockchain.
// MinaEthProcessorSubmitter: a tool that facilitates committing state to the EthProcessor contract using a converted consensus MPT transition proof.
// wait : Polls the Mina RPC for a transaction's status until it's included or a max retry limit is reached.
```

### Browser api

```typescript
import { EthProcessor } from '@nori-zk/ethprocessor/browser';
// EthProcessor: a Mina smart contract that accepts a verified, converted consensus MPT transition proof and stores state on the Mina blockchain.
```

## How to build

```sh
npm run build
```

## Configuration

Env vars (create a .env file):

```
MINA_RPC_NETWORK_URL=
SENDER_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.
- **TX_FEE**: transaction fee to be used when submitting transactions.
- **NETWORK**: specifies the target network (e.g., `mainnet`, `devnet`, `litenet`).

- **ZKAPP_PRIVATE_KEY**: private key for the zkApp account. Will be generated by `npm run deploy <storeHashHex> <[optional]adminPublicKeyBase58>` 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 <storeHashHex> <[optional]adminPublicKeyBase58>` and written to `.env.nori-eth-processor`.

## 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 update-store-hash`
- `npm run prove-and-submit`
- `MinaEthProcessorSubmitter.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.  
Set up your `.env` file in the root directory. Set:

- `MINA_RPC_NETWORK_URL=<url>`
- `NETWORK=<mainnet or devnet or litenet>`
- `SENDER_PRIVATE_KEY=<your-private-key>`

Run `npm run deploy <storeHashInHex> <[optional]adminPublicKeyBase58>`.

The `<storeHashInHex>` must match the `input_store_hash` of the first store you expect as a checkpoint.
The `<adminPublicKeyBase58>` can be the public key of the account which you wish to be the admin of the deployed contract (with permissions to call the `initialize`, `setVerificationKey` and `updateStoreHash` contract methods). If not provided then it will be automatically derived from the `SENDER_PRIVATE_KEY` environment variable provided.

You can find sensible values by:  
- Running the bridge head  
- Inspecting the checkpoint you want to start from in the proof output message directory:  
  `sp1-helios-proof-messages/<file-with-slot-height>.json`  
- Locating the `input_store_hash` and using it as the `<storeHashInHex>`, **omitting** the `0x` prefix.
After running deploy, a `.env.nori-eth-processor` file will be created in the root directory containing:

ZKAPP_PRIVATE_KEY=...  
ZKAPP_ADDRESS=...
Copy these values into your `.env` file.

## How to update a store hash

Run `npm run update-store-hash <storeHashInHex>`  

The `<storeHashInHex>` must match the `input_store_hash` of the store you expect as a checkpoint.

You can find sensible values by:  
- Running the bridge head  
- Inspecting the checkpoint you want to start from in the proof output message directory:  
  `sp1-helios-proof-messages/<file-with-slot-height>.json`  
- Locating the `input_store_hash` and using it as the `<storeHashInHex>`, **omitting** the `0x` prefix.

## 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)

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.

Peform the following steps, if EthVerifiers vk's have been updated, due to a change to a public input / output that it relies upon:

Run `npm run bake-vk-hashes`.
Run `npm run deploy`.

## 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`

```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)