From 56e5b03555ef0152fe6aa88a684ce87752dc29ad Mon Sep 17 00:00:00 2001 From: ulieth Date: Wed, 3 Jun 2026 18:48:26 +0300 Subject: [PATCH 1/3] Add Validator Exits, Consolidations, and Oracle vote flow sections --- docs/docs/oracles/oracle-duties.mdx | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/docs/oracles/oracle-duties.mdx b/docs/docs/oracles/oracle-duties.mdx index bc41af6b..7782df35 100644 --- a/docs/docs/oracles/oracle-duties.mdx +++ b/docs/docs/oracles/oracle-duties.mdx @@ -57,11 +57,21 @@ The reward update process has protocol-wide impact. ## Validator Exits -The validator exit process is automated and trustless. -Validator exits require exit signatures that are generated during the validator registration process. +The validator exit process is automated and trustless. During validator registration, the Operator Service generates each validator's pre-signed exit message, splits it into BLS signature shares using a threshold scheme, and encrypts a share for every Oracle — so the validators can always be exited, even if the operator disappears. -As part of registration, the Operator Service encrypts exit signatures using Shamir's secret sharing and distributes them to all Oracles. +When a Vault has unstake requests, the Oracles independently identify which validators must exit and publish those exits over their APIs. The Operator Service picks up the Oracle-signalled exits and triggers them on-chain through the Vault contract. -:::custom-notes[Key Benefit] -This approach ensures validators can be exited on demand while maintaining protocol security through decentralized signature management. +## Validator Consolidations + +After the [Pectra upgrade ↗](https://ethereum.org/en/roadmap/pectra/), validators with `0x01` withdrawal credentials can be upgraded to `0x02` (raising the effective balance cap to 2048 ETH), and multiple validators can be merged into a single compounding validator. + +Both operations require the Vault's validators manager signature. The upgrade from `0x01` to `0x02` additionally requires Oracle approval, because it introduces a new compounding validator: the Operator Service sends a **consolidation request**, each Oracle confirms the keys are active validators of the Vault and returns a signed approval, and the Vault contract submits the consolidation once the [ConsolidationsChecker contract ↗](https://etherscan.io/address/0x033E5BaE5bdc459CBb7d388b41a9d62020Be810F#code) verifies that at least **6 of 11** Oracles have signed. + +Merges into an existing compounding validator need only the validators manager signature — no Oracle approval — and the Vault contract requires the target to already be a registered `0x02` validator. + +:::custom-info[How Oracle Votes Reach the Chain] +Oracles never submit transactions themselves — they only sign messages and expose them over HTTP. Two off-chain services bridge Oracle signatures to on-chain state: + +- The **Operator Service** collects Oracle signatures for validator registrations and consolidations, since the Vault operator is the party initiating those flows. +- The [Keeper service ↗](https://github.com/stakewise/v3-keeper) polls each Oracle's API for reward distribution votes, aggregates a threshold of them, and submits the transaction to the [Keeper contract ↗](https://etherscan.io/address/0x6B5815467da09DaA7DC83Db21c9239d98Bb487b5#code). ::: From 0e16c4315896d683e028bf6db4a5d175c20953e8 Mon Sep 17 00:00:00 2001 From: ulieth Date: Mon, 29 Jun 2026 14:51:04 +0300 Subject: [PATCH 2/3] Clarify Validator Consolidations and Oracle architecture under the hood --- docs/docs/oracles/oracle-duties.mdx | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/docs/oracles/oracle-duties.mdx b/docs/docs/oracles/oracle-duties.mdx index 7782df35..081ee2d0 100644 --- a/docs/docs/oracles/oracle-duties.mdx +++ b/docs/docs/oracles/oracle-duties.mdx @@ -63,15 +63,17 @@ When a Vault has unstake requests, the Oracles independently identify which vali ## Validator Consolidations -After the [Pectra upgrade ↗](https://ethereum.org/en/roadmap/pectra/), validators with `0x01` withdrawal credentials can be upgraded to `0x02` (raising the effective balance cap to 2048 ETH), and multiple validators can be merged into a single compounding validator. +The [Pectra upgrade ↗](https://ethereum.org/en/roadmap/pectra/) introduced compounding validators: validators with `0x02` withdrawal credentials that can hold up to 2048 ETH of effective balance, instead of the previous 32 ETH cap. A Vault can upgrade an existing `0x01` validator to `0x02`, or merge several validators into a single compounding validator. -Both operations require the Vault's validators manager signature. The upgrade from `0x01` to `0x02` additionally requires Oracle approval, because it introduces a new compounding validator: the Operator Service sends a **consolidation request**, each Oracle confirms the keys are active validators of the Vault and returns a signed approval, and the Vault contract submits the consolidation once the [ConsolidationsChecker contract ↗](https://etherscan.io/address/0x033E5BaE5bdc459CBb7d388b41a9d62020Be810F#code) verifies that at least **6 of 11** Oracles have signed. +**Creating a new compounding validator** (upgrading `0x01` to `0x02`) requires Oracle approval, because it introduces a validator the protocol has not yet recorded. The Operator Service sends a **consolidation request**, each Oracle confirms the keys are active validators of the Vault and returns a signed approval, and the Vault contract submits the consolidation once the [ConsolidationsChecker contract ↗](https://etherscan.io/address/0x033E5BaE5bdc459CBb7d388b41a9d62020Be810F#code) verifies that a threshold of Oracles (currently 6 of 11) has signed. -Merges into an existing compounding validator need only the validators manager signature — no Oracle approval — and the Vault contract requires the target to already be a registered `0x02` validator. +**Merging into an existing compounding validator**, by contrast, needs no Oracle approval: the Vault contract only checks that the destination is already a registered `0x02` validator. -:::custom-info[How Oracle Votes Reach the Chain] -Oracles never submit transactions themselves — they only sign messages and expose them over HTTP. Two off-chain services bridge Oracle signatures to on-chain state: +:::custom-info[Under the Hood] +Oracles are off-chain nodes that bridge the Vault and the Beacon Chain. The smart contracts that define a Vault's behavior live on the Execution Layer, while the validators earning its rewards run on the Consensus Layer, and the Execution Layer cannot read Consensus Layer state. Oracles read that state, do the work it requires off-chain, and sign the result, so the Vault can act on it. -- The **Operator Service** collects Oracle signatures for validator registrations and consolidations, since the Vault operator is the party initiating those flows. -- The [Keeper service ↗](https://github.com/stakewise/v3-keeper) polls each Oracle's API for reward distribution votes, aggregates a threshold of them, and submits the transaction to the [Keeper contract ↗](https://etherscan.io/address/0x6B5815467da09DaA7DC83Db21c9239d98Bb487b5#code). +Oracles never submit transactions themselves; they only sign messages and expose them over their HTTP APIs. Getting those signatures on-chain is left to two off-chain services that fetch them: + +- The **Operator Service**, a Vault's automation software, obtains Oracle approvals for the validator operations it submits, such as registration and consolidation, and includes those signatures in the transaction it sends to the Vault contract. +- The [Keeper service ↗](https://github.com/stakewise/v3-keeper) handles reward distribution. It polls each Oracle's API for signed reward votes, aggregates a threshold of them, and submits the transaction to the [Keeper contract ↗](https://etherscan.io/address/0x6B5815467da09DaA7DC83Db21c9239d98Bb487b5#code). ::: From 44de3252ab955711b5740163853f6a89fee8c836 Mon Sep 17 00:00:00 2001 From: ulieth Date: Mon, 29 Jun 2026 18:20:52 +0300 Subject: [PATCH 3/3] Clarify Validator Exits flow --- docs/docs/oracles/oracle-duties.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/docs/oracles/oracle-duties.mdx b/docs/docs/oracles/oracle-duties.mdx index 081ee2d0..6a220c21 100644 --- a/docs/docs/oracles/oracle-duties.mdx +++ b/docs/docs/oracles/oracle-duties.mdx @@ -57,9 +57,11 @@ The reward update process has protocol-wide impact. ## Validator Exits -The validator exit process is automated and trustless. During validator registration, the Operator Service generates each validator's pre-signed exit message, splits it into BLS signature shares using a threshold scheme, and encrypts a share for every Oracle — so the validators can always be exited, even if the operator disappears. +The validator exit process is automated and trustless. During validator registration, the Operator Service generates each validator's pre-signed exit message, splits it into BLS signature shares using a threshold scheme, and encrypts a share for every Oracle, so the validators can always be exited, even if the Vault operator disappears. -When a Vault has unstake requests, the Oracles independently identify which validators must exit and publish those exits over their APIs. The Operator Service picks up the Oracle-signalled exits and triggers them on-chain through the Vault contract. +When a Vault has unstake requests, the Operator Service covers them first, using partial withdrawals from its `0x02` validators rather than exiting them. Only if the operator has not freed enough ETH within the `force_withdrawals_period` (24 hours) do the Oracles step in: they identify which validators must exit, reconstruct the exit signatures from their shares, and publish those exits over their APIs for submission on-chain through the Vault contract. + +Because Oracles can only exit validators in full, this ordering matters. Covering a small unstake request with a full exit could withdraw an entire compounding validator of up to 2048 ETH, so a Vault relies on its Operator Service to meet requests precisely through partial withdrawals, leaving the Oracle path as a fallback. ## Validator Consolidations