berachain · camembera · Apr 28, 2026 · Apr 28, 2026 · May 14, 2026
diff --git a/.cursor/rules.md b/.cursor/rules.md
@@ -343,7 +343,8 @@ Use updates for changelogs:
 
 - Fixed pagination issue with large datasets
 - Resolved authentication timeout problems
-  </Update>
+
+</Update>
 
 ## Required page structure
 

diff --git a/AGENTS.md b/AGENTS.md
@@ -105,6 +105,14 @@ This project uses **Mintlify** for documentation (not VitePress like the submodu
 4. Maintain consistency with existing documentation in this repository
 5. Reference specific files in the submodule when asking for help or examples
 
+### Redirect Policy
+
+- When a live documentation URL would otherwise begin returning `404`, add a redirect in `docs.json`.
+- If a page is moved, redirect the old URL to the new canonical location.
+- If a page is removed without a direct replacement, choose the closest substitute page and get maintainer approval before adding the redirect destination.
+- Do not leave a previously live documentation URL to 404 without explicit maintainer agreement.
+- After changing redirects, run `make check-redirects` against a running docs server when practical.
+
 ## EVM execution page — Beacon Kit genesis (`nodes/architecture/evm-execution.mdx`)
 
 When editing this page (execution client versions and network genesis downloads):

diff --git a/Makefile b/Makefile
@@ -1,4 +1,6 @@
 
+default: contracts-generate format check
+
 help:
 	@echo "Common docs tasks:"
 	@echo "  make dev                # Run local Mintlify server (http://localhost:3000)"

diff --git a/build/bex/sdk/reference.mdx b/build/bex/sdk/reference.mdx
@@ -15,10 +15,10 @@ The `BalancerApi` class provides helper functions for interacting with the Beran
 const balancerApi = new BalancerApi(apiUrl: string, chainId: ChainId);
 ```
 
-| Name    | Type   | Description                | Mainnet Value                                    |
-| ------- | ------ | -------------------------- | ------------------------------------------------ |
+| Name    | Type   | Description                | Mainnet Value                |
+| ------- | ------ | -------------------------- | ---------------------------- |
 | apiUrl  | string | Url of API                 | `https://api.berachain.com/` |
-| chainId | number | Chain that will be queried | `80094`                                          |
+| chainId | number | Chain that will be queried | `80094`                      |
 
 ### Properties
 

diff --git a/docs.json b/docs.json
@@ -272,58 +272,61 @@
         "tab": "Nodes",
         "groups": [
           {
-            "group": "Overview",
+            "group": "Concepts & Architecture",
             "pages": [
               "nodes/overview/index",
-              "nodes/overview/node-architecture"
-            ]
-          },
-          {
-            "group": "BeaconKit",
-            "pages": [
-              "nodes/beaconkit/overview"
-            ]
-          },
-          {
-            "group": "Architecture",
-            "pages": [
+              "nodes/overview/node-architecture",
               "nodes/architecture/validator-lifecycle",
               "nodes/architecture/beaconkit-consensus",
               "nodes/architecture/evm-execution"
             ]
           },
           {
-            "group": "Operations",
+            "group": "Setup & Deployment",
             "pages": [
               "nodes/operations/quickstart",
               "nodes/operations/bera-geth-to-reth",
               "nodes/operations/self-hosted-rpc",
-              "nodes/operations/production-checklist",
-              "nodes/operations/monitoring",
-              "nodes/operations/fusaka"
+              "nodes/guides/local-devnet-docker",
+              "nodes/guides/local-devnet-kurtosis",
+              {
+                "group": "Staking Pools",
+                "root": "nodes/staking-pools/overview",
+                "pages": [
+                  "nodes/staking-pools/installation",
+                  "nodes/staking-pools/operators",
+                  "nodes/staking-pools/delegators",
+                  "nodes/staking-pools/contracts"
+                ]
+              }
             ]
           },
           {
-            "group": "Staking Pools",
+            "group": "Day-2 Operations",
             "pages": [
-              "nodes/staking-pools/overview",
-              "nodes/staking-pools/installation",
-              "nodes/staking-pools/operators",
-              "nodes/staking-pools/delegators",
-              "nodes/staking-pools/contracts"
+              "nodes/operations/production-checklist",
+              "nodes/operations/monitoring",
+              "nodes/operations/fusaka",
+              "nodes/guides/become-a-validator",
+              {
+                "group": "Being a Validator",
+                "pages": [
+                  "nodes/guides/change-operator-address",
+                  "nodes/guides/manage-reward-allocations",
+                  "nodes/guides/manage-incentives-commission",
+                  "nodes/guides/increase-validator-stake",
+                  "nodes/guides/withdraw-stake"
+                ]
+              }
             ]
           },
           {
-            "group": "Guides",
+            "group": "Reference",
             "pages": [
-              "nodes/guides/become-a-validator",
-              "nodes/guides/change-operator-address",
-              "nodes/guides/manage-reward-allocations",
-              "nodes/guides/increase-validator-stake",
-              "nodes/guides/withdraw-stake",
-              "nodes/guides/local-devnet-docker",
-              "nodes/guides/local-devnet-kurtosis",
-              "nodes/guides/manage-incentives-commission"
+              "nodes/beaconkit/overview",
+              "nodes/beaconkit/api",
+              "nodes/beaconkit/cli",
+              "nodes/beaconkit/configuration"
             ]
           },
           {
@@ -521,17 +524,17 @@
     },
     {
       "source": "/beacon-kit/api",
-      "destination": "/nodes/beaconkit/overview",
+      "destination": "/nodes/beaconkit/api",
       "permanent": true
     },
     {
       "source": "/beacon-kit/cli",
-      "destination": "/nodes/beaconkit/overview",
+      "destination": "/nodes/beaconkit/cli",
       "permanent": true
     },
     {
       "source": "/beacon-kit/configuration",
-      "destination": "/nodes/beaconkit/overview",
+      "destination": "/nodes/beaconkit/configuration",
       "permanent": true
     },
     {
@@ -1340,4 +1343,4 @@
       "permanent": true
     }
   ]
-}
+}
diff --git a/nodes/architecture/evm-execution.mdx b/nodes/architecture/evm-execution.mdx
@@ -7,6 +7,8 @@ Berachain is 100% EVM-compatible, operating on a lightly modified Reth. We keep
 
 The execution layer consists of an EVM execution client. This client handles transactions, transaction gossiping, state management, and support for the Ethereum Virtual Machine — it is not responsible for block building.
 
+By using Bera-Reth, the execution client supports cutting-edge EVM features natively. For developers looking to understand what the execution client supports, check out the [Protocol Features](/build/protocol/overview) section in the Build tab, which includes overviews of [EIP-7702 (Native Account Abstraction)](/build/protocol/eip7702-basics) and [EIP-5792](/build/protocol/eip5792-overview).
+
 Recommended **[Beacon Kit](https://github.com/berachain/beacon-kit)** and **[Bera-Reth](https://github.com/berachain/bera-reth)** versions depend on the network:
 
 | Network | Beacon Kit                                                                    | Bera-Reth                                                                    |

diff --git a/nodes/architecture/validator-lifecycle.mdx b/nodes/architecture/validator-lifecycle.mdx
@@ -7,7 +7,7 @@ description: "Validator states and transitions: Deposited, Eligible, Active, Exi
 
 A validator in Berachain is a participant responsible for proposing and attesting to new blocks, helping secure the network and maintain consensus. Validators stake a required amount of the network's native token ($BERA) as collateral, which serves both as an economic incentive to behave honestly and as a mechanism for penalizing malicious behavior.
 
-Validators can operate independently with direct staking, or they can operate **staking pools** that allow community members to stake BERA through smart contracts and receive liquid shares (stBERA). Staking pools follow the same validator lifecycle described in this document. For information about operating staking pools, see the [Staking Pools documentation](/nodes/staking-pools/overview).
+Validators can operate independently with direct staking, or they can operate **staking pools** that allow community members to stake BERA through smart contracts and receive liquid shares (stBERA). For information about operating staking pools, see the [Staking Pools documentation](/nodes/staking-pools/overview).
 
 Validators have several key responsibilities:
 
@@ -25,70 +25,84 @@ The Validator's Voting Power is the amount of `$BERA` they have deposited, round
   />
 </Frame>
 
-The labeled states are as follows:
+## The Active Set & Stake Requirements
 
-- **Deposited**  
-  Deposit event captured by Beacon-kit and deposit message signature is verified.
+The **Active Set** is the limited group of validators currently participating in the consensus layer and proposing blocks.
+The current limit of validators in the active set is **69**.
 
-- **Eligible**  
-  Validator has been marked as eligible for the activation queue.
+To enter the active set, you must meet the minimum stake requirements. This requirement depends on whether the active set is full:
 
-- **Active**  
-  The validator is marked as Active after 1 epoch from the Eligible state. Currently, the Active Set consists of **69** Validators, which is the number of Validators that can propose blocks.
+- If the active set is not full, the minimum stake requirement is **250,000** `$BERA`.
+- If the active set is full, the minimum stake requirement is **10,000** `$BERA` more than the amount staked by the last validator in the active set.
 
-- **Exited**  
-  The validator is marked for exit if the validator set cap (**69**) is hit and the validator has the lowest effective balance or a lower-order pubKey if it has the same effective balance as another validator.
+It can take up to **3** epochs (**192** blocks per epoch) for deposits to be processed and for a validator to be included in the active set.
 
-- **Withdrawn**  
-  Once the validator is marked as exited, after **256** epochs on mainnet (**32** on Bepolia), validator funds are fully withdrawn. All `$BERA` staked to a Validator is returned to the Validator's Withdrawal Credentials Address.
+For step-by-step instructions on spinning up a validator, see the [Become a Validator](/nodes/guides/become-a-validator) guide.
 
-## Deposited state
+## Direct Staking & Withdrawal Addresses
 
-The validator's journey begins with a deposit transaction on the **Execution Layer** (via the Deposit Contract). Once this deposit transaction is successful and emits an event, beacon-kit nodes capture it and process it for signature verification.
+Berachain follows Proof-of-Stake (PoS) direct staking, which allows `$BERA` holders to directly stake their `$BERA` to a validator.
 
-The initial deposit transaction establishes a connection between a validator's Consensus Layer identity and its Execution Layer identity and decides the withdrawal address for the $BERA stake.
+When a validator makes their first deposit, they define a **Withdrawal Credentials Address**. If funds are withdrawn from a validator, or if the validator is evicted from the active set, _all_ funds are returned to this single address.
+
+This means that validators must communicate clearly with their delegators about how they will handle and manually return funds if the validator is removed from the active set.
+
+<Warning>
+  Avoid staking to validators without knowing how they handle funds when a validator is removed from
+  the active set.
+</Warning>
+
+## Lifecycle States
 
-- **Verification Delay**  
-  It takes 2 ETH1 blocks (on the EVM layer) from the event emission to verify the event on the Consensus Layer. If the deposit event is processed at epoch `N`, the validator is then considered in the **Deposited** state, provided the validator's balance equals (or exceeds) the minimum required for staking.
+The validator lifecycle flows through five main states:
 
-- **Minimum Requirement**  
-  A total of **250,000 BERA** is required for a validator to reach the Deposited state. (Multiple deposits can accumulate to this amount.)
+### 1. Deposited
+
+The validator's journey begins with a deposit transaction on the Execution Layer (via the Deposit Contract). Once this transaction is successful, beacon-kit nodes capture it and process it for signature verification.
+
+The initial deposit transaction establishes a connection between a validator's Consensus Layer identity and its Execution Layer identity and decides the withdrawal address for the $BERA stake.
 
-- **Signature Verification**
-  - On the first deposit, the validator's signature is fully verified (similar to ETH2).
-  - Subsequent deposits simply increase the validator's balance (no additional signature verification is done).
+- **Verification Delay**: It takes 2 ETH1 blocks from the event emission to verify the event on the Consensus Layer. If the deposit event is processed at epoch `N`, the validator is then considered in the **Deposited** state, provided the validator's balance equals (or exceeds) the minimum required for staking.
+- **Minimum Requirement**: A total of **250,000 BERA** is required for a validator to reach the Deposited state. (Multiple deposits can accumulate to this amount.)
+- **Signature Verification**: On the first deposit, the validator's signature is fully verified. Subsequent deposits simply increase the validator's balance.
 
 After remaining in the **Deposited** state for 1 epoch, the validator automatically moves to the **Eligible** state and becomes eligible for activation.
 
-## Eligible state
+### 2. Eligible
 
 Once the validator enters the **Deposited** state at epoch `N`, the system marks it as eligible for the activation queue as soon as epoch `N+1` starts. This is guaranteed because there is no cap on the activation queue size.
 
 The validator remains in this **Eligible** state for 1 epoch. Afterward, it is added to the **Active** set, provided the validator set cap (**69**) is not exceeded, or if the validator is of higher priority (i.e., higher effective balance or lower-order pubKey among equals).
 
-## Active state
+### 3. Active
 
-After spending 1 epoch in the **Eligible** state (say at `N+1`), the validator is marked **Active** at the start of epoch `N+2`.
+After spending 1 epoch in the **Eligible** state (say at `N+1`), the validator is marked **Active** at the start of epoch `N+2` and joins the Active Set (provided the 69-validator limit is not exceeded, or if the validator has a higher priority than an existing validator).
 
-A validator remains active indefinitely until it is forced out by a validator with a higher stake or voluntarily exits.
+A validator remains active indefinitely until it is forced out by a validator with a higher stake, or until it [voluntarily withdraws its stake](/nodes/guides/withdraw-stake).
 
 Once **Active**:
 
 - **CometBFT Consensus** will use the validator for block proposals, validations, and voting.
 - The higher a validator's effective balance, the higher its voting power—and thus, the more frequently it will be polled for block proposals.
 
-## Exited state
+### 4. Exited
 
 A Validator may choose to exit by [withdrawing their complete stake](/nodes/guides/withdraw-stake). Otherwise, the **only** reason for a validator to be evicted from the set (and have its funds returned) is if the validator set cap (**69**) is reached and another validator with a higher priority enters. Higher priority is determined by:
 
-1. **Larger Effective Balance**
-2. **If Equal Effective Balance**, a lower-order pubKey (alphabetically).
+1. Larger Effective Balance
+2. If Equal Effective Balance, a lower-order pubKey (alphabetically).
 
 When the validator is evicted from the validator set, it is marked **Exited**.
 
-## Withdrawn state
+### 5. Withdrawn
 
-Once the validator is marked **Exited** (say at epoch `M`), its funds are fully withdrawn at epoch **M + 256** on mainnet (**M + 32** on Bepolia). Because BeaconKit does not currently enforce a cap on validator churn, this finalizes the validator's lifecycle.
+Once the validator is marked **Exited** (say at epoch `M`), its funds are fully withdrawn at epoch **M + 256** on mainnet (**M + 32** on Bepolia). Because BeaconKit does not currently enforce a cap on validator churn, this finalizes the validator's lifecycle and returns all `$BERA` to the Withdrawal Credentials Address.
+
+<Warning>
+  Staking with a previously-used CometBFT identity — a validator that was removed from the active
+  set — will result in the funds being returned to that validator's withdrawal address at the end of
+  the current epoch. The old identity can never be re-activated.
+</Warning>
 
 ## Effective balance and hysteresis
 
@@ -103,7 +117,7 @@ For example, a validator who wants to lift effective balance from 250,000 to 260
 
 These buffers are consensus chain spec parameters. See [BRIP-0008](https://github.com/berachain/BRIPs/blob/main/meta/BRIP-0008.md) for the derivation.
 
-## Extended validator lifecycle
+## Extended Validator Lifecycle
 
 Putting it all together, the following diagram shows the complete Berachain validator lifecycle:
 
@@ -119,3 +133,16 @@ Putting it all together, the following diagram shows the complete Berachain vali
 </Frame>
 
 Note that the system processes state transitions via a queue, on a FIFO basis, with a cap on the number of transitions in each state to limit excessive churn in the validator set.
+
+## Block Rewards & Distribution
+
+Once active, validators receive block rewards for proposing blocks.
+Block rewards are in the form of `$BGT`, with a base reward of **0.4** `$BGT` per block proposed.
+
+The network distributes block rewards automatically through the Distributor contract. Validators no longer need to manually trigger this distribution.
+
+For ongoing operational guides, see the Being a Validator section:
+
+- [Increase Stake](/nodes/guides/increase-validator-stake)
+- [Withdraw Stake](/nodes/guides/withdraw-stake)
+- [Change Operator Address](/nodes/guides/change-operator-address)