Merge pull request #2802 from OffchainLabs/tw568-arbitrum-chain-feature-config-structure

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

Author: pete-vielhaber

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.

docs/launch-arbitrum-chain/features/advanced/choose-arbos-version.mdx

@@ -0,0 +1,57 @@
+---
+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: jason-w123
+content_type: configuration
+---
+
+Customizing the <a data-quicklook-from="arbos">ArbOS</a> version involves modifying the Nitro codebase to introduce a new, version-controlled iteration of ArbOS (<a data-quicklook-from="arbitrum">Arbitrum</a>'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 <a data-quicklook-from="state-transition-function">State Transition Function</a> (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.
+- **<a data-quicklook-from="wasm">WASM</a> Module Root**: A 32-byte hash of the STF's implementation (e.g., 0x8b104a2e80ac6165dc58b9048de12f301d70b02a0ab51396c22b4b4b802a16a4 for ArbOS 20). Customizations require updating this on the <a data-quicklook-from="parent-chain">parent chain</a> 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 (<a data-quicklook-from="bold">BoLD</a>/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; Arbitrum 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 <a data-quicklook-from="offchain-labs">Offchain Labs</a> review; higher costs for expertise.
+
+### Examples
+
+- **New <a data-quicklook-from="precompile">precompile</a> 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" }`.
+
+:::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. **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.
+
+This reflects Arbitrum's modularity but demands rigorous testing. Refer to the docs or your <a data-quicklook-from="raas">RaaS</a>; 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).

docs/launch-arbitrum-chain/features/advanced/choose-chain-precompiles.mdx

@@ -0,0 +1,71 @@
+---
+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: jason-w123
+content_type: configuration
+---
+
+Customizing your chain's precompiles refers to modifying or extending the built-in, system-level <a data-quicklook-from="smart-contract">smart contract</a>-like functions (precompiles) that provide efficient access to chain-specific operations, such as interacting with the <a data-quicklook-from="parent-chain">parent chain</a> (<a data-quicklook-from="l1">L1</a> or <a data-quicklook-from="l2">L2</a>), 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 <a data-quicklook-from="arbitrum">Arbitrum</a>-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 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
+
+There are several approaches, each building on the Nitro codebase:
+
+- **Add new methods to an existing <a data-quicklook-from="precompile">precompile</a>**: 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 <a data-quicklook-from="arbos">ArbOS</a> state by adding storage variables and methods to read/write them, allowing persistent chain-specific data.
+
+## Compatibility with chain types
+
+- 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 <a data-quicklook-from="bold">BoLD</a> or permissioned 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.
+- Customizing the precompiles will cause <a data-quicklook-from="wasm">WASM</a> 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 <a data-quicklook-from="offchain-labs">Offchain Labs</a>; 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.
+- 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.
+
+**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
+
+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. 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.
+
+This advanced customization aligns with Arbitrum's modular design but demands careful planning and testing. For implementation, refer to the docs or your <a data-quicklook-from="raas">RaaS</a>; 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).

docs/launch-arbitrum-chain/features/advanced/choose-custom-behavior.mdx

@@ -0,0 +1,52 @@
+---
+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: 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 <a data-quicklook-from="state-transition-function">State Transition Function</a> (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 <a data-quicklook-from="arbos">ArbOS</a> (<a data-quicklook-from="arbitrum">Arbitrum</a>'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., <a data-quicklook-from="raas">RaaS</a> providers), as <a data-quicklook-from="offchain-labs">Offchain Labs</a> 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.
+- **<a data-quicklook-from="wasm">WASM</a> Module Root**: A 32-byte hash representing the STF's implementation, which must be updated on the <a data-quicklook-from="parent-chain">parent chain</a> 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 Arbitrum chain DA modes (Rollup, AnyTrust, Alt-DA), gas tokens, and validation (<a data-quicklook-from="bold">BoLD</a> 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 <a data-quicklook-from="precompile">precompile</a> 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/06-third-party-integrations/02-third-party-providers.md#rollup-as-a-service-raas-providers).