---
tags: Oracle, withdrawals
title: Accounting oracle
---

# Accounting oracle

## Data collection

TODO

## Withdrawal requests finalisation

Each oracle report, it decides how many requests to finalize and at what rate. Requests are finalized in the order in which they were created by moving the cursor to the last finalized request. Oracle must take two things into account:

1. Available ETH and share rate
2. Safe requests finalisation border

### Available ETH and rate

The Oracle report has two parts: the report of the number of validators and their total balance and the finalization of requests in the Withdrawal Queue. The tricky part is that the finalization of requests requires data from the first part of the report. So to calculate them we simulate oracle report making static call to `handleOracleReport` in Lido contract, getting share rate and amount of ETH that can be withdrawn from Withdrawal Vault and Execution Layer Rewards Vault taking into account the limits.

def get_requests_finalization_data(report_data, ref_block_hash):
  (total_pooled_ether, total_shares, withdrawals, el_rewards) = simulate_oracle_report(report_data, ref_block_hash)
  
  reserved_buffer = get_reserved_buffer(ref_block_hash)
  available_eth = reserved_buffer + withdrawals + el_rewards

  share_rate = get_share_rate(total_pooled_ether, total_shares)

  return (available_eth, share_rate)


def get_reserved_buffer(ref_block_hash):
  buffered_eth = lido_contract.get_buffered_ether(block_identifier=ref_block_hash)
  withdrawal_reserve = withdrawal_queue_contract.unfinalized_steth(block_identifier=ref_block_hash)

  return min(withdrawal_reserve, buffered_eth)


def get_share_rate(total_pooled_ether, total_shares):
  return 1e27 * total_pooled_ether // total_shares


def simulate_oracle_report(report_data, ref_block_hash):
  last_processing_ref_slot = oracle_contract.get_last_processing_ref_slot(block_identifier=ref_block_hash)
  slots_elapsed = report_data.ref_slot - last_processing_ref_slot
  seconds_elapsed_since_last_report = slots_elapsed * SECONDS_PER_SLOT

  return lido_contract.handle_oracle_report(
    seconds_elapsed_since_last_report,

    report_data.cl_validators,
    report_data.cl_balance_gwei * 1e9,

    report_data.withdrawal_vault_balance,
    report_data.el_rewards_vault_balance,

    request_id_to_finalize_up_to=0,
    finalization_share_rate=0
  ).call(block_identifier=ref_block_hash)

### Safe requests finalisation border

The protocol can be in two states: Turbo and Bunker modes. Turbo mode is a usual state when requests are finalized as fast as possible, while Bunker mode assumes a more prudent requests finalization and is activated if it's necessary to mitigate undesirable factors. More datails in [Withdrawals Landscape](https://hackmd.io/@lido/SyaJQsZoj).

**In Turbo mode**, there is only one border that does not allow to finalize requests created close to the reference slot to which the oracle report is performed.

- New requests border

**In Bunker mode** there are more safe borders. The protocol takes into account the impact of negative factors that occurred in a certain period and finalizes requests on which the negative effects have already been socialized. The safe border is considered to be the earliest of of the following:

- New requests border
- Associated slashing border
- Negative rebase border

Before we begin examining each border, let's introduce some notations that are used in the graphs below:

<img style="margin: 0 0 15px 0" width="500" src="https://hackmd.io/_uploads/BJwAPuthj.png" />

#### New requests border

The border is a constant interval near the reference epoch in which no requests can be finalized:

<img style="margin: 0 0 15px 0" width="500" src="https://hackmd.io/_uploads/Bk8rFuF2o.png" />

NEW_REQUESTS_BORDER = 8 # epochs ~50 min

def get_new_requests_border_epoch(ref_epoch):
  return ref_epoch - NEW_REQUESTS_BORDER

#### Associated slashing border

The border represents the latest epoch before the reference slot before which there are no incompleted associated slashings.

<img style="margin: 0 0 15px 0" width="500" src="https://hackmd.io/_uploads/SyMwK_Fhs.png" />

In the image above there are 4 slashings on the timeline that start with `slashed_epoch` and end with `withdrawable_epoch` and some points in time: withrawal request and reference epoch relationship of the slashnings with which we want to analyze.

##### Completed non-associated

<img style="margin: 0 0 15px 0" width="500" src="https://hackmd.io/_uploads/rJxOYdKhj.png" />

The slashing is non-associated with the withdrawal request since it started and ended before the request was created. It's completed since `withdrawable_epoch` is before `reference_epoch`.

##### Completed associated

<img style="margin: 0 0 15px 0" width="500" src="https://hackmd.io/_uploads/SJhdKOt3i.png" />

The slashing is associated with withdrawal request, since the request is in its boundaries. In this case the slashing is completed since `withdrawable_epoch` is before `reference_epoch`, so all possible impact from it is accounted. This slashing should not block the finalization of this request.

##### Incompleted associated

<img style="margin: 0 0 15px 0" width="500" src="https://hackmd.io/_uploads/Sk0KKOY3i.png" />

Slashing is associated with the withdrawal request and is still going on. The impact from it is still incomplete, so such a request cannot be finalized.

##### Incompleted non-associated

<img style="margin: 0 0 15px 0" width="500" src="https://hackmd.io/_uploads/SyR9tdYho.png" />

Incompleted but non-associated slashing do not block finalization of the request. The impact of it is still incomplete, nevertheless we must allow users to unstake even in bad weather.

##### Computation of the border

<img style="margin: 0 0 25px 0" width="500" src="https://hackmd.io/_uploads/H13Pf5F2s.png" />

The border is calculated as the earliest `slashed_epoch` among all incompleted slashings at the point of `reference_epoch` rounded to the start of the closest oracle report frame - `NEW_REQUESTS_BORDER`.

def get_associated_slashings_border_epoch(ref_epoch):
  earliest_slashed_epoch = get_earliest_slashed_epoch_among_incomplete_slashings(ref_epoch)

  if earliest_slashed_epoch is None:
    return ref_epoch
  
  rounded_epoch = round_epoch_down_to_report_frame(earliest_slashed_epoch)
  return rounded_epoch - NEW_REQUESTS_BORDER

[Detailed research of associated slashings](https://hackmd.io/@lido/r1Qkkiv3j)

#### Negative rebase border

Bunker mode can be enabled by a negative rebase in case of mass validator penalties. In this case the border is considered the reference slot of the previous oracle report from the moment the Bunker mode was activated - `NEW_REQUESTS_BORDER`.

<img style="margin: 0 0 0 0" width="500" src="https://hackmd.io/_uploads/ByjuG5Kho.png" />

<img style="margin: 0 0 15px 0" width="500" src="https://hackmd.io/_uploads/rJ0wrqY2i.png" />

This border has a maximum length equal to two times the governance reaction time.

MAX_NEGATIVE_REBASE_BORDER = 1536 # epochs ~6.8 days

def get_negative_rebase_border_epoch(ref_epoch):  
  bunker_start_epoch = get_bunker_start_epoch_from_contract()
  
  if bunker_start_epoch is None:
    bunker_start_epoch = get_previous_report_epoch_from_contract()

  bunker_start_border_epoch = bunker_start_epoch - NEW_REQUESTS_BORDER
  earliest_allowable_epoch = ref_epoch - MAX_NEGATIVE_REBASE_BORDER

  return max(earliest_allowable_epoch, bunker_start_border_epoch)

#### Border union

The safe border is chosen depending on the protocol mode and is always the longest of all.

<img style="margin: 0 0 15px 0" width="500" src="https://hackmd.io/_uploads/r1NaSqYni.png" />

def get_safe_border_epoch(ref_epoch):
  is_bunker = detect_bunker_mode()
  new_request_border_epoch = get_new_requests_border_epoch(ref_epoch)

  if not is_bunker:
    return new_request_border_epoch
  
  negative_rebase_border_epoch = get_negative_rebase_border_epoch(ref_epoch)
  associated_slashings_border_epoch = get_associated_slashings_border_epoch(ref_epoch)

  return min(
    new_request_border_epoch,
    negative_rebase_border_epoch,
    associated_slashings_border_epoch
  )

### Bunker mode

Activation of Bunker mode assumes the presence of one of the following events:
- CL rewards for the reporting period are negative
- CL rewards for the last epoch are negative
- The slashing midterm penalties can cause negative CL rewards in the future

TODO: describe in details

### Finalization

With the amount of available ETH, rate and safe border, the oracle can find the request id up to and including which requests can be finalized.

def find_request_id_to_finalize_up_to():
  last_finalized_request_id = get_last_finalized_request_id()
  last_request_id = get_last_request_id()

  if last_finalized_request_id >= last_request_id:
    # Contract expects 0 in case no finalization is needed
    return 0

  available_eth, share_rate = get_requests_finalization_data()
  safe_border_timestamp = get_safe_border_timestamp()

  start_request_id = last_finalized_request_id
  end_request_id = last_request_id

  request_id_to_finalize_up_to = 0

  while start_request_id <= end_request_id:
    mid_request_id = (end_request_id + start_request_id) // 2

    required_eth, request_timestamp, _ = withdrawal_queue_contract.finalization_batch(
      mid_request_id,
      share_rate
    )

    if required_eth <= available_eth and request_timestamp < safe_border_timestamp:
      request_id_to_finalize_up_to = mid_request_id

      # Ignore left half
      start_request_id = mid_request_id + 1
    else:
      # Ignore right half
      end_request_id = mid_request_id - 1

  return request_id_to_finalize_up_to