docs: tw568-arbitrum-chain-feature-config-structure #2802
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
pete-vielhaber
commented
Oct 20, 2025
pete-vielhaber
commented
- Added structure for Arbitrum chains -> Features
- Common:
- Configure AEP
- configure aep fees
- Data Availability
- choose alt-da
- choose anytrust
- choose rollup
- Gas and fees
- choose custom gas token
- choose fee rebates
- choose native eth
- MEV
- choose timeboost
- UX
- choose fast withdrawals
- Validation and Security
- choose bold
- choose challenge period
- choose permissioned validators
- Configure AEP
- Advanced
- choose arbos version
- choose chain precompiles
- choose custom behavior
- choose custom delay inbox finality
- Common:
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Jason-W123
reviewed
Nov 6, 2025
|
|
||
| 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). |
Contributor
There was a problem hiding this comment.
We need to ask users to upgrade node and validator first then set new wasm module root or node will throw unknow wasm module root error.
So maybe just change the sequence of point 2 and point 3 here.
Jason-W123
reviewed
Nov 6, 2025
| ## 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. |
Contributor
There was a problem hiding this comment.
Suggested change
| - **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. |
greeting function is just a very simple education example, maybe here we can give a production example like local zk-proof function.
Jason-W123
reviewed
Nov 6, 2025
| ## 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. |
Contributor
There was a problem hiding this comment.
Suggested 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. |
We don't need to mention view methods here
Jason-W123
reviewed
Nov 6, 2025
|
|
||
| ## Cons | ||
|
|
||
| - Requires deep expertise in Go, Solidity, and Nitro; complex setup and maintenance. |
Contributor
There was a problem hiding this comment.
We can also mention that customize precompiles will cause wasm module root changes, thus will introduce more works.
Jason-W123
reviewed
Nov 6, 2025
| - 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. | ||
|
|
Contributor
There was a problem hiding this comment.
Those examples above are for eduction, I would like to add a production example here as well:
- Add a zk proof function here so chains can process zk related work more efficiency than evm based.
Jason-W123
reviewed
Nov 6, 2025
| 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. |
Contributor
There was a problem hiding this comment.
Before changes launch, we still need to re-do all the stuff that mentioned at custom arbos version steps as this will also make changes to stf. We need ask users to continue to follow the steps we mentioned at choose-arbos-version.mdx page.
Jason-W123
reviewed
Nov 6, 2025
| @@ -0,0 +1,52 @@ | |||
| --- | |||
| title: 'Why choose to customize the behavior on your Arbitrum chain' | |||
Contributor
There was a problem hiding this comment.
For these 3 docs:
- Why choose a specific ArbOS version on your Arbitrum chain
- Why choose to customize the precompiles on your Arbitrum chain
- Why choose to customize the behavior on your Arbitrum chain
Their relationship is: Doc 3 includes Doc 1, and Doc 1 includes Doc 2.
(i.e., customizing behavior > choosing ArbOS version > customizing precompiles)
Should we also mention it somewhere?
Jason-W123
reviewed
Nov 6, 2025
| - **Non-STF**: Adding an RPC for multi-block queries (no STF/fraud updates needed). | ||
|
|
||
| ## How to configure | ||
|
|
Contributor
There was a problem hiding this comment.
I think customize chain behavior should include those customization to non-stf logic like sequencer logic, should we add those contents as well?
Jason-W123
reviewed
Nov 6, 2025
| author: pete-vielhaber | ||
| sme: | ||
| content_type: configuration | ||
| --- |
Contributor
There was a problem hiding this comment.
Looks like this docs's content mismatch the tittle?
Jason-W123
reviewed
Nov 6, 2025
|
|
||
| ## 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. |
Contributor
There was a problem hiding this comment.
Suggested change
| - **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) 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. |
Contributor
There was a problem hiding this comment.
Btw, I am not familiar with the aep mechanism so I might be wrong here. Do we have any source that pointed to $60,000 annually profit?
Also, we can also add an refer to af docs here: https://docs.arbitrum.foundation/new-arb-chains#arbitrum-expansion-program-aep ?
Jason-W123
reviewed
Nov 8, 2025
| ## 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). |
Contributor
There was a problem hiding this comment.
Suggested change
| 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). |
There is no script called aep-fee-router.ts, instead the folder name is aep-fee-router.
Jason-W123
reviewed
Nov 8, 2025
|
|
||
| 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. |
Contributor
There was a problem hiding this comment.
flushBeneficiaryBalance is used for Timeboost, the method of aep should be RewardDistributor.distributeRewards
Suggested change
| 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. |
Jason-W123
reviewed
Nov 8, 2025
| - **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). |
Contributor
There was a problem hiding this comment.
Suggested change
| - 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). |
Jason-W123
reviewed
Nov 8, 2025
|
|
||
| ## 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. |
Contributor
There was a problem hiding this comment.
Suggested change
| - **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. |
I think will be posted to parent chain will make more sense here since some data will be expired.
Jason-W123
reviewed
Nov 8, 2025
|
|
||
| ## 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. |
Contributor
There was a problem hiding this comment.
Suggested change
| 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. |
setFeeCollector() method is in ArbAggregator precompile
Jason-W123
reviewed
Nov 8, 2025
|
|
||
| 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). |
Contributor
There was a problem hiding this comment.
setNetworkFeeAccount should be covered at point 1, we can delete this point
Jason-W123
reviewed
Nov 8, 2025
| ## 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. |
Contributor
There was a problem hiding this comment.
Suggested change
| - **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. |
Jason-W123
reviewed
Nov 8, 2025
| 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`. |
Contributor
There was a problem hiding this comment.
Suggested change
| - 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`. |
Jason-W123
reviewed
Nov 8, 2025
| ## 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. |
Contributor
There was a problem hiding this comment.
Bold can also setup allowlist validator
Jason-W123
reviewed
Nov 8, 2025
|
|
||
| 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. |
Contributor
There was a problem hiding this comment.
We can also add a point to state if validators go offline, after a period, anyone can remove the validator allowlist and the chain will become permissionless of validator.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.