Github
Community

Kroma MPT Migration Guide

This is a guide on how to transition from ZK Trie to MPT and zkEVM to zkVM

Node Migration

Starting from the KromaMPT hard fork block, MPT (Merkle Patricia Trie) will replace ZK Trie. All node operators must migrate the entire state data to MPT. The migration process will occur automatically upon upgrading the node to the latest version, as long as it is done before the KromaMPT hard fork block.

For Validator Node Operators:

You must complete the upgrade and migration process before the KromaMPT hard fork. Nodes that fail to complete the migration will submit incorrect outputs after the hard fork and may lose staked assets due to challenges.

For Nodes Not Meeting Minimum Requirements or Skipping Migration:

Refer to the migration deactivation option. Alternatively, you can set up a new node using the snapshot provided after the KromaMPT hard fork block.

Minimum Requirements

To ensure smooth migration during the KromaMPT hard fork, the following minimum specifications are recommended:

  • Processor: 4+ cores CPU

    • A CPU with 4 or more cores is recommended as block production and state data migration occur simultaneously.

  • Memory: 16GB+

    • At least 16GB of memory is required due to high memory usage during the state data migration to MPT.

  • Storage: 1TB+ SSD

    • Prepare a high-speed SSD of 1TB or more, as the database size will increase after migration.

Note: These are minimum recommended specifications. Higher specs will result in faster migration.

Guide for Full Node Operators

Using kroma-up (Recommended)

  1. Upgrade to kroma-up v2.1.0+geth.v0.6.0

    1. Update the kroma-up repository to v2.1.0+geth.v0.6.0 (use git pull or clone the repository and git checkout v2.1.0+geth.v0.6.0).

  2. Follow the Guide

    1. Refer to the guide provided in the repository for detailed steps.

For more information on node operation using kroma-up, check here.

Using Docker Images

  1. Update Docker Images

    1. Download the latest images from Docker Hub:

      1. kromanetwork/geth:v0.6.0

      2. kromanetwork/node:v2.1.0

  2. Restart the Node

    1. Restart the node using the updated images.

  3. Modify rollup.json

    1. Edit the rollup.json file to add the "kroma_mpt_time" field under "ecotone_time".

  4. Mainnet Example:

{
  ...
  "ecotone_time": 1714032001,
  "kroma_mpt_time": TBD
}

  1. Sepolia Example:

{
  ...
  "ecotone_time": 1713340800,
  "kroma_mpt_time": TBD
}

If you are unsure how to edit, refer to the respective JSON files:

Guide for Validator Node Operators

After the KromaMPT hard fork, Kroma will transition from the zkEVM Fault Proof system to the zkVM Fault Proof system. Validators using challenger mode will require additional configurations.

Environment Variable Changes

Some environment variable names have been updated. Check these in kroma-up/envs/{network}/validator.env.

Before

After

VALIDATOR_CHALLENGER_POLL_INTERVAL

VALIDATOR_CHALLENGE_POLL_INTERVAL

VALIDATOR_FETCHING_PROOF_TIMEOUT

VALIDATOR_CHALLENGER_ZKEVM_NETWORK_TIMEOUT

VALIDATOR_PROVER_RPC

VALIDATOR_CHALLENGER_ZKEVM_PROVER_RPC

Settings for zkVM Proofs

When challenger mode is enabled, you must set the following RPC values in the .env file:

  • KROMA_VALIDATOR__ZKVM_PROVER_PROXY_RPC

  • KROMA_VALIDATOR__ZKVM_WITNESS_GENERATOR_RPC

Example:

KROMA_VALIDATOR__ZKVM_PROVER_PROXY_RPC=<Your zkVM Prover Proxy RPC>
KROMA_VALIDATOR__ZKVM_WITNESS_GENERATOR_RPC=<Your Witness Generator RPC>

Optional: Historical RPC Settings

If querying past state data (blocks prior to the KromaMPT hard fork) is needed, configure Historical RPC endpoints.

  • Using kroma-up:

    • Edit .env to add:

KROMA_GETH__HISTORICAL_RPC=<Your Historical RPC Endpoint>

  • Direct Node Operations:

    • Add the flag --rollup.historicalrpc="<RPC Endpoint>" when running Geth:

geth ... --rollup.historicalrpc="<Your Historical RPC Endpoint>"

Note: Nodes without Historical RPC cannot submit outputs containing blocks prior to the KromaMPT hard fork.

Migration Deactivation Option

If the node does not meet the minimum specs or migration is unnecessary (e.g., for Historical RPC-only nodes), migration can be deactivated.

  • Using kroma-up:

    • Set the following in .env:

KROMA_GETH__DISABLE_MPT_MIGRATION=true

  • Direct Node Operations:

    • Add the flag --kroma.migration.disable=true.

geth ... --kroma.migration.disable=true

Caution: Nodes with migration disabled will stop syncing blocks after the KromaMPT hard fork.

Block Sync for Disabled Nodes

Nodes with disabled migration must use snapshots available after the KromaMPT hard fork to set up a new node. Note that these nodes cannot generate blocks during the transition period.

Snapshots will be updated within:

  • Sepolia: Up to 2 hours post-hard fork.

  • Mainnet: TBD.

Regular snapshots will also be available daily at 00:00 UTC.

Hard Fork Schedule

  • Kroma Mainnet: TBD

  • Kroma Sepolia: Jan 17th 2024, 05:00 UTC

Steps to Configure a Historical RPC Node

  1. Complete Steps 1-4 for a Full Node Setup

    1. Follow the Full Node setup process, excluding Step 5: Start a Full Node.

  2. Edit the .env File

    1. Open the .env file with a text editor and modify the following values:

      1. Update IMAGE_TAG__KROMA_GETH and IMAGE_TAG__KROMA_NODE to the specified versions.

      2. If these are already set to the versions below, proceed to the next step.

...
IMAGE_TAG__KROMA_GETH=v0.6.0
IMAGE_TAG__KROMA_NODE=v2.1.0
...

  1. Disable MPT Migration

    1. Locate the KROMA_GETH__DISABLE_MPT_MIGRATION field in the .env file and set its value to true.

...
# If you choose not to migrate to MPT, set this to true.
KROMA_GETH__DISABLE_MPT_MIGRATION=true
...

  1. Start the Historical RPC Node

    1. Perform Step 5: Start a Full Node to run the Historical RPC node.

Key Notes for Historical RPC Nodes

  • Historical RPC nodes have MPT migration disabled by default and will not sync to the latest blocks after the KromaMPT hard fork.

  • To minimize unnecessary resource usage, it is recommended to stop the kroma-node service.

  • Command to stop the service:

docker compose -f docker-compose-<network>.yml --profile fullnode stop kroma-node

Prover Migration

From the KromaMPT hard fork, Kroma’s state tree will transition from ZKTrie to MPT (Merkle Patricia Trie). Kroma employs zk proofs during the challenge process to correct invalid L2 outputs submitted to L1. Before the KromaMPT hard fork, the zkEVM Prover generated zk proofs for Kroma using ZKTrie. Post-hard fork, zk proofs will be generated using the zkVM Prover, which supports Kroma’s MPT-based state.

To achieve this, two components are required:

  • Witness Generator: Provides the input (witness) required to generate SP1 proofs.

  • Prover Proxy: Sends the witness and the target guest program to the SP1 prover network to obtain the proof.

This guide outlines the steps to upgrade the Challenger component for the KromaMPT hard fork.

Minimum Requirements

  • Witness Generator

    • Processor: 4+ cores CPU

    • Memory: 4GB+

    • Storage: 100GB+ (SSD or HDD)

  • Prover Proxy

    • Processor: 2+ cores CPU

    • Memory: 2GB+

    • Storage: 50GB+ (SSD or HDD)

Environment Variable Configuration

Witness Generator

Ensure the following configurations are included in the .env file:

# Configuration for running a Witness generator.
L1_RPC=<Geth RPC Endpoint For L1 with Debug API Enabled>
L1_BEACON_RPC=<Endpoint For L1 Beacon>
L2_RPC=<Geth RPC Endpoint For L2 with Debug API Enabled>
L2_NODE_RPC=<Node RPC Endpoint For L1>

# In the case of witness generator, it MUST be filled in.
MAX_BATCH_POST_DELAY_MIN=<MAXIMUM_DELAY_BETWEEN_L2BATCHES>

ROLLUP_CONFIG_FROM_FILE=true

# Optional
SKIP_SIMULATION=false

  • L1_RPC and L2_RPC must have the debug API enabled.

  • If running the witness generator before the MPT time, ensure ROLLUP_CONFIG_FROM_FILE is set to true. Check the MPT time for each network.

  • MAX_BATCH_POST_DELAY_MIN represents the maximum batch interval for the batcher. This varies by network:

    • KromaHolsky: 20

    • KromaSepolia: 20

    • KromaMainnet: 20

  • Note: The relationship between MAX_BATCH_POST_DELAY_MIN and BATCHER_MAX_CHANNEL_DURATION is: MAX_BATCH_POST_DELAY_MIN = BATCHER_MAX_CHANNEL_DURATION * 12 / 60.

  • Set SKIP_SIMULATION to true to enable self-verification of the generated witness. If your system has fewer than 8 CPU cores, it is recommended to set it to false.

Prover Proxy

Include the following configuration in the .env file:

# API key in order to use SP1's prover network.
SP1_PRIVATE_KEY=<NEED_TO_BE_ISSUED_FROM_SUCCINCT_TEAM>

Please note that the SP1 API Key is now only provided who are whitelisted. Succinct team will make it publicly accessible within a few weeks.

Using Docker Images

  1. Download Docker Images

    1. Obtain the latest or specified versions of the images from Docker Hub:

      1. zkp/witness-gen:v1

      2. zkp/prover-proxy:v1

  2. Run Docker Containers

Witness Generator:

docker run -itd --env-file .env -p 3030:3030 zkp/witness-gen:v1

Prover Proxy:

docker run -itd --env-file .env -p 3031:3031 zkp/prover-proxy:v1

Using Source Code

For source code setup, refer to the README.md file in the kroma-sp1-prover repository.

With this guide, you can prepare the Witness Generator and Prover Proxy components to ensure proper zkVM-based zk proof generation for the KromaMPT hard fork.

PreviousNode OperatorsNextRunning a Full Node

Last updated