OpenOracle integration reference

Why Statoblast uses OpenOracle

Statoblast needs a REP/ETH price to enforce live backing and convert price-independent REP capacity ownership into ETH minting capacity. Price-gated operations include REP withdrawals, liquidations, and certain Escalation Game deposits. A stale or easily manipulated price could allow an unsafe withdrawal or make a healthy vault appear liquidatable. A price change updates aggregate ETH capacity arithmetically and never requires a vault scan.

Statoblast therefore uses OpenOracle to obtain a fresh, economically contestable REP/ETH price. OpenOracle does not prove a price by consulting a trusted source. Instead, a reporter posts a WETH/REP position, and other participants can replace an inaccurate report through an economically motivated correction trade.

Statoblast configures WETH as token1 and REP as token2. Keeping WETH on the exact side lets the coordinator size the report directly from ETH-denominated gas costs without first assuming a REP/ETH conversion price. When a report settles, the coordinator converts the settled token amounts into REP per ETH:

This raw-amount ratio is valid because the configured WETH and REP contracts both use 18 decimals. The coordinator does not normalize token decimals in the settlement callback.

An accepted report becomes the coordinator's cached REP/ETH price. Its freshness window is one hour on Sepolia and five minutes on other chains. The window starts at settlement eligibility (the final report timestamp plus settlementTime), not when settle is called, and lastSettlementTimestamp records that start. A late settlement therefore cannot extend the life of a price that was frozen earlier. The coordinator does not meter how much operation volume uses that price during the freshness window.

Optional upstream capabilities

The vendored openPunt revision adds three independent report flags. They extend what a report can record or permit; they do not change reports that omit them. Statoblast's per-pool coordinator still submits flags 6 for block-number clocks and 7 for timestamp clocks, while the chaos bot's direct reports use 7. None of those configurations enables a new flag, so existing report economics and settlement behavior remain unchanged.

• Store settlement eligibility. OpenOracle records the current settlement-eligibility clock value when a report is created and refreshes it after each dispute. A lightweight application can read that deadline without storing the complete report preimage. The application must still identify whether the report uses timestamps or block numbers.
• Flexible escalation. A disputer may choose any token-one amount from the ordinary required escalation amount through the configured halt. This exposes larger, fully funded correction positions and can move a game to its halt sooner. The report's halt and all dispute validation still apply.
• Fees only at the halt. Reporter and protocol fees are zero before the prior position has reached the escalation halt and apply once the prior position is at that halt. A configuration can therefore make early corrections cheaper while retaining a recurring cost for continued disagreement at the halt.

These flags change operational data and correction incentives, not the meaning or external correctness of a settled price. An integration that enables them must include their effects when sizing positions, monitoring deadlines, and evaluating the participation assumptions in the security model. The exact vendored source and build profile are recorded in the OpenOracle provenance record.

Integration architecture

Every security pool has its own OpenOraclePriceCoordinator. The coordinator connects users, the pool, and the shared OpenOracle instance. It keeps the pool's cached REP/ETH price, pending report state, staged-operation queue, and settlement callback state. Keeping this state per pool prevents one pool's pending report or freshness window from becoming a protocol-wide queue.

OpenOraclePriceCoordinator is deployed with an immutable OpenOracle address. For each origin or child security pool, SecurityPoolFactory asks PriceOracleManagerAndOperatorQueuerFactory for a fresh coordinator wired to the shared OpenOracle instance, shared WETH, and that universe's REP token. SecurityPoolDeployer passes the coordinator to the pool, after which the factory calls setSecurityPool once with the nonzero pool address.

Only the configured pool may seed the coordinator's inherited lastPrice. A child pool inherits the parent's numeric price as a starting value, but its settlement timestamp remains zero, so that number is unusable until the child accepts its own report. The coordinator's validity window then determines whether the child price can be used.

Price request lifecycle

Liquidations, REP withdrawals, and vault target changes begin at the pool's coordinator. The coordinator validates and stages the operation, then uses a cached price or opens an OpenOracle report. REP deposits use the vault's saved target directly at the pool; the first deposit initializes it. Exact target permissions and guards are in the SecurityPool reference.

1. Validate and stage the operation. The coordinator checks the caller, target vault, requested amount, and validity window before any report is requested.
2. Check the cached price. If the cached REP/ETH price is fresh, the coordinator attempts the operation immediately.
3. Open a report when the price is stale. The refresh sponsor supplies the request bounty and initial WETH/REP position, and the coordinator creates the report as its initial reporter.
4. Allow corrections. Other participants may replace the report by posting the position required by OpenOracle. Every valid replacement installs a new reporter and restarts the settlement window.
5. Settle the current report. When its settlement deadline is reached without another dispute, OpenOracle settles the report and calls the coordinator.
6. Accept or reject the price. The coordinator validates the report identity, history, economics, amounts, and settlement-time base fee before updating the cache.
7. Execute queued operations. An accepted fresh price allows the coordinator to attempt the queued pool operations, each of which still performs its own current safety checks.

The complete flow is operation requested → cached price checked → immediate execution or report opened → report corrected or left unchanged → report settled → coordinator accepts or rejects → operation safety checks → execution.

Staging rules

• Liquidation and withdrawal amounts must be nonzero.
• validForSeconds must be positive and no greater than five minutes.
• A liquidation's receiver vault must differ from its target vault. The operator may be the target; operator identity is not used as a Sybil-resistant boundary.
• Non-liquidation operations must target the caller's own vault.
• Staging is disabled after the security pool's local Escalation Game has resolved.

A liquidation whose receiver equals its target is rejected with Receiver is target before the coordinator requests or consumes an oracle report. A self-receiving operator uses a zero approval ID; a distinct receiver requires a bounded approval.

Execution batches

If a cached price is valid, the coordinator stages the operation record and then attempts immediate execution. Liquidation gates, a stale queue-time snapshot, a zero-effect withdrawal, or a downstream pool check may still cause the staged operation to fail and be consumed.

When a new report is needed, one settlement callback can automatically attempt up to MAX_PENDING_SETTLEMENT_OPERATIONS = 4 operations. Additional staged operations remain active outside the callback batch. If they have not expired and the accepted price remains fresh, they can be executed later with executeStagedOperation.

Escalation Game deposits

Escalation Game REP deposits do not use the staged callback path. When a pool has active capacity ownership, depositToEscalationGame requires an already-fresh coordinator price and reverts when the price is stale. After previewing the accepted REP deposit, the pool uses lastPrice for the post-transfer vault and pool coverage checks.

Funding and report ownership

Report funding is caller supplied. The coordinator's getRequestPriceCostAttoEth() getter calculates the minimum request bounty from the current base fee, callback gas limit, and the coordinator's own report processing budget:

Every request path takes an explicit bountyAttoEth. When a call opens a report, the committed bounty must cover getRequestPriceCostAttoEth() at inclusion and msg.value must cover the bounty. The coordinator then retains the whole bounty as the settler reward. If a cached price is usable, nothing is retained and the ETH is refunded. If a report is needed, only the first pending settlement slot retains the bounty. requestPrice(proposedRepPerEthPrice, requestedInitialAttoWeth, bountyAttoEth) forwards exactly the bounty to OpenOracle and refunds any ETH above it. The same transaction submits the initial WETH/REP position, so the refresh sponsor funds both the ETH bounty and report position up front.

Both public request paths refund only a positive unused or excess amount by making a low-level native-ETH call to the caller. A contract caller must accept that callback. If it rejects the refund, the whole transaction reverts, including operation staging, immediate execution, and any report opened in the same transaction.

Sponsor lane

The coordinator refuses a direct requestPrice call while the cached price is still fresh, preventing a redundant report from being opened over a usable price. Once the price is stale and a report is pending, only the original pendingReportSponsor may add operations to that in-flight settlement. Those follow-up operations pay no additional join fee; other callers must wait until the report finishes.

Every successful dispute replaces the current report and restarts its settlement window. The resulting liveness consequences are described under Economic tradeoffs and limits.

Report sizing and correction incentives

OpenOracle's correctness depends on profitable arbitrage correcting inaccurate prices. The coordinator sizes each report so that correcting an error at or above the target remains profitable after modeled dispute costs and OpenOracle fees, with the configured security margin.

In the conservative correction direction, the true REP/ETH price is (1 + targetError) times the reported price. Before gas, correcting that report releases the fraction (targetError - fees) / (1 + targetError) of the WETH position. The sizing formula therefore multiplies the modeled gas cost of one dispute by the security multiplier and divides by that correction-profit fraction.

The coordinator sizes the initial WETH position to make correction economically profitable when the price deviates enough. Every dispute resets the oracle's reporting clock, so repeated disputes can delay settlement indefinitely. The position therefore also accounts for pool open interest. The minimum initial WETH position combines three inputs:

1. Request-block base fee: a report sized from the current block.basefee.
2. Lineage priority-fee assumption: a separate report sized from the immutable initialReportPriorityFeeAttoEthPerGas.
3. Pool open interest: a floor equal to one percent of the pool's current settlement collateral.

The priority-fee report is added to the larger of the base-fee report and the open-interest report. The sponsor may use this minimum or request a larger initial WETH position.

No REP price, expected REP price movement, or individual protected-operation notional enters the minimum WETH calculation. The immutable priority fee is selected when the origin pool is created and inherited unchanged by its child pools. Open interest contributes ⌈settlementCollateralAttoEth / OPEN_INTEREST_DIVIDER⌉, with OPEN_INTEREST_DIVIDER = 100, before the priority-derived report is added.

The coordinator sets initialWethReportAttoEth = max(minimumToken1ReportAttoEth(), requestedInitialAttoWeth), uses that value as OpenOracle's currentAmount1, and derives amount2 = ⌈initialWethReportAttoEth * proposedRepPerEthPrice / 1e18⌉ in the same transaction.

Formula inputs

Construction bounds and parameter effects

Coordinator construction requires:

1. positive dispute gas units
2. a target error no greater than 100%
3. an Open Oracle Security multiplier of at least 1x
4. combined OpenOracle fees below the target error

It also rejects a priority fee whose constant-derived report would consume the reserved uint128 report or escalation-halt capacity; half of that capacity remains available for the dynamic base-fee or open-interest component. The factory stores its deployment configuration, so an invalid parameter domain causes coordinator deployment to revert.

Moving the target error toward the fee floor increases the required WETH sharply. Increasing the Open Oracle Security multiplier increases the required WETH linearly. A larger target error reduces the required position, but permits a wider error before the modeled correction incentive applies.

At a 30 nanoETH base fee and a configured 10 nanoETH priority fee, the modeled gas cost is 0.012 ETH. After applying the 10x Open Oracle Security multiplier and the worst-direction five-percent correction fraction after fees, the minimum report with 100 WETH of open interest is 3.230769230769230770 WETH. With the configured 10x halt multiplier, the initial-report-derived escalation halt is 32.307692307692307700 WETH.

Settlement validation, rejection, and recovery

Low-level callback failure

OpenOracle invokes the coordinator through a low-level callback whose success is intentionally neither stored nor emitted. A failed callback does not automatically undo an otherwise valid OpenOracle settlement. The coordinator accepts callbacks only from the configured OpenOracle and only for the current pending report id. If those checks revert inside the low-level call, the report can still settle while the coordinator remains pending.

If the settlement transaction cannot retain enough gas headroom after the callback attempt, OpenOracle reverts settlement with InvalidGasLimit. In that case, the report has not settled and coordinator recovery is not yet available.

Coordinator settlement validation

A callback that successfully enters the coordinator can still produce a rejected price. The coordinator clears the pending report id, emits PriceReportRejected, and leaves the price cache unchanged when any of the following conditions holds:

• the settlement base fee exceeds the request-time cap, which is the base fee implied by the committed bounty scaled by maxSettlementBaseFeeMultiplierBps;
• storedGame(reportId).numReports is saturated at the uint24 maximum, reported as Counter saturated;
• the final history record's WETH amount is too small to support another dispute at that record's base fee plus the configured priority fee, reported as Report uneconomic;
• settlement happens after the freshness window measured from settlement eligibility has already closed, reported as Report stale;
• either settled token amount is zero; or
• the integer REP/ETH calculation produces a zero price.

When dispute tracking is enabled, OpenOracle records each report block's base fee. If the report counter is not saturated, the coordinator selects history index numReports - 1 and checks the final WETH position against the configured security-sizing formula using that record's base fee plus the configured priority fee. It also enforces the request-time settlement base-fee cap before recording the final ratio.

These checks establish only that the final WETH position meets the modeled security floor and that the callback data is structurally acceptable. They do not prove that the accepted price is externally correct, that an independent corrector exists, or that a correcting transaction will obtain inclusion.

Rejected-price cleanup

A rejected report does not replay its pending settlement operations. Instead, the coordinator terminally fails every operation attached to that report, removes it from the active and pending sets, and releases any liquidation-approval reservation exactly once. A caller must stage a new operation to try again with a later price.

Recovering a settled report after callback failure

When OpenOracle has already settled but the coordinator remains pending because the low-level callback did not complete, anyone can call recoverSettledPendingReport. Recovery clears the pending report, sponsor, and base-fee cap; withdraws coordinator-owned OpenOracle balances; and terminally fails every pending settlement operation attached to the report.

Recovery does not treat those operations as successful and does not accept the report as a new price. Each affected liquidation reservation is released during the same cleanup, so no approval quota remains locked.

Economic tradeoffs and limits

No accepted-price notional budget

The coordinator does not maintain a notional exposure budget. One accepted price may authorize multiple otherwise-valid operations during its freshness window. The report position is therefore an economic correction incentive, not a bond sized to the exact aggregate payoff of every operation that may use the price.

Unbounded funded delay

The stale-price refresh sponsor retains the staging lane while its report is pending. A timely valid dispute replaces the reporter and restarts OpenOracle's settlement clock. Repeated disputes can therefore delay settlement. Each extension requires a transaction and the contract-specified replacement position. Under ordinary non-dust parameters, fees and required position size also accumulate.

There is intentionally no absolute coordinator deadline. The protocol does not claim liveness against a participant with unbounded capital that is willing to keep funding valid replacements. This availability model is separate from the dynamic initial WETH sizing rule and is not a bounded-liveness invariant.

Dispute escalation after the halt

In this integration, WETH is the escalation variable. Before escalationHalt, OpenOracle requires min(⌊oldAmount1 × multiplier / 100⌋, escalationHalt). With the configured multiplier of 115, integer flooring leaves token1 amounts from one through six attoETH unchanged; seven attoETH is the first amount that grows. At or above the halt, each replacement instead requires oldAmount1 + 1, adding one attoETH of WETH.

The selected initial amount is max(minimumToken1ReportAttoEth(), requestedInitialAttoWeth). One escalation-halt candidate is that amount multiplied by the configured halt multiplier. The other is ⌈settlementCollateralAttoEth / OPEN_INTEREST_DIVIDER⌉. The actual halt is the greater of the two, as shown in Dynamic Report and Escalation Threshold.

External-payoff and censorship model

This stress test models an attacker that posts a manipulated REP/ETH report, excludes a correcting transaction until settlement, and receives an outside payoff if the accepted price makes a liquidation executable. It is a continuous approximation for reasoning about incentives, not a contract-enforced exposure cap or a guarantee that a correction will obtain inclusion.

The payoff is binary: the attacker receives externalPayoff only when the manipulated price is strictly above the liquidation threshold and far enough beyond the configured liquidation-distance guard. The cost side grows with the report's WETH-denominated liquidity, the duration of censorship, and the price error above the modeled honest-dispute barrier.

honestDisputeBarrierFraction is a model input that abstracts the cost an honest corrector must overcome before the model assigns censorship pressure. It is not a coordinator field or a separately configured OpenOracle parameter. The calculator's illustrative 1.1% default is only the fixed-fee floor: the configured 1% protocol fee plus 0.1% reporter fee. A deployment analysis must replace it with a full scenario-specific barrier. OpenOracle's report-cost derivation also depends on volatility over the settlement horizon and expected loss under adversarial disputes; gas, priority fees, price impact, and capital lockup can raise the barrier further.

The derived duration threshold applies only when the manipulated price unlocks the outside payoff. It asks how many abstract model steps are required for censorship cost to reach a chosen multiple of that payoff. targetGriefRatio is the desired attacker loss after subtracting externalPayoff, divided by that payoff. A value of 1 therefore targets censorship cost equal to twice the payoff, leaving a modeled net loss equal to the payoff. One censorship step is the interval over which the chosen censorshipRate and report-liquidity cost accrue; it is not inherently a block, second, or dispute round. A deployment analysis must define that time mapping before applying the threshold. When a payoff is unlocked, the result is unbounded if the modeled censorship rate is zero; otherwise it shrinks as price-error pressure or report liquidity relative to the outside payoff increases.

OpenOracle parameters used

Use this page's coordinator parameters for source constants and definitions, and deployment verification for deployed getter values. The OpenOracle explanation provides the shorter conceptual path.