Running a Kroma v2 Validator Node

Why Run a Validator Node on Kroma?

Kroma uniquely integrates Optimistic Rollup and zkEVM with decentralized and permissionless validators, meaning anyone can participate as a validator in the Kroma network. Participating in Kroma's validator network not only promotes the network's decentralization but also earns rewards for the submission of checkpoint outputs upon their finalization. You'll need to deposit certain amount of KRO tokens to join the validator network, and bond KRO tokens within your deposit amount to submit an output.

To learn more about the initiative of the validator system v2, please check out this Medium article.

What a Validator Node does on Kroma

A validator node on Kroma should perform the following tasks:

• Synchronize the blocks and transactions with the Kroma Mainnet by running a local node.

• Submit checkpoint outputs to Layer 1(Ethereum).

• Initiate a challenge if an invalid checkpoint output is identified.

For more details, please refer to the specification.

A Brief Introduction to the Challenge System of Kroma

When a validator detects that a submitted L2 output root contains an invalid state transition, it can start a dispute challenge process by triggering the Colosseum contract. We refer to a validator who submits a dispute challenge as a "challenger" and a validator who initially submitted an L2 output as an "asserter." A dispute challenge entails a confrontational interaction between an asserter and a challenger, which persists until one of them emerges victorious. Detection, Dissection, and Proof Submission completes a cycle of a challenge.

Detection

A challenge starts with a validator detecting an invalid checkpoint output that is submitted by another validator. The validator who detects a difference between its local output and the submitted output initiates a dispute challenge process by calling createChallenge function in Colosseum.sol.

Dissection

After a challenge is successfully created, the asserter(the validator who submitted a potentially invalid checkpoint output) and the challenger(the validator who started the challenge) will take turns to bisect until the challenger finds a single block to prove fault.

Proof Submission

Once the challenger finds a single step of a block to prove fault, the challenger generates a ZK fault proof on the specific block and submit the proof to Verifier.sol. To generate a ZK fault proof, the challenger must run a kroma-prover client.

For more details on the challenge process, please refer to this link.

Incentive Mechanism

When running a validator node, a minimum staking of 10,000 KRO is required to join the validator network. Also, when submitting a checkpoint output, 5,000 KRO is bonded with the output. Upon the finalization of your output, you will receive your bonded KRO back and be rewarded with 400 KRO.

To ensure the network's integrity, it is necessary for one of the validators to submit a checkpoint output every 1800 blocks, which is equivalent to approximately 1 hour. The probability of being selected as the validator with the assertion priority is directly proportionate to the sum of deposit amount and KRO delegation amount of the validator.

Please note that some parameters are set differently on Ethereum Sepolia testnet compared to Ethereum mainnet to provide a faster test environment. Refer to the following table for the differences:

Parameter	Ethereum Sepolia	Ethereum Mainnet
l2OutputOracleSubmissionInterval	300 L2 blocks	1800 L2 blocks
validatorManagerMinRegisterAmount	100 KRO	10,000 KRO
validatorManagerMinActivateAmount	100 KRO	10,000 KRO
assetManagerBondAmount	50 KRO	5,000 KRO
validatorManagerBaseReward	4 KRO	400 KRO
validatorManagerCommissionChangeDelaySeconds	43,200 sec (12 hrs)	1,209,600 sec (14 days)
validatorManagerSoftJailPeriodSeconds	7,200 sec (2 hrs)	259,200 sec (3 days)
validatorManagerHardJailPeriodSeconds	21,600 sec (6 hrs)	604,800 sec (7 days)
validatorManagerJailThreshold	max 2 times	max 2 times
assetManagerMinDelegationPeriod	21,600 sec (6 hrs)	604,800 sec (7 days)
validatorPriorityRound	300 sec	1,800 sec
validatorPublicRound	300 sec	1,800 sec
finalizationPeriodSeconds	21,600 sec (6 hrs)	604,800 sec (7 days)
colosseumCreationPeriodSeconds	18,000 sec (5 hrs)	518,400 sec (6 days)
colosseumBisectionTimeout	1,800 sec	3,600 sec (1 hr)
colosseumProvingTimeout	14,400 sec (4 hrs)	28,800 sec (8 hrs)
colosseumSegmentsLengths	"6,5,6,4"	"9,6,10,6"

How to Run a Validator Node

The process of running a validator node entails several steps, including hardware setup, software installation, and node configuration. These steps also encompass the process of depositing into the ValidatorPool and managing your deposit.

STEP 0: Hardware Requirements

The following are the minimum and recommended hardware requirements to run a validator on Kroma:

	Minimum	Recommended
kroma-geth	CPU with 2+ cores 4GB RAM 512GB free storage space to sync the Mainnet 8 MBit/sec download Internet service	Fast CPU with 4+ cores 16GB+ RAM High-performance SSD with at least 512GB of free space 25+ MBit/sec download Internet service
kroma-node	CPU with 1+ cores 2GB RAM	CPU with 2+ cores 4GB+ RAM
kroma-validator	CPU with 1+ cores 2GB RAM	CPU with 2+ cores 4GB+ RAM
kroma-prover	CPU with 48 cores 384GB RAM	CPU with 128 cores 1024GB RAM

Note: kroma-prover is expensive and only needed when a challenge occurs. It is recommended to turn it on and off as needed to generate a ZK fault proof. Therefore, we provide an additional Docker image for a lightweight proxy server that turns the prover client on only when a ZK fault proof for a block needs to be generated and turns it off afterward. Step-by-step guide on how to set up a kroma-prover client and a kroma-prover-proxy client is provided below.

STEP 1: Install Prerequisites

We recommend using Docker to run a node on Kroma. Make sure you have Docker and Git installed.

STEP 2: Clone the kroma-up Git Repository

Clone the kroma-up Git repository and navigate to the cloned directory:

> git clone https://github.com/kroma-network/kroma-up.git
> cd kroma-up

Note: Please ensure you are cloning to the latest version of the repository.

STEP 3: Start up the Environment

Run the following command to generate keys and environment variables required to run a node:

> ./startup.sh <network>

STEP 4: Configure the Validator Node

Step 3 will generate a .env file with default values. Configure the .env file according to your requirements. Here are the environment variables in the .env file:

[Environment variables in .env file]

Name	Description
NETWORK_NAME	The name of the network to run on. The values available are mainnet or sepolia.
IMAGE_TAG__KROMA_GETH	The docker image tag of kroma-geth. Default value is provided while generating the .env file.
IMAGE_TAG__KROMA_NODE	The docker image tag of kroma-node. Default value is provided while generating the .env file.
IMAGE_TAG__KROMA_VALIDATOR	The docker image tag of kroma-validator. Default value is provided while generating the .env file.
KROMA_NODE__L1_RPC_ENDPOINT	The HTTP RPC endpoint of Layer 1
KROMA_VALIDATOR__L1_RPC_ENDPOINT	The websocket RPC endpoint of Layer 1
KROMA_GETH__BOOT_NODES	The address of a bootnode for kroma-geth client. Default value is provided while generating the .env file.
KROMA_NODE__BOOT_NODES	The address of a bootnode for kroma-node client. Default value is provided while generating the .env file.
KROMA_VALIDATOR__MNEMONIC	The mnemonic phrase of the Ethereum account connected to the validator client. This should be provided along with the HD path value. When this value is provided, the private key value should be empty.
KROMA_VALIDATOR__HD_PATH	The HD path of the Ethereum account connected to the validator client. This should be provided along with the mNemonic value. When this value is provided, the private key value should be empty.
KROMA_VALIDATOR__PRIVATE_KEY	The private key of the Ethereum account connected to the validator client. When this value is provided, the mnemonic and HD path values should be empty.
KROMA_VALIDATOR__OUTPUT_SUBMITTER_ENABLED	A flag to determine if the validator node is going to submit checkpoint outputs. Default value is true.
KROMA_VALIDATOR__ALLOW_PUBLIC_ROUND	A flag to determine if the validator node is going to submit an output in public round. Default value is false.
KROMA_VALIDATOR__CHALLENGER_ENABLED	A flag to determine if the validator node is going to validate unfinalized checkpoint outputs and initiate a challenge if an invalid checkpoint output is detected. Default value is false.
KROMA_VALIDATOR__GUARDIAN_ENABLED	A flag for the Security Council member. Members of the Security Council are whitelisted and only those can operate as a Guardian. Default value is false.
KROMA_VALIDATOR__PROVER_RPC	The RPC address of the kroma-prover client. If KROMA_VALIDATOR__CHALLENGER_ENABLED is true, this value must be provided.
KROMA_PROVER_PROXY__PROVER_BASE_DIR	The base directory of proofs of prover. We recommend using the values provided by default.
KROMA_PROVER_PROXY__PROVER_URL_SCHEMA	The prover url schema of prover. We recommend using the values provided by default.
KROMA_PROVER_PROXY__PROVER_RPC_PORT	The RPC port of prover. We recommend using the values provided by default.
KROMA_PROVER_PROXY__AWS_REGION	If you are using AWS Access Key, the information must be provided.
KROMA_PROVER_PROXY__AWS_ACCESS_KEY_ID	If you are using AWS Access Key, the information must be provided.
KROMA_PROVER_PROXY__AWS_SECRET_ACCESS_KEY	If you are using AWS Access Key, the information must be provided.
KROMA_PROVER_PROXY__PROVER_INSTANCE_ID	Currently, Kroma-prover-proxy only supports AWS, so you'll need to enter the AWS EC2 instance ID where the Kroma-prover is running.
KROMA_PROVER_PROXY__PROVER_ADDRESS_TYPE	You need to specify in which network environment the kroma-prover-proxy will call kroma-prover. If kroma-prover-proxy and kroma-prover are on the same network, set it to private so that the communication is internal However, if they are on different networks, set it to public so that kroma-prover can utilize the public IP of the instance it is running on.

For more information on environment variables, please refer to the Github documentation.

Now, open the .env file:

> vim .env

Set the values for your Ethereum account to connect the validator client with your account. You can choose either the private key or the mnemonic and HD path values.

[Example for Using Private Key]

#.env (it was created in "STEP 3: Start up the environment")
...
VALIDATOR_PRIVATE_KEY=${YOUR_ETH_PRIVATE_KEY}

# It should be kept as an empty value.
VALIDATOR_MNEMONIC=
VALIDATOR_HD_PATH=

[Example for Using Mnemonic and HD Path]

#.env (it was created in "STEP 3: Start up the environment")
...
VALIDATOR_MNEMONIC=${YOUR_ETH_MNEMONIC}
VALIDATOR_HD_PATH=${YOUR_ETH_HD_PATH}

# It should be kept as an empty value.
VALIDATOR_PRIVATE_KEY=

[Example for Validator as an OutputSubmitter]

#.env (it was created in "STEP 3: Start up the environment")
...
KROMA_VALIDATOR__OUTPUT_SUBMITTER_ENABLED=true
KROMA_VALIDATOR__CHALLENGER_ENABLED=false

# It should be kept as an empty value.
KROMA_VALIDATOR__PROVER_RPC=

[Example for Validator as a Challenger (w/ Prover RPC setting)]

#.env (it was created in "STEP 3: Start up the environment")
...
KROMA_VALIDATOR__OUTPUT_SUBMITTER_ENABLED=false
KROMA_VALIDATOR__CHALLENGER_ENABLED=true
KROMA_VALIDATOR__PROVER_RPC=${YOUR_KROMA_PROVER_CLIENT_RPC_ADDRESS}

[Example for Validator as Both an Output Submitter and a Challenger (w/ Prover RPC setting)]

#.env (it was created in "STEP 3: Start up the environment")
...
KROMA_VALIDATOR__OUTPUT_SUBMITTER_ENABLED=true
KROMA_VALIDATOR__CHALLENGER_ENABLED=true
KROMA_VALIDATOR__PROVER_RPC=${YOUR_KROMA_PROVER_CLIENT_RPC_ADDRESS}

Please note that either KROMA_VALIDATOR__OUTPUT_SUBMITTER_ENABLED or KROMA_VALIDATOR__CHALLENGER_ENABLED must be set to true to operate as a validator node.

STEP 5: Start the Prover Node

Please note that the kroma-prover instance should be running on AWS Cloud, as currently the kroma-prover-proxy only supports AWS.

The kroma-prover client must be up and running before starting the kroma-validator because the kroma-validator requires the RPC endpoint of the kroma-prover client.

Setup Prover Params

> ./setup_prover.sh

Run Prover

> docker compose -f docker-compose-<network>.yml --profile prover up -d

Check if the kroma-prover client has successfully started

> docker compose -f docker-compose-<network>.yml logs -f kroma-prover

If you see the log saying [KROMA] Prover server starting on 0.0.0.0:3030, this means that your kroma-prover client has successfully started.

STEP 6: Start the Validator Node with Prover-Proxy Client

Set up AWS IAM Role

You can run the kroma-prover-proxy on other cloud services, but the kroma-prover must be run on AWS.

The kroma-prover-proxy client should have the authorities to start and stop the kroma-prover EC2 instance.

The AWS roles that are required to be set are:

• REGION: The region of the kroma-prover EC2

• ACCOUNT_ID: The AWS account id of the kroma-prover EC2

• INSTANCE_ID: The instance ID of the kroma-prover EC2

An example of the IAM role setting is provided below:

# kroma-prover-proxy-role.json

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:StopInstances",
                "ec2:StartInstances"
            ],
            "Resource": "arn:aws:ec2:${REGION}:${ACCOUNT_ID}:instance/${INSTANCE_ID}"
        },
        {
            "Action": [
                "ec2:DescribeInstances",
                "ec2:DescribeTags"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

To learn more about how to create and manage AWS IAM roles, please refer to the official AWS guides below:

• https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html

• https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html

Grant role to the kroma-prover-proxy(on AWS)

Please refer to the official AWS guide on how to grant the role to a EC2 instance:

• https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html

Grant role to the kroma-prover-proxy(on other cloud services)

To control an AWS instance from outside, you need to have an access key for the IAM user. Please refer to the links below to generate the access key:

• https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html

• https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html

Apply the required values to the .env variables

> vim .env

# .env

...
KROMA_VALIDATOR__CHALLENGER_ENABLED=true
KROMA_VALIDATOR__PROVER_RPC=http://kroma-prover-proxy:6000
KROMA_PROVER_PROXY__AWS_REGION=${YOUR_KROMA_PROVER_EC2_REGION}
KROMA_PROVER_PROXY__AWS_ACCESS_KEY_ID=${YOUR_KROMA_PROVER_EC2_ACCESS_KEY_ID}
KROMA_PROVER_PROXY__AWS_SECRET_ACCESS_KEY=${YOUR_KROMA_PROVER_EC2_SECRET_ACCESS_KEY}
KROMA_PROVER_PROXY__PROVER_INSTANCE_ID=${YOUR_KROMA_PROVER_INSTANCE_ID}
KROMA_PROVER_PROXY__PROVER_ADDRESS_TYPE=private # if you're not running the kroma-prover-proxy on AWS, the value should be 'public'

If you have followed the previous steps, you can now start your validator node. Ensure that Docker is running, and execute the following command:

> docker compose -f docker-compose-<network>.yml --profile validator+proxy up -d

Please make sure you stop the kroma-prover instance started on STEP 5 because your kroma-prover-proxy client will turn it on and off automatically when needed.

STEP 7: Register as a Validator in the KRO-based Validator System

You need to register for ValidatorManager contract with KRO deposit to participate in the new KRO-based validator system as a validator. The deposited asset will be used as a bond for each output submission, or challenge creation. The minimum amount of deposit is 10,000 KRO, and the bond amount for each output submission is 5,000 KRO. For example, if you register with 10,000 KRO deposit, your validator will be able to submit outputs up to 2 times in a finalization window.

You can register by running command via the running kroma-validator docker container.

Register via the running kroma-validator container:

> docker exec kroma-validator kroma-validator register --amount 10000000000000000000000 --commission-rate 10 --withdraw-account 0x0000000000000000000000000000000000000001

The meaning of each flag in the command:

• --amount: The amount of KRO to deposit (in wei).

• --commission-rate: The commission rate of the validator (in %).

• --withdraw-account: The address which can withdraw the validator’s asset. Once set, it cannot be changed.

We separated withdraw account from the validator address to mitigate the management risk of validator key which is exposed as an environment variable. Even if the private key of the validator got hacked, you can safely withdraw all of your assets with the withdraw account. Therefore, be sure to keep the key of the address registered as your withdrawal account safe(e.g. using hard wallet or similar).

Deposit Additional KRO to the Validator

If you want to deposit additional KRO tokens after registration, you should deposit to the AssetManager contract, not to the ValidatorManager contract.

You can deposit by running command via the running kroma-validator docker container.

> docker exec kroma-validator kroma-validator depositKro --amount 10000000000000000000000

Withdraw

As mentioned above, you can only withdraw the accumulated KRO tokens of your validator with withdraw account you registered. So to withdraw your asset, you should call the withdraw function in Etherscan by connecting your withdraw account and submitting a withdraw transaction with the amount to withdraw.

Note that you can withdraw your asset when below conditions are met:

1. MIN_DELEGATION_PERIOD passed since your last deposit time.

2. If you are in jail, the expiration time of jail should be passed.

3. Only your KRO not bonded can be withdrawn.

Change Commission Rate

You can change the commission rate set during registration, but it requires two steps to prevent a validator changing the commission rate without any notifications to the delegators. First, you initiate the change, which has no immediate effect. Then, after a minimum of 14 days, you can finalize the change to make it effective.

Note that you cannot initiate or finalize the commission change when you are in jail.

You can initiate and finalize the commission change by running command via the running kroma-validator docker container.

> docker exec kroma-validator kroma-validator changeCommission init --commission-rate 5
> docker exec kroma-validator kroma-validator changeCommission finalize

Unjail

If a validator fails to submit outputs three times when selected as a priority validator, it is jailed for 3 days. If a validator loses a challenge and gets slashed, it is jailed for 7 days. After the jail period ends, the validator can unjail itself by submitting a tryUnjail transaction.

You can unjail by running command via the running kroma-validator docker container.

> docker exec kroma-validator kroma-validator unjail

Remove a Running Validator Node

To remove a running validator node, you can use the following command:

> docker compose -f docker-compose-<network>.yml --profile validator down -v

Please note that removing a running node does not automatically withdraw the Ethereum deposited by the validator node. Even if you forget to withdraw your deposit before removing the node, you can always access your assets by re-running the validator node with the same Ethereum account environment variable settings. This ensures that your deposited funds are not lost and can be easily recovered when running the validator node again.

Monitoring Your Validator Node

Step 1: Setting Up the Monitoring Containers

1. Open a terminal on the machine hosting your validator node.

2. Navigate to the directory containing your docker-compose.yml file.

3. To start the monitoring containers in detached mode, run the following command:

docker compose -f docker-compose-<network>.yml --profile monitoring up -d

This command will spin up the necessary containers for Grafana and Prometheus.

Step 2: Accessing Grafana and Prometheus

Once the monitoring containers are up and running, you can access Grafana and Prometheus through your web browser.

• Grafana is available at localhost:3000

• Prometheus is available at localhost:9090

Step 3: Logging into Grafana

1. In your web browser, go to http://localhost:3000.

2. Log in with the following credentials:

   • Username: admin

   • Password: password

Step 4: Accessing the Validator Dashboard

To view the monitoring dashboard for your validator node:

1. Navigate to Home > Dashboards > Kroma > Validator.

2. Here, you will find a dashboard displaying metrics related to the performance and health of your validator node.

Step 5: Understanding Prometheus Metrics Collection

Prometheus collects metrics from your validator node using the internal Docker network. It is configured to scrape metrics from kroma-validator:7300. This setup allows Prometheus to gather data on the node's operation, and system health indicators.