From 8daf0d497de4ffed89bbbb04eff7904b08cd7546 Mon Sep 17 00:00:00 2001 From: Pete Date: Mon, 20 Oct 2025 11:48:08 -0500 Subject: [PATCH 01/61] Adding new feature content for Arbitrum chains --- .../advanced/choose-arbos-version.mdx | 52 ++++++++++++++++ .../advanced/choose-chain-precompiles.mdx | 62 +++++++++++++++++++ .../advanced/choose-custom-behavior.mdx | 53 ++++++++++++++++ .../choose-custom-delay-inbox-finality.mdx | 56 +++++++++++++++++ .../configure-aep/configure-aep-fees.mdx | 50 +++++++++++++++ .../data-availability/choose-alt-da.mdx | 45 ++++++++++++++ .../data-availability/choose-anytrust.mdx | 32 ++++++++++ .../data-availability/choose-rollup.mdx | 24 +++++++ .../gas-and-fees/choose-custom-gas-token.mdx | 46 ++++++++++++++ .../gas-and-fees/choose-fee-rebates.mdx | 59 ++++++++++++++++++ .../common/gas-and-fees/choose-native-eth.mdx | 54 ++++++++++++++++ .../features/common/mev/choose-timeboost.mdx | 53 ++++++++++++++++ .../common/ux/choose-fast-withdrawals.mdx | 59 ++++++++++++++++++ .../validation-and-security/choose-bold.mdx | 47 ++++++++++++++ .../choose-challenge-period.mdx | 55 ++++++++++++++++ .../choose-permissioned-validators.mdx | 42 +++++++++++++ 16 files changed, 789 insertions(+) create mode 100644 docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx create mode 100644 docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx create mode 100644 docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx create mode 100644 docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx create mode 100644 docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx create mode 100644 docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx create mode 100644 docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx create mode 100644 docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx create mode 100644 docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx create mode 100644 docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx create mode 100644 docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx create mode 100644 docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx create mode 100644 docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx create mode 100644 docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx create mode 100644 docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx create mode 100644 docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx new file mode 100644 index 0000000000..19bc1c1c2c --- /dev/null +++ b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx @@ -0,0 +1,52 @@ +--- +title: 'Why choose a specific ArbOS version on your Arbitrum chain' +description: 'Learn about choosing which ArbOS version to use on your chain.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +In the context of Arbitrum, particularly when deploying and managing custom layer-2 (L2) or layer-3 (L3) chains via Arbitrum Orbit, "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. + +### Key Concepts + +- **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. +- **State Transition Function (STF)**: The deterministic process for computing new states from transactions. Customizations here (e.g., new logic or states) often necessitate an ArbOS upgrade to integrate changes into the replay binary used for fraud proofs. +- **WASM Module Root**: A 32-byte hash of the STF's implementation (e.g., 0x8b104a2e80ac6165dc58b9048de12f301d70b02a0ab51396c22b4b4b802a16a4 for ArbOS 20). Customizations require updating this on the parent chain for validation compatibility. +- **Backward Compatibility**: Changes must preserve old block results; new features activate only post-upgrade via version gates (e.g., `if state.ArbOSVersion() >= targetVersion`). + +### Compatibility + +- Works with all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (BoLD/permissioned), as long as changes meet STF rules (deterministic, pure, <1s/block). +- Backward-compatible by design; WASM roots support old versions. +- For public chains like One/Nova, requires DAO governance; Orbit chains have owner discretion. + +### Pros + +- Enables precise, version-gated customizations (e.g., new STF logic) for specialized chains. +- No downtime; upgrades bundle features seamlessly. +- Supports ecosystem alignment (e.g., adopting mainnet features post-delay). + +### Cons + +- Complexity and risks (e.g., re-orgs from improper state init, proof failures). +- Requires audits/maintenance; unintended intermediate features may activate. +- No Offchain Labs review; higher costs for expertise. + +### Examples + +- **New Precompile Method**: Add `sayHi()` to ArbSys, gated by `ArbOwner.methodsByName["SayHi"].arbosVersion = 32`. +- **New Precompile**: Create ArbHi with `ArbHi.arbosVersion = 32` and method gates. +- **New State Variable**: Add `myNumber` initialized in `UpgradeArbosVersion` switch for v21: `ensure(state.SetNewMyNumber(randomNumber))`. +- **STF Logic Change**: Branch in a method: `if p.state.ArbOSVersion() >= 32 { return "hi, new version" } else { return "hi" }`. + +## How to configure + +1. **Clone and Modify Nitro**: Use a branch like v3.7.2 (`git clone --branch v3.7.2 https://github.com/OffchainLabs/nitro.git`). Edit files (e.g., precompile.go, arbosstate.go) for changes, adding version gates. +2. **Build Custom Node**: Create Docker images, extract the new WASM module root, and update it on the parent chain via `setWasmModuleRoot` on the rollup contract. +3. **Upgrade Nodes/Validators**: Update to the custom Nitro version (e.g., v2.3.1+ for ArbOS 20 base). +4. **Schedule Upgrade**: Call `scheduleArbOSUpgrade` on ArbOwner precompile with the new version and timestamp (0 for immediate). +5. **Enable Features**: Post-upgrade, configure any version-specific flags. + +This reflects Orbit's modularity but demands rigorous testing. Refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx new file mode 100644 index 0000000000..f7e3474f58 --- /dev/null +++ b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx @@ -0,0 +1,62 @@ +--- +title: 'Why choose to customize the precompiles on your Arbitrum chain' +description: 'Learn about precompiles and the pros and cons of choosing to customize them on your chain.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +Customizing your chain's precompiles refers to modifying or extending the built-in, system-level smart contract-like functions (precompiles) that provide efficient access to chain-specific operations, such as interacting with the parent chain (L1 or L2), querying state, or performing computations. Precompiles are hardcoded at specific addresses (e.g., 0x64 for `ArbSys`) and executed outside the EVM bytecode level for performance. They inherit from Ethereum's standard precompiles (e.g., for hashing or elliptic curves) while adding Arbitrum-specific ones (e.g., `ArbAddressTable` for address compression). + +Customization allows developers to add new methods, events, gas logic, or state interactions tailored to the chain's needs, such as app-specific utilities or optimizations. This flexibility is an advanced feature requiring modifications to the Nitro software stack, enabling deeper chain personalization beyond defaults like custom gas tokens or DA modes. + +## Key Concepts + +- **Precompiles in Arbitrum**: These are predefined contracts at fixed addresses that handle operations more efficiently than regular EVM code. Standard ones include ArbSys (for L1 interactions), ArbInfo (for balances and codes), and others for aggregation, retryables, or gas estimation. Customization builds on this by altering their behavior or adding new ones in the Nitro Go implementation. +- **Customization Scope**: Focuses on extending functionality without full EVM changes, such as adding utility methods (e.g., a greeting function) or integrating chain-specific state (e.g., a stored number). It doesn't alter core EVM opcodes but enhances system access. + +## Options for Customization + +There are several approaches, each building on the Nitro codebase: + +- **Add New Methods to an Existing Precompile**: Extend a built-in precompile (e.g., `ArbSys`) with additional functions. +- **Create a New Precompile**: Define a completely new precompile at a custom address (e.g., 0x011a for ArbHi) with its own methods. +- **Define a New Event**: Add events to methods for logging, making the method state-modifying and indexable for off-chain querying. +- **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. +- **Call and Modify State**: Integrate with ArbOS state by adding storage variables and methods to read/write them, allowing persistent chain-specific data. + +## Compatibility with Chain Types + +- Works with all Orbit DA modes (Rollup, AnyTrust, Alt-DA) and gas tokens (native ETH or custom), as it's a Nitro-level change. +- Compatible with BoLD or permissioned validation, but custom precompiles may require `eth_call` for view methods to avoid breaking block validation. + +## Pros + +- Enables highly tailored functionality (e.g., custom events for better logging, state for app-specific data). +- Optimizes performance and gas (e.g., cheaper queries). +- Enhances chain utility for specialized use cases like DeFi or gaming. + +## Cons + +- Requires deep expertise in Go, Solidity, and Nitro; complex setup and maintenance. +- Risks include DoS vulnerabilities without proper gas implementation, security issues without audits, and potential validation breaks. +- No official review from Offchain Labs; changes may complicate upgrades or fraud proofs. + +## Examples + +- Adding a "sayHi" method to ArbSys that returns "hi" and emits a "Hi" event. +- Creating a new ArbHi precompile with a gas-optimized balance query. +- Storing and modifying a custom state variable like "myNumber" via a new method. + +## How to configure + +Customizing requires building a modified Nitro node, as precompiles are part of the core software: + +1. **Clone and Setup Nitro**: Use branch v3.7.2 or later (`git clone --branch v3.7.2 https://github.com/OffchainLabs/nitro.git`), then initialize submodules. +2. **Edit Go Files**: Modify `/precompiles` directory (e.g., add methods to ArbSys.go), register new precompiles in precompile.go, and for state changes, update arbosstate.go with variables, offsets, and initialization. +3. **Update Solidity Interfaces**: Add corresponding methods/events to .sol files in the precompiles interface directory for dApp compatibility. +4. **Build and Run Node**: Compile a custom Docker image and run the node with your configurations (e.g., specifying parent chain URL and chain ID). Test with tools like curl for eth_call or Foundry's cast for calls/sends. +5. **Post-Launch Changes**: Use ArbOS version upgrades to apply without reorganizing the chain; follow related guides for fraud proofs. + +This advanced customization aligns with Orbit's modular design but demands careful planning and testing. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx new file mode 100644 index 0000000000..599fc2dc4f --- /dev/null +++ b/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx @@ -0,0 +1,53 @@ +--- +title: 'Why choose to customize the behavior on your Arbitrum chain' +description: 'Learn about custom behaviors and the pros and cons of choosing to customize the behavior it on your chain.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +In the context of Arbitrum, particularly when deploying custom layer-2 (L2) or layer-3 (L3) chains via Arbitrum Orbit, "customizing your chain's behavior" refers to modifying the core logic that governs how the chain processes transactions, produces blocks, and transitions states—primarily by altering the State Transition Function (STF) within the Nitro software stack. This goes beyond surface-level configurations (e.g., gas tokens or DA modes) and involves code-level changes to ArbOS (Arbitrum's operating system layer), such as adding new EVM opcodes, precompiles, or state variables, while ensuring compatibility with fraud proofs and backward compatibility. Such customizations enable highly tailored chains for specific use cases but require building custom Nitro nodes and handling upgrades carefully to avoid disruptions like chain re-orgs or invalid fraud proofs. It's an advanced feature recommended for teams with expertise or partners (e.g., Rollup-as-a-Service providers), as Offchain Labs does not review individual changes—audits and maintenance are the developer's responsibility. + +### Key Concepts + +- **State Transition Function (STF)**: The deterministic logic that computes new chain states from inputs (e.g., transactions). Customizations here affect block production, execution outcomes, or state (e.g., balances), requiring updates to fraud proofs to recognize the changes as valid. +- **ArbOS**: The operating system-like layer in Nitro that manages STF components, including precompiles, state, and upgrades. Customizations often involve versioning ArbOS to activate changes safely on live chains. +- **WASM Module Root**: A 32-byte hash representing the STF's implementation, which must be updated on the parent chain for fraud proofs to work with customizations. +- **Backward Compatibility**: Changes must not alter results for old blocks; they activate at specific ArbOS versions or timestamps to prevent re-orgs. +- **STF Requirements**: Must be deterministic, pure (no external resources), performant (<1 second per block), and state-managed only via the Ethereum trie or block headers. + +### Compatibility + +- Works with all Orbit DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (BoLD or permissioned), but STF changes must meet strict rules (e.g., no non-determinism). +- Backward-compatible by design; upgrades activate features sequentially, including all intermediate ones. +- Incompatible with external dependencies or changes that violate STF purity/performance. + +### Pros + +- Enables innovative, use-case-specific behaviors (e.g., custom rewards or opcodes) for competitive advantages. +- Supports seamless live upgrades without downtime. +- Builds on canonical releases for reliability. + +### Cons + +- High complexity; errors (e.g., in versioning) can cause re-orgs, security vulnerabilities, or proof failures. +- Requires audits, expertise, and maintenance; no official support for custom code. +- Trade-offs in performance/cost; skipping versions activates unintended features. + +### Examples + +- **Adding a New Precompile Method**: Extend ArbSys with a "sayHi" function that activates at ArbOS v32, returning different strings pre/post-upgrade. +- **New State Variable**: Add "myNumber" initialized during upgrade to v21, modifiable only post-upgrade. +- **STF Logic Change**: Modify a method to use new behavior if ArbOS version >= target, e.g., altering gas rewards for deployers. +- **Non-STF**: Adding an RPC for multi-block queries (no STF/fraud updates needed). + +## How to configure + +1. **Clone Nitro Source**: Use a specific branch (e.g., v3.7.2): `git clone --branch v3.7.2 https://github.com/OffchainLabs/nitro.git` and initialize submodules. +2. **Implement Changes**: Edit Go files (e.g., in `/precompiles` or `arbosstate.go`) for new methods, states, or logic. Add version gates (e.g., `if state.ArbOSVersion() >= targetVersion`) for compatibility. +3. **Build Custom Node**: Create Docker images (dev and production) with changes; extract and set the new WASM module root on the parent chain via contract calls. +4. **Run and Verify**: Start the node (initially without fraud proofs), test transactions, and confirm validation logs. For live upgrades, schedule ArbOS version increases. +5. **Upgrade ArbOS (for Live Chains)**: Target a new version (e.g., from v18 to v25), initializing states during the upgrade function to avoid re-orgs. + +Refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx new file mode 100644 index 0000000000..de5705ca05 --- /dev/null +++ b/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx @@ -0,0 +1,56 @@ +--- +title: 'Why choose to customize the delayed inbox finality on your Arbitrum chain' +description: 'Learn about delayed inbox finality and the pros and cons of choosing to customize it on your chain.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +Customizing the ArbOS version involves modifying the Nitro codebase to introduce a new, version-controlled iteration of ArbOS (Arbitrum's operating system-like layer). This process 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., RaaS providers), as it requires audits, maintenance, and careful handling to avoid issues like chain re-orgs or failed fraud proofs. + +### Key Concepts + +- **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 inspired by planetary moons (e.g., "Atlas" for 20, "Bianca" for 30). Custom versions can use intermediates (e.g., 21-29) for project-specific forks. +- **State Transition Function (STF)**: The deterministic process for computing new states from transactions. Customizations here (e.g., new logic or states) often necessitate an ArbOS upgrade to integrate changes into the replay binary used for fraud proofs. +- **WASM Module Root**: A 32-byte hash of the STF's implementation (e.g., `0x8b104a2e80ac6165dc58b9048de12f301d70b02a0ab51396c22b4b4b802a16a4` for ArbOS 20). Customizations require updating this on the parent chain for validation compatibility. +- **Backward compatibility**: Changes must preserve old block results; new features activate only post-upgrade via version gates (e.g., `if state.ArbOSVersion() >= targetVersion`). + +### Compatibility + +- Works with all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (BoLD/permissioned), as long as changes meet STF rules (deterministic, pure, <1s/block). +- Backward-compatible by design; WASM roots support old versions. +- For public chains like One/Nova, requires DAO governance; Orbit chains have owner discretion. + +### Pros + +- Enables precise, version-gated customizations (e.g., new STF logic) for specialized chains. +- No downtime; upgrades bundle features seamlessly. +- Supports ecosystem alignment (e.g., adopting mainnet features post-delay). + +### Cons + +- Complexity and risks (e.g., re-orgs from improper state init, proof failures). +- Requires audits/maintenance; unintended intermediate features may activate. +- No Offchain Labs review; higher costs for expertise. + +### Examples + +- **New Precompile Method**: Add `sayHi()` to ArbSys, gated by `ArbOwner.methodsByName["SayHi"].arbosVersion = 32`. +- **New Precompile**: Create ArbHi with `ArbHi.arbosVersion = 32` and method gates. +- **New State Variable**: Add `myNumber` initialized in `UpgradeArbosVersion` switch for v21: `ensure(state.SetNewMyNumber(randomNumber))`. +- **STF Logic Change**: Branch in a method: `if p.state.ArbOSVersion() >= 32 { return "hi, new version" } else { return "hi" }`. + +## How to configure + +1. **Clone and Modify Nitro**: Use a branch like v3.7.2 (`git clone --branch v3.7.2 https://github.com/OffchainLabs/nitro.git`). Edit files (e.g., precompile.go, arbosstate.go) to incorporate changes and add version gates. +2. **Build Custom Node**: Create Docker images, extract the new WASM module root, and update it on the parent chain via `setWasmModuleRoot` on the rollup contract. +3. **Upgrade Nodes/Validators**: Update to the custom Nitro version (e.g., v2.3.1+ for ArbOS 20 base). +4. **Schedule Upgrade**: Call `scheduleArbOSUpgrade` on ArbOwner precompile with the new version and timestamp (0 for immediate). +5. **Enable Features**: Post-upgrade, configure any version-specific flags. + +This feature reflects Orbit's modularity but demands rigorous testing. Refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx new file mode 100644 index 0000000000..0eb0c65ae7 --- /dev/null +++ b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx @@ -0,0 +1,50 @@ +--- +title: 'Why choose to configure AEP fees for your Arbitrum chain' +description: 'Learn about AEP fee configuration and the pros and cons of choosing to configure it.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +Configuring the AEP fees refers to setting up an optional but recommended smart contract system (the AEP fee router) to automate the calculation, collection, and transfer of the required 10% license fee on the chain's Protocol Net Revenue to the Arbitrum DAO treasury. This feature is part of the Arbitrum Expansion Program (AEP). This self-service licensing model permits developers to use Arbitrum's technology stack (e.g., Nitro) for custom chains in exchange for sharing revenue. + +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). + +## Key Concepts + +- **Arbitrum Expansion Program (AEP)**: A licensing framework for deploying Orbit chains on any blockchain that derives security from Ethereum (e.g., settling to Ethereum mainnet, other L2s, or even non-Ethereum chains with DAO approval). It requires no upfront permission but mandates paying 10% of net revenue (8% to the DAO treasury, 2% to ecosystem growth funds) on chains generating over $60,000 USD annually in profit. This framework applies to modifications of the stack, including custom DA, gas tokens, or governance. +- **Protocol Net Revenue**: The chain's profit, calculated as total fees collected (e.g., from gas, surplus, or custom mechanisms) minus Settlement Costs. Settlement Costs include gas fees for posting data to the parent chain (e.g., Ethereum calldata or blobs) and any other direct operational expenses like batch posting. Only positive net revenue triggers the 10% fee; losses or zero profit incur no payment. +- **AEP Fee Router**: A set of deployable contracts (e.g., `RewardDistributor` or custom distributors) that automatically routes the 10% share. It integrates with the chain's fee collectors (e.g., for surplus fees) and handles cross-chain transfers (e.g., bridging to Ethereum then to a DAO-controlled address on Arbitrum One). + +## Compatibility + +- **DA Modes**: Applies across Rollup, AnyTrust, and Alt-DA, as settlement costs vary by mode (e.g., lower in Alt-DA). +- **Gas Tokens**: For custom ERC-20s, requires conversion mechanisms; native `ETH` simplifies bridging. +- **Validation**: No impact on BoLD or permissioned setups. + +## Pros + +- Automates compliance, reducing administrative burden and errors in manual calculations. +- Contributes to Arbitrum ecosystem growth (e.g., funding grants), potentially increasing chain visibility and integrations. +- Flexible for revenue models; only applies to profits, not gross fees. + +## Cons + +- Reduces net profits by 10%, which could impact low-margin chains (though waived below $60K USD/year). +- Adds deployment and monitoring complexity, especially for cross-chain transfers. +- Reporting requirements may involve audits or transparency, with non-compliance risking license revocation. + +## Examples + +- **DeFi-Focused Orbit Chain**: Configures the router to route 10% of surplus fees (after Ethereum posting costs) to the DAO, using a custom gas token with oracle-based pricing for accurate `ETH` conversion. +- **Gaming L3 Chain**: Low-revenue setups might skip full configuration initially but enable it upon profitability, bridging fees quarterly. + +## How to configure + +1. **Calculate Net Revenue**: Use tools or scripts to track total fees minus settlement costs (e.g., via on-chain queries or off-chain monitoring). For custom tokens, deploy a pricer contract to value fees in `ETH` equivalents. +2. **Deploy Fee Router**: Use the Orbit SDK script (e.g., `aep-fee-router.ts`) to deploy contracts like RewardDistributor on your chain. Set it as a fee collector (e.g., for surplus fees via `ArbOwner` precompile). +3. **Route and Bridge Fees**: Configure the router to send the 10% share to Ethereum (e.g., via native bridges), then deposit to the DAO address on Arbitrum One. Use functions like `flushBeneficiaryBalance` for periodic transfers. +4. **Report Fees**: Submit quarterly reports to the Arbitrum Foundation, including calculations and proofs of payment, to maintain license compliance. + +This setup reflects Arbitrum's collaborative model, ensuring custom chains contribute back while benefiting from the ecosystem. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx new file mode 100644 index 0000000000..f1b0fd0075 --- /dev/null +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx @@ -0,0 +1,45 @@ +--- +title: 'Why choose to use alt-DA for data availability on your Arbitrum chain' +description: 'Learn about alt-DA and the pros and cons of choosing to use it for DA on your chain.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +Choosing alternative data availability (Alt-DA) refers to configuring the chain to use a third-party data availability layer instead of Arbitrum's native options. This feature allows developers to post transaction batch data to external DA providers for storage and accessibility, rather than relying solely on Ethereum (L1) or Arbitrum's built-in mechanisms. Alt-DA integrations expand the flexibility of the Arbitrum Nitro stack, enabling optimized trade-offs in cost, scalability, and security. + +Selecting Alt-DA means integrating an external provider into your Orbit chain's configuration, often via modifications to the Nitro software stack. Developers can also set fallback preferences (e.g., try Alt-DA first, then AnyTrust, then Ethereum) to ensure resilience if the primary DA fails. This choice is ideal for applications prioritizing ultra-low fees and massive scalability, such as gaming, social, or data-intensive dApps, where the cost of posting to Ethereum would be prohibitive. + +## Key Concepts + +- **Data Availability (DA) in Arbitrum Orbit**: DA ensures that transaction data is stored and retrievable for verification, fraud proofs, and node synchronization in optimistic rollups. Arbitrum chains are customizable with different DA setups to suit specific needs, such as high-throughput apps or cost-sensitive projects. + - **Alt-DA**: Posting transaction batches post to an external, modular DA network (e.g., specialized blockchains designed for DA). Only proofs of availability (e.g., commitments or certificates) post to the parent chain. This process decouples DA from settlement, allowing for specialized optimization. + +## How It Differs: + +- From **Rollup**: Alt-DA moves data off Ethereum entirely, avoiding L1 gas costs but potentially sacrificing some decentralization if the external layer has different security properties (e.g., Celestia uses data availability sampling for efficiency). +- From **AnyTrust**: While both are off-chain, AnyTrust uses Arbitrum's own DAC (permissioned and integrated), whereas Alt-DA leverages independent networks with their own consensus and incentives, offering more modularity but requiring additional setup and trust in the provider's model. + +## Pros + +- Dramatically lower costs (e.g., up to orders of magnitude cheaper than L1 posting) and higher throughput. +- Modular design allows specialization (e.g., Celestia focuses solely on DA for efficiency). +- Fallback mechanisms enhance reliability. + +## Cons + +- Introduces new trust assumptions based on the provider (e.g., reliance on the external layer's validators or sampling protocols). +- Potential for integration complexity, including custom code and bridges for proofs. +- May have varying uptime or finality compared to native options. + +## Examples of Alt-DA Providers + +Arbitrum Orbit supports integrations with several Alt-DA solutions, including: + +- **Celestia**: A modular DA blockchain using data availability sampling for lightweight verification. +- **Avail**: Focuses on high-throughput DA with erasure coding. +- **EigenDA (via EigenLayer)**: Leverages restaking for secure, decentralized DA. +- For a list of Alt-DA providers, refer to the [Third-party providers page](launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#data-availability-providers-for-anytrust-chains) + +This option reflects the growing trend toward modular blockchain architectures, where DA handling is separate to scale ecosystems like Arbitrum without compromising core security. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx new file mode 100644 index 0000000000..60dd4832be --- /dev/null +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx @@ -0,0 +1,32 @@ +--- +title: 'Why choose to use AnyTrust for data availability on your Arbitrum chain' +description: 'Learn about data availability using AnyTrust and the pros and cons of choosing to use it for DA on your chain.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +Choosing AnyTrust mode refers to selecting the AnyTrust protocol as the data availability (DA) mechanism for a chain, such as when deploying custom chains via Arbitrum Orbit. AnyTrust is an alternative to the pure Rollup mode, prioritizing cost efficiency and performance over maximum decentralization. + +Opting for AnyTrust means configuring your Arbitrum-based chain to use this DA approach for reduced operational costs and better scalability, while accepting a slight trade-off in trust-minimization compared to posting all data directly to L1 (as in Rollup mode). + +It's ideal for use cases where ultra-low fees are a priority over Ethereum's full security guarantees, such as consumer apps or high-frequency trading platforms. Developers can set up and configure a DAC via Arbitrum's tools, including defining the committee size and keyset threshold. This flexibility allows tailoring to specific needs within the Arbitrum ecosystem, and it's compatible with other Orbit features like custom gas tokens or third-party DA integrations. + +## Key Concepts + +- **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. +- **AnyTrust Mode**: + - Transaction data is initially submitted off-chain to a permissioned group of nodes called the Data Availability Committee (DAC), typically consisting of around 20 members (though configurable). + - The DAC stores the data and signs a Data Availability Certificate (DACert), which posts to the parent chain (Ethereum L1). Full data is not posted onchain unless requested (e.g., during a challenge). + - Security relies on a "keyset" where at least two honest members are assumed to prevent data withholding—far milder than centralized assumptions but not fully trustless like Rollup mode. + +## Pros + +With up to 90% lower fees, higher throughput, and faster finality, it is suitable for high-volume, low-value applications like gaming or social dApps. + +## Cons + +Introduces a trust assumption in the DAC, which could be a vector for censorship or failure if too many members collude (though mitigated by requiring only a small honest minority). + +This option reflects the growing trend toward modular blockchain architectures, where DA handling is separate to scale ecosystems like Arbitrum without compromising core security. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx new file mode 100644 index 0000000000..2dbe42f2ef --- /dev/null +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx @@ -0,0 +1,24 @@ +--- +title: 'Why choose to use rollup for data availability on your Arbitrum chain' +description: 'Learn about data availability using rollups and the pros and cons of choosing to use it for DA on your chain.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +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. + +## Key Concepts + +- **Data Availability (DA) in Rollups**: DA ensures that all transaction data is publicly accessible for verification, fraud proofs, and security. In optimistic rollups like Arbitrum, this is critical to allow challengers to dispute invalid state transitions. +- **Arbitrum Rollup Mode**: + - All batch transaction data is posted directly to the parent chain (Ethereum L1) as calldata or blobs. + - This inherits Ethereum's full security and decentralization, with no additional trust assumptions—data is always available on-chain for anyone to access and verify. + - Example: Arbitrum One operates in this mode. + +For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx new file mode 100644 index 0000000000..fff0765b6b --- /dev/null +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx @@ -0,0 +1,46 @@ +--- +title: 'Why choose to use a custom gas token on your Arbitrum chain' +description: 'Learn about the pros and cons of choosing to use a custom gas token for your chain.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +Choosing a custom gas token refers to configuring the chain to use a specific `ERC-20` token—rather than `ETH`—as the native currency for paying transaction fees (gas costs) on your chain. This allows developers to tailor the fee structure to their project's ecosystem, such as using a stablecoin like `USDC`, a yield-bearing asset, or the project's own native token. The choice is made during chain deployment and is generally immutable afterward, integrating directly into the chain's genesis parameters. + +## Key Concepts + +- **Gas and Fees in Arbitrum**: Gas represents the computational resources required for transactions and smart contract executions. Fees are calculated as gas used multiplied by gas price, covering sequencer costs, data posting to the parent chain (e.g., Ethereum or another Arbitrum chain), and network maintenance. In standard setups (like Arbitrum One), these are paid in `ETH`. +- **Custom Gas Token**: An `ERC-20` token deployed on the parent chain is "natively bridged" to the new Orbit chain and set as the gas token. Transactions on the child chain are validated against users' balances of this token, with fees deducted accordingly. The token must meet strict requirements: standard `ERC-20` compliance (no proxies, hooks, rebasing, or transfer fees), typically 18 decimals, and transfers/approvals must not revert in edge cases. + +## How Fees Are Handled + +- **On the child chain**: Gas costs are calculated and deducted in the custom token. +- **For data posting to the parent chain**: The sequencer or batch poster collects custom tokens as revenue but must convert them to the parent's native token (e.g., `ETH`) to cover posting costs. This is managed via an exchange rate mechanism, such as a pricer contract that uses manual updates, oracles, or trade tracking. Inaccurate rates can lead to over- or under-reimbursement, impacting profitability. + +- **Compatibility with Chain Types**: + - **Rollup Mode**: Supported for L2 chains posting data to Ethereum, requiring BoLD (Bounded Liquidity Delay) enabled and a fee token pricer for exchange rates. L3 support is planned but not yet available. + - **AnyTrust Mode**: Directly supported with simpler configuration (no heavy pricer emphasis), ideal for cost-sensitive setups. + - **Alt-DA (Alternative Data Availability)**: Compatible, especially with cheaper DA providers like Celestia or EigenDA, which reduce conversion risks from token volatility. + +## Pros + +- Enhances token utility and ecosystem alignment (e.g., demand sink for project tokens). +- Improves user experience by avoiding `ETH` dependency and enabling stable or yield-bearing fees. +- Supports onboarding strategies like airdrops and compliance via token controls. +- More feasible with low-cost DA, minimizing economic risks. + +## Cons + +- Adds deployment and operational complexity (e.g., pricers, funding for conversions). +- Introduces risks from exchange rate fluctuations, potentially causing losses for operators or higher fees for users. +- Immutable post-deployment; token must adhere to strict standards. +- Not ideal for high-volatility tokens without hedging, especially on expensive DA like Ethereum mainnet. + +## Examples + +- **Bridged USDC**: Allows stable, predictable fees. +- Project-native tokens in gaming or DeFi appchains, where users pay fees in the ecosystem's token for seamless integration. + +For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx new file mode 100644 index 0000000000..7074445cb5 --- /dev/null +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx @@ -0,0 +1,59 @@ +--- +title: 'Why choose to leverage fee rebates on your Arbitrum chain' +description: 'Learn about the pros and cons of choosing to enable fee rebates for your chain.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +Choosing fee rebates refers to configuring the chain's fee management system to enable the distribution or return of a portion of collected transaction fees (gas fees) back to users, developers, dApps, or other stakeholders. This is achieved through customizable fee collectors and optional distributor contracts, allowing chain owners to implement rebate mechanisms as part of the chain's economic model. + +Rebates can incentivize usage, reward high-volume participants, or align with project tokenomics, but they are not a default setting—instead, they require intentional configuration during or after deployment. This choice contrasts with directing all fees to a single owner or treasury address without redistribution. + +Configuration requires chain owner privileges and can be done post-deployment using precompiles or the Arbitrum Orbit SDK. It's compatible with all DA modes (Rollup, AnyTrust, Alt-DA) and gas tokens (native `ETH` or custom), though custom tokens add complexity in exchange rate management for reimbursements. For example, surplus fees could be rebated to high-activity users or contributed to a community fund. + +## Key Concepts + +- **Gas and Fees in Arbitrum Orbit**: Fees are charged for transaction execution and data posting, denominated in the chain's gas token (`ETH` by default or a custom `ERC-20`). They cover operational costs like sequencing, data availability, and parent chain interactions. Surplus fees (beyond minimum costs) can accumulate during congestion, providing a pool for potential rebates. +- **Fee Rebates**: Rebates involve returning part of the paid fees, often as incentives. In Orbit chains, this isn't an explicit "rebate toggle" but is facilitated by routing fees to smart contracts that automate distributions (e.g., proportional payouts). This can mimic rebate programs seen in dApps on Arbitrum (e.g., trading fee rebates funded by incentives), but applied at the chain level. + +## Types of Fees Available for Rebates + +- **Orbit Base Fee**: Minimum execution fee; routed to an infrastructure account. +- **Orbit Surplus Fee**: Congestion-based extra; routed to a network account. +- **Parent Chain Base Fee**: Data posting cost; routed to batch poster collectors. +- **Parent Chain Surplus Fee**: Optional batch poster reward; routed to a reward recipient. + +## Compatibility and Considerations + +- **With Custom Gas Tokens**: Rebates work but require a fee token pricer for parent chain reimbursements (e.g., converting custom tokens to `ETH`). Pricers (manual, oracle-based, or trade-tracking) ensure accurate reimbursements to batch posters, which can include refund-like mechanics if reserves are managed. +- **With Native `ETH`**: Simpler, as no conversions are needed; rebates can be direct `ETH` payouts. + +## Pros + +- Boosts user engagement by reducing effective costs (e.g., 75-100% rebates in dApp examples). +- Flexible tokenomics, such as funding rebates with surplus or incentives like `ARB` grants. +- Enhances competitiveness for high-throughput apps like gaming or DeFi. + +## Cons + +- Reduces chain revenue, potentially impacting sustainability. +- Adds complexity in setup and management (e.g., monitoring distributions, handling custom token risks like volatility). +- Requires careful design to avoid abuse (e.g., sybil attacks on rebates). + +## Examples + +- **dApp-Level Rebates**: Protocols like GMX or Synthetix on Arbitrum rebate 75%+ of trading fees using `ARB` incentives, which Orbit chains can emulate at the chain level. +- **Chain-Level**: Set surplus fees to a distributor that rebates to top users or integrates with programs like ArbiFuel for sponsored (rebated) gas in early stages. + +## How to configure + +1. **Set Fee Collectors**: Use the `ArbOwner` precompile (0x70) to assign addresses for each fee type (e.g., setInfraFeeAccount for Orbit base fees). Collectors can be simple addresses or smart contracts. +2. **Deploy a Distributor Contract**: For rebates, deploy a contract like `RewardDistributor.sol` on the chain. Set recipients and proportions (e.g., 80% to treasury, 20% to user rebate pool using basis points). +3. **Assign Distributor as Collector**: Update the relevant fee collector to the distributor's address (e.g., via `setNetworkFeeAccount` for surplus fees). +4. **Trigger Distributions**: Call distributeRewards on the contract to execute rebates, specifying recipients and shares. + +- Tools: Use command-line (cast) or SDK extensions like `arbOwnerActions` for programmatic setup. + +This feature underscores Arbitrum's modularity, allowing tailored fee economics while inheriting Ethereum security. For implementation, refer to official docs, SDK examples, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx new file mode 100644 index 0000000000..1f83ec307b --- /dev/null +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx @@ -0,0 +1,54 @@ +--- +title: 'Why choose to use native Ethereum for gas on your Arbitrum chain' +description: 'Learn about the pros and cons of choosing to use native Ethereum as the gas token for your chain.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +Choosing native Ethereum refers to configuring the chain to use `ETH`—the native currency of Ethereum—as the gas token for paying transaction fees. This is the default option in Orbit deployments, in contrast to selecting a custom `ERC-20` token for gas. The choice is set during chain deployment via genesis parameters and is immutable afterward, directly impacting how users pay for gas and how operators handle revenue and costs. + +Selecting native `ETH` means users must hold and spend `ETH` for all onchain activities, simplifying the fee mechanism without additional layers like token swaps or pricers. For operators, revenue is collected directly in `ETH`, which can be used seamlessly for data availability (DA) costs on the parent chain (e.g., posting to 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. + +## Key Concepts + +- **Gas and Fees in Arbitrum**: Gas measures computational work for transactions and executions, with fees equaling gas used times gas price. These cover sequencer operations, data posting to the parent chain (e.g., Ethereum), and network upkeep. In native `ETH` setups, all fees are denominated, paid, and settled in `ETH`. +- **Native `ETH` as Gas Token**: The chain validates transactions against users' `ETH` balances, deducting fees directly in `ETH`. No token conversions are needed, aligning the chain's economics with Ethereum's standard model. + +## How Fees Are Handled + +- Gas calculations and deductions occur directly in `ETH` during transaction processing. +- No conversions or hedging are required for DA payments, as `ETH` is the native asset on the parent chain. +- Fees remain subject to `ETH`'s price volatility, which can affect user predictability. + +## Compatibility with Chain Types + +- Works with all Orbit DA modes, including Rollup (posting to Ethereum), AnyTrust (DAC-based), and Alt-DA (e.g., Celestia), without restrictions. +- No special setup beyond standard deployment tools like the Orbit portal or scripts. + +## How It Differs from Custom Gas Tokens + +- **Custom Tokens**: Fees are paid in an `ERC-20` (e.g., `USDC` or a project token), requiring users to hold that token instead of `ETH`. Operators must convert collected tokens to `ETH` for DA costs, which introduces volatility risks and necessitates mechanisms like pricer contracts for exchange rates. +- **Native `ETH`**: Eliminates conversions, swaps, and associated risks, but requires users to manage `ETH` specifically for gas, which may not align with app-specific ecosystems. + +## Pros + +- **Simplicity and Low Risk**: No need for token conversions, hedging, or pricers, reducing operational complexity and economic losses from volatility. +- **Seamless Ethereum Integration**: Direct compatibility with Ethereum DA and broader tools, making it easier for `ETH`-centric users and developers. +- **Predictable Revenue**: Operators receive `ETH` directly, usable without intermediaries. + +## Cons + +- **User Friction**: Requires holding `ETH` even in ecosystems where it's not otherwise needed (e.g., gaming appchains), potentially complicating onboarding. +- **Limited Tokenomics**: Doesn't create demand for project-specific tokens, missing opportunities for ecosystem utility or incentives like airdrops. +- **Volatility Exposure**: Fees in `ETH` can fluctuate with market prices, affecting user costs without stablecoin benefits. + +## Examples + +- Standard Arbitrum chains like Arbitrum One use native `ETH` for broad Ethereum compatibility and simplicity. +- In contrast, some Orbit chains opt for custom tokens like bridged `USDC` for stable fees, but native `ETH` suits projects prioritizing Ethereum alignment over custom economics. + +This default choice emphasizes reliability and Ethereum-native operations within Arbitrum's modular framework. For deployment details, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx new file mode 100644 index 0000000000..d2f97ddb0c --- /dev/null +++ b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx @@ -0,0 +1,53 @@ +--- +title: 'Why choose to enable Timeboost for your Arbitrum chain' +description: 'Learn about Timeboost and the pros and cons of choosing to enable it.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +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 it is an owner-level decision, typically for chains with significant DeFi activity where MEV opportunities justify the trade-offs, and it can be done without halting operations (falling back to FCFS if no auction winner). + +It's ideal for DeFi-heavy chains with substantial MEV (e.g., arbitrage opportunities), as low-MEV chains may see costs outweigh benefits. Once enabled, searchers bid continuously (predicting MEV 15s-1m15s ahead), and users experience a minor delay on non-express transactions (~450ms average soft finality vs. ~250ms), but with no impact if no winner. + +## Key Concepts + +- **MEV in Arbitrum**: MEV refers to the profit extractable from transaction ordering, such as through arbitrage, liquidations, or backrunning. Under default FCFS, MEV often goes to searchers via latency races (e.g., faster hardware), leading to network spam and no revenue for the chain. Timeboost internalizes this by auctioning a time-based edge, diverting competition to bids while limiting harmful MEV via no reordering or visibility into other transactions. +- **Express Lane**: A special sequencer endpoint (`timeboost_sendExpressLaneTransaction`) where the auction winner (controller) can submit transactions without an artificial delay. Non-express transactions get a default 200ms delay added to their arrival timestamp, potentially pushing them to the next block (but block times remain ~250ms). The controller gets no guarantees of top-of-block positioning or profitability—value comes from predicted MEV during the round (default 60s). +- **Offchain Auction**: A sealed-bid, second-price auction (winner pays the second-highest bid) run by an autonomous auctioneer every round. Bids use a configurable `ERC-20` token (e.g., `WETH`; no fee-on-transfer or rebasing tokens) and must meet a minimum reserve price (default 0.001 `WETH`). Auctions close 15s before the round starts, with bids verifiable on-chain. Limit of 5 bids per address per round to prevent DDoS. +- **Auction Contract**: Deployed on-chain, it handles deposits (withdrawable after ~2 minutes), bid resolution, and proceeds transfer to a beneficiary (e.g., chain owner or burn address) via `flushBeneficiaryBalance()`. + +## Compatibility + +Works with any Arbitrum chain (L2/L3), all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens (native `ETH` or custom), and validation (BoLD or permissioned). Compatible with centralized or future decentralized sequencers; no prerequisites beyond a bid token and infrastructure. Not formally supported yet. + +## Pros + +- Revenue generation for chain owners. Proceeds can fund ecosystems or burn tokens. +- Reduces spam/congestion from latency races; fairer, predictable MEV access for searchers. +- Maintains security (no harmful MEV increase) and fast blocks; open auctions prevent monopolies. + +## Cons + +- Adds ~200ms delay to non-express user transactions (~450ms average response), potentially impacting UX. +- Setup/maintenance costs (e.g., auctioneer servers, Redis) may exceed revenue on low-MEV chains. +- No guaranteed revenue; ineffective without MEV activity. Minor risks like bid limits for DDoS mitigation. + +## Examples + +- **Arbitrum One and Nova**: Generates revenue from MEV auctions while protecting users. +- **Custom Orbit Chains**: DeFi-focused L3s enable it for revenue (e.g., using custom tokens for bids), while low-activity chains skip it. + +## How to configure + +1. **Deploy Auction Contract**: Use Orbit scripts (e.g., from orbit-actions repo) with a .env file specifying addresses (e.g., proxy admin, bid token like `WETH`, beneficiary). Run `forge script` to deploy and verify. +2. **Run Auctioneer Services**: Set up Redis for coordination; run bid validator (verifies bids) and auction server (resolves auctions) using the `autonomous-auctioneer` binary from Nitro (Docker or local build). +3. **Configure Sequencer**: Update node config to enable `timeboost` and `auctioneer` APIs, pointing to the contract and Redis. + +- Verify via logs (e.g., "New express lane auction round") and test bids/submissions. +- Post-enable, adjust parameters like round duration (60s default) or delay (200ms) via owner privileges. + +This feature enhances Arbitrum's modularity for MEV-aware chains but requires careful evaluation. For details, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx new file mode 100644 index 0000000000..61a39a7378 --- /dev/null +++ b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx @@ -0,0 +1,59 @@ +--- +title: 'Why choose to enable fast withdrawals for your Arbitrum chain' +description: 'Learn about fast withdrawals and the pros and cons of choosing to enable it.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +Enabling fast withdrawals refers to configuring the chain to use a fast confirmation mechanism that allows transactions and state assertions to achieve finality much quicker than the standard multi-day challenge period in optimistic rollups. This is achieved by routing assertions through a permissioned committee of validators (often overlapping with the Data Availability Committee or DAC in AnyTrust mode) that unanimously confirms them via a multisig wallet, bypassing the full fraud-proof window. As a result, users can withdraw assets or access finalized states in as little as 15 minutes for L2 chains or 15 seconds for L3 chains, significantly enhancing user experience by reducing wait times and enabling faster cross-chain interactions. + +Enabling this feature shifts the chain from relying solely on time-based fraud proofs to a committee-driven confirmation process, where validators (recommended to be at least three for reduced trust risks) must agree unanimously. It's primarily recommended for AnyTrust chains, as it leverages the existing DAC trust model without adding new assumptions—ideally, DAC members run the validators. + +For pure Rollup chains, enabling it effectively introduces a committee trust layer, making it less "trust-minimized" than standard mode. Once enabled, the chain processes a potential backlog of unconfirmed assertions before operating at full speed, and confirmations may slightly delay under high load (e.g., >1 Mgas/s throughput), but security remains intact. + +## Key Concepts + +- **Standard Withdrawal Process**: In optimistic rollups like Arbitrum, assertions about the chain's state (e.g., transaction batches) are posted to the parent chain (e.g., Ethereum or Arbitrum One) and remain challengeable for a configurable period (default ~6.4-7 days) to allow fraud proofs. Unchallenged assertions confirm, enabling secure withdrawals, but this delays user access to funds. +- **Fast Withdrawals Mechanism**: When enabled, a committee (e.g., an n/n multisig Safe wallet) of validators processes and unanimously signs assertions at a set frequency. This provides immediate confirmation, with finality tied to the parent chain's block times rather than the full challenge period. For example, L2 chains on Ethereum can confirm in ~15 minutes (above Ethereum's ~12.8-minute finality), while L3 chains on Arbitrum One can leverage "soft finality" (~250ms sequencer confirmations) for near-instant speeds. +- **Related Parameters**: Often paired with adjusting the `minimumAssertionPeriod` (e.g., to 1 block for frequent assertions) and node flags to control posting intervals. + +## Compatibility + +- **DA Modes**: Optimized for AnyTrust (leverages DAC); possible but not recommended for Rollup or Alt-DA, as it adds trust assumptions. +- **Validation**: Works with BoLD (permissionless) or pre-BoLD (permissioned), but the committee must be allowlisted. +- **Gas Tokens**: No restrictions; compatible with native `ETH` or custom `ERC-20`s. +- **Parent Chain**: Frequency must exceed the parent's finality time (e.g., >12.8 minutes for Ethereum L2s). + +## Pros + +- Dramatically faster finality (15s-15m vs. days), improving UX for withdrawals and dApps. +- Configurable frequency for tailored performance. +- No new trust if validators are DAC members in AnyTrust. + +## Cons + +- Introduces reliance on a unanimous committee, potentially increasing trust assumptions (mitigated with ≥3 members). +- Minor delays possible under high load; initial backlog post-enable. +- Not ideal for pure Rollups; requires upgrades and careful parent-chain alignment. + +## Impact on User Experience + +From a UX perspective, enabling fast withdrawals transforms slow, multi-day processes into near-real-time ones, making the chain feel more responsive. Users get quicker access to withdrawn funds (e.g., 15 minutes vs. 6.4 days), reducing frustration and capital lockup. dApps benefit from faster cross-chain state reads, enabling seamless interactions like oracle updates or multi-chain DeFi. However, it assumes users trust the committee (e.g., for high-value transfers), and any load-based delays could still impact predictability. Overall, it's ideal for consumer-facing apps like gaming or social, where speed is key. + +## Examples + +- **AnyTrust L2 Chain**: Configure for 15-minute withdrawals on Ethereum, using DAC members as validators for trust alignment. +- **L3 on Arbitrum One**: Set to 15 seconds using soft finality, suitable for high-throughput gaming appchains. + +## How to configure + +1. **Upgrade Contracts and Nodes**: Ensure nitro-contracts v2.1.0+ (update `RollupAdminLogic` and `RollupUserLogic`) and node software to nitro v3.1.2+. Use the Orbit versioner script to check and upgrade. +2. **Run Configuration Scripts**: Use the Orbit SDK (e.g., setup-fast-withdrawal example) or Orbit actions repo (e.g., fast-confirm script with Foundry's cast CLI) to create a Safe multisig for the committee, add validators to the allowlist, set the Safe as the `anytrustFastConfirmer`, and optionally adjust `minimumAssertionPeriod` (defaults to 75 blocks ~15 minutes, measured in the first non-Arbitrum ancestor chain's blocks). +3. **Configure Nodes**: + - Batch Poster: Set `--node.batch-poster.max-delay` to match the assertion period (e.g., 15m). + - Validators (BoLD mode): Enable `--node.bold.enable-fast-confirmation=true` and set `--node.bold.assertion-posting-interval` to the period. + - Validators (pre-BoLD): Similar flags like `--node.staker.enable-fast-confirmation=true`. + +This feature aligns with Arbitrum's focus on scalable, user-friendly chains while maintaining core security. For setup, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx new file mode 100644 index 0000000000..2e92ef30bf --- /dev/null +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx @@ -0,0 +1,47 @@ +--- +title: 'Why choose to enable BoLD for your Arbitrum chain' +description: 'Learn about BoLD and the pros and cons of choosing to enable it.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +Upgrading or configuring the chain to use the Bounded Liquidity Delay (BoLD) protocol as its dispute resolution mechanism means replacing the legacy 1-vs-1 challenge system with a permissionless, all-vs-all dispute framework that enhances validation and security by allowing anyone to participate in challenging invalid state assertions through bonding, while ensuring disputes resolve within a fixed time bound (up to two challenge periods, typically ~12.8 days on Ethereum). It's enabled via an administrative upgrade on the parent chain (e.g., Ethereum) and is mandatory for certain Arbitrum chain configurations, such as using custom gas tokens in Rollup mode when posting directly to Ethereum. + +For the chain, it resets the challenge clock for in-flight withdrawals (adding up to 6.4 days delay, with a max of 12.8 days total), handles overflow assertions for accumulated blocks during upgrade, and requires at least one active proposer (validator in MakeNodes mode) to advance the chain. Chain owners configure bond sizes (e.g., 3600 `ETH` for assertions on Arbitrum One equivalents) and can add incentives like service fees or bounties. This choice prioritizes enhanced security and decentralization over the legacy system's potential for centralized control, making the chain more resilient to attacks but introducing economic considerations for participation. + +## Key Concepts + +- **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. +- **Security Through Disputes**: Disputes narrow disagreements via bisections (binary search over computation steps, up to `2^69` in total space) across levels (block, BigStep for WASM ranges, SmallStep for single steps). Honest validators use offchain software (e.g., Nitro in Defensive mode) to automatically challenge invalid assertions, generating deterministic fraud proofs. Security relies on economic incentives: bonds are posted and forfeited by losers, deterring malice. +- **BoLD Protocol**: BoLD introduces an "all-vs-all" (battle royale) model where multiple parties can challenge and defend simultaneously via "edges" (claims about history segments). It uses timers based on parent chain blocks, trustless bonding pools for crowdsourced stakes, and recursive sub-challenges to ensure a single honest party can always win against any number of adversaries. This bounds liquidity delays (hence the name) and mitigates "delay attacks" where malicious parties could previously prolong disputes indefinitely. + +## Compatibility with Chain Types + +BoLD is required for Rollup mode with custom gas tokens posting to Ethereum (to handle conversions securely). It's compatible with AnyTrust and Alt-DA modes but focuses on L2/L3 chains settling on Ethereum for maximum security. Post-upgrade, the chain uses BoLD for all new assertions. + +## How It Differs from Legacy Protocols + +- **Legacy (Pre-BoLD)**: Used 1-vs-1 tournament-style challenges, vulnerable to delay attacks (malicious parties forcing sequential games to stall confirmations) and reliant on permissioned validators, limiting decentralization. +- **BoLD**: Shifts to permissionless, all-vs-all disputes with bounded delays (constant upper limit), trustless pooling for bonds, and exponential cost ratios (~6.46:1 malicious-to-honest for Arbitrum One) to deter spam. It guarantees honest wins and resolves in a fixed time, even against coordinated attacks. + +## Pros + +- **Improved Security**: Mitigates delay attacks and ensures only valid states are confirmed, with high bonds (e.g., millions in USD equivalent) deterring malice while allowing trustless defense. +- **Permissionless Decentralization**: Anyone can validate via bonds, reducing reliance on centralized entities and enabling community participation through pools. +- **Bounded Delays**: Caps withdrawal delays at ~12.8 days during disputes, providing predictability. +- **Incentives**: Includes bounties (1% of confiscated bonds) and reimbursements for honest defenders, plus optional chain-specific rewards. + +## Cons + +- **High Economic Barriers**: Large bonds (e.g., 3600 `ETH` for assertions) may limit small-scale participation without pools, and disputes impose opportunity costs on users (e.g., ~$3.27M USD/week for Arbitrum One's TVL). +- **Upgrade Disruptions**: Enabling BoLD delays pending withdrawals and requires careful overflow handling during the upgrade. +- **Complexity**: Adds operational needs for proposers and parameter tuning (e.g., bond sizes, resource ratios) to maintain security. + +## Examples + +- **Arbitrum One and Nova**: Upgraded to BoLD for permissionless validation, allowing public testnets and community validators to secure the chains. +- **Custom Orbit Chains**: Projects like gaming or DeFi appchains choose BoLD to enable decentralized validation, especially when using Rollup mode with Ethereum settlement for high-security needs. + +This upgrade aligns with Arbitrum's modular ethos, bolstering trust-minimization while inheriting Ethereum's security. For implementation, refer to the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx new file mode 100644 index 0000000000..32648ee805 --- /dev/null +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx @@ -0,0 +1,55 @@ +--- +title: 'Why choose to customize the challenge period for your Arbitrum chain' +description: 'Learn about the challenge period and the pros and cons of choosing to customize it.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +Choosing or configuring the challenge period refers to setting the duration (measured in parent chain blocks) during which state assertions—claims about the chain's execution history, block hashes, and inbox messages—can be disputed via fraud proofs before they are confirmed as valid on the parent chain (e.g., Ethereum or an Arbitrum L2). + +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`). + +It's set by the chain owner and can be chosen based on the application's risk tolerance—e.g., high-value DeFi might opt for longer periods, while gaming appchains favor shorter ones. + +## Key Concepts + +- **Challenge Period (`confirmPeriodBlocks`)**: The main window for validators to bond stakes and initiate challenges against potentially fraudulent assertions. If no valid challenge is raised, the assertion confirms, and the chain's state advances securely. +- **Extra Challenge Period (`extraChallengeTimeBlocks`)**: A post-main-period buffer to resolve any ongoing disputes or last-minute challenges, preventing premature finalization. +- **Measurement**: Always denominated in the underlying L1 chain's blocks (e.g., Ethereum's `block.number`, ~12 seconds per block), even for L3 chains settling to an L2 like Arbitrum One. This ensures consistent timing aligned with the parent chain's finality. +- **Defaults**: + - **Primary**: Approximately 45,818 L1 blocks (~1 week or 6.4 days on Ethereum). + - **Extra**: 200 L1 blocks (~40 minutes). +- **Related Features**: Interacts with minimum assertion periods (default 75 L1 blocks or ~15 minutes) to prevent rapid assertions, and can be shortened dramatically (e.g., to 15 minutes) via fast withdrawals in AnyTrust mode, where the Data Availability Committee (DAC) accelerates verification. + +## Compatibility + +- **With DA Modes**: Fully compatible across Rollup (full on-chain DA), AnyTrust (DAC-based), and Alt-DA (e.g., Celestia). In AnyTrust, fast withdrawals can reduce the effective period to 15 minutes by leveraging the DAC for rapid verification, bypassing traditional delays. +- **With Gas Tokens**: No direct impact; works with native `ETH` or custom `ERC-20`s, as the period governs validation timing rather than fee mechanics. +- **With Validation (e.g., BoLD)**: Integrates with BoLD's permissionless disputes, where the period sets the initial challenge window, but BoLD bounds total delays to at most two periods (~12.8 days max on Ethereum) during active disputes, mitigating delay attacks. + +## Pros + +- **Customizability**: Allows optimization for specific use cases, e.g., shorter periods for low-risk, high-speed apps like gaming (reducing withdrawal waits from days to minutes via fast withdrawals). +- **Enhanced Security with Longer Periods**: Provides ample time for fraud detection, especially in permissioned or high-stakes setups. +- **Buffer for Reliability**: The extra period ensures dispute resolution in high-latency environments. + +## Cons + +- **Trade-Offs in Length**: Shorter periods risk undetected fraud if validators miss the window; longer ones delay finality, impacting UX (e.g., 6.4 day waits for withdrawals). +- **Dependency on Parent Chain**: Timing is tied to L1 block times, which can vary (e.g., Ethereum congestion), and misconfiguration could lead to stalled chains or economic attacks. +- **Complexity in AnyTrust Fast Withdrawals**: Requires DAC setup and minimal hardware (e.g., 8-16 GB RAM, 1.2 TB SSD), but introduces mild trust assumptions for the speed gains. + +## Examples + +- **Standard High-Security Setup**: Arbitrum One uses ~1 week for broad DeFi compatibility, balancing security with Ethereum settlement. +- **Fast AnyTrust Chain**: A gaming L3 might configure 15-minute periods via fast withdrawals, enabling near-instant cross-chain asset moves (672x faster than defaults). +- **Custom Adjustment**: Set primary to 30,000 blocks (~4.5 days) for moderate-speed apps, with extra at 300 blocks for added buffer in latency-prone environments. + +## When to configure + +- **During Deployment**: Specified in the `RollupCreator` configuration (e.g., via the Orbit SDK deployment portal or scripts like `createRollup.ts`). For example, set `confirmPeriodBlocks` to 30,000 for ~4.5 days. +- **Post-Deployment**: Dynamically updated via owner-privileged contract calls, such as `Rollup.setConfirmPeriodBlocks(newValue)` for the primary period or `Rollup.setExtraChallengeTimeBlocks(newExtraTimeBlocks)` for the extra buffer (e.g., using tools like cast for onchain transactions). + +This parameter underscores Arbitrum's modular design, allowing chains to fine-tune validation without compromising core fraud-proof security. For implementation, refer to the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx new file mode 100644 index 0000000000..c39532c442 --- /dev/null +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx @@ -0,0 +1,42 @@ +--- +title: 'Why choose permissioned validators for your Arbitrum chain' +description: 'Learn about permissioned validators and the pros and cons of choosing to use them.' +author: pete-vielhaber +sme: +sidebar_position: +content_type: configuration +--- + +Choosing permissioned validators refers to configuring the chain to use a legacy dispute resolution protocol where only an allowlisted set of entities (e.g., approved by the chain owner or DAO) can participate in validation activities, such as posting state assertions, opening challenges, and resolving disputes. This contrasts with enabling the Bounded Liquidity Delay (BoLD) protocol for permissionless validation. The choice is made during chain deployment or via upgrades, often through governance, and prioritizes controlled oversight over broad decentralization. It's suitable for chains where limiting participants reduces operational complexity or economic risks, but it introduces trust assumptions in the allowlist. + +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. + +This choice is configurable for all DA modes (Rollup, AnyTrust, Alt-DA) and gas tokens, but it's often retained for low-TVL chains to avoid the high bonds needed in permissionless setups, which could centralize around wealthy participants. + +## Key Concepts + +- **Validation in Arbitrum**: Validators monitor and advance the chain's state by posting assertions (claims about block hashes, history commitments, and inbox messages) to the parent chain (e.g., Ethereum or an L2 like Arbitrum One). If an assertion is suspected of being invalid, challengers initiate interactive fraud proofs during a challenge window (typically ~6.4 days), bisecting disagreements down to verifiable one-step proofs executed on-chain. Security relies on economic incentives, where invalid claims lead to bond forfeitures. +- **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. + +## Compatibility with Chain Types + +Works with L2/L3 Arbitrum chains settling to Ethereum or other L2s. For AnyTrust chains (e.g., like Arbitrum Nova), validation typically remains permissioned even post-BoLD upgrades, as the Data Availability Committee (DAC) already introduces trust assumptions, and permissionless bonds could invite griefing attacks. + +## Pros + +- **Controlled Security**: Easier to manage and audit a small, trusted group, reducing risks from unvetted participants or spam attacks on low-value chains. +- **Lower Barriers**: Avoids requiring massive bonds (e.g., thousands of ETH equivalents in BoLD), making it feasible for early-stage or niche Orbit chains without attracting centralized stakers. +- **Faster Setup**: Simpler for chains prioritizing speed over full decentralization, with potential for quicker withdrawals in trusted environments like AnyTrust. + +## Cons + +- **Centralization Risks**: Relies on the allowlist's integrity; collusion or downtime could compromise the chain without community backups. +- **Vulnerability to Delays**: Susceptible to "delay attacks" where malicious validators prolong disputes indefinitely, stalling confirmations and withdrawals (e.g., beyond the standard ~7-day window). +- **Limited Decentralization**: Prevents achieving "Stage 2" rollup status, as it doesn't allow unrestricted validation, potentially reducing user trust in high-value applications. + +## Examples + +- **Arbitrum Nova**: Retains permissioned validation post-BoLD due to its lower TVL and AnyTrust model, where the DAC members double as validators for controlled security. +- **Custom Orbit Chains**: Early-stage gaming or enterprise L3s might choose permissioned to limit access to internal teams, avoiding the economic overhead of BoLD while testing. + +This option balances security with practicality in Arbitrum's ecosystem, but for maximum trust-minimization, BoLD's permissionless model is recommended for mature chains. Consult the latest official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). From 9fdcd10af1233450c58336e9e99bd66db8cba2f1 Mon Sep 17 00:00:00 2001 From: Pete Date: Mon, 20 Oct 2025 15:10:31 -0500 Subject: [PATCH 02/61] Adding content for features (config options) --- .../advanced/choose-arbos-version.mdx | 7 +- .../advanced/choose-chain-precompiles.mdx | 3 +- .../advanced/choose-custom-behavior.mdx | 7 +- .../choose-custom-delay-inbox-finality.mdx | 5 +- .../configure-aep/configure-aep-fees.mdx | 3 +- .../data-availability/choose-alt-da.mdx | 5 +- .../data-availability/choose-anytrust.mdx | 3 +- .../data-availability/choose-rollup.mdx | 3 +- .../gas-and-fees/choose-custom-gas-token.mdx | 3 +- .../gas-and-fees/choose-fee-rebates.mdx | 3 +- .../common/gas-and-fees/choose-native-eth.mdx | 3 +- .../features/common/mev/choose-timeboost.mdx | 3 +- .../common/ux/choose-fast-withdrawals.mdx | 3 +- .../validation-and-security/choose-bold.mdx | 3 +- .../choose-challenge-period.mdx | 3 +- .../choose-permissioned-validators.mdx | 3 +- sidebars.js | 143 ++++++++++++++++++ 17 files changed, 165 insertions(+), 38 deletions(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx index 19bc1c1c2c..ed9590bb83 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx @@ -3,11 +3,10 @@ title: 'Why choose a specific ArbOS version on your Arbitrum chain' description: 'Learn about choosing which ArbOS version to use on your chain.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- -In the context of Arbitrum, particularly when deploying and managing custom layer-2 (L2) or layer-3 (L3) chains via Arbitrum Orbit, "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 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. ### Key Concepts @@ -18,7 +17,7 @@ In the context of Arbitrum, particularly when deploying and managing custom laye ### Compatibility -- Works with all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (BoLD/permissioned), as long as changes meet STF rules (deterministic, pure, <1s/block). +- Works with all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (BoLD/permissioned), as long as changes meet STF rules. - Backward-compatible by design; WASM roots support old versions. - For public chains like One/Nova, requires DAO governance; Orbit chains have owner discretion. @@ -49,4 +48,4 @@ In the context of Arbitrum, particularly when deploying and managing custom laye 4. **Schedule Upgrade**: Call `scheduleArbOSUpgrade` on ArbOwner precompile with the new version and timestamp (0 for immediate). 5. **Enable Features**: Post-upgrade, configure any version-specific flags. -This reflects Orbit's modularity but demands rigorous testing. Refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This reflects Orbit's modularity but demands rigorous testing. Refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx index f7e3474f58..6b61434db1 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx @@ -3,7 +3,6 @@ title: 'Why choose to customize the precompiles on your Arbitrum chain' description: 'Learn about precompiles and the pros and cons of choosing to customize them on your chain.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -59,4 +58,4 @@ Customizing requires building a modified Nitro node, as precompiles are part of 4. **Build and Run Node**: Compile a custom Docker image and run the node with your configurations (e.g., specifying parent chain URL and chain ID). Test with tools like curl for eth_call or Foundry's cast for calls/sends. 5. **Post-Launch Changes**: Use ArbOS version upgrades to apply without reorganizing the chain; follow related guides for fraud proofs. -This advanced customization aligns with Orbit's modular design but demands careful planning and testing. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This advanced customization aligns with Orbit's modular design but demands careful planning and testing. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx index 599fc2dc4f..6a220e2ebd 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx @@ -3,11 +3,10 @@ title: 'Why choose to customize the behavior on your Arbitrum chain' description: 'Learn about custom behaviors and the pros and cons of choosing to customize the behavior it on your chain.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- -In the context of Arbitrum, particularly when deploying custom layer-2 (L2) or layer-3 (L3) chains via Arbitrum Orbit, "customizing your chain's behavior" refers to modifying the core logic that governs how the chain processes transactions, produces blocks, and transitions states—primarily by altering the State Transition Function (STF) within the Nitro software stack. This goes beyond surface-level configurations (e.g., gas tokens or DA modes) and involves code-level changes to ArbOS (Arbitrum's operating system layer), such as adding new EVM opcodes, precompiles, or state variables, while ensuring compatibility with fraud proofs and backward compatibility. Such customizations enable highly tailored chains for specific use cases but require building custom Nitro nodes and handling upgrades carefully to avoid disruptions like chain re-orgs or invalid fraud proofs. It's an advanced feature recommended for teams with expertise or partners (e.g., Rollup-as-a-Service providers), as Offchain Labs does not review individual changes—audits and maintenance are the developer's responsibility. +Customizing your chain's behavior refers to modifying the core logic that governs how the chain processes transactions, produces blocks, and transitions states—primarily by altering the State Transition Function (STF) within the Nitro software stack. This goes beyond surface-level configurations (e.g., gas tokens or DA modes) and involves code-level changes to ArbOS (Arbitrum's operating system layer), such as adding new EVM opcodes, precompiles, or state variables, while ensuring compatibility with fraud proofs and backward compatibility. Such customizations enable highly tailored chains for specific use cases but require building custom Nitro nodes and handling upgrades carefully to avoid disruptions like chain re-orgs or invalid fraud proofs. It's an advanced feature recommended for teams with expertise or partners (e.g., RaaS providers), as Offchain Labs does not review individual changes—audits and maintenance are the developer's responsibility. ### Key Concepts @@ -15,7 +14,7 @@ In the context of Arbitrum, particularly when deploying custom layer-2 (L2) or l - **ArbOS**: The operating system-like layer in Nitro that manages STF components, including precompiles, state, and upgrades. Customizations often involve versioning ArbOS to activate changes safely on live chains. - **WASM Module Root**: A 32-byte hash representing the STF's implementation, which must be updated on the parent chain for fraud proofs to work with customizations. - **Backward Compatibility**: Changes must not alter results for old blocks; they activate at specific ArbOS versions or timestamps to prevent re-orgs. -- **STF Requirements**: Must be deterministic, pure (no external resources), performant (<1 second per block), and state-managed only via the Ethereum trie or block headers. +- **STF Requirements**: Must be deterministic, pure (no external resources), performant (< 1 second per block), and state-managed only via the Ethereum trie or block headers. ### Compatibility @@ -50,4 +49,4 @@ In the context of Arbitrum, particularly when deploying custom layer-2 (L2) or l 4. **Run and Verify**: Start the node (initially without fraud proofs), test transactions, and confirm validation logs. For live upgrades, schedule ArbOS version increases. 5. **Upgrade ArbOS (for Live Chains)**: Target a new version (e.g., from v18 to v25), initializing states during the upgrade function to avoid re-orgs. -Refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +Refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx index de5705ca05..499ccd597e 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx @@ -3,7 +3,6 @@ title: 'Why choose to customize the delayed inbox finality on your Arbitrum chai description: 'Learn about delayed inbox finality and the pros and cons of choosing to customize it on your chain.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -22,7 +21,7 @@ It's recommended for teams with expertise or partners (e.g., RaaS providers), as ### Compatibility -- Works with all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (BoLD/permissioned), as long as changes meet STF rules (deterministic, pure, <1s/block). +- Works with all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (BoLD/permissioned), as long as changes meet STF rules (deterministic, pure, < 1s/block). - Backward-compatible by design; WASM roots support old versions. - For public chains like One/Nova, requires DAO governance; Orbit chains have owner discretion. @@ -53,4 +52,4 @@ It's recommended for teams with expertise or partners (e.g., RaaS providers), as 4. **Schedule Upgrade**: Call `scheduleArbOSUpgrade` on ArbOwner precompile with the new version and timestamp (0 for immediate). 5. **Enable Features**: Post-upgrade, configure any version-specific flags. -This feature reflects Orbit's modularity but demands rigorous testing. Refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This feature reflects Orbit's modularity but demands rigorous testing. Refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx index 0eb0c65ae7..4700518979 100644 --- a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx +++ b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx @@ -3,7 +3,6 @@ title: 'Why choose to configure AEP fees for your Arbitrum chain' description: 'Learn about AEP fee configuration and the pros and cons of choosing to configure it.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -47,4 +46,4 @@ The configuration ensures compliance with the AEP terms, streamlines reporting, 3. **Route and Bridge Fees**: Configure the router to send the 10% share to Ethereum (e.g., via native bridges), then deposit to the DAO address on Arbitrum One. Use functions like `flushBeneficiaryBalance` for periodic transfers. 4. **Report Fees**: Submit quarterly reports to the Arbitrum Foundation, including calculations and proofs of payment, to maintain license compliance. -This setup reflects Arbitrum's collaborative model, ensuring custom chains contribute back while benefiting from the ecosystem. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This setup reflects Arbitrum's collaborative model, ensuring custom chains contribute back while benefiting from the ecosystem. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx index f1b0fd0075..0c6daba10c 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx @@ -3,7 +3,6 @@ title: 'Why choose to use alt-DA for data availability on your Arbitrum chain' description: 'Learn about alt-DA and the pros and cons of choosing to use it for DA on your chain.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -40,6 +39,6 @@ Arbitrum Orbit supports integrations with several Alt-DA solutions, including: - **Celestia**: A modular DA blockchain using data availability sampling for lightweight verification. - **Avail**: Focuses on high-throughput DA with erasure coding. - **EigenDA (via EigenLayer)**: Leverages restaking for secure, decentralized DA. -- For a list of Alt-DA providers, refer to the [Third-party providers page](launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#data-availability-providers-for-anytrust-chains) +- For a list of Alt-DA providers, refer to the [Third-party providers page](launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#data-availability-providers-for-anytrust-chains) -This option reflects the growing trend toward modular blockchain architectures, where DA handling is separate to scale ecosystems like Arbitrum without compromising core security. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This option reflects the growing trend toward modular blockchain architectures, where DA handling is separate to scale ecosystems like Arbitrum without compromising core security. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx index 60dd4832be..3fa680420a 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx @@ -3,7 +3,6 @@ title: 'Why choose to use AnyTrust for data availability on your Arbitrum chain' description: 'Learn about data availability using AnyTrust and the pros and cons of choosing to use it for DA on your chain.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -29,4 +28,4 @@ With up to 90% lower fees, higher throughput, and faster finality, it is suitabl Introduces a trust assumption in the DAC, which could be a vector for censorship or failure if too many members collude (though mitigated by requiring only a small honest minority). -This option reflects the growing trend toward modular blockchain architectures, where DA handling is separate to scale ecosystems like Arbitrum without compromising core security. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This option reflects the growing trend toward modular blockchain architectures, where DA handling is separate to scale ecosystems like Arbitrum without compromising core security. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx index 2dbe42f2ef..b6d17d0a25 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx @@ -3,7 +3,6 @@ title: 'Why choose to use rollup for data availability on your Arbitrum chain' description: 'Learn about data availability using rollups and the pros and cons of choosing to use it for DA on your chain.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -21,4 +20,4 @@ This flexibility allows developers to tailor chains to specific needs while buil - This inherits Ethereum's full security and decentralization, with no additional trust assumptions—data is always available on-chain for anyone to access and verify. - Example: Arbitrum One operates in this mode. -For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx index fff0765b6b..77909524f1 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx @@ -3,7 +3,6 @@ title: 'Why choose to use a custom gas token on your Arbitrum chain' description: 'Learn about the pros and cons of choosing to use a custom gas token for your chain.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -43,4 +42,4 @@ Choosing a custom gas token refers to configuring the chain to use a specific `E - **Bridged USDC**: Allows stable, predictable fees. - Project-native tokens in gaming or DeFi appchains, where users pay fees in the ecosystem's token for seamless integration. -For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx index 7074445cb5..db0a304d7b 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx @@ -3,7 +3,6 @@ title: 'Why choose to leverage fee rebates on your Arbitrum chain' description: 'Learn about the pros and cons of choosing to enable fee rebates for your chain.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -56,4 +55,4 @@ Configuration requires chain owner privileges and can be done post-deployment us - Tools: Use command-line (cast) or SDK extensions like `arbOwnerActions` for programmatic setup. -This feature underscores Arbitrum's modularity, allowing tailored fee economics while inheriting Ethereum security. For implementation, refer to official docs, SDK examples, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This feature underscores Arbitrum's modularity, allowing tailored fee economics while inheriting Ethereum security. For implementation, refer to official docs, SDK examples, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx index 1f83ec307b..bcd33537ab 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx @@ -3,7 +3,6 @@ title: 'Why choose to use native Ethereum for gas on your Arbitrum chain' description: 'Learn about the pros and cons of choosing to use native Ethereum as the gas token for your chain.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -51,4 +50,4 @@ This option prioritizes straightforward integration with Ethereum's ecosystem, a - Standard Arbitrum chains like Arbitrum One use native `ETH` for broad Ethereum compatibility and simplicity. - In contrast, some Orbit chains opt for custom tokens like bridged `USDC` for stable fees, but native `ETH` suits projects prioritizing Ethereum alignment over custom economics. -This default choice emphasizes reliability and Ethereum-native operations within Arbitrum's modular framework. For deployment details, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This default choice emphasizes reliability and Ethereum-native operations within Arbitrum's modular framework. For deployment details, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx index d2f97ddb0c..b7fc9f8d19 100644 --- a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx +++ b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx @@ -3,7 +3,6 @@ title: 'Why choose to enable Timeboost for your Arbitrum chain' description: 'Learn about Timeboost and the pros and cons of choosing to enable it.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -50,4 +49,4 @@ Works with any Arbitrum chain (L2/L3), all DA modes (Rollup, AnyTrust, Alt-DA), - Verify via logs (e.g., "New express lane auction round") and test bids/submissions. - Post-enable, adjust parameters like round duration (60s default) or delay (200ms) via owner privileges. -This feature enhances Arbitrum's modularity for MEV-aware chains but requires careful evaluation. For details, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This feature enhances Arbitrum's modularity for MEV-aware chains but requires careful evaluation. For details, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx index 61a39a7378..b6a26cbc90 100644 --- a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx +++ b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx @@ -3,7 +3,6 @@ title: 'Why choose to enable fast withdrawals for your Arbitrum chain' description: 'Learn about fast withdrawals and the pros and cons of choosing to enable it.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -56,4 +55,4 @@ From a UX perspective, enabling fast withdrawals transforms slow, multi-day proc - Validators (BoLD mode): Enable `--node.bold.enable-fast-confirmation=true` and set `--node.bold.assertion-posting-interval` to the period. - Validators (pre-BoLD): Similar flags like `--node.staker.enable-fast-confirmation=true`. -This feature aligns with Arbitrum's focus on scalable, user-friendly chains while maintaining core security. For setup, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This feature aligns with Arbitrum's focus on scalable, user-friendly chains while maintaining core security. For setup, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx index 2e92ef30bf..20b425b14f 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx @@ -3,7 +3,6 @@ title: 'Why choose to enable BoLD for your Arbitrum chain' description: 'Learn about BoLD and the pros and cons of choosing to enable it.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -44,4 +43,4 @@ BoLD is required for Rollup mode with custom gas tokens posting to Ethereum (to - **Arbitrum One and Nova**: Upgraded to BoLD for permissionless validation, allowing public testnets and community validators to secure the chains. - **Custom Orbit Chains**: Projects like gaming or DeFi appchains choose BoLD to enable decentralized validation, especially when using Rollup mode with Ethereum settlement for high-security needs. -This upgrade aligns with Arbitrum's modular ethos, bolstering trust-minimization while inheriting Ethereum's security. For implementation, refer to the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This upgrade aligns with Arbitrum's modular ethos, bolstering trust-minimization while inheriting Ethereum's security. For implementation, refer to the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx index 32648ee805..96cdce1f66 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx @@ -3,7 +3,6 @@ title: 'Why choose to customize the challenge period for your Arbitrum chain' description: 'Learn about the challenge period and the pros and cons of choosing to customize it.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -52,4 +51,4 @@ It's set by the chain owner and can be chosen based on the application's risk to - **During Deployment**: Specified in the `RollupCreator` configuration (e.g., via the Orbit SDK deployment portal or scripts like `createRollup.ts`). For example, set `confirmPeriodBlocks` to 30,000 for ~4.5 days. - **Post-Deployment**: Dynamically updated via owner-privileged contract calls, such as `Rollup.setConfirmPeriodBlocks(newValue)` for the primary period or `Rollup.setExtraChallengeTimeBlocks(newExtraTimeBlocks)` for the extra buffer (e.g., using tools like cast for onchain transactions). -This parameter underscores Arbitrum's modular design, allowing chains to fine-tune validation without compromising core fraud-proof security. For implementation, refer to the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This parameter underscores Arbitrum's modular design, allowing chains to fine-tune validation without compromising core fraud-proof security. For implementation, refer to the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx index c39532c442..2955c3060d 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx @@ -3,7 +3,6 @@ title: 'Why choose permissioned validators for your Arbitrum chain' description: 'Learn about permissioned validators and the pros and cons of choosing to use them.' author: pete-vielhaber sme: -sidebar_position: content_type: configuration --- @@ -39,4 +38,4 @@ Works with L2/L3 Arbitrum chains settling to Ethereum or other L2s. For AnyTrust - **Arbitrum Nova**: Retains permissioned validation post-BoLD due to its lower TVL and AnyTrust model, where the DAC members double as validators for controlled security. - **Custom Orbit Chains**: Early-stage gaming or enterprise L3s might choose permissioned to limit access to internal teams, avoiding the economic overhead of BoLD while testing. -This option balances security with practicality in Arbitrum's ecosystem, but for maximum trust-minimization, BoLD's permissionless model is recommended for mature chains. Consult the latest official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/third-party-integrations/third-party-providers.mdx#rollup-as-a-service-raas-providers). +This option balances security with practicality in Arbitrum's ecosystem, but for maximum trust-minimization, BoLD's permissionless model is recommended for mature chains. Consult the latest official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/sidebars.js b/sidebars.js index 4c33e9e64e..b47c45cd51 100644 --- a/sidebars.js +++ b/sidebars.js @@ -112,6 +112,149 @@ const sidebars = { id: 'launch-arbitrum-chain/aep-license', label: 'Arbitrum chain licensing', }, + { + type: 'category', + label: 'Features', + collapsed: true, + items: [ + { + type: 'category', + label: 'Common', + collapsed: true, + items: [ + { + type: 'category', + label: 'Data availability', + collapsed: true, + items: [ + { + type: 'doc', + id: 'launch-arbitrum-chain/features/common/data-availability/choose-alt-da', + label: `Alt-DA`, + }, + { + type: 'doc', + id: 'launch-arbitrum-chain/features/common/data-availability/choose-anytrust', + label: `AnyTrust`, + }, + { + type: 'doc', + id: 'launch-arbitrum-chain/features/common/data-availability/choose-rollup', + label: `Rollup`, + }, + ], + }, + { + type: 'category', + label: 'Gas and fees', + collapsed: true, + items: [ + { + type: 'doc', + id: 'launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token', + label: `Custom gas token`, + }, + { + type: 'doc', + id: 'launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates', + label: `Fee rebates`, + }, + { + type: 'doc', + id: 'launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth', + label: `Native ETH`, + }, + ], + }, + { + type: 'category', + label: 'Validation and security', + collapsed: true, + items: [ + { + type: 'doc', + id: 'launch-arbitrum-chain/features/common/validation-and-security/choose-bold', + label: `BoLD`, + }, + { + type: 'doc', + id: 'launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period', + label: `Custom challenge period`, + }, + { + type: 'doc', + id: 'launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators', + label: `Permissioned validators`, + }, + ], + }, + { + type: 'category', + label: 'MEV', + collapsed: true, + items: [ + { + type: 'doc', + id: 'launch-arbitrum-chain/features/common/mev/choose-timeboost', + label: `Timeboost`, + }, + ], + }, + { + type: 'category', + label: 'UX', + collapsed: true, + items: [ + { + type: 'doc', + id: 'launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals', + label: `Fast withdrawals`, + }, + ], + }, + { + type: 'category', + label: 'AEP fees', + collapsed: true, + items: [ + { + type: 'doc', + id: 'launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees', + label: `AEP fees`, + }, + ], + }, + ], + }, + { + type: 'category', + label: 'Advanced', + collapsed: true, + items: [ + { + type: 'doc', + id: 'launch-arbitrum-chain/features/advanced/choose-arbos-version', + label: `ArbOS version`, + }, + { + type: 'doc', + label: 'Precompiles', + id: 'launch-arbitrum-chain/features/advanced/choose-chain-precompiles', + }, + { + type: 'doc', + label: 'Chain behavior', + id: 'launch-arbitrum-chain/features/advanced/choose-custom-behavior', + }, + { + type: 'doc', + label: 'Delayed inbox finality', + id: 'launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality', + }, + ], + }, + ], + }, { type: 'category', label: 'Configure your chain', From 1cbddb4264b9598779fc2350c131d57e48e5cd2e Mon Sep 17 00:00:00 2001 From: Pete Date: Wed, 22 Oct 2025 08:53:37 -0500 Subject: [PATCH 03/61] Moving items around for Data Availability --- sidebars.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sidebars.js b/sidebars.js index b47c45cd51..3663268deb 100644 --- a/sidebars.js +++ b/sidebars.js @@ -129,8 +129,8 @@ const sidebars = { items: [ { type: 'doc', - id: 'launch-arbitrum-chain/features/common/data-availability/choose-alt-da', - label: `Alt-DA`, + id: 'launch-arbitrum-chain/features/common/data-availability/choose-rollup', + label: `Rollup`, }, { type: 'doc', @@ -139,8 +139,8 @@ const sidebars = { }, { type: 'doc', - id: 'launch-arbitrum-chain/features/common/data-availability/choose-rollup', - label: `Rollup`, + id: 'launch-arbitrum-chain/features/common/data-availability/choose-alt-da', + label: `Alt-DA`, }, ], }, From 8b9ab22701909a055830a977f4aeeb8b917fe272 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 08:58:28 -0600 Subject: [PATCH 04/61] Adding partial for Timeboost pros/cons; added renderer --- .../features/common/mev/choose-timeboost.mdx | 16 +++++----------- .../features/partials/_timeboost-pc.mdx | 11 +++++++++++ .../partials/config-timeboost.mdx | 8 -------- src/components/FloatingHoverModal/index.js | 2 +- 4 files changed, 17 insertions(+), 20 deletions(-) create mode 100644 docs/launch-arbitrum-chain/features/partials/_timeboost-pc.mdx delete mode 100644 docs/launch-arbitrum-chain/partials/config-timeboost.mdx diff --git a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx index b7fc9f8d19..b2fcd2fa6f 100644 --- a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx +++ b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx @@ -6,6 +6,8 @@ sme: content_type: configuration --- +import TimeboostPCPartial from '../../partials/_timeboost-pc.mdx'; + 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 it is an owner-level decision, typically for chains with significant DeFi activity where MEV opportunities justify the trade-offs, and it can be done without halting operations (falling back to FCFS if no auction winner). @@ -23,17 +25,9 @@ It's ideal for DeFi-heavy chains with substantial MEV (e.g., arbitrage opportuni Works with any Arbitrum chain (L2/L3), all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens (native `ETH` or custom), and validation (BoLD or permissioned). Compatible with centralized or future decentralized sequencers; no prerequisites beyond a bid token and infrastructure. Not formally supported yet. -## Pros - -- Revenue generation for chain owners. Proceeds can fund ecosystems or burn tokens. -- Reduces spam/congestion from latency races; fairer, predictable MEV access for searchers. -- Maintains security (no harmful MEV increase) and fast blocks; open auctions prevent monopolies. - -## Cons + -- Adds ~200ms delay to non-express user transactions (~450ms average response), potentially impacting UX. -- Setup/maintenance costs (e.g., auctioneer servers, Redis) may exceed revenue on low-MEV chains. -- No guaranteed revenue; ineffective without MEV activity. Minor risks like bid limits for DDoS mitigation. + ## Examples @@ -42,7 +36,7 @@ Works with any Arbitrum chain (L2/L3), all DA modes (Rollup, AnyTrust, Alt-DA), ## How to configure -1. **Deploy Auction Contract**: Use Orbit scripts (e.g., from orbit-actions repo) with a .env file specifying addresses (e.g., proxy admin, bid token like `WETH`, beneficiary). Run `forge script` to deploy and verify. +1. **Deploy Auction Contract**: Use Orbit scripts (e.g., from `orbit-actions` repo) with a `.env` file specifying addresses (e.g., proxy admin, bid token like `WETH`, beneficiary). Run `forge script` to deploy and verify. 2. **Run Auctioneer Services**: Set up Redis for coordination; run bid validator (verifies bids) and auction server (resolves auctions) using the `autonomous-auctioneer` binary from Nitro (Docker or local build). 3. **Configure Sequencer**: Update node config to enable `timeboost` and `auctioneer` APIs, pointing to the contract and Redis. diff --git a/docs/launch-arbitrum-chain/features/partials/_timeboost-pc.mdx b/docs/launch-arbitrum-chain/features/partials/_timeboost-pc.mdx new file mode 100644 index 0000000000..9e19add210 --- /dev/null +++ b/docs/launch-arbitrum-chain/features/partials/_timeboost-pc.mdx @@ -0,0 +1,11 @@ +## Pros + +- Revenue generation for chain owners. Proceeds can fund ecosystems or burn tokens. +- Reduces spam/congestion from latency races; fairer, predictable MEV access for searchers. +- Maintains security (no harmful MEV increase) and fast blocks; open auctions prevent monopolies. + +## Cons + +- Adds ~200ms delay to non-express user transactions (~450ms average response), potentially impacting UX. +- Setup/maintenance costs (e.g., auctioneer servers, Redis) may exceed revenue on low-MEV chains. +- No guaranteed revenue; ineffective without MEV activity. Minor risks like bid limits for DDoS mitigation. diff --git a/docs/launch-arbitrum-chain/partials/config-timeboost.mdx b/docs/launch-arbitrum-chain/partials/config-timeboost.mdx deleted file mode 100644 index 06aee62c86..0000000000 --- a/docs/launch-arbitrum-chain/partials/config-timeboost.mdx +++ /dev/null @@ -1,8 +0,0 @@ -Timeboost is an optional transaction ordering policy that is configurable on any Arbitrum chain, including Arbitrum (Orbit) chains. It replaces the First-come, First-served (FCFS) ordering by introducing a sealed-bid, second-price auction for an "express lane." This express lane gives the auction winner a temporary time advantage (default: 200ms) for submitting transactions ahead of others, allowing the chain owner to capture Maximal Extractable Value (MEV) from activities like arbitrage or liquidations. - -| Feature | Pros | Cons | -| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Revenue and MEV Capture | Captures MEV (e.g., from arbitrage or backrunning) as auction revenue for the chain owner, potentially generating significant income. Revenue can be redistributed to users, apps, or burned, creating new value accrual paths. Flexible bid tokens (e.g., any `ERC-20`) allow customization. | Revenue isn't guaranteed; it depends on MEV volume—if your Arbitrum chain has low activity, auctions may yield little or nothing. Setup/maintenance costs (e.g., auctioneer infrastructure) could exceed benefits. | -| Network performance and spam reduction | Reduces spam and congestion by shifting searcher resources from hardware-based latency races to auctions, potentially lowering network stress and improving overall efficiency. Maintains industry-leading block times (250ms) and protects against harmful MEV via private mempool. | Introduces a ~200ms delay for non-express lane transactions (increasing average response time to ~450ms), which could slightly degrade UX for regular users during active auction rounds. Express lane transactions may drop if not sequenced within ~1.25 seconds, adding minor reliability risks. | -| User and ecosystem impact | Preserves strong UX with minimal changes for most users; enables new models like searchers reselling express lane access, potentially boosting ecosystem innovation. Socializes MEV benefits back to the chain (e.g., via DAO), reducing negative externalities from searcher competition. | Risk of centralized dominance: well-funded entities might monopolize auctions, though mitigated by competitive bidding and short advantage (200ms). This centralization could enable new MEV strategies (e.g., front-running liquidations), potentially harming users or protocols in some cases. Adds friction for latency-sensitive features like onchain limit order books, potentially widening spreads or increasing risks for market makers. | -| Flexibility and Implementation | Fully optional and customizable (e.g, adjust delays, auction cadence); works with decentralized sequencers and reverts to FCFS if needed. Ideal for Arbitrum chain owners seeking control over ordering policies. Requires continuous bidding, which may not suit spontaneous MEV opportunities, and lacks reordering or full control for winners, limiting utility in some scenarios. Potential for secondary markets adds complexity and requires ongoing monitoring for risks like collusion or abuse. Bid deposits tie up liquidity (with a withdrawal delay of ~2 minutes). | diff --git a/src/components/FloatingHoverModal/index.js b/src/components/FloatingHoverModal/index.js index 71b07d2871..5ff8bfcc5c 100644 --- a/src/components/FloatingHoverModal/index.js +++ b/src/components/FloatingHoverModal/index.js @@ -26,7 +26,7 @@ import ConfigHardware from '@site/docs/launch-arbitrum-chain/partials/config-har import ConfigRollup from '@site/docs/launch-arbitrum-chain/partials/config-rollup.mdx'; import ConfigAnytrust from '@site/docs/launch-arbitrum-chain/partials/config-anytrust.mdx'; import ConfigFastwithdrawals from '@site/docs/launch-arbitrum-chain/partials/config-fast-withdrawals.mdx'; -import ConfigTimeboost from '@site/docs/launch-arbitrum-chain/partials/config-timeboost.mdx'; +import ConfigTimeboost from '@site/docs/launch-arbitrum-chain/features/partials/_timeboost-pc.mdx'; import ConfigBold from '@site/docs/launch-arbitrum-chain/partials/config-bold.mdx'; import ConfigPermissionedValidators from '@site/docs/launch-arbitrum-chain/partials/config-permissioned-validators.mdx'; import ConfigL1ChallengePeriod from '@site/docs/launch-arbitrum-chain/partials/config-l1-challenge-period.mdx'; From 183011c3ad91780bf8b5cf4bd5e07f1876185772 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 09:07:17 -0600 Subject: [PATCH 05/61] Adding partial for BoLD pros & cons; added renderer --- .../validation-and-security/choose-bold.mdx | 15 ++++----------- .../features/partials/_bold-pc.mdx | 12 ++++++++++++ .../partials/config-bold.mdx | 8 -------- src/components/FloatingHoverModal/index.js | 2 +- 4 files changed, 17 insertions(+), 20 deletions(-) create mode 100644 docs/launch-arbitrum-chain/features/partials/_bold-pc.mdx delete mode 100644 docs/launch-arbitrum-chain/partials/config-bold.mdx diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx index 20b425b14f..7364505a24 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx @@ -6,6 +6,8 @@ sme: content_type: configuration --- +import BoldPCPartial from '../../partials/_bold-pc.mdx'; + Upgrading or configuring the chain to use the Bounded Liquidity Delay (BoLD) protocol as its dispute resolution mechanism means replacing the legacy 1-vs-1 challenge system with a permissionless, all-vs-all dispute framework that enhances validation and security by allowing anyone to participate in challenging invalid state assertions through bonding, while ensuring disputes resolve within a fixed time bound (up to two challenge periods, typically ~12.8 days on Ethereum). It's enabled via an administrative upgrade on the parent chain (e.g., Ethereum) and is mandatory for certain Arbitrum chain configurations, such as using custom gas tokens in Rollup mode when posting directly to Ethereum. For the chain, it resets the challenge clock for in-flight withdrawals (adding up to 6.4 days delay, with a max of 12.8 days total), handles overflow assertions for accumulated blocks during upgrade, and requires at least one active proposer (validator in MakeNodes mode) to advance the chain. Chain owners configure bond sizes (e.g., 3600 `ETH` for assertions on Arbitrum One equivalents) and can add incentives like service fees or bounties. This choice prioritizes enhanced security and decentralization over the legacy system's potential for centralized control, making the chain more resilient to attacks but introducing economic considerations for participation. @@ -25,18 +27,9 @@ BoLD is required for Rollup mode with custom gas tokens posting to Ethereum (to - **Legacy (Pre-BoLD)**: Used 1-vs-1 tournament-style challenges, vulnerable to delay attacks (malicious parties forcing sequential games to stall confirmations) and reliant on permissioned validators, limiting decentralization. - **BoLD**: Shifts to permissionless, all-vs-all disputes with bounded delays (constant upper limit), trustless pooling for bonds, and exponential cost ratios (~6.46:1 malicious-to-honest for Arbitrum One) to deter spam. It guarantees honest wins and resolves in a fixed time, even against coordinated attacks. -## Pros - -- **Improved Security**: Mitigates delay attacks and ensures only valid states are confirmed, with high bonds (e.g., millions in USD equivalent) deterring malice while allowing trustless defense. -- **Permissionless Decentralization**: Anyone can validate via bonds, reducing reliance on centralized entities and enabling community participation through pools. -- **Bounded Delays**: Caps withdrawal delays at ~12.8 days during disputes, providing predictability. -- **Incentives**: Includes bounties (1% of confiscated bonds) and reimbursements for honest defenders, plus optional chain-specific rewards. - -## Cons + -- **High Economic Barriers**: Large bonds (e.g., 3600 `ETH` for assertions) may limit small-scale participation without pools, and disputes impose opportunity costs on users (e.g., ~$3.27M USD/week for Arbitrum One's TVL). -- **Upgrade Disruptions**: Enabling BoLD delays pending withdrawals and requires careful overflow handling during the upgrade. -- **Complexity**: Adds operational needs for proposers and parameter tuning (e.g., bond sizes, resource ratios) to maintain security. + ## Examples diff --git a/docs/launch-arbitrum-chain/features/partials/_bold-pc.mdx b/docs/launch-arbitrum-chain/features/partials/_bold-pc.mdx new file mode 100644 index 0000000000..1758f053ce --- /dev/null +++ b/docs/launch-arbitrum-chain/features/partials/_bold-pc.mdx @@ -0,0 +1,12 @@ +## Pros + +- **Improved Security**: Mitigates delay attacks and ensures only valid states are confirmed, with high bonds (e.g., millions in USD equivalent) deterring malice while allowing trustless defense. +- **Permissionless Decentralization**: Anyone can validate via bonds, reducing reliance on centralized entities and enabling community participation through pools. +- **Bounded Delays**: Caps withdrawal delays at ~12.8 days during disputes, providing predictability. +- **Incentives**: Includes bounties (1% of confiscated bonds) and reimbursements for honest defenders, plus optional chain-specific rewards. + +## Cons + +- **High Economic Barriers**: Large bonds (e.g., 3600 `ETH` for assertions) may limit small-scale participation without pools, and disputes impose opportunity costs on users (e.g., ~$3.27M USD/week for Arbitrum One's TVL). +- **Upgrade Disruptions**: Enabling BoLD delays pending withdrawals and requires careful overflow handling during the upgrade. +- **Complexity**: Adds operational needs for proposers and parameter tuning (e.g., bond sizes, resource ratios) to maintain security. diff --git a/docs/launch-arbitrum-chain/partials/config-bold.mdx b/docs/launch-arbitrum-chain/partials/config-bold.mdx deleted file mode 100644 index 3866e5776c..0000000000 --- a/docs/launch-arbitrum-chain/partials/config-bold.mdx +++ /dev/null @@ -1,8 +0,0 @@ -BoLD (Bounded Liquidity Delay) is a dispute resolution protocol that enables permissionless validation, allowing anyone to propose, challenge, and defend chain states by bonding `ETH`, with disputes resolved in a fixed-time window (typically around 7-14 days, depending on the chain). For Arbitrum chains, BoLD is available as an optional upgrade via the Nitro stack, enhancing decentralization and security while setting states to a parent chain like Ethereum or Arbitrum One. - -| Feature | Pros | Cons | -| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Validation & Decentraliation | - Enables permissionless validation, allowing anyone to propose and defend states, increasing resilience and inclusivity
- Supports trustless bonding pools, letting groups pool `ETH` to participate without high individual capital barriers, promoting broader decentralization | - High bond requirements (e.g., potentially thousands of `ETH` for assertions) may centralize participation to well-funded entities, limiting smaller validators.
- No built-in protocol-level incentives for validators could lead to free-riding, where parties rely on others to defend the chain. | -| Security & Dispute Resolution | - Mitigates delay attacks by enforcing a bounded dispute window (e.g., ~7 days plus grace periods), ensuring predictable resolution even against multiple malicious challengers.
- Enhances withdrawal security to the parent chain by limiting indefinite delays, and includes features like Delay Buffer for censorship resistance.
- A single honest party can win disputes against any number of dishonest ones, with audited code for reliability. | - Disputes can still delay all withdrawals (up to ~14 days total), impacting user experience and liquidity.
- For lower-TVL Arbitrum chains, high bonds might need adjustment, trading off security against centralization risks or vulnerability to spam.
- Potential censorship risks for L3 Arbitrum chains (e.g., parent chain is censored, delays could extend up to 50 days in extreme cases, though mitigated). | -| Economics & Incentives | - Bonds deter actors, with honest parties refunded plus a 1% defender's bounty and gas reimbursements, plus potential service fees (3-4% annualized `ETH` yield) from chain owners.
- Fixed costs and resource ratios prevent dishonest parties from inflating expenses for honest validators. | - Significant capital lockup in bonds creates opportunity costs and risks (e.g., loss if proven wrong), potentially prohibitive for smaller chains.
- KYC requirements for fee eligibility may exclude some participants, like those in sanctioned regions.
- Operational costs for onchain proofs and disputes (gas, computation), add complexity and expenses. | -| Implementations & Maturity | - Modular upgrade for Arbitrum chains
- Community testing via testnets and visualizers available for easier adoption | - Increased protocol complexity may require additional tooling and expertise to manage.
- Reliance on parent chain for final proofs; issues there could affect Arbitrum chain disputes. | diff --git a/src/components/FloatingHoverModal/index.js b/src/components/FloatingHoverModal/index.js index 5ff8bfcc5c..4a41febd27 100644 --- a/src/components/FloatingHoverModal/index.js +++ b/src/components/FloatingHoverModal/index.js @@ -27,7 +27,7 @@ import ConfigRollup from '@site/docs/launch-arbitrum-chain/partials/config-rollu import ConfigAnytrust from '@site/docs/launch-arbitrum-chain/partials/config-anytrust.mdx'; import ConfigFastwithdrawals from '@site/docs/launch-arbitrum-chain/partials/config-fast-withdrawals.mdx'; import ConfigTimeboost from '@site/docs/launch-arbitrum-chain/features/partials/_timeboost-pc.mdx'; -import ConfigBold from '@site/docs/launch-arbitrum-chain/partials/config-bold.mdx'; +import ConfigBold from '@site/docs/launch-arbitrum-chain/features/partials/_bold-pc.mdx'; import ConfigPermissionedValidators from '@site/docs/launch-arbitrum-chain/partials/config-permissioned-validators.mdx'; import ConfigL1ChallengePeriod from '@site/docs/launch-arbitrum-chain/partials/config-l1-challenge-period.mdx'; import ConfigForceInclusion from '@site/docs/launch-arbitrum-chain/partials/config-force-inclusion.mdx'; From 03bd2ef7e5813d2f4679720af3457130394dc586 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 09:13:16 -0600 Subject: [PATCH 06/61] Adding Rollup partial; added renderer --- .../features/common/data-availability/choose-rollup.mdx | 6 ++++++ .../config-rollup.mdx => features/partials/_rollup-pc.mdx} | 4 ++-- src/components/FloatingHoverModal/index.js | 2 +- 3 files changed, 9 insertions(+), 3 deletions(-) rename docs/launch-arbitrum-chain/{partials/config-rollup.mdx => features/partials/_rollup-pc.mdx} (94%) diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx index b6d17d0a25..5ca1aad174 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx @@ -6,6 +6,8 @@ sme: content_type: configuration --- +import RollupPCPartial from '../../partials/_rollup-pc.mdx'; + 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. @@ -20,4 +22,8 @@ This flexibility allows developers to tailor chains to specific needs while buil - This inherits Ethereum's full security and decentralization, with no additional trust assumptions—data is always available on-chain for anyone to access and verify. - Example: Arbitrum One operates in this mode. + + + + For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/partials/config-rollup.mdx b/docs/launch-arbitrum-chain/features/partials/_rollup-pc.mdx similarity index 94% rename from docs/launch-arbitrum-chain/partials/config-rollup.mdx rename to docs/launch-arbitrum-chain/features/partials/_rollup-pc.mdx index 4d12421675..2cb6b38a45 100644 --- a/docs/launch-arbitrum-chain/partials/config-rollup.mdx +++ b/docs/launch-arbitrum-chain/features/partials/_rollup-pc.mdx @@ -1,10 +1,10 @@ -## Pros of using Rollup mode +## Pros - **Security**: Provides maximum security and decentralization by inheriting full Ethereum-grade security without additional trust assumptions beyond the base layer. - **Strong Data Availability**: Ensures strong data availability and censorship resistance, as all transaction data is publicly posted on the parent chain, allowing anyone to validate and detect fraud. - **Trustless and permissionless**: Fully trustless and permissionless operation, requiring only one honest validator for the system to remain secure, making it ideal for high-value applications like DeFi protocols. -## Cons of using Rollup mode +## Cons - **Higher costs**: Higher transaction fees due to the cost of posting all data on-chain to the parent layer. - **Withdrawal times**: Longer withdrawal times, typically involving a seven-day challenge period for fraud proofs before funds can be moved back to the parent layer. diff --git a/src/components/FloatingHoverModal/index.js b/src/components/FloatingHoverModal/index.js index 4a41febd27..9a6873bcc1 100644 --- a/src/components/FloatingHoverModal/index.js +++ b/src/components/FloatingHoverModal/index.js @@ -23,7 +23,7 @@ import ConfigAltDa from '@site/docs/launch-arbitrum-chain/partials/config-alt-da import ConfigDedicatedThroughput from '@site/docs/launch-arbitrum-chain/partials/config-dedicated-throughput.mdx'; import ConfigNativeEth from '@site/docs/launch-arbitrum-chain/partials/config-native-eth.mdx'; import ConfigHardware from '@site/docs/launch-arbitrum-chain/partials/config-hardware.mdx'; -import ConfigRollup from '@site/docs/launch-arbitrum-chain/partials/config-rollup.mdx'; +import ConfigRollup from '@site/docs/launch-arbitrum-chain/features/partials/_rollup-pc.mdx'; import ConfigAnytrust from '@site/docs/launch-arbitrum-chain/partials/config-anytrust.mdx'; import ConfigFastwithdrawals from '@site/docs/launch-arbitrum-chain/partials/config-fast-withdrawals.mdx'; import ConfigTimeboost from '@site/docs/launch-arbitrum-chain/features/partials/_timeboost-pc.mdx'; From 853d37e17d8f265e5b295ef9bf2c066bba5d9184 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 09:13:47 -0600 Subject: [PATCH 07/61] redirect vercel.json --- vercel.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/vercel.json b/vercel.json index 3392afe3ea..49a7583b03 100644 --- a/vercel.json +++ b/vercel.json @@ -220,6 +220,11 @@ "destination": "/(docs/launch-arbitrum-chain/configure-your-chain/common-configurations/arbitrum-chain-finality/?)", "permanent": false }, + { + "source": "/(docs/launch-arbitrum-chain/partials/config-rollup/?)", + "destination": "/(docs/launch-arbitrum-chain/features/partials/_rollup-pc/?)", + "permanent": false + }, { "source": "/(docs/launch-arbitrum-chain/timeboost-for-arbitrum-chains/?)", "destination": "/(docs/launch-arbitrum-chain/configure-your-chain/common-configurations/timeboost-for-arbitrum-chains/?)", From 728c4fe6f1f43ddb82ba6ed1fec0ec1f125c116f Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 09:16:43 -0600 Subject: [PATCH 08/61] Added partial for Anytrust; added renderer --- .../data-availability/choose-anytrust.mdx | 10 ++++------ .../features/partials/_anytrust-pc.mdx | 16 ++++++++++++++++ .../partials/config-anytrust.mdx | 17 ++--------------- src/components/FloatingHoverModal/index.js | 2 +- 4 files changed, 23 insertions(+), 22 deletions(-) create mode 100644 docs/launch-arbitrum-chain/features/partials/_anytrust-pc.mdx diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx index 3fa680420a..265426ac37 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx @@ -6,6 +6,8 @@ sme: content_type: configuration --- +import AnytrustPCPartial from '../../partials/_anytrust-pc.mdx'; + Choosing AnyTrust mode refers to selecting the AnyTrust protocol as the data availability (DA) mechanism for a chain, such as when deploying custom chains via Arbitrum Orbit. AnyTrust is an alternative to the pure Rollup mode, prioritizing cost efficiency and performance over maximum decentralization. Opting for AnyTrust means configuring your Arbitrum-based chain to use this DA approach for reduced operational costs and better scalability, while accepting a slight trade-off in trust-minimization compared to posting all data directly to L1 (as in Rollup mode). @@ -20,12 +22,8 @@ It's ideal for use cases where ultra-low fees are a priority over Ethereum's ful - The DAC stores the data and signs a Data Availability Certificate (DACert), which posts to the parent chain (Ethereum L1). Full data is not posted onchain unless requested (e.g., during a challenge). - Security relies on a "keyset" where at least two honest members are assumed to prevent data withholding—far milder than centralized assumptions but not fully trustless like Rollup mode. -## Pros - -With up to 90% lower fees, higher throughput, and faster finality, it is suitable for high-volume, low-value applications like gaming or social dApps. - -## Cons + -Introduces a trust assumption in the DAC, which could be a vector for censorship or failure if too many members collude (though mitigated by requiring only a small honest minority). + This option reflects the growing trend toward modular blockchain architectures, where DA handling is separate to scale ecosystems like Arbitrum without compromising core security. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/partials/_anytrust-pc.mdx b/docs/launch-arbitrum-chain/features/partials/_anytrust-pc.mdx new file mode 100644 index 0000000000..ef008bcdf5 --- /dev/null +++ b/docs/launch-arbitrum-chain/features/partials/_anytrust-pc.mdx @@ -0,0 +1,16 @@ +## Pros + +- **Ultra-low transaction fees**: By offloading data availability to a Data Availability Committee (DAC) instead of posting all transaction data directly to Ethereum L1, AnyTrust significantly reduces costs, making micro-transactions viable. +- **Higher throughput and speed**: Supports a much larger volume of transactions per second compared to traditional rollups, ideal for high-frequency applications. +- **Faster withdrawals**: Withdrawals to Ethereum can occur immediately if vouched for by the DAC, avoiding the typical seven-day challenge period. +- **Minimal trust assumptions with strong feedback**: Requires only a small number of honest DAC members for normal operation, which is less trust-intensive. If the DAC fails, it automatically falls back to rollup mode, posting data to Ethereum for security. +- **Customization**: Enables flexible configurations like custom gas tokens, governance, and execution logic while inheriting low-cost benefits. +- **Ideal for specific use cases**: Best for high-volume, low-value applications such as Web3 gaming, decentralized social media, NFT platforms, and micro-payment systems where cost efficiency outweighs maximum decentralization. + +## Cons + +- **Introduced trust assumptions**: Relies on the DAC's honesty and availability, which adds a layer of trust not present in full trustless Rollups. This trust assumption could be a risk if committee members collude or fail. +- **Reduced decentralization and security guarantees**: Lacks the full trustlessness, permissionlessness, and censorship resistance of Rollups, as not all data is posted to Ethereum by default. This lack of data posting makes it less suitable for high-value DeFi or applications requiring Ethereum-level security. +- **Potential for fallback mode issues**: If the DAC cannot come to a quorum, the chain reverts to Rollup mode, which could increase costs temporarily and introduce delays similar to standard Rollups. +- **Liquidity and adoption changes**: May face lower liquidity or ecosystem integration compared to Rollup-based chains like Arbitrum One, potentially limiting interoperability with certain apps. +- **Not optimal for all use cases**: For applications handling significant financial value or needing maximum security, the trade-offs in decentralization could outweigh the benefits. diff --git a/docs/launch-arbitrum-chain/partials/config-anytrust.mdx b/docs/launch-arbitrum-chain/partials/config-anytrust.mdx index 3f693b10ad..a42c0a9c17 100644 --- a/docs/launch-arbitrum-chain/partials/config-anytrust.mdx +++ b/docs/launch-arbitrum-chain/partials/config-anytrust.mdx @@ -1,16 +1,3 @@ -## Pros of using AnyTrust +import AnytrustPCPartial from '../../partials/_anytrust-pc.mdx'; -- **Ultra-low transaction fees**: By offloading data availability to a Data Availability Committee (DAC) instead of posting all transaction data directly to Ethereum L1, AnyTrust significantly reduces costs, making micro-transactions viable. -- **Higher throughput and speed**: Supports a much larger volume of transactions per second compared to traditional rollups, ideal for high-frequency applications. -- **Faster withdrawals**: Withdrawals to Ethereum can occur immediately if vouched for by the DAC, avoiding the typical seven-day challenge period. -- **Minimal trust assumptions with strong feedback**: Requires only a small number of honest DAC members for normal operation, which is less trust-intensive. If the DAC fails, it automatically falls back to rollup mode, posting data to Ethereum for security. -- **Customization**: Enables flexible configurations like custom gas tokens, governance, and execution logic while inheriting low-cost benefits. -- **Ideal for specific use cases**: Best for high-volume, low-value applications such as Web3 gaming, decentralized social media, NFT platforms, and micro-payment systems where cost efficiency outweighs maximum decentralization. - -## Cons of using AnyTrust - -- **Introduced trust assumptions**: Relies on the DAC's honesty and availability, which adds a layer of trust not present in full trustless Rollups. This trust assumption could be a risk if committee members collude or fail. -- **Reduced decentralization and security guarantees**: Lacks the full trustlessness, permissionlessness, and censorship resistance of Rollups, as not all data is posted to Ethereum by default. This lack of data posting makes it less suitable for high-value DeFi or applications requiring Ethereum-level security. -- **Potential for fallback mode issues**: If the DAC cannot come to a quorum, the chain reverts to Rollup mode, which could increase costs temporarily and introduce delays similar to standard Rollups. -- **Liquidity and adoption changes**: May face lower liquidity or ecosystem integration compared to Rollup-based chains like Arbitrum One, potentially limiting interoperability with certain apps. -- **Not optimal for all use cases**: For applications handling significant financial value or needing maximum security, the trade-offs in decentralization could outweigh the benefits. + diff --git a/src/components/FloatingHoverModal/index.js b/src/components/FloatingHoverModal/index.js index 9a6873bcc1..3a42887d1c 100644 --- a/src/components/FloatingHoverModal/index.js +++ b/src/components/FloatingHoverModal/index.js @@ -24,7 +24,7 @@ import ConfigDedicatedThroughput from '@site/docs/launch-arbitrum-chain/partials import ConfigNativeEth from '@site/docs/launch-arbitrum-chain/partials/config-native-eth.mdx'; import ConfigHardware from '@site/docs/launch-arbitrum-chain/partials/config-hardware.mdx'; import ConfigRollup from '@site/docs/launch-arbitrum-chain/features/partials/_rollup-pc.mdx'; -import ConfigAnytrust from '@site/docs/launch-arbitrum-chain/partials/config-anytrust.mdx'; +import ConfigAnytrust from '@site/docs/launch-arbitrum-chain/features/partials/_anytrust-pc.mdx'; import ConfigFastwithdrawals from '@site/docs/launch-arbitrum-chain/partials/config-fast-withdrawals.mdx'; import ConfigTimeboost from '@site/docs/launch-arbitrum-chain/features/partials/_timeboost-pc.mdx'; import ConfigBold from '@site/docs/launch-arbitrum-chain/features/partials/_bold-pc.mdx'; From 8797f16c25fb2f85f06f6612bec757b3bae2ca00 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 09:18:25 -0600 Subject: [PATCH 09/61] removing old anytrust modal --- docs/launch-arbitrum-chain/partials/config-anytrust.mdx | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 docs/launch-arbitrum-chain/partials/config-anytrust.mdx diff --git a/docs/launch-arbitrum-chain/partials/config-anytrust.mdx b/docs/launch-arbitrum-chain/partials/config-anytrust.mdx deleted file mode 100644 index a42c0a9c17..0000000000 --- a/docs/launch-arbitrum-chain/partials/config-anytrust.mdx +++ /dev/null @@ -1,3 +0,0 @@ -import AnytrustPCPartial from '../../partials/_anytrust-pc.mdx'; - - From b22eb1087b8ec87db21b288472d80176b11c7adf Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 09:22:37 -0600 Subject: [PATCH 10/61] Added partial for Alt-DA; added renderer --- .../common/data-availability/choose-alt-da.mdx | 14 ++++---------- .../partials/_alt-da-pc.mdx} | 6 ++---- src/components/FloatingHoverModal/index.js | 2 +- 3 files changed, 7 insertions(+), 15 deletions(-) rename docs/launch-arbitrum-chain/{partials/config-alt-da.mdx => features/partials/_alt-da-pc.mdx} (78%) diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx index 0c6daba10c..a571e026dd 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx @@ -6,6 +6,8 @@ sme: content_type: configuration --- +import AltDAPCPartial from '../../partials/_alt-da-pc.mdx'; + Choosing alternative data availability (Alt-DA) refers to configuring the chain to use a third-party data availability layer instead of Arbitrum's native options. This feature allows developers to post transaction batch data to external DA providers for storage and accessibility, rather than relying solely on Ethereum (L1) or Arbitrum's built-in mechanisms. Alt-DA integrations expand the flexibility of the Arbitrum Nitro stack, enabling optimized trade-offs in cost, scalability, and security. Selecting Alt-DA means integrating an external provider into your Orbit chain's configuration, often via modifications to the Nitro software stack. Developers can also set fallback preferences (e.g., try Alt-DA first, then AnyTrust, then Ethereum) to ensure resilience if the primary DA fails. This choice is ideal for applications prioritizing ultra-low fees and massive scalability, such as gaming, social, or data-intensive dApps, where the cost of posting to Ethereum would be prohibitive. @@ -20,17 +22,9 @@ Selecting Alt-DA means integrating an external provider into your Orbit chain's - From **Rollup**: Alt-DA moves data off Ethereum entirely, avoiding L1 gas costs but potentially sacrificing some decentralization if the external layer has different security properties (e.g., Celestia uses data availability sampling for efficiency). - From **AnyTrust**: While both are off-chain, AnyTrust uses Arbitrum's own DAC (permissioned and integrated), whereas Alt-DA leverages independent networks with their own consensus and incentives, offering more modularity but requiring additional setup and trust in the provider's model. -## Pros - -- Dramatically lower costs (e.g., up to orders of magnitude cheaper than L1 posting) and higher throughput. -- Modular design allows specialization (e.g., Celestia focuses solely on DA for efficiency). -- Fallback mechanisms enhance reliability. - -## Cons + -- Introduces new trust assumptions based on the provider (e.g., reliance on the external layer's validators or sampling protocols). -- Potential for integration complexity, including custom code and bridges for proofs. -- May have varying uptime or finality compared to native options. + ## Examples of Alt-DA Providers diff --git a/docs/launch-arbitrum-chain/partials/config-alt-da.mdx b/docs/launch-arbitrum-chain/features/partials/_alt-da-pc.mdx similarity index 78% rename from docs/launch-arbitrum-chain/partials/config-alt-da.mdx rename to docs/launch-arbitrum-chain/features/partials/_alt-da-pc.mdx index 76cf7f86dd..7f9fc14513 100644 --- a/docs/launch-arbitrum-chain/partials/config-alt-da.mdx +++ b/docs/launch-arbitrum-chain/features/partials/_alt-da-pc.mdx @@ -1,6 +1,4 @@ -Arbitrum (Orbit) chains allow companies to launch custom Layer 2 (L2) or Layer 3 (L3) chains using the Arbitrum technology stack. By default, chains can utilize Ethereum for data availability (DA). Still, there is support for alternative DA (Alt-DA) options, such as third-party solutions like Celestia, EigenDA, Avail, or NEAR DA, or Arbitrum's AnyTrust mode, which relies on a Data Availability Committee (DAC). Alt-DA offloads transaction data posting from Ethereum to these alternatives, aiming to optimize for cost and performance. Below are the key pros and cons of using an Alt-DA for an Arbitrum Orbit chain: - -### Pros +## Pros - **Significant cost savings**: Using an Alt-DA can reduce DA fees by 75-95% compared to posting data directly to Ethereum, making it an ideal solution for high-volume or cost-sensitive applications, such as gaming, social platforms, or AI agents. For instance, over 95% of rollup costs often stem from Ethereum DA, and alternatives like Celestia or NEAR DA offer transactions up to 100x cheaper. - **Improved throughput and scalability**: By separating DA from Ethereum's blockspace constraints, Alt-DA enables higher transaction volumes and better handles data-intensive use cases. @@ -8,7 +6,7 @@ Arbitrum (Orbit) chains allow companies to launch custom Layer 2 (L2) or Layer 3 - **Reduced trust assumptions in some cases**: Compared to a DAC in AnyTrust mode, a decentralized Alt-DA like Avail can lower reliance on a small committee by using broader validator sets (e.g., up to 1,000 validators) and mathematical proofs for DA guarantees. - **Predictable performance**: Alt-DA often provides stable fees and fast finality, with fallbacks (e.g., Ethereum) to maintain uptime, benefitting consumer-facing apps. -### Cons +## Cons - **Trade-offs in security and trust**: Alt-DA may introduce mild trust assumptions or different security models (e.g., relying on the Alt-DA network's consensus mechanism), which are potentially less robust than Ethereum's onchain DA, which inherits Ethereum's anti-censorship and verifiability features. This trade-off makes it less suitable for high-total-value-locked (TVL) applications that require maximal decentralization. - **Operational complexity**: Implementing Alt-DA requires additional monitoring, alerting, data retention policies, and integration efforts (e.g., modifying batchers or bridgers), which increases overhead for development teams and demands operational maturity. diff --git a/src/components/FloatingHoverModal/index.js b/src/components/FloatingHoverModal/index.js index 3a42887d1c..373af0f115 100644 --- a/src/components/FloatingHoverModal/index.js +++ b/src/components/FloatingHoverModal/index.js @@ -19,7 +19,7 @@ import './styles.css'; // Import all config partials statically to avoid CSP issues import ConfigCustomGasToken from '@site/docs/launch-arbitrum-chain/partials/config-custom-gas-token.mdx'; -import ConfigAltDa from '@site/docs/launch-arbitrum-chain/partials/config-alt-da.mdx'; +import ConfigAltDa from '@site/docs/launch-arbitrum-chain/features/partials/_alt-da-pc.mdx'; import ConfigDedicatedThroughput from '@site/docs/launch-arbitrum-chain/partials/config-dedicated-throughput.mdx'; import ConfigNativeEth from '@site/docs/launch-arbitrum-chain/partials/config-native-eth.mdx'; import ConfigHardware from '@site/docs/launch-arbitrum-chain/partials/config-hardware.mdx'; From ac3f838d9b318320bbf345563addc1d33ab1e552 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 09:22:56 -0600 Subject: [PATCH 11/61] redirect vercel.json --- vercel.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/vercel.json b/vercel.json index 49a7583b03..f97cb41c51 100644 --- a/vercel.json +++ b/vercel.json @@ -220,6 +220,11 @@ "destination": "/(docs/launch-arbitrum-chain/configure-your-chain/common-configurations/arbitrum-chain-finality/?)", "permanent": false }, + { + "source": "/(docs/launch-arbitrum-chain/partials/config-alt-da/?)", + "destination": "/(docs/launch-arbitrum-chain/features/partials/_alt-da-pc/?)", + "permanent": false + }, { "source": "/(docs/launch-arbitrum-chain/partials/config-rollup/?)", "destination": "/(docs/launch-arbitrum-chain/features/partials/_rollup-pc/?)", From 408271850f0e5a8958dee993d221e66d9ddcfebf Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 09:30:00 -0600 Subject: [PATCH 12/61] Adding partial for fast withdrawals; added renderer --- .../features/common/ux/choose-fast-withdrawals.mdx | 14 ++++---------- .../partials/_fast-withdrawals-pc.mdx} | 0 src/components/FloatingHoverModal/index.js | 2 +- 3 files changed, 5 insertions(+), 11 deletions(-) rename docs/launch-arbitrum-chain/{partials/config-fast-withdrawals.mdx => features/partials/_fast-withdrawals-pc.mdx} (100%) diff --git a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx index b6a26cbc90..2950dc372d 100644 --- a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx +++ b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx @@ -6,6 +6,8 @@ sme: content_type: configuration --- +import FastwithdrawalsPCPartial from '../../partials/_fast-withdrawals_-pc.mdx'; + Enabling fast withdrawals refers to configuring the chain to use a fast confirmation mechanism that allows transactions and state assertions to achieve finality much quicker than the standard multi-day challenge period in optimistic rollups. This is achieved by routing assertions through a permissioned committee of validators (often overlapping with the Data Availability Committee or DAC in AnyTrust mode) that unanimously confirms them via a multisig wallet, bypassing the full fraud-proof window. As a result, users can withdraw assets or access finalized states in as little as 15 minutes for L2 chains or 15 seconds for L3 chains, significantly enhancing user experience by reducing wait times and enabling faster cross-chain interactions. Enabling this feature shifts the chain from relying solely on time-based fraud proofs to a committee-driven confirmation process, where validators (recommended to be at least three for reduced trust risks) must agree unanimously. It's primarily recommended for AnyTrust chains, as it leverages the existing DAC trust model without adding new assumptions—ideally, DAC members run the validators. @@ -25,17 +27,9 @@ For pure Rollup chains, enabling it effectively introduces a committee trust lay - **Gas Tokens**: No restrictions; compatible with native `ETH` or custom `ERC-20`s. - **Parent Chain**: Frequency must exceed the parent's finality time (e.g., >12.8 minutes for Ethereum L2s). -## Pros - -- Dramatically faster finality (15s-15m vs. days), improving UX for withdrawals and dApps. -- Configurable frequency for tailored performance. -- No new trust if validators are DAC members in AnyTrust. - -## Cons + -- Introduces reliance on a unanimous committee, potentially increasing trust assumptions (mitigated with ≥3 members). -- Minor delays possible under high load; initial backlog post-enable. -- Not ideal for pure Rollups; requires upgrades and careful parent-chain alignment. + ## Impact on User Experience diff --git a/docs/launch-arbitrum-chain/partials/config-fast-withdrawals.mdx b/docs/launch-arbitrum-chain/features/partials/_fast-withdrawals-pc.mdx similarity index 100% rename from docs/launch-arbitrum-chain/partials/config-fast-withdrawals.mdx rename to docs/launch-arbitrum-chain/features/partials/_fast-withdrawals-pc.mdx diff --git a/src/components/FloatingHoverModal/index.js b/src/components/FloatingHoverModal/index.js index 373af0f115..e5addbd264 100644 --- a/src/components/FloatingHoverModal/index.js +++ b/src/components/FloatingHoverModal/index.js @@ -25,7 +25,7 @@ import ConfigNativeEth from '@site/docs/launch-arbitrum-chain/partials/config-na import ConfigHardware from '@site/docs/launch-arbitrum-chain/partials/config-hardware.mdx'; import ConfigRollup from '@site/docs/launch-arbitrum-chain/features/partials/_rollup-pc.mdx'; import ConfigAnytrust from '@site/docs/launch-arbitrum-chain/features/partials/_anytrust-pc.mdx'; -import ConfigFastwithdrawals from '@site/docs/launch-arbitrum-chain/partials/config-fast-withdrawals.mdx'; +import ConfigFastwithdrawals from '@site/docs/launch-arbitrum-chain/features/partials/_fast-withdrawals-pc.mdx'; import ConfigTimeboost from '@site/docs/launch-arbitrum-chain/features/partials/_timeboost-pc.mdx'; import ConfigBold from '@site/docs/launch-arbitrum-chain/features/partials/_bold-pc.mdx'; import ConfigPermissionedValidators from '@site/docs/launch-arbitrum-chain/partials/config-permissioned-validators.mdx'; From dff39c803832bfee62cce2effe3c81ef7cfdb541 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 09:30:13 -0600 Subject: [PATCH 13/61] redirect vercel.json --- vercel.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/vercel.json b/vercel.json index f97cb41c51..0e2557a951 100644 --- a/vercel.json +++ b/vercel.json @@ -225,6 +225,11 @@ "destination": "/(docs/launch-arbitrum-chain/features/partials/_alt-da-pc/?)", "permanent": false }, + { + "source": "/(docs/launch-arbitrum-chain/partials/config-fast-withdrawals/?)", + "destination": "/(docs/launch-arbitrum-chain/features/partials/_fast-withdrawals-pc/?)", + "permanent": false + }, { "source": "/(docs/launch-arbitrum-chain/partials/config-rollup/?)", "destination": "/(docs/launch-arbitrum-chain/features/partials/_rollup-pc/?)", From 143f3acdb2d22334b48460eefc7cb923818350ea Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 09:31:59 -0600 Subject: [PATCH 14/61] fixed path to fast withdrawal partial --- .../features/common/ux/choose-fast-withdrawals.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx index 2950dc372d..d877764f55 100644 --- a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx +++ b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx @@ -6,7 +6,7 @@ sme: content_type: configuration --- -import FastwithdrawalsPCPartial from '../../partials/_fast-withdrawals_-pc.mdx'; +import FastwithdrawalsPCPartial from '../../partials/_fast-withdrawals-pc.mdx'; Enabling fast withdrawals refers to configuring the chain to use a fast confirmation mechanism that allows transactions and state assertions to achieve finality much quicker than the standard multi-day challenge period in optimistic rollups. This is achieved by routing assertions through a permissioned committee of validators (often overlapping with the Data Availability Committee or DAC in AnyTrust mode) that unanimously confirms them via a multisig wallet, bypassing the full fraud-proof window. As a result, users can withdraw assets or access finalized states in as little as 15 minutes for L2 chains or 15 seconds for L3 chains, significantly enhancing user experience by reducing wait times and enabling faster cross-chain interactions. From 041759dbb55fe52c029eb426f859b2b533aa1977 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 09:55:08 -0600 Subject: [PATCH 15/61] Removing duplicates --- src/components/FloatingHoverModal/index.js | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/components/FloatingHoverModal/index.js b/src/components/FloatingHoverModal/index.js index e5addbd264..95c15274de 100644 --- a/src/components/FloatingHoverModal/index.js +++ b/src/components/FloatingHoverModal/index.js @@ -32,7 +32,6 @@ import ConfigPermissionedValidators from '@site/docs/launch-arbitrum-chain/parti import ConfigL1ChallengePeriod from '@site/docs/launch-arbitrum-chain/partials/config-l1-challenge-period.mdx'; import ConfigForceInclusion from '@site/docs/launch-arbitrum-chain/partials/config-force-inclusion.mdx'; import ConfigAccountAbstraction from '@site/docs/launch-arbitrum-chain/partials/config-account-abstraction.mdx'; -import ConfigChallengePeriod from '@site/docs/launch-arbitrum-chain/partials/config-challenge-period-l1.mdx'; import ConfigCustomizableGovernance from '@site/docs/launch-arbitrum-chain/partials/config-customizable-governance.mdx'; import ConfigDataPostingCosts from '@site/docs/launch-arbitrum-chain/partials/config-data-posting-costs.mdx'; import ConfigEVMCompatibility from '@site/docs/launch-arbitrum-chain/partials/config-evm-compatbility.mdx'; @@ -54,7 +53,6 @@ const contentMap = { 'config-l1-challenge-period': ConfigL1ChallengePeriod, 'config-force-inclusion': ConfigForceInclusion, 'config-account-abstraction': ConfigAccountAbstraction, - 'config-challenge-period-l1': ConfigChallengePeriod, 'config-customizable-governance': ConfigCustomizableGovernance, 'config-data-posting-costs': ConfigDataPostingCosts, 'config-evm-compatibility': ConfigEVMCompatibility, From d92b63966f431fca9294c03fd9b17cb91f08e8a5 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 10:20:09 -0600 Subject: [PATCH 16/61] Adding partial for permissioned validators; added renderer --- .../choose-permissioned-validators.mdx | 14 ++++---------- .../partials/_permissioned-validators-pc.mdx} | 2 -- src/components/FloatingHoverModal/index.js | 2 +- 3 files changed, 5 insertions(+), 13 deletions(-) rename docs/launch-arbitrum-chain/{partials/config-permissioned-validators.mdx => features/partials/_permissioned-validators-pc.mdx} (89%) diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx index 2955c3060d..a302f4b850 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx @@ -6,6 +6,8 @@ sme: content_type: configuration --- +import PermissionedValidatorsPCPartial from '../../partials/_permissioned-validators-pc.mdx'; + Choosing permissioned validators refers to configuring the chain to use a legacy dispute resolution protocol where only an allowlisted set of entities (e.g., approved by the chain owner or DAO) can participate in validation activities, such as posting state assertions, opening challenges, and resolving disputes. This contrasts with enabling the Bounded Liquidity Delay (BoLD) protocol for permissionless validation. The choice is made during chain deployment or via upgrades, often through governance, and prioritizes controlled oversight over broad decentralization. It's suitable for chains where limiting participants reduces operational complexity or economic risks, but it introduces trust assumptions in the allowlist. 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. @@ -21,17 +23,9 @@ This choice is configurable for all DA modes (Rollup, AnyTrust, Alt-DA) and gas Works with L2/L3 Arbitrum chains settling to Ethereum or other L2s. For AnyTrust chains (e.g., like Arbitrum Nova), validation typically remains permissioned even post-BoLD upgrades, as the Data Availability Committee (DAC) already introduces trust assumptions, and permissionless bonds could invite griefing attacks. -## Pros - -- **Controlled Security**: Easier to manage and audit a small, trusted group, reducing risks from unvetted participants or spam attacks on low-value chains. -- **Lower Barriers**: Avoids requiring massive bonds (e.g., thousands of ETH equivalents in BoLD), making it feasible for early-stage or niche Orbit chains without attracting centralized stakers. -- **Faster Setup**: Simpler for chains prioritizing speed over full decentralization, with potential for quicker withdrawals in trusted environments like AnyTrust. - -## Cons + -- **Centralization Risks**: Relies on the allowlist's integrity; collusion or downtime could compromise the chain without community backups. -- **Vulnerability to Delays**: Susceptible to "delay attacks" where malicious validators prolong disputes indefinitely, stalling confirmations and withdrawals (e.g., beyond the standard ~7-day window). -- **Limited Decentralization**: Prevents achieving "Stage 2" rollup status, as it doesn't allow unrestricted validation, potentially reducing user trust in high-value applications. + ## Examples diff --git a/docs/launch-arbitrum-chain/partials/config-permissioned-validators.mdx b/docs/launch-arbitrum-chain/features/partials/_permissioned-validators-pc.mdx similarity index 89% rename from docs/launch-arbitrum-chain/partials/config-permissioned-validators.mdx rename to docs/launch-arbitrum-chain/features/partials/_permissioned-validators-pc.mdx index 93bc88e167..b14a535b2a 100644 --- a/docs/launch-arbitrum-chain/partials/config-permissioned-validators.mdx +++ b/docs/launch-arbitrum-chain/features/partials/_permissioned-validators-pc.mdx @@ -1,5 +1,3 @@ -By default, Arbitrum chains can use permissioned validators, where only pre-approved entities can participate in validation (e.g., challenging state assertions). This model contrasts with permissionless validation, enabled via protocols like BoLD, which opens validation to anyone. - ## Pros - **Enhanced control and security in trusted environments**: Permissioned validators allow the chain owner to select and vet participants, reducing risks from unknown or malicious actors, which is ideal for enterprise or private chains where trust among validators is present, minimizing the chance of spam or uncoordinated attacks. diff --git a/src/components/FloatingHoverModal/index.js b/src/components/FloatingHoverModal/index.js index 95c15274de..9de63819ed 100644 --- a/src/components/FloatingHoverModal/index.js +++ b/src/components/FloatingHoverModal/index.js @@ -28,7 +28,7 @@ import ConfigAnytrust from '@site/docs/launch-arbitrum-chain/features/partials/_ import ConfigFastwithdrawals from '@site/docs/launch-arbitrum-chain/features/partials/_fast-withdrawals-pc.mdx'; import ConfigTimeboost from '@site/docs/launch-arbitrum-chain/features/partials/_timeboost-pc.mdx'; import ConfigBold from '@site/docs/launch-arbitrum-chain/features/partials/_bold-pc.mdx'; -import ConfigPermissionedValidators from '@site/docs/launch-arbitrum-chain/partials/config-permissioned-validators.mdx'; +import ConfigPermissionedValidators from '@site/docs/launch-arbitrum-chain/features/partials/_permissioned-validators-pc.mdx'; import ConfigL1ChallengePeriod from '@site/docs/launch-arbitrum-chain/partials/config-l1-challenge-period.mdx'; import ConfigForceInclusion from '@site/docs/launch-arbitrum-chain/partials/config-force-inclusion.mdx'; import ConfigAccountAbstraction from '@site/docs/launch-arbitrum-chain/partials/config-account-abstraction.mdx'; From 919042c766f515d99394650865def948ede1a9cc Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 10:20:25 -0600 Subject: [PATCH 17/61] redirect vercel.json --- vercel.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/vercel.json b/vercel.json index 0e2557a951..31512ac4ec 100644 --- a/vercel.json +++ b/vercel.json @@ -230,6 +230,11 @@ "destination": "/(docs/launch-arbitrum-chain/features/partials/_fast-withdrawals-pc/?)", "permanent": false }, + { + "source": "/(docs/launch-arbitrum-chain/partials/config-permissioned-validators/?)", + "destination": "/(docs/launch-arbitrum-chain/features/partials/_permissioned-validators-pc/?)", + "permanent": false + }, { "source": "/(docs/launch-arbitrum-chain/partials/config-rollup/?)", "destination": "/(docs/launch-arbitrum-chain/features/partials/_rollup-pc/?)", From b2bb746b6c472a80981c6fb12c96298ce29e26f0 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 10:29:19 -0600 Subject: [PATCH 18/61] Added partial for Native ETH; added renderer --- .../common/gas-and-fees/choose-native-eth.mdx | 14 ++++---------- .../partials/_native-eth-pc.mdx} | 0 src/components/FloatingHoverModal/index.js | 2 +- 3 files changed, 5 insertions(+), 11 deletions(-) rename docs/launch-arbitrum-chain/{partials/config-native-eth.mdx => features/partials/_native-eth-pc.mdx} (100%) diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx index bcd33537ab..0c6e2fb432 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx @@ -6,6 +6,8 @@ sme: content_type: configuration --- +import NativeETHPCPartial from '../../partials/_native-eth-pc.mdx'; + Choosing native Ethereum refers to configuring the chain to use `ETH`—the native currency of Ethereum—as the gas token for paying transaction fees. This is the default option in Orbit deployments, in contrast to selecting a custom `ERC-20` token for gas. The choice is set during chain deployment via genesis parameters and is immutable afterward, directly impacting how users pay for gas and how operators handle revenue and costs. Selecting native `ETH` means users must hold and spend `ETH` for all onchain activities, simplifying the fee mechanism without additional layers like token swaps or pricers. For operators, revenue is collected directly in `ETH`, which can be used seamlessly for data availability (DA) costs on the parent chain (e.g., posting to Ethereum). @@ -33,17 +35,9 @@ This option prioritizes straightforward integration with Ethereum's ecosystem, a - **Custom Tokens**: Fees are paid in an `ERC-20` (e.g., `USDC` or a project token), requiring users to hold that token instead of `ETH`. Operators must convert collected tokens to `ETH` for DA costs, which introduces volatility risks and necessitates mechanisms like pricer contracts for exchange rates. - **Native `ETH`**: Eliminates conversions, swaps, and associated risks, but requires users to manage `ETH` specifically for gas, which may not align with app-specific ecosystems. -## Pros - -- **Simplicity and Low Risk**: No need for token conversions, hedging, or pricers, reducing operational complexity and economic losses from volatility. -- **Seamless Ethereum Integration**: Direct compatibility with Ethereum DA and broader tools, making it easier for `ETH`-centric users and developers. -- **Predictable Revenue**: Operators receive `ETH` directly, usable without intermediaries. - -## Cons + -- **User Friction**: Requires holding `ETH` even in ecosystems where it's not otherwise needed (e.g., gaming appchains), potentially complicating onboarding. -- **Limited Tokenomics**: Doesn't create demand for project-specific tokens, missing opportunities for ecosystem utility or incentives like airdrops. -- **Volatility Exposure**: Fees in `ETH` can fluctuate with market prices, affecting user costs without stablecoin benefits. + ## Examples diff --git a/docs/launch-arbitrum-chain/partials/config-native-eth.mdx b/docs/launch-arbitrum-chain/features/partials/_native-eth-pc.mdx similarity index 100% rename from docs/launch-arbitrum-chain/partials/config-native-eth.mdx rename to docs/launch-arbitrum-chain/features/partials/_native-eth-pc.mdx diff --git a/src/components/FloatingHoverModal/index.js b/src/components/FloatingHoverModal/index.js index 9de63819ed..a8b0b38753 100644 --- a/src/components/FloatingHoverModal/index.js +++ b/src/components/FloatingHoverModal/index.js @@ -21,7 +21,7 @@ import './styles.css'; import ConfigCustomGasToken from '@site/docs/launch-arbitrum-chain/partials/config-custom-gas-token.mdx'; import ConfigAltDa from '@site/docs/launch-arbitrum-chain/features/partials/_alt-da-pc.mdx'; import ConfigDedicatedThroughput from '@site/docs/launch-arbitrum-chain/partials/config-dedicated-throughput.mdx'; -import ConfigNativeEth from '@site/docs/launch-arbitrum-chain/partials/config-native-eth.mdx'; +import ConfigNativeEth from '@site/docs/launch-arbitrum-chain/features/partials/_native-eth-pc.mdx'; import ConfigHardware from '@site/docs/launch-arbitrum-chain/partials/config-hardware.mdx'; import ConfigRollup from '@site/docs/launch-arbitrum-chain/features/partials/_rollup-pc.mdx'; import ConfigAnytrust from '@site/docs/launch-arbitrum-chain/features/partials/_anytrust-pc.mdx'; From 0ee69af8b87a7dac4016e53f197b893da2560072 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 10:29:30 -0600 Subject: [PATCH 19/61] Redirect vercel.json --- vercel.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/vercel.json b/vercel.json index 31512ac4ec..88e7946da9 100644 --- a/vercel.json +++ b/vercel.json @@ -230,6 +230,11 @@ "destination": "/(docs/launch-arbitrum-chain/features/partials/_fast-withdrawals-pc/?)", "permanent": false }, + { + "source": "/(docs/launch-arbitrum-chain/partials/config-native-eth/?)", + "destination": "/(docs/launch-arbitrum-chain/features/partials/_native-eth-pc/?)", + "permanent": false + }, { "source": "/(docs/launch-arbitrum-chain/partials/config-permissioned-validators/?)", "destination": "/(docs/launch-arbitrum-chain/features/partials/_permissioned-validators-pc/?)", From 657d863313bee7ed2abbd24e6dbad4bed0c68aed Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 10:34:00 -0600 Subject: [PATCH 20/61] Added partial for Custom Gas Token; added renderer --- .../gas-and-fees/choose-custom-gas-token.mdx | 16 ++++------------ .../partials/_custom-gas-token-pc.mdx} | 6 ++---- src/components/FloatingHoverModal/index.js | 2 +- 3 files changed, 7 insertions(+), 17 deletions(-) rename docs/launch-arbitrum-chain/{partials/config-custom-gas-token.mdx => features/partials/_custom-gas-token-pc.mdx} (95%) diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx index 77909524f1..7580780076 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx @@ -6,6 +6,8 @@ sme: content_type: configuration --- +import CustomGasTokenPCPartial from '../../partials/_custom-gas-token-pc.mdx'; + Choosing a custom gas token refers to configuring the chain to use a specific `ERC-20` token—rather than `ETH`—as the native currency for paying transaction fees (gas costs) on your chain. This allows developers to tailor the fee structure to their project's ecosystem, such as using a stablecoin like `USDC`, a yield-bearing asset, or the project's own native token. The choice is made during chain deployment and is generally immutable afterward, integrating directly into the chain's genesis parameters. ## Key Concepts @@ -23,19 +25,9 @@ Choosing a custom gas token refers to configuring the chain to use a specific `E - **AnyTrust Mode**: Directly supported with simpler configuration (no heavy pricer emphasis), ideal for cost-sensitive setups. - **Alt-DA (Alternative Data Availability)**: Compatible, especially with cheaper DA providers like Celestia or EigenDA, which reduce conversion risks from token volatility. -## Pros - -- Enhances token utility and ecosystem alignment (e.g., demand sink for project tokens). -- Improves user experience by avoiding `ETH` dependency and enabling stable or yield-bearing fees. -- Supports onboarding strategies like airdrops and compliance via token controls. -- More feasible with low-cost DA, minimizing economic risks. - -## Cons + -- Adds deployment and operational complexity (e.g., pricers, funding for conversions). -- Introduces risks from exchange rate fluctuations, potentially causing losses for operators or higher fees for users. -- Immutable post-deployment; token must adhere to strict standards. -- Not ideal for high-volatility tokens without hedging, especially on expensive DA like Ethereum mainnet. + ## Examples diff --git a/docs/launch-arbitrum-chain/partials/config-custom-gas-token.mdx b/docs/launch-arbitrum-chain/features/partials/_custom-gas-token-pc.mdx similarity index 95% rename from docs/launch-arbitrum-chain/partials/config-custom-gas-token.mdx rename to docs/launch-arbitrum-chain/features/partials/_custom-gas-token-pc.mdx index ee1aa98891..169dd2886d 100644 --- a/docs/launch-arbitrum-chain/partials/config-custom-gas-token.mdx +++ b/docs/launch-arbitrum-chain/features/partials/_custom-gas-token-pc.mdx @@ -1,6 +1,4 @@ -One key feature is the ability to use an `ERC-20` token (other than `ETH`) as the native gas token for transaction fees. - -### Pros +## Pros - **Enhanced token utility and demand**: Using a custom `ERC-20` token for gas fees creates inherent utility and constant demand for the project's native token, driving value accrual through practical use rather than speculation. This utility is particularly beneficial for ecosystems like gaming or DeFi, where it can support in-app economies and incentivize network participation. - **Internalized economic value**: Retention of transaction fees within the ecosystem, creating a sustainable model where the community captures the value generated by network activity, rather than relying on external tokens like `ETH`. @@ -9,7 +7,7 @@ One key feature is the ability to use an `ERC-20` token (other than `ETH`) as th - **Stability and predictability (with stablecoins)**: Using a stable token like USDC mitigates volatility in transaction costs compared to `ETH`, providing consistent and affordable fees. - **Integration with existing tools**: Native implementation in Arbitrum Orbit ensures compatibility with EVM tooling, deterministic gas accounting, and seamless deployment. -### Cons +## Cons - **Limited Flexibility (Native Implementation)**: Once deployed, it's difficult to support multiple gas tokens or switch tokens, requiring users to acquire the specific `ERC-20` token, which can complicate onboarding and limit ecosystem diversity. - **Potential sell pressure and economic risks**: Fees must be converted to the parent chain's token (e.g., `ETH`) for data availability costs, creating systematic sell pressure on the custom token. Significant price declines (e.g., 50%) could lead to operational deficits, necessitating advanced economic modeling for forecasting, hedging, and reserve management. diff --git a/src/components/FloatingHoverModal/index.js b/src/components/FloatingHoverModal/index.js index a8b0b38753..bf86b3824e 100644 --- a/src/components/FloatingHoverModal/index.js +++ b/src/components/FloatingHoverModal/index.js @@ -18,7 +18,7 @@ import { MDXProvider } from '@mdx-js/react'; import './styles.css'; // Import all config partials statically to avoid CSP issues -import ConfigCustomGasToken from '@site/docs/launch-arbitrum-chain/partials/config-custom-gas-token.mdx'; +import ConfigCustomGasToken from '@site/docs/launch-arbitrum-chain/features/partials/_custom-gas-token-pc.mdx'; import ConfigAltDa from '@site/docs/launch-arbitrum-chain/features/partials/_alt-da-pc.mdx'; import ConfigDedicatedThroughput from '@site/docs/launch-arbitrum-chain/partials/config-dedicated-throughput.mdx'; import ConfigNativeEth from '@site/docs/launch-arbitrum-chain/features/partials/_native-eth-pc.mdx'; From 000e4ce9324fd31228ade92b7d77a9f60660354c Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 10:34:14 -0600 Subject: [PATCH 21/61] Redirect vercel.json --- vercel.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/vercel.json b/vercel.json index 88e7946da9..db9c4b32ab 100644 --- a/vercel.json +++ b/vercel.json @@ -225,6 +225,11 @@ "destination": "/(docs/launch-arbitrum-chain/features/partials/_alt-da-pc/?)", "permanent": false }, + { + "source": "/(docs/launch-arbitrum-chain/partials/config-custom-gas-token/?)", + "destination": "/(docs/launch-arbitrum-chain/features/partials/_custom-gas-token-pc/?)", + "permanent": false + }, { "source": "/(docs/launch-arbitrum-chain/partials/config-fast-withdrawals/?)", "destination": "/(docs/launch-arbitrum-chain/features/partials/_fast-withdrawals-pc/?)", From e89ad020e441a60577d4aed3d101de00cbc0588f Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 4 Nov 2025 12:35:09 -0600 Subject: [PATCH 22/61] Adding redirect to vercel.json --- vercel.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/vercel.json b/vercel.json index db9c4b32ab..4681cba355 100644 --- a/vercel.json +++ b/vercel.json @@ -225,6 +225,11 @@ "destination": "/(docs/launch-arbitrum-chain/features/partials/_alt-da-pc/?)", "permanent": false }, + { + "source": "/(docs/launch-arbitrum-chain/partials/config-anytrust/?)", + "destination": "/(docs/launch-arbitrum-chain/features/partials/_anytrust-pc/?)", + "permanent": false + }, { "source": "/(docs/launch-arbitrum-chain/partials/config-custom-gas-token/?)", "destination": "/(docs/launch-arbitrum-chain/features/partials/_custom-gas-token-pc/?)", From 881fa905f0ae2abc3372ba5efd56cc6b29730166 Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Thu, 6 Nov 2025 15:54:12 +0800 Subject: [PATCH 23/61] add version control note to docs --- .../05-customize-your-chain/customize-arbos.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/05-customize-your-chain/customize-arbos.mdx b/docs/launch-arbitrum-chain/05-customize-your-chain/customize-arbos.mdx index 8ec6dfa4fa..fd8694ff02 100644 --- a/docs/launch-arbitrum-chain/05-customize-your-chain/customize-arbos.mdx +++ b/docs/launch-arbitrum-chain/05-customize-your-chain/customize-arbos.mdx @@ -111,7 +111,7 @@ To prevent this, if you are using an external call to the precompile contract to [point 2](./customize-arbos.mdx#2-create-a-new-precompile-contract-on-a-specific-arbos-version) to set the activation time of the precompile contract method. If your nitro code needs to call this method to change the state, you can continue reading [point 4](./customize-arbos.mdx#4-any-changes-in-the-stf-logic-that-will-affect-the-final-execution-result). -### 4. Any changes in the STF logic that will affect the final execution result +### 4. Any changes in the STF logic that will affect the final execution result (ArbOS version control) If you change the logic in STF, it will cause the execution result of the transaction to be different, you need to keep the original execution logic and put the new logic into another branch. From bcba4b9af98906a9cf14b8481c18ac265b7a57aa Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Thu, 6 Nov 2025 15:56:56 +0800 Subject: [PATCH 24/61] add version control note --- .../features/advanced/choose-arbos-version.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx index ed9590bb83..ec33f093f0 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx @@ -13,7 +13,7 @@ Customizing the ArbOS version refers to modifying the Nitro codebase to introduc - **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. - **State Transition Function (STF)**: The deterministic process for computing new states from transactions. Customizations here (e.g., new logic or states) often necessitate an ArbOS upgrade to integrate changes into the replay binary used for fraud proofs. - **WASM Module Root**: A 32-byte hash of the STF's implementation (e.g., 0x8b104a2e80ac6165dc58b9048de12f301d70b02a0ab51396c22b4b4b802a16a4 for ArbOS 20). Customizations require updating this on the parent chain for validation compatibility. -- **Backward Compatibility**: Changes must preserve old block results; new features activate only post-upgrade via version gates (e.g., `if state.ArbOSVersion() >= targetVersion`). +- **Backward Compatibility**: Changes must preserve old block results; new features activate only post-upgrade via version gates (e.g., `if state.ArbOSVersion() >= targetVersion`). For more details, please refer to [ArbOS version control](/launch-arbitrum-chain/05-customize-your-chain/customize-arbos.mdx#4-any-changes-in-the-stf-logic-that-will-affect-the-final-execution-result-arbos-version-control). ### Compatibility From 1efa42d0233db8859cb5da82a94b0e22e58f5db4 Mon Sep 17 00:00:00 2001 From: Pete Date: Mon, 10 Nov 2025 10:59:32 -0600 Subject: [PATCH 25/61] Update docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../features/advanced/choose-chain-precompiles.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx index 6b61434db1..fbcda1b0ee 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx @@ -13,7 +13,7 @@ Customization allows developers to add new methods, events, gas logic, or state ## Key Concepts - **Precompiles in Arbitrum**: These are predefined contracts at fixed addresses that handle operations more efficiently than regular EVM code. Standard ones include ArbSys (for L1 interactions), ArbInfo (for balances and codes), and others for aggregation, retryables, or gas estimation. Customization builds on this by altering their behavior or adding new ones in the Nitro Go implementation. -- **Customization Scope**: Focuses on extending functionality without full EVM changes, such as adding utility methods (e.g., a greeting function) or integrating chain-specific state (e.g., a stored number). It doesn't alter core EVM opcodes but enhances system access. +- **Customization Scope**: Focuses on extending functionality without full EVM changes, such as adding utility methods (e.g., a local zk-proof function) or integrating chain-specific state (e.g., a stored bytes). It doesn't alter core EVM opcodes but enhances system access. ## Options for Customization From 3e747b518ce0428cca22b7a87fecc14263f6d9ea Mon Sep 17 00:00:00 2001 From: Pete Date: Mon, 10 Nov 2025 10:59:48 -0600 Subject: [PATCH 26/61] Update docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../features/advanced/choose-chain-precompiles.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx index fbcda1b0ee..ed6ece6deb 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx @@ -28,7 +28,7 @@ There are several approaches, each building on the Nitro codebase: ## Compatibility with Chain Types - Works with all Orbit DA modes (Rollup, AnyTrust, Alt-DA) and gas tokens (native ETH or custom), as it's a Nitro-level change. -- Compatible with BoLD or permissioned validation, but custom precompiles may require `eth_call` for view methods to avoid breaking block validation. +- Compatible with BoLD or permissioned validation. ## Pros From 517fb409023c39b6b0c788b86410a2296a18b61e Mon Sep 17 00:00:00 2001 From: Pete Date: Mon, 10 Nov 2025 11:00:53 -0600 Subject: [PATCH 27/61] Update docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../features/common/configure-aep/configure-aep-fees.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx index 4700518979..ee6b95ae60 100644 --- a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx +++ b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx @@ -42,7 +42,7 @@ The configuration ensures compliance with the AEP terms, streamlines reporting, ## How to configure 1. **Calculate Net Revenue**: Use tools or scripts to track total fees minus settlement costs (e.g., via on-chain queries or off-chain monitoring). For custom tokens, deploy a pricer contract to value fees in `ETH` equivalents. -2. **Deploy Fee Router**: Use the Orbit SDK script (e.g., `aep-fee-router.ts`) to deploy contracts like RewardDistributor on your chain. Set it as a fee collector (e.g., for surplus fees via `ArbOwner` precompile). +2. **Deploy Fee Router**: Use the Orbit SDK script (e.g., [`aep-fee-router`](https://github.com/OffchainLabs/arbitrum-orbit-sdk/tree/main/examples/setup-aep-fee-router)) to deploy contracts like RewardDistributor on your chain. Set it as a fee collector (e.g., for surplus fees via `ArbOwner` precompile). 3. **Route and Bridge Fees**: Configure the router to send the 10% share to Ethereum (e.g., via native bridges), then deposit to the DAO address on Arbitrum One. Use functions like `flushBeneficiaryBalance` for periodic transfers. 4. **Report Fees**: Submit quarterly reports to the Arbitrum Foundation, including calculations and proofs of payment, to maintain license compliance. From fc672c143a5faddfb73b8a957f8b9b5de193f3a1 Mon Sep 17 00:00:00 2001 From: Pete Date: Mon, 10 Nov 2025 11:01:11 -0600 Subject: [PATCH 28/61] Update docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../features/common/gas-and-fees/choose-fee-rebates.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx index db0a304d7b..be197b0a9a 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx @@ -48,7 +48,7 @@ Configuration requires chain owner privileges and can be done post-deployment us ## How to configure -1. **Set Fee Collectors**: Use the `ArbOwner` precompile (0x70) to assign addresses for each fee type (e.g., setInfraFeeAccount for Orbit base fees). Collectors can be simple addresses or smart contracts. +1. **Set Fee Collectors**: Use the `ArbOwner` and `ArbAggregator` precompile (0x70) to assign addresses for each fee type (e.g., setInfraFeeAccount for Orbit base fees). Collectors can be simple addresses or smart contracts. 2. **Deploy a Distributor Contract**: For rebates, deploy a contract like `RewardDistributor.sol` on the chain. Set recipients and proportions (e.g., 80% to treasury, 20% to user rebate pool using basis points). 3. **Assign Distributor as Collector**: Update the relevant fee collector to the distributor's address (e.g., via `setNetworkFeeAccount` for surplus fees). 4. **Trigger Distributions**: Call distributeRewards on the contract to execute rebates, specifying recipients and shares. From 3b21f1bf3fc0eb91e950792de64422d852f91950 Mon Sep 17 00:00:00 2001 From: Pete Date: Mon, 10 Nov 2025 11:01:27 -0600 Subject: [PATCH 29/61] Update docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../features/common/data-availability/choose-rollup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx index 5ca1aad174..e51bf6adde 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx @@ -16,7 +16,7 @@ This flexibility allows developers to tailor chains to specific needs while buil ## Key Concepts -- **Data Availability (DA) in Rollups**: DA ensures that all transaction data is publicly accessible 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. - **Arbitrum Rollup Mode**: - All batch transaction data is posted directly to the parent chain (Ethereum L1) as calldata or blobs. - This inherits Ethereum's full security and decentralization, with no additional trust assumptions—data is always available on-chain for anyone to access and verify. From bf9b6400b9766f4d7d0de4e011cb0713a09f2008 Mon Sep 17 00:00:00 2001 From: Pete Date: Mon, 10 Nov 2025 11:01:37 -0600 Subject: [PATCH 30/61] Update docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../features/common/gas-and-fees/choose-native-eth.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx index 0c6e2fb432..9cc886b2e8 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx @@ -17,7 +17,7 @@ This option prioritizes straightforward integration with Ethereum's ecosystem, a ## Key Concepts - **Gas and Fees in Arbitrum**: Gas measures computational work for transactions and executions, with fees equaling gas used times gas price. These cover sequencer operations, data posting to the parent chain (e.g., Ethereum), and network upkeep. In native `ETH` setups, all fees are denominated, paid, and settled in `ETH`. -- **Native `ETH` as Gas Token**: The chain validates transactions against users' `ETH` balances, deducting fees directly in `ETH`. No token conversions are needed, aligning the chain's economics with Ethereum's standard model. +- **Native `ETH` as Gas Token**: The chain executes transactions against users' `ETH` balances, deducting fees directly in `ETH`. No token conversions are needed, aligning the chain's economics with Ethereum's standard model. ## How Fees Are Handled From 2787bd91a7feb848c559d59766bea2e4d21a2c71 Mon Sep 17 00:00:00 2001 From: Pete Date: Mon, 10 Nov 2025 14:48:37 -0600 Subject: [PATCH 31/61] Update docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../features/common/configure-aep/configure-aep-fees.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx index ee6b95ae60..ee9fdb8088 100644 --- a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx +++ b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx @@ -43,7 +43,7 @@ The configuration ensures compliance with the AEP terms, streamlines reporting, 1. **Calculate Net Revenue**: Use tools or scripts to track total fees minus settlement costs (e.g., via on-chain queries or off-chain monitoring). For custom tokens, deploy a pricer contract to value fees in `ETH` equivalents. 2. **Deploy Fee Router**: Use the Orbit SDK script (e.g., [`aep-fee-router`](https://github.com/OffchainLabs/arbitrum-orbit-sdk/tree/main/examples/setup-aep-fee-router)) to deploy contracts like RewardDistributor on your chain. Set it as a fee collector (e.g., for surplus fees via `ArbOwner` precompile). -3. **Route and Bridge Fees**: Configure the router to send the 10% share to Ethereum (e.g., via native bridges), then deposit to the DAO address on Arbitrum One. Use functions like `flushBeneficiaryBalance` for periodic transfers. +3. **Route and Bridge Fees**: Configure the router to send the 10% share to Ethereum (e.g., via native bridges), then deposit to the DAO address on Arbitrum One. Use functions like `RewardDistributor.distributeRewards` for periodic transfers. 4. **Report Fees**: Submit quarterly reports to the Arbitrum Foundation, including calculations and proofs of payment, to maintain license compliance. This setup reflects Arbitrum's collaborative model, ensuring custom chains contribute back while benefiting from the ecosystem. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). From b0911ea28e59e0cd83ca3f532ad3d814ae36180e Mon Sep 17 00:00:00 2001 From: Pete Date: Mon, 10 Nov 2025 14:48:49 -0600 Subject: [PATCH 32/61] Update docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../features/common/data-availability/choose-anytrust.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx index 265426ac37..5841864028 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx @@ -19,7 +19,7 @@ It's ideal for use cases where ultra-low fees are a priority over Ethereum's ful - **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. - **AnyTrust Mode**: - Transaction data is initially submitted off-chain to a permissioned group of nodes called the Data Availability Committee (DAC), typically consisting of around 20 members (though configurable). - - The DAC stores the data and signs a Data Availability Certificate (DACert), which posts to the parent chain (Ethereum L1). Full data is not posted onchain unless requested (e.g., during a challenge). + - The DAC stores the data and signs a Data Availability Certificate (DACert), which posts to the parent chain. Full data is not posted onchain unless requested (e.g., during a challenge). - Security relies on a "keyset" where at least two honest members are assumed to prevent data withholding—far milder than centralized assumptions but not fully trustless like Rollup mode. From 94e97d1f2e6ad999d2f68873c153a7aa4c6f9d2b Mon Sep 17 00:00:00 2001 From: Pete Date: Mon, 10 Nov 2025 14:48:59 -0600 Subject: [PATCH 33/61] Update docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../features/common/ux/choose-fast-withdrawals.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx index d877764f55..a8323d23f2 100644 --- a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx +++ b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx @@ -47,6 +47,6 @@ From a UX perspective, enabling fast withdrawals transforms slow, multi-day proc 3. **Configure Nodes**: - Batch Poster: Set `--node.batch-poster.max-delay` to match the assertion period (e.g., 15m). - Validators (BoLD mode): Enable `--node.bold.enable-fast-confirmation=true` and set `--node.bold.assertion-posting-interval` to the period. - - Validators (pre-BoLD): Similar flags like `--node.staker.enable-fast-confirmation=true`. + - Validators (pre-BoLD): Similar flags like `--node.staker.enable-fast-confirmation=true` and `--node.staker.make-assertion-interval`. This feature aligns with Arbitrum's focus on scalable, user-friendly chains while maintaining core security. For setup, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). From 25a708a06c45012820be424891c6e677b8150f7f Mon Sep 17 00:00:00 2001 From: Pete Date: Mon, 10 Nov 2025 15:45:39 -0600 Subject: [PATCH 34/61] Addressing comments --- .../advanced/choose-chain-precompiles.mdx | 4 +- .../choose-custom-delay-inbox-finality.mdx | 76 +++++++++++-------- .../configure-aep/configure-aep-fees.mdx | 4 +- .../gas-and-fees/choose-fee-rebates.mdx | 7 +- .../choose-permissioned-validators.mdx | 12 +++ 5 files changed, 64 insertions(+), 39 deletions(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx index ed6ece6deb..e39e81b705 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx @@ -39,6 +39,7 @@ There are several approaches, each building on the Nitro codebase: ## Cons - Requires deep expertise in Go, Solidity, and Nitro; complex setup and maintenance. +- Customizing the precompiles will cause WASM module root changes, introducing additional modifications. - Risks include DoS vulnerabilities without proper gas implementation, security issues without audits, and potential validation breaks. - No official review from Offchain Labs; changes may complicate upgrades or fraud proofs. @@ -47,6 +48,7 @@ There are several approaches, each building on the Nitro codebase: - Adding a "sayHi" method to ArbSys that returns "hi" and emits a "Hi" event. - Creating a new ArbHi precompile with a gas-optimized balance query. - Storing and modifying a custom state variable like "myNumber" via a new method. +- Add a zk proof function so chains can process zk-related work more efficiently than EVM based options. ## How to configure @@ -54,7 +56,7 @@ Customizing requires building a modified Nitro node, as precompiles are part of 1. **Clone and Setup Nitro**: Use branch v3.7.2 or later (`git clone --branch v3.7.2 https://github.com/OffchainLabs/nitro.git`), then initialize submodules. 2. **Edit Go Files**: Modify `/precompiles` directory (e.g., add methods to ArbSys.go), register new precompiles in precompile.go, and for state changes, update arbosstate.go with variables, offsets, and initialization. -3. **Update Solidity Interfaces**: Add corresponding methods/events to .sol files in the precompiles interface directory for dApp compatibility. +3. **Update Solidity Interfaces**: Add corresponding methods/events to .sol files in the precompiles interface directory for dApp compatibility. Also, follow the steps in [Choose ArbOS version](/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx), as it will also modify the STF. 4. **Build and Run Node**: Compile a custom Docker image and run the node with your configurations (e.g., specifying parent chain URL and chain ID). Test with tools like curl for eth_call or Foundry's cast for calls/sends. 5. **Post-Launch Changes**: Use ArbOS version upgrades to apply without reorganizing the chain; follow related guides for fraud proofs. diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx index 499ccd597e..649060b9b7 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx @@ -6,50 +6,62 @@ sme: content_type: configuration --- -Customizing the ArbOS version involves modifying the Nitro codebase to introduce a new, version-controlled iteration of ArbOS (Arbitrum's operating system-like layer). This process activates custom behaviors, features, or state changes in a way that maintains backward compatibility and determinism for fraud proofs. +Configuring the delayed inbox finality refers to adjusting sequencer node flags to control the timing and dependencies for when transactions (e.g., cross-chain messages or deposits) sent through the Delayed Inbox achieve finality on the child chain. The Delayed Inbox is a fallback mechanism for parent-to-child communications that bypasses the sequencer for direct inclusion, ensuring censorship resistance. -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. +By default, finality for these transactions relies on layer-1 (L1) Ethereum block confirmations (typically tens of minutes). Configuration allows shifting to faster L2-based finality or reducing confirmation waits, trading speed for potential re-org risks. This reduction is an advanced sequencer-level setting, not a deployment-time parameter, and is primarily used to optimize bridging speed for use cases like high-frequency DeFi or gaming. -It's recommended for teams with expertise or partners (e.g., RaaS providers), as it requires audits, maintenance, and careful handling to avoid issues like chain re-orgs or failed fraud proofs. +## Key concepts -### Key Concepts +- **Delayed Inbox**: A contract on the parent chain where users can submit transactions (e.g., retryable tickets for token bridges or direct calls) to be force-included on the child chain if the sequencer delays them. These are held until the sequencer releases them based on parent chain progress. +- **Finality**: The point at which a Delayed Inbox transaction is irreversibly executable on the child chain. By default, this depends on L1 finality (e.g., Ethereum blocks confirming a batch from Arbitrum One or a Data Availability Certificate/DACert from Nova), taking ~10-60 minutes. +- **L2 vs. L1 Finality**: L3 chains can be configured to rely on the parent L2's quicker "soft finality" (~1-15 minutes) instead of waiting for deeper L1 confirmations, or to reduce L2 block waits for even faster processing. +- **Relevant Flags**: + - `--node.delayed-sequencer.use-merge-finality=false`: Disables L1 dependency, using only L2 finality. + - `--node.delayed-sequencer.finalize-distance=1`: Sets the number of L2 block confirmations needed (default is higher; 1 enables ~1-minute finality). -- **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 inspired by planetary moons (e.g., "Atlas" for 20, "Bianca" for 30). Custom versions can use intermediates (e.g., 21-29) for project-specific forks. -- **State Transition Function (STF)**: The deterministic process for computing new states from transactions. Customizations here (e.g., new logic or states) often necessitate an ArbOS upgrade to integrate changes into the replay binary used for fraud proofs. -- **WASM Module Root**: A 32-byte hash of the STF's implementation (e.g., `0x8b104a2e80ac6165dc58b9048de12f301d70b02a0ab51396c22b4b4b802a16a4` for ArbOS 20). Customizations require updating this on the parent chain for validation compatibility. -- **Backward compatibility**: Changes must preserve old block results; new features activate only post-upgrade via version gates (e.g., `if state.ArbOSVersion() >= targetVersion`). +## What It Means to Configure Delayed Inbox Finality -### Compatibility +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. -- Works with all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (BoLD/permissioned), as long as changes meet STF rules (deterministic, pure, < 1s/block). -- Backward-compatible by design; WASM roots support old versions. -- For public chains like One/Nova, requires DAO governance; Orbit chains have owner discretion. +:::note -### Pros +This affects only incoming (parent-to-child) Delayed Inbox flows; outgoing (child-to-parent) finality uses separate mechanisms, such as DAC in AnyTrust mode, for ~15-minute confirmations. -- Enables precise, version-gated customizations (e.g., new STF logic) for specialized chains. -- No downtime; upgrades bundle features seamlessly. -- Supports ecosystem alignment (e.g., adopting mainnet features post-delay). +::: -### Cons +### Configuration Process: -- Complexity and risks (e.g., re-orgs from improper state init, proof failures). -- Requires audits/maintenance; unintended intermediate features may activate. -- No Offchain Labs review; higher costs for expertise. +- **Prepare the Sequencer Node**: When running your Orbit chain's sequencer (e.g., via Docker or local build from Nitro source), add the flags to the startup command. Example for a Dockerized sequencer: + `docker run --rm -it -p 8547:8547 offchainlabs/nitro-node:v3.7.2 --chain.id=12345 --node.delayed-sequencer.use-merge-finality=false --node.delayed-sequencer.finalize-distance=1` +- Replace with your chain's parameters (e.g., parent chain URL). +- **Test and Deploy**: Verify in a devnet by submitting a Delayed Inbox transaction (e.g., via a token bridge) and monitoring release timing in logs. For production, ensure validators are updated to match the new behavior. +- **Monitor**: Use tools like chain explorers or sequencer logs to track finality times and re-org incidents. -### Examples +## How It Differs from Default -- **New Precompile Method**: Add `sayHi()` to ArbSys, gated by `ArbOwner.methodsByName["SayHi"].arbosVersion = 32`. -- **New Precompile**: Create ArbHi with `ArbHi.arbosVersion = 32` and method gates. -- **New State Variable**: Add `myNumber` initialized in `UpgradeArbosVersion` switch for v21: `ensure(state.SetNewMyNumber(randomNumber))`. -- **STF Logic Change**: Branch in a method: `if p.state.ArbOSVersion() >= 32 { return "hi, new version" } else { return "hi" }`. +- **Default (L1-Dependent)**: Relies on Ethereum L1 finality for batches/DACerts, ensuring maximum security but slower deposits (~tens of minutes). +- **Configured (L2-Only with Low Distance)**: Shifts to L2 soft finality and minimal confirmations, achieving ~1-minute deposits but introducing re-org risks if the parent L2 reverts unconfirmed blocks. -## How to configure +## Pros -1. **Clone and Modify Nitro**: Use a branch like v3.7.2 (`git clone --branch v3.7.2 https://github.com/OffchainLabs/nitro.git`). Edit files (e.g., precompile.go, arbosstate.go) to incorporate changes and add version gates. -2. **Build Custom Node**: Create Docker images, extract the new WASM module root, and update it on the parent chain via `setWasmModuleRoot` on the rollup contract. -3. **Upgrade Nodes/Validators**: Update to the custom Nitro version (e.g., v2.3.1+ for ArbOS 20 base). -4. **Schedule Upgrade**: Call `scheduleArbOSUpgrade` on ArbOwner precompile with the new version and timestamp (0 for immediate). -5. **Enable Features**: Post-upgrade, configure any version-specific flags. +- Significantly faster cross-chain deposits (e.g., 1 minute vs. tens), enhancing UX for bridging and dApps. +- Flexible for L3 setups settling to L2, optimizing for the parent chain's quicker confirmations. -This feature reflects Orbit's modularity but demands rigorous testing. Refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +## Cons + +- Increases re-org vulnerability on the child chain if the parent experiences instability in unconfirmed blocks. +- Not suitable for high-security applications; requires careful monitoring and may complicate fraud proofs if mismatches occur. + +## Compatibility + +- Primarily for Orbit L3 chains settling to Arbitrum One or Nova; not directly applicable to L2s settling to Ethereum. +- Compatible with all DA modes (Rollup, AnyTrust, Alt-DA) and gas tokens (native `ETH` or custom), as it focuses on sequencer logic. +- Integrates with BoLD or permissioned validation; for AnyTrust, pairs well with DAC for symmetric fast incoming/outgoing flows. + +## Examples + +- **Default L1 Finality**: A token deposit from Ethereum to an L3 (settling to Arbitrum One) waits for L1 to confirm the L2 batch, finalizing in ~10-30 minutes. +- **Fast L2 Finality**: For an L3 settling to Arbitrum Nova, configure with `--node.delayed-sequencer.use-merge-finality=false` `--node.delayed-sequencer.finalize-distance=1`. A bridge deposit is released after 1 L2 block (~1 minute), but may be reorg'd if Nova reverts. +- **DACert-Optimized**: On Nova settlement with default flags, finality ties to DACert posting (~tens of minutes); configuring low-distance speeds reduces this to ~1 minute for gaming apps needing quick asset transfers. + +This feature underscores Arbitrum's modularity for performance tuning while inheriting parent security. For implementation, refer to the latest Nitro sequencer docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx index ee6b95ae60..30d7ceefa6 100644 --- a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx +++ b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx @@ -12,14 +12,14 @@ The configuration ensures compliance with the AEP terms, streamlines reporting, ## Key Concepts -- **Arbitrum Expansion Program (AEP)**: A licensing framework for deploying Orbit chains on any blockchain that derives security from Ethereum (e.g., settling to Ethereum mainnet, other L2s, or even non-Ethereum chains with DAO approval). It requires no upfront permission but mandates paying 10% of net revenue (8% to the DAO treasury, 2% to ecosystem growth funds) on chains generating over $60,000 USD annually in profit. This framework applies to modifications of the stack, including custom DA, gas tokens, or governance. +- **Arbitrum Expansion Program (AEP)**: A licensing framework for deploying arbitrum chains outside of Arbitrum One and Arbitrum Nova (e.g., settling to Ethereum mainnet, other L2s, or even non-Ethereum chains with DAO approval). It requires no upfront permission but mandates paying 10% of net revenue (8% to the DAO treasury, 2% to ecosystem growth funds). This framework applies to modifications of the stack, including custom DA, gas tokens, or governance. For complete information refer to the Arbitrum Foundation's [Creating new Arbitrum chains, Arbitrum Expansion Program (AEP) section](https://docs.arbitrum.foundation/new-arb-chains#arbitrum-expansion-program-aep). - **Protocol Net Revenue**: The chain's profit, calculated as total fees collected (e.g., from gas, surplus, or custom mechanisms) minus Settlement Costs. Settlement Costs include gas fees for posting data to the parent chain (e.g., Ethereum calldata or blobs) and any other direct operational expenses like batch posting. Only positive net revenue triggers the 10% fee; losses or zero profit incur no payment. - **AEP Fee Router**: A set of deployable contracts (e.g., `RewardDistributor` or custom distributors) that automatically routes the 10% share. It integrates with the chain's fee collectors (e.g., for surplus fees) and handles cross-chain transfers (e.g., bridging to Ethereum then to a DAO-controlled address on Arbitrum One). ## Compatibility - **DA Modes**: Applies across Rollup, AnyTrust, and Alt-DA, as settlement costs vary by mode (e.g., lower in Alt-DA). -- **Gas Tokens**: For custom ERC-20s, requires conversion mechanisms; native `ETH` simplifies bridging. +- **Gas Tokens**: For custom `ERC-20`'s, requires conversion mechanisms; native `ETH` simplifies bridging. - **Validation**: No impact on BoLD or permissioned setups. ## Pros diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx index be197b0a9a..c0ff3798a7 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx @@ -48,11 +48,10 @@ Configuration requires chain owner privileges and can be done post-deployment us ## How to configure -1. **Set Fee Collectors**: Use the `ArbOwner` and `ArbAggregator` precompile (0x70) to assign addresses for each fee type (e.g., setInfraFeeAccount for Orbit base fees). Collectors can be simple addresses or smart contracts. +1. **Set Fee Collectors**: Use the `ArbOwner` and `ArbAggregator` precompile (0x70) to assign addresses for each fee type (e.g., `setInfraFeeAccount` for Orbit base fees). Collectors can be simple addresses or smart contracts. 2. **Deploy a Distributor Contract**: For rebates, deploy a contract like `RewardDistributor.sol` on the chain. Set recipients and proportions (e.g., 80% to treasury, 20% to user rebate pool using basis points). -3. **Assign Distributor as Collector**: Update the relevant fee collector to the distributor's address (e.g., via `setNetworkFeeAccount` for surplus fees). -4. **Trigger Distributions**: Call distributeRewards on the contract to execute rebates, specifying recipients and shares. +3. **Trigger Distributions**: Call distributeRewards on the contract to execute rebates, specifying recipients and shares. -- Tools: Use command-line (cast) or SDK extensions like `arbOwnerActions` for programmatic setup. +- **Tools**: Use command-line (cast) or SDK extensions like `arbOwnerActions` for programmatic setup. This feature underscores Arbitrum's modularity, allowing tailored fee economics while inheriting Ethereum security. For implementation, refer to official docs, SDK examples, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx index a302f4b850..d53cc0158d 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx @@ -12,6 +12,12 @@ Choosing permissioned validators refers to configuring the chain to use a legacy 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. +:::note + +If allowlisted validators were to go offline, after a period, anyone could remove the validator allowlist and the chain would then become permissionless. + +::: + This choice is configurable for all DA modes (Rollup, AnyTrust, Alt-DA) and gas tokens, but it's often retained for low-TVL chains to avoid the high bonds needed in permissionless setups, which could centralize around wealthy participants. ## Key Concepts @@ -19,6 +25,12 @@ This choice is configurable for all DA modes (Rollup, AnyTrust, Alt-DA) and gas - **Validation in Arbitrum**: Validators monitor and advance the chain's state by posting assertions (claims about block hashes, history commitments, and inbox messages) to the parent chain (e.g., Ethereum or an L2 like Arbitrum One). If an assertion is suspected of being invalid, challengers initiate interactive fraud proofs during a challenge window (typically ~6.4 days), bisecting disagreements down to verifiable one-step proofs executed on-chain. Security relies on economic incentives, where invalid claims lead to bond forfeitures. - **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. +:::note + +BoLD allows is configurable to include an allowlist of validators, instead of the default of permissionless. + +::: + ## Compatibility with Chain Types Works with L2/L3 Arbitrum chains settling to Ethereum or other L2s. For AnyTrust chains (e.g., like Arbitrum Nova), validation typically remains permissioned even post-BoLD upgrades, as the Data Availability Committee (DAC) already introduces trust assumptions, and permissionless bonds could invite griefing attacks. From cbdda6b1b31305bac83abae0d64b6568ee17b501 Mon Sep 17 00:00:00 2001 From: Pete Date: Wed, 12 Nov 2025 07:50:49 -0600 Subject: [PATCH 35/61] Addressing comments --- .../features/advanced/choose-arbos-version.mdx | 10 ++++++++-- .../features/advanced/choose-chain-precompiles.mdx | 6 ++++++ 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx index ec33f093f0..1087d48d63 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx @@ -40,11 +40,17 @@ Customizing the ArbOS version refers to modifying the Nitro codebase to introduc - **New State Variable**: Add `myNumber` initialized in `UpgradeArbosVersion` switch for v21: `ensure(state.SetNewMyNumber(randomNumber))`. - **STF Logic Change**: Branch in a method: `if p.state.ArbOSVersion() >= 32 { return "hi, new version" } else { return "hi" }`. +:::info + +It is important to understand that this is part of customizing the behavior of your chain. You can read more about this on the [Choose Custom Behavior](/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx) page. + +::: + ## How to configure 1. **Clone and Modify Nitro**: Use a branch like v3.7.2 (`git clone --branch v3.7.2 https://github.com/OffchainLabs/nitro.git`). Edit files (e.g., precompile.go, arbosstate.go) for changes, adding version gates. -2. **Build Custom Node**: Create Docker images, extract the new WASM module root, and update it on the parent chain via `setWasmModuleRoot` on the rollup contract. -3. **Upgrade Nodes/Validators**: Update to the custom Nitro version (e.g., v2.3.1+ for ArbOS 20 base). +2. **Upgrade Nodes/Validators**: Update to the custom Nitro version (e.g., v2.3.1+ for ArbOS 20 base). +3. **Build Custom Node**: Create Docker images, extract the new WASM module root, and update it on the parent chain via `setWasmModuleRoot` on the rollup contract. 4. **Schedule Upgrade**: Call `scheduleArbOSUpgrade` on ArbOwner precompile with the new version and timestamp (0 for immediate). 5. **Enable Features**: Post-upgrade, configure any version-specific flags. diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx index e39e81b705..296df2f577 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx @@ -50,6 +50,12 @@ There are several approaches, each building on the Nitro codebase: - Storing and modifying a custom state variable like "myNumber" via a new method. - Add a zk proof function so chains can process zk-related work more efficiently than EVM based options. +:::info + +It is important to understand that this is part of customizing ArbOS on your chain. You can read more about this on the [Choose ArbOS Version](/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx) page. + +::: + ## How to configure Customizing requires building a modified Nitro node, as precompiles are part of the core software: From f4be2bc43a7520248338f073ac78640817a92fa6 Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 20 Nov 2025 13:55:09 -0600 Subject: [PATCH 36/61] Update docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/advanced/choose-arbos-version.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx index 1087d48d63..32ee7ae7a0 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx @@ -12,7 +12,7 @@ Customizing the ArbOS version refers to modifying the Nitro codebase to introduc - **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. - **State Transition Function (STF)**: The deterministic process for computing new states from transactions. Customizations here (e.g., new logic or states) often necessitate an ArbOS upgrade to integrate changes into the replay binary used for fraud proofs. -- **WASM Module Root**: A 32-byte hash of the STF's implementation (e.g., 0x8b104a2e80ac6165dc58b9048de12f301d70b02a0ab51396c22b4b4b802a16a4 for ArbOS 20). Customizations require updating this on the parent chain for validation compatibility. +- **WASM Module Root**: A 32-byte hash of the STF's implementation (e.g., 0x8b104a2e80ac6165dc58b9048de12f301d70b02a0ab51396c22b4b4b802a16a4 for ArbOS 20). Customizations require updating this on the parent chain for compatibility validation. - **Backward Compatibility**: Changes must preserve old block results; new features activate only post-upgrade via version gates (e.g., `if state.ArbOSVersion() >= targetVersion`). For more details, please refer to [ArbOS version control](/launch-arbitrum-chain/05-customize-your-chain/customize-arbos.mdx#4-any-changes-in-the-stf-logic-that-will-affect-the-final-execution-result-arbos-version-control). ### Compatibility From 7961c60e9d1ae334ed39e487ecb0917a1d2dc242 Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 20 Nov 2025 13:55:21 -0600 Subject: [PATCH 37/61] Update docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/advanced/choose-chain-precompiles.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx index 296df2f577..9e4631782d 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx @@ -6,7 +6,7 @@ sme: content_type: configuration --- -Customizing your chain's precompiles refers to modifying or extending the built-in, system-level smart contract-like functions (precompiles) that provide efficient access to chain-specific operations, such as interacting with the parent chain (L1 or L2), querying state, or performing computations. Precompiles are hardcoded at specific addresses (e.g., 0x64 for `ArbSys`) and executed outside the EVM bytecode level for performance. They inherit from Ethereum's standard precompiles (e.g., for hashing or elliptic curves) while adding Arbitrum-specific ones (e.g., `ArbAddressTable` for address compression). +Customizing your chain's precompiles refers to modifying or extending the built-in, system-level smart contract-like functions (precompiles) that provide efficient access to chain-specific operations, such as interacting with the parent chain (L1 or L2), querying state, or performing computations. Precompiles are hardcoded at specific addresses (e.g., 0x64 for `ArbSys`) and executed outside the EVM bytecode level for performance. They inherit Ethereum's standard precompiles (e.g., for hashing or elliptic curves) while adding Arbitrum-specific ones (e.g., `ArbAddressTable` for address compression). Customization allows developers to add new methods, events, gas logic, or state interactions tailored to the chain's needs, such as app-specific utilities or optimizations. This flexibility is an advanced feature requiring modifications to the Nitro software stack, enabling deeper chain personalization beyond defaults like custom gas tokens or DA modes. From 6b152b631c50d5822640c2a4034230ef2214278a Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 20 Nov 2025 13:55:30 -0600 Subject: [PATCH 38/61] Update docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/advanced/choose-chain-precompiles.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx index 9e4631782d..75f48c471e 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx @@ -15,7 +15,7 @@ Customization allows developers to add new methods, events, gas logic, or state - **Precompiles in Arbitrum**: These are predefined contracts at fixed addresses that handle operations more efficiently than regular EVM code. Standard ones include ArbSys (for L1 interactions), ArbInfo (for balances and codes), and others for aggregation, retryables, or gas estimation. Customization builds on this by altering their behavior or adding new ones in the Nitro Go implementation. - **Customization Scope**: Focuses on extending functionality without full EVM changes, such as adding utility methods (e.g., a local zk-proof function) or integrating chain-specific state (e.g., a stored bytes). It doesn't alter core EVM opcodes but enhances system access. -## Options for Customization +## Options for customization There are several approaches, each building on the Nitro codebase: From da085deeadc8df452d1bfcaaf57fedb31b27ff5c Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:06:53 -0600 Subject: [PATCH 39/61] Update docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/advanced/choose-custom-delay-inbox-finality.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx index 649060b9b7..33b2b00d6e 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx @@ -21,7 +21,7 @@ By default, finality for these transactions relies on layer-1 (L1) Ethereum bloc ## What It Means to Configure Delayed Inbox Finality -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. :::note From f3abdb08ec6396add39d93dcf4458773fcf44fca Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:07:03 -0600 Subject: [PATCH 40/61] Update docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/data-availability/choose-rollup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx index e51bf6adde..857e57f899 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx @@ -1,5 +1,5 @@ --- -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' description: 'Learn about data availability using rollups and the pros and cons of choosing to use it for DA on your chain.' author: pete-vielhaber sme: From 3a6344df753acf23c4c12176e75c959697fa0c9e Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:07:26 -0600 Subject: [PATCH 41/61] Update docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/configure-aep/configure-aep-fees.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx index af43526e20..8bfa5bfaa9 100644 --- a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx +++ b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx @@ -5,7 +5,7 @@ author: pete-vielhaber sme: content_type: configuration --- - +import { VanillaAdmonition } from '@site/src/components/VanillaAdmonition/'; Configuring the AEP fees refers to setting up an optional but recommended smart contract system (the AEP fee router) to automate the calculation, collection, and transfer of the required 10% license fee on the chain's Protocol Net Revenue to the Arbitrum DAO treasury. This feature is part of the Arbitrum Expansion Program (AEP). This self-service licensing model permits developers to use Arbitrum's technology stack (e.g., Nitro) for custom chains in exchange for sharing revenue. 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). From 41ef4020a5d56b71dccb8f314aa57ab34dc8f063 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:07:48 -0600 Subject: [PATCH 42/61] Update docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/configure-aep/configure-aep-fees.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx index 8bfa5bfaa9..f3cb12157e 100644 --- a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx +++ b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx @@ -8,7 +8,7 @@ content_type: configuration import { VanillaAdmonition } from '@site/src/components/VanillaAdmonition/'; Configuring the AEP fees refers to setting up an optional but recommended smart contract system (the AEP fee router) to automate the calculation, collection, and transfer of the required 10% license fee on the chain's Protocol Net Revenue to the Arbitrum DAO treasury. This feature is part of the Arbitrum Expansion Program (AEP). This self-service licensing model permits developers to use Arbitrum's technology stack (e.g., Nitro) for custom chains in exchange for sharing revenue. -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. ## Key Concepts From 6ee34b0f7b432c94313849ded02e0b71ce19a25d Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:08:22 -0600 Subject: [PATCH 43/61] Update docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../features/advanced/choose-chain-precompiles.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx index 75f48c471e..0ff4f1329a 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx @@ -22,7 +22,7 @@ There are several approaches, each building on the Nitro codebase: - **Add New Methods to an Existing Precompile**: Extend a built-in precompile (e.g., `ArbSys`) with additional functions. - **Create a New Precompile**: Define a completely new precompile at a custom address (e.g., 0x011a for ArbHi) with its own methods. - **Define a New Event**: Add events to methods for logging, making the method state-modifying and indexable for off-chain querying. -- **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. - **Call and Modify State**: Integrate with ArbOS state by adding storage variables and methods to read/write them, allowing persistent chain-specific data. ## Compatibility with Chain Types From fb8d78e789b72ea55cefaf784449258e1386afd0 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:08:40 -0600 Subject: [PATCH 44/61] Update docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/data-availability/choose-anytrust.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx index 5841864028..ddf1ecdbb8 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx @@ -16,7 +16,7 @@ It's ideal for use cases where ultra-low fees are a priority over Ethereum's ful ## Key Concepts -- **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. - **AnyTrust Mode**: - Transaction data is initially submitted off-chain to a permissioned group of nodes called the Data Availability Committee (DAC), typically consisting of around 20 members (though configurable). - The DAC stores the data and signs a Data Availability Certificate (DACert), which posts to the parent chain. Full data is not posted onchain unless requested (e.g., during a challenge). From 995fd8de4b0a0832c317b6e08cf2f74043a1e339 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:08:54 -0600 Subject: [PATCH 45/61] Update docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/data-availability/choose-rollup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx index 857e57f899..a17167fa8d 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx @@ -1,6 +1,6 @@ --- title: 'Why choose to use Rollup for data availability on your Arbitrum chain' -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.' author: pete-vielhaber sme: content_type: configuration From 39a3d1573f4519e19f7254e6b58cc069a3d62c07 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:09:15 -0600 Subject: [PATCH 46/61] Update docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/data-availability/choose-rollup.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx index a17167fa8d..db1c401ad6 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx @@ -8,9 +8,9 @@ content_type: configuration import RollupPCPartial from '../../partials/_rollup-pc.mdx'; -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. +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. +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. From e51ff0620b703479f793c9a592f7d36b4e191fe8 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:09:35 -0600 Subject: [PATCH 47/61] Update docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/data-availability/choose-rollup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx index db1c401ad6..188e692451 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx @@ -16,7 +16,7 @@ This flexibility allows developers to tailor chains to specific needs while buil ## Key Concepts -- **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. - **Arbitrum Rollup Mode**: - All batch transaction data is posted directly to the parent chain (Ethereum L1) as calldata or blobs. - This inherits Ethereum's full security and decentralization, with no additional trust assumptions—data is always available on-chain for anyone to access and verify. From 5da2e69cc60db06aab1ca8ce9f3e67e9af6be70e Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:09:47 -0600 Subject: [PATCH 48/61] Update docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/gas-and-fees/choose-native-eth.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx index 9cc886b2e8..ecc9cfde69 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx @@ -12,7 +12,7 @@ Choosing native Ethereum refers to configuring the chain to use `ETH`—the nati Selecting native `ETH` means users must hold and spend `ETH` for all onchain activities, simplifying the fee mechanism without additional layers like token swaps or pricers. For operators, revenue is collected directly in `ETH`, which can be used seamlessly for data availability (DA) costs on the parent chain (e.g., posting to 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. +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. ## Key Concepts From d4696935cb064c812ca2c57e74bb98c539f1eb5b Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:10:01 -0600 Subject: [PATCH 49/61] Update docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/mev/choose-timeboost.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx index b2fcd2fa6f..f3309234eb 100644 --- a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx +++ b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx @@ -8,7 +8,7 @@ content_type: configuration import TimeboostPCPartial from '../../partials/_timeboost-pc.mdx'; -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. Enabling it is an owner-level decision, typically for chains with significant DeFi activity where MEV opportunities justify the trade-offs, and it can be done without halting operations (falling back to FCFS if no auction winner). From 31a0c5b59a505f402fd4681cd1b9e8f848105c36 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:10:11 -0600 Subject: [PATCH 50/61] Update docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/validation-and-security/choose-bold.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx index 7364505a24..7ae2465c3b 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx @@ -14,7 +14,7 @@ For the chain, it resets the challenge clock for in-flight withdrawals (adding u ## Key Concepts -- **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. - **Security Through Disputes**: Disputes narrow disagreements via bisections (binary search over computation steps, up to `2^69` in total space) across levels (block, BigStep for WASM ranges, SmallStep for single steps). Honest validators use offchain software (e.g., Nitro in Defensive mode) to automatically challenge invalid assertions, generating deterministic fraud proofs. Security relies on economic incentives: bonds are posted and forfeited by losers, deterring malice. - **BoLD Protocol**: BoLD introduces an "all-vs-all" (battle royale) model where multiple parties can challenge and defend simultaneously via "edges" (claims about history segments). It uses timers based on parent chain blocks, trustless bonding pools for crowdsourced stakes, and recursive sub-challenges to ensure a single honest party can always win against any number of adversaries. This bounds liquidity delays (hence the name) and mitigates "delay attacks" where malicious parties could previously prolong disputes indefinitely. From 9ce167aae8f2a90df30264aecd91fe19268f8974 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:10:23 -0600 Subject: [PATCH 51/61] Update docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../common/validation-and-security/choose-challenge-period.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx index 96cdce1f66..d3348dee93 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx @@ -8,7 +8,7 @@ content_type: configuration Choosing or configuring the challenge period refers to setting the duration (measured in parent chain blocks) during which state assertions—claims about the chain's execution history, block hashes, and inbox messages—can be disputed via fraud proofs before they are confirmed as valid on the parent chain (e.g., Ethereum or an Arbitrum L2). -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`). It's set by the chain owner and can be chosen based on the application's risk tolerance—e.g., high-value DeFi might opt for longer periods, while gaming appchains favor shorter ones. From a6eedeecfc70dd219a97e243215cf6a6d0739e8d Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:15:48 -0600 Subject: [PATCH 52/61] Update docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/advanced/choose-arbos-version.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx index 32ee7ae7a0..7958959d48 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx @@ -10,7 +10,7 @@ Customizing the ArbOS version refers to modifying the Nitro codebase to introduc ### Key Concepts -- **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. - **State Transition Function (STF)**: The deterministic process for computing new states from transactions. Customizations here (e.g., new logic or states) often necessitate an ArbOS upgrade to integrate changes into the replay binary used for fraud proofs. - **WASM Module Root**: A 32-byte hash of the STF's implementation (e.g., 0x8b104a2e80ac6165dc58b9048de12f301d70b02a0ab51396c22b4b4b802a16a4 for ArbOS 20). Customizations require updating this on the parent chain for compatibility validation. - **Backward Compatibility**: Changes must preserve old block results; new features activate only post-upgrade via version gates (e.g., `if state.ArbOSVersion() >= targetVersion`). For more details, please refer to [ArbOS version control](/launch-arbitrum-chain/05-customize-your-chain/customize-arbos.mdx#4-any-changes-in-the-stf-logic-that-will-affect-the-final-execution-result-arbos-version-control). From ec94d98027d4e88fe60a5965d4137e886807722a Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:16:00 -0600 Subject: [PATCH 53/61] Update docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/advanced/choose-arbos-version.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx index 7958959d48..fbfa884fac 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx @@ -6,7 +6,7 @@ sme: content_type: configuration --- -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. ### Key Concepts From 3a9f6028ca77e03d3d6a4881286f599855124383 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:18:27 -0600 Subject: [PATCH 54/61] Update docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/mev/choose-timeboost.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx index f3309234eb..a069d8a40f 100644 --- a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx +++ b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx @@ -36,7 +36,7 @@ Works with any Arbitrum chain (L2/L3), all DA modes (Rollup, AnyTrust, Alt-DA), ## How to configure -1. **Deploy Auction Contract**: Use Orbit scripts (e.g., from `orbit-actions` repo) with a `.env` file specifying addresses (e.g., proxy admin, bid token like `WETH`, beneficiary). Run `forge script` to deploy and verify. +1. **Deploy Auction Contract**: Use Orbit scripts (e.g., from `[orbit-actions](https://github.com/OffchainLabs/orbit-actions)` repo) with a `.env` file specifying addresses (e.g., proxy admin, bid token like `WETH`, beneficiary). Run `forge script` to deploy and verify. 2. **Run Auctioneer Services**: Set up Redis for coordination; run bid validator (verifies bids) and auction server (resolves auctions) using the `autonomous-auctioneer` binary from Nitro (Docker or local build). 3. **Configure Sequencer**: Update node config to enable `timeboost` and `auctioneer` APIs, pointing to the contract and Redis. From d87dbcd20f624e34d9238c1ebef3f0bb541a62e8 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:18:42 -0600 Subject: [PATCH 55/61] Update docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../validation-and-security/choose-permissioned-validators.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx index d53cc0158d..f750cc157d 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx @@ -23,7 +23,7 @@ This choice is configurable for all DA modes (Rollup, AnyTrust, Alt-DA) and gas ## Key Concepts - **Validation in Arbitrum**: Validators monitor and advance the chain's state by posting assertions (claims about block hashes, history commitments, and inbox messages) to the parent chain (e.g., Ethereum or an L2 like Arbitrum One). If an assertion is suspected of being invalid, challengers initiate interactive fraud proofs during a challenge window (typically ~6.4 days), bisecting disagreements down to verifiable one-step proofs executed on-chain. Security relies on economic incentives, where invalid claims lead to bond forfeitures. -- **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. :::note From ca5f4b31a6e891c24d81d567c4a325b170c3ae2c Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:19:26 -0600 Subject: [PATCH 56/61] Update docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/ux/choose-fast-withdrawals.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx index a8323d23f2..49fd5cb8f5 100644 --- a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx +++ b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx @@ -16,7 +16,7 @@ For pure Rollup chains, enabling it effectively introduces a committee trust lay ## Key Concepts -- **Standard Withdrawal Process**: In optimistic rollups like Arbitrum, assertions about the chain's state (e.g., transaction batches) are posted to the parent chain (e.g., Ethereum or Arbitrum One) and remain challengeable for a configurable period (default ~6.4-7 days) to allow fraud proofs. Unchallenged assertions confirm, enabling secure withdrawals, but this delays user access to funds. +- **Standard Withdrawal Process**: In optimistic Rollups like Arbitrum, assertions about the chain's state (e.g., transaction batches) are posted to the parent chain (e.g., Ethereum or Arbitrum One) and remain challengeable for a configurable period (default ~6.4-7 days) to allow fraud proofs. Unchallenged assertions confirm, enabling secure withdrawals, but this delays user access to funds. - **Fast Withdrawals Mechanism**: When enabled, a committee (e.g., an n/n multisig Safe wallet) of validators processes and unanimously signs assertions at a set frequency. This provides immediate confirmation, with finality tied to the parent chain's block times rather than the full challenge period. For example, L2 chains on Ethereum can confirm in ~15 minutes (above Ethereum's ~12.8-minute finality), while L3 chains on Arbitrum One can leverage "soft finality" (~250ms sequencer confirmations) for near-instant speeds. - **Related Parameters**: Often paired with adjusting the `minimumAssertionPeriod` (e.g., to 1 block for frequent assertions) and node flags to control posting intervals. From c72c17e5dfe99d1396e255c28fe86fa990c22765 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:20:13 -0600 Subject: [PATCH 57/61] Update docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/ux/choose-fast-withdrawals.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx index 49fd5cb8f5..23b069a0ec 100644 --- a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx +++ b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx @@ -33,7 +33,7 @@ For pure Rollup chains, enabling it effectively introduces a committee trust lay ## Impact on User Experience -From a UX perspective, enabling fast withdrawals transforms slow, multi-day processes into near-real-time ones, making the chain feel more responsive. Users get quicker access to withdrawn funds (e.g., 15 minutes vs. 6.4 days), reducing frustration and capital lockup. dApps benefit from faster cross-chain state reads, enabling seamless interactions like oracle updates or multi-chain DeFi. However, it assumes users trust the committee (e.g., for high-value transfers), and any load-based delays could still impact predictability. Overall, it's ideal for consumer-facing apps like gaming or social, where speed is key. +From a UX perspective, enabling fast withdrawals transforms slow, multi-day processes into near-real-time ones, making the chain feel more responsive. Users get quicker access to withdrawn funds (e.g., 15 minutes vs. 6.4 days), reducing frustration and capital lockup. Apps benefit from faster cross-chain state reads, enabling seamless interactions such as oracle updates and multi-chain DeFi. However, it assumes users trust the committee (e.g., for high-value transfers), and any load-based delays could still impact predictability. Overall, it's ideal for consumer-facing apps like gaming or social, where speed is key. ## Examples From e3892a0f15140181cd5ac0233bb04512bacb7010 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:20:29 -0600 Subject: [PATCH 58/61] Update docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/ux/choose-fast-withdrawals.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx index 23b069a0ec..f5b2bd2611 100644 --- a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx +++ b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx @@ -37,7 +37,7 @@ From a UX perspective, enabling fast withdrawals transforms slow, multi-day proc ## Examples -- **AnyTrust L2 Chain**: Configure for 15-minute withdrawals on Ethereum, using DAC members as validators for trust alignment. +- **AnyTrust L2 Chain**: Configured for 15-minute withdrawals on Ethereum, using DAC members as validators for trust alignment. - **L3 on Arbitrum One**: Set to 15 seconds using soft finality, suitable for high-throughput gaming appchains. ## How to configure From a9ff4f8ee9cbf2fe9a39f70bbbcd303736993336 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:20:56 -0600 Subject: [PATCH 59/61] Update docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gaël Blanchemain --- .../features/common/validation-and-security/choose-bold.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx index 7ae2465c3b..85ea4d9aa2 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx @@ -8,7 +8,7 @@ content_type: configuration import BoldPCPartial from '../../partials/_bold-pc.mdx'; -Upgrading or configuring the chain to use the Bounded Liquidity Delay (BoLD) protocol as its dispute resolution mechanism means replacing the legacy 1-vs-1 challenge system with a permissionless, all-vs-all dispute framework that enhances validation and security by allowing anyone to participate in challenging invalid state assertions through bonding, while ensuring disputes resolve within a fixed time bound (up to two challenge periods, typically ~12.8 days on Ethereum). It's enabled via an administrative upgrade on the parent chain (e.g., Ethereum) and is mandatory for certain Arbitrum chain configurations, such as using custom gas tokens in Rollup mode when posting directly to Ethereum. +Upgrading or configuring the chain to use the Bounded Liquidity Delay (BoLD) protocol as its dispute resolution mechanism means replacing the legacy 1-vs-1 challenge system with a permissionless, all-vs-all dispute framework that enhances validation and security by allowing anyone to participate in challenging invalid state assertions through bonding, while ensuring disputes resolve within a fixed time bound (up to two challenge periods, typically ~12.8 days on Ethereum). It's enabled via an administrative upgrade on the parent chain (e.g., Ethereum). It is mandatory for certain Arbitrum chain configurations, such as using custom gas tokens in Rollup mode when posting directly to Ethereum. For the chain, it resets the challenge clock for in-flight withdrawals (adding up to 6.4 days delay, with a max of 12.8 days total), handles overflow assertions for accumulated blocks during upgrade, and requires at least one active proposer (validator in MakeNodes mode) to advance the chain. Chain owners configure bond sizes (e.g., 3600 `ETH` for assertions on Arbitrum One equivalents) and can add incentives like service fees or bounties. This choice prioritizes enhanced security and decentralization over the legacy system's potential for centralized control, making the chain more resilient to attacks but introducing economic considerations for participation. From e8ae772c9f5962bec5de6df337650e5da93d0719 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 12:36:24 -0600 Subject: [PATCH 60/61] Addressing comments --- .../features/advanced/choose-arbos-version.mdx | 4 ++-- .../features/advanced/choose-chain-precompiles.mdx | 6 ++++-- .../features/advanced/choose-custom-behavior.mdx | 2 +- .../advanced/choose-custom-delay-inbox-finality.mdx | 10 ++++++++-- .../common/configure-aep/configure-aep-fees.mdx | 6 ++++-- .../common/data-availability/choose-alt-da.mdx | 2 +- .../common/data-availability/choose-anytrust.mdx | 2 +- .../common/data-availability/choose-rollup.mdx | 2 +- .../common/gas-and-fees/choose-custom-gas-token.mdx | 2 +- .../common/gas-and-fees/choose-fee-rebates.mdx | 2 +- .../features/common/gas-and-fees/choose-native-eth.mdx | 2 +- .../features/common/mev/choose-timeboost.mdx | 2 +- .../features/common/ux/choose-fast-withdrawals.mdx | 6 +++--- .../common/validation-and-security/choose-bold.mdx | 2 +- .../choose-challenge-period.mdx | 2 +- .../choose-permissioned-validators.mdx | 2 +- 16 files changed, 32 insertions(+), 22 deletions(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx index fbfa884fac..fd57cb0e0c 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx @@ -1,8 +1,8 @@ --- -title: 'Why choose a specific ArbOS version on your Arbitrum chain' +title: 'Why choose a specific ArbOS version and customize it' description: 'Learn about choosing which ArbOS version to use on your chain.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx index 0ff4f1329a..61eda4c0f9 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx @@ -2,11 +2,11 @@ title: 'Why choose to customize the precompiles on your Arbitrum chain' description: 'Learn about precompiles and the pros and cons of choosing to customize them on your chain.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- -Customizing your chain's precompiles refers to modifying or extending the built-in, system-level smart contract-like functions (precompiles) that provide efficient access to chain-specific operations, such as interacting with the parent chain (L1 or L2), querying state, or performing computations. Precompiles are hardcoded at specific addresses (e.g., 0x64 for `ArbSys`) and executed outside the EVM bytecode level for performance. They inherit Ethereum's standard precompiles (e.g., for hashing or elliptic curves) while adding Arbitrum-specific ones (e.g., `ArbAddressTable` for address compression). +Customizing your chain's precompiles refers to modifying or extending the built-in, system-level smart contract-like functions (precompiles) that provide efficient access to chain-specific operations, such as interacting with the parent chain (L1 or L2), querying state, or performing computations. Precompiles are hardcoded at specific addresses (e.g., 0x64 for `ArbSys`) and executed outside the EVM bytecode level for performance. They inherit Ethereum's standard precompiles (e.g., for hashing or elliptic curves) while adding Arbitrum-specific ones (e.g., `ArbAddressTable` for address compression). Customization allows developers to add new methods, events, gas logic, or state interactions tailored to the chain's needs, such as app-specific utilities or optimizations. This flexibility is an advanced feature requiring modifications to the Nitro software stack, enabling deeper chain personalization beyond defaults like custom gas tokens or DA modes. @@ -54,6 +54,8 @@ There are several approaches, each building on the Nitro codebase: It is important to understand that this is part of customizing ArbOS on your chain. You can read more about this on the [Choose ArbOS Version](/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx) page. +**All** modifications to precompiles should consider ArbOS version control or it may cause a chain fork. More information can be found on the [Customize ArbOS page](/launch-arbitrum-chain/customize-your-chain/customize-arbos#where-should-i-insert-arbos-upgrade-related-code). + ::: ## How to configure diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx index 6a220e2ebd..ee1f9d3246 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx @@ -2,7 +2,7 @@ title: 'Why choose to customize the behavior on your Arbitrum chain' description: 'Learn about custom behaviors and the pros and cons of choosing to customize the behavior it on your chain.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx index 33b2b00d6e..26daa8323c 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx @@ -2,13 +2,19 @@ title: 'Why choose to customize the delayed inbox finality on your Arbitrum chain' description: 'Learn about delayed inbox finality and the pros and cons of choosing to customize it on your chain.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- Configuring the delayed inbox finality refers to adjusting sequencer node flags to control the timing and dependencies for when transactions (e.g., cross-chain messages or deposits) sent through the Delayed Inbox achieve finality on the child chain. The Delayed Inbox is a fallback mechanism for parent-to-child communications that bypasses the sequencer for direct inclusion, ensuring censorship resistance. -By default, finality for these transactions relies on layer-1 (L1) Ethereum block confirmations (typically tens of minutes). Configuration allows shifting to faster L2-based finality or reducing confirmation waits, trading speed for potential re-org risks. This reduction is an advanced sequencer-level setting, not a deployment-time parameter, and is primarily used to optimize bridging speed for use cases like high-frequency DeFi or gaming. +By default, finality for these transactions relies on Layer-1 (L1) Ethereum block confirmations (typically tens of minutes). Configuration allows shifting to faster L2-based finality or reducing confirmation waits, trading speed for potential re-org risks. This reduction is an advanced sequencer-level setting, not a deployment-time parameter, and is primarily used to optimize bridging speed for use cases like high-frequency DeFi or gaming. + +:::note + +It's worth noting that this page is based on a well-behaved sequencer, not one that is censoring. + +::: ## Key concepts diff --git a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx index f3cb12157e..af47768e45 100644 --- a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx +++ b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx @@ -2,13 +2,15 @@ title: 'Why choose to configure AEP fees for your Arbitrum chain' description: 'Learn about AEP fee configuration and the pros and cons of choosing to configure it.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- + import { VanillaAdmonition } from '@site/src/components/VanillaAdmonition/'; + Configuring the AEP fees refers to setting up an optional but recommended smart contract system (the AEP fee router) to automate the calculation, collection, and transfer of the required 10% license fee on the chain's Protocol Net Revenue to the Arbitrum DAO treasury. This feature is part of the Arbitrum Expansion Program (AEP). This self-service licensing model permits developers to use Arbitrum's technology stack (e.g., Nitro) for custom chains in exchange for sharing revenue. -The configuration ensures compliance with the AEP terms, streamlines reporting, and avoids manual transfers, while allowing chains to retain 90% of profits. +The configuration ensures compliance with the AEP terms, streamlines reporting, and avoids manual transfers, while allowing chains to retain 90% of profits. ## Key Concepts diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx index a571e026dd..dcff20036e 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx @@ -2,7 +2,7 @@ title: 'Why choose to use alt-DA for data availability on your Arbitrum chain' description: 'Learn about alt-DA and the pros and cons of choosing to use it for DA on your chain.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx index ddf1ecdbb8..923896c2de 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx @@ -2,7 +2,7 @@ title: 'Why choose to use AnyTrust for data availability on your Arbitrum chain' description: 'Learn about data availability using AnyTrust and the pros and cons of choosing to use it for DA on your chain.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx index 188e692451..a2eabbe8c5 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx @@ -2,7 +2,7 @@ title: 'Why choose to use Rollup for data availability on your Arbitrum chain' description: 'Learn about data availability using Rollups and the pros and cons of choosing to use it for DA on your chain.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx index 7580780076..64ff85aa35 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx @@ -2,7 +2,7 @@ title: 'Why choose to use a custom gas token on your Arbitrum chain' description: 'Learn about the pros and cons of choosing to use a custom gas token for your chain.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx index c0ff3798a7..a1454a5c42 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx @@ -2,7 +2,7 @@ title: 'Why choose to leverage fee rebates on your Arbitrum chain' description: 'Learn about the pros and cons of choosing to enable fee rebates for your chain.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx index ecc9cfde69..7d2e1052f7 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx @@ -2,7 +2,7 @@ title: 'Why choose to use native Ethereum for gas on your Arbitrum chain' description: 'Learn about the pros and cons of choosing to use native Ethereum as the gas token for your chain.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- diff --git a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx index a069d8a40f..39330d8edc 100644 --- a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx +++ b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx @@ -2,7 +2,7 @@ title: 'Why choose to enable Timeboost for your Arbitrum chain' description: 'Learn about Timeboost and the pros and cons of choosing to enable it.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- diff --git a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx index f5b2bd2611..a5b4658d98 100644 --- a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx +++ b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx @@ -2,7 +2,7 @@ title: 'Why choose to enable fast withdrawals for your Arbitrum chain' description: 'Learn about fast withdrawals and the pros and cons of choosing to enable it.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- @@ -17,7 +17,7 @@ For pure Rollup chains, enabling it effectively introduces a committee trust lay ## Key Concepts - **Standard Withdrawal Process**: In optimistic Rollups like Arbitrum, assertions about the chain's state (e.g., transaction batches) are posted to the parent chain (e.g., Ethereum or Arbitrum One) and remain challengeable for a configurable period (default ~6.4-7 days) to allow fraud proofs. Unchallenged assertions confirm, enabling secure withdrawals, but this delays user access to funds. -- **Fast Withdrawals Mechanism**: When enabled, a committee (e.g., an n/n multisig Safe wallet) of validators processes and unanimously signs assertions at a set frequency. This provides immediate confirmation, with finality tied to the parent chain's block times rather than the full challenge period. For example, L2 chains on Ethereum can confirm in ~15 minutes (above Ethereum's ~12.8-minute finality), while L3 chains on Arbitrum One can leverage "soft finality" (~250ms sequencer confirmations) for near-instant speeds. +- **Fast Withdrawals Mechanism**: When enabled, a committee (e.g., an `n/n` multisig Safe wallet) of validators processes and unanimously signs assertions at a set interval. This provides immediate confirmation, with finality tied to the parent chain's block times rather than the full challenge period. For example, L2 chains on Ethereum can confirm in ~15 minutes (above Ethereum's ~12.8-minute finality), while L3 chains on Arbitrum One can leverage "soft finality" (~250ms sequencer confirmations) for near-instant speeds. - **Related Parameters**: Often paired with adjusting the `minimumAssertionPeriod` (e.g., to 1 block for frequent assertions) and node flags to control posting intervals. ## Compatibility @@ -25,7 +25,7 @@ For pure Rollup chains, enabling it effectively introduces a committee trust lay - **DA Modes**: Optimized for AnyTrust (leverages DAC); possible but not recommended for Rollup or Alt-DA, as it adds trust assumptions. - **Validation**: Works with BoLD (permissionless) or pre-BoLD (permissioned), but the committee must be allowlisted. - **Gas Tokens**: No restrictions; compatible with native `ETH` or custom `ERC-20`s. -- **Parent Chain**: Frequency must exceed the parent's finality time (e.g., >12.8 minutes for Ethereum L2s). +- **Parent Chain**: Interval must exceed the parent's finality time (e.g., >12.8 minutes for Ethereum L2s). (Refer to [Key Concepts above](#key-concepts) for more information about the Fast Withdrawal Mechanism.) diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx index 85ea4d9aa2..27b0d6420b 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx @@ -2,7 +2,7 @@ title: 'Why choose to enable BoLD for your Arbitrum chain' description: 'Learn about BoLD and the pros and cons of choosing to enable it.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx index d3348dee93..b2e3f33c7b 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx @@ -2,7 +2,7 @@ title: 'Why choose to customize the challenge period for your Arbitrum chain' description: 'Learn about the challenge period and the pros and cons of choosing to customize it.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx index f750cc157d..7e8c2a30b6 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx @@ -2,7 +2,7 @@ title: 'Why choose permissioned validators for your Arbitrum chain' description: 'Learn about permissioned validators and the pros and cons of choosing to use them.' author: pete-vielhaber -sme: +sme: jason-w123 content_type: configuration --- From 121bd2a9cd7d23afd4cd2a532ffe587b38be4e18 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 21 Nov 2025 13:02:58 -0600 Subject: [PATCH 61/61] Quicklook generator --- .../advanced/choose-arbos-version.mdx | 14 ++++++------ .../advanced/choose-chain-precompiles.mdx | 16 +++++++------- .../advanced/choose-custom-behavior.mdx | 8 +++---- .../choose-custom-delay-inbox-finality.mdx | 22 +++++++++---------- .../configure-aep/configure-aep-fees.mdx | 16 +++++++------- .../data-availability/choose-alt-da.mdx | 14 ++++++------ .../data-availability/choose-anytrust.mdx | 14 ++++++------ .../data-availability/choose-rollup.mdx | 10 ++++----- .../gas-and-fees/choose-custom-gas-token.mdx | 12 +++++----- .../gas-and-fees/choose-fee-rebates.mdx | 12 +++++----- .../common/gas-and-fees/choose-native-eth.mdx | 16 +++++++------- .../features/common/mev/choose-timeboost.mdx | 20 ++++++++--------- .../common/ux/choose-fast-withdrawals.mdx | 20 +++++++++-------- .../validation-and-security/choose-bold.mdx | 16 +++++++------- .../choose-challenge-period.mdx | 14 ++++++------ .../choose-permissioned-validators.mdx | 16 +++++++------- 16 files changed, 121 insertions(+), 119 deletions(-) diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx index fd57cb0e0c..323ee3b161 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx @@ -6,20 +6,20 @@ sme: jason-w123 content_type: configuration --- -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. +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. ### Key Concepts - **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. - **State Transition Function (STF)**: The deterministic process for computing new states from transactions. Customizations here (e.g., new logic or states) often necessitate an ArbOS upgrade to integrate changes into the replay binary used for fraud proofs. -- **WASM Module Root**: A 32-byte hash of the STF's implementation (e.g., 0x8b104a2e80ac6165dc58b9048de12f301d70b02a0ab51396c22b4b4b802a16a4 for ArbOS 20). Customizations require updating this on the parent chain for compatibility validation. +- **WASM Module Root**: A 32-byte hash of the STF's implementation (e.g., 0x8b104a2e80ac6165dc58b9048de12f301d70b02a0ab51396c22b4b4b802a16a4 for ArbOS 20). Customizations require updating this on the parent chain for compatibility validation. - **Backward Compatibility**: Changes must preserve old block results; new features activate only post-upgrade via version gates (e.g., `if state.ArbOSVersion() >= targetVersion`). For more details, please refer to [ArbOS version control](/launch-arbitrum-chain/05-customize-your-chain/customize-arbos.mdx#4-any-changes-in-the-stf-logic-that-will-affect-the-final-execution-result-arbos-version-control). ### Compatibility -- Works with all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (BoLD/permissioned), as long as changes meet STF rules. +- Works with all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (BoLD/permissioned), as long as changes meet STF rules. - Backward-compatible by design; WASM roots support old versions. -- For public chains like One/Nova, requires DAO governance; Orbit chains have owner discretion. +- For public chains like One/Nova, requires DAO governance; Arbitrum chains have owner discretion. ### Pros @@ -31,11 +31,11 @@ Customizing the ArbOS version involves modifying the Nitro codebase to introduce - Complexity and risks (e.g., re-orgs from improper state init, proof failures). - Requires audits/maintenance; unintended intermediate features may activate. -- No Offchain Labs review; higher costs for expertise. +- No Offchain Labs review; higher costs for expertise. ### Examples -- **New Precompile Method**: Add `sayHi()` to ArbSys, gated by `ArbOwner.methodsByName["SayHi"].arbosVersion = 32`. +- **New Precompile Method**: Add `sayHi()` to ArbSys, gated by `ArbOwner.methodsByName["SayHi"].arbosVersion = 32`. - **New Precompile**: Create ArbHi with `ArbHi.arbosVersion = 32` and method gates. - **New State Variable**: Add `myNumber` initialized in `UpgradeArbosVersion` switch for v21: `ensure(state.SetNewMyNumber(randomNumber))`. - **STF Logic Change**: Branch in a method: `if p.state.ArbOSVersion() >= 32 { return "hi, new version" } else { return "hi" }`. @@ -54,4 +54,4 @@ It is important to understand that this is part of customizing the behavior of y 4. **Schedule Upgrade**: Call `scheduleArbOSUpgrade` on ArbOwner precompile with the new version and timestamp (0 for immediate). 5. **Enable Features**: Post-upgrade, configure any version-specific flags. -This reflects Orbit's modularity but demands rigorous testing. Refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This reflects Arbitrum's modularity but demands rigorous testing. Refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx index 61eda4c0f9..871f2615af 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx @@ -6,7 +6,7 @@ sme: jason-w123 content_type: configuration --- -Customizing your chain's precompiles refers to modifying or extending the built-in, system-level smart contract-like functions (precompiles) that provide efficient access to chain-specific operations, such as interacting with the parent chain (L1 or L2), querying state, or performing computations. Precompiles are hardcoded at specific addresses (e.g., 0x64 for `ArbSys`) and executed outside the EVM bytecode level for performance. They inherit Ethereum's standard precompiles (e.g., for hashing or elliptic curves) while adding Arbitrum-specific ones (e.g., `ArbAddressTable` for address compression). +Customizing your chain's precompiles refers to modifying or extending the built-in, system-level smart contract-like functions (precompiles) that provide efficient access to chain-specific operations, such as interacting with the parent chain (L1 or L2), querying state, or performing computations. Precompiles are hardcoded at specific addresses (e.g., 0x64 for `ArbSys`) and executed outside the EVM bytecode level for performance. They inherit Ethereum's standard precompiles (e.g., for hashing or elliptic curves) while adding Arbitrum-specific ones (e.g., `ArbAddressTable` for address compression). Customization allows developers to add new methods, events, gas logic, or state interactions tailored to the chain's needs, such as app-specific utilities or optimizations. This flexibility is an advanced feature requiring modifications to the Nitro software stack, enabling deeper chain personalization beyond defaults like custom gas tokens or DA modes. @@ -19,16 +19,16 @@ Customization allows developers to add new methods, events, gas logic, or state There are several approaches, each building on the Nitro codebase: -- **Add New Methods to an Existing Precompile**: Extend a built-in precompile (e.g., `ArbSys`) with additional functions. +- **Add New Methods to an Existing Precompile**: Extend a built-in precompile (e.g., `ArbSys`) with additional functions. - **Create a New Precompile**: Define a completely new precompile at a custom address (e.g., 0x011a for ArbHi) with its own methods. - **Define a New Event**: Add events to methods for logging, making the method state-modifying and indexable for off-chain querying. - **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. -- **Call and Modify State**: Integrate with ArbOS state by adding storage variables and methods to read/write them, allowing persistent chain-specific data. +- **Call and Modify State**: Integrate with ArbOS state by adding storage variables and methods to read/write them, allowing persistent chain-specific data. ## Compatibility with Chain Types -- Works with all Orbit DA modes (Rollup, AnyTrust, Alt-DA) and gas tokens (native ETH or custom), as it's a Nitro-level change. -- Compatible with BoLD or permissioned validation. +- Works with all Arbitrum chain DA modes (Rollup, AnyTrust, Alt-DA) and gas tokens (native ETH or custom), as it's a Nitro-level change. +- Compatible with BoLD or permissioned validation. ## Pros @@ -39,9 +39,9 @@ There are several approaches, each building on the Nitro codebase: ## Cons - Requires deep expertise in Go, Solidity, and Nitro; complex setup and maintenance. -- Customizing the precompiles will cause WASM module root changes, introducing additional modifications. +- Customizing the precompiles will cause WASM module root changes, introducing additional modifications. - Risks include DoS vulnerabilities without proper gas implementation, security issues without audits, and potential validation breaks. -- No official review from Offchain Labs; changes may complicate upgrades or fraud proofs. +- No official review from Offchain Labs; changes may complicate upgrades or fraud proofs. ## Examples @@ -68,4 +68,4 @@ Customizing requires building a modified Nitro node, as precompiles are part of 4. **Build and Run Node**: Compile a custom Docker image and run the node with your configurations (e.g., specifying parent chain URL and chain ID). Test with tools like curl for eth_call or Foundry's cast for calls/sends. 5. **Post-Launch Changes**: Use ArbOS version upgrades to apply without reorganizing the chain; follow related guides for fraud proofs. -This advanced customization aligns with Orbit's modular design but demands careful planning and testing. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This advanced customization aligns with Arbitrum's modular design but demands careful planning and testing. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx index ee1f9d3246..47cffb136a 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx @@ -6,19 +6,19 @@ sme: jason-w123 content_type: configuration --- -Customizing your chain's behavior refers to modifying the core logic that governs how the chain processes transactions, produces blocks, and transitions states—primarily by altering the State Transition Function (STF) within the Nitro software stack. This goes beyond surface-level configurations (e.g., gas tokens or DA modes) and involves code-level changes to ArbOS (Arbitrum's operating system layer), such as adding new EVM opcodes, precompiles, or state variables, while ensuring compatibility with fraud proofs and backward compatibility. Such customizations enable highly tailored chains for specific use cases but require building custom Nitro nodes and handling upgrades carefully to avoid disruptions like chain re-orgs or invalid fraud proofs. It's an advanced feature recommended for teams with expertise or partners (e.g., RaaS providers), as Offchain Labs does not review individual changes—audits and maintenance are the developer's responsibility. +Customizing your chain's behavior refers to modifying the core logic that governs how the chain processes transactions, produces blocks, and transitions states—primarily by altering the State Transition Function (STF) within the Nitro software stack. This goes beyond surface-level configurations (e.g., gas tokens or DA modes) and involves code-level changes to ArbOS (Arbitrum's operating system layer), such as adding new EVM opcodes, precompiles, or state variables, while ensuring compatibility with fraud proofs and backward compatibility. Such customizations enable highly tailored chains for specific use cases but require building custom Nitro nodes and handling upgrades carefully to avoid disruptions like chain re-orgs or invalid fraud proofs. It's an advanced feature recommended for teams with expertise or partners (e.g., RaaS providers), as Offchain Labs does not review individual changes—audits and maintenance are the developer's responsibility. ### Key Concepts - **State Transition Function (STF)**: The deterministic logic that computes new chain states from inputs (e.g., transactions). Customizations here affect block production, execution outcomes, or state (e.g., balances), requiring updates to fraud proofs to recognize the changes as valid. - **ArbOS**: The operating system-like layer in Nitro that manages STF components, including precompiles, state, and upgrades. Customizations often involve versioning ArbOS to activate changes safely on live chains. -- **WASM Module Root**: A 32-byte hash representing the STF's implementation, which must be updated on the parent chain for fraud proofs to work with customizations. +- **WASM Module Root**: A 32-byte hash representing the STF's implementation, which must be updated on the parent chain for fraud proofs to work with customizations. - **Backward Compatibility**: Changes must not alter results for old blocks; they activate at specific ArbOS versions or timestamps to prevent re-orgs. - **STF Requirements**: Must be deterministic, pure (no external resources), performant (< 1 second per block), and state-managed only via the Ethereum trie or block headers. ### Compatibility -- Works with all Orbit DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (BoLD or permissioned), but STF changes must meet strict rules (e.g., no non-determinism). +- Works with all Arbitrum chain DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (BoLD or permissioned), but STF changes must meet strict rules (e.g., no non-determinism). - Backward-compatible by design; upgrades activate features sequentially, including all intermediate ones. - Incompatible with external dependencies or changes that violate STF purity/performance. @@ -36,7 +36,7 @@ Customizing your chain's behavior refers to modifying the core logic that govern ### Examples -- **Adding a New Precompile Method**: Extend ArbSys with a "sayHi" function that activates at ArbOS v32, returning different strings pre/post-upgrade. +- **Adding a New Precompile Method**: Extend ArbSys with a "sayHi" function that activates at ArbOS v32, returning different strings pre/post-upgrade. - **New State Variable**: Add "myNumber" initialized during upgrade to v21, modifiable only post-upgrade. - **STF Logic Change**: Modify a method to use new behavior if ArbOS version >= target, e.g., altering gas rewards for deployers. - **Non-STF**: Adding an RPC for multi-block queries (no STF/fraud updates needed). diff --git a/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx b/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx index 26daa8323c..0357cc8503 100644 --- a/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx +++ b/docs/launch-arbitrum-chain/features/advanced/choose-custom-delay-inbox-finality.mdx @@ -6,9 +6,9 @@ sme: jason-w123 content_type: configuration --- -Configuring the delayed inbox finality refers to adjusting sequencer node flags to control the timing and dependencies for when transactions (e.g., cross-chain messages or deposits) sent through the Delayed Inbox achieve finality on the child chain. The Delayed Inbox is a fallback mechanism for parent-to-child communications that bypasses the sequencer for direct inclusion, ensuring censorship resistance. +Configuring the Delayed Inbox finality refers to adjusting Sequencer node flags to control the timing and dependencies for when transactions (e.g., cross-chain messages or deposits) sent through the Delayed Inbox achieve finality on the child chain. The Delayed Inbox is a fallback mechanism for parent-to-child communications that bypasses the sequencer for direct inclusion, ensuring censorship resistance. -By default, finality for these transactions relies on Layer-1 (L1) Ethereum block confirmations (typically tens of minutes). Configuration allows shifting to faster L2-based finality or reducing confirmation waits, trading speed for potential re-org risks. This reduction is an advanced sequencer-level setting, not a deployment-time parameter, and is primarily used to optimize bridging speed for use cases like high-frequency DeFi or gaming. +By default, finality for these transactions relies on Layer-1 (L1) Ethereum block confirmations (typically tens of minutes). Configuration allows shifting to faster L2-based finality or reducing confirmation waits, trading speed for potential re-org risks. This reduction is an advanced sequencer-level setting, not a deployment-time parameter, and is primarily used to optimize bridging speed for use cases like high-frequency DeFi or gaming. :::note @@ -18,9 +18,9 @@ It's worth noting that this page is based on a well-behaved sequencer, not one t ## Key concepts -- **Delayed Inbox**: A contract on the parent chain where users can submit transactions (e.g., retryable tickets for token bridges or direct calls) to be force-included on the child chain if the sequencer delays them. These are held until the sequencer releases them based on parent chain progress. -- **Finality**: The point at which a Delayed Inbox transaction is irreversibly executable on the child chain. By default, this depends on L1 finality (e.g., Ethereum blocks confirming a batch from Arbitrum One or a Data Availability Certificate/DACert from Nova), taking ~10-60 minutes. -- **L2 vs. L1 Finality**: L3 chains can be configured to rely on the parent L2's quicker "soft finality" (~1-15 minutes) instead of waiting for deeper L1 confirmations, or to reduce L2 block waits for even faster processing. +- **Delayed Inbox**: A contract on the parent chain where users can submit transactions (e.g., retryable tickets for token bridges or direct calls) to be force-included on the child chain if the sequencer delays them. These are held until the sequencer releases them based on parent chain progress. +- **Finality**: The point at which a Delayed Inbox transaction is irreversibly executable on the child chain. By default, this depends on L1 finality (e.g., Ethereum blocks confirming a batch from Arbitrum One or a Data Availability Certificate/DACert from Nova), taking ~10-60 minutes. +- **L2 vs. L1 Finality**: L3 chains can be configured to rely on the parent L2's quicker "soft finality" (~1-15 minutes) instead of waiting for deeper L1 confirmations, or to reduce L2 block waits for even faster processing. - **Relevant Flags**: - `--node.delayed-sequencer.use-merge-finality=false`: Disables L1 dependency, using only L2 finality. - `--node.delayed-sequencer.finalize-distance=1`: Sets the number of L2 block confirmations needed (default is higher; 1 enables ~1-minute finality). @@ -37,10 +37,10 @@ This affects only incoming (parent-to-child) Delayed Inbox flows; outgoing (chil ### Configuration Process: -- **Prepare the Sequencer Node**: When running your Orbit chain's sequencer (e.g., via Docker or local build from Nitro source), add the flags to the startup command. Example for a Dockerized sequencer: +- **Prepare the Sequencer Node**: When running your Arbitrum chain's sequencer (e.g., via Docker or local build from Nitro source), add the flags to the startup command. Example for a Dockerized sequencer: `docker run --rm -it -p 8547:8547 offchainlabs/nitro-node:v3.7.2 --chain.id=12345 --node.delayed-sequencer.use-merge-finality=false --node.delayed-sequencer.finalize-distance=1` - Replace with your chain's parameters (e.g., parent chain URL). -- **Test and Deploy**: Verify in a devnet by submitting a Delayed Inbox transaction (e.g., via a token bridge) and monitoring release timing in logs. For production, ensure validators are updated to match the new behavior. +- **Test and Deploy**: Verify in a devnet by submitting a Delayed Inbox transaction (e.g., via a token bridge) and monitoring release timing in logs. For production, ensure validators are updated to match the new behavior. - **Monitor**: Use tools like chain explorers or sequencer logs to track finality times and re-org incidents. ## How It Differs from Default @@ -60,14 +60,14 @@ This affects only incoming (parent-to-child) Delayed Inbox flows; outgoing (chil ## Compatibility -- Primarily for Orbit L3 chains settling to Arbitrum One or Nova; not directly applicable to L2s settling to Ethereum. +- Primarily for Arbitrum L3 chains settling to Arbitrum One or Nova; not directly applicable to L2s settling to Ethereum. - Compatible with all DA modes (Rollup, AnyTrust, Alt-DA) and gas tokens (native `ETH` or custom), as it focuses on sequencer logic. -- Integrates with BoLD or permissioned validation; for AnyTrust, pairs well with DAC for symmetric fast incoming/outgoing flows. +- Integrates with BoLD or permissioned validation; for AnyTrust, pairs well with DAC for symmetric fast incoming/outgoing flows. ## Examples - **Default L1 Finality**: A token deposit from Ethereum to an L3 (settling to Arbitrum One) waits for L1 to confirm the L2 batch, finalizing in ~10-30 minutes. -- **Fast L2 Finality**: For an L3 settling to Arbitrum Nova, configure with `--node.delayed-sequencer.use-merge-finality=false` `--node.delayed-sequencer.finalize-distance=1`. A bridge deposit is released after 1 L2 block (~1 minute), but may be reorg'd if Nova reverts. +- **Fast L2 Finality**: For an L3 settling to Arbitrum Nova, configure with `--node.delayed-sequencer.use-merge-finality=false` `--node.delayed-sequencer.finalize-distance=1`. A bridge deposit is released after 1 L2 block (~1 minute), but may be reorg'd if Nova reverts. - **DACert-Optimized**: On Nova settlement with default flags, finality ties to DACert posting (~tens of minutes); configuring low-distance speeds reduces this to ~1 minute for gaming apps needing quick asset transfers. -This feature underscores Arbitrum's modularity for performance tuning while inheriting parent security. For implementation, refer to the latest Nitro sequencer docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This feature underscores Arbitrum's modularity for performance tuning while inheriting parent security. For implementation, refer to the latest Nitro sequencer docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx index af47768e45..67690eab59 100644 --- a/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx +++ b/docs/launch-arbitrum-chain/features/common/configure-aep/configure-aep-fees.mdx @@ -8,21 +8,21 @@ content_type: configuration import { VanillaAdmonition } from '@site/src/components/VanillaAdmonition/'; -Configuring the AEP fees refers to setting up an optional but recommended smart contract system (the AEP fee router) to automate the calculation, collection, and transfer of the required 10% license fee on the chain's Protocol Net Revenue to the Arbitrum DAO treasury. This feature is part of the Arbitrum Expansion Program (AEP). This self-service licensing model permits developers to use Arbitrum's technology stack (e.g., Nitro) for custom chains in exchange for sharing revenue. +Configuring the AEP fees refers to setting up an optional but recommended smart contract system (the AEP fee router) to automate the calculation, collection, and transfer of the required 10% license fee on the chain's Protocol Net Revenue to the Arbitrum DAO treasury. This feature is part of the Arbitrum Expansion Program (AEP). This self-service licensing model permits developers to use Arbitrum's technology stack (e.g., Nitro) for custom chains in exchange for sharing revenue. The configuration ensures compliance with the AEP terms, streamlines reporting, and avoids manual transfers, while allowing chains to retain 90% of profits. ## Key Concepts -- **Arbitrum Expansion Program (AEP)**: A licensing framework for deploying arbitrum chains outside of Arbitrum One and Arbitrum Nova (e.g., settling to Ethereum mainnet, other L2s, or even non-Ethereum chains with DAO approval). It requires no upfront permission but mandates paying 10% of net revenue (8% to the DAO treasury, 2% to ecosystem growth funds). This framework applies to modifications of the stack, including custom DA, gas tokens, or governance. For complete information refer to the Arbitrum Foundation's [Creating new Arbitrum chains, Arbitrum Expansion Program (AEP) section](https://docs.arbitrum.foundation/new-arb-chains#arbitrum-expansion-program-aep). -- **Protocol Net Revenue**: The chain's profit, calculated as total fees collected (e.g., from gas, surplus, or custom mechanisms) minus Settlement Costs. Settlement Costs include gas fees for posting data to the parent chain (e.g., Ethereum calldata or blobs) and any other direct operational expenses like batch posting. Only positive net revenue triggers the 10% fee; losses or zero profit incur no payment. +- **Arbitrum Expansion Program (AEP)**: A licensing framework for deploying Arbitrum chains outside of Arbitrum One and Arbitrum Nova (e.g., settling to Ethereum mainnet, other L2s, or even non-Ethereum chains with DAO approval). It requires no upfront permission but mandates paying 10% of net revenue (8% to the DAO treasury, 2% to ecosystem growth funds). This framework applies to modifications of the stack, including custom DA, gas tokens, or governance. For complete information refer to the Arbitrum Foundation's [Creating new Arbitrum chains, Arbitrum Expansion Program (AEP) section](https://docs.arbitrum.foundation/new-arb-chains#arbitrum-expansion-program-aep). +- **Protocol Net Revenue**: The chain's profit, calculated as total fees collected (e.g., from gas, surplus, or custom mechanisms) minus Settlement Costs. Settlement Costs include gas fees for posting data to the parent chain (e.g., Ethereum calldata or blobs) and any other direct operational expenses like batch posting. Only positive net revenue triggers the 10% fee; losses or zero profit incur no payment. - **AEP Fee Router**: A set of deployable contracts (e.g., `RewardDistributor` or custom distributors) that automatically routes the 10% share. It integrates with the chain's fee collectors (e.g., for surplus fees) and handles cross-chain transfers (e.g., bridging to Ethereum then to a DAO-controlled address on Arbitrum One). ## Compatibility - **DA Modes**: Applies across Rollup, AnyTrust, and Alt-DA, as settlement costs vary by mode (e.g., lower in Alt-DA). - **Gas Tokens**: For custom `ERC-20`'s, requires conversion mechanisms; native `ETH` simplifies bridging. -- **Validation**: No impact on BoLD or permissioned setups. +- **Validation**: No impact on BoLD or permissioned setups. ## Pros @@ -38,14 +38,14 @@ The configuration ensures compliance with the AEP terms, streamlines reporting, ## Examples -- **DeFi-Focused Orbit Chain**: Configures the router to route 10% of surplus fees (after Ethereum posting costs) to the DAO, using a custom gas token with oracle-based pricing for accurate `ETH` conversion. +- **DeFi-Focused Arbitrum Chain**: Configures the router to route 10% of surplus fees (after Ethereum posting costs) to the DAO, using a custom gas token with oracle-based pricing for accurate `ETH` conversion. - **Gaming L3 Chain**: Low-revenue setups might skip full configuration initially but enable it upon profitability, bridging fees quarterly. ## How to configure 1. **Calculate Net Revenue**: Use tools or scripts to track total fees minus settlement costs (e.g., via on-chain queries or off-chain monitoring). For custom tokens, deploy a pricer contract to value fees in `ETH` equivalents. -2. **Deploy Fee Router**: Use the Orbit SDK script (e.g., [`aep-fee-router`](https://github.com/OffchainLabs/arbitrum-orbit-sdk/tree/main/examples/setup-aep-fee-router)) to deploy contracts like RewardDistributor on your chain. Set it as a fee collector (e.g., for surplus fees via `ArbOwner` precompile). -3. **Route and Bridge Fees**: Configure the router to send the 10% share to Ethereum (e.g., via native bridges), then deposit to the DAO address on Arbitrum One. Use functions like `RewardDistributor.distributeRewards` for periodic transfers. +2. **Deploy Fee Router**: Use the Arbitrum Chain SDK script (e.g., [`aep-fee-router`](https://github.com/OffchainLabs/arbitrum-chain-sdk/tree/main/examples/setup-aep-fee-router)) to deploy contracts like RewardDistributor on your chain. Set it as a fee collector (e.g., for surplus fees via `ArbOwner` precompile). +3. **Route and bridge Fees**: Configure the router to send the 10% share to Ethereum (e.g., via native bridges), then deposit to the DAO address on Arbitrum One. Use functions like `RewardDistributor.distributeRewards` for periodic transfers. 4. **Report Fees**: Submit quarterly reports to the Arbitrum Foundation, including calculations and proofs of payment, to maintain license compliance. -This setup reflects Arbitrum's collaborative model, ensuring custom chains contribute back while benefiting from the ecosystem. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This setup reflects Arbitrum's collaborative model, ensuring custom chains contribute back while benefiting from the ecosystem. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx index dcff20036e..ec3db7a690 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-alt-da.mdx @@ -8,14 +8,14 @@ content_type: configuration import AltDAPCPartial from '../../partials/_alt-da-pc.mdx'; -Choosing alternative data availability (Alt-DA) refers to configuring the chain to use a third-party data availability layer instead of Arbitrum's native options. This feature allows developers to post transaction batch data to external DA providers for storage and accessibility, rather than relying solely on Ethereum (L1) or Arbitrum's built-in mechanisms. Alt-DA integrations expand the flexibility of the Arbitrum Nitro stack, enabling optimized trade-offs in cost, scalability, and security. +Choosing alternative data availability (Alt-DA) refers to configuring the chain to use a third-party data availability layer instead of Arbitrum's native options. This feature allows developers to post transaction batch data to external DA providers for storage and accessibility, rather than relying solely on Ethereum (L1) or Arbitrum's built-in mechanisms. Alt-DA integrations expand the flexibility of the Arbitrum Nitro stack, enabling optimized trade-offs in cost, scalability, and security. -Selecting Alt-DA means integrating an external provider into your Orbit chain's configuration, often via modifications to the Nitro software stack. Developers can also set fallback preferences (e.g., try Alt-DA first, then AnyTrust, then Ethereum) to ensure resilience if the primary DA fails. This choice is ideal for applications prioritizing ultra-low fees and massive scalability, such as gaming, social, or data-intensive dApps, where the cost of posting to Ethereum would be prohibitive. +Selecting Alt-DA means integrating an external provider into your Arbitrum chain's configuration, often via modifications to the Nitro software stack. Developers can also set fallback preferences (e.g., try Alt-DA first, then AnyTrust, then Ethereum) to ensure resilience if the primary DA fails. This choice is ideal for applications prioritizing ultra-low fees and massive scalability, such as gaming, social, or data-intensive dApps, where the cost of posting to Ethereum would be prohibitive. ## Key Concepts -- **Data Availability (DA) in Arbitrum Orbit**: DA ensures that transaction data is stored and retrievable for verification, fraud proofs, and node synchronization in optimistic rollups. Arbitrum chains are customizable with different DA setups to suit specific needs, such as high-throughput apps or cost-sensitive projects. - - **Alt-DA**: Posting transaction batches post to an external, modular DA network (e.g., specialized blockchains designed for DA). Only proofs of availability (e.g., commitments or certificates) post to the parent chain. This process decouples DA from settlement, allowing for specialized optimization. +- **Data Availability (DA) in Arbitrum chains**: DA ensures that transaction data is stored and retrievable for verification, fraud proofs, and node synchronization in optimistic rollups. Arbitrum chains are customizable with different DA setups to suit specific needs, such as high-throughput apps or cost-sensitive projects. + - **Alt-DA**: Posting transaction batches post to an external, modular DA network (e.g., specialized blockchains designed for DA). Only proofs of availability (e.g., commitments or certificates) post to the parent chain. This process decouples DA from settlement, allowing for specialized optimization. ## How It Differs: @@ -28,11 +28,11 @@ Selecting Alt-DA means integrating an external provider into your Orbit chain's ## Examples of Alt-DA Providers -Arbitrum Orbit supports integrations with several Alt-DA solutions, including: +Arbitrum chains supports integrations with several Alt-DA solutions, including: -- **Celestia**: A modular DA blockchain using data availability sampling for lightweight verification. +- **Celestia**: A modular DA blockchain using data availability sampling for lightweight verification. - **Avail**: Focuses on high-throughput DA with erasure coding. - **EigenDA (via EigenLayer)**: Leverages restaking for secure, decentralized DA. - For a list of Alt-DA providers, refer to the [Third-party providers page](launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#data-availability-providers-for-anytrust-chains) -This option reflects the growing trend toward modular blockchain architectures, where DA handling is separate to scale ecosystems like Arbitrum without compromising core security. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This option reflects the growing trend toward modular blockchain architectures, where DA handling is separate to scale ecosystems like Arbitrum without compromising core security. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx index 923896c2de..7b79d28845 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-anytrust.mdx @@ -8,22 +8,22 @@ content_type: configuration import AnytrustPCPartial from '../../partials/_anytrust-pc.mdx'; -Choosing AnyTrust mode refers to selecting the AnyTrust protocol as the data availability (DA) mechanism for a chain, such as when deploying custom chains via Arbitrum Orbit. AnyTrust is an alternative to the pure Rollup mode, prioritizing cost efficiency and performance over maximum decentralization. +Choosing AnyTrust mode refers to selecting the AnyTrust protocol as the data availability (DA) mechanism for a chain, such as when deploying custom chains. AnyTrust is an alternative to the pure Rollup mode, prioritizing cost efficiency and performance over maximum decentralization. -Opting for AnyTrust means configuring your Arbitrum-based chain to use this DA approach for reduced operational costs and better scalability, while accepting a slight trade-off in trust-minimization compared to posting all data directly to L1 (as in Rollup mode). +Opting for AnyTrust means configuring your Arbitrum-based chain to use this DA approach for reduced operational costs and better scalability, while accepting a slight trade-off in trust-minimization compared to posting all data directly to L1 (as in Rollup mode). -It's ideal for use cases where ultra-low fees are a priority over Ethereum's full security guarantees, such as consumer apps or high-frequency trading platforms. Developers can set up and configure a DAC via Arbitrum's tools, including defining the committee size and keyset threshold. This flexibility allows tailoring to specific needs within the Arbitrum ecosystem, and it's compatible with other Orbit features like custom gas tokens or third-party DA integrations. +It's ideal for use cases where ultra-low fees are a priority over Ethereum's full security guarantees, such as consumer apps or high-frequency trading platforms. Developers can set up and configure a DAC via Arbitrum's tools, including defining the committee size and keyset threshold. This flexibility allows tailoring to specific needs within the Arbitrum ecosystem, and it's compatible with other Arbitrum chain features like custom gas tokens or third-party DA integrations. ## Key Concepts -- **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. - **AnyTrust Mode**: - Transaction data is initially submitted off-chain to a permissioned group of nodes called the Data Availability Committee (DAC), typically consisting of around 20 members (though configurable). - - The DAC stores the data and signs a Data Availability Certificate (DACert), which posts to the parent chain. Full data is not posted onchain unless requested (e.g., during a challenge). - - Security relies on a "keyset" where at least two honest members are assumed to prevent data withholding—far milder than centralized assumptions but not fully trustless like Rollup mode. + - The DAC stores the data and signs a Data Availability Certificate (DACert), which posts to the parent chain. Full data is not posted onchain unless requested (e.g., during a challenge). + - Security relies on a "keyset" where at least two honest members are assumed to prevent data withholding—far milder than centralized assumptions but not fully trustless like Rollup mode. -This option reflects the growing trend toward modular blockchain architectures, where DA handling is separate to scale ecosystems like Arbitrum without compromising core security. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This option reflects the growing trend toward modular blockchain architectures, where DA handling is separate to scale ecosystems like Arbitrum without compromising core security. For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-RaaS-providers). diff --git a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx index a2eabbe8c5..9a1cec5a16 100644 --- a/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx +++ b/docs/launch-arbitrum-chain/features/common/data-availability/choose-rollup.mdx @@ -8,7 +8,7 @@ content_type: configuration import RollupPCPartial from '../../partials/_rollup-pc.mdx'; -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. +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. @@ -16,14 +16,14 @@ This flexibility allows developers to tailor chains to specific needs while buil ## Key Concepts -- **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. - **Arbitrum Rollup Mode**: - - All batch transaction data is posted directly to the parent chain (Ethereum L1) as calldata or blobs. + - All batch transaction data is posted directly to the parent chain (Ethereum L1) as calldata or blobs. - This inherits Ethereum's full security and decentralization, with no additional trust assumptions—data is always available on-chain for anyone to access and verify. - - Example: Arbitrum One operates in this mode. + - Example: Arbitrum One operates in this mode. -For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx index 64ff85aa35..0793c44e22 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-custom-gas-token.mdx @@ -8,20 +8,20 @@ content_type: configuration import CustomGasTokenPCPartial from '../../partials/_custom-gas-token-pc.mdx'; -Choosing a custom gas token refers to configuring the chain to use a specific `ERC-20` token—rather than `ETH`—as the native currency for paying transaction fees (gas costs) on your chain. This allows developers to tailor the fee structure to their project's ecosystem, such as using a stablecoin like `USDC`, a yield-bearing asset, or the project's own native token. The choice is made during chain deployment and is generally immutable afterward, integrating directly into the chain's genesis parameters. +Choosing a custom gas token refers to configuring the chain to use a specific `ERC-20` token—rather than `ETH`—as the native currency for paying transaction fees (gas costs) on your chain. This allows developers to tailor the fee structure to their project's ecosystem, such as using a stablecoin like `USDC`, a yield-bearing asset, or the project's own native token. The choice is made during chain deployment and is generally immutable afterward, integrating directly into the chain's genesis parameters. ## Key Concepts -- **Gas and Fees in Arbitrum**: Gas represents the computational resources required for transactions and smart contract executions. Fees are calculated as gas used multiplied by gas price, covering sequencer costs, data posting to the parent chain (e.g., Ethereum or another Arbitrum chain), and network maintenance. In standard setups (like Arbitrum One), these are paid in `ETH`. -- **Custom Gas Token**: An `ERC-20` token deployed on the parent chain is "natively bridged" to the new Orbit chain and set as the gas token. Transactions on the child chain are validated against users' balances of this token, with fees deducted accordingly. The token must meet strict requirements: standard `ERC-20` compliance (no proxies, hooks, rebasing, or transfer fees), typically 18 decimals, and transfers/approvals must not revert in edge cases. +- **Gas and Fees in Arbitrum**: Gas represents the computational resources required for transactions and smart contract executions. Fees are calculated as gas used multiplied by gas price, covering Sequencer costs, data posting to the parent chain (e.g., Ethereum or another Arbitrum chain), and network maintenance. In standard setups (like Arbitrum One), these are paid in `ETH`. +- **Custom Gas Token**: An `ERC-20` token deployed on the parent chain is "natively bridged" to the new Arbitrum chain and set as the gas token. Transactions on the child chain are validated against users' balances of this token, with fees deducted accordingly. The token must meet strict requirements: standard `ERC-20` compliance (no proxies, hooks, rebasing, or transfer fees), typically 18 decimals, and transfers/approvals must not revert in edge cases. ## How Fees Are Handled - **On the child chain**: Gas costs are calculated and deducted in the custom token. -- **For data posting to the parent chain**: The sequencer or batch poster collects custom tokens as revenue but must convert them to the parent's native token (e.g., `ETH`) to cover posting costs. This is managed via an exchange rate mechanism, such as a pricer contract that uses manual updates, oracles, or trade tracking. Inaccurate rates can lead to over- or under-reimbursement, impacting profitability. +- **For data posting to the parent chain**: The sequencer or batch poster collects custom tokens as revenue but must convert them to the parent's native token (e.g., `ETH`) to cover posting costs. This is managed via an exchange rate mechanism, such as a pricer contract that uses manual updates, oracles, or trade tracking. Inaccurate rates can lead to over- or under-reimbursement, impacting profitability. - **Compatibility with Chain Types**: - - **Rollup Mode**: Supported for L2 chains posting data to Ethereum, requiring BoLD (Bounded Liquidity Delay) enabled and a fee token pricer for exchange rates. L3 support is planned but not yet available. + - **Rollup Mode**: Supported for L2 chains posting data to Ethereum, requiring BoLD (Bounded Liquidity Delay) enabled and a fee token pricer for exchange rates. L3 support is planned but not yet available. - **AnyTrust Mode**: Directly supported with simpler configuration (no heavy pricer emphasis), ideal for cost-sensitive setups. - **Alt-DA (Alternative Data Availability)**: Compatible, especially with cheaper DA providers like Celestia or EigenDA, which reduce conversion risks from token volatility. @@ -34,4 +34,4 @@ Choosing a custom gas token refers to configuring the chain to use a specific `E - **Bridged USDC**: Allows stable, predictable fees. - Project-native tokens in gaming or DeFi appchains, where users pay fees in the ecosystem's token for seamless integration. -For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +For implementation, refer to the docs or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx index a1454a5c42..6733c7fbe6 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-fee-rebates.mdx @@ -6,27 +6,27 @@ sme: jason-w123 content_type: configuration --- -Choosing fee rebates refers to configuring the chain's fee management system to enable the distribution or return of a portion of collected transaction fees (gas fees) back to users, developers, dApps, or other stakeholders. This is achieved through customizable fee collectors and optional distributor contracts, allowing chain owners to implement rebate mechanisms as part of the chain's economic model. +Choosing fee rebates refers to configuring the chain's fee management system to enable the distribution or return of a portion of collected transaction fees (gas fees) back to users, developers, dApps, or other stakeholders. This is achieved through customizable fee collectors and optional distributor contracts, allowing chain owners to implement rebate mechanisms as part of the chain's economic model. Rebates can incentivize usage, reward high-volume participants, or align with project tokenomics, but they are not a default setting—instead, they require intentional configuration during or after deployment. This choice contrasts with directing all fees to a single owner or treasury address without redistribution. -Configuration requires chain owner privileges and can be done post-deployment using precompiles or the Arbitrum Orbit SDK. It's compatible with all DA modes (Rollup, AnyTrust, Alt-DA) and gas tokens (native `ETH` or custom), though custom tokens add complexity in exchange rate management for reimbursements. For example, surplus fees could be rebated to high-activity users or contributed to a community fund. +Configuration requires chain owner privileges and can be done post-deployment using precompiles or the Arbitrum Arbitrum Chain SDK. It's compatible with all DA modes (Rollup, AnyTrust, Alt-DA) and gas tokens (native `ETH` or custom), though custom tokens add complexity in exchange rate management for reimbursements. For example, surplus fees could be rebated to high-activity users or contributed to a community fund. ## Key Concepts -- **Gas and Fees in Arbitrum Orbit**: Fees are charged for transaction execution and data posting, denominated in the chain's gas token (`ETH` by default or a custom `ERC-20`). They cover operational costs like sequencing, data availability, and parent chain interactions. Surplus fees (beyond minimum costs) can accumulate during congestion, providing a pool for potential rebates. +- **Gas and Fees in Arbitrum chains**: Fees are charged for transaction execution and data posting, denominated in the chain's gas token (`ETH` by default or a custom `ERC-20`). They cover operational costs like sequencing, data availability, and parent chain interactions. Surplus fees (beyond minimum costs) can accumulate during congestion, providing a pool for potential rebates. - **Fee Rebates**: Rebates involve returning part of the paid fees, often as incentives. In Orbit chains, this isn't an explicit "rebate toggle" but is facilitated by routing fees to smart contracts that automate distributions (e.g., proportional payouts). This can mimic rebate programs seen in dApps on Arbitrum (e.g., trading fee rebates funded by incentives), but applied at the chain level. ## Types of Fees Available for Rebates - **Orbit Base Fee**: Minimum execution fee; routed to an infrastructure account. - **Orbit Surplus Fee**: Congestion-based extra; routed to a network account. -- **Parent Chain Base Fee**: Data posting cost; routed to batch poster collectors. +- **Parent Chain Base Fee**: Data posting cost; routed to batch poster collectors. - **Parent Chain Surplus Fee**: Optional batch poster reward; routed to a reward recipient. ## Compatibility and Considerations -- **With Custom Gas Tokens**: Rebates work but require a fee token pricer for parent chain reimbursements (e.g., converting custom tokens to `ETH`). Pricers (manual, oracle-based, or trade-tracking) ensure accurate reimbursements to batch posters, which can include refund-like mechanics if reserves are managed. +- **With Custom Gas Tokens**: Rebates work but require a fee token pricer for parent chain reimbursements (e.g., converting custom tokens to `ETH`). Pricers (manual, oracle-based, or trade-tracking) ensure accurate reimbursements to batch posters, which can include refund-like mechanics if reserves are managed. - **With Native `ETH`**: Simpler, as no conversions are needed; rebates can be direct `ETH` payouts. ## Pros @@ -54,4 +54,4 @@ Configuration requires chain owner privileges and can be done post-deployment us - **Tools**: Use command-line (cast) or SDK extensions like `arbOwnerActions` for programmatic setup. -This feature underscores Arbitrum's modularity, allowing tailored fee economics while inheriting Ethereum security. For implementation, refer to official docs, SDK examples, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This feature underscores Arbitrum's modularity, allowing tailored fee economics while inheriting Ethereum security. For implementation, refer to official docs, SDK examples, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx index 7d2e1052f7..e48d4a3fb4 100644 --- a/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx +++ b/docs/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-eth.mdx @@ -8,15 +8,15 @@ content_type: configuration import NativeETHPCPartial from '../../partials/_native-eth-pc.mdx'; -Choosing native Ethereum refers to configuring the chain to use `ETH`—the native currency of Ethereum—as the gas token for paying transaction fees. This is the default option in Orbit deployments, in contrast to selecting a custom `ERC-20` token for gas. The choice is set during chain deployment via genesis parameters and is immutable afterward, directly impacting how users pay for gas and how operators handle revenue and costs. +Choosing native Ethereum refers to configuring the chain to use `ETH`—the native currency of Ethereum—as the gas token for paying transaction fees. This is the default option in Arbitrum chain deployments, in contrast to selecting a custom `ERC-20` token for gas. The choice is set during chain deployment via genesis parameters and is immutable afterward, directly impacting how users pay for gas and how operators handle revenue and costs. -Selecting native `ETH` means users must hold and spend `ETH` for all onchain activities, simplifying the fee mechanism without additional layers like token swaps or pricers. For operators, revenue is collected directly in `ETH`, which can be used seamlessly for data availability (DA) costs on the parent chain (e.g., posting to Ethereum). +Selecting native `ETH` means users must hold and spend `ETH` for all onchain activities, simplifying the fee mechanism without additional layers like token swaps or pricers. For operators, revenue is collected directly in `ETH`, which can be used seamlessly for data availability (DA) costs on the parent chain (e.g., posting to 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. ## Key Concepts -- **Gas and Fees in Arbitrum**: Gas measures computational work for transactions and executions, with fees equaling gas used times gas price. These cover sequencer operations, data posting to the parent chain (e.g., Ethereum), and network upkeep. In native `ETH` setups, all fees are denominated, paid, and settled in `ETH`. +- **Gas and Fees in Arbitrum**: Gas measures computational work for transactions and executions, with fees equaling gas used times gas price. These cover Sequencer operations, data posting to the parent chain (e.g., Ethereum), and network upkeep. In native `ETH` setups, all fees are denominated, paid, and settled in `ETH`. - **Native `ETH` as Gas Token**: The chain executes transactions against users' `ETH` balances, deducting fees directly in `ETH`. No token conversions are needed, aligning the chain's economics with Ethereum's standard model. ## How Fees Are Handled @@ -27,8 +27,8 @@ This option prioritizes straightforward integration with Ethereum's ecosystem, a ## Compatibility with Chain Types -- Works with all Orbit DA modes, including Rollup (posting to Ethereum), AnyTrust (DAC-based), and Alt-DA (e.g., Celestia), without restrictions. -- No special setup beyond standard deployment tools like the Orbit portal or scripts. +- Works with all Arbitrum chain DA modes, including Rollup (posting to Ethereum), AnyTrust (DAC-based), and Alt-DA (e.g., Celestia), without restrictions. +- No special setup beyond standard deployment tools like the Arbitrum portal or scripts. ## How It Differs from Custom Gas Tokens @@ -41,7 +41,7 @@ This option prioritizes straightforward integration with Ethereum's ecosystem, a ## Examples -- Standard Arbitrum chains like Arbitrum One use native `ETH` for broad Ethereum compatibility and simplicity. -- In contrast, some Orbit chains opt for custom tokens like bridged `USDC` for stable fees, but native `ETH` suits projects prioritizing Ethereum alignment over custom economics. +- Standard Arbitrum chains like Arbitrum One use native `ETH` for broad Ethereum compatibility and simplicity. +- In contrast, some Arbitrum chains opt for custom tokens like bridged `USDC` for stable fees, but native `ETH` suits projects prioritizing Ethereum alignment over custom economics. -This default choice emphasizes reliability and Ethereum-native operations within Arbitrum's modular framework. For deployment details, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This default choice emphasizes reliability and Ethereum-native operations within Arbitrum's modular framework. For deployment details, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx index 39330d8edc..e991345c84 100644 --- a/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx +++ b/docs/launch-arbitrum-chain/features/common/mev/choose-timeboost.mdx @@ -8,7 +8,7 @@ content_type: configuration import TimeboostPCPartial from '../../partials/_timeboost-pc.mdx'; -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. +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. Enabling it is an owner-level decision, typically for chains with significant DeFi activity where MEV opportunities justify the trade-offs, and it can be done without halting operations (falling back to FCFS if no auction winner). @@ -17,13 +17,13 @@ It's ideal for DeFi-heavy chains with substantial MEV (e.g., arbitrage opportuni ## Key Concepts - **MEV in Arbitrum**: MEV refers to the profit extractable from transaction ordering, such as through arbitrage, liquidations, or backrunning. Under default FCFS, MEV often goes to searchers via latency races (e.g., faster hardware), leading to network spam and no revenue for the chain. Timeboost internalizes this by auctioning a time-based edge, diverting competition to bids while limiting harmful MEV via no reordering or visibility into other transactions. -- **Express Lane**: A special sequencer endpoint (`timeboost_sendExpressLaneTransaction`) where the auction winner (controller) can submit transactions without an artificial delay. Non-express transactions get a default 200ms delay added to their arrival timestamp, potentially pushing them to the next block (but block times remain ~250ms). The controller gets no guarantees of top-of-block positioning or profitability—value comes from predicted MEV during the round (default 60s). -- **Offchain Auction**: A sealed-bid, second-price auction (winner pays the second-highest bid) run by an autonomous auctioneer every round. Bids use a configurable `ERC-20` token (e.g., `WETH`; no fee-on-transfer or rebasing tokens) and must meet a minimum reserve price (default 0.001 `WETH`). Auctions close 15s before the round starts, with bids verifiable on-chain. Limit of 5 bids per address per round to prevent DDoS. -- **Auction Contract**: Deployed on-chain, it handles deposits (withdrawable after ~2 minutes), bid resolution, and proceeds transfer to a beneficiary (e.g., chain owner or burn address) via `flushBeneficiaryBalance()`. +- **Express Lane**: A special Sequencer endpoint (`timeboost_sendExpressLaneTransaction`) where the auction winner (controller) can submit transactions without an artificial delay. Non-express transactions get a default 200ms delay added to their arrival timestamp, potentially pushing them to the next block (but block times remain ~250ms). The controller gets no guarantees of top-of-block positioning or profitability—value comes from predicted MEV during the round (default 60s). +- **Offchain Auction**: A sealed-bid, second-price auction (winner pays the second-highest bid) run by an autonomous auctioneer every round. Bids use a configurable `ERC-20` token (e.g., `WETH`; no fee-on-transfer or rebasing tokens) and must meet a minimum reserve price (default 0.001 `WETH`). Auctions close 15s before the round starts, with bids verifiable on-chain. Limit of 5 bids per address per round to prevent DDoS. +- **auction contract**: Deployed on-chain, it handles deposits (withdrawable after ~2 minutes), bid resolution, and proceeds transfer to a beneficiary (e.g., chain owner or burn address) via `flushBeneficiaryBalance()`. ## Compatibility -Works with any Arbitrum chain (L2/L3), all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens (native `ETH` or custom), and validation (BoLD or permissioned). Compatible with centralized or future decentralized sequencers; no prerequisites beyond a bid token and infrastructure. Not formally supported yet. +Works with any Arbitrum chain (L2/L3), all DA modes (Rollup, AnyTrust, Alt-DA), gas tokens (native `ETH` or custom), and validation (BoLD or permissioned). Compatible with centralized or future decentralized sequencers; no prerequisites beyond a bid token and infrastructure. Not formally supported yet. @@ -31,16 +31,16 @@ Works with any Arbitrum chain (L2/L3), all DA modes (Rollup, AnyTrust, Alt-DA), ## Examples -- **Arbitrum One and Nova**: Generates revenue from MEV auctions while protecting users. -- **Custom Orbit Chains**: DeFi-focused L3s enable it for revenue (e.g., using custom tokens for bids), while low-activity chains skip it. +- **Arbitrum One and Nova**: Generates revenue from MEV auctions while protecting users. +- **Custom Arbitrum Chains**: DeFi-focused L3s enable it for revenue (e.g., using custom tokens for bids), while low-activity chains skip it. ## How to configure -1. **Deploy Auction Contract**: Use Orbit scripts (e.g., from `[orbit-actions](https://github.com/OffchainLabs/orbit-actions)` repo) with a `.env` file specifying addresses (e.g., proxy admin, bid token like `WETH`, beneficiary). Run `forge script` to deploy and verify. -2. **Run Auctioneer Services**: Set up Redis for coordination; run bid validator (verifies bids) and auction server (resolves auctions) using the `autonomous-auctioneer` binary from Nitro (Docker or local build). +1. **Deploy Auction Contract**: Use Arbitrum chain scripts (e.g., from `[orbit-actions](https://github.com/OffchainLabs/orbit-actions)` repo) with a `.env` file specifying addresses (e.g., proxy admin, bid token like `WETH`, beneficiary). Run `forge script` to deploy and verify. +2. **Run Auctioneer Services**: Set up Redis for coordination; run bid validator (verifies bids) and auction server (resolves auctions) using the `autonomous-auctioneer` binary from Nitro (Docker or local build). 3. **Configure Sequencer**: Update node config to enable `timeboost` and `auctioneer` APIs, pointing to the contract and Redis. - Verify via logs (e.g., "New express lane auction round") and test bids/submissions. - Post-enable, adjust parameters like round duration (60s default) or delay (200ms) via owner privileges. -This feature enhances Arbitrum's modularity for MEV-aware chains but requires careful evaluation. For details, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This feature enhances Arbitrum's modularity for MEV-aware chains but requires careful evaluation. For details, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx index a5b4658d98..e848209cb8 100644 --- a/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx +++ b/docs/launch-arbitrum-chain/features/common/ux/choose-fast-withdrawals.mdx @@ -8,7 +8,7 @@ content_type: configuration import FastwithdrawalsPCPartial from '../../partials/_fast-withdrawals-pc.mdx'; -Enabling fast withdrawals refers to configuring the chain to use a fast confirmation mechanism that allows transactions and state assertions to achieve finality much quicker than the standard multi-day challenge period in optimistic rollups. This is achieved by routing assertions through a permissioned committee of validators (often overlapping with the Data Availability Committee or DAC in AnyTrust mode) that unanimously confirms them via a multisig wallet, bypassing the full fraud-proof window. As a result, users can withdraw assets or access finalized states in as little as 15 minutes for L2 chains or 15 seconds for L3 chains, significantly enhancing user experience by reducing wait times and enabling faster cross-chain interactions. +Enabling fast withdrawals refers to configuring the chain to use a fast confirmation mechanism that allows transactions and state assertions to achieve finality much quicker than the standard multi-day challenge period in optimistic rollups. This is achieved by routing assertions through a permissioned committee of validators (often overlapping with the Data Availability Committee or DAC in AnyTrust mode) that unanimously confirms them via a multisig wallet, bypassing the full fraud-proof window. As a result, users can withdraw assets or access finalized states in as little as 15 minutes for L2 chains or 15 seconds for L3 chains, significantly enhancing user experience by reducing wait times and enabling faster cross-chain interactions. Enabling this feature shifts the chain from relying solely on time-based fraud proofs to a committee-driven confirmation process, where validators (recommended to be at least three for reduced trust risks) must agree unanimously. It's primarily recommended for AnyTrust chains, as it leverages the existing DAC trust model without adding new assumptions—ideally, DAC members run the validators. @@ -16,14 +16,14 @@ For pure Rollup chains, enabling it effectively introduces a committee trust lay ## Key Concepts -- **Standard Withdrawal Process**: In optimistic Rollups like Arbitrum, assertions about the chain's state (e.g., transaction batches) are posted to the parent chain (e.g., Ethereum or Arbitrum One) and remain challengeable for a configurable period (default ~6.4-7 days) to allow fraud proofs. Unchallenged assertions confirm, enabling secure withdrawals, but this delays user access to funds. -- **Fast Withdrawals Mechanism**: When enabled, a committee (e.g., an `n/n` multisig Safe wallet) of validators processes and unanimously signs assertions at a set interval. This provides immediate confirmation, with finality tied to the parent chain's block times rather than the full challenge period. For example, L2 chains on Ethereum can confirm in ~15 minutes (above Ethereum's ~12.8-minute finality), while L3 chains on Arbitrum One can leverage "soft finality" (~250ms sequencer confirmations) for near-instant speeds. +- **Standard Withdrawal Process**: In optimistic Rollups like Arbitrum, assertions about the chain's state (e.g., transaction batches) are posted to the Parent chain (e.g., Ethereum or Arbitrum One) and remain challengeable for a configurable period (default ~6.4-7 days) to allow fraud proofs. Unchallenged assertions confirm, enabling secure withdrawals, but this delays user access to funds. +- **Fast Withdrawals Mechanism**: When enabled, a committee (e.g., an `n/n` multisig Safe wallet) of validators processes and unanimously signs assertions at a set interval. This provides immediate confirmation, with finality tied to the parent chain's block times rather than the full challenge period. For example, L2 chains on Ethereum can confirm in ~15 minutes (above Ethereum's ~12.8-minute finality), while L3 chains on Arbitrum One can leverage "soft finality" (~250ms Sequencer confirmations) for near-instant speeds. - **Related Parameters**: Often paired with adjusting the `minimumAssertionPeriod` (e.g., to 1 block for frequent assertions) and node flags to control posting intervals. ## Compatibility - **DA Modes**: Optimized for AnyTrust (leverages DAC); possible but not recommended for Rollup or Alt-DA, as it adds trust assumptions. -- **Validation**: Works with BoLD (permissionless) or pre-BoLD (permissioned), but the committee must be allowlisted. +- **Validation**: Works with BoLD (permissionless) or pre-BoLD (permissioned), but the committee must be allowlisted. - **Gas Tokens**: No restrictions; compatible with native `ETH` or custom `ERC-20`s. - **Parent Chain**: Interval must exceed the parent's finality time (e.g., >12.8 minutes for Ethereum L2s). (Refer to [Key Concepts above](#key-concepts) for more information about the Fast Withdrawal Mechanism.) @@ -33,7 +33,7 @@ For pure Rollup chains, enabling it effectively introduces a committee trust lay ## Impact on User Experience -From a UX perspective, enabling fast withdrawals transforms slow, multi-day processes into near-real-time ones, making the chain feel more responsive. Users get quicker access to withdrawn funds (e.g., 15 minutes vs. 6.4 days), reducing frustration and capital lockup. Apps benefit from faster cross-chain state reads, enabling seamless interactions such as oracle updates and multi-chain DeFi. However, it assumes users trust the committee (e.g., for high-value transfers), and any load-based delays could still impact predictability. Overall, it's ideal for consumer-facing apps like gaming or social, where speed is key. +From a UX perspective, enabling fast withdrawals transforms slow, multi-day processes into near-real-time ones, making the chain feel more responsive. Users get quicker access to withdrawn funds (e.g., 15 minutes vs. 6.4 days), reducing frustration and capital lockup. Apps benefit from faster cross-chain state reads, enabling seamless interactions such as oracle updates and multi-chain DeFi. However, it assumes users trust the committee (e.g., for high-value transfers), and any load-based delays could still impact predictability. Overall, it's ideal for consumer-facing apps like gaming or social, where speed is key. ## Examples @@ -42,11 +42,13 @@ From a UX perspective, enabling fast withdrawals transforms slow, multi-day proc ## How to configure -1. **Upgrade Contracts and Nodes**: Ensure nitro-contracts v2.1.0+ (update `RollupAdminLogic` and `RollupUserLogic`) and node software to nitro v3.1.2+. Use the Orbit versioner script to check and upgrade. -2. **Run Configuration Scripts**: Use the Orbit SDK (e.g., setup-fast-withdrawal example) or Orbit actions repo (e.g., fast-confirm script with Foundry's cast CLI) to create a Safe multisig for the committee, add validators to the allowlist, set the Safe as the `anytrustFastConfirmer`, and optionally adjust `minimumAssertionPeriod` (defaults to 75 blocks ~15 minutes, measured in the first non-Arbitrum ancestor chain's blocks). +1. **Upgrade Contracts and Nodes**: Ensure nitro-contracts v2.1.0+ (update `RollupAdminLogic` and `RollupUserLogic`) and node software to nitro v3.1.2+. Use the Arbitrum chain versioner script to check and upgrade. +2. **Run Configuration Scripts**: Use the Arbitrum Chain SDK (e.g., setup-fast-withdrawal example) or Orbit actions repo (e.g., fast-confirm script with Foundry's cast CLI) to create a Safe multisig for the committee, add validators to the allowlist, set the Safe as the `anytrustFastConfirmer`, and optionally adjust `minimumAssertionPeriod` (defaults to 75 blocks ~15 minutes, measured in the first non-Arbitrum ancestor chain's blocks). 3. **Configure Nodes**: - - Batch Poster: Set `--node.batch-poster.max-delay` to match the assertion period (e.g., 15m). + - batch Poster: Set `--node.batch-poster.max-delay` to match the + assertion + period (e.g., 15m). - Validators (BoLD mode): Enable `--node.bold.enable-fast-confirmation=true` and set `--node.bold.assertion-posting-interval` to the period. - Validators (pre-BoLD): Similar flags like `--node.staker.enable-fast-confirmation=true` and `--node.staker.make-assertion-interval`. -This feature aligns with Arbitrum's focus on scalable, user-friendly chains while maintaining core security. For setup, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This feature aligns with Arbitrum's focus on scalable, user-friendly chains while maintaining core security. For setup, consult the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx index 27b0d6420b..6efebf4047 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-bold.mdx @@ -8,19 +8,19 @@ content_type: configuration import BoldPCPartial from '../../partials/_bold-pc.mdx'; -Upgrading or configuring the chain to use the Bounded Liquidity Delay (BoLD) protocol as its dispute resolution mechanism means replacing the legacy 1-vs-1 challenge system with a permissionless, all-vs-all dispute framework that enhances validation and security by allowing anyone to participate in challenging invalid state assertions through bonding, while ensuring disputes resolve within a fixed time bound (up to two challenge periods, typically ~12.8 days on Ethereum). It's enabled via an administrative upgrade on the parent chain (e.g., Ethereum). It is mandatory for certain Arbitrum chain configurations, such as using custom gas tokens in Rollup mode when posting directly to Ethereum. +Upgrading or configuring the chain to use the Bounded Liquidity Delay (BoLD) protocol as its dispute resolution mechanism means replacing the legacy 1-vs-1 challenge system with a permissionless, all-vs-all dispute framework that enhances validation and security by allowing anyone to participate in challenging invalid state assertions through bonding, while ensuring disputes resolve within a fixed time bound (up to two challenge periods, typically ~12.8 days on Ethereum). It's enabled via an administrative upgrade on the parent chain (e.g., Ethereum). It is mandatory for certain Arbitrum chain configurations, such as using custom gas tokens in Rollup mode when posting directly to Ethereum. -For the chain, it resets the challenge clock for in-flight withdrawals (adding up to 6.4 days delay, with a max of 12.8 days total), handles overflow assertions for accumulated blocks during upgrade, and requires at least one active proposer (validator in MakeNodes mode) to advance the chain. Chain owners configure bond sizes (e.g., 3600 `ETH` for assertions on Arbitrum One equivalents) and can add incentives like service fees or bounties. This choice prioritizes enhanced security and decentralization over the legacy system's potential for centralized control, making the chain more resilient to attacks but introducing economic considerations for participation. +For the chain, it resets the challenge clock for in-flight withdrawals (adding up to 6.4 days delay, with a max of 12.8 days total), handles overflow assertions for accumulated blocks during upgrade, and requires at least one active proposer (validator in MakeNodes mode) to advance the chain. Chain owners configure bond sizes (e.g., 3600 `ETH` for assertions on Arbitrum One equivalents) and can add incentives like service fees or bounties. This choice prioritizes enhanced security and decentralization over the legacy system's potential for centralized control, making the chain more resilient to attacks but introducing economic considerations for participation. ## Key Concepts -- **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. +- **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. - **Security Through Disputes**: Disputes narrow disagreements via bisections (binary search over computation steps, up to `2^69` in total space) across levels (block, BigStep for WASM ranges, SmallStep for single steps). Honest validators use offchain software (e.g., Nitro in Defensive mode) to automatically challenge invalid assertions, generating deterministic fraud proofs. Security relies on economic incentives: bonds are posted and forfeited by losers, deterring malice. -- **BoLD Protocol**: BoLD introduces an "all-vs-all" (battle royale) model where multiple parties can challenge and defend simultaneously via "edges" (claims about history segments). It uses timers based on parent chain blocks, trustless bonding pools for crowdsourced stakes, and recursive sub-challenges to ensure a single honest party can always win against any number of adversaries. This bounds liquidity delays (hence the name) and mitigates "delay attacks" where malicious parties could previously prolong disputes indefinitely. +- **BoLD Protocol**: BoLD introduces an "all-vs-all" (battle royale) model where multiple parties can challenge and defend simultaneously via "edges" (claims about history segments). It uses timers based on parent chain blocks, trustless bonding pools for crowdsourced stakes, and recursive sub-challenges to ensure a single honest party can always win against any number of adversaries. This bounds liquidity delays (hence the name) and mitigates "delay attacks" where malicious parties could previously prolong disputes indefinitely. ## Compatibility with Chain Types -BoLD is required for Rollup mode with custom gas tokens posting to Ethereum (to handle conversions securely). It's compatible with AnyTrust and Alt-DA modes but focuses on L2/L3 chains settling on Ethereum for maximum security. Post-upgrade, the chain uses BoLD for all new assertions. +BoLD is required for Rollup mode with custom gas tokens posting to Ethereum (to handle conversions securely). It's compatible with AnyTrust and Alt-DA modes but focuses on L2/L3 chains settling on Ethereum for maximum security. Post-upgrade, the chain uses BoLD for all new assertions. ## How It Differs from Legacy Protocols @@ -33,7 +33,7 @@ BoLD is required for Rollup mode with custom gas tokens posting to Ethereum (to ## Examples -- **Arbitrum One and Nova**: Upgraded to BoLD for permissionless validation, allowing public testnets and community validators to secure the chains. -- **Custom Orbit Chains**: Projects like gaming or DeFi appchains choose BoLD to enable decentralized validation, especially when using Rollup mode with Ethereum settlement for high-security needs. +- **Arbitrum One and Nova**: Upgraded to BoLD for permissionless validation, allowing public testnets and community validators to secure the chains. +- **Custom Arbitrum Chains**: Projects like gaming or DeFi appchains choose BoLD to enable decentralized validation, especially when using Rollup mode with Ethereum settlement for high-security needs. -This upgrade aligns with Arbitrum's modular ethos, bolstering trust-minimization while inheriting Ethereum's security. For implementation, refer to the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This upgrade aligns with Arbitrum's modular ethos, bolstering trust-minimization while inheriting Ethereum's security. For implementation, refer to the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx index b2e3f33c7b..842e13ff0a 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-challenge-period.mdx @@ -6,17 +6,17 @@ sme: jason-w123 content_type: configuration --- -Choosing or configuring the challenge period refers to setting the duration (measured in parent chain blocks) during which state assertions—claims about the chain's execution history, block hashes, and inbox messages—can be disputed via fraud proofs before they are confirmed as valid on the parent chain (e.g., Ethereum or an Arbitrum L2). +Choosing or configuring the challenge period refers to setting the duration (measured in parent chain blocks) during which state assertions—claims about the chain's execution history, block hashes, and inbox messages—can be disputed via fraud proofs before they are confirmed as valid on the parent chain (e.g., Ethereum or an Arbitrum L2). -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`). It's set by the chain owner and can be chosen based on the application's risk tolerance—e.g., high-value DeFi might opt for longer periods, while gaming appchains favor shorter ones. ## Key Concepts -- **Challenge Period (`confirmPeriodBlocks`)**: The main window for validators to bond stakes and initiate challenges against potentially fraudulent assertions. If no valid challenge is raised, the assertion confirms, and the chain's state advances securely. +- **Challenge Period (`confirmPeriodBlocks`)**: The main window for validators to bond stakes and initiate challenges against potentially fraudulent assertions. If no valid challenge is raised, the assertion confirms, and the chain's state advances securely. - **Extra Challenge Period (`extraChallengeTimeBlocks`)**: A post-main-period buffer to resolve any ongoing disputes or last-minute challenges, preventing premature finalization. -- **Measurement**: Always denominated in the underlying L1 chain's blocks (e.g., Ethereum's `block.number`, ~12 seconds per block), even for L3 chains settling to an L2 like Arbitrum One. This ensures consistent timing aligned with the parent chain's finality. +- **Measurement**: Always denominated in the underlying L1 chain's blocks (e.g., Ethereum's `block.number`, ~12 seconds per block), even for L3 chains settling to an L2 like Arbitrum One. This ensures consistent timing aligned with the parent chain's finality. - **Defaults**: - **Primary**: Approximately 45,818 L1 blocks (~1 week or 6.4 days on Ethereum). - **Extra**: 200 L1 blocks (~40 minutes). @@ -26,7 +26,7 @@ It's set by the chain owner and can be chosen based on the application's risk to - **With DA Modes**: Fully compatible across Rollup (full on-chain DA), AnyTrust (DAC-based), and Alt-DA (e.g., Celestia). In AnyTrust, fast withdrawals can reduce the effective period to 15 minutes by leveraging the DAC for rapid verification, bypassing traditional delays. - **With Gas Tokens**: No direct impact; works with native `ETH` or custom `ERC-20`s, as the period governs validation timing rather than fee mechanics. -- **With Validation (e.g., BoLD)**: Integrates with BoLD's permissionless disputes, where the period sets the initial challenge window, but BoLD bounds total delays to at most two periods (~12.8 days max on Ethereum) during active disputes, mitigating delay attacks. +- **With Validation (e.g., BoLD)**: Integrates with BoLD's permissionless disputes, where the period sets the initial challenge window, but BoLD bounds total delays to at most two periods (~12.8 days max on Ethereum) during active disputes, mitigating delay attacks. ## Pros @@ -48,7 +48,7 @@ It's set by the chain owner and can be chosen based on the application's risk to ## When to configure -- **During Deployment**: Specified in the `RollupCreator` configuration (e.g., via the Orbit SDK deployment portal or scripts like `createRollup.ts`). For example, set `confirmPeriodBlocks` to 30,000 for ~4.5 days. +- **During Deployment**: Specified in the `RollupCreator` configuration (e.g., via the Arbitrum Chain SDK deployment portal or scripts like `createRollup.ts`). For example, set `confirmPeriodBlocks` to 30,000 for ~4.5 days. - **Post-Deployment**: Dynamically updated via owner-privileged contract calls, such as `Rollup.setConfirmPeriodBlocks(newValue)` for the primary period or `Rollup.setExtraChallengeTimeBlocks(newExtraTimeBlocks)` for the extra buffer (e.g., using tools like cast for onchain transactions). -This parameter underscores Arbitrum's modular design, allowing chains to fine-tune validation without compromising core fraud-proof security. For implementation, refer to the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This parameter underscores Arbitrum's modular design, allowing chains to fine-tune validation without compromising core fraud-proof security. For implementation, refer to the official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). diff --git a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx index 7e8c2a30b6..63d0ed83c7 100644 --- a/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx +++ b/docs/launch-arbitrum-chain/features/common/validation-and-security/choose-permissioned-validators.mdx @@ -8,13 +8,13 @@ content_type: configuration import PermissionedValidatorsPCPartial from '../../partials/_permissioned-validators-pc.mdx'; -Choosing permissioned validators refers to configuring the chain to use a legacy dispute resolution protocol where only an allowlisted set of entities (e.g., approved by the chain owner or DAO) can participate in validation activities, such as posting state assertions, opening challenges, and resolving disputes. This contrasts with enabling the Bounded Liquidity Delay (BoLD) protocol for permissionless validation. The choice is made during chain deployment or via upgrades, often through governance, and prioritizes controlled oversight over broad decentralization. It's suitable for chains where limiting participants reduces operational complexity or economic risks, but it introduces trust assumptions in the allowlist. +Choosing permissioned validators refers to configuring the chain to use a legacy dispute resolution protocol where only an allowlisted set of entities (e.g., approved by the chain owner or DAO) can participate in validation activities, such as posting state assertions, opening challenges, and resolving disputes. This contrasts with enabling the Bounded Liquidity Delay (BoLD) protocol for permissionless validation. The choice is made during chain deployment or via upgrades, often through governance, and prioritizes controlled oversight over broad decentralization. It's suitable for chains where limiting participants reduces operational complexity or economic risks, but it introduces trust assumptions in the allowlist. -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 allowlist using tools like the Arbitrum Chain 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. :::note -If allowlisted validators were to go offline, after a period, anyone could remove the validator allowlist and the chain would then become permissionless. +If allowlisted validators were to go offline, after a period, anyone could remove the validator allowlist and the chain would then become permissionless. ::: @@ -22,8 +22,8 @@ This choice is configurable for all DA modes (Rollup, AnyTrust, Alt-DA) and gas ## Key Concepts -- **Validation in Arbitrum**: Validators monitor and advance the chain's state by posting assertions (claims about block hashes, history commitments, and inbox messages) to the parent chain (e.g., Ethereum or an L2 like Arbitrum One). If an assertion is suspected of being invalid, challengers initiate interactive fraud proofs during a challenge window (typically ~6.4 days), bisecting disagreements down to verifiable one-step proofs executed on-chain. Security relies on economic incentives, where invalid claims lead to bond forfeitures. -- **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. +- **Validation in Arbitrum**: Validators monitor and advance the chain's state by posting assertions (claims about block hashes, history commitments, and inbox messages) to the parent chain (e.g., Ethereum or an L2 like Arbitrum One). If an assertion is suspected of being invalid, challengers initiate interactive fraud proofs during a challenge window (typically ~6.4 days), bisecting disagreements down to verifiable one-step proofs executed on-chain. Security relies on economic incentives, where invalid claims lead to bond forfeitures. +- **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. :::note @@ -33,7 +33,7 @@ BoLD allows is configurable to include an allowlist of validators, instead of th ## Compatibility with Chain Types -Works with L2/L3 Arbitrum chains settling to Ethereum or other L2s. For AnyTrust chains (e.g., like Arbitrum Nova), validation typically remains permissioned even post-BoLD upgrades, as the Data Availability Committee (DAC) already introduces trust assumptions, and permissionless bonds could invite griefing attacks. +Works with L2/L3 Arbitrum chains settling to Ethereum or other L2s. For AnyTrust chains (e.g., like Arbitrum Nova), validation typically remains permissioned even post-BoLD upgrades, as the Data Availability Committee (DAC) already introduces trust assumptions, and permissionless bonds could invite griefing attacks. @@ -42,6 +42,6 @@ Works with L2/L3 Arbitrum chains settling to Ethereum or other L2s. For AnyTrust ## Examples - **Arbitrum Nova**: Retains permissioned validation post-BoLD due to its lower TVL and AnyTrust model, where the DAC members double as validators for controlled security. -- **Custom Orbit Chains**: Early-stage gaming or enterprise L3s might choose permissioned to limit access to internal teams, avoiding the economic overhead of BoLD while testing. +- **Custom Arbitrum Chains**: Early-stage gaming or enterprise L3s might choose permissioned to limit access to internal teams, avoiding the economic overhead of BoLD while testing. -This option balances security with practicality in Arbitrum's ecosystem, but for maximum trust-minimization, BoLD's permissionless model is recommended for mature chains. Consult the latest official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers). +This option balances security with practicality in Arbitrum's ecosystem, but for maximum trust-minimization, BoLD's permissionless model is recommended for mature chains. Consult the latest official docs, or your RaaS; a [list of RaaSes is on the Third-party providers page](/launch-arbitrum-chain/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers).