Skip to content

Commit 2c0dac7

Browse files
sm-stacksm-stack
committed
docs: add Kroma MPT migration upgrade
1 parent 5e9efe3 commit 2c0dac7

File tree

4 files changed

+147
-0
lines changed

4 files changed

+147
-0
lines changed

‎specs/SUMMARY.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,9 @@
3131
- [Ecotone](./protocol/ecotone/overview.md)
3232
- [Derivation](./protocol/ecotone/derivation.md)
3333
- [L1 attributes](./protocol/ecotone/l1-attributes.md)
34+
- [Kroma MPT Migration](./protocol/mpt-migration/overview.md)
35+
- [Execution Engine](./protocol/mpt-migration/exec-engine.md)
36+
- [Predeploys](./protocol/mpt-migration/predeploys.md)
3437
- [Fault Proof]()
3538
- [Challenge](zk-fault-proof/challenge.md)
3639
- [zkVM Prover](zk-fault-proof/zkvm-prover.md)

‎specs/protocol/mpt-migration/exec-engine.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# L2 Execution Engine
2+
3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
**Table of Contents**
6+
7+
- [Overview](#overview)
8+
- [Timestamp Activation](#timestamp-activation)
9+
- [EVM Changes](#evm-changes)
10+
- [Transition from ZK Trie to MPT](#transition-from-zk-trie-to-mpt)
11+
- [`SELFDESTRUCT` opcode](#selfdestruct-opcode)
12+
- [`isSystemTransaction` boolean at transaction struct](#issystemtransaction-boolean-at-transaction-struct)
13+
- [Fee Distribution Process](#fee-distribution-process)
14+
15+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
16+
17+
[g-zktrie]: ../../glossary.md#zk-trie
18+
[g-mpt]: ../../glossary.md#merkle-patricia-trie
19+
[validator-system]: ../validator-v2/overview.md
20+
21+
## Overview
22+
23+
This upgrade changes the underlying trie structure of the execution client from the [ZK Trie][g-zktrie] to the
24+
[Merkle Patricia Trie][g-mpt]. There are also subsequent changes to the EVM to enhance the compatibility with
25+
Vanilla OP Stack.
26+
27+
## Timestamp Activation
28+
29+
Kroma MPT Migration upgrade, like other network upgrades, is activated at a timestamp. Changes to the L2 Block execution
30+
rules are applied when the `L2 Timestamp >= activation time`.
31+
32+
## EVM Changes
33+
34+
### Transition from ZK Trie to MPT
35+
36+
The underlying trie structure of the execution client is changed from the ZK Trie to the Merkle Patricia Trie. This
37+
enhances the performance of the execution client, and reduces the operational cost of maintaining zkEVM circuits by
38+
enabling the proving scheme transition to zkVM.
39+
40+
### `SELFDESTRUCT` opcode
41+
42+
The `SELFDESTRUCT` opcode was regarded as invalid opcode, since zkEVM proving system used in ZK fault proof cannot prove
43+
the self-destruct operation. However, with the transition to zkVM, the `SELFDESTRUCT` opcode is now enabled, following
44+
rules that are defined at [EIP-6780].
45+
46+
[EIP-6780]: https://eips.ethereum.org/EIPS/eip-6780
47+
48+
### `isSystemTransaction` boolean at transaction struct
49+
50+
In the previous version of the protocol, the `isSystemTransaction` boolean was removed. To enhance the compatibility
51+
with vanilla OP Stack, the `isSystemTransaction` boolean is re-enabled.
52+
53+
However, since `isSystemTransaction` was disabled as in the [Regolith upgrade](../regolith/overview.md), system
54+
transactions remain to use the same gas accounting rules as regular deposits.
55+
56+
## Fee Distribution Process
57+
58+
The fee distribution process is updated to be compatible with OP Stack. Previously, the fee distribution process was
59+
defined to support robustness of validator system.
60+
61+
| Vault | Address | Amount |
62+
|------------------------|----------------------------------------------|-----------------------------------------------------------------------|
63+
| `ProtocolVault` | `0x4200000000000000000000000000000000000006` | `(base_fee + priority_fee) * (10000 - validatorRewardScalar) / 10000` |
64+
| `L1FeeVault` | `0x4200000000000000000000000000000000000007` | `l1_cost` |
65+
| `ValidatorRewardVault` | `0x4200000000000000000000000000000000000008` | `(base_fee + priority_fee) * validatorRewardScalar / 10000` |
66+
67+
However, with transition to [KRO-based validator system][validator-system], validators are now getting KRO rewards,
68+
and `validatorRewardScalar` was set to 0. After Kroma MPT Migration upgrade, the fee distribution process is updated
69+
as follows:
70+
71+
| Vault | Address | Amount |
72+
|---------------------|----------------------------------------------|----------------|
73+
| `SequencerFeeVault` | `0x4200000000000000000000000000000000000011` | `priority_fee` |
74+
| `BaseFeeVault` | `0x4200000000000000000000000000000000000019` | `base_fee` |
75+
| `L1FeeVault` | `0x420000000000000000000000000000000000001a` | `l1_cost` |

‎specs/protocol/mpt-migration/overview.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Kroma MPT Migration
2+
3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
**Table of Contents**
6+
7+
- [Execution Layer](#execution-layer)
8+
- [Smart Contracts](#smart-contracts)
9+
10+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
11+
12+
## Execution Layer
13+
14+
- [Transition from ZK Trie to MPT](./exec-engine.md#transition-from-zk-trie-to-mpt)
15+
- [`SELFDESTRUCT` opcode](./exec-engine.md#selfdestruct-opcode)
16+
- [`isSystemTransaction` boolean at transaction struct](./exec-engine.md#issystemtransaction-boolean)
17+
- [Fee distribution process](./exec-engine.md#fee-distribution-process)
18+
19+
## Smart Contracts
20+
21+
- [System Config](./predeploys.md#systemconfig)
22+
- [L1 Block](./predeploys.md#l1block)

‎specs/protocol/mpt-migration/predeploys.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# System Config
2+
3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
**Table of Contents**
6+
7+
- [Overview](#overview)
8+
- [`SystemConfig`](#systemconfig)
9+
- [`L1Block`](#l1block)
10+
11+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
12+
13+
## Overview
14+
15+
The `SystemConfig` and `L1Block` is updated to reflect changes of deprecated `validatorRewardScalar`.
16+
17+
### `SystemConfig`
18+
19+
`validatorRewardScalar` is now unused and removed from the `SystemConfig`.
20+
21+
### `L1Block`
22+
23+
After Kroma MPT migration upgrade, `L1Block` does not store the `validatorRewardScalar`.
24+
The interface of `setL1BlockValues` is updated as follows:
25+
26+
```solidity
27+
/// @notice Updates the L1 block values.
28+
/// @param _number L1 blocknumber.
29+
/// @param _timestamp L1 timestamp.
30+
/// @param _basefee L1 basefee.
31+
/// @param _hash L1 blockhash.
32+
/// @param _sequenceNumber Number of L2 blocks since epoch start.
33+
/// @param _batcherHash Versioned hash to authenticate batcher by.
34+
/// @param _l1FeeOverhead L1 fee overhead.
35+
/// @param _l1FeeScalar L1 fee scalar.
36+
function setL1BlockValues(
37+
uint64 _number,
38+
uint64 _timestamp,
39+
uint256 _basefee,
40+
bytes32 _hash,
41+
uint64 _sequenceNumber,
42+
bytes32 _batcherHash,
43+
uint256 _l1FeeOverhead,
44+
uint256 _l1FeeScalar,
45+
uint256 _validatorRewardScalar
46+
) external;
47+
```

0 commit comments

Comments
 (0)