Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Batcher Configuration Page Update #1215

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Batcher Configuration Page Update #1215

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e2241f7
Bring the recommendations to the top
richardgreg Jan 3, 2025
6927ad5
Add content that outlines the standard configurability requirements a…
richardgreg Jan 3, 2025
2c0a285
Build the latest release, run the --help command and update the page …
richardgreg Jan 5, 2025
dc8e9a2
Update batcher page to accurate release version
richardgreg Jan 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
308 changes: 230 additions & 78 deletions pages/builders/chain-operators/configuration/batcher.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,50 @@ import { Callout, Tabs } from 'nextra/components'

This page lists all configuration options for the op-batcher. The op-batcher posts
L2 sequencer data to the L1, to make it available for verifiers. The following
options are from the `--help` in [v1.7.6](https://github.com/ethereum-optimism/optimism/releases/tag/v1.7.6).
options are from the `--help` in [v1.10.0](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher%2Fv1.10.0).

## Recommendations

### Set your `OP_BATCHER_MAX_CHANNEL_DURATION`

<Callout>
The default value inside `op-batcher`, if not specified, is still `0`, which means channel duration tracking is disabled.
For very low throughput chains, this would mean to fill channels until close to the sequencing window and post the channel to `L1 SUB_SAFETY_MARGIN` L1 blocks before the sequencing window expires.
</Callout>

To minimize costs, we recommend setting your `OP_BATCHER_MAX_CHANNEL_DURATION` to target 5 hours, with a value of `1500` L1 blocks. When non-zero, this parameter is the max time (in L1 blocks, which are 12 seconds each) between which batches will be submitted to the L1. If you have this set to 5 for example, then your batcher will send a batch to the L1 every 5\*12=60 seconds. When using blobs, because 130kb blobs need to be purchased in full, if your chain doesn't generate at least \~130kb of data in those 60 seconds, then you'll be posting only partially full blobs and wasting storage.

* We do not recommend setting any values higher than targeting 5 hours, as batches have to be submitted within the sequencing window which defaults to 12 hours for OP chains, otherwise your chain may experience a 12 hour long chain reorg. 5 hours is the longest length of time we recommend that still sits snugly within that 12 hour window to avoid affecting stability.
* If your chain fills up full blobs of data before the `OP_BATCHER_MAX_CHANNEL_DURATION` elapses, a batch will be submitted anyways - (e.g. even if the OP Mainnet batcher sets an `OP_BATCHER_MAX_CHANNEL_DURATION` of 5 hours, it will still be submitting batches every few minutes)

<Callout type="warning">
While setting an`OP_BATCHER_MAX_CHANNEL_DURATION` of `1500` results in the cheapest fees, it also means that your [safe head](https://github.com/ethereum-optimism/specs/blob/main/specs/glossary.md#safe-l2-head) can stall for up to 5 hours.

* This will negatively impact apps on your chain that rely on the safe head for operation. While many apps can likely operate simply by following the unsafe head, often Centralized Exchanges or third party bridges wait until transactions are marked safe before processing deposits and withdrawal.
* Thus a larger gap between posting batches can result in significant delays in the operation of certain types of high-security applications.
</Callout>

### Configure your batcher to use multiple blobs

The `op-batcher` has the capabilities to send multiple blobs per single blob transaction. This is accomplished by the use of multi-frame channels, see the [specs](https://specs.optimism.io/protocol/derivation.html#frame-format) for more technical details on channels and frames.

A minimal batcher configuration (with env vars) to enable 6-blob batcher transactions is:

```
- OP_BATCHER_BATCH_TYPE=1 # span batches, optional
- OP_BATCHER_DATA_AVAILABILITY_TYPE=blobs
- OP_BATCHER_TARGET_NUM_FRAMES=6 # 6 blobs per tx
- OP_BATCHER_TXMGR_MIN_BASEFEE=2.0 # 2 gwei, might need to tweak, depending on gas market
- OP_BATCHER_TXMGR_MIN_TIP_CAP=2.0 # 2 gwei, might need to tweak, depending on gas market
- OP_BATCHER_RESUBMISSION_TIMEOUT=240s # wait 4 min before bumping fees
```

This enables blob transactions and sets the target number of frames to 6, which translates to 6 blobs per transaction.
The minimum tip cap and base fee are also lifted to 2 gwei because it is uncertain how easy it will be to get 6-blob transactions included and slightly higher priority fees should help.
The resubmission timeout is increased to a few minutes to give more time for inclusion before bumping the fees because current transaction pool implementations require a doubling of fees for blob transaction replacements.

Multi-blob transactions are particularly useful for medium to high-throughput chains, where enough transaction volume exists to fill up 6 blobs in a reasonable amount of time.
You can use [this calculator](https://docs.google.com/spreadsheets/d/12VIiXHaVECG2RUunDSVJpn67IQp9NHFJqUsma2PndpE/edit) for your chain to determine what number of blobs are right for you, and what gas scalar configuration to use. Please also refer to guide on [Using Blobs](/builders/chain-operators/management/blobs) for chain operators.

## Global options

Expand All @@ -25,6 +68,81 @@ default value is `2m0s`.
<Tabs.Tab>`OP_BATCHER_ACTIVE_SEQUENCER_CHECK_DURATION=2m0s`</Tabs.Tab>
</Tabs>

### altda.da-server

HTTP address of a DA Server.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--altda.da-server=<value>`</Tabs.Tab>
<Tabs.Tab>`--altda.da-server=http://da.example.com:1234`</Tabs.Tab>
<Tabs.Tab>`$OP_BATCHER_ALTDA_DA_SERVER=http://da.example.com:1234`</Tabs.Tab>
</Tabs>

### altda.da-service

Use DA service type where commitments are generated by Alt-DA server. The default
value is `false`.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--altda.da-service=<value>`</Tabs.Tab>
<Tabs.Tab>`--altda.da-service=true`</Tabs.Tab>
<Tabs.Tab>`$OP_BATCHER_ALTDA_DA_SERVER=true`</Tabs.Tab>
</Tabs>

### altda.enabled

Enable Alt-DA mode
Alt-DA Mode is a Beta feature of the MIT licensed OP Stack.
While it has received initial review from core contributors, it is still
undergoing testing, and may have bugs or other issues.
The default value is `false`.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--altda.enabled=<value>`</Tabs.Tab>
<Tabs.Tab>`--altda.enabled=false`</Tabs.Tab>
<Tabs.Tab>`$OP_BATCHER_ALTDA_ENABLED=false`</Tabs.Tab>
</Tabs>

### altda.get-timeout

Timeout for get requests. **0 means no timeout**.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--altda.get-timeout=<value>`</Tabs.Tab>
<Tabs.Tab>`--altda.get-timeout=5s`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_ALTDA_GET_TIMEOUT=5s`</Tabs.Tab>
</Tabs>

### altda.max-concurrent-da-requests

Maximum number of concurrent requests to the DA server.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--altda.max-concurrent-da-requests=<value>`</Tabs.Tab>
<Tabs.Tab>`--altda.max-concurrent-da-requests=4`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_ALTDA_MAX_CONCURRENT_DA_REQUESTS=4`</Tabs.Tab>
</Tabs>

### altda.put-timeout

Timeout for put requests. **0 means no timeout**.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--altda.put-timeout=<value>`</Tabs.Tab>
<Tabs.Tab>`--altda.put-timeout=10s`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_ALTDA_PUT_TIMEOUT=10s`</Tabs.Tab>
</Tabs>

### altda.verify-on-read

Verify input data matches the commitments from the DA storage service.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--altda.verify-on-read=<value>`</Tabs.Tab>
<Tabs.Tab>`--altda.verify-on-read=true`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_ALTDA_VERIFY_ON_READ=true`</Tabs.Tab>
</Tabs>

### approx-compr-ratio

The approximate compression ratio (`<=1.0`). Only relevant for ratio
Expand Down Expand Up @@ -168,6 +286,26 @@ The lowest log level that will be output. The default value is `INFO`.
<Tabs.Tab>`OP_BATCHER_LOG_LEVEL=INFO`</Tabs.Tab>
</Tabs>

### log.pid

Show PID in the log.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--log.pid=<value>`</Tabs.Tab>
<Tabs.Tab>`--log.pid=true`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_LOG_PID=true`</Tabs.Tab>
</Tabs>

### max-blocks-per-span-batch

Maximum number of blocks to add to a span batch. **Default is 0 (no maximum)**.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--max-blocks-per-span-batch=<value>`</Tabs.Tab>
<Tabs.Tab>`--max-blocks-per-span-batch=100`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_MAX_BLOCKS_PER_SPAN_BATCH=100`</Tabs.Tab>
</Tabs>

### max-channel-duration

The maximum duration of L1-blocks to keep a channel open. 0 to disable. The
Expand Down Expand Up @@ -262,48 +400,6 @@ default value is `10`.
<Tabs.Tab>`OP_BATCHER_NUM_CONFIRMATIONS=10`</Tabs.Tab>
</Tabs>

### plasma.da-server

HTTP address of a DA Server.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--plasma.da-server=<value>`</Tabs.Tab>
<Tabs.Tab>`--plasma.da-server=`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_PLASMA_DA_SERVER=`</Tabs.Tab>
</Tabs>

### plasma.da-service

Use DA service type where commitments are generated by plasma server. The
default value is `false`.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--plasma.da-service=<value>`</Tabs.Tab>
<Tabs.Tab>`--plasma.da-service=false`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_PLASMA_DA_SERVICE=false`</Tabs.Tab>
</Tabs>

### plasma.enabled

Enable plasma mode. The default value is `false`.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--plasma.enabled=<value>`</Tabs.Tab>
<Tabs.Tab>`--plasma.enabled=false`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_PLASMA_ENABLED=false`</Tabs.Tab>
</Tabs>

### plasma.verify-on-read

Verify input data matches the commitments from the DA storage service. The
default value is `true`.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--plasma.verify-on-read=<value>`</Tabs.Tab>
<Tabs.Tab>`--plasma.verify-on-read=true`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_PLASMA_VERIFY_ON_READ=true`</Tabs.Tab>
</Tabs>

### poll-interval

How frequently to poll L2 for new blocks. The default value is `6s`.
Expand Down Expand Up @@ -470,6 +566,19 @@ Signer endpoint the client will connect to.
<Tabs.Tab>`OP_BATCHER_SIGNER_ENDPOINT=`</Tabs.Tab>
</Tabs>

### signer.header

Headers to pass to the remote signer. Format `key=value`.
Value can contain any character allowed in an HTTP header.
When using env vars, split multiple headers with commas.
When using flags, provide one key-value pair per flag.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--signer.header=<key=value>`</Tabs.Tab>
<Tabs.Tab>`--signer.header="Authorization=Bearer 123abc"`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_SIGNER_HEADER=Authorization=Bearer 123abc`</Tabs.Tab>
</Tabs>

### signer.tls.ca

tls ca cert path. The default value is `tls/ca.crt`.
Expand Down Expand Up @@ -534,6 +643,63 @@ blob tx, if using Blob DA. The default value is `1`.
<Tabs.Tab>`OP_BATCHER_TARGET_NUM_FRAMES=1`</Tabs.Tab>
</Tabs>

### throttle-always-block-size

The total DA limit to start imposing on block building **at all times**.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--throttle-always-block-size=<value>`</Tabs.Tab>
<Tabs.Tab>`--throttle-always-block-size=250000`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_THROTTLE_ALWAYS_BLOCK_SIZE=250000`</Tabs.Tab>
</Tabs>

### throttle-block-size

The total DA limit to start imposing on block building **when we are over the throttle threshold**.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--throttle-block-size=<value>`</Tabs.Tab>
<Tabs.Tab>`--throttle-block-size=50000`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_THROTTLE_BLOCK_SIZE=50000`</Tabs.Tab>
</Tabs>

---

### throttle-interval

Interval between potential DA throttling actions. **Zero disables throttling**.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--throttle-interval=<value>`</Tabs.Tab>
<Tabs.Tab>`--throttle-interval=5s`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_THROTTLE_INTERVAL=5s`</Tabs.Tab>
</Tabs>

---

### throttle-threshold

Threshold on `pending-blocks-bytes-current` beyond which the batcher instructs the
block builder to start throttling transactions with larger DA demands.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--throttle-threshold=<value>`</Tabs.Tab>
<Tabs.Tab>`--throttle-threshold=1500000`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_THROTTLE_THRESHOLD=1500000`</Tabs.Tab>
</Tabs>

---

### throttle-tx-size

The DA size of transactions at which throttling begins **when we are over the throttle threshold**.

<Tabs items={['Syntax', 'Example', 'Environment Variable']}>
<Tabs.Tab>`--throttle-tx-size=<value>`</Tabs.Tab>
<Tabs.Tab>`--throttle-tx-size=10000`</Tabs.Tab>
<Tabs.Tab>`OP_BATCHER_THROTTLE_TX_SIZE=10000`</Tabs.Tab>
</Tabs>

### txmgr.fee-limit-threshold

The minimum threshold (in GWei) at which fee bumping starts to be capped.
Expand Down Expand Up @@ -631,45 +797,31 @@ Print the version. The default value is false.
<Tabs.Tab>`--version=false`</Tabs.Tab>
</Tabs>

## Recommendations
## Batcher Policy

### Set your `OP_BATCHER_MAX_CHANNEL_DURATION`
The batcher policy defines high-level constraints and responsibilities regarding how L2 data is posted to L1. Below are the standard guidelines for configuring the batcher within the OP Stack.

<Callout>
The default value inside `op-batcher`, if not specified, is still `0`, which means channel duration tracking is disabled.
For very low throughput chains, this would mean to fill channels until close to the sequencing window and post the channel to `L1 SUB_SAFETY_MARGIN` L1 blocks before the sequencing window expires.
</Callout>
| Parameter | Description | Administrator | Requirement | Notes |
|-----------|------------|---------------|-------------|--------|
| Data Availability Type | Specifies whether the batcher uses **blobs** or **calldata** to post transaction data to L1. | Batch submitter address | Ethereum (Blobs or Calldata) | - Alternative data availability (Alt-DA) is not yet supported in the standard configuration.<br/>- The sequencer can switch at will between blob transactions and calldata, with no restrictions, because both are fully secured by L1. |
| Batch Submission Frequency | Determines how frequently the batcher submits aggregated transaction data to L1 (via the batcher transaction). | Batch submitter address | Must target **1,800 L1 blocks** (6 hours on Ethereum, assuming 12s L1 block time) or lower | - Batches must be posted before the sequencing window closes (commonly 12 hours by default).<br/>- Leave a buffer for L1 network congestion and data size to ensure that each batch is fully committed in a timely manner. |
| Output Frequency | Defines how frequently L2 output roots are submitted to L1 (via the output oracle). | L1 Proxy Admin | **43,200 L2 blocks** (24 hours at 2s block times) or lower | - Once fault proofs are implemented, this value may become deprecated.<br/>- It cannot be set to 0 (there must be some cadence for outputs). |

To minimize costs, we recommend setting your `OP_BATCHER_MAX_CHANNEL_DURATION` to target 5 hours, with a value of `1500` L1 blocks. When non-zero, this parameter is the max time (in L1 blocks, which are 12 seconds each) between which batches will be submitted to the L1. If you have this set to 5 for example, then your batcher will send a batch to the L1 every 5\*12=60 seconds. When using blobs, because 130kb blobs need to be purchased in full, if your chain doesn't generate at least \~130kb of data in those 60 seconds, then you'll be posting only partially full blobs and wasting storage.
### Additional Guidance

* We do not recommend setting any values higher than targeting 5 hours, as batches have to be submitted within the sequencing window which defaults to 12 hours for OP chains, otherwise your chain may experience a 12 hour long chain reorg. 5 hours is the longest length of time we recommend that still sits snugly within that 12 hour window to avoid affecting stability.
* If your chain fills up full blobs of data before the `OP_BATCHER_MAX_CHANNEL_DURATION` elapses, a batch will be submitted anyways - (e.g. even if the OP Mainnet batcher sets an `OP_BATCHER_MAX_CHANNEL_DURATION` of 5 hours, it will still be submitting batches every few minutes)
* **Data Availability Types**:
* **Calldata** is generally simpler but can be more expensive on mainnet Ethereum, depending on gas prices.
* **Blobs** are typically lower cost when your chain has enough transaction volume to fill large chunks of data.
* The `op-batcher` can toggle between these approaches by setting the `--data-availability-type=<blobs|calldata>` flag or with the `OP_BATCHER_DATA_AVAILABILITY_TYPE` env variable.

<Callout type="warning">
While setting an`OP_BATCHER_MAX_CHANNEL_DURATION` of `1500` results in the cheapest fees, it also means that your [safe head](https://github.com/ethereum-optimism/specs/blob/main/specs/glossary.md#safe-l2-head) can stall for up to 5 hours.
* **Batch Submission Frequency** (`OP_BATCHER_MAX_CHANNEL_DURATION` and related flags):
* Standard OP Chains frequently target a maximum channel duration between 1–6 hours.
* Your chain should never exceed your L2's sequencing window (commonly 12 hours).
* If targeting a longer submission window (e.g., 5 or 6 hours), be aware that the [safe head](https://github.com/ethereum-optimism/specs/blob/main/specs/glossary.md#safe-l2-head) can stall up to that duration.

* This will negatively impact apps on your chain that rely on the safe head for operation. While many apps can likely operate simply by following the unsafe head, often Centralized Exchanges or third party bridges wait until transactions are marked safe before processing deposits and withdrawal.
* Thus a larger gap between posting batches can result in significant delays in the operation of certain types of high-security applications.
</Callout>

### Configure your batcher to use multiple blobs

The `op-batcher` has the capabilities to send multiple blobs per single blob transaction. This is accomplished by the use of multi-frame channels, see the [specs](https://specs.optimism.io/protocol/derivation.html#frame-format) for more technical details on channels and frames.

A minimal batcher configuration (with env vars) to enable 6-blob batcher transactions is:

```
- OP_BATCHER_BATCH_TYPE=1 # span batches, optional
- OP_BATCHER_DATA_AVAILABILITY_TYPE=blobs
- OP_BATCHER_TARGET_NUM_FRAMES=6 # 6 blobs per tx
- OP_BATCHER_TXMGR_MIN_BASEFEE=2.0 # 2 gwei, might need to tweak, depending on gas market
- OP_BATCHER_TXMGR_MIN_TIP_CAP=2.0 # 2 gwei, might need to tweak, depending on gas market
- OP_BATCHER_RESUBMISSION_TIMEOUT=240s # wait 4 min before bumping fees
```
* **Output Frequency**:
* Used to post output roots to L1 for verification.
* The recommended maximum is 24 hours (43,200 blocks at 2s each), though many chains choose smaller intervals.
* Will eventually be replaced or significantly changed by the introduction of fault proofs.

This enables blob transactions and sets the target number of frames to 6, which translates to 6 blobs per transaction.
The minimum tip cap and base fee are also lifted to 2 gwei because it is uncertain how easy it will be to get 6-blob transactions included and slightly higher priority fees should help.
The resubmission timeout is increased to a few minutes to give more time for inclusion before bumping the fees because current transaction pool implementations require a doubling of fees for blob transaction replacements.

Multi-blob transactions are particularly useful for medium to high-throughput chains, where enough transaction volume exists to fill up 6 blobs in a reasonable amount of time.
You can use [this calculator](https://docs.google.com/spreadsheets/d/12VIiXHaVECG2RUunDSVJpn67IQp9NHFJqUsma2PndpE/edit) for your chain to determine what number of blobs are right for you, and what gas scalar configuration to use. Please also refer to guide on [Using Blobs](/builders/chain-operators/management/blobs) for chain operators.
Include these high-level "policy" requirements when you set up or modify your `op-batcher` configuration. See the [Batcher Configuration](#global-options) reference, which explains each CLI flag and environment variable in depth.