docs: restructure staking modules and document 0x02 CSM

[eenti]

Please, go through these steps before you request a review:

📝 Describe your changes

1. Merged CSM and CMv2 modules information under /staking-modules, with redirects to avoid broken links.
2. Updated the CSM guide on /run-on-lido with 0x02 CSM information and other fixes.
3. Added a guide for NOs in CMv2 to interact with the module directly from the contracts.

🔎 Attach a source of truth or evidence that allows reviewers to confirm the changes independently

N/A

[Copilot]

Pull request overview

Consolidates CSM and CMv2 reference documentation, adds 0x02 CSM operational guidance, and documents direct CMv2 contract interaction.

Changes:

• Unifies staking-module concepts, contracts, navigation, and redirects.
• Updates CSM guides for 0x01/0x02 behavior.
• Adds a CMv2 direct on-chain operations guide.

Reviewed changes

Copilot reviewed 76 out of 85 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
sidebars.js	Reorganizes staking-module navigation.
run-on-lido/csm/useful-tools/extra-resources.md	Updates documentation link.
run-on-lido/csm/updates-and-maintenance/client-updates.md	Fixes code fencing.
run-on-lido/csm/troubleshooting/unbonded-validators.md	Updates links and debt guidance.
run-on-lido/csm/troubleshooting/mev-stealing.md	Updates penalty details and links.
run-on-lido/csm/troubleshooting/mev-install.md	Updates relays, images, and references.
run-on-lido/csm/penalties.md	Revises penalty parameters and links.
run-on-lido/csm/node-setup/intermediate/ethpillar.md	Notes 0x02 limitations.
run-on-lido/csm/node-setup/index.md	Adds DVT setup navigation.
run-on-lido/csm/node-setup/DVT-setup/ssv.md	Adds IDVTC guidance and fixes numbering.
run-on-lido/csm/node-setup/DVT-setup/obol.md	Adds IDVTC and exit guidance.
run-on-lido/csm/node-setup/beginner/dappnode.md	Revises operator-management steps.
run-on-lido/csm/node-setup/advanced/systemd/method-2-configure-csm-fee-recipient-on-separate-validator-client.md	Corrects destructive commands.
run-on-lido/csm/node-setup/advanced/sedge.md	Notes 0x02 limitations.
run-on-lido/csm/node-setup/advanced/eth-docker.md	Documents credential selection.
run-on-lido/csm/lido-csm-widget/upload-remove-view-validator-keys.md	Documents queues, 0x02, and statuses.
run-on-lido/csm/lido-csm-widget/rewards-and-bonds.md	Reorganizes rewards and penalty guidance.
run-on-lido/csm/lido-csm-widget/operator-roles.md	Adds multi-operator role guidance.
run-on-lido/csm/lido-csm-widget/managing-0x01-and-0x02-operators.md	Adds operator-switching guide.
run-on-lido/csm/lido-csm-widget/index.md	Links the new management guide.
run-on-lido/csm/lido-csm-widget/exiting-csm-validators/index.md	Updates exit causes and consequences.
run-on-lido/csm/lido-csm-widget/exiting-csm-validators/exit-using-validator-keystores.md	Replaces Holesky with Hoodi.
run-on-lido/csm/index.md	Updates module availability and references.
run-on-lido/csm/generating-validator-keys/key-generation-for-testnet.md	Adds 0x02 key-generation instructions.
run-on-lido/csm/generating-validator-keys/key-generation-for-mainnet/tailsos-on-usb-as-air-gapped-machine.md	Adds sidebar ordering.
run-on-lido/csm/generating-validator-keys/key-generation-for-mainnet/index.md	Updates secure key-generation workflow.
run-on-lido/csm/generating-validator-keys/index.md	Distinguishes credential types.
run-on-lido/csm/context-and-background.md	Documents 0x01 and 0x02 CSM.
run-on-lido/csm/best-practices/slashing-prevention.md	Adds balance-scaled slashing guidance.
run-on-lido/csm/alerts-and-monitoring/intermediate.md	Updates monitoring links.
run-on-lido/csm/alerts-and-monitoring/expert-custom-alerts.md	Documents current contract events.
run-on-lido/csm/alerts-and-monitoring/advanced.md	Completes Prometheus instructions.
run-on-lido/cm-v2/useful-tools/working-with-cmv2-directly-onchain.md	Adds direct contract-interaction guide.
run-on-lido/cm-v2/useful-tools/index.md	Links the on-chain guide.
run-on-lido/cm-v2/useful-tools/cm-prover-tool.md	Adjusts sidebar ordering.
docusaurus.config.js	Adds redirects for consolidated routes.
docs/staking-modules/validator-exits.md	Adds shared exit mechanics.
docs/staking-modules/rewards.md	Consolidates reward documentation.
docs/staking-modules/permissions.md	Adds shared permissions reference.
docs/staking-modules/node-operators.md	Adds shared operator mechanics.
docs/staking-modules/index.md	Introduces consolidated module overview.
docs/staking-modules/further-reading.md	Expands shared references.
docs/staking-modules/csm/validator-exits.md	Removes superseded CSM page.
docs/staking-modules/csm/permissions.md	Removes superseded CSM page.
docs/staking-modules/csm/join-csm.md	Removes superseded CSM page.
docs/staking-modules/csm/intro.md	Removes superseded CSM introduction.
docs/staking-modules/csm/contracts/Verifier.md	Removes duplicate contract reference.
docs/staking-modules/csm/contracts/ValidatorStrikes.md	Removes duplicate contract reference.
docs/staking-modules/csm/contracts/MerkleGateFactory.md	Removes duplicate contract reference.
docs/staking-modules/csm/contracts/FeeOracle.md	Removes duplicate contract reference.
docs/staking-modules/csm/contracts/FeeDistributor.md	Removes duplicate contract reference.
docs/staking-modules/csm/contracts/ExitPenalties.md	Removes duplicate contract reference.
docs/staking-modules/csm/contracts/Ejector.md	Removes duplicate contract reference.
docs/staking-modules/contracts/VettedGate.md	Adds shared deployment context.
docs/staking-modules/contracts/Verifier.md	Lists per-module deployments.
docs/staking-modules/contracts/ValidatorStrikes.md	Consolidates deployments and links.
docs/staking-modules/contracts/PermissionlessGate.md	Adds deployment table.
docs/staking-modules/contracts/ParametersRegistry.md	Consolidates module references.
docs/staking-modules/contracts/MetaRegistry.md	Updates deployment and links.
docs/staking-modules/contracts/MerkleGateFactory.md	Documents both module factories.
docs/staking-modules/contracts/index.md	Adds consolidated contract index.
docs/staking-modules/contracts/FeeOracle.md	Lists both deployments.
docs/staking-modules/contracts/FeeDistributor.md	Lists both deployments.
docs/staking-modules/contracts/ExitPenalties.md	Generalizes module behavior.
docs/staking-modules/contracts/Ejector.md	Lists both deployments.
docs/staking-modules/contracts/CuratedModule.md	Updates deployment and shared links.
docs/staking-modules/contracts/CuratedGate.md	Updates deployment context.
docs/staking-modules/contracts/CSModule.md	Updates deployment and proxy links.
docs/staking-modules/contracts/Accounting.md	Consolidates deployment information.
docs/staking-modules/cm-v2/permissions.md	Removes superseded CMv2 page.
docs/staking-modules/cm-v2/intro.md	Removes superseded CMv2 introduction.
docs/holders/lido-oracle.md	Updates FeeOracle link.
docs/deployed-contracts/hoodi.md	Adds stable CMv2 anchor.
docs/contracts/ossifiable-proxy.md	Updates consolidated contract links.

Suppressed comments (1)

docusaurus.config.js:240

• The CMv2 intro redirect likewise breaks section-level URLs: old fragments such as #stake-allocation, #meta-operators-registry, and #weighted-stake-allocation now land on an overview without matching anchors, even though that content moved to Node Operators. Add compatibility handling for these deep links rather than only redirecting the page path.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 77 out of 86 changed files in this pull request and generated 1 comment.

[dgusakov]

Did a quick pass. Overall LGTM. Tho such a large PRs are almost impossible to review

[tamtamchik]

@eenti could you please resize images to some sane size before merge? Now its huge, and for example static/img/csm/exits-1.png takes > 5Mb.

[eenti]

done @tamtamchik

[tamtamchik]

LGTM!

[Copilot]

🟡 Changes recommended

Shared documentation currently contains incorrect loss-baseline, reward eligibility, penalty-scope, and CMv2 repository guidance.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

docs/staking-modules/rewards.md:45

• This shared CMv2/CSM page links “GitHub” only to the CSM rewards repository, so CMv2 operators are sent to the wrong module's tree. Link both repositories here (as the Artifacts section already does) or defer the repository links to that section.
  docs/staking-modules/rewards.md:86
• This section incorrectly makes rewards all-or-nothing at the Node Operator level even though line 49 defines eligibility per validator; eligible validators under the same operator still contribute rewards. It also generalizes forced ejection to CMv2, whose Phase 1 strike system is explicitly documented as inactive in run-on-lido/cm-v2/penalties.md:43-50. Distinguish the per-validator calculation and module-specific penalty behavior.

• Files reviewed: 78/87 changed files
• Comments generated: 2
• Review effort level: Balanced

[TheDZhon]

Thank you for putting it together 👏

---

I'd suggest to consider improving a few things before we merge it:

1. The 0x02 exit-delay charge is not flat (regression, already flagged in the inline Codex thread)

docs/run-on-lido/csm/penalties.md

Line 43 in 8e243a0

| Exit delay charge | 0.1 ETH | 0.05 ETH | 0.05 ETH | 0.1 ETH |

The cell was changed from the merge-base wording to "0.1 ETH" following the bot comment:

docs/run-on-lido/csm/penalties.md

Line 43 in 199c339

| Exit delay charge | 0.1 ETH | 0.05 ETH | 0.05 ETH | 0.1 ETH per 32 ETH of validator balance;<br />up to 6.4 ETH |

The settlement library scales the exit-delay fee exactly like the bad-performance penalty. _fulfillExitObligations computes one penaltyMultiplier from the exit balance clamped to [32 ETH + confirmed excess, 2048 ETH] and applies it to both delayFee and strikesPenalty:

• https://github.com/lidofinance/staking-modules/blob/4d3de6658499e1c1774951780a97d7ae25ca18b8/src/lib/WithdrawnValidatorLib.sol#L107-L127
• constants PENALTY_QUOTIENT = 1 ether, PENALTY_SCALE = 32: https://github.com/lidofinance/staking-modules/blob/4d3de6658499e1c1774951780a97d7ae25ca18b8/src/lib/WithdrawnValidatorLib.sol#L20-L22
• the only unscaled items are the EL withdrawal-request fee (L134) and the slashing loss (L140): https://github.com/lidofinance/staking-modules/blob/4d3de6658499e1c1774951780a97d7ae25ca18b8/src/lib/WithdrawnValidatorLib.sol#L129-L141
• identical in the Hoodi 0x02 build: https://github.com/lidofinance/staking-modules/blob/bbdb033df8b26e45641030d17b8b8465190b21db/src/lib/WithdrawnValidatorLib.sol#L115-L127

So the charge is fee × exitBalance / 32 ETH: 0.1 ETH at 32 ETH, 6.4 ETH at 2,048 ETH. The approved 0x02 CSM landscape says the same, and so does the CMv2 penalties page in this repo (same library, "reduced linearly"):

docs/run-on-lido/cm-v2/penalties.md

Lines 23 to 27 in 8e243a0

	### Exit Delay Fee
	Applied automatically when a validator is not exited within the allowed time after an exit request. The allowed exit delay is 4 days (i.e., 96 hours) for all types according to the [Validator Exits Standard NO Protocol](https://github.com/lidofinance/documents-and-policies/blob/main/Lido%20on%20Ethereum%20Standard%20Node%20Operator%20Protocol%20-%20Validator%20Exits.md).
	The **Exit Delay Fee** charged at withdrawal for a 2,048 ETH validator is 0.64 ETH for PO and 0.32 ETH for all other types. This charge is reduced linearly if the validator's balance is below 2,048 ETH.

Please restore "0.1 ETH per 32 ETH of validator balance; up to 6.4 ETH". The sentence below the table and the pointer from the shared exits page are correct as written but now point at a table that says the opposite:

docs/run-on-lido/csm/penalties.md

Line 46 in 8e243a0

The Slashing penalty and the loss component of a General Delayed Penalty depend on the assessed loss. The Triggerable Exit fee depends on the execution-layer withdrawal request cost and does not scale with the validator balance, so these do not have fixed values in the table.

docs/docs/staking-modules/validator-exits.md

Line 77 in 8e243a0

If the withdrawal amount is below the [confirmed expected balance](#validator-balance-tracking), the difference is applied as a penalty. The module also settles any previously recorded delayed-exit penalty, bad-performance penalty, and applicable execution-layer withdrawal request fee. Some of these amounts are proportional to the validator's balance while others are flat, as documented for [CMv2](/run-on-lido/cm-v2/penalties#exit-delay-fee) and [0x02 CSM](/run-on-lido/csm/penalties#parameters-by-operator-profile).

This is the same point as #984 (comment); the lines above are the exact code path.

2. The four bot findings from 2026-09-09 are still at head

No content commit landed after 2026-09-08; both approvals postdate these comments.

a. Loss baseline. The baseline is the confirmed high-water balance (minExpectedBalance = 32 ETH + keyConfirmedBalance, L114 in the library range linked above), as the shared exits page already says:

docs/docs/staking-modules/index.md

Line 15 in 8e243a0

Node Operators get their rewards from the bond rebase and from their [portion of the staking rewards](/staking-modules/rewards). Accumulated CL penalties resulting in a balance reduction below the deposit balance and stolen EL rewards are confiscated from the bond. Node Operators should perform validator exits upon protocol request to avoid force ejection (via [EIP-7002](https://eips.ethereum.org/EIPS/eip-7002)), and can also voluntarily [exit or eject](/staking-modules/validator-exits) their validators.

docs/docs/staking-modules/validator-exits.md

Lines 17 to 28 in 8e243a0

	The module keeps a **confirmed balance** for every deposited validator key: the highest balance ever proven on the Consensus Layer through [`Verifier`](/staking-modules/contracts/Verifier). Anyone can update it with a balance proof as the validator grows from CL rewards, settled [top-ups](/staking-modules/node-operators#top-up-queue), consolidation inflows, or other CL activity. It never decreases while the validator is active, so it acts as a high-water mark capped at the validator `MAX_EB`.
	It is used in three places:
	- [`Verifier`](/staking-modules/contracts/Verifier) checks it to confirm that a reported withdrawal is large enough to be treated as a full withdrawal.
	- The module uses it as the baseline for the [withdrawal-balance penalty](/run-on-lido/csm/penalties#what-can-affect-your-bond) applied when the validator is [withdrawn](#withdrawal-balance-reporting).
	- When the confirmed balance exceeds the validator's allocated amount, the module raises the allocated amount to match, so validator balance growth is reflected in the module's tracked stake and remaining [top-up](/staking-modules/node-operators#top-up-queue) capacity. This keeps stake allocation fair.
	This approach has two important caveats:
	- **Stale balance proofs can cause under-penalization.** If proof delivery lags behind settled top-ups or balance growth, the confirmed balance can be lower than the validator's actual high-water mark, so a later loss is measured from an outdated baseline.
	- **Consensus Layer balance decreases are assessed without determining fault.** Any decrease from the confirmed high-water mark to the withdrawal balance is charged to the Node Operator, regardless of its cause, so losses from systemic network conditions are not distinguished from operator-caused ones.

b. Additional fine scope. The fine is charged once per operator-level reportGeneralDelayedPenalty of any penaltyType, not per validator and not only for stolen EL rewards (https://github.com/lidofinance/staking-modules/blob/4d3de6658499e1c1774951780a97d7ae25ca18b8/src/lib/GeneralPenaltyLib.sol#L12-L26); the permissions page already says "protocol rule violations":

docs/docs/staking-modules/node-operators.md

Line 154 in 8e243a0

- `generalDelayedPenaltyAdditionalFine` - an additional fine charged for each validator that has stolen EL rewards;

docs/docs/staking-modules/permissions.md

Line 44 in 8e243a0

- Report and cancel general delayed penalties for protocol rule violations, and manage the associated additional fines.

c. Rewards repository link. "GitHub" links only csm-rewards, while the Artifacts section links both repositories:

docs/docs/staking-modules/rewards.md

Line 45 in 8e243a0

The Performance Oracle creates a [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree) with the allocation of the Node Operator rewards and delivers the root on-chain. To make the original tree available to users, it is published on [IPFS](https://ipfs.tech/) and [GitHub](https://github.com/lidofinance/csm-rewards). Instead of storing multiple roots, each new tree consists of all Node Operator rewards ever acquired by the module's Node Operators. Hence, only the latest tree is required to determine the reward allocation at any moment in time. The amount available for distribution can be calculated as `cumulativeFeeShares - distributedShares`. `FeeDistributor` stores `distributedShares` for each Node Operator to ensure correct accounting.

docs/docs/staking-modules/rewards.md

Line 65 in 8e243a0

The Merkle tree dump can be used to construct a valid proof for Node Operators to claim their acquired rewards. Each module publishes its tree and pre-generated proofs in a repository with one branch per network: [cm-v2-rewards](https://github.com/lidofinance/cm-v2-rewards) for CMv2 and [csm-rewards](https://github.com/lidofinance/csm-rewards) for CSM.

d. Per-validator forfeiture and CMv2 scope. Eligibility is per validator (L49), but the bad-performance paragraph speaks per operator and generalizes strikes-based ejection to both modules; the CMv2 penalties page says the strike system is not active in Phase 1. The same generalization is on the exits page.

docs/docs/staking-modules/rewards.md

Lines 84 to 86 in 8e243a0

	If a Node Operator's performance is below the threshold, they will not receive any rewards for that frame. However, the Node Operator can still claim their [bond](/staking-modules/node-operators#bond) rewards (rebase) as usual. This means that even if a Node Operator's validators are not performing well, they can still benefit from the bond rebase. One can find an example of the rewards calculation [here](https://docs.google.com/spreadsheets/d/1hLvuOesPVOYHDqO373bdyiKn4_3UXQF1rATbgTrKhWc/edit?usp=sharing).
	However, consistent bad performance can lead to forced ejection and the application of penalties. Please refer to the [Penalties](/run-on-lido/csm/penalties) guide for more details on this process.

docs/docs/staking-modules/validator-exits.md

Lines 50 to 52 in 8e243a0

	From the module side, validator exits can be requested or triggered for:
	- Unbonded validators. These exits are requested automatically using the `targetLimitMode = 2` (forced mode);
	- Validators with an excessive number of bad performance strikes. These exits are triggered via the permissionless method on the [`ValidatorStrikes`](/staking-modules/contracts/ValidatorStrikes) contract. The strike parameters are set per Node Operator type, and are documented for CSM under [Penalties](/run-on-lido/csm/penalties#what-can-affect-your-bond).

docs/run-on-lido/cm-v2/penalties.md

Lines 43 to 46 in 8e243a0

	## Strike system
	:::info
	A strike system is planned for Phase 2 and is not active in Phase 1.

3. Redirects lose the intro-page fragments (bot thread of 2026-08-28, still open)

docs/docusaurus.config.js

Lines 214 to 217 in 8e243a0

	{
	to: '/staking-modules/',
	from: '/staking-modules/csm/intro',
	},

docs/docusaurus.config.js

Lines 238 to 241 in 8e243a0

	{
	to: '/staking-modules/',
	from: '/staking-modules/cm-v2/intro',
	},

The generated redirect pages do preserve window.location.hash, but /staking-modules/ has none of the old ids: 8 of 11 anchors from csm/intro (#top-up-queue, #validator-balance-tracking, #node-operator-structure, #stake-distribution-queue, …) and all from cm-v2/intro (#weighted-stake-allocation, #meta-operators-registry, …) land at the top of the overview. Internal links are all updated (the build passes with onBrokenAnchors: throw); only external deep links are affected. Either accept explicitly or add the most-linked old ids as explicit anchors on the sections they moved to.

4. Low: the key-status table omits the exit statuses

docs/run-on-lido/csm/lido-csm-widget/upload-remove-view-validator-keys.md

Lines 122 to 134 in 8e243a0

	| Status | What it means | What to do? |
	| --- | --- | --- |
	| <span style={{color: 'orange'}}><strong>Unchecked</strong></span> | Key has been uploaded but not yet validated by the protocol | Wait for validation. If an earlier key is Invalid, remove it so the rest can be checked |
	| **Depositable** | Key is valid and bond is sufficient. Pending deposit from Lido Protocol | Maintain sufficient bond amounts |
	| <span style={{color: 'orange'}}><strong>Non queued</strong></span> | Key is depositable but does not currently hold a place in the deposit queue | No action needed, the key is queued again automatically |
	| **Activation pending** | Key has been deposited and is awaiting activation on the [beacon chain] | Make sure your validator node is online and ready to perform duties |
	| <span style={{color: 'green'}}><strong>Active</strong></span> | Key is active on the [beacon chain] | Make sure your validator node is online to perform its duties |
	| **Withdrawn** | Key has been exited and ETH has been returned to the protocol | Claim your bond and rewards under **Bond & Rewards** |
	| <span style={{color: 'orange'}}><strong>Unbonded</strong></span> | Bond is insufficient for this key, which can be Active or otherwise | - Active key: Top up bond or exit key<br />- Non-active key: Top up bond or do nothing |
	| <span style={{color: 'orange'}}><strong>Strikes</strong></span> | The key has accumulated strikes for performing below the threshold | Improve performance. Enough strikes can lead to ejection and a penalty |
	| <span style={{color: 'red'}}><strong>Slashed</strong></span> | The validator has been slashed on the [beacon chain] | Review your setup to prevent further slashings. See [Slashing Prevention](/run-on-lido/csm/best-practices/slashing-prevention) |
	| <span style={{color: 'red'}}><strong>Duplicated</strong></span> | Key has been uploaded twice | Remove duplicate key |
	| <span style={{color: 'red'}}><strong>Invalid</strong></span> | Uploaded key has an invalid signature | Remove key |

The widget also shows Exit requested, Exit initiated, Exiting and Exited (withdrawal pending) (https://github.com/lidofinance/csm-widget/blob/5443db63aa7b10979ec29c583562191f267a7cee/shared/components/status-chip/key-status-chip.tsx#L30-L49); Exit requested is the one that needs operator action. Worth checking against the deployed widget.

5. Low: frame lengths need a network qualifier

docs/docs/staking-modules/rewards.md

Line 53 in 8e243a0

Each deployment sets its own `frame` length, it is 28 days in CSM and 14 days in CMv2.

docs/run-on-lido/csm/penalties.md

Line 30 in 8e243a0

One period of poor performance does not immediately reduce your bond. The validator first loses its Node Operator reward for that 28-day frame and receives a strike. Strikes expire after the applicable lifetime if the validator does not continue underperforming.

On chain these are mainnet values (CSM 6300 epochs, CMv2 3150). On Hoodi both CSM modules run 3150 epochs (14 days) and CMv2 runs 1575 (7 days).

Informational

• The staking-modules repository README still links /staking-modules/csm/intro (https://github.com/lidofinance/staking-modules/blob/9a9715bbc0bfc5ae5b3243de898b5f9e49b54d51/README.md#L10). The redirect covers it; a one-line follow-up there removes the hop.
• Prettier non-conformance on the generated contract pages is pre-existing and not CI-enforced.

[eenti]

Thanks for the comments @tamtamchik @TheDZhon, and sorry for the back and forth! It's pretty big and it's easy to miss some things!

@TheDZhon re: "3. Redirects lose the intro-page fragments (bot thread of 2026-08-28, still open)", we agreed that it's acceptable as it is.

Everything else should be ready now.

[TheDZhon]

GG