Skip to main content

Oracle Duties

Oracles run the v3-oracle ↗ nodes and are responsible for validator registration, reward distribution, and validator exits.

Validator Registration Approval​

Oracles approve validator registration requests before the Vault contract forwards the deposit to the Beacon Chain Deposit Contract ↗.

The Operator Service monitors the Vault and, once enough ETH has accumulated (at least 32 ETH), prepares a registration and sends an approval request to all 11 Oracles. The request carries all the information each Oracle needs to verify the registration trustlessly, including the encrypted exit signature shares that let the protocol exit the validators on demand.

Each Oracle independently:

  1. rebuilds the deposit message and verifies the deposit signature against it;
  2. decrypts its own exit signature share and verifies it is a valid BLS signature against the corresponding public-key shard;
  3. confirms that none of the public keys are already registered and that each validator is assigned the next expected index;
  4. uploads the encrypted exit shares to IPFS and signs an approval message that commits to their IPFS hash, the current deposit_root, the Vault address, the validators payload (public keys and deposit signatures), and an expiration deadline.

Once at least 6 Oracles have signed, the Operator Service bundles those signatures and submits them to the Keeper ↗ — the smart contract that enforces the rules on-chain.

The Keeper confirms the 6-of-11 threshold is met and that the deposit_root still matches what the Oracles signed, ensuring the Deposit Contract's state did not change since the Oracles approved — which also protects against the front-running withdrawal credentials attack ↗.

Once everything passes, the Vault forwards the deposit to the Beacon Chain Deposit Contract ↗. The deposit enters the Beacon Chain's deposit queue, and the validator is created once the pending deposit is processed.

Reward Distribution​

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 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;
  5. signs an EIP-712 message that includes the Merkle root and the IPFS hash.

Once enough Oracles have voted, the Keeper service ↗ polls each Oracle's API, collects a threshold of matching signatures (rewardsMinOracles, currently 6 of 11), and submits them to the Keeper contract ↗. The Keeper contract verifies the signers, checks the threshold and nonce, and stores the new Merkle root. Individual Vaults can then harvest their rewards.

For MetaVaults, the per-Vault calculation also propagates the underlying sub-Vaults' rewards into the parent.

IconHow 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 newly distributed share, releasing it once the Vault produces its next correct MEV block (or once all its validators have fully withdrawn).

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 Vault operator disappears.

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​

The Pectra upgrade ↗ 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.

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 ↗ verifies that a threshold of Oracles (currently 6 of 11) has signed.

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.

IconUnder 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.

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 ↗ 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 ↗.
Last updated on