diff --git a/.github/ISSUE_TEMPLATE/FEATURE-FORM.yml b/.github/ISSUE_TEMPLATE/FEATURE-FORM.yml index c15dc772b..ffdc3049b 100644 --- a/.github/ISSUE_TEMPLATE/FEATURE-FORM.yml +++ b/.github/ISSUE_TEMPLATE/FEATURE-FORM.yml @@ -16,11 +16,8 @@ body: - consensus - network - genesis - - protocol - provider - op-alloy - - registry - - rpc-jsonrpsee - rpc-types - rpc-types-engine - other diff --git a/README.md b/README.md index e589bee62..dc604c77b 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ shall be dual licensed as above, without any additional terms or conditions. [check-no-std]: ./scripts/check_no_std.sh -[kona]: https://github.com/anton-rs/kona +[kona]: https://github.com/op-rs/kona [alloy]: https://github.com/alloy-rs/alloy [contributing]: https://alloy-rs.github.io/op-alloy diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 69b127abc..710d3482e 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -8,16 +8,8 @@ - [System Config](./building/genesis/system-config.md) - [Consensus](./building/consensus.md) - [Engine RPC Types](./building/engine.md) - - [Protocol](./building/protocol/README.md) - - [BlockInfo and L2BlockInfo Types](./building/protocol/block-info.md) - - [Frames](./building/protocol/frames.md) - - [Channels](./building/protocol/channels.md) - - [Batches](./building/protocol/batches.md) - [Examples](./examples/README.md) - [Load a Rollup Config](./examples/load-a-rollup-config.md) - - [Create a new L1BlockInfoTx Hardfork Variant](./examples/new-l1-block-info-tx-hardfork.md) - - [Transform Frames to a Batch](./examples/frames-to-batch.md) - - [Transform a Batch into Frames](./examples/batch-to-frames.md) - [Contributing](./CONTRIBUTING.md) - [Licensing](./LICENSE.md) - [Glossary](./glossary.md) diff --git a/book/src/building/README.md b/book/src/building/README.md index 5359e68d1..79ec52085 100644 --- a/book/src/building/README.md +++ b/book/src/building/README.md @@ -11,8 +11,6 @@ Some of the primary crates and their types are listed below. - [`op-alloy-rpc-types-engine`][op-alloy-rpc-types-engine] provides the [`OpPayloadAttributes`][op-payload-attributes] and [`OpAttributesWithParent`][op-attributes-with-parent]. -- [`op-alloy-protocol`][op-alloy-protocol] provides [`Frame`][frame], - [`Channel`][channel], [`Batch`][batch] types and more. @@ -28,11 +26,6 @@ Some of the primary crates and their types are listed below. [op-payload-attributes]: https://docs.rs/op-alloy-rpc-types-engine/latest/op_alloy_rpc_types_engine/struct.OpPayloadAttributes.html [op-attributes-with-parent]: https://docs.rs/op-alloy-rpc-types-engine/latest/op_alloy_rpc_types_engine/struct.OpAttributesWithParent.html -[frame]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html -[channel]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html -[batch]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/enum.Batch.html - [op-alloy-genesis]: https://crates.io/crates/op-alloy-genesis [op-alloy-consensus]: https://crates.io/crates/op-alloy-consensus -[op-alloy-protocol]: https://crates.io/crates/op-alloy-protocol [op-alloy-rpc-types-engine]: https://crates.io/crates/op-alloy-rpc-types-engine diff --git a/book/src/building/protocol/README.md b/book/src/building/protocol/README.md deleted file mode 100644 index df694ba33..000000000 --- a/book/src/building/protocol/README.md +++ /dev/null @@ -1,66 +0,0 @@ -# Protocol - -op-alloy-protocol crate - -The [`op-alloy-protocol`][protocol] crate contains types, constants, and methods -specific to Optimism derivation and batch-submission. - -[`op-alloy-protocol`][protocol] supports `no_std`. - -## Background - -Protocol types are primarily used for L2 chain derivation. This section will -break down L2 chain derivation as it relates to types defined in -`op-alloy-protocol` - that is, from the raw L2 chain data posted to L1, to the -[`Batch`][batch] type. And since the [`Batch`][batch] type naively breaks up -into the payload attributes, once executed, it becomes the canonical L2 block! -Note though, this provides an incredibly simplified introduction. It is advised -to reference [the specs][s] for the most up-to-date information regarding -derivation. - -The L2 chain is derived from data posted to the L1 chain - either as calldata -or blob data. Data is iteratively pulled from each L1 block and translated -into the first type defined by `op-alloy-protocol`: the [`Frame`][frame] type. - -[`Frame`][frame]s are [parsed][parsed] from the raw data. Each [`Frame`][frame] -is a part of a [`Channel`][channel], the next type one level up in deriving -L2 blocks. [`Channel`][channel]s have IDs that frames reference. [`Frame`][frame]s -are [added][added] iteratively to the [`Channel`][channel]. Once a -[`Channel`][channel] [is ready][ready], it can be used to read a [`Batch`][batch]. - -Since a [`Channel`][channel] stitches together frames, it contains the raw frame -data. In order to turn this [`Channel`][channel] data into a [`Batch`][batch], -it needs to be decompressed using the respective (de)compression algorithm -(see [the channel specs][channel-specs] for more detail on this). Once -decompressed, the raw data can be [decoded][decoded] into the [`Batch`][batch] -type. - - -## Sections - -#### Core Derviation Types (discussed above) - -- [Frames](./frames.md) -- [Channels](./channels.md) -- [Batches](./batches.md) - -#### Other Critical Protocol Types - -- [BlockInfo and L2BlockInfo Types](./block-info.md) -- [L1BlockInfo Types](./l1-block-info.md) - - - - -[decoded]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/enum.Batch.html#method.decode -[batch]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/enum.Batch.html -[ready]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html#method.is_ready -[added]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html#method.add_frame -[channel]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html -[frame]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html -[parsed]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html#method.parse_frames - -[protocol]: https://crates.io/crates/op-alloy-protocol -[s]: https://specs.optimism.io/protocol/derivation.html#overview -[lcd]: https://specs.optimism.io/protocol/derivation.html#overview -[channel-specs]: https://specs.optimism.io/protocol/derivation.html#channel-format diff --git a/book/src/building/protocol/batches.md b/book/src/building/protocol/batches.md deleted file mode 100644 index 7873873c6..000000000 --- a/book/src/building/protocol/batches.md +++ /dev/null @@ -1,117 +0,0 @@ -# Batches - -A [Batch][batch] contains a list of transactions to be included in a specific -L2 block. Since the [Delta hardfork][delta], there are two Batch types or -variants: [`SingleBatch`][single-batch] and [`SpanBatch`][span-batch]. - - -## Where Batches fit in the OP Stack - -The [Batch][batch] is the highest-level data type in the OP Stack -derivation process that comes prior to building payload attributes. -A [Batch][batch] is constructed by taking the raw data from a -[Channel][channel], decompressing it, and decoding the [Batch][batch] -from this decompressed data. - -Alternatively, when looking at the [Batch][batch] type from a batching -perspective, and not from the derivation perspective, the [Batch][batch] -type contains a list of L2 transactions and is compressed into the -[`Channel`][channel] type. In turn, the [`Channel`][channel] is split -into frames which are posted to the data availability layer through batcher -transactions. - - -## Contents of a `Batch` - -A [`Batch`][batch] is either a [`SingleBatch`][single-batch] or a -[`SpanBatch`][span-batch], each with their own contents. Below, -these types are broken down in their respective sections. - -### `SingleBatch` Type - -The [`SingleBatch`][single-batch] type contains the following. -- A [`BlockHash`][block-hash] parent hash that represents the parent L2 block. -- A `u64` epoch number that identifies the [epoch][epoch] for this batch. -- A [`BlockHash`][block-hash] epoch hash. -- The timestamp for the batch as a `u64`. -- A list of EIP-2718 encoded transactions (represented as [`Bytes`][bytes]). - -In order to validate the [`SingleBatch`][single-batch] once decoded, -the [`SingleBatch::check_batch`][check-batch-single] method should be used, -providing the rollup config, l1 blocks, l2 safe head, and inclusion block. - -### `SpanBatch` Type - -The [`SpanBatch`][span-batch] type (available since the [Delta hardfork][delta]) -comprises the data needed to build a "span" of multiple L2 blocks. It contains -the following data. -- The parent check (the first 20 bytes of the block's parent hash). -- The l1 origin check (the first 20 bytes of the last block's l1 origin hash). -- The genesis timestamp. -- The chain id. -- A list of [`SpanBatchElement`][span-batch-element]s. These are similar to - the [`SingleBatch`][single-batch] type but don't contain the parent hash - and epoch hash for this L2 block. -- Origin bits. -- Block transaction counts. -- Span batch transactions which contain information for transactions in a span batch. - -Similar to the `SingleBatch` type discussed above, the [`SpanBatch`][span-batch] type -must be validated once decoded. For this, the [`SpanBatch::check_batch`][check-batch-span] -method is available. - -After the [Holocene hardfork][holocene] was introduced, span batch validation is greatly -simplified to be forwards-invalidating instead of backwards-invalidating, so a new -[`SpanBatch::check_batch_prefix`][check-batch-prefix] method provides a way to validate -each batch as it is loaded, in an iterative fashion. - - -## Batch Encoding - -The first byte of the decompressed channel data is the -[`BatchType`][batch-type], which identifies whether the batch is a -[`SingleBatch`][single-batch] or a [`SpanBatch`][span-batch]. -From there, the respective type is decoded, and [derived][derived] -in the case of the [`SpanBatch`][span-batch]. - -The `Batch` encoding format for the [`SingleBatch`][single-batch] is -broken down [in the specs][specs]. - - -## The `Batch` Type - -The [`Batch`][batch] type itself only provides two useful methods. -- [`timestamp`][timestamp] returns the timestamp of the [`Batch`][batch] -- [`deocde`][decode], constructs a new [`Batch`][batch] from the provided - raw, decompressed batch data and rollup config. - -Within each [`Batch`][batch] variant, the individual types contain -more functionality. - - - - -[holocene]: https://specs.optimism.io/protocol/holocene/overview.html -[check-batch-prefix]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.SpanBatch.html#method.check_batch_prefix -[check-batch-span]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.SpanBatch.html#method.check_batch -[span-batch-element]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.SpanBatchElement.html -[check-batch-single]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.SingleBatch.html#method.check_batch - -[bytes]: https://docs.rs/alloy-primitives/latest/alloy_primitives/struct.Bytes.html - -[block-hash]: https://docs.rs/alloy-primitives/latest/alloy_primitives/aliases/type.BlockHash.html -[epoch]: https://specs.optimism.io/glossary.html?highlight=Epoch#sequencing-epoch - -[decode]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/enum.Batch.html#method.decode -[timestamp]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/enum.Batch.html#method.timestamp - -[specs]: https://specs.optimism.io/protocol/derivation.html#batch-format - -[derived]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.RawSpanBatch.html#method.derive -[batch-type]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/enum.BatchType.html -[channel]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html -[batch]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/enum.Batch.html -[span-batch]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.SpanBatch.html -[single-batch]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.SingleBatch.html - -[delta]: https://specs.optimism.io/protocol/delta/overview.html diff --git a/book/src/building/protocol/block-info.md b/book/src/building/protocol/block-info.md deleted file mode 100644 index 06f980bd1..000000000 --- a/book/src/building/protocol/block-info.md +++ /dev/null @@ -1,27 +0,0 @@ -# BlockInfo and L2BlockInfo Types - -Optimism defines block info types that encapsulate minimal block header -information needed by protocol operations. - - -## BlockInfo - -The [`BlockInfo`][bi] type is straightforward, containing the block hash, -number, parent hash, and timestamp. - - -## L2BlockInfo - -The [`L2BlockInfo`][lbi] extends the [`BlockInfo`][bi] type for the canonical -L2 chain. It contains the "L1 origin" which is a set of block info for the L1 -block that this L2 block "originated". - -[`L2BlockInfo`][lbi] provides a [`from_block_and_gensis`][fbg] method to -construct the [`L2BlockInfo`][lbi] from a block and `ChainGenesis`. - - - - -[bi]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.BlockInfo.html -[lbi]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.L2BlockInfo.html -[fbg]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.L2BlockInfo.html#method.from_block_and_genesis diff --git a/book/src/building/protocol/channels.md b/book/src/building/protocol/channels.md deleted file mode 100644 index f5005f23b..000000000 --- a/book/src/building/protocol/channels.md +++ /dev/null @@ -1,109 +0,0 @@ -# Channels - -Taken from the [OP Stack specs][specs], [`Channel`][channel]s are a set of -sequencer batches (for any L2 blocks) compressed together. - - -## Where Channels fit in the OP Stack - -L2 transactions are grouped into what are called [sequencer batches][seq-batch]. -In order to obtain a better compression ratio when posting these L2 transactions -to the data availability layer, [sequencer batches][seq-batch] are compressed -together into what is called a [Channel][channel]. This ultimately reduces -data availability costs. As previously noted in the [Frame][frame-docs] section, -[Channel][channel]s may not "fit" in a single batcher transaction, posting the -data to the data availability layer. In order to accommodate large -[Channel][channel]s, a tertiary [Frame][frame] data type breaks the -[Channel][channel] up into multiple [Frame][frame]s where a batcher transaction -then consists of one or multiple [Frame][frame]s. - - -## Contents of a Channel - -A [Channel][channel] is comprised of the following items. -- A [`ChannelId`][cid] which is a 16 byte long identifier for the channel. - Notice, [Frame][frame]s also contain a [`ChannelId`][cid], which is the - identical to this identifier, since frames "belong" to a given channel. -- A [`BlockInfo`][block-info] that marks the L1 block at which the channel - is "opened" at. -- The estimated size of the channel (as a `usize`) used to drop the channel - if there is a data overflow. -- A `boolean` if the channel is "closed". This indicates if the last frame - has been buffered, and added to the channel. -- A `u16` indicating the highest frame number within the channel. -- The frame number of the last frame (where `is_last` set to `true`). -- A mapping from Frame number to the [`Frame`][frame] itself. -- A [`BlockInfo`][block-info] for highest L1 inclusion block that a frame - was included in. - - -## Channel Encoding - -[`Channel`][channel] encoding is even more straightforward than that of a -[`Frame`][frame]. Simply, a [`Channel`][channel] is the concatenated list -of encoded [`Frame`][frame]s. - -Since each [`Frame`][frame] contains the [`ChannelId`][cid] that corresponds -to the given [`Channel`][channel], constructing a [`Channel`][channel] is as -simple as calling the [`Channel::add_frame`][add-frame] method for each of -its [`Frame`][frame]s. - -Once the [`Channel`][channel] has ingested all of it's [`Frame`][frame]s, -it will be marked as "ready", with the [`Channel::is_ready`][is-ready] -method returning `true`. - - -## The `Channel` Type - -As discussed [above](#-channel-encoding), the [`Channel`][channel] type is -expected to be populated with [`Frame`][frame]s using its -[`Channel::add_frame`][add-frame] method. Below we demonstrate constructing -a minimal [`Channel`][channel] using a few frames. - -```rust -use op_alloy_protocol::{Channel, Frame}; - -// Construct a channel at the given L1 block. -let id = [0xee; 16]; -let block = BlockInfo::default(); -let mut channel = Channel::new(id, block); - -// The channel will consist of 3 frames. -let frame_0 = Frame { id: [0xee; 16], number: 0, ..Default::default() }; -let frame_1 = Frame { id: [0xee; 16], number: 1, ..Default::default() }; -let frame_2 = Frame { id: [0xee; 16], number: 2, is_last: true, ..Default::default() }; - -// Add the frames to the channel. -channel.add_frame(frame_0); -channel.add_frame(frame_1); -channel.add_frame(frame_2); - -// Since the last frame was ingested, -// the channel should be ready. -assert!(channel.is_ready()); -``` - -There are a few rules when adding a [`Frame`][frame] to a [`Channel`][channel]. -- The [`Frame`][frame]'s id must be the same [`ChannelId`][cid] as the [`Channel`][channel]s. -- [`Frame`][frame]s cannot be added once a [`Channel`][channel] is closed. -- [`Frame`][frame]s within a [`Channel`][channel] must have distinct numbers. - -Notice, [`Frame`][frame]s can be added out-of-order so long as the [`Channel`][channel] is -still open, and the frame hasn't already been added. - - - - -[is-ready]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html#method.is_ready -[add-frame]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html#method.add_frame - -[block-info]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.BlockInfo.html - -[frame-docs]: ./frames.md -[specs]: https://specs.optimism.io/protocol/derivation.html#batch-submission-wire-format -[seq-batch]: https://specs.optimism.io/glossary.html#sequencer-batch - - -[channel]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html -[cid]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/type.ChannelId.html -[frame]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html diff --git a/book/src/building/protocol/frames.md b/book/src/building/protocol/frames.md deleted file mode 100644 index 411e3acc6..000000000 --- a/book/src/building/protocol/frames.md +++ /dev/null @@ -1,85 +0,0 @@ -# Frames - -[`Frame`][frame]s are the lowest level data format in the OP Stack protocol. - - -## Where Frames fit in the OP Stack - -Transactions posted to the data availability layer of the rollup -contain one or multiple [Frame][frame]s. Frames are chunks of raw data that -belong to a given [Channel][channel], the next, higher up data format in the -OP Stack protocol. Importantly, a given transaction can contain -a variety of frames from _different_ channels, allowing maximum flexibility -when breaking up channels into batcher transactions. - - -## Contents of a Frame - -A [Frame][frame] is comprised of the following items. -- A [`ChannelId`][cid] which is a 16 byte long identifier for the channel that - the given frame belongs to. -- A `number` that identifies the index of the frame within the channel. Frames - are 0-indexed and are bound to `u16` size limit. -- `data` contains the raw data within the frame. -- `is_last` marks if the frame is the last within the channel. - - -## Frame Encoding - -When frames are posted through a batcher transaction, they are encoded as a -contiguous list with a single byte prefix denoting the derivation version. -The encoding can be represented as the following concatenated bytes. - -``` -encoded = DERIVATION_VERSION_0 ++ encoded_frame_0 ++ encoded_frame_1 ++ .. -``` - -Where `DERIVATION_VERSION_0` is a single byte (`0x00`) indicating the derivation -version including how the frames are encoded. Currently, the only supported -derivation version is `0`. - - -`encoded_frame_0`, `encoded_frame_1`, and so on, are all [`Frame`][frame]s encoded -as raw bytes. A single encoded [`Frame`][frame] can be represented by the following -concatenation of it's fields. - -``` -encoded_frame = channel_id ++ frame_number ++ frame_data_length ++ frame_data ++ is_last -``` - -Where `++` represents concatenation. The frame's fields map to it's encoding. -- `channel_id` is the 16 byte long [`Frame::id`][id]. -- `frame_number` is the 2 byte long (or `u16`) [`Frame::number`][number]. -- `frame_data_length` and `frame_data` provide the necessary details to decode - the [`Frame::data`][data], where `frame_data_length` is 4 bytes long (or `u32`). -- `is_last` is a single byte [`Frame::is_last`][is_last]. - - -## op-alloy's `Frame` Type - -[`op-alloy-protocol`][protocol] provides the [`Frame`][frame] type with a few useful -methods. [`Frame`][frame]s can be encoded and decoded using the [`Frame::encode`][encode] -and [`Frame::decode`][decode] methods. Given the raw batcher transaction data or blob data -containing the concatenated derivation version and contiguous list of encoded frames, -the [`Frame::parse_frame`][parse_frame] and [`Frame::parse_frames`][parse_frames] methods -provide ways to decode single and multiple frames, respectively. - - - - -[encode]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html#method.encode -[decode]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html#method.decode - -[parse_frame]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html#method.parse_frame -[parse_frames]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html#method.parse_frames - -[protocol]: https://crates.io/crate/op-alloy-protocol - -[id]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html#structfield.id -[number]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html#structfield.number -[data]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html#structfield.data -[is_last]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html#structfield.is_last - -[cid]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/type.ChannelId.html -[channel]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html -[frame]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html diff --git a/book/src/examples/README.md b/book/src/examples/README.md index 7e241ba72..b7da6dd0f 100644 --- a/book/src/examples/README.md +++ b/book/src/examples/README.md @@ -3,6 +3,3 @@ Examples for working with `op-alloy-*` crates. - [Load a Rollup Config for a Chain ID](./load-a-rollup-config.md) -- [Create a new L1BlockInfoTx Hardfork Variant](./new-l1-block-info-tx-hardfork.md) -- [Transform Frames to a Batch](./frames-to-batch.md) -- [Transform a Batch to Frames](./batch-to-frames.md) diff --git a/book/src/examples/batch-to-frames.md b/book/src/examples/batch-to-frames.md deleted file mode 100644 index 4fc2bf804..000000000 --- a/book/src/examples/batch-to-frames.md +++ /dev/null @@ -1,62 +0,0 @@ -# Transform a Batch into Frames - -> [!NOTE] -> -> This example performs the reverse transformation as the [frames-to-batch][frames-to-batch] example. - -> [!CAUTION] -> -> Steps and handling of types with respect to chain tip, ordering of frames, re-orgs, and -> more are not covered by this example. This example solely demonstrates the most trivial -> way to transform an individual [`Batch`][batch] into [`Frame`][frame]s. - -This example walks through transforming a [`Batch`][batch] into [`Frame`][frame]s. - -Effectively, this example demonstrates the _encoding_ process from an L2 batch into the -serialized bytes that are posted to the data availability layer. - -## Walkthrough - -The high level transformation is the following. - -``` -Batch -> decompressed batch data -> ChannelOut -> frames[] -> bytes[] -``` - -Given the [`Batch`][batch], the first step to encode the batch -using the [`Batch::encode()`][encode-batch] method. The output bytes -need to then be compressed prior to adding them to the -[`ChannelOut`][channel-out]. - -> [!NOTE] -> -> The [`ChannelOut`][channel-out] type also provides a method for adding -> the [`Batch`][batch] itself, handling encoding and compression, but -> this method is not available yet. - -Once compressed using the [`compress_brotli`][compress-brotli] method, the -compressed bytes can be added to a newly constructed [`ChannelOut`][channel-out]. -As long as the [`ChannelOut`][channel-out] has [`ready_bytes()`][ready-bytes], -[`Frame`][frame]s can be constructed using the -[`ChannelOut::output_frame()`][output-frame] method, specifying the maximum -frame size. - -Once [`Frame`][frame]s are returned from the [`ChannelOut`][channel-out], -they can be [`Frame::encode`][encode-frame] into raw, serialized data -ready to be batch-submitted to the data-availability layer. - - -## Running this example: - -- Clone the examples repository: `git clone git@github.com:alloy-rs/op-alloy.git` -- Run: `cargo run --example batch_to_frames` - -```rust -{{#include ../../../crates/protocol/examples/batch_to_frames.rs}} -``` - - - -[frames-to-batch]: ./frames-to-batch.md - -{{#include ../links.md}} diff --git a/book/src/examples/frames-to-batch.md b/book/src/examples/frames-to-batch.md deleted file mode 100644 index 15736dd3f..000000000 --- a/book/src/examples/frames-to-batch.md +++ /dev/null @@ -1,57 +0,0 @@ -# Transform Frames into a Batch - -> [!NOTE] -> -> This example performs the reverse transformation as the [batch-to-frames][batch-to-frames] example. - -> [!CAUTION] -> -> Steps and handling of types with respect to chain tip, ordering of frames, re-orgs, and -> more are not covered by this example. This example solely demonstrates the most trivial -> way to transform individual [`Frame`][frame]s into a [`Batch`][batch] type. - -This example walks through transforming [`Frame`][frame]s into the [`Batch`][batch] types. - -## Walkthrough - -The high level transformation is the following. - -``` -raw bytes[] -> frames[] -> channel -> decompressed channel data -> Batch -``` - -Given the raw, batch-submitted frame data as bytes (read in with the [`hex!` macro][hex]), -the first step is to decode the frame data into [`Frame`][frame]s using -[`Frame::decode`][decode-frame]. Once all the [`Frame`][frame]s are decoded, -the [`Channel`][channel] can be constructed using the [`ChannelId`][channel-id] -of the first frame. - -> [!Note] -> -> [`Frame`][frame]s may also be added to a [`Channel`][channel] -> once decoded with the [`Channel::add_frame`][add-frame] method. - -When the [`Channel`][channel] is [`Channel::is_ready()`][is-ready], -the frame data can taken from the [`Channel`][channel] using -[`Channel::frame_data()`][frame-data]. This data is represented as [`Bytes`][bytes] -and needs to be decompressed using the respective compression algorithm depending on -which hardforks are activated (using the `RollupConfig`). For the sake of this example, -`brotli` is used (which was activated in the [Fjord hardfork][fjord]). Decompressed -brotli bytes can then be passed right into [`Batch::decode`][decode-batch] -to wind up with the example's desired [`Batch`][batch]. - - -## Running this example: - -- Clone the examples repository: `git clone git@github.com:alloy-rs/op-alloy.git` -- Run: `cargo run --example frames_to_batch` - -```rust -{{#include ../../../crates/protocol/examples/frames_to_batch.rs}} -``` - - - -[batch-to-frames]: ./batch-to-frames.md - -{{#include ../links.md}} diff --git a/book/src/examples/new-l1-block-info-tx-hardfork.md b/book/src/examples/new-l1-block-info-tx-hardfork.md deleted file mode 100644 index a16ad3e4e..000000000 --- a/book/src/examples/new-l1-block-info-tx-hardfork.md +++ /dev/null @@ -1,113 +0,0 @@ -# Create a L1BlockInfoTx Variant for a new Hardfork - -This example walks through creating a variant of the [`L1BlockInfoTx`][info-tx] -for a new Hardfork. - -> [!NOTE] -> -> This example is very verbose. -> To grok required changes, view [this PR diff][pr-diff] -> which introduces Isthmus hardfork changes to the `L1BlockInfoTx` with a new variant. - - -## Required Genesis Updates - -The first updates that need to be made are to [`op-alloy-genesis`][genesis] -types, namely the [`RollupConfig`][rc] and [`HardForkConfiguration`][hfc]. - -First, add a timestamp field to the [`RollupConfig`][rc]. Let's use the -hardfork name "Glacier" as an example. - -```rust -pub struct RollupConfig { - ... - /// `glacier_time` sets the activation time for the Glacier network upgrade. - /// Active if `glacier_time` != None && L2 block timestamp >= Some(glacier_time), inactive - /// otherwise. - #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))] - pub glacier_time: Option, - ... -} -``` - -Add an accessor on the [`RollupConfig`][rc] to provide a way of checking whether the -"Glacier" hardfork is active for a given timestamp. Also update the prior hardfork -accessor to call this method (let's use "Isthmus" as the prior hardfork). - -```rust - /// Returns true if Isthmus is active at the given timestamp. - pub fn is_isthmus_active(&self, timestamp: u64) -> bool { - self.isthmus_time.map_or(false, |t| timestamp >= t) || self.is_glacier_active(timestamp) - } - - /// Returns true if Glacier is active at the given timestamp. - pub fn is_glacier_active(&self, timestamp: u64) -> bool { - self.glacier_time.map_or(false, |t| timestamp >= t) - } -``` - -Lastly, add the "Glacier" timestamp to the [`HardForkConfiguration`][hfc]. - -```rust -pub struct HardForkConfiguration { - ... - /// Glacier hardfork activation time - pub glacier_time: Option, -} -``` - - -## Protocol Changes - -Introduce a new `glacier.rs` module containing a `L1BlockInfoGlacier` type -in [`op_alloy_genesis::info` module][info-mod]. - -This should include a few methods used in the `L1BlockInfoTx` later. - -```rust - pub fn encode_calldata(&self) -> Bytes { ... } - - pub fn decode_calldata(r: &[u8]) -> Result { ... } -``` - -Use other hardfork variants like the [`L1BlockInfoEcotone`][ecotone] -for reference. - -Next, add the new "Glacier" variant to the [`L1BlockInfoTx`][info-tx]. - -```rust -pub enum L1BlockInfoTx { - ... - Glacier(L1BlockInfoGlacier) -} -``` - -Update [`L1BlockInfoTx::try_new`][try-new] to construct the `L1BlockInfoGlacier` -if the hardfork is active using the `RollupConfig::is_glacier_active`. - -Also, be sure to update [`L1BlockInfoTx::decode_calldata`][decode-calldata] -with the new variant decoding, as well as other [`L1BlockInfoTx`][info-tx] -methods. - -Once some tests are added surrounding the decoding and encoding of the new -`L1BlockInfoGlacier` variant, all required changes are complete! - -Now, [this example PR diff][pr-diff] introducing the Isthmus changes should -make sense, since it effectively implements the above changes for the Isthmus -hardfork (replacing "Glacier" with "Isthmus"). Notice, Isthmus introduces -some new "operator fee" fields as part of it's `L1BlockInfoIsthmus` type. -Some new error variants to the [`BlockInfoError`][bie] are needed as well. - - - - -[bie]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/enum.BlockInfoError.html -[pr-diff]: https://github.com/alloy-rs/op-alloy/pull/130/files -[decode-calldata]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/enum.L1BlockInfoTx.html#method.decode_calldata -[try-new]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/enum.L1BlockInfoTx.html#method.try_new -[ecotone]: https://github.com/alloy-rs/op-alloy/blob/main/crates/protocol/src/info/ecotone.rs -[info-mod]: https://github.com/alloy-rs/op-alloy/blob/main/crates/protocol/src/info/mod.rs -[genesis]: https://docs.rs/op-alloy-genesis/latest/op_alloy_genesis/index.html -[rc]: https://docs.rs/op-alloy-genesis/latest/op_alloy_genesis/struct.RollupConfig.html -[hfc]: https://docs.rs/op-alloy-genesis/latest/op_alloy_genesis/struct.HardForkConfiguration.html -[info-tx]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/enum.L1BlockInfoTx.html diff --git a/book/src/links.md b/book/src/links.md index 702bb3831..e561c931d 100644 --- a/book/src/links.md +++ b/book/src/links.md @@ -8,7 +8,6 @@ [op-alloy-consensus]: https://crates.io/crates/op-alloy-consensus [op-alloy-genesis]: https://crates.io/crates/op-alloy-genesis [op-alloy-network]: https://crates.io/crates/op-alloy-network -[op-alloy-protocol]: https://crates.io/crates/op-alloy-protocol [op-alloy-rpc-types-engine]: https://crates.io/crates/op-alloy-rpc-types-engine [op-alloy-rpc-types]: https://crates.io/crates/op-alloy-rpc-types @@ -21,28 +20,6 @@ [update]: https://docs.rs/op-alloy-genesis/latest/op_alloy_genesis/system/struct.SystemConfig.html#method.update_with_receipts [system-config]: https://docs.rs/op-alloy-genesis/latest/op_alloy_genesis/system/struct.SystemConfig.html - - -[compress-brotli]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/fn.compress_brotli.html -[encode-batch]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.SingleBatch.html#method.encode -[encode-frame]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html#method.encode -[add-frame]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html#method.add_frame -[decode-batch]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.SingleBatch.html#method.decode -[single-batch]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.SingleBatch.html -[bytes]: https://docs.rs/alloy-primitives/latest/alloy_primitives/struct.Bytes.html -[channel-id]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/type.ChannelId.html -[channel]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html -[channel-out]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.ChannelOut.html -[ready-bytes]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.ChannelOut.html#method.ready_bytes -[output-frame]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.ChannelOut.html#method.output_frame -[decode-frame]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html#method.decode -[hex]: https://docs.rs/hex-literal/latest/hex_literal/macro.hex.html -[fjord]: https://specs.optimism.io/protocol/fjord/overview.html -[frame-data]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html#method.frame_data -[is-ready]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Channel.html#method.is_ready -[frame]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/struct.Frame.html -[batch]: https://docs.rs/op-alloy-protocol/latest/op_alloy_protocol/enum.Batch.html - [consensus]: https://crates.io/crates/op-alloy-consensus @@ -75,9 +52,10 @@ +[maili]: https://github.com/op-rs/maili [revm]: https://github.com/bluealloy/revm [2718]: https://eips.ethereum.org/EIPS/eip-2718 -[cannon-rs]: https://github.com/anton-rs/cannon-rs +[cannon-rs]: https://github.com/op-rs/cannon-rs [asterisc]: https://github.com/ethereum-optimism/asterisc [op-stack]: https://github.com/ethereum-optimism/optimism [op-succinct]: https://github.com/succinctlabs/op-succinct @@ -93,11 +71,11 @@ -[kona]: https://github.com/anton-rs/kona -[book]: https://anton-rs.github.io/kona/ -[issues]: https://github.com/anton-rs/kona/issues -[new-issue]: https://github.com/anton-rs/kona/issues/new -[contributing]: https://github.com/anton-rs/kona/tree/main/CONTRIBUTING.md +[kona]: https://github.com/op-rs/kona +[book]: https://op-rs.github.io/kona/ +[issues]: https://github.com/op-rs/kona/issues +[new-issue]: https://github.com/op-rs/kona/issues/new +[contributing]: https://github.com/op-rs/kona/tree/main/CONTRIBUTING.md diff --git a/book/src/starting.md b/book/src/starting.md index 0ad604194..296cbe954 100644 --- a/book/src/starting.md +++ b/book/src/starting.md @@ -63,7 +63,6 @@ so `op-alloy-consensus` types can be used from `op-alloy` through `op_alloy::con - [`op-alloy-network`][op-alloy-network] - [`op-alloy-genesis`][op-alloy-genesis] (supports `no_std`) -- [`op-alloy-protocol`][op-alloy-protocol] (supports `no_std`) - [`op-alloy-consensus`][op-alloy-consensus] (supports `no_std`) - [`op-alloy-rpc-types`][op-alloy-rpc-types] (supports `no_std`) - [`op-alloy-rpc-types-engine`][op-alloy-rpc-types-engine] (supports `no_std`) @@ -74,7 +73,6 @@ As noted above, the following crates are `no_std` compatible. - [`op-alloy-consensus`][op-alloy-consensus] - [`op-alloy-genesis`][op-alloy-genesis] -- [`op-alloy-protocol`][op-alloy-protocol] - [`op-alloy-rpc-types-engine`][op-alloy-rpc-types-engine] - [`op-alloy-rpc-types`][op-alloy-rpc-types] diff --git a/crates/genesis/README.md b/crates/genesis/README.md index b4c9e2437..b680481b8 100644 --- a/crates/genesis/README.md +++ b/crates/genesis/README.md @@ -34,4 +34,4 @@ This is based off of [alloy-genesis]. [alloy-genesis]: https://github.com/alloy-rs -[kona]: https://github.com/anton-rs/kona/blob/main/Cargo.toml#L137 +[kona]: https://github.com/op-rs/kona/blob/main/Cargo.toml#L137 diff --git a/crates/op-alloy/README.md b/crates/op-alloy/README.md index 4430ca0a8..7ea47969a 100644 --- a/crates/op-alloy/README.md +++ b/crates/op-alloy/README.md @@ -81,7 +81,7 @@ shall be dual licensed as above, without any additional terms or conditions. [check-no-std]: https://github.com/alloy-rs/op-alloy/blob/main/scripts/check_no_std.sh -[kona]: https://github.com/anton-rs/kona +[kona]: https://github.com/op-rs/kona [alloy]: https://github.com/alloy-rs/alloy [contributing]: https://alloy-rs.github.io/op-alloy