Running a 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 bond $ETH to submit an output. Both the validator reward and the bond amount are subject to governance decisions.

To learn more about the road to Kroma’s decentralization, 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 Mainnet and run a local node.

• Submit checkpoint outputs to Layer 1(Ethereum).

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

For more detailed information on Kroma’s architecture, please refer to this Medium article.

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, Bisection, 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.

Bisection

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, an initial bond of 0.2 ETH is required. This bond acts as a security deposit and is necessary to participate in the network. Upon the finalization of your output, you will be rewarded, aiming at a 10% APR when $ETH is used.

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 selection of the validator with the assertion priority is chosen at random for each submission.

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	60 blocks	1800 blocks
validatorPoolNonPenaltyPeriod	20 seconds	600 seconds
validatorPoolPenaltyPeriod	40 seconds	1200 seconds
finalizationPeriodSeconds	600 seconds	604800 seconds (7 days)
colosseumBisectionTimeout	120 seconds	120 seconds
colosseumProvingTimeout	480 seconds	7200 seconds
colosseumSegmentsLengths	“4,3,6,3”	“9,6,10,6”
validatorPoolMinBondAmount	0.1 ETH	0.2 ETH

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: Deposit into ValidatorPool

To enable your validator node to submit checkpoint outputs or challenges, you need to deposit a certain amount of Ethereum into the ValidatorPool to be used as a bond for each output submission. The bonding amount for each output submission is 0.2 ETH.

You can deposit your ETH into the ValidatorPool contract either via the running kroma-validator container or via CLI. Note that to run commands via CLI, you should clone the kroma git repository and run the commands in the directory you cloned the repo.

Deposit via the running kroma-validator container:

> docker exec kroma-validator kroma-validator deposit --amount 1000000000000000000 #(unit:wei)

Deposit via CLI:

> cd components/validator
> go run ./cmd/main.go \
  --valpool-address <validator-pool-address> \ # must be set
  --l1-eth-rpc <l1-eth-rpc> \
  --mnemonic <mnemonic> \
  --hd-path <hd-path> \
  --rollup-rpc "" \ # empty required flags
  --l2oo-address "" \
  --colosseum-address "" \
  --challenger.poll-interval 0s \
  deposit \
  --amount <amount-wei> # must be set

valpool-address means ValidatorPool proxy address on Ethereum Sepolia, which can be found here. For more details, please refer to the Github documentation.

Withdraw from ValidatorPool

If you want to withdraw some or all of your deposited amount in ValidatorPool, you can withdraw via the running kroma-validator container or via CLI. Keep in mind that if the deposited amount is lower than the minimum bonding amount, your validator node will not be eligible for output submission.

Withdraw via the running kroma-validator container:

> docker exec kroma-validator kroma-validator withdraw --amount 1000000000000000000 #(unit:wei)

Withdraw via CLI:

> cd components/validator
> go run ./cmd/main.go \
  --valpool-address <validator-pool-address> \ # must be set
  --l1-eth-rpc <l1-eth-rpc> \
  --mnemonic <mnemonic> \
  --hd-path <hd-path> \
  --rollup-rpc "" \ # empty required flags
  --l2oo-address "" \
  --colosseum-address "" \
  --challenger.poll-interval 0s \
  withdraw \
  --amount <amount-wei> # must be set

Manually Unbond in ValidatorPool

The bonded ETH of a checkpoint output is automatically unbonded after the finalization time. As the finalization of the output is checked when new outputs are submitted, sometimes you may need to wait an additional hour after the finalization time if a new output is not submitted yet to check your output’s finalization. In such cases, you can directly try to unbond in ValidatorPool via the running kroma-validator container or via CLI commands.

Try unbond via the running kroma-validator container:

> docker exec kroma-validator kroma-validator unbond

Try unbond via CLI:

> cd components/validator
> go run ./cmd/main.go \
  --valpool-address <validator-pool-address> \ # must be set
  --l1-eth-rpc <l1-eth-rpc> \
  --mnemonic <mnemonic> \
  --hd-path <hd-path> \
  --rollup-rpc "" \ # empty required flags
  --l2oo-address "" \
  --colosseum-address "" \
  --challenger.poll-interval 0s \
  unbond

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.