kroma-network · sm-stack · Dec 10, 2024 · Nov 27, 2024 · Nov 28, 2024 · Dec 2, 2024
@@ -16,14 +16,23 @@
     - [Rollup Node](./protocol/rollup-node.md)
       - [Rollup Node P2P](./protocol/rollup-node-p2p.md)
       - [Derivation](./protocol/derivation.md)
-      - [Span Batches](./protocol/span-batches.md)
     - [Batch Submitter](./protocol/batcher.md)
     - [Validator](./protocol/validation.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)
+  - [Protocol Upgrades]()
+    - [Regolith](./protocol/regolith/overview.md)
+    - [Canyon](./protocol/canyon/overview.md)
+    - [Delta](./protocol/delta/overview.md)
+      - [Span Batches](./protocol/delta/span-batches.md)
+    - [Ecotone](./protocol/ecotone/overview.md)
+      - [Derivation](./protocol/ecotone/derivation.md)
+      - [L1 attributes](./protocol/ecotone/l1-attributes.md)
+    - [Kroma MPT Migration](./protocol/mpt-migration/overview.md)
+      - [Execution Engine](./protocol/mpt-migration/exec-engine.md)
 - [ZK Fault Proof]()
   - [Challenge](zk-fault-proof/challenge.md)
   - [zkVM Prover](zk-fault-proof/zkvm-prover.md)

@@ -0,0 +1,46 @@
+# Canyon
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Execution Layer](#execution-layer)
+- [Consensus Layer](#consensus-layer)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+[eip3651]: https://eips.ethereum.org/EIPS/eip-3651
+[eip3855]: https://eips.ethereum.org/EIPS/eip-3855
+[eip3860]: https://eips.ethereum.org/EIPS/eip-3860
+[eip4895]: https://eips.ethereum.org/EIPS/eip-4895
+[eip6049]: https://eips.ethereum.org/EIPS/eip-6049
+
+[block-validation]: ../rollup-node-p2p.md#block-validation
+[payload-attributes]: ../derivation.md#building-individual-payload-attributes
+[1559-params]: ../exec-engine.md#1559-parameters
+[channel-reading]: ../derivation.md#reading
+[deposit-reading]: ../deposits.md#deposit-receipt
+[create2deployer]: ../predeploys.md#create2deployer
+
+The Canyon upgrade contains the Shapella upgrade from L1 and some minor protocol fixes.
+The Canyon upgrade uses a _L2 block-timestamp_ activation-rule, and is specified in both the
+rollup-node (`canyon_time`) and execution engine (`config.canyonTime`). Shanghai time in the
+execution engine should be set to the same time as the Canyon time.
+
+## Execution Layer
+
+- Shapella Upgrade
+  - [EIP-3651: Warm COINBASE][eip3651]
+  - [EIP-3855: PUSH0 instruction][eip3855]
+  - [EIP-3860: Limit and meter initcode][eip3860]
+  - [EIP-4895: Beacon chain push withdrawals as operations][eip4895]
+    - [Withdrawals are prohibited in P2P Blocks][block-validation]
+    - [Withdrawals should be set to the empty array with Canyon][payload-attributes]
+  - [EIP-6049: Deprecate SELFDESTRUCT][eip6049]
+- [Modifies the EIP-1559 Denominator][1559-params]
+- [Adds the deposit nonce & deposit nonce version to the deposit receipt hash][deposit-reading]
+- [Deploys the create2Deployer to `0x13b0D85CcB8bf860b6b79AF3029fCA081AE9beF2`][create2deployer]
+
+## Consensus Layer
+
+- [Channel Ordering Fix][channel-reading]
@@ -0,0 +1,17 @@
+# Delta
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Consensus Layer](#consensus-layer)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+The Delta upgrade uses a _L2 block-timestamp_ activation-rule, and is specified only in the rollup-node (`delta_time`).
+
+## Consensus Layer
+
+[span-batches]: ./span-batches.md
+
+The Delta upgrade consists of a single consensus-layer feature: [Span Batches][span-batches].
@@ -6,9 +6,9 @@
 
 - [Introduction](#introduction)
 - [Span batch format](#span-batch-format)
-  - [Max span-batch size](#max-span-batch-size)
+  - [Span Batch Size Limits](#span-batch-size-limits)
   - [Future batch-format extension](#future-batch-format-extension)
-- [Span batch Activation Rule](#span-batch-activation-rule)
+- [Span Batch Activation Rule](#span-batch-activation-rule)
 - [Optimization Strategies](#optimization-strategies)
   - [Truncating information and storing only necessary data](#truncating-information-and-storing-only-necessary-data)
   - [`tx_data_headers` removal from initial specs](#tx_data_headers-removal-from-initial-specs)
@@ -18,7 +18,7 @@
   - [Store `y_parity` and `protected_bit` instead of `v`](#store-y_parity-and-protected_bit-instead-of-v)
   - [Adjust `txs` Data Layout for Better Compression](#adjust-txs-data-layout-for-better-compression)
   - [`fee_recipients` Encoding Scheme](#fee_recipients-encoding-scheme)
-- [How derivation works with Span Batch?](#how-derivation-works-with-span-batch)
+- [How Derivation works with Span Batches](#how-derivation-works-with-span-batches)
 - [Integration](#integration)
   - [Channel Reader (Batch Decoding)](#channel-reader-batch-decoding)
   - [Batch Queue](#batch-queue)
@@ -28,7 +28,13 @@
 
 <!-- All glossary references in this file. -->
 
-[g-deposit-tx-type]: ../glossary.md#deposited-transaction-type
+[g-deposit-tx-type]: ../../glossary.md#deposited-transaction-type
+[derivation]: ../derivation.md
+[channel-format]: ../derivation.md#channel-format
+[batch-format]: ../derivation.md#batch-format
+[frame-format]: ../derivation.md#frame-format
+[batch-queue]: ../derivation.md#batch-queue
+[batcher]: ../batcher.md
 
 ## Introduction
 
@@ -40,11 +46,11 @@ The overhead is reduced by representing a span of
 consecutive L2 blocks in a more efficient manner,
 while preserving the same consistency checks as regular batch data.
 
-Note that the [channel](./derivation.md#channel-format) and
-[frame](./derivation.md#frame-format) formats stay the same:
+Note that the [channel][channel-format] and
+[frame][frame-format] formats stay the same:
 data slicing, packing and multi-transaction transport is already optimized.
 
-The overhead in the [V0 batch format](./derivation.md) comes from:
+The overhead in the [V0 batch format][derivation] comes from:
 
 - The meta-data attributes are repeated for every L2 block, while these are mostly implied already:
   - parent hash (32 bytes)
@@ -67,9 +73,9 @@ Span-batches address these inefficiencies, with a new batch format version.
 [span-batch-format]: #span-batch-format
 
 Note that span-batches, unlike previous singular batches,
-encode *a range of consecutive* L2 blocks at the same time.
+encode _a range of consecutive_ L2 blocks at the same time.
 
-Introduce version `1` to the [batch-format](./derivation.md#batch-format) table:
+Introduce version `1` to the [batch-format][batch-format] table:
 
 | `batch_version` | `content`           |
 | --------------- | ------------------- |
@@ -133,22 +139,21 @@ tx_sigs ++ tx_tos ++ tx_datas ++ tx_nonces ++ tx_gases ++ protected_bits`
 [EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559
 [EIP-155]: https://eips.ethereum.org/EIPS/eip-155
 
-### Max span-batch size
+### Span Batch Size Limits
 
-Total size of encoded span batch is limited to `MAX_SPAN_BATCH_SIZE` (currently 10,000,000 bytes,
-equal to `MAX_RLP_BYTES_PER_CHANNEL`). Therefore every field size of span batch will be implicitly limited to
-`MAX_SPAN_BATCH_SIZE` . There can be at least single span batch per channel, and channel size is limited
-to `MAX_RLP_BYTES_PER_CHANNEL` and you may think that there is already an implicit limit. However, having an explicit
-limit for span batch is helpful for several reasons. We may save computation costs by avoiding malicious input while
-decoding. For example, let's say bad batcher wrote span batch which `block_count = max.Uint64`. We may early return
-using the explicit limit, not trying to consume data until EOF is reached. We can also safely preallocate memory for
-decoding because we know the upper limit of memory usage.
+The total size of an encoded span batch is limited to `MAX_RLP_BYTES_PER_CHANNEL`, which is defined in the
+[Protocol Parameters table](../derivation.md#protocol-parameters).
+This is done at the channel level rather than at the span batch level.
+
+In addition to the byte limit, the number of blocks, and total transactions is limited to `MAX_SPAN_BATCH_ELEMENT_COUNT`
+. This does imply that the max number of transactions per block is also `MAX_SPAN_BATCH_ELEMENT_COUNT`.
+`MAX_SPAN_BATCH_ELEMENT_COUNT` is defined in [Protocol Parameters table](../derivation.md#protocol-parameters).
 
 ### Future batch-format extension
 
 This is an experimental extension of the span-batch format, and not activated with the Delta upgrade yet.
 
-Introduce version `2` to the [batch-format](derivation.md#batch-format) table:
+Introduce version `2` to the [batch-format][batch-format] table:
 
 | `batch_version` | `content`           |
 | --------------- | ------------------- |
@@ -167,7 +172,7 @@ Where:
     - `fee_recipients_idxs`: for each block,
       `uvarint` number of index to decode fee recipients from `fee_recipients_set`.
 
-## Span batch Activation Rule
+## Span Batch Activation Rule
 
 The span batch upgrade is activated based on timestamp.
 
@@ -225,11 +230,10 @@ Deposit transactions are excluded in batches and are never written at L1 so excl
 
 ### Adjust `txs` Data Layout for Better Compression
 
-There are (7 choose 2) * 5! = 2520 permutations of ordering fields of `txs`.
-It is not 7! because `contract_creation_bits` must be first decoded in order to decode `tx_tos`.
-We experimented to find out the best layout for compression.
-It turned out placing random data together(`TxSigs`, `TxTos`, `TxDatas`),
-then placing leftovers helped gzip to gain more size reduction.
+There are (8 choose 2) \* 6! = 20160 permutations of ordering fields of `txs`.  It is not 8!
+because `contract_creation_bits` must be first decoded in order to decode `tx_tos`.  We
+experimented with different data layouts and found that segregating random data (`tx_sigs`,
+`tx_tos`, `tx_datas`) from the rest most improved the zlib compression ratio.
 
 ### `fee_recipients` Encoding Scheme
 
@@ -242,7 +246,7 @@ we thought sequencer rotation happens not much often, so assumed that `K` will b
 The assumption makes upper inequality to hold. Therefore, we decided to manage `fee_recipients_idxs` and
 `fee_recipients_set` separately. This adds complexity but reduces data.
 
-## How derivation works with Span Batch?
+## How Derivation works with Span Batches
 
 - Block Timestamp
   - The first L2 block's block timestamp is `rel_timestamp + L2Genesis.Timestamp`.
@@ -282,7 +286,7 @@ Span-batches share the same queue with v0 batches: batches are processed in L1 i
 
 A set of modified validation rules apply to the span-batches.
 
-Rules are enforced with the [contextual definitions](./derivation.md#batch-queue) as v0-batch validation:
+Rules are enforced with the [contextual definitions][batch-queue] as v0-batch validation:
 `epoch`, `inclusion_block_number`, `next_timestamp`
 
 Definitions:
@@ -307,7 +311,7 @@ Span-batch rules, in validation order:
 - `batch.parent_check != prev_l2_block.hash[:20]` -> `drop`:
   i.e. the checked part of the parent hash must be equal to the same part of the corresponding L2 block hash.
 - Sequencing-window checks:
-  - Note: The sequencing window is enforced for the *batch as a whole*:
+  - Note: The sequencing window is enforced for the _batch as a whole_:
     if the batch was partially invalid instead, it would drop the oldest L2 blocks,
     which makes the later L2 blocks invalid.
   - Variables:
@@ -328,7 +332,7 @@ Span-batch rules, in validation order:
     - `start_epoch_num < prev_l2_block.l1_origin.number` -> `drop`:
       epoch number cannot be older than the origin of parent block
 - Max Sequencer time-drift checks:
-  - Note: The max time-drift is enforced for the *batch as a whole*, to keep the possible output variants small.
+  - Note: The max time-drift is enforced for the _batch as a whole_, to keep the possible output variants small.
   - Variables:
     - `block_input`: an L2 block from the span-batch,
       with L1 origin as derived from the `origin_bits` and now established canonical L1 chain.
@@ -383,6 +387,6 @@ not directly call `(co *ChannelOut) AddBatch` but defer that until a minimum num
 Output-size estimation of the queued up blocks is not possible until the span-batch is written to the channel.
 Past a given number of blocks, the channel may be written for estimation, and then re-written if more blocks arrive.
 
-The [batcher functionality](./batcher.md) stays the same otherwise: unsafe blocks are transformed into batches,
+The [batcher functionality][batcher] stays the same otherwise: unsafe blocks are transformed into batches,
 encoded in compressed channels, and then split into frames for submission to L1.
 Batcher implementations can implement different heuristics and re-attempts to build the most gas-efficient data-txs.
@@ -16,6 +16,7 @@
   - [L1 Attributes Deposited Transaction Calldata](#l1-attributes-deposited-transaction-calldata)
     - [L1 Attributes - Genesis, Canyon, Delta](#l1-attributes---genesis-canyon-delta)
     - [L1 Attributes - Ecotone](#l1-attributes---ecotone)
+    - [L1 Attributes - Kroma MPT](#l1-attributes---kroma-mpt)
 - [Special Accounts on L2](#special-accounts-on-l2)
   - [L1 Attributes Depositor Account](#l1-attributes-depositor-account)
   - [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract)
@@ -299,6 +300,24 @@ and also set the following new attributes:
   Or `1` if the L1 block does not support blobs.
   The `1` value is derived from the EIP-4844 `MIN_BLOB_GASPRICE`.
 
+#### L1 Attributes - Kroma MPT
+
+After Kroma MPT activation, the calldata of the L1 attributes deposited transaction excludes the deprecated
+`validatorRewardScalar` argument. The overall calldata layout is as follows:
+
+| Input arg             | Type    | Calldata bytes | Segment |
+|-----------------------| ------- |----------------|---------|
+| {0x440a5e20}          |         | 0-3            | n/a     |
+| baseFeeScalar         | uint32  | 4-7            | 1       |
+| blobBaseFeeScalar     | uint32  | 8-11           |         |
+| sequenceNumber        | uint64  | 12-19          |         |
+| l1BlockTimestamp      | uint64  | 20-27          |         |
+| l1BlockNumber         | uint64  | 28-35          |         |
+| basefee               | uint256 | 36-67          | 2       |
+| blobBaseFee           | uint256 | 68-99          | 3       |
+| l1BlockHash           | bytes32 | 100-131        | 4       |
+| batcherHash           | bytes32 | 132-163        | 5       |
+
 ## Special Accounts on L2
 
 The L1 attributes deposit transaction involves two special purpose accounts:

@@ -17,8 +17,6 @@
   - [L2 Chain Derivation Pipeline](#l2-chain-derivation-pipeline)
     - [L1 Traversal](#l1-traversal)
     - [L1 Retrieval](#l1-retrieval)
-      - [Ecotone: Blob Retrieval](#ecotone-blob-retrieval)
-        - [Blob Encoding](#blob-encoding)
     - [Frame Queue](#frame-queue)
     - [Channel Bank](#channel-bank)
       - [Pruning](#pruning)
@@ -489,98 +487,6 @@ on to the next phase.
 
 [`to`]: https://github.com/ethereum/execution-specs/blob/3fe6514f2d9d234e760d11af883a47c1263eff51/src/ethereum/frontier/fork_types.py#L52C31-L52C31
 
-#### Ecotone: Blob Retrieval
-
-With the Ecotone upgrade the retrieval stage is extended to support an additional DA source:
-[EIP-4844] blobs. After the Ecotone upgrade we modify the iteration over batcher transactions to
-treat transactions of transaction-type == `0x03` (`BLOB_TX_TYPE`) differently. If the batcher
-transaction is a blob transaction, then its calldata MUST be ignored should it be present. Instead:
-
-- For each blob hash in `blob_versioned_hashes`, retrieve the blob that matches it. A blob may be
-  retrieved from any of a number different sources. Retrieval from a local beacon-node, through
-  the `/eth/v1/beacon/blob_sidecars/` endpoint, with `indices` filter to skip unrelated blobs, is
-  recommended. For each retrieved blob:
-  - The blob SHOULD (MUST, if the source is untrusted) be cryptographically verified against its
-    versioned hash.
-  - If the blob has a [valid encoding](#blob-encoding), decode it into its continuous byte-string
-    and pass that on to the next phase. Otherwise the blob is ignored.
-
-Note that batcher transactions of type blob must be processed in the same loop as other batcher
-transactions to preserve the invariant that batches are always processed in the order they appear
-in the block. We ignore calldata in blob transactions so that it may be used in the future for
-batch metadata or other purposes.
-
-##### Blob Encoding
-
-Each blob in a [EIP-4844] transaction really consists of `FIELD_ELEMENTS_PER_BLOB = 4096` field elements.
-
-Each field element is a number in a prime field of
-`BLS_MODULUS = 52435875175126190479447740508185965837690552500527637822603658699938581184513`.
-This number does not represent a full `uint256`: `math.log2(BLS_MODULUS) = 254.8570894...`
-
-The [L1 consensus-specs](https://github.com/ethereum/consensus-specs/blob/dev/specs/deneb/polynomial-commitments.md)
-describe the encoding of this polynomial.
-The field elements are encoded as big-endian integers (`KZG_ENDIANNESS = big`).
-
-To save computational overhead, only `254` bits per field element are used for rollup data.
-
-`127` bytes of application-layer rollup data is encoded at a time, into 4 adjacent field elements of the blob:
-
-```python
-# read(N): read the next N bytes from the application-layer rollup-data. The next read starts where the last stopped.
-# write(V): append V (one or more bytes) to the raw blob.
-bytes tailA = read(31)
-byte x = read(1)
-byte A = x & 0b0011_1111
-write(A)
-write(tailA)
-
-bytes tailB = read(31)
-byte y = read(1)
-byte B = (y & 0b0000_1111) | (x & 0b1100_0000) >> 2)
-write(B)
-write(tailB)
-
-bytes tailC = read(31)
-byte z = read(1)
-byte C = z & 0b0011_1111
-write(C)
-write(tailC)
-
-bytes tailD = read(31)
-byte D = ((z & 0b1100_0000) >> 2) | ((y & 0b1111_0000) >> 4)
-write(D)
-write(tailD)
-```
-
-Each written field element looks like this:
-
-- Starts with one of the prepared 6-bit left-padded byte values, to keep the field element within valid range.
-- Followed by 31 bytes of application-layer data, to fill the low 31 bytes of the field element.
-
-The written output should look like this:
-
-```text
-<----- element 0 -----><----- element 1 -----><----- element 2 -----><----- element 3 ----->
-| byte A |  tailA...  || byte B |  tailB...  || byte C |  tailC...  || byte D |  tailD...  |
-```
-
-The above is repeated 1024 times, to fill all `4096` elements,
-with a total of `(4 * 31 + 3) * 1024 = 130048` bytes of data.
-
-When decoding a blob, the top-most two bits of each field-element must be 0,
-to make the encoding/decoding bijective.
-
-The first byte of rollup-data (second byte in first field element) is used as a version-byte.
-
-In version `0`, the next 3 bytes of data are used to encode the length of the rollup-data, as big-endian `uint24`.
-Any trailing data, past the length delimiter, must be 0, to keep the encoding/decoding bijective.
-If the length is larger than `130048 - 4`, the blob is invalid.
-
-If any of the encoding is invalid, the blob as whole must be ignored.
-
-[EIP-4844]: https://eips.ethereum.org/EIPS/eip-4844
-
 ### Frame Queue
 
 The Frame Queue buffers one data-transaction at a time,