op-node: Add comments to pipeline stages (#3213)

* op-node: Add comments to pipeline stages

This explains each stage in a bit better detail.

* Update op-node/rollup/derive/attributes_queue.go
Co-authored-by: Javed Khan <javed@optimism.io>
Co-authored-by: Javed Khan <javed@optimism.io>

op-node/rollup/derive/attributes_queue.go

@@ -10,6 +10,17 @@ import (
 	"github.com/ethereum/go-ethereum/log"
 )
 
+// The attributes queue sits in between the batch queue and the engine queue
+// It transforms batches into payload attributes. The outputted payload
+// attributes cannot be buffered because each batch->attributes transformation
+// pulls in data about the current L2 safe head.
+//
+// It also buffers batches that have been output because multiple batches can
+// be created at once.
+//
+// This stage can be reset by clearing it's batch buffer.
+// This stage does not need to retain any references to L1 blocks.
+
 type AttributesQueueOutput interface {
 	AddSafeAttributes(attributes *eth.PayloadAttributes)
 	SafeL2Head() eth.L2BlockRef

op-node/rollup/derive/batch_queue.go

@@ -12,6 +12,21 @@ import (
 	"github.com/ethereum/go-ethereum/log"
 )
 
+// The batch queue is responsible for ordering unordered batches & generating empty batches
+// when the sequence window has passed. This is a very stateful stage.
+//
+// It receives batches that are tagged with the L1 Inclusion block of the batch. It only considers
+// batches that are inside the sequencing window of a specific L1 Origin.
+// It tries to eagerly pull batches based on the current L2 safe head.
+// Otherwise it filters/creates an entire epoch's worth of batches at once.
+//
+// This stage tracks a range of L1 blocks with the assumption that all batches with an L1 inclusion
+// block inside that range have been added to the stage by the time that it attempts to advance a
+// full epoch.
+//
+// It is internally responsible for making sure that batches with L1 inclusions block outside it's
+// working range are not considered or pruned.
+
 type BatchQueueOutput interface {
 	StageProgress
 	AddBatch(batch *BatchData)

op-node/rollup/derive/calldata_source.go

@@ -12,6 +12,11 @@ import (
 	"github.com/ethereum/go-ethereum/log"
 )
 
+// CalldataSource readers raw transactions from a given block & then filters for
+// batch submitter transactions.
+// This is not a stage in the pipeline, but a wrapper for another stage in the pipeline
+//
+
 type L1TransactionFetcher interface {
 	InfoAndTxsByHash(ctx context.Context, hash common.Hash) (eth.L1Info, types.Transactions, error)
 }

op-node/rollup/derive/channel_bank.go

@@ -12,6 +12,17 @@ import (
 	"github.com/ethereum/go-ethereum/log"
 )
 
+// ChannelBank is a stateful stage that does the following:
+// 1. Unmarshalls frames from L1 transaction data
+// 2. Applies those frames to a channel
+// 3. Attempts to read from the channel when it is ready
+// 4. Prunes channels (not frames) when the channel bank is too large.
+//
+// Note: we prune before we ingest data.
+// As we switch between ingesting data & reading, the prune step occurs at an odd point
+// Specifically, the channel bank is not allowed to become too large between successive calls
+// to `IngestData`. This means that we can do an ingest and then do a read while becoming too large.
+
 type ChannelBankOutput interface {
 	StageProgress
 	WriteChannel(data []byte)

op-node/rollup/derive/channel_in_reader.go

@@ -11,6 +11,11 @@ import (
 	"github.com/ethereum/go-ethereum/rlp"
 )
 
+// Channel In Reader reads a batch from the channel
+// This does decompression and limits the max RLP size
+// This is a pure function from the channel, but each channel (or channel fragment)
+// must be tagged with an L1 inclusion block to be passed to the the batch queue.
+
 // zlib returns an io.ReadCloser but explicitly documents it is also a zlib.Resetter, and we want to use it as such.
 type zlibReader interface {
 	io.ReadCloser

op-node/rollup/derive/l1_retrieval.go

@@ -9,6 +9,9 @@ import (
 	"github.com/ethereum/go-ethereum/log"
 )
 
+// This is a generic wrapper around fetching all transactions in a block & then
+// it feeds one L1 transaction at a time to the next stage
+
 // DataIter is a minimal iteration interface to fetch rollup input data from an arbitrary data-availability source
 type DataIter interface {
 	// Next can be repeatedly called for more data, until it returns an io.EOF error.