From 3c3c6cc3db1b4b26cfe97b8a49e2e8d75af1accc Mon Sep 17 00:00:00 2001 From: ulieth Date: Mon, 1 Jun 2026 21:31:11 +0300 Subject: [PATCH 1/3] Refine Reward Distribution section --- docs/docs/oracles/oracle-duties.mdx | 36 +++++++++++++++++------------ 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/docs/docs/oracles/oracle-duties.mdx b/docs/docs/oracles/oracle-duties.mdx index bc41af6b..72861fae 100644 --- a/docs/docs/oracles/oracle-duties.mdx +++ b/docs/docs/oracles/oracle-duties.mdx @@ -38,22 +38,28 @@ For details on how the Operator Service initiates and prepares validator registr Oracle reward distribution process for Vaults -Oracles periodically vote on the consensus rewards/penalties accumulated by the Vaults in the Beacon Chain and execution rewards (MEV & priority fees) for the Vaults connected to the Smoothing Pool. - -The reward distribution process consists of the following steps: - -:::custom-info[Reward Distribution Process] -1. Verify sufficient time has passed since the last reward distribution. -2. Calculate rewards/penalties for all Vaults based on validator balances in the Beacon Chain. -3. Calculate MEV and priority fee rewards for Vaults connected to the Smoothing Pool. -4. Create Merkle trees from the reward calculations and upload them to IPFS. For example, bafkreibqhdr6p5uh67ickt4dpppb525bwuofjocnpsx4dbl57llogfph2e. -5. Save the cryptographically signed vote to the local database and expose via API. -6. The [Keeper service ↗](https://github.com/stakewise/v3-keeper/) fetches votes from Oracle APIs, concatenates them, and sends the resulting transaction to the [Keeper contract ↗](https://etherscan.io/address/0x6B5815467da09DaA7DC83Db21c9239d98Bb487b5#code). -7. Upon verification, the protocol updates global state. -8. Individual Vaults can claim their rewards. -::: +Oracles periodically vote on the consensus rewards and penalties accumulated by each Vault's validators on the Beacon Chain. + +Each Oracle independently: + +1. computes each Vault's consensus rewards from its validators' Beacon Chain balances; +2. computes each Vault's MEV rewards — for Smoothing Pool Vaults, a proportional slice of the shared escrow; for Vaults with their own MEV escrow, the on-chain unlocked amount; +3. builds a Merkle tree of all per-Vault rewards and computes each Vault's proof; +4. uploads the full snapshot (every Vault's rewards + every Vault's proof) to IPFS; +5. signs an EIP-712 message that includes the Merkle root and the IPFS hash. + +Once enough Oracles have voted, the [Keeper service ↗](https://github.com/stakewise/v3-keeper/) polls each Oracle's API, collects a threshold of matching signatures (`rewardsMinOracles`, currently **6 of 11**), and submits them to the [Keeper contract ↗](https://etherscan.io/address/0x6B5815467da09DaA7DC83Db21c9239d98Bb487b5#code). The Keeper contract verifies the signers, checks the threshold and nonce, and stores the new Merkle root. Individual Vaults can then harvest their rewards. -The reward update process has protocol-wide impact. +For MetaVaults, the per-Vault calculation also propagates the underlying sub-Vaults' rewards into the parent. + +:::custom-notes[How the Smoothing Pool share is calculated] +Every 12 hours, Oracles: + +1. Calculate the new MEV that arrived in the shared escrow since the last vote; +2. Reject misbehaving Vaults (e.g. redirecting the fee recipient, using an untrusted relay, or skimming rewards); +3. Split the new MEV among Vaults, weighted by their validators' attestation rewards on the Beacon Chain; +4. Lock each Vault's share until the Vault has been active and non-rejected through the full period (or until all its validators have fully withdrawn) — then unlock it. +::: ## Validator Exits From 7a5462f5458277ee30c7b02d2590eeb51e1374dc Mon Sep 17 00:00:00 2001 From: ulieth Date: Wed, 3 Jun 2026 18:10:20 +0300 Subject: [PATCH 2/3] Clarify Smoothing Pool reward unlock condition --- docs/docs/oracles/oracle-duties.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/oracles/oracle-duties.mdx b/docs/docs/oracles/oracle-duties.mdx index 72861fae..690bdb18 100644 --- a/docs/docs/oracles/oracle-duties.mdx +++ b/docs/docs/oracles/oracle-duties.mdx @@ -58,7 +58,7 @@ Every 12 hours, Oracles: 1. Calculate the new MEV that arrived in the shared escrow since the last vote; 2. Reject misbehaving Vaults (e.g. redirecting the fee recipient, using an untrusted relay, or skimming rewards); 3. Split the new MEV among Vaults, weighted by their validators' attestation rewards on the Beacon Chain; -4. Lock each Vault's share until the Vault has been active and non-rejected through the full period (or until all its validators have fully withdrawn) — then unlock it. +4. Lock each Vault's newly distributed share, releasing it once the Vault produces its next correct MEV block (or once all its validators have fully withdrawn). ::: ## Validator Exits From 0df93fb2951624e11bb28171396d4ee30a2f0b2a Mon Sep 17 00:00:00 2001 From: ulieth Date: Tue, 30 Jun 2026 09:10:58 +0300 Subject: [PATCH 3/3] Add penalties to consensus rewards wording --- docs/docs/oracles/oracle-duties.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/oracles/oracle-duties.mdx b/docs/docs/oracles/oracle-duties.mdx index 690bdb18..4eedddef 100644 --- a/docs/docs/oracles/oracle-duties.mdx +++ b/docs/docs/oracles/oracle-duties.mdx @@ -42,7 +42,7 @@ Oracles periodically vote on the consensus rewards and penalties accumulated by Each Oracle independently: -1. computes each Vault's consensus rewards from its validators' Beacon Chain balances; +1. computes each Vault's consensus rewards and penalties from its validators' Beacon Chain balances; 2. computes each Vault's MEV rewards — for Smoothing Pool Vaults, a proportional slice of the shared escrow; for Vaults with their own MEV escrow, the on-chain unlocked amount; 3. builds a Merkle tree of all per-Vault rewards and computes each Vault's proof; 4. uploads the full snapshot (every Vault's rewards + every Vault's proof) to IPFS;