OpenOraclePriceCoordinator
Obtains a fresh REP-per-ETH price and coordinates withdrawals, delegated liquidation routing, approval reservations, and terminal cleanup. OpenOraclePriceCoordinator source contract
Read surface
Configuration getters are MAX_PENDING_SETTLEMENT_OPERATIONS, OPEN_INTEREST_DIVIDER, reputationToken, securityPool, openOracle, weth, liquidationApprovalRegistry, gasConsumedOpenOracleReportPrice, gasConsumedSettlement, gasUnitsForOneDispute, initialReportPriorityFeeAttoEthPerGas, targetPriceErrorForDispute, openOracleSecurityMultiplierBps, settlementTime, disputeDelay, protocolFee, feePercentage, multiplier, timeType, trackDisputes, protocolFeeRecipient, escalationHaltMultiplierBps, maxSettlementBaseFeeMultiplierBps, and minLiquidationPriceDistanceBps. Current report and operation getters are pendingReportId, pendingReportSponsor, pendingOperationSlotId, lastSettlementTimestamp, lastPrice, pendingReportMaxSettlementBaseFeeAttoEthPerGas, stagedOperationCounter, and stagedOperations. lastSettlementTimestamp records when the accepted final report reached settlement eligibility (report timestamp plus settlementTime), not when settle was called, and isPriceValid measures freshness from it. Use isPriceValid, minimumToken1ReportAttoEth, getRequestPriceCostAttoEth, getQueuedOperationCostAttoEth, getSettlementCallbackGasLimit, getPendingOperationSlot, getActiveStagedOperationCount, getActiveStagedOperations, getPendingSettlementOperationCount, and getPendingSettlementOperationIds for derived or paged state.
Report and staged-operation liveness depends on A16 timely inclusion, A17 corrector capability, A18 independent correction incentive, A19 observable correctable price, and A06 lifecycle executors. When lastPrice is zero, the official client currently needs an offchain market quote to propose the first report; quote availability is a client limitation rather than a protocol security assumption. Proposals copied from a nonzero cached price do not use that quote path.
State-changing interactions
| Transaction | Caller | Main prerequisites | State or asset effect | Primary signals |
|---|---|---|---|---|
requestPriceIfNeededAndStageLiquidation(targetVault, receiverVault, requestedDebtAttoEth, approvalId, ..., bountyAttoEth) |
Liquidation operator; a delegated receiver must have approved this exact operator | Receiver differs from target; delegated approval matches pool, receiver, operator, and target scope, has available cumulative and per-operation quota, and remains valid through latest execution. | Stages explicit operator, receiver, target backing, and target capacity ownership and reserves bounded receiver quota before any oracle work. The queue event retains the full historical observation for indexing, while live execution inputs are not duplicated in persistent operation storage. The self-receiving operator path uses a zero approval ID. | LiquidationRouteStaged; LiquidationApprovalReserved on a delegated route; staged-operation lifecycle events |
requestPriceIfNeededAndStageOperation(...) with funding when stale |
Vault owner for self withdrawal or a target change; self-receiving liquidation callers are also supported. While a report is pending, only that report sponsor may stage more operations. | securityPool.isEscalationResolved() is false; valid self-target for withdrawal or target adjustment, nonzero operation value (at least the pool security multiplier for a target adjustment), and timeout from 1 second through 5 minutes. A committed bounty of at least getRequestPriceCostAttoEth() covered by msg.value, buffered report funding, matching REP, and token approvals are required only when this call opens a new report. The caller must accept any positive unused-ETH refund. |
Records the operation (0 liquidation debt in attoETH, 1 withdrawal in attoREP, 2 target backing factor in BPS), executes immediately with a fresh price, or attaches it to a bounded pending settlement batch and opens a report when required. A newly accepted target change consumes any older active target change for the same vault with success=false and Backing target superseded, freeing its settlement slot. When a report opens, the whole committed bountyAttoEth is retained as the settler reward regardless of the inclusion-block cost. If unused ETH is positive, the final caller refund uses a low-level callback; rejection rolls back the entire transaction, including any queueing, immediate execution, or newly opened report. |
StagedOperationQueued, possibly PriceRequested, then ExecutedStagedOperation; authoritative CoordinatorStateCheckpoint records |
requestPrice(proposedRepPerEthPrice, requestedInitialAttoWeth, bountyAttoEth) with report funding |
Anyone when no fresh price or report is pending | Cached price stale; no pending report; nonzero proposed REP/ETH price, a committed bounty of at least getRequestPriceCostAttoEth() covered by msg.value, and funding and approvals for at least the configured priority report plus the larger of the base-fee and open-interest WETH reports, plus matching REP. Zero requested WETH uses the minimum; a larger request voluntarily increases the initial report. The caller must accept any positive excess-ETH refund. |
Opens and atomically funds a fresh WETH/REP report without staging a new operation, retains the whole committed bounty as the settler reward, then refunds any ETH above the bounty through a low-level caller callback. Callback rejection rolls back the report and initial position. | PriceRequested and CoordinatorStateCheckpoint |
executeStagedOperation(operationId) |
Anyone | Operation exists. Expired cleanup requires no valid price; a non-expired operation requires a fresh coordinator price. Lifecycle failures are emitted rather than retried. | Consumes an expired operation and releases its delegated reservation without requiring a valid price. Otherwise, consumes and attempts the active operation using the current fresh price. Price-report funding is independent of the operation's notional; the downstream operation applies its own protocol bounds. | ExecutedStagedOperation, either LiquidationApprovalConsumed or LiquidationApprovalReleased for a delegated liquidation, and CoordinatorStateCheckpoint |
expireStagedOperation(operationId) |
Anyone | Operation exists and its settlement-plus-validity window has elapsed. | Permissionlessly consumes an expired operation and releases its liquidation reservation without requiring a valid oracle price. | ExecutedStagedOperation, LiquidationApprovalReleased for a delegated liquidation, and CoordinatorStateCheckpoint |
recoverSettledPendingReport() |
Anyone | A pending report ID exists and its stored OpenOracle storedGame(reportId).settlementTimestamp is nonzero. |
Clears a pending report whose normal callback path did not clear coordinator state, consumes every live operation attached to that report, and releases each delegated-liquidation reservation. Operations that were active but outside the bounded pending callback batch remain active. | PendingReportRecovered, failed ExecutedStagedOperation for each live attached operation, LiquidationApprovalReleased for each attached delegated liquidation, and CoordinatorStateCheckpoint |
openOracleCallback(...) |
Configured OpenOracle only |
Callback report matches the pending report; excessive settlement basefee, a saturated uint24 report counter, an uneconomic final history record at its recorded base fee plus configured priority fee, a stale report, or zero values reject the price after clearing pending report state. |
A valid settlement updates the price and auto-executes the bounded pending batch. A terminally rejected settlement consumes the pending batch and releases every liquidation reservation. | PriceReported or PriceReportRejected; operation execution events; authoritative CoordinatorStateCheckpoint records |
setLiquidationApprovalRegistry(registry) |
Coordinator deployment factory only | Registry is nonzero and no registry was previously installed. | Binds the coordinator-local approval registry once. | No event; deterministic factory deployment and the public getter identify the registry. |
setSecurityPool(pool) |
Anyone while securityPool remains zero; normal factory deployment calls atomically |
Current securityPool is zero; the argument itself is not required to be nonzero. |
A nonzero value binds the pool permanently. A zero value emits and checkpoints zero but leaves the setter callable. Normal factory deployment supplies the nonzero canonical pool before returning the coordinator. | SecurityPoolSet and CoordinatorStateCheckpoint |
setRepEthPrice(price) |
Configured nonzero SecurityPool only |
Caller equals the configured pool. | Seeds the coordinator's price value, including zero, for inherited child state. | RepEthPriceSet and CoordinatorStateCheckpoint |