> ## Documentation Index
> Fetch the complete documentation index at: https://developer.bron.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Oracle

## Overview

**Oracles** are independent validators that confirm cross-chain transactions in Bron Intents.
Every order requires oracle consensus at two checkpoints: after the user sends funds, and after the solver sends funds.

Oracles monitor blockchain events, verify transactions on-chain, and submit their votes to the **OracleAggregator** smart contract. A quorum-based mechanism ensures that no single oracle can approve or reject a transaction alone.

## Role in the Protocol

Oracles participate at two critical points during order execution:

### 1. User Transaction Confirmation

After the user sends funds to the solver on the base network:

* Oracles fetch the transaction from the base blockchain
* Check amount, sender, receiver, and transferred token
* Submit vote via `oracleConfirmUserTx(orderId, isConfirmed)` on the OracleAggregator contract

### 2. Solver Transaction Confirmation

After the solver sends funds to the user on the quote network:

* Oracles fetch the transaction from the quote blockchain
* Check amount, sender, receiver, and transferred token
* Submit vote via `oracleConfirmSolverTx(orderId, isConfirmed)` on the OracleAggregator contract

Each vote must be submitted within the network's **confirmation time window**. Late votes are rejected.

## Consensus Mechanism

Decisions are made by **quorum** — more than half of the oracles subscribed to the relevant network must vote.

| Outcome                               | Result                                                 |
| ------------------------------------- | ------------------------------------------------------ |
| Yes votes > No votes (quorum reached) | Order proceeds to the next step                        |
| No votes > Yes votes (quorum reached) | User TX: order cancelled. Solver TX: solver liquidated |
| Tie (quorum reached)                  | Consensus resets, new voting round starts              |

Oracles that vote against the majority are placed into a **cooldown** period and temporarily unsubscribed from all networks.

## Oracle Lifecycle

### Registration Flow

<Steps>
  <Step title="Register">
    Call `OracleAggregator.registerOracle()` — your status becomes `PENDING`.
  </Step>

  <Step title="Approval">
    The Bron DAO reviews and approves your registration via `registerOracleResponse(oracle, isAccepted)`.
  </Step>

  <Step title="Subscribe to Networks">
    Call `subscribeToNetwork(networkId)` for each blockchain network you want to validate.
    An oracle can subscribe to up to 30 networks.
  </Step>

  <Step title="Start Validating">
    Once active and subscribed, your oracle participates in consensus for orders on those networks.
  </Step>
</Steps>

## Fee Distribution

Oracles earn fees for participating in consensus:

1. Each order has an **oracle fee** calculated as a percentage of the order amount
2. Fees are transferred to the OracleAggregator after order completion
3. Fees are distributed **weighted by total positive votes** — an oracle that voted `true` at both checkpoints (user TX and solver TX) earns more than one that voted `true` at only one
4. Oracles claim accumulated fees via `claimOracleCollectedFees(feeToken)`

## Penalty System

Oracles that vote against the majority consensus receive a **per-network cooldown** on the network where the incorrect vote occurred.

### Network Cooldown

When quorum is reached and an oracle is on the losing side:

1. The oracle receives a cooldown on **that specific network** — it cannot vote on orders for that network until the cooldown expires
2. The oracle remains `ACTIVE` and subscribed to all its networks, so it can continue voting on other networks
3. While in cooldown, the oracle is excluded from the effective oracle count for quorum calculation on that network
4. Expired cooldowns are cleaned up automatically when the oracle submits its next vote, or manually via `cleanupExpiredNetworkCooldown`
5. Once the cooldown expires, the oracle resumes voting on that network automatically — no re-subscription required

### Auto-Suspension

If the number of active cooldowns **strictly exceeds** `maxNetworkCooldownsBeforeSuspend` (i.e. with a threshold of 5, suspension triggers at 6 cooldowns):

1. Status changes to `SUSPENDED`.
2. The oracle is automatically unsubscribed from **all** networks and all active cooldown timers are cleared as a side-effect of suspension.
3. Only the Bron DAO can unsuspend the oracle via `updateSuspendOracleStatus(oracle, false)`.
4. Once unsuspended, the oracle must re-subscribe to networks manually.

A suspended oracle that is not unsuspended can ultimately be removed by the Bron DAO via `kickOracle`. Note: `kickOracle` only works on oracles already in `SUSPENDED` status; it sets them to `INACTIVE`.

This tiered mechanism allows minor disagreements to be resolved with a temporary network-level penalty, while persistent misbehavior across multiple networks triggers a full suspension requiring DAO intervention.