From d1f0102a88e9c0543e81a26436b0f8cd27d52eee Mon Sep 17 00:00:00 2001 From: geoknee Date: Wed, 26 Nov 2025 09:42:10 +0000 Subject: [PATCH 1/6] Update batcher throttling docs and defaults --- .../guides/configuration/batcher.mdx | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/chain-operators/guides/configuration/batcher.mdx b/chain-operators/guides/configuration/batcher.mdx index 20cd3780f..f18f1ab90 100644 --- a/chain-operators/guides/configuration/batcher.mdx +++ b/chain-operators/guides/configuration/batcher.mdx @@ -81,8 +81,8 @@ This feature is a batcher-driven sequencer-throttling control loop. This is to a There are two throttling knobs: -1. Transaction L1 data throttling, which skips individual transactions whose estimated compressed L1 DA usage goes over a certain threshold, and -2. block L1 data throttling, which caps a block's estimated total L1 DA usage and leads to not including transactions during block building that would move the block's L1 DA usage past a certain threshold. +1. Transaction throttling, which skips individual transactions whose estimated compressed L1 DA usage goes over a certain threshold, and +2. Block throttling, which caps a block's estimated total L1 DA usage and leads to not including transactions during block building that would move the block's L1 DA usage past a certain threshold. **Feature requirements** @@ -95,13 +95,14 @@ There are two throttling knobs: Note that this feature requires the batcher to correctly follow the sequencer at all times, or it would set throttling parameters on a non-sequencer EL client. That means, active sequencer follow mode has to be enabled correctly by listing all the possible sequencers in the L2 rollup and EL endpoint flags. -The batcher can be configured with the following new flags and default parameters: +The batcher is configured for throttling by default with the parameters described below (and corresponding flags which allow the defaults to be overriden): -* Backlog of pending block bytes beyond which the batcher will enable throttling on the sequencer via `--throttle-threshold` (env var `OP_BATCHER_THROTTLE_THRESHOLD`): 1\_000\_000 (batcher backlog of 1MB of data to batch). Disable throttling by setting this to `0`. -* Individual tx size throttling via `--throttle-tx-size` (env var `OP_BATCHER_THROTTLE_TX_SIZE`): 300 (estimated compressed bytes) -* Block size throttling via `--throttle-block-size` (env var `OP_BATCHER_THROTTLE_BLOCK_SIZE`): 21\_000 (estimated total compressed bytes, at least 70 transactions per block of up to 300 compressed bytes each) -* Block size throttling that's always active via `--throttle-always-block-size` (env var `OP_BATCHER_THROTTLE_ALWAYS_BLOCK_SIZE`): 130\_000 - * This block size limit is enforced on the sequencer at all times, even if there isn't any backlog in the batcher. Normal network usage shouldn't be impacted by this. This is to prevent a too fast build up of data to batch. +* Backlog of pending block bytes beyond which the batcher will enable throttling on the sequencer via `--throttle.unsafe-da-bytes-lower/upper-threshold` (env var `OP_BATCHER_THROTTLE_UNSAFE_DA_BYTES_LOWER/UPPER_THRESHOLD`): 3\_200\_000 and 12\_800\_000 (batcher backlog of 3.2MB to 12.8MB of data to batch). Disable throttling by setting the lower threshold to `0`. The upper threshold sets the level where the maximum throttling intensity is reached. +* Individual tx size throttling via `--throttle.tx-size-lower/upper-limit` (env var `OP_BATCHER_THROTTLE_TX_SIZE_LOWER/UPPER-LIMIT`): 150 and 20\_000. This is the limit on the estimated compressed size of a transaction when throttling is at minimum/maximum intensity respectively. +* Block size throttling via `--throttle.block-size-lower/upper-limit` (env var `OP_BATCHER_THROTTLE_BLOCK_SIZE_LOWER/UPPER-LIMIT`): 2\_000 and 130\_000. This is the limit on the estimated compressed size of a block when throttling is at minimum/maximum intensity respectively. +* Throttler controller type via `--throttle.controller-type` (env var `OP_BATCHER_THROTTLE_CONTROLLER_TYPE`): `quadratic` by default. This determines how transaction and block size limits are interoplated when throttling is at intermediate inensity. + +For full details, see the [readme](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/readme.md). If the batcher at startup has throttling enabled and the sequencer's `op-geth` instance to which it's talking doesn't have the `miner_setMaxDASize` RPC enabled, it will fail with an error message like: From fbb64fdcbcd550184148e4ceb57964db04d8c36d Mon Sep 17 00:00:00 2001 From: geoknee Date: Wed, 26 Nov 2025 09:52:48 +0000 Subject: [PATCH 2/6] fix flags reference --- .../guides/configuration/batcher.mdx | 164 +++++++++++++++--- 1 file changed, 139 insertions(+), 25 deletions(-) diff --git a/chain-operators/guides/configuration/batcher.mdx b/chain-operators/guides/configuration/batcher.mdx index f18f1ab90..ad511b358 100644 --- a/chain-operators/guides/configuration/batcher.mdx +++ b/chain-operators/guides/configuration/batcher.mdx @@ -321,47 +321,161 @@ admin\_startBatcher RPC. The default value is `false`. ### Throttling -#### throttle-threshold +The batcher supports throttling configuration to limit DA usage for transactions and blocks, and to control throttle intensity via several controller types (including an experimental PID controller). The following flags are available: -Threshold on `pending-blocks-bytes-current` beyond which the batcher instructs the\ -block builder to start throttling transactions with larger DA demands. **Zero disables throttling**. +#### throttle.additional-endpoints + Comma-separated list of endpoints to distribute throttling configuration to (in addition to the L2 endpoints specified with `--l2-eth-rpc`). - - `--throttle-threshold=` - `--throttle-threshold=1500000` - `OP_BATCHER_THROTTLE_THRESHOLD=1500000` + + + Type: string slice + Default: none + CLI: `--throttle.additional-endpoints=,,...` + + + + CLI: `--throttle.additional-endpoints=http://builder1:8545,http://builder2:8545` + + + + `THROTTLE_ADDITIONAL_ENDPOINTS=http://builder1:8545,http://builder2:8545` + -#### throttle-tx-size +#### throttle.tx-size-lower-limit + The DA size limit for individual transactions when the throttle intensity is at its maximum. `0` disables limits; use `1` as the smallest effective limit. -The DA size of transactions at which throttling begins **when we are over the throttle threshold**. + + + Type: uint64 + Default: `150` + CLI: `--throttle.tx-size-lower-limit=` + - - `--throttle-tx-size=` - `--throttle-tx-size=10000` - `OP_BATCHER_THROTTLE_TX_SIZE=10000` + + CLI: `--throttle.tx-size-lower-limit=150` + + + + `THROTTLE_TX_SIZE_LOWER_LIMIT=150` + -#### throttle-block-size +#### throttle.tx-size-upper-limit + The DA size limit for individual transactions as throttle intensity approaches `0` (minimal throttling). Not applied when throttling is inactive. -The total DA limit to start imposing on block building **when we are over the throttle threshold**. + + + Type: uint64 + Default: `20000` + CLI: `--throttle.tx-size-upper-limit=` + - - `--throttle-block-size=` - `--throttle-block-size=50000` - `OP_BATCHER_THROTTLE_BLOCK_SIZE=50000` + + CLI: `--throttle.tx-size-upper-limit=20000` + + + + `THROTTLE_TX_SIZE_UPPER_LIMIT=20000` + -#### throttle-always-block-size +#### throttle.block-size-lower-limit + The DA size limit for blocks when throttle intensity is at maximum (applies for linear and quadratic controllers). `0` disables limits; use `1` as the smallest effective limit. -The total DA limit to start imposing on block building **at all times**. + + + Type: uint64 + Default: `2000` + CLI: `--throttle.block-size-lower-limit=` + - - `--throttle-always-block-size=` - `--throttle-always-block-size=250000` - `OP_BATCHER_THROTTLE_ALWAYS_BLOCK_SIZE=250000` + + CLI: `--throttle.block-size-lower-limit=2000` + + + + `THROTTLE_BLOCK_SIZE_LOWER_LIMIT=2000` + + + +#### throttle.block-size-upper-limit + The DA size limit for blocks when throttling is inactive (throttle intensity = 0). + + + + Type: uint64 + Default: `130000` + CLI: `--throttle.block-size-upper-limit=` + + + + CLI: `--throttle.block-size-upper-limit=130000` + + + + `THROTTLE_BLOCK_SIZE_UPPER_LIMIT=130000` + + + +#### throttle.controller-type + Type of throttle controller to use. Valid values: `step`, `linear`, `quadratic` (default), `pid` (EXPERIMENTAL - use with caution). + + + + Type: string + Default: `quadratic` + CLI: `--throttle.controller-type=` + + + + CLI: `--throttle.controller-type=quadratic` + + + + `THROTTLE_CONTROLLER_TYPE=quadratic` + +#### throttle.unsafe-da-bytes-lower-threshold + Threshold on `unsafe_da_bytes` beyond which the batcher will start to throttle the block builder. `0` disables throttling. + + + + Type: uint64 + Default: `3200000` + CLI: `--throttle.unsafe-da-bytes-lower-threshold=` + + + + CLI: `--throttle.unsafe-da-bytes-lower-threshold=3200000` + + + + `THROTTLE_UNSAFE_DA_BYTES_LOWER_THRESHOLD=3200000` + + + +#### throttle.unsafe-da-bytes-upper-threshold + Threshold on `unsafe_da_bytes` at which throttling reaches maximum intensity (applies for linear and quadratic controllers). + + + + Type: uint64 + Default: `12800000` + CLI: `--throttle.unsafe-da-bytes-upper-threshold=` + + + + CLI: `--throttle.unsafe-da-bytes-upper-threshold=12800000` + + + + `THROTTLE_UNSAFE_DA_BYTES_UPPER_THRESHOLD=12800000` + + + + ### Transaction manager #### num-confirmations From 5dd10c978d9ee711929b47db07ab91427b45bf07 Mon Sep 17 00:00:00 2001 From: geoknee Date: Wed, 26 Nov 2025 09:59:03 +0000 Subject: [PATCH 3/6] spellcheck --- chain-operators/guides/configuration/batcher.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chain-operators/guides/configuration/batcher.mdx b/chain-operators/guides/configuration/batcher.mdx index ad511b358..1609788aa 100644 --- a/chain-operators/guides/configuration/batcher.mdx +++ b/chain-operators/guides/configuration/batcher.mdx @@ -95,12 +95,12 @@ There are two throttling knobs: Note that this feature requires the batcher to correctly follow the sequencer at all times, or it would set throttling parameters on a non-sequencer EL client. That means, active sequencer follow mode has to be enabled correctly by listing all the possible sequencers in the L2 rollup and EL endpoint flags. -The batcher is configured for throttling by default with the parameters described below (and corresponding flags which allow the defaults to be overriden): +The batcher is configured for throttling by default with the parameters described below (and corresponding flags which allow the defaults to be overridden): * Backlog of pending block bytes beyond which the batcher will enable throttling on the sequencer via `--throttle.unsafe-da-bytes-lower/upper-threshold` (env var `OP_BATCHER_THROTTLE_UNSAFE_DA_BYTES_LOWER/UPPER_THRESHOLD`): 3\_200\_000 and 12\_800\_000 (batcher backlog of 3.2MB to 12.8MB of data to batch). Disable throttling by setting the lower threshold to `0`. The upper threshold sets the level where the maximum throttling intensity is reached. * Individual tx size throttling via `--throttle.tx-size-lower/upper-limit` (env var `OP_BATCHER_THROTTLE_TX_SIZE_LOWER/UPPER-LIMIT`): 150 and 20\_000. This is the limit on the estimated compressed size of a transaction when throttling is at minimum/maximum intensity respectively. * Block size throttling via `--throttle.block-size-lower/upper-limit` (env var `OP_BATCHER_THROTTLE_BLOCK_SIZE_LOWER/UPPER-LIMIT`): 2\_000 and 130\_000. This is the limit on the estimated compressed size of a block when throttling is at minimum/maximum intensity respectively. -* Throttler controller type via `--throttle.controller-type` (env var `OP_BATCHER_THROTTLE_CONTROLLER_TYPE`): `quadratic` by default. This determines how transaction and block size limits are interoplated when throttling is at intermediate inensity. +* Throttler controller type via `--throttle.controller-type` (env var `OP_BATCHER_THROTTLE_CONTROLLER_TYPE`): `quadratic` by default. This determines how transaction and block size limits are interpolated when throttling is at intermediate intensity. For full details, see the [readme](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/readme.md). From 2b128c61105a88a4215367827c806b19a77ee45e Mon Sep 17 00:00:00 2001 From: geoknee Date: Wed, 26 Nov 2025 10:30:15 +0000 Subject: [PATCH 4/6] Replace Tabs.Tab with Tab in batcher guide --- .../guides/configuration/batcher.mdx | 362 +++++++++--------- 1 file changed, 181 insertions(+), 181 deletions(-) diff --git a/chain-operators/guides/configuration/batcher.mdx b/chain-operators/guides/configuration/batcher.mdx index 1609788aa..683ece97e 100644 --- a/chain-operators/guides/configuration/batcher.mdx +++ b/chain-operators/guides/configuration/batcher.mdx @@ -159,9 +159,9 @@ is `0` for `SingularBatch`. See the [span batch feature page](/op-stack/features/span-batches) to learn more. - `--batch-type=` - `--batch-type=singular` - `OP_BATCHER_BATCH_TYPE=` + `--batch-type=` + `--batch-type=singular` + `OP_BATCHER_BATCH_TYPE=` #### max-blocks-per-span-batch @@ -171,10 +171,10 @@ recent batch tx on L1. This can speed up waiting for node sync. It should be set to the verifier confirmation depth of the sequencer (e.g. 4). The default value is `0`. - - `--check-recent-txs-depth=` - `--check-recent-txs-depth=0` - `OP_BATCHER_CHECK_RECENT_TXS_DEPTH=0` + + `--check-recent-txs-depth=` + `--check-recent-txs-depth=0` + `OP_BATCHER_CHECK_RECENT_TXS_DEPTH=0` #### compression-algo @@ -183,9 +183,9 @@ The compression algorithm to use. Valid options: zlib, brotli, brotli-9, brotli-10, brotli-11. The default value is `zlib`. - `--compression-algo=` - `--compression-algo=zlib` - `OP_BATCHER_COMPRESSION_ALGO=zlib` + `--compression-algo=` + `--compression-algo=zlib` + `OP_BATCHER_COMPRESSION_ALGO=zlib` #### compressor @@ -194,9 +194,9 @@ The type of compressor. Valid options: none, ratio, shadow. The default value is `shadow`. - `--compressor=` - `--compressor=shadow` - `OP_BATCHER_COMPRESSOR=shadow` + `--compressor=` + `--compressor=shadow` + `OP_BATCHER_COMPRESSOR=shadow` #### approx-compr-ratio @@ -204,9 +204,9 @@ is `shadow`. Only relevant for ratio compressor. The approximate compression ratio (`<=1.0`). The default value is `0.6`. - `--approx-compr-ratio=` - `--approx-compr-ratio=0.6` - `OP_BATCHER_APPROX_COMPR_RATIO=0.6` + `--approx-compr-ratio=` + `--approx-compr-ratio=0.6` + `OP_BATCHER_APPROX_COMPR_RATIO=0.6` #### poll-interval @@ -214,9 +214,9 @@ Only relevant for ratio compressor. The approximate compression ratio (`<=1.0`). How frequently to poll L2 for new blocks. The default value is `6s`. - `--poll-interval=` - `--poll-interval=6s` - `OP_BATCHER_POLL_INTERVAL=6s` + `--poll-interval=` + `--poll-interval=6s` + `OP_BATCHER_POLL_INTERVAL=6s` ### Batch submission @@ -231,9 +231,9 @@ The data availability type to use for submitting batches to the L1. Valid options: `calldata`, `blobs`, and `auto`. The default value is `calldata`. - `--data-availability-type=` - `--data-availability-type=calldata` - `OP_BATCHER_DATA_AVAILABILITY_TYPE=calldata` + `--data-availability-type=` + `--data-availability-type=calldata` + `OP_BATCHER_DATA_AVAILABILITY_TYPE=calldata` #### target-num-frames @@ -242,9 +242,9 @@ The target number of frames to create per channel. Controls number of blobs per blob tx, if using Blob DA. The default value is `1`. - `--target-num-frames=` - `--target-num-frames=1` - `OP_BATCHER_TARGET_NUM_FRAMES=1` + `--target-num-frames=` + `--target-num-frames=1` + `OP_BATCHER_TARGET_NUM_FRAMES=1` #### max-channel-duration @@ -253,9 +253,9 @@ The maximum duration of L1-blocks to keep a channel open. 0 to disable. The default value is `0`. - `--max-channel-duration=` - `--max-channel-duration=0` - `OP_BATCHER_MAX_CHANNEL_DURATION=0` + `--max-channel-duration=` + `--max-channel-duration=0` + `OP_BATCHER_MAX_CHANNEL_DURATION=0` #### sub-safety-margin @@ -265,9 +265,9 @@ channel's timeout and sequencing window, to guarantee safe inclusion of a channel on L1. The default value is `10`. - `--sub-safety-margin=` - `--sub-safety-margin=10` - `OP_BATCHER_SUB_SAFETY_MARGIN=10s` + `--sub-safety-margin=` + `--sub-safety-margin=10` + `OP_BATCHER_SUB_SAFETY_MARGIN=10s` #### max-l1-tx-size-bytes @@ -276,9 +276,9 @@ The maximum size of a batch tx submitted to L1. Ignored for blobs, where max blob size will be used. The default value is `120000`. - `--max-l1-tx-size-bytes=` - `--max-l1-tx-size-bytes=120000` - `OP_BATCHER_MAX_L1_TX_SIZE_BYTES=120000` + `--max-l1-tx-size-bytes=` + `--max-l1-tx-size-bytes=120000` + `OP_BATCHER_MAX_L1_TX_SIZE_BYTES=120000` ### Batcher startup @@ -290,9 +290,9 @@ on L1 to finalize (via more block confirmations). This should help avoid duplicate batcher txs. The default value is `false`. - `--wait-node-sync=` - `--wait-node-sync=false` - `OP_BATCHER_WAIT_NODE_SYNC=false` + `--wait-node-sync=` + `--wait-node-sync=false` + `OP_BATCHER_WAIT_NODE_SYNC=false` #### check-recent-txs-depth @@ -303,9 +303,9 @@ set to the verifier confirmation depth of the sequencer (e.g. 4). The default value is `0`. - `--check-recent-txs-depth=` - `--check-recent-txs-depth=0` - `OP_BATCHER_CHECK_RECENT_TXS_DEPTH=0` + `--check-recent-txs-depth=` + `--check-recent-txs-depth=0` + `OP_BATCHER_CHECK_RECENT_TXS_DEPTH=0` #### stopped @@ -314,9 +314,9 @@ Initialize the batcher in a stopped state. The batcher can be started using the admin\_startBatcher RPC. The default value is `false`. - `--stopped=` - `--stopped=false` - `OP_BATCHER_STOPPED=false` + `--stopped=` + `--stopped=false` + `OP_BATCHER_STOPPED=false` ### Throttling @@ -484,9 +484,9 @@ Number of confirmations which we will wait after sending a transaction. The default value is `10`. - `--num-confirmations=` - `--num-confirmations=10` - `OP_BATCHER_NUM_CONFIRMATIONS=10` + `--num-confirmations=` + `--num-confirmations=10` + `OP_BATCHER_NUM_CONFIRMATIONS=10` #### max-pending-tx @@ -495,9 +495,9 @@ The maximum number of pending transactions. 0 for no limit. The default value is `1`. - `--max-pending-tx=` - `--max-pending-tx=1` - `OP_BATCHER_MAX_PENDING_TX=1` + `--max-pending-tx=` + `--max-pending-tx=1` + `OP_BATCHER_MAX_PENDING_TX=1` #### resubmission-timeout @@ -506,9 +506,9 @@ Duration we will wait before resubmitting a transaction to L1. The default value is `48s`. - `--resubmission-timeout=` - `--resubmission-timeout=48s` - `OP_BATCHER_RESUBMISSION_TIMEOUT=48s` + `--resubmission-timeout=` + `--resubmission-timeout=48s` + `OP_BATCHER_RESUBMISSION_TIMEOUT=48s` #### safe-abort-nonce-too-low-count @@ -517,9 +517,9 @@ Number of ErrNonceTooLow observations required to give up on a tx at a particular nonce without receiving confirmation. The default value is `3`. - `--safe-abort-nonce-too-low-count=` - `--safe-abort-nonce-too-low-count=3` - `OP_BATCHER_SAFE_ABORT_NONCE_TOO_LOW_COUNT=3` + `--safe-abort-nonce-too-low-count=` + `--safe-abort-nonce-too-low-count=3` + `OP_BATCHER_SAFE_ABORT_NONCE_TOO_LOW_COUNT=3` #### txmgr.min-basefee @@ -528,9 +528,9 @@ Enforces a minimum base fee (in GWei) to assume when determining tx fees. 1 GWei by default. The default value is `1`. - `--txmgr.min-basefee=` - `--txmgr.min-basefee=1` - `OP_BATCHER_TXMGR_MIN_BASEFEE=1` + `--txmgr.min-basefee=` + `--txmgr.min-basefee=1` + `OP_BATCHER_TXMGR_MIN_BASEFEE=1` #### txmgr.min-tip-cap @@ -539,9 +539,9 @@ Enforces a minimum tip cap (in GWei) to use when determining tx fees. 1 GWei by default. The default value is `1`. - `--txmgr.min-tip-cap=` - `--txmgr.min-tip-cap=1` - `OP_BATCHER_TXMGR_MIN_TIP_CAP=1` + `--txmgr.min-tip-cap=` + `--txmgr.min-tip-cap=1` + `OP_BATCHER_TXMGR_MIN_TIP_CAP=1` #### fee-limit-multiplier @@ -550,9 +550,9 @@ The multiplier applied to fee suggestions to put a hard limit on fee increases. The default value is `5`. - `--fee-limit-multiplier=` - `--fee-limit-multiplier=5` - `OP_BATCHER_TXMGR_FEE_LIMIT_MULTIPLIER=5` + `--fee-limit-multiplier=` + `--fee-limit-multiplier=5` + `OP_BATCHER_TXMGR_FEE_LIMIT_MULTIPLIER=5` #### txmgr.fee-limit-threshold @@ -561,9 +561,9 @@ The minimum threshold (in GWei) at which fee bumping starts to be capped. Allows arbitrary fee bumps below this threshold. The default value is `100`. - `--txmgr.fee-limit-threshold=` - `--txmgr.fee-limit-threshold=100` - `OP_BATCHER_TXMGR_FEE_LIMIT_THRESHOLD=100` + `--txmgr.fee-limit-threshold=` + `--txmgr.fee-limit-threshold=100` + `OP_BATCHER_TXMGR_FEE_LIMIT_THRESHOLD=100` #### txmgr.receipt-query-interval @@ -571,9 +571,9 @@ Allows arbitrary fee bumps below this threshold. The default value is `100`. Frequency to poll for receipts. The default value is `12s`. - `--txmgr.receipt-query-interval=` - `--txmgr.receipt-query-interval=12s` - `OP_BATCHER_TXMGR_RECEIPT_QUERY_INTERVAL=12s` + `--txmgr.receipt-query-interval=` + `--txmgr.receipt-query-interval=12s` + `OP_BATCHER_TXMGR_RECEIPT_QUERY_INTERVAL=12s` #### txmgr.not-in-mempool-timeout @@ -582,9 +582,9 @@ Timeout for aborting a tx send if the tx does not make it to the mempool. The default value is `2m0s`. - `--txmgr.not-in-mempool-timeout=` - `--txmgr.not-in-mempool-timeout=2m0s` - `OP_BATCHER_TXMGR_TX_NOT_IN_MEMPOOL_TIMEOUT=2m0s` + `--txmgr.not-in-mempool-timeout=` + `--txmgr.not-in-mempool-timeout=2m0s` + `OP_BATCHER_TXMGR_TX_NOT_IN_MEMPOOL_TIMEOUT=2m0s` #### txmgr.send-timeout @@ -593,9 +593,9 @@ Timeout for sending transactions. If 0 it is disabled. The default value is `0s`. - `--txmgr.send-timeout=` - `--txmgr.send-timeout=0s` - `OP_BATCHER_TXMGR_TX_SEND_TIMEOUT=0s` + `--txmgr.send-timeout=` + `--txmgr.send-timeout=0s` + `OP_BATCHER_TXMGR_TX_SEND_TIMEOUT=0s` ### Authentication and wallet @@ -605,9 +605,9 @@ Timeout for sending transactions. If 0 it is disabled. The default value is The private key to use with the service. Must not be used with mnemonic. - `--private-key=` - `--private-key=` - `OP_BATCHER_PRIVATE_KEY=` + `--private-key=` + `--private-key=` + `OP_BATCHER_PRIVATE_KEY=` #### mnemonic @@ -615,9 +615,9 @@ The private key to use with the service. Must not be used with mnemonic. The mnemonic used to derive the wallets for either the service. - `--mnemonic=` - `--mnemonic=` - `OP_BATCHER_MNEMONIC=` + `--mnemonic=` + `--mnemonic=` + `OP_BATCHER_MNEMONIC=` #### hd-path @@ -626,9 +626,9 @@ The HD path used to derive the sequencer wallet from the mnemonic. The mnemonic flag must also be set. - `--hd-path=` - `--hd-path=` - `OP_BATCHER_HD_PATH=` + `--hd-path=` + `--hd-path=` + `OP_BATCHER_HD_PATH=` @@ -637,9 +637,9 @@ flag must also be set. Address the signer is signing transactions for. - `--signer.address=` - `--signer.address=` - `OP_BATCHER_SIGNER_ADDRESS=` + `--signer.address=` + `--signer.address=` + `OP_BATCHER_SIGNER_ADDRESS=` #### signer.endpoint @@ -647,9 +647,9 @@ Address the signer is signing transactions for. Signer endpoint the client will connect to. - `--signer.endpoint=` - `--signer.endpoint=` - `OP_BATCHER_SIGNER_ENDPOINT=` + `--signer.endpoint=` + `--signer.endpoint=` + `OP_BATCHER_SIGNER_ENDPOINT=` #### signer.header @@ -660,9 +660,9 @@ When using env vars, split multiple headers with commas.\ When using flags, provide one key-value pair per flag. - `--signer.header=` - `--signer.header="Authorization=Bearer 123abc"` - `OP_BATCHER_SIGNER_HEADER=Authorization=Bearer 123abc` + `--signer.header=` + `--signer.header="Authorization=Bearer 123abc"` + `OP_BATCHER_SIGNER_HEADER=Authorization=Bearer 123abc` #### signer.tls.ca @@ -670,9 +670,9 @@ When using flags, provide one key-value pair per flag. tls ca cert path. The default value is `tls/ca.crt`. - `--signer.tls.ca=` - `--signer.tls.ca=tls/ca.crt` - `OP_BATCHER_SIGNER_TLS_CA=tls/ca.crt` + `--signer.tls.ca=` + `--signer.tls.ca=tls/ca.crt` + `OP_BATCHER_SIGNER_TLS_CA=tls/ca.crt` #### signer.tls.cert @@ -680,9 +680,9 @@ tls ca cert path. The default value is `tls/ca.crt`. tls cert path. The default value is `tls/tls.crt`. - `--signer.tls.cert=` - `--signer.tls.cert=tls/tls.crt` - `OP_BATCHER_SIGNER_TLS_CERT=` + `--signer.tls.cert=` + `--signer.tls.cert=tls/tls.crt` + `OP_BATCHER_SIGNER_TLS_CERT=` #### signer.tls.key @@ -690,9 +690,9 @@ tls cert path. The default value is `tls/tls.crt`. tls key. The default value is `tls/tls.key`. - `--signer.tls.key=` - `--signer.tls.key=tls/tls.key` - `OP_BATCHER_SIGNER_TLS_KEY=` + `--signer.tls.key=` + `--signer.tls.key=tls/tls.key` + `OP_BATCHER_SIGNER_TLS_KEY=` ### Network connections @@ -702,9 +702,9 @@ tls key. The default value is `tls/tls.key`. HTTP provider URL for L1. - `--l1-eth-rpc=` - `--l1-eth-rpc` - `OP_BATCHER_L1_ETH_RPC=` + `--l1-eth-rpc=` + `--l1-eth-rpc` + `OP_BATCHER_L1_ETH_RPC=` #### l2-eth-rpc @@ -714,9 +714,9 @@ active L2 endpoint provider. Such a list needs to match the number of rollup-rpcs provided. - `--l2-eth-rpc=` - `--l2-eth-rpc=` - `OP_BATCHER_L2_ETH_RPC=` + `--l2-eth-rpc=` + `--l2-eth-rpc=` + `OP_BATCHER_L2_ETH_RPC=` #### rollup-rpc @@ -726,9 +726,9 @@ endpoint provider. Such a list needs to match the number of l2-eth-rpcs provided. - `--rollup-rpc=` - `--rollup-rpc=` - `OP_BATCHER_ROLLUP_RPC=` + `--rollup-rpc=` + `--rollup-rpc=` + `OP_BATCHER_ROLLUP_RPC=` #### rpc.addr @@ -736,9 +736,9 @@ provided. rpc listening address. The default value is `0.0.0.0`. - `--rpc.addr=` - `--rpc.addr=0.0.0.0` - `OP_BATCHER_RPC_ADDR=0.0.0.0` + `--rpc.addr=` + `--rpc.addr=0.0.0.0` + `OP_BATCHER_RPC_ADDR=0.0.0.0` #### rpc.enable-admin @@ -746,9 +746,9 @@ rpc listening address. The default value is `0.0.0.0`. Enable the admin API. The default value is `false`. - `--rpc.enable-admin=` - `--rpc.enable-admin=false` - `OP_BATCHER_RPC_ENABLE_ADMIN=false` + `--rpc.enable-admin=` + `--rpc.enable-admin=false` + `OP_BATCHER_RPC_ENABLE_ADMIN=false` #### rpc.port @@ -756,9 +756,9 @@ Enable the admin API. The default value is `false`. rpc listening port. The default value is `8545`. - `--rpc.port=` - `--rpc.port=8545` - `OP_BATCHER_RPC_PORT=8545` + `--rpc.port=` + `--rpc.port=8545` + `OP_BATCHER_RPC_PORT=8545` #### network-timeout @@ -766,9 +766,9 @@ rpc listening port. The default value is `8545`. Timeout for all network operations. The default value is `10s`. - `--network-timeout=` - `--network-timeout=10s` - `OP_BATCHER_NETWORK_TIMEOUT=10s` + `--network-timeout=` + `--network-timeout=10s` + `OP_BATCHER_NETWORK_TIMEOUT=10s` ### Alt-DA mode (Beta feature) @@ -781,9 +781,9 @@ undergoing testing, and may have bugs or other issues. The default value is `false`. - `--altda.enabled=` - `--altda.enabled=false` - `OP_BATCHER_ALTDA_ENABLED=false` + `--altda.enabled=` + `--altda.enabled=false` + `OP_BATCHER_ALTDA_ENABLED=false` #### altda.da-server @@ -791,9 +791,9 @@ The default value is `false`. HTTP address of a DA Server. - `--altda.da-server=` - `--altda.da-server=http://da.example.com:1234` - `$OP_BATCHER_ALTDA_DA_SERVER=http://da.example.com:1234` + `--altda.da-server=` + `--altda.da-server=http://da.example.com:1234` + `$OP_BATCHER_ALTDA_DA_SERVER=http://da.example.com:1234` #### altda.da-service @@ -802,9 +802,9 @@ Use DA service type where commitments are generated by Alt-DA server. The defaul value is `false`. - `--altda.da-service=` - `--altda.da-service=true` - `$OP_BATCHER_ALTDA_DA_SERVER=true` + `--altda.da-service=` + `--altda.da-service=true` + `$OP_BATCHER_ALTDA_DA_SERVER=true` #### altda.get-timeout @@ -812,9 +812,9 @@ value is `false`. Timeout for get requests. **0 means no timeout**. - `--altda.get-timeout=` - `--altda.get-timeout=5s` - `OP_BATCHER_ALTDA_GET_TIMEOUT=5s` + `--altda.get-timeout=` + `--altda.get-timeout=5s` + `OP_BATCHER_ALTDA_GET_TIMEOUT=5s` #### altda.put-timeout @@ -822,9 +822,9 @@ Timeout for get requests. **0 means no timeout**. Timeout for put requests. **0 means no timeout**. - `--altda.put-timeout=` - `--altda.put-timeout=10s` - `OP_BATCHER_ALTDA_PUT_TIMEOUT=10s` + `--altda.put-timeout=` + `--altda.put-timeout=10s` + `OP_BATCHER_ALTDA_PUT_TIMEOUT=10s` #### altda.max-concurrent-da-requests @@ -832,9 +832,9 @@ Timeout for put requests. **0 means no timeout**. Maximum number of concurrent requests to the DA server. - `--altda.max-concurrent-da-requests=` - `--altda.max-concurrent-da-requests=4` - `OP_BATCHER_ALTDA_MAX_CONCURRENT_DA_REQUESTS=4` + `--altda.max-concurrent-da-requests=` + `--altda.max-concurrent-da-requests=4` + `OP_BATCHER_ALTDA_MAX_CONCURRENT_DA_REQUESTS=4` #### altda.verify-on-read @@ -842,9 +842,9 @@ Maximum number of concurrent requests to the DA server. Verify input data matches the commitments from the DA storage service. - `--altda.verify-on-read=` - `--altda.verify-on-read=true` - `OP_BATCHER_ALTDA_VERIFY_ON_READ=true` + `--altda.verify-on-read=` + `--altda.verify-on-read=true` + `OP_BATCHER_ALTDA_VERIFY_ON_READ=true` ### Logging and monitoring @@ -854,9 +854,9 @@ Verify input data matches the commitments from the DA storage service. The lowest log level that will be output. The default value is `INFO`. - `--log.level=` - `--log.level=INFO` - `OP_BATCHER_LOG_LEVEL=INFO` + `--log.level=` + `--log.level=INFO` + `OP_BATCHER_LOG_LEVEL=INFO` #### log.format @@ -865,9 +865,9 @@ Format the log output. Supported formats: 'text', 'terminal', 'logfmt', 'json', 'json-pretty'. The default value is `text`. - `--log.format=` - `--log.format=text` - `OP_BATCHER_LOG_FORMAT=text` + `--log.format=` + `--log.format=text` + `OP_BATCHER_LOG_FORMAT=text` #### log.color @@ -875,9 +875,9 @@ Format the log output. Supported formats: 'text', 'terminal', 'logfmt', 'json', Color the log output if in terminal mode. The default value is `false`. - `--log.color=` - `--log.color=false` - `OP_BATCHER_LOG_COLOR=false` + `--log.color=` + `--log.color=false` + `OP_BATCHER_LOG_COLOR=false` #### log.pid @@ -885,9 +885,9 @@ Color the log output if in terminal mode. The default value is `false`. Show PID in the log. - `--log.pid=` - `--log.pid=true` - `OP_BATCHER_LOG_PID=true` + `--log.pid=` + `--log.pid=true` + `OP_BATCHER_LOG_PID=true` #### metrics.enabled @@ -895,8 +895,8 @@ Show PID in the log. Enable the metrics server. The default value is `false`. - `--version=` - `--version=false` + `--version=` + `--version=false` @@ -908,9 +908,9 @@ The duration between checks to determine the active sequencer endpoint. The default value is `2m0s`. - `--active-sequencer-check-duration=` - `--active-sequencer-check-duration=2m0s` - `OP_BATCHER_ACTIVE_SEQUENCER_CHECK_DURATION=2m0s` + `--active-sequencer-check-duration=` + `--active-sequencer-check-duration=2m0s` + `OP_BATCHER_ACTIVE_SEQUENCER_CHECK_DURATION=2m0s` #### pprof.addr @@ -918,9 +918,9 @@ default value is `2m0s`. pprof listening address. The default value is `0.0.0.0`. - `--pprof.addr=` - `--pprof.addr=0.0.0.0` - `OP_BATCHER_PPROF_ADDR=0.0.0.0` + `--pprof.addr=` + `--pprof.addr=0.0.0.0` + `OP_BATCHER_PPROF_ADDR=0.0.0.0` #### pprof.enabled @@ -928,9 +928,9 @@ pprof listening address. The default value is `0.0.0.0`. Enable the pprof server. The default value is `false`. - `--pprof.enabled=` - `--pprof.enabled=false` - `OP_BATCHER_PPROF_ENABLED=false` + `--pprof.enabled=` + `--pprof.enabled=false` + `OP_BATCHER_PPROF_ENABLED=false` #### pprof.path @@ -938,9 +938,9 @@ Enable the pprof server. The default value is `false`. pprof file path. If it is a directory, the path is `{dir}/{profileType}.prof`. - `--pprof.path=` - `--pprof.path=` - `OP_BATCHER_PPROF_PATH=` + `--pprof.path=` + `--pprof.path=` + `OP_BATCHER_PPROF_PATH=` #### pprof.port @@ -948,9 +948,9 @@ pprof file path. If it is a directory, the path is `{dir}/{profileType}.prof`. pprof listening port. The default value is `6060`. - `--pprof.port=` - `--pprof.port=6060` - `OP_BATCHER_PPROF_PORT=6060` + `--pprof.port=` + `--pprof.port=6060` + `OP_BATCHER_PPROF_PORT=6060` #### pprof.type @@ -959,9 +959,9 @@ pprof profile type. One of cpu, heap, goroutine, threadcreate, block, mutex, allocs. - `--pprof.type=` - `--pprof.type` - `OP_BATCHER_PPROF_TYPE=` + `--pprof.type=` + `--pprof.type` + `OP_BATCHER_PPROF_TYPE=` #### help @@ -969,8 +969,8 @@ allocs. Show help. The default value is false. - `--help=` - `--help=false` + `--help=` + `--help=false` #### version @@ -978,6 +978,6 @@ Show help. The default value is false. Print the version. The default value is false. - `--version=` - `--version=false` + `--version=` + `--version=false` From 989859fd4e0590b4a8bc343ec932e19343685dea Mon Sep 17 00:00:00 2001 From: geoknee Date: Wed, 26 Nov 2025 10:36:42 +0000 Subject: [PATCH 5/6] Refactor batcher docs Tabs and throttle config --- .../guides/configuration/batcher.mdx | 668 +++++++++--------- 1 file changed, 323 insertions(+), 345 deletions(-) diff --git a/chain-operators/guides/configuration/batcher.mdx b/chain-operators/guides/configuration/batcher.mdx index 683ece97e..d04a403a1 100644 --- a/chain-operators/guides/configuration/batcher.mdx +++ b/chain-operators/guides/configuration/batcher.mdx @@ -158,10 +158,10 @@ The batch type. 0 for `SingularBatch` and 1 for `SpanBatch`. The default value is `0` for `SingularBatch`. See the [span batch feature page](/op-stack/features/span-batches) to learn more. - - `--batch-type=` - `--batch-type=singular` - `OP_BATCHER_BATCH_TYPE=` + + `--batch-type=` + `--batch-type=singular` + `OP_BATCHER_BATCH_TYPE=` #### max-blocks-per-span-batch @@ -182,10 +182,10 @@ value is `0`. The compression algorithm to use. Valid options: zlib, brotli, brotli-9, brotli-10, brotli-11. The default value is `zlib`. - - `--compression-algo=` - `--compression-algo=zlib` - `OP_BATCHER_COMPRESSION_ALGO=zlib` + + `--compression-algo=` + `--compression-algo=zlib` + `OP_BATCHER_COMPRESSION_ALGO=zlib` #### compressor @@ -193,30 +193,30 @@ brotli-10, brotli-11. The default value is `zlib`. The type of compressor. Valid options: none, ratio, shadow. The default value is `shadow`. - - `--compressor=` - `--compressor=shadow` - `OP_BATCHER_COMPRESSOR=shadow` + + `--compressor=` + `--compressor=shadow` + `OP_BATCHER_COMPRESSOR=shadow` #### approx-compr-ratio Only relevant for ratio compressor. The approximate compression ratio (`<=1.0`). The default value is `0.6`. - - `--approx-compr-ratio=` - `--approx-compr-ratio=0.6` - `OP_BATCHER_APPROX_COMPR_RATIO=0.6` + + `--approx-compr-ratio=` + `--approx-compr-ratio=0.6` + `OP_BATCHER_APPROX_COMPR_RATIO=0.6` #### poll-interval How frequently to poll L2 for new blocks. The default value is `6s`. - - `--poll-interval=` - `--poll-interval=6s` - `OP_BATCHER_POLL_INTERVAL=6s` + + `--poll-interval=` + `--poll-interval=6s` + `OP_BATCHER_POLL_INTERVAL=6s` ### Batch submission @@ -230,10 +230,10 @@ How frequently to poll L2 for new blocks. The default value is `6s`. The data availability type to use for submitting batches to the L1. Valid options: `calldata`, `blobs`, and `auto`. The default value is `calldata`. - - `--data-availability-type=` - `--data-availability-type=calldata` - `OP_BATCHER_DATA_AVAILABILITY_TYPE=calldata` + + `--data-availability-type=` + `--data-availability-type=calldata` + `OP_BATCHER_DATA_AVAILABILITY_TYPE=calldata` #### target-num-frames @@ -241,10 +241,10 @@ options: `calldata`, `blobs`, and `auto`. The default value is `calldata`. The target number of frames to create per channel. Controls number of blobs per blob tx, if using Blob DA. The default value is `1`. - - `--target-num-frames=` - `--target-num-frames=1` - `OP_BATCHER_TARGET_NUM_FRAMES=1` + + `--target-num-frames=` + `--target-num-frames=1` + `OP_BATCHER_TARGET_NUM_FRAMES=1` #### max-channel-duration @@ -252,10 +252,10 @@ blob tx, if using Blob DA. The default value is `1`. The maximum duration of L1-blocks to keep a channel open. 0 to disable. The default value is `0`. - - `--max-channel-duration=` - `--max-channel-duration=0` - `OP_BATCHER_MAX_CHANNEL_DURATION=0` + + `--max-channel-duration=` + `--max-channel-duration=0` + `OP_BATCHER_MAX_CHANNEL_DURATION=0` #### sub-safety-margin @@ -264,10 +264,10 @@ The batcher tx submission safety margin (in #L1-blocks) to subtract from a channel's timeout and sequencing window, to guarantee safe inclusion of a channel on L1. The default value is `10`. - - `--sub-safety-margin=` - `--sub-safety-margin=10` - `OP_BATCHER_SUB_SAFETY_MARGIN=10s` + + `--sub-safety-margin=` + `--sub-safety-margin=10` + `OP_BATCHER_SUB_SAFETY_MARGIN=10s` #### max-l1-tx-size-bytes @@ -275,10 +275,10 @@ channel on L1. The default value is `10`. The maximum size of a batch tx submitted to L1. Ignored for blobs, where max blob size will be used. The default value is `120000`. - - `--max-l1-tx-size-bytes=` - `--max-l1-tx-size-bytes=120000` - `OP_BATCHER_MAX_L1_TX_SIZE_BYTES=120000` + + `--max-l1-tx-size-bytes=` + `--max-l1-tx-size-bytes=120000` + `OP_BATCHER_MAX_L1_TX_SIZE_BYTES=120000` ### Batcher startup @@ -289,10 +289,10 @@ Indicates if, during startup, the batcher should wait for a recent batcher tx on L1 to finalize (via more block confirmations). This should help avoid duplicate batcher txs. The default value is `false`. - - `--wait-node-sync=` - `--wait-node-sync=false` - `OP_BATCHER_WAIT_NODE_SYNC=false` + + `--wait-node-sync=` + `--wait-node-sync=false` + `OP_BATCHER_WAIT_NODE_SYNC=false` #### check-recent-txs-depth @@ -302,10 +302,10 @@ recent batch tx on L1. This can speed up waiting for node sync. It should be set to the verifier confirmation depth of the sequencer (e.g. 4). The default value is `0`. - - `--check-recent-txs-depth=` - `--check-recent-txs-depth=0` - `OP_BATCHER_CHECK_RECENT_TXS_DEPTH=0` + + `--check-recent-txs-depth=` + `--check-recent-txs-depth=0` + `OP_BATCHER_CHECK_RECENT_TXS_DEPTH=0` #### stopped @@ -313,10 +313,10 @@ value is `0`. Initialize the batcher in a stopped state. The batcher can be started using the admin\_startBatcher RPC. The default value is `false`. - - `--stopped=` - `--stopped=false` - `OP_BATCHER_STOPPED=false` + + `--stopped=` + `--stopped=false` + `OP_BATCHER_STOPPED=false` ### Throttling @@ -324,157 +324,133 @@ admin\_startBatcher RPC. The default value is `false`. The batcher supports throttling configuration to limit DA usage for transactions and blocks, and to control throttle intensity via several controller types (including an experimental PID controller). The following flags are available: #### throttle.additional-endpoints - Comma-separated list of endpoints to distribute throttling configuration to (in addition to the L2 endpoints specified with `--l2-eth-rpc`). +Comma-separated list of endpoints to distribute throttling configuration to (in addition to the L2 endpoints specified with `--l2-eth-rpc`). - - Type: string slice - Default: none - CLI: `--throttle.additional-endpoints=,,...` - - - - CLI: `--throttle.additional-endpoints=http://builder1:8545,http://builder2:8545` - - - - `THROTTLE_ADDITIONAL_ENDPOINTS=http://builder1:8545,http://builder2:8545` - + `--throttle.additional-endpoints=,,...` + `--throttle.additional-endpoints=http://builder1:8545,http://builder2:8545` + `THROTTLE_ADDITIONAL_ENDPOINTS=http://builder1:8545,http://builder2:8545` #### throttle.tx-size-lower-limit - The DA size limit for individual transactions when the throttle intensity is at its maximum. `0` disables limits; use `1` as the smallest effective limit. +The DA size limit for individual transactions when the throttle intensity is at its maximum. `0` disables limits; use `1` as the smallest effective limit. - - Type: uint64 - Default: `150` - CLI: `--throttle.tx-size-lower-limit=` - - - - CLI: `--throttle.tx-size-lower-limit=150` - - - - `THROTTLE_TX_SIZE_LOWER_LIMIT=150` - + `--throttle.tx-size-lower-limit=` + `--throttle.tx-size-lower-limit=150` + `THROTTLE_TX_SIZE_LOWER_LIMIT=150` #### throttle.tx-size-upper-limit - The DA size limit for individual transactions as throttle intensity approaches `0` (minimal throttling). Not applied when throttling is inactive. +The DA size limit for individual transactions as throttle intensity approaches `0` (minimal throttling). Not applied when throttling is inactive. - - Type: uint64 - Default: `20000` - CLI: `--throttle.tx-size-upper-limit=` - - - - CLI: `--throttle.tx-size-upper-limit=20000` - - - - `THROTTLE_TX_SIZE_UPPER_LIMIT=20000` - + `--throttle.tx-size-upper-limit=` + `--throttle.tx-size-upper-limit=20000` + `THROTTLE_TX_SIZE_UPPER_LIMIT=20000` #### throttle.block-size-lower-limit - The DA size limit for blocks when throttle intensity is at maximum (applies for linear and quadratic controllers). `0` disables limits; use `1` as the smallest effective limit. +The DA size limit for blocks when throttle intensity is at maximum (applies for linear and quadratic controllers). `0` disables limits; use `1` as the smallest effective limit. - - Type: uint64 - Default: `2000` - CLI: `--throttle.block-size-lower-limit=` - + `--throttle.block-size-lower-limit=` + `--throttle.block-size-lower-limit=2000` + `THROTTLE_BLOCK_SIZE_LOWER_LIMIT=2000` + - - CLI: `--throttle.block-size-lower-limit=2000` - +#### throttle.block-size-upper-limit +The DA size limit for blocks when throttling is inactive (throttle intensity = 0). - - `THROTTLE_BLOCK_SIZE_LOWER_LIMIT=2000` - + + `--throttle.block-size-upper-limit=` + `--throttle.block-size-upper-limit=130000` + `THROTTLE_BLOCK_SIZE_UPPER_LIMIT=130000` -#### throttle.block-size-upper-limit - The DA size limit for blocks when throttling is inactive (throttle intensity = 0). +#### throttle.controller-type +Type of throttle controller to use. Valid values: `step`, `linear`, `quadratic` (default), `pid` (EXPERIMENTAL - use with caution). - - Type: uint64 - Default: `130000` - CLI: `--throttle.block-size-upper-limit=` - + `--throttle.controller-type=` + `--throttle.controller-type=quadratic` + `THROTTLE_CONTROLLER_TYPE=quadratic` + - - CLI: `--throttle.block-size-upper-limit=130000` - +#### throttle.unsafe-da-bytes-lower-threshold +Threshold on `unsafe_da_bytes` beyond which the batcher will start to throttle the block builder. `0` disables throttling. - - `THROTTLE_BLOCK_SIZE_UPPER_LIMIT=130000` - + + `--throttle.unsafe-da-bytes-lower-threshold=` + `--throttle.unsafe-da-bytes-lower-threshold=3200000` + `THROTTLE_UNSAFE_DA_BYTES_LOWER_THRESHOLD=3200000` -#### throttle.controller-type - Type of throttle controller to use. Valid values: `step`, `linear`, `quadratic` (default), `pid` (EXPERIMENTAL - use with caution). +#### throttle.unsafe-da-bytes-upper-threshold +Threshold on `unsafe_da_bytes` at which throttling reaches maximum intensity (applies for linear and quadratic controllers). - - Type: string - Default: `quadratic` - CLI: `--throttle.controller-type=` - + `--throttle.unsafe-da-bytes-upper-threshold=` + `--throttle.unsafe-da-bytes-upper-threshold=12800000` + `THROTTLE_UNSAFE_DA_BYTES_UPPER_THRESHOLD=12800000` + - - CLI: `--throttle.controller-type=quadratic` - +#### (EXPERIMENTAL) PID controller flags +These flags are only relevant when `--throttle.controller-type=pid`. The PID controller is experimental — adjust carefully. - - `THROTTLE_CONTROLLER_TYPE=quadratic` - +##### throttle.pid-kp +PID proportional gain. Must be >= 0. + + + `--throttle.pid-kp=` + `--throttle.pid-kp=0.33` + `THROTTLE_PID_KP=0.33` -#### throttle.unsafe-da-bytes-lower-threshold - Threshold on `unsafe_da_bytes` beyond which the batcher will start to throttle the block builder. `0` disables throttling. +##### throttle.pid-ki +PID integral gain. Must be >= 0. - - Type: uint64 - Default: `3200000` - CLI: `--throttle.unsafe-da-bytes-lower-threshold=` - + `--throttle.pid-ki=` + `--throttle.pid-ki=0.01` + `THROTTLE_PID_KI=0.01` + - - CLI: `--throttle.unsafe-da-bytes-lower-threshold=3200000` - +##### throttle.pid-kd +PID derivative gain. Must be >= 0. - - `THROTTLE_UNSAFE_DA_BYTES_LOWER_THRESHOLD=3200000` - + + `--throttle.pid-kd=` + `--throttle.pid-kd=0.05` + `THROTTLE_PID_KD=0.05` -#### throttle.unsafe-da-bytes-upper-threshold - Threshold on `unsafe_da_bytes` at which throttling reaches maximum intensity (applies for linear and quadratic controllers). +##### throttle.pid-integral-max +PID maximum integral windup. Must be > 0. - - Type: uint64 - Default: `12800000` - CLI: `--throttle.unsafe-da-bytes-upper-threshold=` - + `--throttle.pid-integral-max=` + `--throttle.pid-integral-max=1000.0` + `THROTTLE_PID_INTEGRAL_MAX=1000.0` + - - CLI: `--throttle.unsafe-da-bytes-upper-threshold=12800000` - +##### throttle.pid-output-max +PID maximum output (normalized between 0 and 1). Must be > 0 and <= 1.0. - - `THROTTLE_UNSAFE_DA_BYTES_UPPER_THRESHOLD=12800000` - + + `--throttle.pid-output-max=` + `--throttle.pid-output-max=1.0` + `THROTTLE_PID_OUTPUT_MAX=1.0` +##### throttle.pid-sample-time +PID sample time interval. + + + `--throttle.pid-sample-time=` + `--throttle.pid-sample-time=2s` + `THROTTLE_PID_SAMPLE_TIME=2s` + ### Transaction manager @@ -483,10 +459,10 @@ The batcher supports throttling configuration to limit DA usage for transactions Number of confirmations which we will wait after sending a transaction. The default value is `10`. - - `--num-confirmations=` - `--num-confirmations=10` - `OP_BATCHER_NUM_CONFIRMATIONS=10` + + `--num-confirmations=` + `--num-confirmations=10` + `OP_BATCHER_NUM_CONFIRMATIONS=10` #### max-pending-tx @@ -494,10 +470,10 @@ default value is `10`. The maximum number of pending transactions. 0 for no limit. The default value is `1`. - - `--max-pending-tx=` - `--max-pending-tx=1` - `OP_BATCHER_MAX_PENDING_TX=1` + + `--max-pending-tx=` + `--max-pending-tx=1` + `OP_BATCHER_MAX_PENDING_TX=1` #### resubmission-timeout @@ -505,10 +481,10 @@ is `1`. Duration we will wait before resubmitting a transaction to L1. The default value is `48s`. - - `--resubmission-timeout=` - `--resubmission-timeout=48s` - `OP_BATCHER_RESUBMISSION_TIMEOUT=48s` + + `--resubmission-timeout=` + `--resubmission-timeout=48s` + `OP_BATCHER_RESUBMISSION_TIMEOUT=48s` #### safe-abort-nonce-too-low-count @@ -516,10 +492,10 @@ value is `48s`. Number of ErrNonceTooLow observations required to give up on a tx at a particular nonce without receiving confirmation. The default value is `3`. - - `--safe-abort-nonce-too-low-count=` - `--safe-abort-nonce-too-low-count=3` - `OP_BATCHER_SAFE_ABORT_NONCE_TOO_LOW_COUNT=3` + + `--safe-abort-nonce-too-low-count=` + `--safe-abort-nonce-too-low-count=3` + `OP_BATCHER_SAFE_ABORT_NONCE_TOO_LOW_COUNT=3` #### txmgr.min-basefee @@ -527,10 +503,10 @@ particular nonce without receiving confirmation. The default value is `3`. Enforces a minimum base fee (in GWei) to assume when determining tx fees. 1 GWei by default. The default value is `1`. - - `--txmgr.min-basefee=` - `--txmgr.min-basefee=1` - `OP_BATCHER_TXMGR_MIN_BASEFEE=1` + + `--txmgr.min-basefee=` + `--txmgr.min-basefee=1` + `OP_BATCHER_TXMGR_MIN_BASEFEE=1` #### txmgr.min-tip-cap @@ -538,10 +514,10 @@ GWei by default. The default value is `1`. Enforces a minimum tip cap (in GWei) to use when determining tx fees. 1 GWei by default. The default value is `1`. - - `--txmgr.min-tip-cap=` - `--txmgr.min-tip-cap=1` - `OP_BATCHER_TXMGR_MIN_TIP_CAP=1` + + `--txmgr.min-tip-cap=` + `--txmgr.min-tip-cap=1` + `OP_BATCHER_TXMGR_MIN_TIP_CAP=1` #### fee-limit-multiplier @@ -549,10 +525,10 @@ default. The default value is `1`. The multiplier applied to fee suggestions to put a hard limit on fee increases. The default value is `5`. - - `--fee-limit-multiplier=` - `--fee-limit-multiplier=5` - `OP_BATCHER_TXMGR_FEE_LIMIT_MULTIPLIER=5` + + `--fee-limit-multiplier=` + `--fee-limit-multiplier=5` + `OP_BATCHER_TXMGR_FEE_LIMIT_MULTIPLIER=5` #### txmgr.fee-limit-threshold @@ -560,20 +536,20 @@ The default value is `5`. The minimum threshold (in GWei) at which fee bumping starts to be capped. Allows arbitrary fee bumps below this threshold. The default value is `100`. - - `--txmgr.fee-limit-threshold=` - `--txmgr.fee-limit-threshold=100` - `OP_BATCHER_TXMGR_FEE_LIMIT_THRESHOLD=100` + + `--txmgr.fee-limit-threshold=` + `--txmgr.fee-limit-threshold=100` + `OP_BATCHER_TXMGR_FEE_LIMIT_THRESHOLD=100` #### txmgr.receipt-query-interval Frequency to poll for receipts. The default value is `12s`. - - `--txmgr.receipt-query-interval=` - `--txmgr.receipt-query-interval=12s` - `OP_BATCHER_TXMGR_RECEIPT_QUERY_INTERVAL=12s` + + `--txmgr.receipt-query-interval=` + `--txmgr.receipt-query-interval=12s` + `OP_BATCHER_TXMGR_RECEIPT_QUERY_INTERVAL=12s` #### txmgr.not-in-mempool-timeout @@ -581,10 +557,10 @@ Frequency to poll for receipts. The default value is `12s`. Timeout for aborting a tx send if the tx does not make it to the mempool. The default value is `2m0s`. - - `--txmgr.not-in-mempool-timeout=` - `--txmgr.not-in-mempool-timeout=2m0s` - `OP_BATCHER_TXMGR_TX_NOT_IN_MEMPOOL_TIMEOUT=2m0s` + + `--txmgr.not-in-mempool-timeout=` + `--txmgr.not-in-mempool-timeout=2m0s` + `OP_BATCHER_TXMGR_TX_NOT_IN_MEMPOOL_TIMEOUT=2m0s` #### txmgr.send-timeout @@ -592,10 +568,10 @@ default value is `2m0s`. Timeout for sending transactions. If 0 it is disabled. The default value is `0s`. - - `--txmgr.send-timeout=` - `--txmgr.send-timeout=0s` - `OP_BATCHER_TXMGR_TX_SEND_TIMEOUT=0s` + + `--txmgr.send-timeout=` + `--txmgr.send-timeout=0s` + `OP_BATCHER_TXMGR_TX_SEND_TIMEOUT=0s` ### Authentication and wallet @@ -604,20 +580,20 @@ Timeout for sending transactions. If 0 it is disabled. The default value is The private key to use with the service. Must not be used with mnemonic. - - `--private-key=` - `--private-key=` - `OP_BATCHER_PRIVATE_KEY=` + + `--private-key=` + `--private-key=` + `OP_BATCHER_PRIVATE_KEY=` #### mnemonic The mnemonic used to derive the wallets for either the service. - - `--mnemonic=` - `--mnemonic=` - `OP_BATCHER_MNEMONIC=` + + `--mnemonic=` + `--mnemonic=` + `OP_BATCHER_MNEMONIC=` #### hd-path @@ -625,10 +601,10 @@ The mnemonic used to derive the wallets for either the service. The HD path used to derive the sequencer wallet from the mnemonic. The mnemonic flag must also be set. - - `--hd-path=` - `--hd-path=` - `OP_BATCHER_HD_PATH=` + + `--hd-path=` + `--hd-path=` + `OP_BATCHER_HD_PATH=` @@ -636,20 +612,20 @@ flag must also be set. Address the signer is signing transactions for. - - `--signer.address=` - `--signer.address=` - `OP_BATCHER_SIGNER_ADDRESS=` + + `--signer.address=` + `--signer.address=` + `OP_BATCHER_SIGNER_ADDRESS=` #### signer.endpoint Signer endpoint the client will connect to. - - `--signer.endpoint=` - `--signer.endpoint=` - `OP_BATCHER_SIGNER_ENDPOINT=` + + `--signer.endpoint=` + `--signer.endpoint=` + `OP_BATCHER_SIGNER_ENDPOINT=` #### signer.header @@ -659,40 +635,40 @@ 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. - - `--signer.header=` - `--signer.header="Authorization=Bearer 123abc"` - `OP_BATCHER_SIGNER_HEADER=Authorization=Bearer 123abc` + + `--signer.header=` + `--signer.header="Authorization=Bearer 123abc"` + `OP_BATCHER_SIGNER_HEADER=Authorization=Bearer 123abc` #### signer.tls.ca tls ca cert path. The default value is `tls/ca.crt`. - - `--signer.tls.ca=` - `--signer.tls.ca=tls/ca.crt` - `OP_BATCHER_SIGNER_TLS_CA=tls/ca.crt` + + `--signer.tls.ca=` + `--signer.tls.ca=tls/ca.crt` + `OP_BATCHER_SIGNER_TLS_CA=tls/ca.crt` #### signer.tls.cert tls cert path. The default value is `tls/tls.crt`. - - `--signer.tls.cert=` - `--signer.tls.cert=tls/tls.crt` - `OP_BATCHER_SIGNER_TLS_CERT=` + + `--signer.tls.cert=` + `--signer.tls.cert=tls/tls.crt` + `OP_BATCHER_SIGNER_TLS_CERT=` #### signer.tls.key tls key. The default value is `tls/tls.key`. - - `--signer.tls.key=` - `--signer.tls.key=tls/tls.key` - `OP_BATCHER_SIGNER_TLS_KEY=` + + `--signer.tls.key=` + `--signer.tls.key=tls/tls.key` + `OP_BATCHER_SIGNER_TLS_KEY=` ### Network connections @@ -701,10 +677,10 @@ tls key. The default value is `tls/tls.key`. HTTP provider URL for L1. - - `--l1-eth-rpc=` - `--l1-eth-rpc` - `OP_BATCHER_L1_ETH_RPC=` + + `--l1-eth-rpc=` + `--l1-eth-rpc` + `OP_BATCHER_L1_ETH_RPC=` #### l2-eth-rpc @@ -713,10 +689,10 @@ HTTP provider URL for L2 execution engine. A comma-separated list enables the active L2 endpoint provider. Such a list needs to match the number of rollup-rpcs provided. - - `--l2-eth-rpc=` - `--l2-eth-rpc=` - `OP_BATCHER_L2_ETH_RPC=` + + `--l2-eth-rpc=` + `--l2-eth-rpc=` + `OP_BATCHER_L2_ETH_RPC=` #### rollup-rpc @@ -725,50 +701,50 @@ HTTP provider URL for Rollup node. A comma-separated list enables the active L2 endpoint provider. Such a list needs to match the number of l2-eth-rpcs provided. - - `--rollup-rpc=` - `--rollup-rpc=` - `OP_BATCHER_ROLLUP_RPC=` + + `--rollup-rpc=` + `--rollup-rpc=` + `OP_BATCHER_ROLLUP_RPC=` #### rpc.addr rpc listening address. The default value is `0.0.0.0`. - - `--rpc.addr=` - `--rpc.addr=0.0.0.0` - `OP_BATCHER_RPC_ADDR=0.0.0.0` + + `--rpc.addr=` + `--rpc.addr=0.0.0.0` + `OP_BATCHER_RPC_ADDR=0.0.0.0` #### rpc.enable-admin Enable the admin API. The default value is `false`. - - `--rpc.enable-admin=` - `--rpc.enable-admin=false` - `OP_BATCHER_RPC_ENABLE_ADMIN=false` + + `--rpc.enable-admin=` + `--rpc.enable-admin=false` + `OP_BATCHER_RPC_ENABLE_ADMIN=false` #### rpc.port rpc listening port. The default value is `8545`. - - `--rpc.port=` - `--rpc.port=8545` - `OP_BATCHER_RPC_PORT=8545` + + `--rpc.port=` + `--rpc.port=8545` + `OP_BATCHER_RPC_PORT=8545` #### network-timeout Timeout for all network operations. The default value is `10s`. - - `--network-timeout=` - `--network-timeout=10s` - `OP_BATCHER_NETWORK_TIMEOUT=10s` + + `--network-timeout=` + `--network-timeout=10s` + `OP_BATCHER_NETWORK_TIMEOUT=10s` ### Alt-DA mode (Beta feature) @@ -780,20 +756,20 @@ 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`. - - `--altda.enabled=` - `--altda.enabled=false` - `OP_BATCHER_ALTDA_ENABLED=false` + + `--altda.enabled=` + `--altda.enabled=false` + `OP_BATCHER_ALTDA_ENABLED=false` #### altda.da-server HTTP address of a DA Server. - - `--altda.da-server=` - `--altda.da-server=http://da.example.com:1234` - `$OP_BATCHER_ALTDA_DA_SERVER=http://da.example.com:1234` + + `--altda.da-server=` + `--altda.da-server=http://da.example.com:1234` + `OP_BATCHER_ALTDA_DA_SERVER=http://da.example.com:1234` #### altda.da-service @@ -801,50 +777,50 @@ HTTP address of a DA Server. Use DA service type where commitments are generated by Alt-DA server. The default value is `false`. - - `--altda.da-service=` - `--altda.da-service=true` - `$OP_BATCHER_ALTDA_DA_SERVER=true` + + `--altda.da-service=` + `--altda.da-service=true` + `OP_BATCHER_ALTDA_DA_SERVER=true` #### altda.get-timeout Timeout for get requests. **0 means no timeout**. - - `--altda.get-timeout=` - `--altda.get-timeout=5s` - `OP_BATCHER_ALTDA_GET_TIMEOUT=5s` + + `--altda.get-timeout=` + `--altda.get-timeout=5s` + `OP_BATCHER_ALTDA_GET_TIMEOUT=5s` #### altda.put-timeout Timeout for put requests. **0 means no timeout**. - - `--altda.put-timeout=` - `--altda.put-timeout=10s` - `OP_BATCHER_ALTDA_PUT_TIMEOUT=10s` + + `--altda.put-timeout=` + `--altda.put-timeout=10s` + `OP_BATCHER_ALTDA_PUT_TIMEOUT=10s` #### altda.max-concurrent-da-requests Maximum number of concurrent requests to the DA server. - - `--altda.max-concurrent-da-requests=` - `--altda.max-concurrent-da-requests=4` - `OP_BATCHER_ALTDA_MAX_CONCURRENT_DA_REQUESTS=4` + + `--altda.max-concurrent-da-requests=` + `--altda.max-concurrent-da-requests=4` + `OP_BATCHER_ALTDA_MAX_CONCURRENT_DA_REQUESTS=4` #### altda.verify-on-read Verify input data matches the commitments from the DA storage service. - - `--altda.verify-on-read=` - `--altda.verify-on-read=true` - `OP_BATCHER_ALTDA_VERIFY_ON_READ=true` + + `--altda.verify-on-read=` + `--altda.verify-on-read=true` + `OP_BATCHER_ALTDA_VERIFY_ON_READ=true` ### Logging and monitoring @@ -853,10 +829,10 @@ Verify input data matches the commitments from the DA storage service. The lowest log level that will be output. The default value is `INFO`. - - `--log.level=` - `--log.level=INFO` - `OP_BATCHER_LOG_LEVEL=INFO` + + `--log.level=` + `--log.level=INFO` + `OP_BATCHER_LOG_LEVEL=INFO` #### log.format @@ -864,42 +840,42 @@ The lowest log level that will be output. The default value is `INFO`. Format the log output. Supported formats: 'text', 'terminal', 'logfmt', 'json', 'json-pretty'. The default value is `text`. - - `--log.format=` - `--log.format=text` - `OP_BATCHER_LOG_FORMAT=text` + + `--log.format=` + `--log.format=text` + `OP_BATCHER_LOG_FORMAT=text` #### log.color Color the log output if in terminal mode. The default value is `false`. - - `--log.color=` - `--log.color=false` - `OP_BATCHER_LOG_COLOR=false` + + `--log.color=` + `--log.color=false` + `OP_BATCHER_LOG_COLOR=false` #### log.pid Show PID in the log. - - `--log.pid=` - `--log.pid=true` - `OP_BATCHER_LOG_PID=true` + + `--log.pid=` + `--log.pid=true` + `OP_BATCHER_LOG_PID=true` #### metrics.enabled Enable the metrics server. The default value is `false`. - - `--version=` - `--version=false` + + `--version=` + `--version=false` + `OP_BATCHER_METRICS_ENABLED=false` - ### Miscellaneous #### active-sequencer-check-duration @@ -907,50 +883,50 @@ Enable the metrics server. The default value is `false`. The duration between checks to determine the active sequencer endpoint. The default value is `2m0s`. - - `--active-sequencer-check-duration=` - `--active-sequencer-check-duration=2m0s` - `OP_BATCHER_ACTIVE_SEQUENCER_CHECK_DURATION=2m0s` + + `--active-sequencer-check-duration=` + `--active-sequencer-check-duration=2m0s` + `OP_BATCHER_ACTIVE_SEQUENCER_CHECK_DURATION=2m0s` #### pprof.addr pprof listening address. The default value is `0.0.0.0`. - - `--pprof.addr=` - `--pprof.addr=0.0.0.0` - `OP_BATCHER_PPROF_ADDR=0.0.0.0` + + `--pprof.addr=` + `--pprof.addr=0.0.0.0` + `OP_BATCHER_PPROF_ADDR=0.0.0.0` #### pprof.enabled Enable the pprof server. The default value is `false`. - - `--pprof.enabled=` - `--pprof.enabled=false` - `OP_BATCHER_PPROF_ENABLED=false` + + `--pprof.enabled=` + `--pprof.enabled=false` + `OP_BATCHER_PPROF_ENABLED=false` #### pprof.path pprof file path. If it is a directory, the path is `{dir}/{profileType}.prof`. - - `--pprof.path=` - `--pprof.path=` - `OP_BATCHER_PPROF_PATH=` + + `--pprof.path=` + `--pprof.path=` + `OP_BATCHER_PPROF_PATH=` #### pprof.port pprof listening port. The default value is `6060`. - - `--pprof.port=` - `--pprof.port=6060` - `OP_BATCHER_PPROF_PORT=6060` + + `--pprof.port=` + `--pprof.port=6060` + `OP_BATCHER_PPROF_PORT=6060` #### pprof.type @@ -958,26 +934,28 @@ pprof listening port. The default value is `6060`. pprof profile type. One of cpu, heap, goroutine, threadcreate, block, mutex, allocs. - - `--pprof.type=` - `--pprof.type` - `OP_BATCHER_PPROF_TYPE=` + + `--pprof.type=` + `--pprof.type` + `OP_BATCHER_PPROF_TYPE=` #### help Show help. The default value is false. - - `--help=` - `--help=false` + + `--help=` + `--help=false` + `OP_BATCHER_HELP=false` #### version Print the version. The default value is false. - - `--version=` - `--version=false` - + + `--version=` + `--version=false` + `OP_BATCHER_VERSION=false` + \ No newline at end of file From 887c54774ca4fd2e2dcba77e9f6e4e5d0fd0537d Mon Sep 17 00:00:00 2001 From: geoknee Date: Wed, 26 Nov 2025 10:40:05 +0000 Subject: [PATCH 6/6] Remove PID throttle flags and update types --- .../guides/configuration/batcher.mdx | 61 +------------------ 1 file changed, 2 insertions(+), 59 deletions(-) diff --git a/chain-operators/guides/configuration/batcher.mdx b/chain-operators/guides/configuration/batcher.mdx index d04a403a1..ea552c8bc 100644 --- a/chain-operators/guides/configuration/batcher.mdx +++ b/chain-operators/guides/configuration/batcher.mdx @@ -369,7 +369,7 @@ The DA size limit for blocks when throttling is inactive (throttle intensity = 0 #### throttle.controller-type -Type of throttle controller to use. Valid values: `step`, `linear`, `quadratic` (default), `pid` (EXPERIMENTAL - use with caution). +Type of throttle controller to use. Valid values: `step`, `linear`, or `quadratic` (default). `--throttle.controller-type=` @@ -395,63 +395,6 @@ Threshold on `unsafe_da_bytes` at which throttling reaches maximum intensity (ap `THROTTLE_UNSAFE_DA_BYTES_UPPER_THRESHOLD=12800000` -#### (EXPERIMENTAL) PID controller flags -These flags are only relevant when `--throttle.controller-type=pid`. The PID controller is experimental — adjust carefully. - -##### throttle.pid-kp -PID proportional gain. Must be >= 0. - - - `--throttle.pid-kp=` - `--throttle.pid-kp=0.33` - `THROTTLE_PID_KP=0.33` - - -##### throttle.pid-ki -PID integral gain. Must be >= 0. - - - `--throttle.pid-ki=` - `--throttle.pid-ki=0.01` - `THROTTLE_PID_KI=0.01` - - -##### throttle.pid-kd -PID derivative gain. Must be >= 0. - - - `--throttle.pid-kd=` - `--throttle.pid-kd=0.05` - `THROTTLE_PID_KD=0.05` - - -##### throttle.pid-integral-max -PID maximum integral windup. Must be > 0. - - - `--throttle.pid-integral-max=` - `--throttle.pid-integral-max=1000.0` - `THROTTLE_PID_INTEGRAL_MAX=1000.0` - - -##### throttle.pid-output-max -PID maximum output (normalized between 0 and 1). Must be > 0 and <= 1.0. - - - `--throttle.pid-output-max=` - `--throttle.pid-output-max=1.0` - `THROTTLE_PID_OUTPUT_MAX=1.0` - - -##### throttle.pid-sample-time -PID sample time interval. - - - `--throttle.pid-sample-time=` - `--throttle.pid-sample-time=2s` - `THROTTLE_PID_SAMPLE_TIME=2s` - - ### Transaction manager #### num-confirmations @@ -958,4 +901,4 @@ Print the version. The default value is false. `--version=` `--version=false` `OP_BATCHER_VERSION=false` - \ No newline at end of file +