docs: tw787 - #3468
Open
pete-vielhaber wants to merge 4 commits into
Open
Conversation
…ationship Expand the Sequencer timing adjustments page with concept + reference coverage of the SequencerInbox maxTimeVariation setting: what each of the four fields (delayBlocks, futureBlocks, delaySeconds, futureSeconds) guards, how the window is recorded on the parent chain but enforced by clamping in the STF, parent-chain dependent defaults, and the impact of changing them. Add a dedicated section on the batch poster --node.batch-poster.reorg-resistance-margin flag, the =0 bypass, and its child-chain reorg risk profile. Correct the stale defaults in the parameter table. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The SDK selects the 2s parentBlockTime only for Base and Base Sepolia by chain ID, not for OP-stack parents generically. Update the Default values table and callout to say Base / Base Sepolia -> 2s and all other parents -> 12s, matching the shipped getParentChainBlockTime logic. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Jason-W123
reviewed
Jul 22, 2026
anegg0
reviewed
Jul 23, 2026
| | [Timeboost](/how-arbitrum-works/timeboost/gentle-introduction.mdx) non-express delay | Node (`execution.sequencer.timeboost`) | 200ms | In node config: `"execution": { "sequencer": { "timeboost": { "non-express-delay-msec": 300 } } }` | Larger delay for more advantage/revenue for <a data-quicklook-from="express-lane">Express Lane</a> winner. Increases latency for regular transactions. | | ||
| | Parameter | Location | Default | How to configure | Why adjust | | ||
| | ------------------------------------------------------------------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | Delayed sequencer finalize distance | Node (`node.delayed-sequencer`) | Higher (e.g., waits for full <a data-quicklook-from="parent-chain">parent chain</a> finality) | CLI: `--node.delayed-sequencer.finalize-distance=1` and enable: `--node.delayed-sequencer.enable=true` and disable: `node.delayed-sequencer.use-merge-finality=false` | Lower value for near instant deposits (~seconds instead of minutes). Trade-off: ⚠️ **DANGER** ⚠️ Risk of reorg on parent chain. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Delayed sequencer finalize distance | Node (`node.delayed-sequencer`) | Higher (e.g., waits for full <a data-quicklook-from="parent-chain">parent chain</a> finality) | CLI: `--node.delayed-sequencer.finalize-distance=1` and enable: `--node.delayed-sequencer.enable=true` and disable: `node.delayed-sequencer.use-merge-finality=false` | Lower value for near instant deposits (~seconds instead of minutes). Trade-off: ⚠️ **DANGER** ⚠️ Risk of reorg on parent chain. | | |
| | Delayed sequencer finalize distance | Node (`node.delayed-sequencer`) | Higher (e.g., waits for full <a data-quicklook-from="parent-chain">parent chain</a> finality) | CLI: `--node.delayed-sequencer.finalize-distance=1` and enable: `--node.delayed-sequencer.enable=true` and disable: `node.delayed-sequencer.use-merge-finality=false` | Lower value for near instant deposits (~seconds instead of minutes). Trade-off: ⚠️ **DANGER** ⚠️ Risk of <a data-quicklook-from="reorg">reorg</a> on parent chain. | |
| | Parameter | Location | Default | How to configure | Why adjust | | ||
| | ------------------------------------------------------------------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | Delayed sequencer finalize distance | Node (`node.delayed-sequencer`) | Higher (e.g., waits for full <a data-quicklook-from="parent-chain">parent chain</a> finality) | CLI: `--node.delayed-sequencer.finalize-distance=1` and enable: `--node.delayed-sequencer.enable=true` and disable: `node.delayed-sequencer.use-merge-finality=false` | Lower value for near instant deposits (~seconds instead of minutes). Trade-off: ⚠️ **DANGER** ⚠️ Risk of reorg on parent chain. | | ||
| | <a data-quicklook-from="sequencer-inbox">Sequencer Inbox</a> max time variation | Chain deployment (`sequencerInboxMaxTimeVariation`) | Parent-chain dependent — see [Default values](#default-values) | In Chain SDK config struct or `chainConfig` JSON during deployment, or later via `SequencerInbox.setMaxTimeVariation`. See [Understanding `maxTimeVariation`](#understanding-maxtimevariation). | Bounds how far a message's claimed parent-chain block/time may sit from the block the batch lands in, and sets the force-inclusion wait. See the sections below before changing. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | <a data-quicklook-from="sequencer-inbox">Sequencer Inbox</a> max time variation | Chain deployment (`sequencerInboxMaxTimeVariation`) | Parent-chain dependent — see [Default values](#default-values) | In Chain SDK config struct or `chainConfig` JSON during deployment, or later via `SequencerInbox.setMaxTimeVariation`. See [Understanding `maxTimeVariation`](#understanding-maxtimevariation). | Bounds how far a message's claimed parent-chain block/time may sit from the block the batch lands in, and sets the force-inclusion wait. See the sections below before changing. | | |
| | <a data-quicklook-from="sequencer-inbox">Sequencer Inbox</a> max time variation | Chain deployment (`sequencerInboxMaxTimeVariation`) | Parent-chain dependent — see [Default values](#default-values) | In Chain SDK config struct or `chainConfig` JSON during deployment, or later via `SequencerInbox.setMaxTimeVariation`. See [Understanding `maxTimeVariation`](#understanding-maxtimevariation). | Bounds how far a message's claimed parent-chain block/time may sit from the block the <a data-quicklook-from="batch">batch</a> lands in, and sets the force-inclusion wait. See the sections below before changing. | |
| 3. **Test changes** on a devnet or testnet first—monitor TPS, state growth, posting costs, and deposit latency. | ||
| 4. **Test changes** on a devnet or testnet first—monitor TPS, state growth, posting costs, and deposit latency. | ||
|
|
||
| For a full list of flags, run `nitro-node --help`. Refer to Arbitrum Docs sections on [Running a Sequencer Node](/run-arbitrum-node/sequencer/04-run-sequencer-node.mdx) and [How to configure your Arbitrum chain's node using the Chain SDK](/launch-arbitrum-chain/deploy/configure-node.mdx) for your exact version. If using Timeboost or advanced features, additional setup (e.g., <a data-quicklook-from="auction-contract">Auction Contract</a>) is needed. |
Contributor
There was a problem hiding this comment.
Suggested change
| For a full list of flags, run `nitro-node --help`. Refer to Arbitrum Docs sections on [Running a Sequencer Node](/run-arbitrum-node/sequencer/04-run-sequencer-node.mdx) and [How to configure your Arbitrum chain's node using the Chain SDK](/launch-arbitrum-chain/deploy/configure-node.mdx) for your exact version. If using Timeboost or advanced features, additional setup (e.g., <a data-quicklook-from="auction-contract">Auction Contract</a>) is needed. | |
| For a full list of flags, run `nitro-node --help`. Refer to Arbitrum Docs sections on [Running a Sequencer Node](/run-arbitrum-node/sequencer/04-run-sequencer-node.mdx) and [How to configure your Arbitrum chain's node using the Chain SDK](/launch-arbitrum-chain/deploy/configure-node.mdx) for your exact version. If using <a data-quicklook-from="timeboost">Timeboost</a> or advanced features, additional setup (e.g., <a data-quicklook-from="auction-contract">Auction Contract</a>) is needed. |
|
|
||
| The four fields define a **two-sided window** around the current parent-chain block and time: | ||
|
|
||
| - `delayBlocks` and `delaySeconds` bound the **past** edge—how old a message's claimed block or timestamp may be. |
Contributor
There was a problem hiding this comment.
Suggested change
| - `delayBlocks` and `delaySeconds` bound the **past** edge—how old a message's claimed block or timestamp may be. | |
| - `delayBlocks` and `delaySeconds` bound the **past** <a data-quicklook-from="edge">edge</a>—how old a message's claimed block or timestamp may be. |
|
|
||
| Understanding what this setting guards requires knowing _where_ it is enforced, which is not where most people expect. | ||
|
|
||
| When a batch is posted, the Sequencer Inbox computes the window from the **current** parent-chain block and time at the moment the batch lands: |
Contributor
There was a problem hiding this comment.
Suggested change
| When a batch is posted, the Sequencer Inbox computes the window from the **current** parent-chain block and time at the moment the batch lands: | |
| When a batch is posted, the <a data-quicklook-from="sequencer-inbox">Sequencer Inbox</a> computes the window from the **current** parent-chain block and time at the moment the batch lands: |
|
|
||
| <VanillaAdmonition type="warning" title="Out-of-window messages are clamped, not rejected"> | ||
|
|
||
| Because out-of-window messages are silently clamped rather than rejected, a message can be assigned a different parent-chain block or timestamp than the Sequencer originally computed locally. When the locally executed chain and the chain derived from onchain data disagree, the result is a child-chain reorg. `maxTimeVariation` therefore does not guard by blocking bad batches; it defines the window inside which the Sequencer and batch poster must keep every message to avoid such reorgs. |
Contributor
There was a problem hiding this comment.
Suggested change
| Because out-of-window messages are silently clamped rather than rejected, a message can be assigned a different parent-chain block or timestamp than the Sequencer originally computed locally. When the locally executed chain and the chain derived from onchain data disagree, the result is a child-chain reorg. `maxTimeVariation` therefore does not guard by blocking bad batches; it defines the window inside which the Sequencer and batch poster must keep every message to avoid such reorgs. | |
| Because out-of-window messages are silently clamped rather than rejected, a message can be assigned a different parent-chain block or timestamp than the Sequencer originally computed locally. When the locally executed chain and the chain derived from onchain data disagree, the result is a child-chain reorg. `maxTimeVariation` therefore does not guard by blocking bad batches; it defines the window inside which the Sequencer and <a data-quicklook-from="batch-poster">batch poster</a> must keep every message to avoid such reorgs. |
|
|
||
| **`delayBlocks` also sets the force-inclusion wait.** The same `delayBlocks` value determines how long a message submitted through the <a data-quicklook-from="delayed-inbox">Delayed Inbox</a> must wait before it can be <a data-quicklook-from="forceinclusion">force-included</a>, bypassing the Sequencer. `forceInclusion` reverts with `ForceIncludeBlockTooSoon` until `delayBlocks` parent-chain blocks have elapsed since the message was submitted. Raising `delayBlocks` therefore lengthens the Sequencer's exclusive window and delays when users can force their transactions in. The optional delay-buffer feature can shorten this window under sustained delay, but never lengthen it. | ||
|
|
||
| For more on force inclusion and the Delayed Inbox, see the [Sequencer deep dive](/how-arbitrum-works/deep-dives/sequencer.mdx). |
Contributor
There was a problem hiding this comment.
Suggested change
| For more on force inclusion and the Delayed Inbox, see the [Sequencer deep dive](/how-arbitrum-works/deep-dives/sequencer.mdx). | |
| For more on force inclusion and the <a data-quicklook-from="delayed-inbox">Delayed Inbox</a>, see the [Sequencer deep dive](/how-arbitrum-works/deep-dives/sequencer.mdx). |
anegg0
reviewed
Jul 23, 2026
| ### Reorg resistance margin | ||
|
|
||
| The reorganization resistance margin is configurable via the `--node.batch-poster.reorg-resistance-margin` parameter, which specifies a time duration (e.g., in minutes) during which the batch poster will avoid posting batches if their minimum L1 block number or timestamp is too close to the current L1 head. This margin serves as a safety buffer to prevent posting batches that reference recent L1 states, which are prone to reorganization. The default value is ten minutes (600 seconds), based on observed usage in deployments and error logs. | ||
| Reorg prevention interacts with batch posting through `maxTimeVariation` and reorg-resistance-margin. See the [Configure Sequencer timing adjustments](/launch-arbitrum-chain/chain-config/sequencer/sequencer-timing-adjustments.mdx) page for the full mechanism. |
Contributor
There was a problem hiding this comment.
Suggested change
| Reorg prevention interacts with batch posting through `maxTimeVariation` and reorg-resistance-margin. See the [Configure Sequencer timing adjustments](/launch-arbitrum-chain/chain-config/sequencer/sequencer-timing-adjustments.mdx) page for the full mechanism. | |
| Reorg prevention interacts with batch posting through `maxTimeVariation` and `reorg-resistance-margin`. See the [Configure Sequencer timing adjustments](/launch-arbitrum-chain/chain-config/sequencer/sequencer-timing-adjustments.mdx) page for the full mechanism. |
anegg0
approved these changes
Jul 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Thank you for contributing to our docs!
Please fill out the form below to ensure your doc gets quickly approved and merged.
Description
Document type
Checklist
yarn startoryarn build