Update batcher throttling docs and defaults

[geoknee]

No description provided.

[geoknee]

Note that these tab objects don't seem to render correctly on the new site.

I wonder if we should just point the user at the batcher CLI help, or copy paste that here?

[geoknee]

  op-batcher git:(gk/recover-mode-fixes) ✗ go run cmd/main.go --help
NAME:
   op-batcher - Batch Submitter Service

USAGE:
   op-batcher [global options] command [command options]

VERSION:
   v0.0.0

DESCRIPTION:
   Service for generating and submitting L2 tx batches to L1

COMMANDS:
   doc
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:

    --active-sequencer-check-duration value (default: 5s)                      ($OP_BATCHER_ACTIVE_SEQUENCER_CHECK_DURATION)
          The duration between checks to determine the active sequencer endpoint.

    --altda.da-server value                                                ($OP_BATCHER_ALTDA_DA_SERVER)
          HTTP address of a DA Server

    --altda.da-service                  (default: false)                   ($OP_BATCHER_ALTDA_DA_SERVICE)
          Use DA service type where commitments are generated by Alt-DA server

    --altda.enabled                     (default: false)                   ($OP_BATCHER_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.

    --altda.get-timeout value           (default: 0s)                      ($OP_BATCHER_ALTDA_GET_TIMEOUT)
          Timeout for get requests. 0 means no timeout.

    --altda.max-concurrent-da-requests value (default: 1)                       ($OP_BATCHER_ALTDA_MAX_CONCURRENT_DA_REQUESTS)
          Maximum number of concurrent requests to the DA server

    --altda.put-timeout value           (default: 0s)                      ($OP_BATCHER_ALTDA_PUT_TIMEOUT)
          Timeout for put requests. 0 means no timeout.

    --altda.verify-on-read              (default: true)                    ($OP_BATCHER_ALTDA_VERIFY_ON_READ)
          Verify input data matches the commitments from the DA storage service

    --approx-compr-ratio value          (default: 0.6)                     ($OP_BATCHER_APPROX_COMPR_RATIO)
          The approximate compression ratio (<= 1.0). Only relevant for ratio compressor.

    --batch-type value                  (default: singular)                ($OP_BATCHER_BATCH_TYPE)
          The batch type. 0 for SingularBatch and 1 for SpanBatch.

    --check-recent-txs-depth value      (default: 0)                       ($OP_BATCHER_CHECK_RECENT_TXS_DEPTH)
          Indicates how many blocks back the batcher should look during startup for a
          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).

    --compression-algo value            (default: zlib)                    ($OP_BATCHER_COMPRESSION_ALGO)
          The compression algorithm to use. Valid options: zlib, brotli, brotli-9,
          brotli-10, brotli-11

    --compressor value                  (default: "shadow")                ($OP_BATCHER_COMPRESSOR)
          The type of compressor. Valid options: shadow, none, ratio

    --data-availability-type value      (default: calldata)                ($OP_BATCHER_DATA_AVAILABILITY_TYPE)
          The data availability type to use for submitting batches to the L1. Valid
          options: calldata, blobs, auto

    --fee-limit-multiplier value        (default: 5)                       ($OP_BATCHER_TXMGR_FEE_LIMIT_MULTIPLIER)
          The multiplier applied to fee suggestions to put a hard limit on fee increases

    --hd-path value                                                        ($OP_BATCHER_HD_PATH)
          The HD path used to derive the sequencer wallet from the mnemonic. The mnemonic
          flag must also be set.

    --l1-eth-rpc value                                                     ($OP_BATCHER_L1_ETH_RPC)
          HTTP provider URL for L1

    --l2-eth-rpc value                                                     ($OP_BATCHER_L2_ETH_RPC)
          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.

    --log.color                         (default: false)                   ($OP_BATCHER_LOG_COLOR)
          Color the log output if in terminal mode

    --log.format value                  (default: text)                    ($OP_BATCHER_LOG_FORMAT)
          Format the log output. Supported formats: text, terminal, logfmt, logfmtms,
          json, jsonms

    --log.level value                   (default: INFO)                    ($OP_BATCHER_LOG_LEVEL)
          The lowest log level that will be output

    --log.pid                           (default: false)                   ($OP_BATCHER_LOG_PID)
          Show pid in the log

    --max-blocks-per-span-batch value   (default: 0)                       ($OP_BATCHER_MAX_BLOCKS_PER_SPAN_BATCH)
          Maximum number of blocks to add to a span batch. Default is 0 - no maximum.

    --max-channel-duration value        (default: 0)                       ($OP_BATCHER_MAX_CHANNEL_DURATION)
          The maximum duration of L1-blocks to keep a channel open. 0 to disable.

    --max-l1-tx-size-bytes value        (default: 120000)                  ($OP_BATCHER_MAX_L1_TX_SIZE_BYTES)
          The maximum size of a batch tx submitted to L1. Ignored for blobs, where max
          blob size will be used.

    --max-pending-tx value              (default: 1)                       ($OP_BATCHER_MAX_PENDING_TX)
          The maximum number of pending transactions. 0 for no limit.

    --metrics.addr value                (default: "0.0.0.0")               ($OP_BATCHER_METRICS_ADDR)
          Metrics listening address

    --metrics.enabled                   (default: false)                   ($OP_BATCHER_METRICS_ENABLED)
          Enable the metrics server

    --metrics.port value                (default: 7300)                    ($OP_BATCHER_METRICS_PORT)
          Metrics listening port

    --mnemonic value                                                       ($OP_BATCHER_MNEMONIC)
          The mnemonic used to derive the wallets for either the service

    --network-timeout value             (default: 10s)                     ($OP_BATCHER_NETWORK_TIMEOUT)
          Timeout for all network operations

    --num-confirmations value           (default: 10)                      ($OP_BATCHER_NUM_CONFIRMATIONS)
          Number of confirmations which we will wait after sending a transaction

    --poll-interval value               (default: 6s)                      ($OP_BATCHER_POLL_INTERVAL)
          How frequently to poll L2 for new blocks

    --pprof.addr value                  (default: "0.0.0.0")               ($OP_BATCHER_PPROF_ADDR)
          pprof listening address

    --pprof.enabled                     (default: false)                   ($OP_BATCHER_PPROF_ENABLED)
          Enable the pprof server

    --pprof.path value                                                     ($OP_BATCHER_PPROF_PATH)
          pprof file path. If it is a directory, the path is {dir}/{profileType}.prof

    --pprof.port value                  (default: 6060)                    ($OP_BATCHER_PPROF_PORT)
          pprof listening port

    --pprof.type value                                                     ($OP_BATCHER_PPROF_TYPE)
          pprof profile type. One of cpu, heap, goroutine, threadcreate, block, mutex,
          allocs

    --private-key value                                                    ($OP_BATCHER_PRIVATE_KEY)
          The private key to use with the service. Must not be used with mnemonic.

    --resubmission-timeout value        (default: 48s)                     ($OP_BATCHER_RESUBMISSION_TIMEOUT)
          Duration we will wait before resubmitting a transaction to L1

    --rollup-rpc value                                                     ($OP_BATCHER_ROLLUP_RPC)
          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.

    --rpc.addr value                    (default: "0.0.0.0")               ($OP_BATCHER_RPC_ADDR)
          rpc listening address

    --rpc.enable-admin                  (default: false)                   ($OP_BATCHER_RPC_ENABLE_ADMIN)
          Enable the admin API

    --rpc.port value                    (default: 8545)                    ($OP_BATCHER_RPC_PORT)
          rpc listening port

    --safe-abort-nonce-too-low-count value (default: 3)                       ($OP_BATCHER_SAFE_ABORT_NONCE_TOO_LOW_COUNT)
          Number of ErrNonceTooLow observations required to give up on a tx at a
          particular nonce without receiving confirmation

    --sequencer-hd-path value                                              ($OP_BATCHER_SEQUENCER_HD_PATH)
          DEPRECATED: The HD path used to derive the sequencer wallet from the mnemonic.
          The mnemonic flag must also be set.

    --signer.address value                                                 ($OP_BATCHER_SIGNER_ADDRESS)
          Address the signer is signing requests for

    --signer.endpoint value                                                ($OP_BATCHER_SIGNER_ENDPOINT)
          Signer endpoint the client will connect to

    --signer.header value                                                  ($OP_BATCHER_SIGNER_HEADER)
          Headers to pass to the remote signer. Format `key=value`. Value can contain any
          character allowed in a HTTP header. When using env vars, split with commas. When
          using flags one key value pair per flag.

    --signer.tls.ca value               (default: "tls/ca.crt")            ($OP_BATCHER_SIGNER_TLS_CA)
          tls ca cert path

    --signer.tls.cert value             (default: "tls/tls.crt")           ($OP_BATCHER_SIGNER_TLS_CERT)
          tls cert path

    --signer.tls.enabled                (default: true)                    ($OP_BATCHER_SIGNER_TLS_ENABLED)
          Enable or disable TLS client authentication for the signer

    --signer.tls.key value              (default: "tls/tls.key")           ($OP_BATCHER_SIGNER_TLS_KEY)
          tls key

    --stopped                           (default: false)                   ($OP_BATCHER_STOPPED)
          Initialize the batcher in a stopped state. The batcher can be started using the
          admin_startBatcher RPC

    --sub-safety-margin value           (default: 10)                      ($OP_BATCHER_SUB_SAFETY_MARGIN)
          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.

    --target-num-frames value           (default: 1)                       ($OP_BATCHER_TARGET_NUM_FRAMES)
          The target number of frames to create per channel. Controls number of blobs per
          blob tx, if using Blob DA.

    --throttle.additional-endpoints value                                    ($OP_BATCHER_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.block-size-lower-limit value (default: 2000)                    ($OP_BATCHER_THROTTLE_BLOCK_SIZE_LOWER_LIMIT)
          The limit on the DA size of blocks when we are at maximum throttle intensity
          (linear and quadratic controllers only). 0 means no limits will ever be applied,
          so consider 1 the smallest effective limit.

    --throttle.block-size-upper-limit value (default: 130000)                  ($OP_BATCHER_THROTTLE_BLOCK_SIZE_UPPER_LIMIT)
          The limit on the DA size of blocks when we are at 0 throttle intensity (applied
          when throttling is inactive)

    --throttle.controller-type value    (default: "quadratic")             ($OP_BATCHER_THROTTLE_CONTROLLER_TYPE)
          Type of throttle controller to use: 'step', 'linear', 'quadratic' (default) or
          'pid' (EXPERIMENTAL - use with caution)

    --throttle.pid-integral-max value   (default: 1000)                    ($OP_BATCHER_THROTTLE_PID_INTEGRAL_MAX)
          EXPERIMENTAL: PID controller maximum integral windup. Only relevant if
          --throttle-controller-type is set to 'pid'

    --throttle.pid-kd value             (default: 0.05)                    ($OP_BATCHER_THROTTLE_PID_KD)
          EXPERIMENTAL: PID controller derivative gain. Only relevant if
          --throttle-controller-type is set to 'pid'

    --throttle.pid-ki value             (default: 0.01)                    ($OP_BATCHER_THROTTLE_PID_KI)
          EXPERIMENTAL: PID controller integral gain. Only relevant if
          --throttle-controller-type is set to 'pid'

    --throttle.pid-kp value             (default: 0.33)                    ($OP_BATCHER_THROTTLE_PID_KP)
          EXPERIMENTAL: PID controller proportional gain. Only relevant if
          --throttle-controller-type is set to 'pid'

    --throttle.pid-output-max value     (default: 1)                       ($OP_BATCHER_THROTTLE_PID_OUTPUT_MAX)
          EXPERIMENTAL: PID controller maximum output. Only relevant if
          --throttle-controller-type is set to 'pid'

    --throttle.pid-sample-time value    (default: 2s)                      ($OP_BATCHER_THROTTLE_PID_SAMPLE_TIME)
          EXPERIMENTAL: PID controller sample time interval, default is 2s

    --throttle.tx-size-lower-limit value (default: 150)                     ($OP_BATCHER_THROTTLE_TX_SIZE_LOWER_LIMIT)
          The limit on the DA size of transactions when we are at maximum throttle
          intensity. 0 means no limits will ever be applied, so consider 1 the smallest
          effective limit.

    --throttle.tx-size-upper-limit value (default: 20000)                   ($OP_BATCHER_THROTTLE_TX_SIZE_UPPER_LIMIT)
          The limit on the DA size of transactions when we are at 0+ throttle intensity
          (limit of the intensity as it approaches 0 from positive values). Not applied
          when throttling is inactive.

    --throttle.unsafe-da-bytes-lower-threshold value (default: 3200000)                 ($OP_BATCHER_THROTTLE_UNSAFE_DA_BYTES_LOWER_THRESHOLD)
          The threshold on unsafe_da_bytes beyond which the batcher will start to throttle
          the block builder. Zero disables throttling.

    --throttle.unsafe-da-bytes-upper-threshold value (default: 12800000)                ($OP_BATCHER_THROTTLE_UNSAFE_DA_BYTES_UPPER_THRESHOLD)
          Threshold on unsafe_da_bytes at which throttling has the maximum intensity
          (linear and quadratic controllers only)

    --txmgr.already-published-custom-errs value                                    ($OP_BATCHER_TXMGR_ALREADY_PUBLISHED_CUSTOM_ERRS)
          List of custom RPC error messages that indicate that a transaction has already
          been published.

    --txmgr.cell-proof-time value       (default: 18446744073709551615)    ($OP_BATCHER_TXMGR_CELL_PROOF_TIME)
          Enables cell proofs in blob transactions for Fusaka (EIP-7742) compatibility
          from the provided unix timestamp. Should be set to the L1 Fusaka time. May be
          left blank for Ethereum Mainnet, Sepolia, Holesky, or Hoodi L1s.

    --txmgr.fee-limit-threshold value   (default: 100)                     ($OP_BATCHER_TXMGR_FEE_LIMIT_THRESHOLD)
          The minimum threshold (in GWei) at which fee bumping starts to be capped. Allows
          arbitrary fee bumps below this threshold.

    --txmgr.max-basefee value           (default: 0)                       ($OP_BATCHER_TXMGR_MAX_BASEFEE)
          Enforces a maximum base fee (in GWei) to assume when determining tx fees,
          `TxMgr` returns an error when exceeded. Disabled by default.

    --txmgr.max-retries value           (default: 10)                      ($OP_BATCHER_TXMGR_MAX_RETRIES)
          Maximum number of times to resubmit a transaction to L1 on a transient error.
          Set to 0 to disable retries.

    --txmgr.max-tip-cap value           (default: 0)                       ($OP_BATCHER_TXMGR_MAX_TIP_CAP)
          Enforces a maximum tip cap (in GWei) to use when determining tx fees, `TxMgr`
          returns an error when exceeded. Disabled by default.

    --txmgr.min-basefee value           (default: 1)                       ($OP_BATCHER_TXMGR_MIN_BASEFEE)
          Enforces a minimum base fee (in GWei) to assume when determining tx fees. 1 GWei
          by default.

    --txmgr.min-tip-cap value           (default: 1)                       ($OP_BATCHER_TXMGR_MIN_TIP_CAP)
          Enforces a minimum tip cap (in GWei) to use when determining tx fees. 1 GWei by
          default.

    --txmgr.not-in-mempool-timeout value (default: 2m0s)                    ($OP_BATCHER_TXMGR_TX_NOT_IN_MEMPOOL_TIMEOUT)
          Timeout for aborting a tx send if the tx does not make it to the mempool.

    --txmgr.rebroadcast-interval value  (default: 12s)                     ($OP_BATCHER_TXMGR_REBROADCAST_INTERVAL)
          Interval at which a published transaction will be rebroadcasted if it has not
          yet been mined. Should be less than ResubmissionTimeout to have an effect.

    --txmgr.receipt-query-interval value (default: 12s)                     ($OP_BATCHER_TXMGR_RECEIPT_QUERY_INTERVAL)
          Frequency to poll for receipts

    --txmgr.retry-interval value        (default: 1s)                      ($OP_BATCHER_TXMGR_RETRY_INTERVAL)
          Duration we will wait before resubmitting a transaction to L1 on a transient
          error. Values <= 0 will result in retrying immediately. Should be less than
          ResubmissionTimeout to have an effect.

    --txmgr.send-timeout value          (default: 0s)                      ($OP_BATCHER_TXMGR_TX_SEND_TIMEOUT)
          Timeout for sending transactions. If 0 it is disabled.

    --wait-node-sync                    (default: false)                   ($OP_BATCHER_WAIT_NODE_SYNC)
          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.

   MISC


    --help, -h                          (default: false)
          show help

    --version, -v                       (default: false)
          print the version

Seems like a much easier to maintain strategy to me.

[sbvegan]

Agreed, I like this approach it's similar to how geth's docs are. What we lose is the logical grouping of config parameters because it defaults to an alphabetical ordering. Fwiw, the mintlify tab component goes:

<Tabs>
  <Tab title="tab a">
    tab a content 
  </Tab>
  <Tab title="tab b">
    tab b content
  </Tab>
</Tabs>

source: https://www.mintlify.com/docs/components/tabs

[sbvegan]

I suppose we could change the batcher help output to group the related options and then just copy and past the --help output. I think that would be nice

[geoknee]

Yeah I realise I used a different syntax to the surrounding <Tabs/> stuff, but then I checked the deployment preview and it seems none of the others render either.

[geoknee]

I'll see if I can fix all of them.

[geoknee]

Done. I like the idea of sprucing up the actual help output and using that in the docs. But perhaps we tackle that in a follow up. I think for now this PR at least brings things up to date with the existing style.

[sbvegan]

thanks for the PR george! I like your idea of making this page easier to maintain and I think we should jam on how we can do that. It would be nice if we could even automate PRs when new batcher releases are cut