Mina zkApp: Eth-processor

How to build

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:

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.

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.

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

npm run coverage

License

Apache-2.0