diff --git a/specs/SUMMARY.md b/specs/SUMMARY.md index 81c1326..2e8f898 100644 --- a/specs/SUMMARY.md +++ b/specs/SUMMARY.md @@ -19,15 +19,14 @@ - [Span Batches](./protocol/span-batches.md) - [Batch Submitter](./protocol/batcher.md) - [Validator](./protocol/validation.md) - - [ETH-based Validator System](protocol/validator-v1/validator-pool.md) - [KRO-based Validator System](protocol/validator-v2/overview.md) - [Validator Manager](protocol/validator-v2/validator-manager.md) - [Asset Manager](protocol/validator-v2/asset-manager.md) - [Predeploys](./protocol/predeploys.md) - [System Config](./protocol/system-config.md) -- [Fault Proof]() - - [Challenge](./fault-proof/challenge.md) - - [zkEVM Prover](./fault-proof/zkevm-prover.md) +- [ZK Fault Proof]() + - [Challenge](zk-fault-proof/challenge.md) + - [zkVM Prover](zk-fault-proof/zkvm-prover.md) - [Experimental]() - [ZK Fault Dispute Game](./experimental/zk-fault-dipute-game/overview.md) - [Fault Proof System V2](./experimental/fault-proof-system-v2/overview.md) @@ -37,4 +36,7 @@ - [Challenge](./experimental/fault-proof-system-v2/challenge.md) - [Security Council Intervention](./experimental/fault-proof-system-v2/security-council-intervention.md) - [Improvements](./experimental/fault-proof-system-v2/improvements.md) +- [Deprecated]() + - [zkEVM Prover](deprecated/zkevm-prover.md) + - [ETH-based Validator System](deprecated/validator-v1/validator-pool.md) - [Glossary](./glossary.md) diff --git a/specs/protocol/validator-v1/validator-pool.md b/specs/deprecated/validator-v1/validator-pool.md similarity index 97% rename from specs/protocol/validator-v1/validator-pool.md rename to specs/deprecated/validator-v1/validator-pool.md index 5a79ba6..bb4a0ce 100644 --- a/specs/protocol/validator-v1/validator-pool.md +++ b/specs/deprecated/validator-v1/validator-pool.md @@ -20,14 +20,14 @@ ## Validator Pool Smart Contract Only accounts registered as [Validator][g-validator] can submit [output][g-l2-output] to -the [L2 Output Oracle](../validation.md#l2-output-oracle-smart-contract). +the [L2 Output Oracle](../../protocol/validation.md#l2-output-oracle-smart-contract). To register as a [Validator][g-validator], you must deposit at least `REQUIRED_BOND_AMOUNT` of ETH into the `ValidatorPool` contract. When submitting the output, the validator must bond Ethereum for `REQUIRED_BOND_AMOUNT`, which will be unbonded and rewarded to the L2 `ValidatorRewardVault` contract when the output is finalized. Also, validators should stake their bond for disputing challenge. This bond will be given to the winner of the challenge -as a reward. When this reward distributed, a [tax](../../fault-proof/challenge.md) is imposed to prevent collusive +as a reward. When this reward distributed, a [tax](../../zk-fault-proof/challenge.md) is imposed to prevent collusive attacks of asserter and challenger. Validator Pool Smart Contract implements the following interface: diff --git a/specs/fault-proof/zkevm-prover.md b/specs/deprecated/zkevm-prover.md similarity index 100% rename from specs/fault-proof/zkevm-prover.md rename to specs/deprecated/zkevm-prover.md diff --git a/specs/experimental/fault-proof-system-v2/challenge.md b/specs/experimental/fault-proof-system-v2/challenge.md index 039c8bd..746792f 100644 --- a/specs/experimental/fault-proof-system-v2/challenge.md +++ b/specs/experimental/fault-proof-system-v2/challenge.md @@ -34,7 +34,7 @@ ## Overview -Similar to [V1](../../fault-proof/challenge.md), the challenge process in Fault Proof System V2 revolves around +Similar to [V1](../../zk-fault-proof/challenge.md), the challenge process in Fault Proof System V2 revolves around interactively dissecting [outputs][g-checkpoint-output] to find the first disagreeing block, thereby proving the validity of the [state][g-state] transition. @@ -362,7 +362,7 @@ asserter or challenger executed the correct transactions, as described in [Transaction Data Commitment](./transaction-data-commitment.md). The `OutputRootProof` and `PublicInputProof` in the previous -[proving fault](../../fault-proof/challenge.md#proving-fault) have been changed as follows. The `OutputRootProof` was +[proving fault](../../zk-fault-proof/challenge.md#proving-fault) have been changed as follows. The `OutputRootProof` was changed accordingly by removing `nextBlockHash` from the [output root][g-l2-output] payload as described in [Output Root Payload (Version 1)](./output-proposal.md#output-root-payload-version-1), and some fields for on-chain verification of [batch data][g-sequencer-batch] and [user-deposited transaction][g-user-deposited] data have been added diff --git a/specs/experimental/fault-proof-system-v2/improvements.md b/specs/experimental/fault-proof-system-v2/improvements.md index 14fcb80..66f924c 100644 --- a/specs/experimental/fault-proof-system-v2/improvements.md +++ b/specs/experimental/fault-proof-system-v2/improvements.md @@ -21,8 +21,8 @@ ## Overview Fault Proof System V2 has been designed to address the key limitations identified in -[Fault Proof System V1](../../fault-proof/challenge.md), as outlined in the [Background](./overview.md#background). This -document details how each of the four main limitations of V1 has been effectively resolved in V2. +[Fault Proof System V1](../../zk-fault-proof/challenge.md), as outlined in the [Background](./overview.md#background). +This document details how each of the four main limitations of V1 has been effectively resolved in V2. ## Guaranteed Win of Valid Output diff --git a/specs/experimental/fault-proof-system-v2/output-proposal.md b/specs/experimental/fault-proof-system-v2/output-proposal.md index d12ba31..b0b2258 100644 --- a/specs/experimental/fault-proof-system-v2/output-proposal.md +++ b/specs/experimental/fault-proof-system-v2/output-proposal.md @@ -25,8 +25,8 @@ This document addresses one of the limitations of [the previous output proposal process](../../protocol/validation.md#submitting-l2-output-commitments) in Fault Proof System V1. When consecutive invalid [outputs][g-checkpoint-output] are proposed, the previous system's sequential -[challenge](../../fault-proof/challenge.md) and deletion mechanism for the first invalid output could lead to -insufficient time to [prove fault](../../fault-proof/challenge.md#proving-fault) in subsequent challenges before +[challenge](../../zk-fault-proof/challenge.md) and deletion mechanism for the first invalid output could lead to +insufficient time to [prove fault](../../zk-fault-proof/challenge.md#proving-fault) in subsequent challenges before finalization. Additionally, the limited participation in each challenge (only designated asserters and challengers) increased the risk of losing challenges due to timeouts, even for honest parties. @@ -63,7 +63,7 @@ payload = state_root || withdrawal_storage_root || block_hash This version removes the `next_block_hash`, which was added as a means to ensure that the asserter and challenger executed the same transactions in the target block in the -[previous ZK proof verification process](../../fault-proof/challenge.md#proving-fault). The elimination of +[previous ZK proof verification process](../../zk-fault-proof/challenge.md#proving-fault). The elimination of `next_block_hash` is feasible now that [transaction data is verifiable on-chain](./transaction-data-commitment.md). This change addresses the incorrect identification of the first disagreeing block in dissection, as noted in the [Background](./overview.md#background). diff --git a/specs/experimental/fault-proof-system-v2/overview.md b/specs/experimental/fault-proof-system-v2/overview.md index 458cac3..2a9fe6f 100755 --- a/specs/experimental/fault-proof-system-v2/overview.md +++ b/specs/experimental/fault-proof-system-v2/overview.md @@ -27,7 +27,7 @@ ## Background -The initial version, [Fault Proof System V1](../../fault-proof/challenge.md) introduced a permissionless +The initial version, [Fault Proof System V1](../../zk-fault-proof/challenge.md) introduced a permissionless [validator][g-validator] system. However, it encountered several limitations: - **Challenge Invalidity**: There was no assurance that a valid [output][g-checkpoint-output] would always win in diff --git a/specs/experimental/validator-system-v2/asset-manager.md b/specs/experimental/validator-system-v2/asset-manager.md deleted file mode 100644 index e69de29..0000000 diff --git a/specs/experimental/zk-fault-dipute-game/overview.md b/specs/experimental/zk-fault-dipute-game/overview.md index 079646c..f52d4b9 100644 --- a/specs/experimental/zk-fault-dipute-game/overview.md +++ b/specs/experimental/zk-fault-dipute-game/overview.md @@ -2,8 +2,6 @@ [g-zk-fault-proof]: ../../glossary.md#zk-fault-proof -[g-l2-chain-derivation]: ../../glossary.md#l2-chain-derivation -[g-sequencer-batch]: ../../glossary.md#sequencer-batch [g-withdrawals]: ../../glossary.md#withdrawals @@ -17,10 +15,6 @@ - [Proving Fault using zkVM](#proving-fault-using-zkvm) - [ZK Fault Proof](#zk-fault-proof) - [zkVM Proving System](#zkvm-proving-system) - - [Guest Program](#guest-program) - - [Host Program](#host-program) - - [Public Values of Proof](#public-values-of-proof) - - [Proving Fault](#proving-fault) - [Resolution of ZK Fault Dispute Game](#resolution-of-zk-fault-dispute-game) @@ -32,9 +26,9 @@ disagreeing output root between defender and challenger is found by the process derivation of L2 block corresponding to that output root and the execution of the block's transactions are carried out in zkVM. The validity of the execution is guaranteed by the ZK proof, which can be verified on-chain. -The main difference from [Kroma's previous ZK Fault Proof System](../../fault-proof/challenge.md) is that ZKFDG uses a -"zkVM" instead of a "zkEVM" to handle the proving fault process. By using zkVM for fault proof, it is possible to verify -the entire processes from derivation to execution without any additional developments of ZK circuit. +The main difference from [Kroma's previous ZK Fault Proof System](../../zk-fault-proof/challenge.md) is that ZKFDG uses +a "zkVM" instead of a "zkEVM" to handle the proving fault process. By using zkVM for fault proof, it is possible to +verify the entire processes from derivation to execution without any additional developments of ZK circuit. ZKFDG implements the OP Stack's `IDisputeGame`, implying that it is fully compatible as one of the OP Stack's dispute game type. This also implies that it can be applied to the OP Stack's multi-proof system in the future. @@ -71,7 +65,7 @@ As with Kroma's [previous Fault Proof System][prev-challenge-creation], a challe disagrees the submitted claim. The challenge process begins by submitting the intermediate segments between starting output root and disputed output root by challenger. -[prev-challenge-creation]: ../../../specs/fault-proof/challenge.md#challenge-creation +[prev-challenge-creation]: ../../zk-fault-proof/challenge.md#challenge-creation ```solidity /** @@ -94,7 +88,7 @@ The dissection process is carried out in the same manner as in Kroma's [previous Through interactions between the challenger and the defender (the game creator), the first disagreeing output root can be specified. -[prev-bisection]: ../../../specs/fault-proof/challenge.md#bisection +[prev-bisection]: ../../zk-fault-proof/challenge.md#bisection ```solidity /** @@ -125,90 +119,7 @@ providing evidence of a valid state transition from S to Sā€™. ### zkVM Proving System -The zkVM (Zero-Knowledge Virtual Machine) is a virtual machine that executes guest program compiled with a specified -compiler generating zero-knowledge proofs for their execution. The guest program can be written in standard programming -languages, such as Rust and Go. - -#### Guest Program - -For ZK Fault Dispute Game, the guest program is an extension of [L2 Chain Derivation][g-l2-chain-derivation] that -includes a connectivity check among the blocks from L1 origin block to the specified block `C`. The hash of Block -`C` is determined as the parent hash stored when the ZK Fault Dispute Game is created by calling `create()` of -the [Dispute Game Factory]. - -If the attacker manipulates any data within the extension of L2 Chain Derivation, it will affect the block hash `C`. -This is because all data is ultimately linked to the block hash `C` through the hash chain. Therefore if any data -manipulating attack can be thwarted by checking the block hash `C` value. For example, if an attacker creates a proof -using a transaction that is not included in the [sequencer batch][g-sequencer-batch], the block `C` value will change, -preventing them from winning the challenge. - -[Dispute Game Factory]: https://github.com/ethereum-optimism/specs/blob/46d411bfea922c520a1d43329dbf78a2f6966ae0/specs/fault-proof/stage-one/dispute-game-interface.md#disputegamefactory-interface - -#### Host Program - -The host program is a main part of the prover, responsible for delivering the guest program and its input to the zkVM. -The host program first executes the guest program to gather the necessary data, which is same as the data stored in -[PreImageOracle] during [Optimism's Fault Dispute Game]. For ZKFDG, however, additional data is required, which is the -L1 block data from the origin of target L2 block to block `C`. Finally, the host program delivers the guest program -and the preimages to the zkVM to obtain the zkVM proof. - -[PreImageOracle]: https://github.com/ethereum-optimism/specs/blob/46d411bfea922c520a1d43329dbf78a2f6966ae0/specs/fault-proof/stage-one/fault-dispute-game.md#preimageoracle -[Optimism's Fault Dispute Game]: https://github.com/ethereum-optimism/specs/blob/46d411bfea922c520a1d43329dbf78a2f6966ae0/specs/fault-proof/stage-one/fault-dispute-game.md#fault-dispute-game - -#### Public Values of Proof - -To mark which blocks have been executed, the proof publicly reveals the following data. - -``` plain -1. Output root at the parent block of the target -2. Output root at the target block -3. Hash of the block C -``` - -#### Proving Fault - -The ZK proof generated by a prover can be verified on chain. - -```solidity - /** - * @notice Proves that a specific output is invalid using ZK proof. - * - * @param _pos Position of the last valid segment. - * @param _targetOutput The output root of target block. - * @param _zkProof SP1 proofs composed of points and scalars. - */ - function proveFault( - uint256 _pos, - bytes32 _targetOutput, - uint256[] calldata _zkProof - ) external; -``` - -The verify function of `ZKVerifier` contract, which will be used in `proveFault` for verification of provided ZK proof, -will be implemented following the below interface. - -```solidity -interface ZKVerifier { - /** - * @notice The entrypoint for verifying the ZK fault proof. - * - * @param _publicValues The encoded public values. - * @param _proofBytes The encoded proof. - * - * @return If verification of ZK proof is passed or not. - */ - function verify( - bytes calldata _publicValues, - bytes calldata _proofBytes - ) public view returns (bool); -} -``` - -where the `_publicValues` is concatenated value of public values as described [above](#public-values-of-proof). - -```text -_publicValues = output_root_parent ++ output_root_target ++ l1_head -``` +See [zkVM Prover](../../zk-fault-proof/zkvm-prover.md#zkvm-proving-system) for details. ## Resolution of ZK Fault Dispute Game diff --git a/specs/glossary.md b/specs/glossary.md index 9ef0d03..8e58b8d 100644 --- a/specs/glossary.md +++ b/specs/glossary.md @@ -82,7 +82,6 @@ - [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract) - [L2 Output Root](#l2-output-root) - [L2 Output Oracle Contract](#l2-output-oracle-contract) - - [Validator Pool Contract](#validator-pool-contract) - [Validator Manager Contract](#validator-manager-contract) - [Asset Manager Contract](#asset-manager-contract) - [Colosseum Contract](#colosseum-contract) @@ -173,8 +172,6 @@ A merkle root of [Storage Trie][storage-trie]. ## Keccak -[keccak]: glossary.md#Keccak - [Keccak][keccak-wiki] is a hash function used in [L1] for various purposes. Some examples are deriving address of [EOA] and computing path of [MPT] which is called Secure Trie. @@ -196,9 +193,7 @@ The root hash of a ZKT is a commitment to the contents of the tree, which allows proof to be constructed for any key-value mapping encoded in the tree. Such a proof is called a Merkle proof, and can be verified against the Merkle root. -Whereas [L1] uses [MPT][mpt] to represent state, [L2] uses ZKT. This is because ZKT enables faster proof -generation by avoiding [Keccak][keccak] and [RLP encoding][RLP format]. -To accomplish this, ZKT uses poseidon hash to calculate the path and concatenates leaf values in bytes. +ZK Trie is now deprecated, and Kroma uses [Merkle Patricia Trie][mpt-details] instead after MPT hard fork. ## Chain Re-Organization @@ -332,12 +327,9 @@ Checkpoint output is the l2 output root that denotes state transition during [va [validator]: glossary.md#validator A validator is a decentralized actor, who does [validation]. To participate network as a validator, one needs to -deposit to [Validator Pool contract][validator-pool-contract] in -[ETH-based Validator System][eth-based-validator-system], otherwise needs to register to -[Validator Manager contract][validator-manager-contract] in [KRO-based Validator System][kro-based-validator-system]. +register to [Validator Manager contract][validator-manager-contract] in [Validator System][kro-based-validator-system]. Then the validator becomes eligible to submit checkpoint output. -[eth-based-validator-system]: ./protocol/validator-v1/validator-pool.md [kro-based-validator-system]: ./protocol/validator-v2/overview.md ## Trusted Validator @@ -349,7 +341,7 @@ A trusted validator is an actor who is run by Lightscale. If validations are not [validating-epoch]: glossary.md#validating-epoch -c of [L2] [blocks][block] where needs to be checkpointed. +The number of [L2][L2] [blocks][block] that need to be checkpointed. Each epoch is identified by an epoch number, which is incremented by 1. @@ -388,18 +380,12 @@ to false. Output submission rewards are given as an incentive for validators to submit checkpoint output. -In [ETH-based Validator System][eth-based-validator-system], the output reward is the same as the -[validator reward][validator-reward], otherwise in [KRO-based Validator System][kro-based-validator-system], it consists -of the validator reward, [base reward][base-reward], and [boosted reward][boosted-reward]. +In [validator system][kro-based-validator-system], it consists of the validator reward, [base reward][base-reward], and +[boosted reward][boosted-reward]. ## Validator Reward -[validator-reward]: glossary.md#validator-reward - -In [ETH-based Validator System][eth-based-validator-system], the validator reward is calculated using the following -formula: `(L2 base fee + L2 priority fee) * validator reward scalar / 10000`. - -In [KRO-based Validator System][kro-based-validator-system], the validator reward is given in terms of KRO tokens, and +In [validator system][kro-based-validator-system], the validator reward is given in terms of KRO tokens, and is calculated as the sum of the [base reward][base-reward] and [boosted reward][boosted-reward] multiplied by the commission rate. @@ -408,7 +394,7 @@ commission rate. [base-reward]: glossary.md#base-reward The base validator reward is given to the vault of the validator who submits the output at -[KRO-based Validator System][kro-based-validator-system]. The base reward is given in terms of a fixed amount of KRO +[validator system][kro-based-validator-system]. The base reward is given in terms of a fixed amount of KRO tokens for each submission. ## Boosted Reward @@ -416,7 +402,7 @@ tokens for each submission. [boosted-reward]: glossary.md#boosted-reward The boosted validator reward is given to the vault of the validator who submits the output at -[KRO-based Validator System][kro-based-validator-system]. The boosted reward is given in terms of KRO tokens, and is +[validator system][kro-based-validator-system]. The boosted reward is given in terms of KRO tokens, and is calculated using the following formula: $$\verb#BASE_REWARD# \times 0.4 \times arctan(0.01 \times G_i)$$ where $G_i$ is the total amount of KGH NFTs delegated to the output submitter. This is designed to have the effect that the boosted reward is constantly decreasing while the number of delegated KGH increases. More information on boosted reward due to @@ -558,8 +544,8 @@ An EOA on L1 which finalizes a withdrawal by submitting the data necessary to ve The finalization period ā€” sometimes also called *withdrawal delay* ā€” is the minimum amount of time (in seconds) that must elapse before a [withdrawal][withdrawals] can be finalized. -The finalization period is necessary to afford sufficient time for [validators][validator] to make a -[ZK fault proof][zk-fault-proof]. +The finalization period is necessary to afford sufficient time for [validators][validator] to avoid L1 censorship +attacks. > **TODO** specify current value for finalization period @@ -895,25 +881,18 @@ An L1 contract to which [L2 output roots][l2-output] are posted by the [validato > **TODO** expand -## Validator Pool Contract - -[validator-pool-contract]: glossary.md#validator-pool-contract - -An [L1] contract that determines [validator] eligibility, selects the [validator] of next round, and manages bonding for -[L2 output roots][l2-output] submissions in [ETH-based Validator System][eth-based-validator-system]. - ## Validator Manager Contract [validator-manager-contract]: glossary.md#validator-manager-contract An [L1] contract that manages the set of [validators][validator], selects the validator of next [priority round][priority-round], and is an entry point of [output reward][output-reward] distribution and slash in -[KRO-based Validator System][kro-based-validator-system]. +[validator system][kro-based-validator-system]. ## Asset Manager Contract An [L1] contract that oversees the delegation and undelegation of assets, and manages distributed rewards and slashing -penalties in [KRO-based Validator System][kro-based-validator-system]. +penalties in [validator system][kro-based-validator-system]. ## Colosseum Contract @@ -1002,4 +981,3 @@ In these specifications, "execution engine" always refer to the L2 execution eng [merge]: https://ethereum.org/en/eth2/merge/ [mempool]: https://www.quicknode.com/guides/defi/how-to-access-ethereum-mempool [zkt-details]: https://github.com/kroma-network/zktrie -[RLP format]: https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp diff --git a/specs/introduction.md b/specs/introduction.md index ac0a456..797952b 100644 --- a/specs/introduction.md +++ b/specs/introduction.md @@ -12,7 +12,7 @@ - [Foundations](#foundations) - [Blockchain Trilemma](#blockchain-trilemma) - [What is Ethereum scalability?](#what-is-ethereum-scalability) - - [What is a Layer2?](#what-is-a-layer2) + - [What is a Layer 2?](#what-is-a-layer-2) - [What is a Rollup?](#what-is-a-rollup) - [What is EVM Equivalence?](#what-is-evm-equivalence) - [šŸŽ¶ All together now šŸŽ¶](#-all-together-now-) @@ -53,7 +53,7 @@ processed on the network. Of the three resources, computation and storage are cu bottlenecks. These bottlenecks limit the supply of transactions, leading to extremely high fees. Scaling ethereum and reducing fees can be achieved by better utilizing bandwidth, computation and storage. -### What is a Layer2? +### What is a Layer 2? Layer 2 is a solution for Ethereum scalability. The key is to do state transition at not onchain but offchain. This means the transaction execution is not part of the consensus. Why? because the more participants re-execute @@ -86,11 +86,6 @@ with the state transition function described in the Ethereum yellow paper, the f conforming to the Ethereum standard across EVM equivalent rollups, smart contract developers can write once and deploy anywhere. -**NOTE:** At this moment, `OP_SELFDESTRUCT` is disabled. We are actively trying to fully cover the evm spec. But like -[eip-4758] suggests, we don't recommend users to rely on this opcode. - -[eip-4758]: https://eips.ethereum.org/EIPS/eip-4758 - ### šŸŽ¶ All together now šŸŽ¶ **Kroma is an _EVM equivalent_, _optimistic rollup_ protocol designed to _scale Ethereum_.** diff --git a/specs/protocol/contract-upgrades.md b/specs/protocol/contract-upgrades.md index 84dd4b9..59d068d 100644 --- a/specs/protocol/contract-upgrades.md +++ b/specs/protocol/contract-upgrades.md @@ -15,13 +15,12 @@ [Smart contract upgrades](https://docs.openzeppelin.com/upgrades-plugins/1.x/proxies) are executed through the [governance](https://docs.openzeppelin.com/contracts/4.x/api/governance) of the Security Council. The authority to perform proxy upgrades lies with the Security Council's governor. -When a proposal for an upgrade is approved, it undergoes a mandatory 7-day timelock delay period before execution. ## Upgrade By Governance When an on-chain proposal for a contract upgrade is submitted by a member of Security Council, the member votes on the proposal during the voting period. Once a proposal is approved, the Security Council queues the proposal to the batch -to be executed with a 7-day timelock. After the timelock delay, the upgrade can be executed. +to be executed, and the upgrade can be executed. ### Interface diff --git a/specs/protocol/deposits.md b/specs/protocol/deposits.md index 04c489e..0e6f739 100644 --- a/specs/protocol/deposits.md +++ b/specs/protocol/deposits.md @@ -338,8 +338,8 @@ The predeploy stores the following values: The `overhead` value is dropped as it is no longer used in the [Ecotone L1 fee formula](exec-engine.md#ecotone-l1-cost-fee-changes-eip-4844-da). - `scalar` (`uint256`): The L1 fee scalar to apply to L1 cost computation of transactions in this L2 block. -- Parameters to calculate a validator reward. It's only used for - [ETH-based Validator System](./validator-v1/validator-pool.md), and set to zero in +- Parameters to calculate a validator reward. It was only used for + [ETH-based Validator System](../deprecated/validator-v1/validator-pool.md), and had set to zero in [KRO-based Validator System](./validator-v2/overview.md) - `validatorRewardScalar` (`uint256`): A number between 0 and 10000. A [validator reward][g-validator-reward] is calculated with the expression. diff --git a/specs/protocol/differences-from-optimism.md b/specs/protocol/differences-from-optimism.md index ba7b760..8c65f6b 100644 --- a/specs/protocol/differences-from-optimism.md +++ b/specs/protocol/differences-from-optimism.md @@ -17,11 +17,13 @@ - [Nodes](#nodes) - [Verifier -> Validator](#verifier---validator) - [Compositions](#compositions) - - [Adding field to System Configuration](#adding-field-to-system-configuration) - - [Adding field to Output Payload](#adding-field-to-output-payload) -- [Geth](#geth) - [Validator](#validator) - - [ZK fault proof](#zk-fault-proof) + - [ZK fault proof system](#zk-fault-proof-system) + - [DPoS Validator System](#dpos-validator-system) +- [(Deprecated) zkEVM Fault Proof and ZK Trie](#deprecated-zkevm-fault-proof-and-zk-trie) + - [(Deprecated) Adding field to System Configuration](#deprecated-adding-field-to-system-configuration) + - [(Deprecated) Adding field to Output Payload](#deprecated-adding-field-to-output-payload) + - [(Deprecated) Geth Changes](#deprecated-geth-changes) @@ -71,7 +73,21 @@ The followings are components that are used to run different types of nodes: **NOTE:** Here `L2 EL client` means `kroma-geth` and `L2 CL client` means `kroma-node`. `L2 EL client` can be expanded to other clients for pragmatic decentralization. -### Adding field to System Configuration +## Validator + +### ZK fault proof system + +Instead of fault proof system based on [cannon], Kroma uses zkVM for [ZK fault proof][g-zk-fault-proof]. + +[cannon]: https://github.com/ethereum-optimism/cannon + +### DPoS Validator System + +Kroma has its own [DPoS validator system](validator-v2/overview.md) utilizing its governance token. + +## (Deprecated) zkEVM Fault Proof and ZK Trie + +### (Deprecated) Adding field to System Configuration The `ValidatorRewardScalar` field was added to [system configuration][g-system-config]. @@ -99,7 +115,7 @@ type L1BlockInfo struct { This value is set via the `SystemConfig` contract on L1 and passed through the L2 derivation process and used as an ingredient in the reward calculation. (Detailed calculations : [Validation Rewards][g-validation-rewards]) -### Adding field to Output Payload +### (Deprecated) Adding field to Output Payload The `next_block_hash` field was added to [Output Payload][g-output-payload-v0]. @@ -121,7 +137,7 @@ proof system. It is used to validate the relationship between the Source OutputRootProof and Dest OutputRootProof, and the validation of the public input. -## Geth +### (Deprecated) Geth Changes To prepare for migration to ZK Rollup, we use a [ZK Trie][g-zktrie] to represent state. Currently, this makes the chain slower than [Merkle Patrica Trie][g-mpt]. As the bottleneck is the time to produce ZK proof right now, @@ -133,11 +149,3 @@ Additionally, to produce a zkEVM proof, geth should return so called `execution `kroma_getBlockTraceByNumberOrHash` which provides zkEVM prover with data as a witness. [scroll]: https://scroll.io/ - -## Validator - -### ZK fault proof - -Instead of [cannon], Kroma uses zkEVM for [ZK fault proof][g-zk-fault-proof]. - -[cannon]: https://github.com/ethereum-optimism/cannon diff --git a/specs/protocol/exec-engine.md b/specs/protocol/exec-engine.md index 077434d..86c2a81 100644 --- a/specs/protocol/exec-engine.md +++ b/specs/protocol/exec-engine.md @@ -9,7 +9,8 @@ - [Deposited transaction boundaries](#deposited-transaction-boundaries) - [Fees](#fees) - [Fee Vaults](#fee-vaults) - - [Transaction Fees](#transaction-fees) + - [Priority fees (Sequencer Fee Vault)](#priority-fees-sequencer-fee-vault) + - [Base fees (Base Fee Vault)](#base-fees-base-fee-vault) - [L1-Cost fees (L1 Fee Vault)](#l1-cost-fees-l1-fee-vault) - [Pre-Ecotone](#pre-ecotone) - [Ecotone L1-Cost fee changes (EIP-4844 DA)](#ecotone-l1-cost-fee-changes-eip-4844-da) @@ -70,8 +71,8 @@ Deposited transactions MUST never be consumed from the transaction pool. ## Fees -Sequenced transactions (i.e. not applicable to deposits) are charged with 2 types of fees: -transaction fees(priority fees + base fees), and L1-cost fees. +Sequenced transactions (i.e. not applicable to deposits) are charged with 3 types of fees: +priority fees, base fees, and L1-cost fees. ### Fee Vaults @@ -81,25 +82,21 @@ fee payments are not registered as internal EVM calls, and thus distinguished be These are hardcoded addresses, pointing at pre-deployed proxy contracts. The proxies are backed by vault contract deployments, based on `FeeVault`, to route vault funds to L1 securely. -| Vault Name | Predeploy | -|------------------------|----------------------------------------------------------------| -| Validator Reward Vault | [`ValidatorRewardVault`](./predeploys.md#ValidatorRewardVault) | -| Protocol Vault | [`ProtocolVault`](./predeploys.md#ProtocolVault) | -| L1 Fee Vault | [`L1FeeVault`](./predeploys.md#L1FeeVault) | +| Vault Name | Predeploy | +| ------------------- | ------------------------------------------------------ | +| Sequencer Fee Vault | [`SequencerFeeVault`](predeploys.md#sequencerfeevault) | +| Base Fee Vault | [`BaseFeeVault`](predeploys.md#basefeevault) | +| L1 Fee Vault | [`L1FeeVault`](predeploys.md#l1feevault) | -### Transaction Fees +### Priority fees (Sequencer Fee Vault) -Transaction fees in Kroma are different from [eip-1559] specification. -The Base Fee is not burned, and there is no distinction between Base Fee and Priority Fee. -The transaction fee is distributed to two vaults, Validator Reward Vault and Protocol Fee, during -[ETH-based Validator System](./validator-v1/validator-pool.md) is live. After transiting to -[KRO-based Validator System](./validator-v2/overview.md), the transaction fee is only accumulated to Protocol Fee with -zero `ValidatorRewardScalar`. +Priority fees follow the [eip-1559] specification, and are collected by the fee-recipient of the L2 block. +The block fee-recipient (a.k.a. coinbase address) is set to the Sequencer Fee Vault address. -- Validator Reward Vault: `(baseFee + priorityFee) * ValidatorRewardScalar / 10000` -- Protocol Vault: `(baseFee + priorityFee) * (10000 - ValidatorRewardScalar) / 10000` +### Base fees (Base Fee Vault) -`ValidatorRewardScalar` value is recorded in the [`L1Block`](./predeploys.md#L1block) contract. +Base fees largely follow the [eip-1559] specification, with the exception that base fees are not burned, +but add up to the Base Fee Vault ETH account balance. ### L1-Cost fees (L1 Fee Vault) diff --git a/specs/protocol/overview.md b/specs/protocol/overview.md index 6a8acf4..428e990 100644 --- a/specs/protocol/overview.md +++ b/specs/protocol/overview.md @@ -69,14 +69,12 @@ token deposits (tokens are locked on L1, then minted on L2 via a deposited trans - The BatchInbox is a regular EOA address. This lets us pass on gas cost savings by not executing any EVM code. - **L2OutputOracle**: A smart contract that stores [L2 output roots][g-l2-output] for use with withdrawals and fault proofs. -- **ValidatorPool**: A smart contract that stores validators and their deposits in - [ETH-based Validator System](./validator-v1/validator-pool.md). - **ValidatorManager**: A smart contract that manages validators in - [KRO-based Validator System](./validator-v2/overview.md). + [Validator System](./validator-v2/overview.md). - **AssetManager**: A smart contract that manages validator and delegators' assets in - [KRO-based Validator System](./validator-v2/overview.md). + [Validator System](./validator-v2/overview.md). - **Colosseum**: A smart contract where validators can dispute assertions on. -- **ZKVerifier**: A smart contract that verifies [ZK fault proof][g-zk-fault-proof]. +- **ZKProofVerifier**: A smart contract that verifies [ZK fault proof][g-zk-fault-proof]. ### L2 Components diff --git a/specs/protocol/predeploys.md b/specs/protocol/predeploys.md index 88100c4..da7f9f2 100644 --- a/specs/protocol/predeploys.md +++ b/specs/protocol/predeploys.md @@ -7,16 +7,21 @@ - [Overview](#overview) - [ProxyAdmin](#proxyadmin) - [WETH9](#weth9) -- [L1Block](#l1block) +- [[DEPRECATED] L1Block](#deprecated-l1block) - [L2ToL1MessagePasser](#l2tol1messagepasser) - [L2CrossDomainMessenger](#l2crossdomainmessenger) - [GasPriceOracle](#gaspriceoracle) -- [ProtocolVault](#protocolvault) -- [L1FeeVault](#l1feevault) -- [ValidatorRewardVault](#validatorrewardvault) +- [[DEPRECATED] ProtocolVault](#deprecated-protocolvault) +- [[DEPRECATED] L1FeeVault](#deprecated-l1feevault) +- [[DEPRECATED] ValidatorRewardVault](#deprecated-validatorrewardvault) - [L2StandardBridge](#l2standardbridge) - [KromaMintableERC20Factory](#kromamintableerc20factory) - [KromaMintableERC721Factory](#kromamintableerc721factory) +- [SequencerFeeVault](#sequencerfeevault) +- [L1Block](#l1block) +- [BaseFeeVault](#basefeevault) +- [L1FeeVault](#l1feevault) +- [Beacon Block Root](#beacon-block-root) @@ -36,21 +41,26 @@ network forking. Predeploy addresses exist in 1 byte namespace `0x42000000000000000000000000000000000000xx`. Proxies are set at each possible predeploy address except for the `ProxyAdmin` and the `WETH9`. -| Name | Address | Proxied | -|----------------------------|--------------------------------------------|---------| -| ProxyAdmin | 0x4200000000000000000000000000000000000000 | No | -| WETH9 | 0x4200000000000000000000000000000000000001 | No | -| L1Block | 0x4200000000000000000000000000000000000002 | Yes | -| L2ToL1MessagePasser | 0x4200000000000000000000000000000000000003 | Yes | -| L2CrossDomainMessenger | 0x4200000000000000000000000000000000000004 | Yes | -| GasPriceOracle | 0x4200000000000000000000000000000000000005 | Yes | -| ProtocolVault | 0x4200000000000000000000000000000000000006 | Yes | -| L1FeeVault | 0x4200000000000000000000000000000000000007 | Yes | -| ValidatorRewardVault | 0x4200000000000000000000000000000000000008 | Yes | -| L2StandardBridge | 0x4200000000000000000000000000000000000009 | Yes | -| L2ERC721Bridge | 0x420000000000000000000000000000000000000A | Yes | -| KromaMintableERC20Factory | 0x420000000000000000000000000000000000000B | Yes | -| KromaMintableERC721Factory | 0x420000000000000000000000000000000000000C | Yes | +| Name | Address | Introduced | Deprecated | Proxied | +|-------------------------------------|--------------------------------------------|------------|------------|---------| +| ProxyAdmin | 0x4200000000000000000000000000000000000000 | Legacy | No | No | +| WETH9 | 0x4200000000000000000000000000000000000001 | Legacy | No | No | +| L1Block (*deprecated*) | 0x4200000000000000000000000000000000000002 | Bedrock | Yes | Yes | +| L2ToL1MessagePasser | 0x4200000000000000000000000000000000000003 | Legacy | No | Yes | +| L2CrossDomainMessenger | 0x4200000000000000000000000000000000000004 | Legacy | No | Yes | +| GasPriceOracle | 0x4200000000000000000000000000000000000005 | Legacy | No | Yes | +| ProtocolVault (*deprecated*) | 0x4200000000000000000000000000000000000006 | Bedrock | Yes | Yes | +| L1FeeVault (*deprecated*) | 0x4200000000000000000000000000000000000007 | Bedrock | Yes | Yes | +| ValidatorRewardVault (*deprecated*) | 0x4200000000000000000000000000000000000008 | Bedrock | Yes | Yes | +| L2StandardBridge | 0x4200000000000000000000000000000000000009 | Bedrock | No | Yes | +| L2ERC721Bridge | 0x420000000000000000000000000000000000000A | Legacy | No | Yes | +| KromaMintableERC20Factory | 0x420000000000000000000000000000000000000B | Legacy | No | Yes | +| KromaMintableERC721Factory | 0x420000000000000000000000000000000000000C | Bedrock | No | Yes | +| SequencerFeeVault | 0x4200000000000000000000000000000000000011 | Kroma MPT | No | Yes | +| L1Block | 0x4200000000000000000000000000000000000015 | Kroma MPT | No | Yes | +| BaseFeeVault | 0x4200000000000000000000000000000000000019 | Kroma MPT | No | Yes | +| L1FeeVault | 0x420000000000000000000000000000000000001a | Kroma MPT | No | Yes | +| BeaconBlockRoot | 0x000F3df6D732807Ef1319fB7B8bB8522d0Beac02 | Ecotone | No | No | ## ProxyAdmin @@ -72,10 +82,12 @@ Address: `0x4200000000000000000000000000000000000001` commonly used contract and is placed as a predeploy so that it is at a deterministic address across Kroma based networks. -## L1Block +## [DEPRECATED] L1Block [Implementation](https://github.com/kroma-network/kroma/blob/main/packages/contracts/contracts/L2/L1Block.sol) +**NOTE**: This contract is deprecated, and the functionality has been moved to the another address. + Address: `0x4200000000000000000000000000000000000002` [l1-block-predeploy]: ../glossary.md#l1-attributes-predeployed-contract @@ -138,7 +150,9 @@ These values are managed by the `SystemConfig` contract on L2. The `scalar` and `overhead` values are sent to the `L1Block` contract each block and the `decimals` value is hardcoded to 6. -## ProtocolVault +## [DEPRECATED] ProtocolVault + +**NOTE**: This contract is deprecated and no longer in use. [Implementation](https://github.com/kroma-network/kroma/blob/main/packages/contracts/contracts/L2/ProtocolVault.sol) @@ -148,7 +162,9 @@ The `ProtocolVault` predeploy accumulates transaction fees to fund network opera Once the contract has received a certain amount of fees, the ETH can be withdrawn to an immutable address on L1. -## L1FeeVault +## [DEPRECATED] L1FeeVault + +**NOTE**: This contract is deprecated, and the functionality has been moved to the another address. [Implementation](https://github.com/kroma-network/kroma/blob/main/packages/contracts/contracts/L2/L1FeeVault.sol) @@ -158,14 +174,16 @@ The `L1FeeVault` predeploy receives the L1 portion of the transaction fees. Once the contract has received a certain amount of fees, the ETH can be withdrawn to an immutable address on L1. -## ValidatorRewardVault +## [DEPRECATED] ValidatorRewardVault + +**NOTE**: This contract is deprecated and no longer in use. [Implementation](https://github.com/kroma-network/kroma/blob/main/packages/contracts/contracts/L2/ValidatorRewardVault.sol) Address: `0x4200000000000000000000000000000000000008` The `ValidatorRewardVault` accumulates transaction fees and pays rewards to validators in -[ETH-based Validator System](./validator-v1/validator-pool.md). +[ETH-based Validator System](../deprecated/validator-v1/validator-pool.md). When enough fees accumulate in this account, they can be withdrawn to an immutable L1 address. To change the L1 address that fees are withdrawn to, the contract must be @@ -215,7 +233,57 @@ and burn tokens, depending on if the user is depositing from L1 to L2 or withdra [Implementation](https://github.com/kroma-network/kroma/blob/main/packages/contracts/contracts/universal/KromaMintableERC721Factory.sol) -Address: `0x4200000000000000000000000000000000000017` +Address: `0x420000000000000000000000000000000000000C` The `KromaMintableERC721Factory` is responsible for creating ERC721 contracts on L2 that can be used for depositing native L1 NFTs into. + +## SequencerFeeVault + +[Implementation](https://github.com/kroma-network/kroma/blob/main/packages/contracts/contracts/L2/ProtocolVault.sol) + +Address: `0x4200000000000000000000000000000000000011` + +The `SequencerFeeVault` accumulates any transaction priority fee and is the value of +`block.coinbase`. +When enough fees accumulate in this account, they can be withdrawn to an immutable L1 address. + +To change the L1 address that fees are withdrawn to, the contract must be +upgraded by changing its proxy's implementation key. + +## L1Block + +[Implementation](https://github.com/kroma-network/kroma/blob/main/packages/contracts/contracts/L2/L1Block.sol) + +Address: `0x4200000000000000000000000000000000000015` + +The [L1Block][l1-block-predeploy] is responsible for maintaining L1 context in L2. +This allows for L1 state to be accessed in L2. + +## BaseFeeVault + +[Implementation](https://github.com/kroma-network/kroma/blob/main/packages/contracts/contracts/L2/ProtocolVault.sol) + +Address: `0x4200000000000000000000000000000000000019` + +The `BaseFeeVault` predeploy receives the base fees on L2. The base fee is not +burnt on L2 like it is on L1. Once the contract has received a certain amount +of fees, the ETH can be withdrawn to an immutable address on +L1. + +## L1FeeVault + +[Implementation](https://github.com/kroma-network/kroma/blob/main/packages/contracts/contracts/L2/L1FeeVault.sol) + +Address: `0x420000000000000000000000000000000000001a` + +The `L1FeeVault` predeploy receives the L1 portion of the transaction fees. +Once the contract has received a certain amount of fees, the ETH can be +withdrawn to an immutable address on L1. + +## Beacon Block Root + +Address: `0x000F3df6D732807Ef1319fB7B8bB8522d0Beac02` + +The `BeaconBlockRoot` predeploy provides access to the L1 beacon block roots. This was added during the +Ecotone network upgrade and is specified in [EIP-4788](https://eips.ethereum.org/EIPS/eip-4788). diff --git a/specs/protocol/security-council.md b/specs/protocol/security-council.md index dc4e505..57bc6f1 100644 --- a/specs/protocol/security-council.md +++ b/specs/protocol/security-council.md @@ -25,8 +25,8 @@ all actions are carried out through multi-sig transaction or governance processe When an undeniable bug occurs within the [ZK Fault Proof System](../glossary.md#zk-fault-proof), assets locked in Layer 2 may be exposed to potential risks. To prevent this, the Security Council has the authority to rectify such issues. The Security Council intervenes in cases where two valid and contradictory ZK proofs exist -([ZK soundness error](../fault-proof/challenge.md#dismiss-challenge)) or fail to prove with a valid proof -([ZK completeness error](../fault-proof/challenge.md#force-delete-output)). +([ZK soundness error](../zk-fault-proof/challenge.md#dismiss-challenge)) or fail to prove with a valid proof +([ZK completeness error](../zk-fault-proof/challenge.md#force-delete-output)). Their intervention aims to prevent invalid outputs from being finalized, thereby safeguarding the assets locked in Layer 2. @@ -61,5 +61,4 @@ is configured to be Security Council. All contract upgrades deployed on [Layer 1][g-l1] are conducted by the [governance of the Security Council](contract-upgrades.md#upgrade-by-governance). These upgrades are proposed by a -member of Security Council and are determined through the voting of these members. If a proposal passes, it typically -has a 7-day timelock delay for execution. +member of Security Council and are determined through the voting of these members. diff --git a/specs/protocol/system-config.md b/specs/protocol/system-config.md index a4ac512..3c64e6b 100644 --- a/specs/protocol/system-config.md +++ b/specs/protocol/system-config.md @@ -12,7 +12,7 @@ - [Ecotone `scalar`, `overhead` (`uint256,uint256`) change](#ecotone-scalar-overhead-uint256uint256-change) - [`gasLimit` (`uint64`)](#gaslimit-uint64) - [`unsafeBlockSigner` (`address`)](#unsafeblocksigner-address) - - [`validatorRewardScalar` (`uint256`)](#validatorrewardscalar-uint256) + - [[DEPRECATED] `validatorRewardScalar` (`uint256`)](#deprecated-validatorrewardscalar-uint256) - [Writing the system config](#writing-the-system-config) - [Reading the system config](#reading-the-system-config) @@ -122,11 +122,13 @@ manner, it is stored at a special storage slot corresponding to Unlike the other values, the `unsafeBlockSigner` only operates on blockchain policy. It is not a consensus level parameter. -### `validatorRewardScalar` (`uint256`) +### [DEPRECATED] `validatorRewardScalar` (`uint256`) + +Note: This field is deprecated and is no longer used in the current system. The scalar value to distribute [transaction fees](./exec-engine.md#transaction-fees) on L2 to validators as a reward of -checkpoint output submission in [ETH-based Validator System](./validator-v1/validator-pool.md). The denominator is -10000. In [KRO-based Validator System](./validator-v2/overview.md), it is set to zero. +checkpoint output submission in [ETH-based Validator System](../deprecated/validator-v1/validator-pool.md). The +denominator is 10000. In [KRO-based Validator System](./validator-v2/overview.md), it is set to zero. ## Writing the system config @@ -167,7 +169,6 @@ The contained log events are filtered and processed as follows: `blobBaseFeeScalar`. - type `2`: `gasLimit` overwrite, as `uint64` payload. - type `3`: `unsafeBlockSigner` overwrite, as `address` payload. - - type `4`: `validatorRewardScalar` overwrite, as `uint256` payload. Note that individual derivation stages may be processing different L1 blocks, and should thus maintain individual system configuration copies, diff --git a/specs/protocol/validation.md b/specs/protocol/validation.md index c63d4ef..632ede8 100644 --- a/specs/protocol/validation.md +++ b/specs/protocol/validation.md @@ -22,7 +22,7 @@ [g-l1]: ../glossary.md#layer-1-l1 [g-l2]: ../glossary.md#layer-2-l2 [g-zk-fault-proof]: ../glossary.md#zk-fault-proof -[g-zktrie]: ../glossary.md#zk-trie +[g-mpt]: ../glossary.md#merkle-patricia-trie [g-priority-round]: ../glossary.md#priority-round [g-public-round]: ../glossary.md#public-round @@ -40,7 +40,7 @@ with a bond at stake if the proof is wrong. > **_NOTE:_** > Before the introduction of the KRO governance token, the -> [validator system was ETH-based](./validator-v1/validator-pool.md). With introduction of KRO token, the +> [validator system was ETH-based](../deprecated/validator-v1/validator-pool.md). With introduction of KRO token, the > system had been transited to [KRO-based validator system](./validator-v2/overview.md), mitigating several limitations > of the ETH-based system. @@ -103,27 +103,26 @@ where: The version 0 payload is defined as: ```pseudocode -payload = state_root || withdrawal_storage_root || block_hash || next_block_hash +payload = state_root || withdrawal_storage_root || block_hash ``` where: 1. The `block_hash` (`bytes32`) is the block hash for the [L2][g-l2] block that the output is generated from. -2. The `state_root` (`bytes32`) is the [ZK-Trie][g-zktrie] root of all execution-layer accounts. +2. The `state_root` (`bytes32`) is the [Merkle Patricia Trie][g-mpt] root of all execution-layer accounts. This value is frequently used and thus elevated closer to the L2 output root, which removes the need to prove its inclusion in the pre-image of the `block_hash`. This reduces the merkle proof depth and cost of accessing the L2 state root on L1. -3. The `withdrawal_storage_root` (`bytes32`) elevates the ZK Trie root of the +3. The `withdrawal_storage_root` (`bytes32`) elevates the Merkle Trie root of the [L2ToL1MessagePasser contract](withdrawals.md#the-l2tol1messagepasser-contract) storage. Instead of making a - [ZKT][g-zktrie] proof for a withdrawal against the state root (proving first the storage root of the + [MPT][g-mpt] proof for a withdrawal against the state root (proving first the storage root of the L2toL1MessagePasser against the state root, then the withdrawal against that storage root), we can prove against the L2toL1MessagePasser's storage root directly, thus reducing the verification cost of withdrawals on L1. -4. The `next_block_hash` (`bytes32`) is the next block hash for the block that is next to the `block_hash`. - -The height of the block where the output is submitted has been delayed by one. +The height of the block where the output is submitted has been delayed by one. Note that `next_block_hash` is deprecated +and not used in the construction of the output root after Kroma MPT migration fork. ## L2 Output Oracle Smart Contract @@ -141,7 +140,11 @@ interface L2OutputOracle { uint256 l1Timestamp ); - event OutputReplaced(uint256 indexed outputIndex, bytes32 newOutputRoot); + event OutputReplaced( + uint256 indexed outputIndex, + address indexed newSubmitter, + bytes32 newOutputRoot + ); function replaceL2Output( uint256 _l2OutputIndex, diff --git a/specs/protocol/validator-v2/overview.md b/specs/protocol/validator-v2/overview.md index 3279921..968bffc 100644 --- a/specs/protocol/validator-v2/overview.md +++ b/specs/protocol/validator-v2/overview.md @@ -34,10 +34,10 @@ ## Background -The [previous permissionless validator system](../validator-v1/validator-pool.md) of Kroma requires validators to bond -`REQUIRED_BOND_AMOUNT` of ETH each time the validator submits an [L2 output root][g-l2-output]. While successfully -involving over 360 validators (as of 6/3/24), there are a few drawbacks in the previous system that need to be -addressed: +The [previous permissionless validator system](../../deprecated/validator-v1/validator-pool.md) of Kroma requires +validators to bond `REQUIRED_BOND_AMOUNT` of ETH each time the validator submits an [L2 output root][g-l2-output]. +While successfully involving over 360 validators (as of 6/3/24), there are a few drawbacks in the previous system that +need to be addressed: - **Multiple Accounts on a Single Validator**: Since the probability of being selected as a priority validator is calculated to be the same if only `REQUIRED_BOND_AMOUNT` of ETH is deposited, a single validator can increase the @@ -55,7 +55,7 @@ incorporating delegation system based on Kroma's governance token (KRO) and Krom **Validator System V2** is a new network security model of Kroma, which introduces KRO tokenomics and delegation to the validator system. It is compatible with current [ZK fault proof][g-zk-fault-proof] and -[challenge system](../../fault-proof/challenge.md), while introducing two new contracts: +[challenge system](../../zk-fault-proof/challenge.md), while introducing two new contracts: [**Validator Manager**][g-validator-manager-contract] and [**Asset Manager** contract][g-asset-manager-contract]. These contracts replace the existing [Validator Pool contract][g-validator-pool-contract], handling jobs such as validator management, delegation, next priority validator selection, [output reward][g-output-reward] distribution, and challenge diff --git a/specs/protocol/validator-v2/validator-manager.md b/specs/protocol/validator-v2/validator-manager.md index 5a39445..a6264ef 100644 --- a/specs/protocol/validator-v2/validator-manager.md +++ b/specs/protocol/validator-v2/validator-manager.md @@ -157,7 +157,7 @@ challenge creation. Namely, the delegated KROs from KRO delegators are not subje concludes, the bond of the loser is slashed, with a portion imposed as tax to the security council and the remainder awarded to the validator who won the challenge. -When the bond is slashed, [Colosseum](../../fault-proof/challenge.md#contract-interface) contract calls Validator +When the bond is slashed, [Colosseum](../../zk-fault-proof/challenge.md#contract-interface) contract calls Validator Manager, which calls Asset Manager's slash function to deduct the bond from the validator's assets. ### Reward Distribution diff --git a/specs/protocol/withdrawals.md b/specs/protocol/withdrawals.md index 4d8bc1b..dd033d2 100644 --- a/specs/protocol/withdrawals.md +++ b/specs/protocol/withdrawals.md @@ -66,7 +66,7 @@ This is a very simple contract that stores the hash of the withdrawal data. These inputs include the withdrawal transaction data, inclusion proofs, and a block number. The block number must be one for which an L2 output root exists, which commits to the withdrawal as registered on L2. 2. The `KromaPortal` contract retrieves the output root for the given block number from the `L2OutputOracle`'s - `getL2OutputAfter()` function, and performs the remainder of the verification process internally. + `getL2Output()` function, and performs the remainder of the verification process internally. 3. If proof verification fails, the call reverts. Otherwise the hash is recorded to prevent it from being re-proven. Note that the withdrawal can be proven more than once if the corresponding output root changes. 4. After the withdrawal is proven, it enters a 7 day challenge period, allowing time for other network participants diff --git a/specs/root.md b/specs/root.md index f816b98..e746702 100644 --- a/specs/root.md +++ b/specs/root.md @@ -31,8 +31,8 @@ that maintains 1:1 compatibility with Ethereum. - [Messengers](./protocol/messengers.md) - [Bridges](./protocol/bridges.md) - [Predeploys](./protocol/predeploys.md) -- [Challenge](./fault-proof/challenge.md) -- [zkEVM Prover](./fault-proof/zkevm-prover.md) +- [Challenge](zk-fault-proof/challenge.md) +- [zkVM Prover](zk-fault-proof/zkvm-prover.md) - [SystemConfig](./protocol/system-config.md) - [Glossary](./glossary.md) diff --git a/specs/fault-proof/challenge.md b/specs/zk-fault-proof/challenge.md similarity index 72% rename from specs/fault-proof/challenge.md rename to specs/zk-fault-proof/challenge.md index 602c085..19a5c92 100644 --- a/specs/fault-proof/challenge.md +++ b/specs/zk-fault-proof/challenge.md @@ -43,7 +43,7 @@ the one who submitted the first valid ZK fault proof is given the asserter's sta against collusion between asserters and challengers, tax is imposed. If there are any ongoing challenges, the challenges are canceled, and staked bonds are refunded to the respective challengers. -In the ZK fault-proof challenge process, the following undeniable bug might arise, prompting the intervention of the +In the ZK fault proof challenge process, the following undeniable bug might arise, prompting the intervention of the [Security Council][g-security-council]: - The deletion of a valid output due to two valid and contradictory ZK proofs @@ -110,11 +110,11 @@ Here we give a simple example with a small number to show you how it works. Let' block is the block a challenger wants to argue against and this number is decomposed into 5 and 2. Also, let's assume that both of them agree the state transitions to the 2nd block. -| Turn | Action | Segment Start | Segment Length | Segments | Condition | -|------------|-----------------|---------------|----------------|-----------------|--------------------| -| Challenger | createChallenge | 0 | 6 | [0, 2, ..., 10] | No | -| Asserter | bisect(2) | 2 | 3 | [2, 3', 4'] | 2 = 2 && 4 != 4' | -| Challenger | proveFault(2) | 2 | 2 | [2, 3''] | 2 = 2 && 3' != 3'' | +| Turn | Action | Segment Start | Segment Length | Segments | Condition | +|------------|-----------------------|---------------|----------------|-----------------|--------------------| +| Challenger | createChallenge | 0 | 6 | [0, 2, ..., 10] | No | +| Asserter | bisect(2) | 2 | 3 | [2, 3', 4'] | 2 = 2 && 4 != 4' | +| Challenger | proveFaultWithZkVm(2) | 2 | 2 | [2, 3''] | 2 = 2 && 3' != 3'' | You can notice that in each turn, the first element of the segments must be same with the element at the same index of the previous segments. Whereas, the last element of the segments must be different from the element at the same index of @@ -125,101 +125,28 @@ the challenge will be canceled automatically. ## Proving Fault -Since Colosseum verifies public input along with [zkEVM-proof](zkevm-prover.md#zkevm-proof), challengers should -calculate as below and enclose the public input to the `proveFault` transaction. +Since Colosseum verifies public input along with [zkVM proof](zkvm-prover.md#zkvm-proving-system), challengers should +enclose the below public input `publicValues` and `zkVmProof` to the `proveFaultWithZkVm` transaction. -```ts -import { DataOptions, hexlify } from '@ethersproject/bytes'; -import { Wallet, constants } from 'ethers'; -import { keccak256 } from 'ethers/lib/utils'; - -function strip0x(str: string): string { - if (str.startsWith('0x')) { - return str.slice(2); - } - return str; -} - -function toFixedBuffer( - value: string | number, - length, - padding = '0', -): Buffer { - const options: DataOptions = { - hexPad: 'left', - }; - return hexToBuffer( - strip0x(hexlify(value, options)).padStart(length * 2, padding), - ); -} - -async function getDummyTxHash(chainId: number): Promise { - const sk = hex.toFixedBuffer(1, 32); - const signer = new Wallet(sk); - const rlp = await signer.signTransaction({ - nonce: 0, - gasLimit: 0, - gasPrice: 0, - to: constants.AddressZero, - value: 0, - data: '0x', - chainId, - }); - return keccak256(rlp); -} - -async function computePublicInput(block: RPCBlock, chainId: number): Promise<[string, string]> { - const maxTxs = 100; - - const buf = Buffer.concat([ - hex.toFixedBuffer(prevStateRoot, 32), - hex.toFixedBuffer(block.stateRoot, 32), - hex.toFixedBuffer(block.withdrawalsRoot ?? 0, 32), - hex.toFixedBuffer(block.hash, 32), - hex.toFixedBuffer(block.parentHash, 32), - hex.toFixedBuffer(block.number, 8), - hex.toFixedBuffer(block.timestamp, 8), - hex.toFixedBuffer(block.baseFeePerGas ?? 0, 32), - hex.toFixedBuffer(block.gasLimit, 8), - hex.toFixedBuffer(block.transactions.length, 2), - Buffer.concat( - block.transactions.map((txHash: string) => { - return toFixedBuffer(txHash, 32); - }), - ), - Buffer.concat( - Array(maxTxs - block.transactions.length).fill( - toFixedBuffer(await getDummyTxHash(chainId), 32), - ), - ), - ]); - const h = hex.toFixedBuffer(keccak256(buf), 32); - return [ - '0x' + h.subarray(0, 16).toString('hex'), - '0x' + h.subarray(16, 32).toString('hex'), - ]; -} +```text +publicValues = output_root_parent ++ output_root_target ++ l1_head ``` -The following is the verification process of invalid output by -[ZK Verifier Contract](zkevm-prover.md#the-zk-verifier-contract): +The following is the [verification process of invalid output at `proveFaultWithZkVm` +function](zkvm-prover.md#proving-fault): 1. Check whether the challenge is ready to prove. The status of challenge should be `READY_TO_PROVE` or `ASSERTER_TIMEOUT`. -2. Check whether `srcOutputRootProof` is the preimage of the first output root of the segment. -3. Check whether `dstOutputRootProof` is the preimage of the next output root of the segment. -4. Verify that the `nextBlockHash` in `srcOutputRootProof` matches the `blockHash` in `dstOutputRootProof`. -5. Verify that the `stateRoot` in `publicInput` matches the `stateRoot` in `dstOutputRootProof`. -6. Verify that the `nextBlockHash` in `srcOutputRootProof` matches the block hash derived from `publicInput` and `rlps`. -7. Verify that the `withdrawalStorageRoot` in `dstOutputRootProof` is contained in `stateRoot` in `dstOutputRootProof` - using `merkleProof`. -8. If the length of transaction hashes in `publicInput` is less than `MAX_TXS`, fill it with `DUMMY_HASH`. -9. Verify the `_zkproof` using `_pair` and `publicInputHash`. The `publicInputHash` is derived from the `publicInput` - and `stateRoot` of `srcOutputRootProof`, while `_zkproof` and `_pair` are submitted by the challenger directly. -10. Delete the output and request validation of the challenge to [Security Council][g-security-council] if there is any - undeniable bugs such as soundness error. -11. If the deleted output was valid so the challenge has an undeniable bug, Security Council will - [dismiss](#dismiss-challenge) the challenge and roll back the output. +2. Check whether the first 32 bytes of `publicValues` is the preimage of the parent output root stored onchain. +3. Check whether the second 32 bytes of `publicValues` is the preimage of the target output root stored onchain. +4. Verify that the `l1Head` stored in `Challenge` is included as the `publicValues`. +5. Verify `zkVmProgramVKey` used to generate `zkVmProof` is same as `ZKVM_PROGRAM_V_KEY`, which is given as a constant + defined at the `ZKProofVerifier` contract. +6. Verify the `zkVmProof` with `publicValues` and `ZKVM_PROGRAM_V_KEY` in a ZK verifier contract. +7. Delete the output and request validation of the challenge to [Security Council][g-security-council] if there is any + undeniable bugs such as soundness error. +8. If the deleted output was valid so the challenge has an undeniable bug, Security Council will + [dismiss](#dismiss-challenge) the challenge and roll back the output. ## Dismiss Challenge @@ -330,7 +257,7 @@ interface Colosseum { ); /** - * @notice Creates a challenge against an invalid output. + * @notice Creates a challenge against an invalid output. * * @param _outputIndex Index of the invalid L2 checkpoint output. * @param _l1BlockHash The block hash of L1 at the time the output L2 block was created. @@ -345,7 +272,7 @@ interface Colosseum { ) external; /** - * @notice Selects an invalid section and submit segments of that section. + * @notice Selects an invalid section and submit segments of that section. * * @param _outputIndex Index of the L2 checkpoint output. * @param _challenger Address of the challenger. @@ -360,22 +287,31 @@ interface Colosseum { ) external; /** - * @notice Proves that a specific output is invalid using ZKP. - * This function can only be called in the READY_TO_PROVE and ASSERTER_TIMEOUT states. - * - * @param _outputIndex Index of the L2 checkpoint output. - * @param _pos Position of the last valid segment. - * @param _proof Proof for public input validation. - * @param _zkproof Halo2 proofs composed of points and scalars. - * See https://zcash.github.io/halo2/design/implementation/proofs.html. - * @param _pair Aggregated multi-opening proofs and public inputs. (Currently only 2 public inputs) - */ - function proveFault( + * @notice Proves that a specific output is invalid using zkEVM proof. + * This function can only be called in the READY_TO_PROVE and ASSERTER_TIMEOUT statuses. + * + * @param _outputIndex Index of the L2 checkpoint output. + * @param _pos Position of the last valid segment. + * @param _zkEvmProof The public input and proof using zkEVM. + */ + function proveFaultWithZkEvm( + uint256 _outputIndex, + uint256 _pos, + Types.ZkEvmProof calldata _zkEvmProof + ) external; + + /** + * @notice Proves that a specific output is invalid using zkVM proof. + * This function can only be called in the READY_TO_PROVE and ASSERTER_TIMEOUT statuses. + * + * @param _outputIndex Index of the L2 checkpoint output. + * @param _pos Position of the last valid segment. + * @param _zkVmProof The public input and proof using zkVM. + */ + function proveFaultWithZkVm( uint256 _outputIndex, uint256 _pos, - Types.PublicInputProof calldata _proof, - uint256[] calldata _zkproof, - uint256[] calldata _pair + Types.ZkVmProof calldata _zkVmProof ) external; /** @@ -434,11 +370,6 @@ Colosseum contract should be deployed behind upgradable proxies. | Name | Value | Unit | |-------------------------------|--------------------------------------------------------------------|-------------------| -| `REQUIRED_BOND_AMOUNT` | 200000000000000000 (0.2 ETH) | wei | -| `FINALIZATION_PERIOD_SECONDS` | 604800 | seconds | -| `CREATION_PERIOD_SECONDS` | 518400 | seconds | | `BISECTION_TIMEOUT` | 3600 | seconds | | `PROVING_TIMEOUT` | 28800 | seconds | | `SEGMENTS_LENGTHS` | [9, 6, 10, 6] | array of integers | -| `MAX_TXS` | 100 | uint256 | -| `DUMMY_HASH` | 0xedf1ae3da135c124658e215a9bf53477facb442a1dcd5a92388332cb6193237f | bytes32 | diff --git a/specs/zk-fault-proof/zkvm-prover.md b/specs/zk-fault-proof/zkvm-prover.md new file mode 100644 index 0000000..a3b2dde --- /dev/null +++ b/specs/zk-fault-proof/zkvm-prover.md @@ -0,0 +1,117 @@ +# zkVM Prover + + + +**Table of Contents** + +- [Overview](#overview) +- [zkVM Proving System](#zkvm-proving-system) + - [Guest Program](#guest-program) + - [Host Program](#host-program) + - [Public Values of Proof](#public-values-of-proof) + - [Proving Fault](#proving-fault) + + + + + +[g-zk-fault-proof]: ../glossary.md#zk-fault-proof +[g-state]: ../glossary.md#state +[g-l2-chain-derivation]: ../glossary.md#l2-chain-derivation +[g-sequencer-batch]: ../glossary.md#sequencer-batch +[g-colosseum-contract]: ../glossary.md#colosseum-contract + +## Overview + +A prover is responsible for generating proof using the [Plonky3](https://github.com/Plonky3/Plonky3/) +for a target blocks. This proof provides claims regarding the legitimacy of block data and state transitions. +A prover plays a vital role in the challenge process, serving as a key component of the challenger. + +A [ZK fault proof][g-zk-fault-proof] demonstrates that a [state][g-state] transition from `S` to `Sā€™` is valid based on +the transactions within the block. While this may seem similar to a validity proof, the key difference lies in its +purpose. The ZK fault proof is used to demonstrate that a state transition from `S` to `S''` is incorrect by +providing evidence of a valid state transition from `S` to `S'`. + +## zkVM Proving System + +The zkVM (Zero-Knowledge Virtual Machine) is a virtual machine that executes guest program compiled with a specified +compiler generating zero-knowledge proofs for their execution. The guest program can be written in standard programming +languages, such as Rust and Go. + +In current version of zkVM fault proof, the proving scheme is based on [SP1] by Succinct. + +[SP1]: https://github.com/succinctlabs/sp1 + +### Guest Program + +For [ZK Fault Proof System](challenge.md#proving-fault), the guest program is an extension of +[L2 Chain Derivation][g-l2-chain-derivation] that includes a connectivity check among the blocks from L1 origin block to +the specified block `C`. The hash of Block `C` is determined as the parent hash stored when the challenge is created by +calling `createChallenge` of the [Colosseum contract][g-colosseum-contract]. + +If the attacker manipulates any data within the extension of L2 Chain Derivation, it will affect the block hash `C`. +This is because all data is ultimately linked to the block hash `C` through the hash chain. Therefore if any data +manipulating attack can be thwarted by checking the block hash `C` value. For example, if an attacker creates a proof +using a transaction that is not included in the [sequencer batch][g-sequencer-batch], the block `C` value will change, +preventing them from winning the challenge. + +Guest program used in this system is implemented based on [Kona]. + +[Kona]: https://github.com/anton-rs/kona + +### Host Program + +The host program is a main part of the prover, responsible for delivering the guest program and its input to the zkVM. +The host program first executes the guest program ([Kona]) to gather the necessary data. Then, during the second +execution within the zkVM, the collected data is provided as input. After the zkVM execution is completed, the Host +program retrieves the SP1 zkVM proof along with the public inputs disclosed by the guest program. + +### Public Values of Proof + +To mark which blocks have been executed, the proof publicly reveals the following data. + +``` plain +1. Output root at the parent block of the target +2. Output root at the target block +3. Hash of the block C +``` + +### Proving Fault + +The ZK proof generated by a prover can be verified on chain. + +```solidity + /** + * @notice Proves that a specific output is invalid using zkVM proof. + * This function can only be called in the READY_TO_PROVE and ASSERTER_TIMEOUT statuses. + * + * @param _outputIndex Index of the L2 checkpoint output. + * @param _pos Position of the last valid segment. + * @param _zkVmProof The public input and proof using zkVM. + */ + function proveFaultWithZkVm( + uint256 _outputIndex, + uint256 _pos, + Types.ZkVmProof calldata _zkVmProof + ) external; +``` + +The verify function of `SP1VerifierPlonk` contract, which will be used in `proveFaultWithZkVm` for verification of +provided ZK proof, is implemented following the below interface. + +```solidity +interface SP1VerifierPlonk { + /// @notice Verifies a proof with given public values and vkey. + /// @param programVKey The verification key for the RISC-V program. + /// @param publicValues The public values encoded as bytes. + /// @param proofBytes The proof of the program execution the SP1 zkVM encoded as bytes. + function verifyProof( + bytes32 programVKey, + bytes calldata publicValues, + bytes calldata proofBytes + ) external view; +} +``` + +where programVKey is the verification key for the RISC-V program used in [SP1] prover, and +the `publicValues` is concatenated value of public values as described [above](#public-values-of-proof).