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 they are submitted to the Beacon Chain Deposit Contract ↗.

The Operator Service → periodically checks whether its Vaults have accumulated enough ETH for registering new validator(s). When the Vault has enough ETH, the operator sends a registration approval request to Oracles that includes encrypted exit signature(s) for the validator(s) it is attempting to create. This is done to maintain the protocol's ability to exit validators on demand, and to perform checks against the front-running withdrawal credentials attack described here ↗. The operator must receive 8 out of 11 approvals from Oracles to register a validator for the Vault.

IconApproval Process
  1. Operator sends the validator registration requests and encrypted exit signatures to the Oracles.
  2. Oracles sign approval messages that include the current tree root hash from the Beacon Chain Deposit Contract.
  3. Operator submits registration to the Vault contract with Oracle signatures.
  4. Vault contract calls the Keeper contract ↗ to validate Oracle signatures and confirm the tree root hash hasn't changed.
  5. Vault transfers ETH to the Beacon Chain deposit contract to complete validator registration.

This process ensures Oracles approve validators based on current Beacon Chain state, bridging the consensus and execution layers while preventing stale approvals and replay attacks.

IconDeep Dive

For details on how the Operator Service initiates and prepares validator registration, see the Validator Registration → section in Vaults.

Reward Distribution​

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:

IconReward 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 ↗ fetches votes from Oracle APIs, concatenates them, and sends the resulting transaction to the Keeper contract ↗.
  7. Upon verification, the protocol updates global state.
  8. Individual Vaults can claim their rewards.

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.

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.

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