docs: tw568-arbitrum-chain-feature-config-structure

[pete-vielhaber]

• Added structure for Arbitrum chains -> Features
  • Common:
    • Configure AEP
      • configure aep fees
    • Data Availability
      • choose alt-da
      • choose anytrust
      • choose rollup
    • Gas and fees
      • choose custom gas token
      • choose fee rebates
      • choose native eth
    • MEV
      • choose timeboost
    • UX
      • choose fast withdrawals
    • Validation and Security
      • choose bold
      • choose challenge period
      • choose permissioned validators
  • Advanced
    • choose arbos version
    • choose chain precompiles
    • choose custom behavior
    • choose custom delay inbox finality

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
arbitrum-docs	Ready	Preview	Nov 20, 2025 8:00pm

[anegg0]

I added minor suggestions.

[anegg0]

Most titles aren't sentence cased

[anegg0]

Suggested change

This configuration configures the sequencer to release Delayed Inbox messages earlier, prioritizing speed over maximum security. For instance, in a default setup, a deposit from Ethereum to an L3 (via L2 settlement) waits for L1 to finalize the L2's batch posting. Enabling L2-only finality skips this, releasing after L2 confirmations (e.g., when a DACert posts on Nova). Further reducing the finalize-distance minimizes L2 waits, allowing near-instant execution but exposing the chain to parent re-orgs if unconfirmed blocks revert. It's ideal for low-latency apps but requires monitoring for re-org events.

This configuration sets up the sequencer to release Delayed Inbox messages earlier, prioritizing speed over maximum security. For instance, in a default setup, a deposit from Ethereum to an L3 (via L2 settlement) waits for L1 to finalize the L2's batch posting. Enabling L2-only finality skips this, releasing after L2 confirmations (e.g., when a DACert posts on Nova). Further reducing the finalize-distance minimizes L2 waits, allowing near-instant execution but exposing the chain to parent re-orgs if unconfirmed blocks revert. It's ideal for low-latency apps but requires monitoring for re-org events.

[anegg0]

Suggested change

	<VanillaAdmonition type="note">
	AEP configuration is not a core chain parameter like gas tokens but an advanced economic setup for revenue-sharing, applicable only to AEP-licensed chains (i.e., those not settling directly to Arbitrum One or Nova without special approval).
	</VanillaAdmonition>

[anegg0]

Suggested change

	import { VanillaAdmonition } from '@site/src/components/VanillaAdmonition/';

[anegg0]

Suggested change

	The configuration ensures compliance with the AEP terms, streamlines reporting, and avoids manual transfers, while allowing chains to retain 90% of profits. It's not a core chain parameter like gas tokens but an advanced economic setup for revenue-sharing, applicable only to AEP-licensed chains (i.e., those not settling directly to Arbitrum One or Nova without special approval).
	The configuration ensures compliance with the AEP terms, streamlines reporting, and avoids manual transfers, while allowing chains to retain 90% of profits.

[Jason-W123]

Suggested change

	- **Customize Gas Usage**: Adjust or implement gas costs for methods (e.g., burn 300 gas instead of 700 for a balance query) to optimize efficiency or prevent DoS attacks.
	- **Customize Gas Usage**: Adjust or implement gas costs for methods (e.g., cost 300 gas instead of 700 for a balance query) to optimize efficiency or prevent DoS attacks.

[Jason-W123]

We can add a comment here that all modification to precompiles should consider arbos version control or it may cause chain fork. And ask them to check https://docs.arbitrum.io/launch-arbitrum-chain/customize-your-chain/customize-arbos#where-should-i-insert-arbos-upgrade-related-code

[Jason-W123]

This page based on sequencer is well-behavior and not consider if seq censor user's tx, do you think we need to add this or not?

[anegg0]

Suggested change

	- **Data Availability (DA) in Arbitrum**: DA ensures transaction data is accessible for verification, fraud proofs, and maintaining security in optimistic rollups. Without reliable DA, users couldn't independently validate the chain's state.
	- **Data Availability (DA) in Arbitrum**: DA ensures transaction data is accessible for verification, fraud proofs, and maintaining security in optimistic Rollups. Without reliable DA, users couldn't independently validate the chain's state.

[anegg0]

Suggested change

	title: 'Why choose to use rollup for data availability on your Arbitrum chain'
	title: 'Why choose to use Rollup for data availability on your Arbitrum chain'

[anegg0]

Lots of really good content. I added some suggestions and questions.

[anegg0]

Suggested change

	description: 'Learn about data availability using rollups and the pros and cons of choosing to use it for DA on your chain.'
	description: 'Learn about data availability using Rollups and the pros and cons of choosing to use it for DA on your chain.'

[anegg0]

Suggested change

	Choosing a rollup refers to selecting the Arbitrum Rollup protocol for a chain's data availability (DA) mechanism. This choice is relevant when deploying custom chains or configuring Arbitrum-based systems.
	The rollup option prioritizes security and decentralization over cost efficiency. It's ideal for applications needing Ethereum's ironclad guarantees, such as high-value DeFi protocols or where users demand minimal trust in third parties. In contrast, opting out of Rollup (e.g., for AnyTrust) is better for high-throughput, low-cost use cases like gaming or social apps, where slight trade-offs in trust are acceptable for better performance.
	This flexibility allows developers to tailor chains to specific needs while building on Arbitrum's optimistic execution framework.
	Choosing a Rollup refers to selecting the Arbitrum Rollup protocol for a chain's data availability (DA) mechanism. This choice is relevant when deploying custom chains or configuring Arbitrum-based systems.
	The Rollup option prioritizes security and decentralization over cost efficiency. It's ideal for applications that require Ethereum's ironclad guarantees, such as high-value DeFi protocols or those where users demand minimal trust in third parties. In contrast, opting out of Rollup (e.g., for AnyTrust) is better for high-throughput, low-cost use cases like gaming or social apps, where slight trade-offs in trust are acceptable for better performance.
	This flexibility allows developers to tailor chains to specific needs while building on Arbitrum's optimistic execution framework.

[anegg0]

Suggested change

	- **Data Availability (DA) in Rollups**: DA ensures that all transaction data will be posted to parent chain for verification, fraud proofs, and security. In optimistic rollups like Arbitrum, this is critical to allow challengers to dispute invalid state transitions.
	- **Data Availability (DA) in Rollups**: DA ensures that all transaction data will be posted to parent chain for verification, fraud proofs, and security. In optimistic Rollups like Arbitrum, this is critical to allow challengers to dispute invalid state transitions.

[anegg0]

Suggested change

	This option prioritizes straightforward integration with Ethereum's ecosystem, avoiding complexities associated with custom tokens. It's ideal for chains where `ETH` is naturally used or where minimal operational overhead is desired, such as general-purpose rollups or those focused on DeFi interoperability with Ethereum.
	This option prioritizes straightforward integration with Ethereum's ecosystem, avoiding complexities associated with custom tokens. It's ideal for chains where `ETH` is naturally used or where minimal operational overhead is desired, such as general-purpose Rollups or those focused on DeFi interoperability with Ethereum.

[anegg0]

Suggested change

Enabling Timeboost refers to activating a novel transaction ordering policy that modifies the default first-come-first-served (FCFS) mechanism to allow chain owners to capture a portion of Maximum Extractable Value (MEV) through timed auctions. This protocol introduces an "express lane" where auction winners gain a temporary time advantage (default 200ms) for submitting transactions, enabling them to potentially extract MEV (e.g., arbitrage or liquidations) more efficiently, while proceeds from the auction flow to the chain owner or designated beneficiary. Timeboost is designed to reduce latency-based spam from MEV searchers (who might otherwise invest in hardware for speed advantages) and preserve user protections against harmful MEV, such as frontrunning or sandwich attacks, by maintaining a private mempool and not granting reordering rights. It does not create new MEV types but adjusts how existing MEV is accessed and monetized.

Enabling Timeboost refers to activating a novel transaction ordering policy that modifies Arbitrum's default first-come-first-served (FCFS) mechanism to allow chain owners to capture a portion of Maximum Extractable Value (MEV) through timed auctions. This protocol introduces an "express lane" where auction winners gain a temporary time advantage (default 200ms) for submitting transactions, enabling them to potentially extract MEV (e.g., arbitrage or liquidations) more efficiently, while proceeds from the auction flow to the chain owner or designated beneficiary. Timeboost is designed to reduce latency-based spam from MEV searchers (who might otherwise invest in hardware for speed advantages) and preserve user protections against harmful MEV, such as frontrunning or sandwich attacks, by maintaining a private mempool and not granting reordering rights. It does not create new MEV types but adjusts how existing MEV is accessed and monetized.

[anegg0]

Suggested change

- **Validation in Arbitrum**: In optimistic rollups like Arbitrum, validators (sequencers or stakers) post assertions about the chain's state (e.g., block hashes, history commitments as Merkle roots, batch numbers, and inbox message counts) to the parent chain. These assertions can be challenged during a fixed window (typically 6.4 days on Ethereum) if suspected invalid, leading to interactive fraud proofs verified onchain via a WASM VM.

- **Validation in Arbitrum**: In optimistic Rollups like Arbitrum, validators (sequencers or stakers) post assertions about the chain's state (e.g., block hashes, history commitments as Merkle roots, batch numbers, and inbox message counts) to the parent chain. These assertions can be challenged during a fixed window (typically 6.4 days on Ethereum) if they are suspected to be invalid, leading to interactive fraud proofs verified onchain via a WASM VM.

[anegg0]

Suggested change

This period is a core security parameter in optimistic rollups, ensuring time for validators to detect and challenge invalid states, after which unchallenged assertions achieve finality, enabling secure withdrawals. Configuration is done during deployment or post-deployment by the chain owner, allowing trade-offs between security (longer periods) and speed (shorter periods). It's composed of two main parameters: the primary challenge period (`confirmPeriodBlocks`) and an extra buffer (`extraChallengeTimeBlocks`).

This period is a core security parameter in optimistic Rollups, ensuring time for validators to detect and challenge invalid states, after which unchallenged assertions achieve finality, enabling secure withdrawals. Configuration is done during deployment or post-deployment by the chain owner, allowing trade-offs between security (longer periods) and speed (shorter periods). It's composed of two main parameters: the primary challenge period (`confirmPeriodBlocks`) and an extra buffer (`extraChallengeTimeBlocks`).

[anegg0]

The title is about choosing one's Arbos version, but the content is mostly about customizing Arbos.

[anegg0]

Suggested change

Customizing the ArbOS version refers to modifying the Nitro codebase to introduce a new, version-controlled iteration of ArbOS (Arbitrum's operating system-like layer) that activates custom behaviors, features, or state changes in a way that maintains backward compatibility and determinism for fraud proofs. This is an advanced customization primarily for live chains, allowing developers to extend or alter the State Transition Function (STF)—the core logic for block production and state updates—while ensuring safe, non-disruptive upgrades. Unlike standard upgrades (e.g., to canonical versions like ArbOS 20 "Atlas"), customization involves creating intermediate or project-specific versions (e.g., ArbOS 32 as a fork of 31) to incorporate bespoke elements like new precompiles, EVM opcodes, or state variables, without conflicting with official releases. It's recommended for teams with expertise or partners (e.g., Rollup-as-a-Service providers), as it requires audits, maintenance, and careful handling to avoid issues like chain re-orgs or failed fraud proofs.

Customizing the ArbOS version involves modifying the Nitro codebase to introduce a new, version-controlled iteration of ArbOS (Arbitrum's operating system-like layer) that activates custom behaviors, features, or state changes while maintaining backward compatibility and determinism for fraud proofs. This is an advanced customization primarily for live chains, allowing developers to extend or alter the State Transition Function (STF)—the core logic for block production and state updates—while ensuring safe, non-disruptive upgrades. Unlike standard upgrades (e.g., to canonical versions like ArbOS 20 "Atlas"), customization involves creating intermediate or project-specific versions (e.g., ArbOS 32, a fork of 31) to incorporate bespoke elements such as new precompiles, EVM opcodes, or state variables, without conflicting with official releases. It's recommended for teams with expertise or partners (e.g., Rollup-as-a-Service providers), as it requires audits, maintenance, and careful handling to avoid issues like chain re-orgs or failed fraud proofs.

[anegg0]

Suggested change

- **ArbOS**: The hypervisor-like layer in Nitro that manages the chain's execution environment, including STF, precompiles, state, and upgrades. Versions are numbered (e.g., starting from 20 in increments of 10 for canonical releases like "Atlas"), with naming after planetary moons (e.g., "Atlas" for 20, "Bianca" for 30). Custom versions can use intermediates (e.g., 21-29) for project-specific forks.

- **ArbOS**: The hypervisor-like layer in Nitro that manages the chain's execution environment, including STF, precompiles, state, and upgrades. Versions are numbered (e.g., starting from 20 in increments of 10 for canonical releases like "Atlas"), with names taken from planetary moons (e.g., "Atlas" for 20, "Bianca" for 30). Custom versions can use intermediates (e.g., 21-29) for project-specific forks.

[Jason-W123]

The configs below mixes with bold-only config and pre-bold only config, should we mention them?

[Jason-W123]

Suggested change

Chain owners add/remove validators from the allowlist using tools like the Orbit SDK or precompiles, ensuring only trusted parties (e.g., the project's team or selected partners) can validate. For validation, this limits who can defend against invalid assertions, requiring the allowlisted group to monitor and respond actively. Disputes follow the legacy protocol, potentially leading to sequential challenges without time bounds. Security is maintained through fraud proofs but depends on the allowlist's honesty and availability—e.g., if validators collude or go offline, the chain could stall or face unaddressed fraud.

Chain owners add/remove validators from the whitelist using tools like the Orbit SDK or precompiles, ensuring only trusted parties (e.g., the project's team or selected partners) can validate. For validation, this limits who can defend against invalid assertions, requiring the allowlisted group to monitor and respond actively. Disputes follow the legacy protocol, potentially leading to sequential challenges without time bounds. Security is maintained through fraud proofs but depends on the allowlist's honesty and availability—e.g., if validators collude or go offline, the chain could stall or face unaddressed fraud.

Allowlist is used on inbox component, we can might better say whitelist here

[Jason-W123]

Suggested change

	If allowlisted validators were to go offline, after a period, anyone could remove the validator allowlist and the chain would then become permissionless.
	If whitelisted validators were to go offline, after a period, anyone could remove the validator allowlist and the chain would then become permissionless.

[Jason-W123]

Suggested change

	- **Permissioned Validators**: Participation is restricted to a whitelist managed by the chain owner (via the ArbOwner precompile or DAO governance). Only these entities can stake bonds, post assertions, or engage in disputes. This setup uses the pre-BoLD fraud proof system, where challenges are handled in a 1-vs-1 tournament style without parallel resolution.
	- **Permissioned Validators**: Participation is restricted to a whitelist managed by the chain owner (via the rollupAdmin contract or DAO governance). Only these entities can stake bonds, post assertions, or engage in disputes. This setup uses the pre-BoLD fraud proof system, where challenges are handled in a 1-vs-1 tournament style without parallel resolution.

ArbOwner precompile can't be used to set validator whitelist

[Jason-W123]

Suggested change

	BoLD allows is configurable to include an allowlist of validators, instead of the default of permissionless.
	BoLD allows is configurable to include an whitelist of validators, instead of the default of permissionless.