A developer-friendly, rollup-based Ethereum Layer 2 solution that offers low fees and EVM equivalence.

  • By Kroma
  • Last update: Aug 8, 2023
  • Comments: 16


This is a client for Kroma network.


If you want to build Kroma, check out the Protocol Specs.


Read through CONTRIBUTING.md for a general overview of our contribution process. Use the Developer Quick Start to get your development environment set up to start working on the Kroma repository. Then check out our list of good first issues to find something fun to work on!




  • 1

    feat(node): update validator reward ratio on L1Block contract

    The name of the Fee Vault has been updated:

    • L1FeeVault -> ProposerRewardVault
    • ProposerFeeVault -> ValidatorRewardVault
    • BaseFeeVault -> ProtocolVault

    And, to distribute the transaction fee to the Protocol Vault and the Validator Reward Vault, the ValidatorRewardRatio value in the L1Block contract is updated.

    Related: #19

  • 2

    chore: rename organization and project

    As part of the rebranding of WEMIX Kanvas to Kroma, this commit includes changes to rename the name of the GitHub organization and the project to Kroma:

    • All components in the format of kanvas-xxx are changed to kroma-xxx.
    • The organization name, previously wemixkanvas, is changed to kroma-network.
    • The wemixkanvas.io domain is changed to kroma.network.
    • All other texts related to Kanvas are changed to Kroma.
  • 3

    docs: rewrite description of zkevm-prover

    Add more description of kroma-prover in detail.

    • on zkevm-prover.md, explanation of the workflow of kroma-prover was added.
    • on challenge.md, add code which calculates public input
  • 4

    test(e2e): mock challenger RPC in e2e actions test

    This PR is based on fix/validator-e2e branch.

    As mentioned in #71, validator and challenger RPC rollup client is mocked for challenge E2E test.

    In addition, there are some fixes in public input:

    • change the type of gasLimit to uint64
    • fix bitwise operating in handling pair data (there were some errors in testing real data)
  • 5

    feat(contracts): reward via portal to L2 vault when the output is finalized

    When output is submitted to L2OutputOracle, it calls a function in L2 ValidatorRewardVault via CrossDomainMessenger to reward the submitter. Once the output is finalized, the submitter can receive this reward.

    Related #19

  • 6

    chore: inject git tag as a version

    The Makefile is modified to set the versions of the binaries using git tag. The versions are managed using git tag and GitHub release, and the version of the binaries is set to the tag associated with the commit.

  • 7

    fix(contracts): fix logic after output finalized in challenger timeout


    Related to https://github.com/chainlight-io/2023-kroma-network-audit-issues-client/issues/9 reported by theori audit. Fixed an issue where, for a challenge to a finalized output root, the asserter could not take the bond even if the challenger went into a timeout state.

  • 8

    feat!(validator): rename output submitter and challenger flags

    Renamed two validator flags for consistency and readability: VALIDATOR_OUTPUT_SUBMITTER_ENABLED and VALIDATOR_CHALLENGER_ENABLED, both are required.

    At first, we named the flags with *_DISABLED. If no value is set, it was to turn on the output submitter and challenger by default.

    With this renaming, we should provide a sample .env file with default value of true for both flags for guide of running Kroma node.

  • 9

    feat: update integrations for securityCouncil and related testing and deployment code


    Update colosseum contract integration for securityCouncil and related testing and deployment code.

    • Integration with Security council Added code to perform a final validation request for the output to the security council upon passing proveFault in Colosseum.
    • Migrate contract changes to chain-ops and deploy-config
    • Test updates for changes to securityCouncil and colosseum contract.

    Related #18

  • 10

    feat: update public input hash computation

    Since our prover code is bumped up to version based on scroll zkevm v0.3, the public input hash computation is changed as follows.

    The main changes are followings:

    • The instance part of the final pair is represented using two values instead of one because the bn256 curve cannot fully represent the result of the keccak 256 hash, which is a bytes32 value. By splitting it into two values, we can accommodate the complete representation of the hash result.
    • In the process of obtaining a dummy transaction hash, we ended up using the zero address as the value for the to field.
    • In the public input hash, the fields for coinbase, difficulty, and chain ID were omitted, while the fields for block hash, parent hash, and withdrawals root were included.
  • 11

    feat!(challenger): change challenge handling to event-driven for multiple challenges


    Challenge handling is changed from polling-based to event-driven way. As multiple challenges can be created simultaneously, the validator can properly handle multiple challenges at the same time.

    To handle outputs in the past and within the finalization window, scanPrevOutputs has also been implemented.

    Tx nonce collision

    Validator has two components: L2 output submitter and challenger. Since each component sends transaction with the same account, should be very careful with nonce collisions. To avoid it, Validator would have a channel for transaction, txCandidatesChan. The created tx candidates will be transferred to txCandidateChan in each component, and txmgr will process the tx candidates sequentially.


    1. E2E tests have not been handled yet, just fixed type error. It will be handled after all the features are implemented.
    2. Moved existing challenger functions down.

    This PR has a slightly complicated structure, using several go routines to concurrently process multiple challenges. I'd appreciate you for your detailed review.

  • 12

    feat(contracts): add contracts about `Multi sig based proxy upgrade`


    Contracts and related code have been written for the Multi sig based proxy upgrade. A contract upgrade is only possible if the vote following the proposal passes. Voting privileges are granted based on a token for this purpose, which in this case is security council members. If a proposal is voted on and passed, it will be executed after being delayed by a set timelock. The delay in upgrading by Timelock will be more than a month. (https://ethereum-magicians.org/t/proposed-milestones-for-rollups-taking-off-training-wheels/11571)

    NOTE: Additional audits are underway and feedback will be adjusted.

  • 13

    Setup continous deployment of npm packages publishment

    Issue Type


    Kroma Version


    Current Behaviour?

    There is no continuous deployment setup to publish npm packages.

    Expected Behaviour

    When a new version of Kroma is released, a new version of npm packages should be released as well with the same version of Kroma

  • 14

    Improve validation of multiple outputs

    Issue Type


    Kroma Version


    Current Behaviour?

    When validating multiple outputs (when scanning previous outputs or missed output submitted event), validator fetches and validates output one by one. To improve the performance of validation, it should fetch multiple outputs at once and validate it.

    Expected Behaviour

    Validator can fetch multiple outputs and validate them.

  • 15

    Allow multiple validators to submit output

    Issue Type

    Feature Request

    Kroma Version


    OS Platform and Distribution

    Linux Ubuntu 22.04

    Go version

    go1.19.3 linux/amd64

    Node version



    Currently a single validator only submits output, which is called validation. For the next release, we want to contain permissionless validation.


    1. Fee vaults would be divided into three categories based on its purpose. Proposer Reward Vault, Protocol Vault and Validator Reward Vault.
    2. Validators need to submit output with a bond of at least minimum bond amount.
    3. Validators receive a reward in exchange for submitting an output.
    4. Validators needs to initiate a challenge with a bond.
    5. The amount of minimum bond and reward can dynamically vary depending on the protocol.

    Optimism distinguishes between three different types of funding sources: ProposerFeeVault, BaseFeeVault, and RollupFeeVault, based on their origin. In the upcoming release of Kroma, funds will be divided into ProposerRewardVault, ProtocolVault, and ValidatorRewardVault, based on their purpose. The ProposerRewardVault will be similar to the existing RollupFeeVault. Of the total fee (sum of base fee and priority fee), a proportion R (Validator Reward Ratio) will go to the ValidatorRewardVault, while the remaining amount will go to the ProtocolVault. The funds in the ValidatorRewardVault will be used solely for rewarding validators, while the ProtocolVault will be used for the development of the protocol.

    R is designed considering the following:

    • R is not fixed but dynamically set depending on the situation.
    • R is updated in the L1Block contract via DepositTx when every L2 block is created.
    • However, we haven't found any factors that would change the current R, so we'll need to do some research and temporarily fix it at a certain value. (probably 0.2)

    To participate in the validation process, a validator must stake a certain amount of bond, but if the bonding amount is too high, the profitability will decrease, and if it is too low, it may lead to abuse. Therefore, to ensure that the staking profitability is similar to that of ETH staking, it is important to set $R_{min}$ and $R_{max}$ appropriately. If the output submitted by a validator is successfully finalized, they can claim a share of the amount present in the ValidatorRewardVault at that time proportional to their contribution. However, there is a submission timeout for validation, and if the output is not submitted within that timeout, the trusted validator will receive the reward.

    In addition, the validation bonding amount should be proportional to the ValidatorRewardVault and inversely proportional to the number of pending output submissions.

    B_{required} = \alpha \times \frac {V_{vault}}{B_{base} \times O_{waiting}}, \text{where } 0 \le \alpha \lt 1 \\
    B_{required} = \text{The required bonding amount} \\
    V_{vault} = \text{The balance of validator reward vault} \\
    B_{base} = \text{The base bonding amount, 1 / (10 *24 * 7) ETH} \\
    O_{waiting} = \text{The number of waiting output submission} \\

    On the other hand, the challenge bonding amount is initially similar to the validation bonding amount, but as the finalized period approaches, the required amount increases. This is to prevent attacks that try to prevent the output from being finalized by challenging it at the last minute. Currently, the finalization period of our chain is 7 days after the output submission, and there is only one challenge, so there are no immediate problems such as delay attacks, but it is still an issue that needs to be discussed. In a similar context, the challenge reward ratio also decreases as the finalization period approaches.


    As a first implementation, the protocol will reward only the one who submits the output the fastest. Such a design will make only a few validators with high-spec devices participate in the network. To prevent this, we need to use VRF (verifiable random function) or Round-robin to ensure that everyone has a fair chance.


    • [x] Activate ValidatorPool.sol and Colosseum.sol. allow only registered validators to submit output with a bond. (https://github.com/kroma-network/kroma/pull/53)
    • [x] Require a challenger to stake a bond to initiate challenge. (https://github.com/kroma-network/kroma/pull/53)
    • [x] Unbond if the associated output has passed finalization period. (https://github.com/kroma-network/kroma/pull/53)
    • [x] The Security Council must approve the challenge result when the challenger wins. (https://github.com/kroma-network/kroma/pull/64)
    • [x] Give the validator a validation reward if the associated output has passed finalization period, and the validator or someone else submits the output. (https://github.com/kroma-network/kroma/pull/61)
    • [ ] Update validator reward ratio at every output submission.
    • [x] Rename ProposerFeeVault.sol, BaseFeeVault.sol and RollupFeeVault.sol. (https://github.com/kroma-network/kroma/pull/47)
    • [x] Distribute (base fee + priority fee) into ProtocolVault.sol and ValidationRewardVault.sol. (https://github.com/kroma-network/go-ethereum/pull/36)
    • [x] Set coinbase/suggestFeeRecipient to zero address.
  • 16

    Support debugging by attaching go process which is run by docker compose

    Issue Type

    Feature Request

    Kroma Version


    OS Platform and Distribution

    Linux Ubuntu 22.04

    Go version

    go1.19.3 linux/amd64

    Node version

    No response

    Current Behaviour?

    In ops-devnet/docker-compose.yaml, set pid to host on kanvas-node.

      pid: host

    And then set ptrace_scope to 0

    > sudo su -
    > echo 0 >  /proc/sys/kernel/yama/ptrace_scope

    And then if I try to debug by attaching go process is rejected with this message.

    Failed to attach: Could not attach to pid 39997: current user does not own the process.

    Which feature do you want to expect?

    I expect the process is launched with uid:gid so that we are able to debug. Currently, we should rely on the log message, which is very difficult when we consider that the logs are emitted so long.