diff --git a/.cursor/rules.md b/.cursor/rules.md
index 4ccee35..db435c7 100644
--- 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
-
+
+
## Required page structure
diff --git a/AGENTS.md b/AGENTS.md
index eb3eef0..059e0c9 100644
--- 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
index d7cd4b6..7192f61 100644
--- 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
index f60e6e1..ceae75e 100644
--- 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
index b0232d8..6f7ca43 100644
--- 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
}
]
-}
+}
\ No newline at end of file
diff --git a/nodes/architecture/evm-execution.mdx b/nodes/architecture/evm-execution.mdx
index 86398e7..4e3169f 100644
--- 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
index 1ad697d..cb2adbe 100644
--- 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
/>
-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.
+
+
+ Avoid staking to validators without knowing how they handle funds when a validator is removed from
+ the active set.
+
+
+## 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.
+
+
+ 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.
+
## 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
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)
diff --git a/nodes/beaconkit/api.mdx b/nodes/beaconkit/api.mdx
new file mode 100644
index 0000000..9856bc6
--- /dev/null
+++ b/nodes/beaconkit/api.mdx
@@ -0,0 +1,130 @@
+---
+title: "BeaconKit API"
+---
+
+# Beacon Kit API Reference
+
+## Enabling the API
+
+Beacon Kit exposes two distinct APIs:
+
+1. **Consensus API**: An implementation of the standard Ethereum [Beacon Node API](https://ethereum.github.io/beacon-APIs/) for consensus clients.
+2. **Beacon Kit API**: A custom AvaPI (`bkit/v1`) specific to Berachain's implementation for validators and tooling.
+
+The API server is **default off** and must be enabled by revising your installation's `app.toml` file, in the `[beacon-kit.node-api]` section. When enabled, the suggested port is `3500`.
+
+Note that this API is different from the CometBFT RPC endpoint (also known as the CometBFT Consensus API), which is typically exposed on port `26657`.
+
+## Consensus API
+
+Beacon Kit implements a large surface area of the standard Ethereum Consensus API. For detailed request and response formats, please refer directly to the [official Ethereum Beacon API Specification](https://ethereum.github.io/beacon-APIs/).
+
+### Supported Endpoints
+
+The following namespaces and endpoints are actively supported by the Beacon Kit consensus implementation:
+
+- **Beacon (`/eth/v1/beacon/*` & `/eth/v2/beacon/*`)**:
+ - `genesis`, `headers`, `blocks`, `blinded_blocks`
+ - `states/{state_id}/root`, `fork`, `validators`, `validator_balances`, `committees`, `randao`, etc.
+ - `blob_sidecars/{block_id}`
+ - `rewards/blocks`, `rewards/attestations`, `rewards/sync_committee`
+ - `pool/attestations`, `pool/attester_slashings`, `pool/proposer_slashings`, `pool/voluntary_exits`, `pool/bls_to_execution_changes`
+ - `light_client/bootstrap`, `light_client/updates`, `light_client/finality_update`, `light_client/optimistic_update`
+
+- **Config (`/eth/v1/config/*`)**:
+ - `spec`, `fork_schedule`, `deposit_contract`
+
+- **Node (`/eth/v1/node/*`)**:
+ - `identity`, `peers`, `peer_count`, `syncing`, `version`, `health`
+
+- **Validator (`/eth/v1/validator/*`, `/eth/v2/validator/*`, `/eth/v3/validator/*`)**:
+ - `duties/attester`, `duties/proposer`, `duties/sync`
+ - `blocks/{slot}`
+ - `attestation_data`, `aggregate_attestation`, `aggregate_and_proofs`
+ - `beacon_committee_subscriptions`, `sync_committee_subscriptions`, `beacon_committee_selections`
+ - `sync_committee_contribution`, `contribution_and_proofs`
+ - `prepare_beacon_proposer`, `register_validator`
+ - `liveness/{epoch}`
+
+- **Builder (`/eth/v1/builder/*`)**:
+ - `states/{state_id}/expected_withdrawals`
+
+- **Events (`/eth/v1/events`)**: Event streaming
+
+- **Debug (`/eth/v1/debug/*`, `/eth/v2/debug/*`)**:
+ - `fork_choice`, `beacon/heads`, `beacon/states/{state_id}`
+
+---
+
+## Beacon Kit API (`bkit/v1`)
+
+The custom `bkit/v1` namespace exposes specialized endpoints that are unique to the Beacon Kit architecture.
+
+### API Values
+
+1. All balance values are returned in Gwei (1 ETH = 10^9 Gwei)
+2. Validator statuses include:
+ - `active_ongoing`
+ - `active_exiting`
+ - `active_slashed`
+ - `exited_unslashed`
+ - `exited_slashed`
+ - `pending_initialized`
+ - `pending_queued`
+ - `withdrawal_possible`
+ - `withdrawal_done`
+
+3. State IDs can be:
+ - `head`
+ - `genesis`
+ - `finalized`
+ - `justified`
+ - A specific slot number
+
+### Get Block Proposer Proof
+
+Returns the block proposer's public key for the given timestamp ID, along with Merkle proofs for the public key and proposer index, verifiable against the beacon block root. Also returns the beacon block header and root.
+
+```http
+GET /bkit/v1/proof/block_proposer/{timestamp_id}
+```
+
+```bash
+curl -s http://localhost:3500/bkit/v1/proof/block_proposer/{timestamp_id}
+```
+
+### Get Validator Pubkey Proof
+
+Returns a validator's public key for the given timestamp ID and validator index, along with a Merkle proof verifiable against the beacon block root. Also returns the beacon block header and root.
+
+```http
+GET /bkit/v1/proof/validator_pubkey/{timestamp_id}/{validator_index}
+```
+
+```bash
+curl -s http://localhost:3500/bkit/v1/proof/validator_pubkey/{timestamp_id}/{validator_index}
+```
+
+### Get Validator Credentials Proof
+
+Returns a validator's withdrawal credentials for the given timestamp ID and validator index, along with a Merkle proof verifiable against the beacon block root. Also returns the beacon block header and root.
+
+```http
+GET /bkit/v1/proof/validator_credentials/{timestamp_id}/{validator_index}
+```
+
+```bash
+curl -s http://localhost:3500/bkit/v1/proof/validator_credentials/{timestamp_id}/{validator_index}
+```
+
+### Get Validator Balance Proof
+
+Returns a validator's balance for the given timestamp ID and validator index, along with a Merkle proof and balance leaf verifiable against the beacon block root. Also returns the beacon block header and root.
+
+```http
+GET /bkit/v1/proof/validator_balance/{timestamp_id}/{validator_index}
+```
+
+```bash
+curl -s http://localhost:3500/bkit/v1/proof/validator_balance/{timestamp_id}/{validator_index}
+```
diff --git a/nodes/beaconkit/cli.mdx b/nodes/beaconkit/cli.mdx
new file mode 100644
index 0000000..c3b08c5
--- /dev/null
+++ b/nodes/beaconkit/cli.mdx
@@ -0,0 +1,267 @@
+---
+title: "BeaconKit CLI"
+---
+
+# Berachain Node (`beacond`) Reference
+
+`beacond`, is an EVM consensus client implementation used as a basic beacon node for Berachain. See [BeaconKit Consensus Layer](/nodes/beaconkit-consensus) for more details.
+
+## Global Flags
+
+These flags apply to all commands:
+
+| Flag | Description |
+| --------------- | ----------------------------------------------------- |
+| `--home string` | Directory for config and data (default: `~/.beacond`) |
+
+## Basic Commands
+
+### `init`
+
+Initialize validator and node configuration files.
+
+```bash
+beacond init [flags]
+```
+
+#### Flags
+
+| Flag | Description |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `--chain-id string` | Genesis file chain-id (randomly created if blank) |
+| `--beacon-kit.chain-spec` | Which chain to generate configurations for. This value is also placed in the generated app.toml. `mainnet` or `testnet` or `file` |
+| `--beacon-kit.chain-spec-file` | If `chain-spec=file`, which file to use. Should be toml format. This value is also placed in the generated app.toml. |
+| `--default-denom string` | Genesis file default denomination (default: "stake") |
+| `--initial-height int` | Initial block height at genesis (default: 1) |
+| `-o, --overwrite` | Overwrite the genesis.json file |
+| `--recover` | Recover existing key using seed phrase instead of creating new one |
+
+### `start`
+
+Run the node application with CometBFT in process.
+
+```bash
+beacond start [flags]
+```
+
+#### Flags
+
+The `start` command has numerous configuration flags for networking, consensus, pruning, and more. Key flags include:
+
+| Flag | Description |
+| ------------------------------- | ------------------------------------------------------- |
+| `--abci string` | ABCI transport (socket or grpc) (default: "socket") |
+| `--address string` | Listen address (default: "tcp://127.0.0.1:26658") |
+| `--db_backend string` | Database backend (default: "pebbledb") |
+| `--moniker string` | Node name |
+| `--p2p.laddr string` | Node listen address (default: "tcp://0.0.0.0:26656") |
+| `--p2p.persistent_peers string` | Comma-delimited ID@host:port persistent peers |
+| `--p2p.seeds string` | Comma-delimited ID@host:port seed nodes |
+| `--pruning string` | Pruning strategy (default\|nothing\|everything\|custom) |
+| `--rpc.laddr string` | RPC listen address (default: "tcp://127.0.0.1:26657") |
+
+Additional flags are available for detailed engine configuration, beacon-kit settings, and consensus parameters.
+
+### `status`
+
+Query remote node for status information.
+
+```bash
+beacond status [flags]
+```
+
+#### Flags
+
+| Flag | Description |
+| --------------------- | ----------------------------------------------------- |
+| `-n, --node string` | Node to connect to (default: "tcp://localhost:26657") |
+| `-o, --output string` | Output format (text\|json) (default: "json") |
+
+### `version`
+
+Print the application binary version information.
+
+```bash
+beacond version [flags]
+```
+
+#### Flags
+
+| Flag | Description |
+| --------------------- | -------------------------------------------- |
+| `--long` | Print long version information |
+| `-o, --output string` | Output format (text\|json) (default: "text") |
+
+### `rollback`
+
+Recover from an incorrect application state transition by rolling back one height.
+
+```bash
+beacond rollback [flags]
+```
+
+#### Flags
+
+| Flag | Description |
+| -------- | ---------------------------------- |
+| `--hard` | Remove last block as well as state |
+
+## CometBFT Commands (`comet`)
+
+Commands for managing the CometBFT consensus engine.
+
+### `comet bootstrap-state`
+
+Bootstrap CometBFT state at an arbitrary block height using a light client.
+
+```bash
+beacond comet bootstrap-state [flags]
+```
+
+#### Flags
+
+| Flag | Description |
+| -------------- | ------------------------------------------------------------------------------------------ |
+| `--height int` | Block height to bootstrap state at (uses latest block height in app state if not provided) |
+
+### `comet reset-state`
+
+Remove all data and WAL (Write-Ahead Log).
+
+```bash
+beacond comet reset-state [flags]
+```
+
+### `comet show-address`
+
+Show this node's CometBFT validator consensus address.
+
+```bash
+beacond comet show-address [flags]
+```
+
+### `comet show-node-id`
+
+Show this node's ID.
+
+```bash
+beacond comet show-node-id [flags]
+```
+
+### `comet show-validator`
+
+Show this node's CometBFT validator info.
+
+```bash
+beacond comet show-validator [flags]
+```
+
+### `comet unsafe-reset-all`
+
+Remove all data and WAL, reset this node's validator to genesis state (unsafe).
+
+```bash
+beacond comet unsafe-reset-all [flags]
+```
+
+#### Flags
+
+| Flag | Description |
+| ----------------------- | --------------------------------------------------------------------- |
+| `--keep-addr-book` | Keep the address book intact |
+| `-k, --key-type string` | Private key type (ed25519\|secp256k1\|bls12_381) (default: "ed25519") |
+
+### `comet version`
+
+Print protocols' and libraries' version numbers this app was compiled against.
+
+```bash
+beacond comet version [flags]
+```
+
+## Deposit Commands (`deposit`)
+
+Commands for managing validator deposits.
+
+### `deposit create-validator`
+
+Create a validator deposit with necessary credentials.
+
+```bash
+beacond deposit create-validator [withdrawal-address] [amount] ?[beacond/genesis.json] [flags]
+```
+
+#### Flags
+
+| Flag | Description |
+| ------------------------------------- | --------------------------------------------------------------------------------------- |
+| `-g, --genesis-validator-root string` | Use provided genesis validator root (if not set, beacond genesis file must be provided) |
+| `-o, --override-node-key` | Override the node private key |
+
+### `deposit validate`
+
+Validate a deposit message for creating a new validator.
+
+```bash
+beacond deposit validate [pubkey] [withdrawal-credentials] [amount] [signature] ?[beacond/genesis.json] [flags]
+```
+
+#### Flags
+
+| Flag | Description |
+| ------------------------------------- | --------------------------------------------------------------------------------------- |
+| `-g, --genesis-validator-root string` | Use provided genesis validator root (if not set, beacond genesis file must be provided) |
+
+### `deposit validator-keys`
+
+Output validator public key in various formats.
+
+```bash
+beacond deposit validator-keys [flags]
+```
+
+Displays the validator key as Comet address, Comet pubkey, and Eth/Beacon pubkey formats.
+
+## Genesis Commands (`genesis`)
+
+Commands for genesis file management. These are largely only of interest to those of us maintaining Berachain, so we have stuck to the generally useful ones.
+
+### `genesis validator-root`
+
+Get and return the genesis validator root hash.
+
+```bash
+beacond genesis validator-root [beacond/genesis.json] [flags]
+```
+
+## JWT Commands (`jwt`)
+
+Commands for managing JWT authentication.
+
+### `jwt generate`
+
+Generate a new JWT authentication secret.
+
+```bash
+beacond jwt generate [flags]
+```
+
+#### Flags
+
+| Flag | Description |
+| -------------------------- | ------------------------------------------------------------------- |
+| `-o, --output-path string` | Optional output file path for the JWT secret (default: "./jwt.hex") |
+
+### `jwt validate`
+
+Validate a JWT secret by checking if it's formatted properly.
+
+```bash
+beacond jwt validate [flags]
+```
+
+#### Flags
+
+| Flag | Description |
+| ------------------------- | ------------------------------------------------------------------ |
+| `-i, --input-path string` | Optional input file path for the JWT secret (default: "./jwt.hex") |
diff --git a/nodes/beaconkit/configuration.mdx b/nodes/beaconkit/configuration.mdx
new file mode 100644
index 0000000..a873931
--- /dev/null
+++ b/nodes/beaconkit/configuration.mdx
@@ -0,0 +1,334 @@
+---
+title: "BeaconKit Configuration"
+---
+
+# Berachain Node Configuration Reference
+
+## app.toml
+
+### Base Configuration (Top-level Options)
+
+These options appear at the top of the file without a section header.
+
+| Option | Description | Default Value |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------- | -------------- |
+| `pruning` | Pruning strategy for state storage. Only nodes that calculate block reward claim transactions need `default`. | `"everything"` |
+| `pruning-keep-recent` | Number of recent states to keep when using `custom` pruning | `"0"` |
+| `pruning-interval` | Interval for state pruning when using `custom` pruning | `"0"` |
+| `halt-height` | Block height at which to gracefully halt the node | `0` |
+| `halt-time` | Unix timestamp at which to gracefully halt the node | `0` |
+| `min-retain-blocks` | Minimum block height offset from current block for pruning CometBFT blocks | `0` |
+| `inter-block-cache` | Enables inter-block caching | `true` |
+| `iavl-cache-size` | Size of the IAVL tree cache (in number of nodes) | `2500` |
+| `iavl-disable-fastnode` | Disables the fast node feature of IAVL | `true` |
+
+#### Pruning Options
+
+- `default`: The last 362880 states are kept, pruning at 10 block intervals
+- `nothing`: All historic states will be saved, nothing will be deleted (archiving node)
+- `everything`: Only 2 latest states will be kept; pruning at 10 block intervals
+- `custom`: Manual specification through `pruning-keep-recent` and `pruning-interval`
+
+### Telemetry Configuration `[telemetry]`
+
+| Option | Description | Default Value |
+| --------------------------- | ----------------------------------------------------- | ------------- |
+| `service-name` | Prefix for keys to separate services | `""` |
+| `enabled` | Enables application telemetry functionality | `true` |
+| `enable-hostname` | Prefixes gauge values with hostname | `false` |
+| `enable-hostname-label` | Adds hostname to labels | `false` |
+| `enable-service-label` | Adds service to labels | `false` |
+| `prometheus-retention-time` | When positive, enables a Prometheus metrics sink | `0` |
+| `global-labels` | Global set of name/value label tuples for all metrics | `[]` |
+| `metrics-sink` | Type of metrics sink to use | `""` |
+| `statsd-addr` | Address of statsd server for metrics | `""` |
+| `datadog-hostname` | Hostname for Datadog metrics | `""` |
+
+### BeaconKit Configuration
+
+BeaconKit settings are organized into several subsections.
+
+#### Core settings `[beacon-kit]`.
+
+| Option | Description | Default Value |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `chain-spec` | The type of chain specification to use. This can be `mainnet`, `testnet`, and `file` | `mainnet` |
+| `chain-spec-file` | When `chain-spec` is `file`, this is the file to use. Evaluated relative to the beacond configuration directory. The [mainnet](https://github.com/berachain/beacon-kit/blob/main/testing/networks/80094/spec.toml) and [testnet](https://github.com/berachain/beacon-kit/blob/main/testing/networks/80069/spec.toml) configuration files are available for reference. | "" |
+| `shutdown-timeout` | This is the maximum time to wait for the node to gracefully shutdown before forcing an exit. | "5m0s" |
+
+#### Engine `[beacon-kit.engine]`
+
+| Option | Description | Default Value |
+| ---------------------------- | ------------------------------------------------------- | ------------------------- |
+| `rpc-dial-url` | HTTP URL of the execution client JSON-RPC endpoint | `"http://localhost:8551"` |
+| `rpc-retries` | Number of retries before shutting down consensus client | `"3"` |
+| `rpc-timeout` | RPC timeout for execution client requests | `"900ms"` |
+| `rpc-startup-check-interval` | Interval for the startup check | `"3s"` |
+| `rpc-jwt-refresh-interval` | Interval for the JWT refresh | `"30s"` |
+| `jwt-secret-path` | Path to the execution client JWT-secret | `"./jwt.hex"` |
+
+#### Logger `[beacon-kit.logger]`
+
+| Option | Description | Default Value |
+| ------------- | -------------------------------- | ------------- |
+| `time-format` | Format of the time in the logger | `"RFC3339"` |
+| `log-level` | Level of logging (verbosity) | `"info"` |
+| `style` | Style of the logger | `"pretty"` |
+
+#### KZG `[beacon-kit.kzg]`
+
+| Option | Description | Default Value |
+| -------------------- | ------------------------------ | ------------------------------------------ |
+| `trusted-setup-path` | Path to the trusted setup file | `"./testing/files/kzg-trusted-setup.json"` |
+| `implementation` | KZG implementation to use | `"crate-crypto/go-kzg-4844"` |
+
+**Implementation Options:**
+
+- `crate-crypto/go-kzg-4844`
+- `ethereum/c-kzg-4844`
+
+#### Payload Builder `[beacon-kit.payload-builder]`
+
+| Option | Description | Default Value |
+| ------------------------- | -------------------------------------------------- | ---------------------------------------------- |
+| `enabled` | Enables the local payload builder (for validators) | `true` |
+| `suggested-fee-recipient` | Address to receive transaction fees from blocks | `"0x0000000000000000000000000000000000000000"` |
+| `payload-timeout` | Timeout for local build payload | `"850ms"` |
+
+#### Validator `[beacon-kit.validator]`
+
+| Option | Description | Default Value |
+| ---------------------------------- | -------------------------------------------------------- | ------------- |
+| `graffiti` | String included in the graffiti field of beacon blocks | `""` |
+| `enable-optimistic-payload-builds` | Enables building the next block's payload optimistically | `"true"` |
+
+#### Block Store Service `[beacon-kit.block-store-service]`
+
+| Option | Description | Default Value |
+| --------------------- | ------------------------------------ | ------------- |
+| `enabled` | Enables the block store service | `"false"` |
+| `availability-window` | Number of slots to keep in the store | `"8192"` |
+
+#### Node API `[beacon-kit.node-api]`
+
+| Option | Description | Default Value |
+| --------- | ------------------------------- | ------------------ |
+| `enabled` | Enables the node API | `"false"` |
+| `address` | Address to bind the node API to | `"127.0.0.1:3500"` |
+| `logging` | Enables node API logging | `"false"` |
+
+## config.toml
+
+## Berachain Node CometBFT Configuration Reference
+
+This document describes the configuration options available in the `config.toml` file for the CometBFT consensus engine used by Berachain nodes.
+
+Current CometBFT version: `1.0.1`
+
+### Main Base Config Options (Top-level)
+
+| Option | Description | Default Value |
+| --------------------------- | -------------------------------------------------------------------- | ---------------------------------- |
+| `proxy_app` | TCP or UNIX socket address of the ABCI application | `"tcp://127.0.0.1:26658"` |
+| `moniker` | Custom human readable name for this node | `"poop"` |
+| `db_backend` | Database backend type | `"pebbledb"` |
+| `db_dir` | Database directory | `"data"` |
+| `log_level` | Output level for logging | `"info"` |
+| `log_format` | Output format: 'plain' (colored text) or 'json' | `"plain"` |
+| `genesis_file` | Path to the JSON file containing the initial validator set | `"config/genesis.json"` |
+| `priv_validator_key_file` | Path to the JSON file containing the private validator key | `"config/priv_validator_key.json"` |
+| `priv_validator_state_file` | Path to the JSON file containing the last sign state | `"data/priv_validator_state.json"` |
+| `priv_validator_laddr` | TCP or UNIX socket address for external PrivValidator process | `""` |
+| `node_key_file` | Path to the JSON file containing the node authentication private key | `"config/node_key.json"` |
+| `abci` | Mechanism to connect to the ABCI application: socket or grpc | `"socket"` |
+| `filter_peers` | If true, query the ABCI app on connecting to new peers | `false` |
+
+#### Database Backend Options
+
+- `badgerdb`: Uses github.com/dgraph-io/badger (stable, pure go)
+- `goleveldb`: Uses github.com/syndtr/goleveldb (UNMAINTAINED, stable, pure go)
+- `pebbledb`: Uses github.com/cockroachdb/pebble (stable, pure go)
+- `rocksdb`: Uses github.com/linxGnu/grocksdb (requires gcc)
+- `cleveldb`: Uses levigo wrapper (DEPRECATED, requires gcc)
+- `boltdb`: Uses etcd's fork of bolt (DEPRECATED, stable)
+
+### RPC Server Configuration `[rpc]`
+
+| Option | Description | Default Value |
+| ------------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------- |
+| `laddr` | TCP or UNIX socket address for the RPC server | `"tcp://127.0.0.1:26657"` |
+| `cors_allowed_origins` | List of origins for cross-domain requests | `[]` |
+| `cors_allowed_methods` | List of allowed methods for cross-domain requests | `["HEAD", "GET", "POST"]` |
+| `cors_allowed_headers` | List of allowed headers for cross-domain requests | `["Origin", "Accept", "Content-Type", "X-Requested-With", "X-Server-Time"]` |
+| `unsafe` | Enable unsafe RPC commands | `false` |
+| `max_open_connections` | Maximum number of simultaneous connections | `900` |
+| `max_subscription_clients` | Maximum number of unique clients that can /subscribe | `100` |
+| `max_subscriptions_per_client` | Maximum subscriptions per client | `5` |
+| `experimental_subscription_buffer_size` | Maximum events to buffer per subscription | `200` |
+| `experimental_websocket_write_buffer_size` | Maximum RPC responses buffered per WebSocket client | `200` |
+| `experimental_close_on_slow_client` | Close WebSocket if client can't read fast enough | `false` |
+| `timeout_broadcast_tx_commit` | How long to wait for tx commit during broadcast | `"10s"` |
+| `max_request_batch_size` | Maximum number of requests in a batch | `10` |
+| `max_body_bytes` | Maximum size of request body | `1000000` |
+| `max_header_bytes` | Maximum size of request header | `1048576` |
+| `tls_cert_file` | Path to TLS certificate file | `""` |
+| `tls_key_file` | Path to TLS key file | `""` |
+| `pprof_laddr` | pprof listen address | `""` |
+
+### gRPC Server Configuration `[grpc]`
+
+| Option | Description | Default Value |
+| ------- | ---------------------------------------------- | ------------- |
+| `laddr` | TCP or UNIX socket address for the gRPC server | `""` |
+
+#### gRPC Service Configurations
+
+| Service | Configuration | Enabled |
+| ------------------------------ | ------------------------------ | ------- |
+| `[grpc.version_service]` | The gRPC version service | `true` |
+| `[grpc.block_service]` | The gRPC block service | `true` |
+| `[grpc.block_results_service]` | The gRPC block results service | `true` |
+
+#### Privileged gRPC Endpoints `[grpc.privileged]`
+
+| Option | Description | Default Value |
+| ------- | --------------------------------------- | ------------- |
+| `laddr` | Host/port for privileged gRPC endpoints | `""` |
+
+##### Pruning Service `[grpc.privileged.pruning_service]`
+
+| Option | Description | Default Value |
+| --------- | ----------------------------------------------- | ------------- |
+| `enabled` | Controls access to pruning service via gRPC API | `false` |
+
+### P2P Configuration `[p2p]`
+
+| Option | Description | Default Value |
+| ---------------------------------- | -------------------------------------------------- | ------------------------ |
+| `laddr` | Address to listen for incoming connections | `"tcp://0.0.0.0:26656"` |
+| `external_address` | Address to advertise to peers | `""` |
+| `seeds` | Comma separated list of seed nodes | `""` |
+| `persistent_peers` | Comma separated list of persistent peer nodes | `""` |
+| `addr_book_file` | Path to address book | `"config/addrbook.json"` |
+| `addr_book_strict` | Set true for strict address routability rules | `true` |
+| `max_num_inbound_peers` | Maximum number of inbound peers | `120` |
+| `max_num_outbound_peers` | Maximum number of outbound peers | `40` |
+| `unconditional_peer_ids` | List of node IDs to connect to ignoring limits | `""` |
+| `persistent_peers_max_dial_period` | Maximum pause when redialing persistent peers | `"0s"` |
+| `flush_throttle_timeout` | Time to wait before flushing messages | `"10ms"` |
+| `max_packet_msg_payload_size` | Maximum size of a message packet payload | `1024` |
+| `send_rate` | Rate at which packets can be sent | `5120000` |
+| `recv_rate` | Rate at which packets can be received | `5120000` |
+| `pex` | Set true to enable the peer-exchange reactor | `true` |
+| `seed_mode` | Seed mode for network crawling | `false` |
+| `private_peer_ids` | List of peer IDs to keep private | `""` |
+| `allow_duplicate_ip` | Toggle to disable guard against peers from same IP | `false` |
+| `handshake_timeout` | Peer connection handshake timeout | `"20s"` |
+| `dial_timeout` | Peer connection dial timeout | `"3s"` |
+
+### Mempool Configuration `[mempool]`
+
+| Option | Description | Default Value |
+| ------------------------------------------------------------- | ----------------------------------------------- | ------------- |
+| `type` | Type of mempool for this node | `"nop"` |
+| `recheck` | Whether to recheck transactions after a block | `false` |
+| `recheck_timeout` | Timeout for rechecking process | `"0s"` |
+| `broadcast` | Whether to relay transactions to other peers | `false` |
+| `wal_dir` | Location of the Write Ahead Log for the mempool | `""` |
+| `size` | Maximum number of transactions in the mempool | `0` |
+| `max_tx_bytes` | Maximum size of a single transaction | `0` |
+| `max_txs_bytes` | Maximum size of all transactions in mempool | `0` |
+| `cache_size` | Size of the transaction cache | `0` |
+| `keep-invalid-txs-in-cache` | Whether to keep invalid transactions in cache | `false` |
+| `experimental_max_gossip_connections_to_persistent_peers` | Limit gossip to number of persistent peers | `0` |
+| `experimental_max_gossip_connections_to_non_persistent_peers` | Limit gossip to number of non-persistent peers | `0` |
+
+#### Mempool Types
+
+- `"flood"`: Concurrent linked list mempool with flooding gossip protocol (default)
+- `"nop"`: No-operation mempool where the ABCI app handles transactions
+
+### State Sync Configuration `[statesync]`
+
+| Option | Description | Default Value |
+| ----------------------- | ----------------------------------------------------------- | ------------- |
+| `enable` | Enable state sync for rapid node bootstrapping | `false` |
+| `rpc_servers` | RPC servers for light client verification | `""` |
+| `trust_height` | Trusted block height for state sync | `0` |
+| `trust_hash` | Trusted block hash for state sync | `""` |
+| `trust_period` | Trust period for validators (usually 2/3 of unbonding time) | `"168h0m0s"` |
+| `discovery_time` | Time for discovering snapshots | `"15s"` |
+| `temp_dir` | Temporary directory for state sync chunks | `""` |
+| `chunk_request_timeout` | Timeout before re-requesting a chunk | `"10s"` |
+| `chunk_fetchers` | Number of concurrent chunk fetchers | `"4"` |
+
+### Block Sync Configuration `[blocksync]`
+
+| Option | Description | Default Value |
+| --------- | ------------------------- | ------------- |
+| `version` | Block Sync version to use | `"v0"` |
+
+### Consensus Configuration `[consensus]`
+
+| Option | Description | Default Value |
+| -------------------------------------- | ------------------------------------------------ | ------------------- |
+| `wal_file` | Path to the consensus WAL file | `"data/cs.wal/wal"` |
+| `timeout_propose` | How long to wait for a proposal block | `"2s"` |
+| `timeout_propose_delta` | How much timeout_propose increases per round | `"500ms"` |
+| `timeout_prevote` | How long to wait after receiving +2/3 prevotes | `"2s"` |
+| `timeout_prevote_delta` | How much timeout_prevote increases per round | `"500ms"` |
+| `timeout_precommit` | How long to wait after receiving +2/3 precommits | `"2s"` |
+| `timeout_precommit_delta` | How much timeout_precommit increases per round | `"500ms"` |
+| `timeout_commit` | How long to wait after committing a block | `"500ms"` |
+| `skip_timeout_commit` | Deprecated: set timeout_commit to 0 instead | `false` |
+| `double_sign_check_height` | How many blocks to check for double signing | `0` |
+| `create_empty_blocks` | Whether to create empty blocks | `true` |
+| `create_empty_blocks_interval` | Interval between empty blocks | `"0s"` |
+| `peer_gossip_sleep_duration` | Sleep duration for peer gossip | `"100ms"` |
+| `peer_gossip_intraloop_sleep_duration` | Intraloop sleep duration for peer gossip | `"0s"` |
+| `peer_query_maj23_sleep_duration` | Sleep duration for peer query | `"2s"` |
+
+### Storage Configuration `[storage]`
+
+| Option | Description | Default Value |
+| ---------------------------- | ----------------------------------------------------- | ------------- |
+| `discard_abci_responses` | Whether to discard ABCI responses from state store | `true` |
+| `experimental_db_key_layout` | Representation of keys in the database | `"v1"` |
+| `compact` | Force compaction for databases that support it | `false` |
+| `compaction_interval` | Number of blocks to wait before triggering compaction | `"1000"` |
+
+#### Pruning Configuration `[storage.pruning]`
+
+| Option | Description | Default Value |
+| ---------- | ------------------------------------------------ | ------------- |
+| `interval` | Time period between automated pruning operations | `"10s"` |
+
+##### Data Companion Configuration `[storage.pruning.data_companion]`
+
+| Option | Description | Default Value |
+| ------------------------------------- | ------------------------------------------------ | ------------- |
+| `enabled` | Whether pruning respects data companion settings | `false` |
+| `initial_block_retain_height` | Initial value for block retain height | `0` |
+| `initial_block_results_retain_height` | Initial value for block results retain height | `0` |
+
+### Transaction Indexer Configuration `[tx_index]`
+
+| Option | Description | Default Value |
+| ----------- | ------------------------------------ | ------------- |
+| `indexer` | What indexer to use for transactions | `"null"` |
+| `psql-conn` | PostgreSQL connection string | `""` |
+
+#### Indexer Options
+
+- `"null"`: No indexer
+- `"kv"`: Simple key-value storage indexer (default)
+- `"psql"`: PostgreSQL-backed indexer
+
+### Instrumentation Configuration `[instrumentation]`
+
+| Option | Description | Default Value |
+| ------------------------ | -------------------------------------------- | ------------- |
+| `prometheus` | Enable Prometheus metrics | `true` |
+| `prometheus_listen_addr` | Address for Prometheus collector connections | `":26660"` |
+| `max_open_connections` | Maximum number of simultaneous connections | `800` |
+| `namespace` | Instrumentation namespace | `"cometbft"` |
diff --git a/nodes/guides/become-a-validator.mdx b/nodes/guides/become-a-validator.mdx
index 6a6abe7..32502bf 100644
--- a/nodes/guides/become-a-validator.mdx
+++ b/nodes/guides/become-a-validator.mdx
@@ -1,5 +1,5 @@
---
-title: "Become a Validator"
+title: "Becoming a Validator"
description: "Register and activate a validator: beacond setup, deposit transaction, BeaconDeposit contract, operator and withdrawal address."
---
diff --git a/nodes/guides/increase-validator-stake.mdx b/nodes/guides/increase-validator-stake.mdx
index 1ccb9c6..63e1888 100644
--- a/nodes/guides/increase-validator-stake.mdx
+++ b/nodes/guides/increase-validator-stake.mdx
@@ -1,5 +1,5 @@
---
-title: "Increase Validator Stake"
+title: "Increase Stake"
description: "Add BERA to an existing validator via the BeaconDeposit contract to improve position in the active set."
---
diff --git a/nodes/operations/bera-geth-to-reth.mdx b/nodes/operations/bera-geth-to-reth.mdx
index 02f717d..03d66bd 100644
--- a/nodes/operations/bera-geth-to-reth.mdx
+++ b/nodes/operations/bera-geth-to-reth.mdx
@@ -1,5 +1,5 @@
---
-title: "Migrate from Bera-Geth to Bera-Reth"
+title: "Migrate Bera-Geth -> Bera-Reth"
description: "Replace your execution client, match your old configuration, install a snapshot."
---
diff --git a/nodes/overview/node-architecture.mdx b/nodes/overview/node-architecture.mdx
index aabcfa6..3f6455c 100644
--- a/nodes/overview/node-architecture.mdx
+++ b/nodes/overview/node-architecture.mdx
@@ -1,11 +1,11 @@
---
title: "Node Architecture"
-description: "Validator and RPC node architecture: consensus (BeaconKit) and execution clients, active set, staking, and block rewards."
+description: "Validator and RPC node architecture: consensus and execution separation, Engine API, and dual P2P networks."
---
Berachain's network relies on validator nodes and RPC nodes. Each can be configured as a full node or archive node.
-Each of these types of nodes is a pair of both an [execution client](/general/help/glossary#execution-client) and a [consensus client](/general/help/glossary#consensus-client). Berachain is a Layer 1 EVM Identical chain, which means that for the execution layer, it supports any EVM execution client paired with a consensus client and framework built by Berachain called [BeaconKit](/nodes/architecture/beaconkit-consensus).
+Berachain follows a decoupled node architecture standard in modern Ethereum-equivalent networks. Every node consists of two separate software clients running in tandem: an **execution client** and a **consensus client**. Berachain supports any EVM execution client paired with [BeaconKit](/nodes/architecture/beaconkit-consensus), a consensus framework built by Berachain.
![]()
-## RPC vs validator nodes
+## RPC vs Validator Nodes
-The main difference between an RPC node and a validator node is that a validator can propose blocks and receive block rewards.
+Architecturally, RPC nodes and validator nodes are nearly identical. Both maintain a complete copy of the blockchain state and participate in peer-to-peer gossip.
-An RPC node can become a validator node by joining the [Active Set](#active-set) through interaction with the [BeaconDeposit](/build/getting-started/deployed-contracts) contract by meeting the `$BERA` [stake requirements](#validator-stake-requirements).
+The only difference is that a **validator node** has been funded with a deposit and holds a private validator key. This key allows the consensus client to sign blocks and attestations, participate in consensus, and receive block rewards. To learn about the economics of becoming a validator, see the [Validator Lifecycle](/nodes/architecture/validator-lifecycle) and the [Be A Validator](/nodes/guides/become-a-validator) guides.
-## Active set
+## Client Separation
-The active set is the set of validators that are currently participating in the consensus layer of the network.
+The separation of concerns between the two clients is strictly defined:
-The current limit of validators in the active set is **69**.
+- **Execution Client (e.g., Bera-Reth, Bera-Geth):** Responsible for transaction execution, managing the Ethereum Virtual Machine (EVM) state, maintaining the state trie, and serving user-facing JSON-RPC requests (like `eth_call` or `eth_sendRawTransaction`).
+- **Consensus Client (BeaconKit):** Responsible for the Proof-of-Stake consensus mechanism, determining the chain's head, managing the validator set, and proposing new blocks. It does _not_ execute transactions or hold EVM state.
-Validators can choose to leave the active set voluntarily — [learn how](/nodes/guides/withdraw-stake) — or be ejected from the set if a validator with more stake joins.
+Because these are separate databases, "archival" status usually refers to the execution client retaining historical EVM state, whereas the consensus client manages its own independent pruning settings.
-## Validator stake requirements
+## The Engine API and JWT
-The minimum stake requirement depends on whether the active set is completely full.
+The execution and consensus clients must communicate continuously to keep the node synced. They do this over a local HTTP interface called the **Engine API**.
-If the active set is not full, the minimum stake requirement is **250,000** `$BERA`.
+Because the Engine API allows the consensus client to command the execution client to build and execute blocks, this API must be highly secured. Communication is authenticated using a **JSON Web Token (JWT) secret**. Both clients must be configured to read the exact same `jwt.hex` file on disk to authorize communication.
-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.
+## Dual P2P Networks
-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.
+Because the node is split into two clients, it participates in two entirely separate Peer-to-Peer (P2P) networks simultaneously:
-## Direct staking
+1. **Execution P2P (devp2p):** The execution client connects to other execution clients to gossip pending user transactions (the mempool).
+2. **Consensus P2P (CometBFT):** The consensus client connects to other consensus clients to gossip proposed blocks, validator attestations, and consensus votes.
-Berachain follows Proof-of-Stake (PoS) direct staking, which allows `$BERA` holders to directly stake their `$BERA` to a validator. However, note that if funds are withdrawn from a validator, currently all funds are returned to a single address: the validator's Withdrawal Credentials Address.
-
-This means that validators will have to communicate how they handle funds when a validator is removed from the active set.
-
-
- Avoid staking to validators without knowing how they handle funds when a validator is removed from
- the active set.
-
-
-## Staking pools
-
-Validators can also operate **staking pools**, which enable liquid staking services for their communities. Staking pools use smart contracts to manage deposits and withdrawals, allowing stakers to receive liquid shares (stBERA) that automatically grow in value as rewards accumulate. Staking pools provide validators with a way to build and monetize their own community of stakers while offering stakers lower barriers to entry and flexible withdrawals. For information about setting up and operating staking pools, see the [Staking Pools documentation](/nodes/staking-pools/overview).
-
-## Removed from active set
-
-If a validator is removed from the active set, all `$BERA` staked to that validator will be returned to the validator's Withdrawal Credentials Address, which is set when the validator makes their first deposit.
-
-A validator can decide to become a validator again but will need to generate new CometBFT validator keys and start the deposit process again as if they were a new validator.
-
-
- 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 validator can never be re-activated.
-
-
-## Voluntary withdrawals
-
-A Validator can [withdraw all or part of their stake](/nodes/guides/withdraw-stake).
-
-## Validator block rewards and distribution
-
-Block rewards are in the form of `$BGT`, with a base reward of **0.5** `$BGT` per block proposed.
-
-The network does not distribute rewards automatically. You must distribute block rewards through the [Distributor](/build/getting-started/deployed-contracts) contract. Distribution must occur before **8,191** seconds have passed, or validators risk losing those rewards.
+For firewall and networking configurations, operators must ensure both P2P ports are open and publicly dialable. For more details on securing and optimizing these networks, see the [Production Checklist](/nodes/operations/production-checklist).