Skip to main content

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.

​
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.
OutcomeResult
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

1

Register

Call OracleAggregator.registerOracle() — your status becomes PENDING.
2

Approval

The Bron DAO reviews and approves your registration via registerOracleResponse(oracle, isAccepted).
3

Subscribe to Networks

Call subscribeToNetwork(networkId) for each blockchain network you want to validate. An oracle can subscribe to up to 30 networks.
4

Start Validating

Once active and subscribed, your oracle participates in consensus for orders on those networks.

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