Mina zkApp: Eth-processor

Exports

Node.js api

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

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

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:

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

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