docs: tw351-arbchain-stake-validator-config

docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/04-stake-and-validator-configurations.mdx

@@ -1,13 +1,106 @@
 ---
-title: 'Stake and validator configurations'
-description: 'Learn how to configure your Arbitrum chain with a custom stake and validator configurations'
-author:
+title: 'Bond and validator configurations'
+description: 'Learn how to configure your Arbitrum chain with a custom bond and validator configurations'
+author: pete-vielhaber
 sme:
 content_type: how-to
 tags: ['hide-from-search']
 unlisted: true
 ---
 
-- **Base Stake**: Minimum bond required for validators.
-- **Stake Token**: Token used for staking.
-- **Loser Stake Escrow**: Address for escrowed funds from losing validators.
+<a data-quicklook-from="arbitrum">Arbitrum</a> Orbit chains are customizable Layer 3 (L3) chains that
+settle to an Arbitrum Layer 2 (L2) chain, such as Arbitrum One. They support <a data-quicklook-from="validator">
+  validator
+</a> configurations to ensure chain security through bonding and <a data-quicklook-from="assertion">
+  assertion
+</a> challenges. Validators post assertions about the chain's state on the parent L2 chain and can <a data-quicklook-from="challenge">
+  challenge
+</a> incorrect assertions. Arbitrum (Orbit) chains can be permissioned, meaning validators must be allowlisted.
+
+Bonding is required for active validation, where validators place bond funds to participate. If a validator loses a challenge (e.g., due to a faulty assertion), their bond is escrowed or burned. Configurations such as the `stakeToken`, `baseStake`, and `loserStakeEscrow` are configurable during chain deployment or post-deployment via contract calls.
+
+Arbitrum (Orbit) chains may utilize the <a data-quicklook-from="bold">BoLD</a> (Bounded Liquidity Delay) protocol for efficient dispute resolution, which affects bonding tokens (e.g., `WETH` for BoLD-enabled chains like Arbitrum One/Nova, or `ETH`/native for other chains).
+
+## `stakeToken`
+
+The bonded token is the asset that validators must bond to participate in asserting the chain's state on the parent L2 chain. It serves as collateral for challenges. The default is `ETH` (or parent chain's native token).
+
+### Configuration details
+
+- Can be `ETH` (native gas token) or any `ERC-20` token.
+- **For BoLD-enabled chains** (e.g., settling to Arbitrum One or Nova), it defaults to `WETH`.
+- **For non-BoLD chains**, it defaults to the <a data-quicklook-from="parent-chain">parent chain</a>'s native token (usually `ETH`).
+- Currently, it's often hardcoded to `ETH` in basic deployments, but customizable to an `ERC-20` contract address in advanced setups. Future updates will expand `ERC-20` support.
+
+### How to Configure
+
+- During deployment in the [Arbitrum Orbit deployment portal](https://orbit.arbitrum.io/):
+  1.  Connect your <a data-quicklook-from="wallet">wallet</a> (may require switching to Arbitrum Sepolia for testnets).
+  2.  In the configuration form, enter the bond token's contract address on the parent L2 chain.
+  3.  Use `0x0000000000000000000000000000000000000000` for `ETH`.
+- **Post-deployment**: Not directly modifiable; set during initial [Rollup contract](https://github.com/OffchainLabs/arbitrum-orbit-deployment-ui/blob/e4e82fca2428ad4c8a20ef19b7b958293ffef958/src/types/rollupConfigDataType.ts) creation.
+
+## `baseStake`
+
+The `baseStake` is the minimum amount of the bond token that validators must deposit to bond and post assertions.
+
+### Configuration details
+
+- Specified as a float value (e.g., in `wei` for `ETH`).
+- Must be greater than 0.
+- **Balances security**: Low values ease entry but risk malicious challenges; high values deter attacks but exclude smaller validators.
+
+### How to configure
+
+- During deployment in the Orbit <a data-quicklook-from="portal">portal</a>:
+  1.  In the configuration form, enter the `baseStake` amount as a float.
+  2.  Review and deploy the chain (submits transactions to the parent chain).
+- **Post-deployment**: Adjustable via the [Rollup contract](https://github.com/OffchainLabs/arbitrum-orbit-deployment-ui/blob/e4e82fca2428ad4c8a20ef19b7b958293ffef958/src/types/rollupConfigDataType.ts) if permissions allow (e.g., as <a data-quicklook-from="chain-owner">chain owner</a>).
+
+## `loserStakeEscrow`
+
+The `loserStakeEscrow` is the address where a validator's bonded funds are sent if they lose a challenge (e.g., due to an incorrect assertion). This mechanism acts as a penalty. The default configuration has no default specified; must be configured.
+
+### Configuration details
+
+- Funds are escrowed rather than immediately burned, allowing potential recovery or governance decisions.
+- Recommended: Set to an address controlled by the chain owner(s) for management, or a burn address (e.g., `0x000000000000000000000000000000000000dEaD`) if funds should be permanently removed.
+
+### How to configure
+
+- **During deployment**: Set in the `loserStakeEscrow` field of the `RollupCreator` configuration.
+- **Post-deployment**:
+  1. As the chain owner or upgrade executor, call the `Rollup.setLoserStakeEscrow`(address `newEscrow`) function on the [Rollup contract](https://github.com/OffchainLabs/arbitrum-orbit-deployment-ui/blob/e4e82fca2428ad4c8a20ef19b7b958293ffef958/src/types/rollupConfigDataType.ts).
+  2. Use tools like Etherscan or a wallet (e.g., MetaMask) to interact with the contract on the parent chain.
+
+## Validator configurations and how to setup them up
+
+Validators are configured during chain deployment and can be run post-launch. Arbitrum (Orbit) chains support permissioned validators, that can be added to an allowlist.
+
+### During deployment (initial setup)
+
+1. In the Orbit deployment portal:
+   - Specify the number of initial validators (e.g., `1` for devnets, more for production).
+   - The first validator address is auto-generated with a private key (stored in downloaded JSON configs).
+   - Add additional validator addresses (e.g., your wallet addresses); they get allowlisted in the Rollup contract.
+2. Download `nodeConfig.json` and `orbitSetupScriptConfig.json` (these files contain validator private keys—back them up securely).
+3. Clone the [orbit-setup-script repo](https://github.com/OffchainLabs/orbit-setup-script).
+4. Move configs to the `config` directory.
+5. Run the setup script (e.g., via Docker or locally) to fund and initialize validators:
+
+- Example command to fund: `yarn run fund-bonder --privateKey 0xYourPrivateKey --l2rpc https://sepolia.arbitrum.io/rpc --l3rpc http://localhost:8449`.
+
+6. Deploy the chain; validators can now bonded with the specified `baseStake` token.
+
+### Adding validators post-deployment (permissioned chains)
+
+1. As the upgrade executor (chain admin), call `setValidator(address[] calldata validators, bool[] calldata isValidator)` on the Rollup contract to update the allowlist.
+2. Ensure the new validator has a wallet funded with the base stake amount in the stake token.
+
+Refer to the [Run a full node](/run-arbitrum-node/02-run-full-node.mdx) article for instructions on how to get up and running.
+
+### Assertion interval
+
+Default to one hour for new assertions (via `--node.staker.make-assertion-interval`); must exceed the Rollup's `minimumAssertionPeriod` (~15 minutes).
+
+For production, run multiple validators in a network. Test on devnets first. Always back up keys, as they're needed to withdraw bonds. If issues arise, refer to the official Arbitrum docs for updates, as configurations evolve.

sidebars.js

@@ -315,6 +315,11 @@ const sidebars = {
                   id: 'launch-arbitrum-chain/configure-your-chain/common-configurations/enable-post-4844-blobs',
                   label: `Enable blob transactions`,
                 },
+                {
+                  type: 'doc',
+                  id: 'launch-arbitrum-chain/configure-your-chain/common-configurations/stake-and-validator-configurations',
+                  label: `Stake and validator configuration`,
+                },
                 {
                   type: 'doc',
                   id: 'launch-arbitrum-chain/configure-your-chain/common-configurations/arbitrum-chain-finality',