OpenOracle Integration

OpenOracle Role

The generic oracle lifecycle comes first. Statoblast's coordinator calls OpenOracle and becomes the initial reporter, then consumes the settled result through OpenOracle's callback.

OpenOracle atomically creates and funds a report for a token pair. Only its state hash is stored for an active game; the full preimage is emitted as packed report data. Later reporters can dispute by posting the contract-required replacement amounts. A dispute is valid only while currentTime < reportTimestamp + settlementTime; settlement becomes valid at equality, when a dispute is already too late. When a callback contract is configured, settlement calls that contract with the settled amounts.

The event-stream reference owns packed-log decoding, chronological replacement, hash verification, and settlement-block reconstruction.

In this repository the pair is WETH as token1 and REP as token2. The coordinator converts the callback amounts into the following REP per ETH price:

This raw-amount ratio is a REP/ETH price because the configured WETH and REP contracts both use 18 decimals. The coordinator does not normalize token decimals inside the callback.

After the coordinator accepts a settlement, that accepted WETH/REP report becomes a REP/ETH coordinator price. The price is reusable only while it remains inside the freshness window; operation volume is not metered by the accepted report.

Four coordinator terms drive the rest of the integration behavior: staged operation, fresh price, liquidation threshold, and report liquidity.

A staged operation is a liquidation, REP withdrawal, or allowance update queued behind the coordinator until it can use a fresh price, meaning a settled coordinator price still inside PRICE_VALID_FOR_SECONDS, currently a five-minute cache window.

For liquidations, the relevant boundary is the liquidation threshold. A staged liquidation can execute only when the current REP/ETH price is strictly above that threshold and at least the configured liquidation distance beyond it, with that extra margin currently set by minLiquidationPriceDistanceBps.

OpenOracle disputes scale with report liquidity. The coordinator computes the initial WETH side from request-time inputs, and the sponsor may request more. The sizing section owns the derivation; ORACLE-A1 owns the security boundary.

Statoblast Integration

In Statoblast, every pool gets its own coordinator. That keeps pending operations, freshness windows, and callback state local to one pool instead of sharing one global queue across the protocol.

OpenOraclePriceCoordinator is deployed with an immutable OpenOracle address. Users request or execute liquidation, REP-withdrawal, and security-bond-allowance operations through the coordinator. When a fresh REP/ETH price is needed, the coordinator stages the requested operation and later calls the configured security pool to perform it.

Deployment is per pool. SecurityPoolFactory asks PriceOracleManagerAndOperatorQueuerFactory for a fresh coordinator for each origin or child security pool, wiring it to the shared OpenOracle, shared WETH, and that universe's REP token. SecurityPoolDeployer passes the coordinator into the pool, and the factory then calls setSecurityPool once with that nonzero pool. Only the configured pool may seed the coordinator's inherited lastPrice; execution instead starts from a user call to the coordinator, which targets that configured pool's operation methods. Child pools inherit the parent's last price as a starting value, but freshness is still controlled by the coordinator's settlement timestamp and validity window.

The factory contract still uses its older internal name, but it is the active deployment path for OpenOraclePriceCoordinator instances.

If the cached price is valid, the coordinator attempts immediate execution after staging the operation record. Liquidation-specific gates, snapshot staleness, zero-effect withdrawals, or downstream pool checks can still consume the operation as a failed staged operation. Otherwise the coordinator can create one OpenOracle report and attach up to four staged operations to the settlement callback. Additional staged operations remain active but outside the auto-executed callback batch; if the fresh price remains valid and they have not expired, they require a later manual executeStagedOperation call.

Staged operation inputs are constrained before any oracle report is requested. Liquidation and withdrawal amounts must be non-zero, allowance updates may set zero, validForSeconds must be positive and no more than five minutes, liquidation must target a different vault, non-liquidation operations must target the caller's own vault, and staging is disabled after the security pool's local escalation has already resolved. Same-vault liquidation is rejected with Caller bad before the coordinator requests or uses an oracle report.

Report funding is caller supplied. The coordinator computes requestPriceEthCost, the caller-funded request bounty, from the current base fee, the callback gas limit, and the gas the coordinator expects to spend on report submission and processing:

If a cached price is usable, the staged operation pays no oracle request cost and unused ETH is refunded. If a new report is needed, only the first pending settlement slot retains the request cost; requestPrice(proposedRepPerEthPrice, requestedInitialWeth) forwards exactly that bounty to OpenOracle and refunds any excess. That call also submits the initial WETH/REP report inside the same transaction, so the refresh sponsor funds the ETH bounty plus the initial OpenOracle position up front. The coordinator, not the sponsor, is recorded as the initial reporter. Disputes can replace that position. At settlement OpenOracle credits the final position to the final reporter; the callback supplies the accepted amounts to the coordinator but does not transfer them.

Both public request paths refund only a positive unused or excess ETH amount, using a low-level call to the caller. A contract caller must accept that callback. If it rejects the refund, the entire transaction reverts: operation staging or immediate execution and any newly opened report roll back together with the refund.

The coordinator refuses requestPrice(proposedRepPerEthPrice, requestedInitialWeth) while its cached price is still fresh, so callers cannot open a redundant pending report on top of a usable price. Once the cached price has gone stale and a new report is pending, only the original pendingReportSponsor can queue more staged operations against that in-flight settlement. Those follow-up queues pay no additional ETH join fee, and other callers must wait for settlement before staging their own operations. Every successful dispute replaces the current report and restarts its settlement window. The economic tradeoffs section owns the resulting cost and liveness analysis.

The money flow is easiest to follow if each role is separated. The triggering caller pays the ETH request bounty, supplies the initial WETH/REP, and becomes the queue owner for that stale refresh window. The coordinator transfers and approves those assets, calls OpenOracle, and becomes the initial reporter. The eventual settler still receives the settler reward, and disputes can replace the initial report before settlement.

A successful correction swaps the wrong current report at an unfavorable rate, replaces its reporter, and makes the correction value available to the disputer if that corrected position later exits or settles. The wrong reporter therefore bears the corresponding loss on its posted WETH/REP position, subject to OpenOracle fees and integer rounding; no queued operation or pool exposure funds that profit.

The application proposes a REP/ETH price from the coordinator's cached lastPrice whenever it is non-zero, even after that price becomes stale. If no cached price exists, it requests a live WETH-to-REP Uniswap quote and does not substitute a fixed fallback. The coordinator enforces a non-zero proposed price, computes the request block's minimum WETH amount, selects the greater of that minimum and requestedInitialWeth, and derives REP amount2 with ceiling division. It does not certify the proposal; the correction trade is what makes a bad price costly to its reporter.

Worked example using a market snapshot taken at 2026-07-09 09:49:35 UTC: at that moment Ethereum base fee was 69,594,403 wei per gas (0.069594403 gwei), ETH traded at $1,750.34, and REP traded at $0.792188 or 0.00045231 ETH per REP. The USD quotes and the ETH-per-REP quote are independently rounded snapshot values, so reconstructing one from the other may differ by a few basis points. With the coordinator defaults used in this documentation revision, gasConsumedOpenOracleReportPrice = 100,000, gasConsumedSettlement = 1,000,000, and MAX_PENDING_SETTLEMENT_OPERATIONS = 4, the callback gas limit is:

The refresh sponsor's coordinator call supplies a proposed REP/ETH price and passes requestedInitialWeth = 0. For this worked example, the pool has no open interest, so the coordinator atomically computes and posts the gas-based minimum WETH amount and its matching REP amount2. At the snapshot base fee of 69,594,403 wei, the minimum side is 0.005621086396153847 WETH. Using the snapshot price of 2,210 REP/ETH gives:

If no dispute replaces the report, settlement credits the full REP and WETH amounts to the coordinator as current reporter in OpenOracle's internal balances. The reporter withdraws those balances separately. The entire ETH request bounty is configured as the settler reward and is likewise credited to the settler's internal ETH balance; OpenOracle 0.2.0 has no separate reporter ETH reward. For coordinator-created reports, the coordinator is the initial reporter and forwards its withdrawable WETH and REP balance to the request sponsor during the settlement callback. If a disputer is the final reporter, that disputer receives the final position; the coordinator instead forwards only the prior-reporter swap proceeds credited to its own internal balances. The recovery path performs the same coordinator-owned withdrawal if the callback failed.

Escalation-game REP deposits are the exception to the staged callback path. When the pool has active security-bond allowance, depositToEscalationGame requires a fresh coordinator price and reverts if it is stale. After previewing the accepted REP deposit, the pool uses lastPrice for the post-transfer vault and pool coverage checks instead of queueing the deposit behind a report.

Security Model and Guardrails

Statoblast uses the oracle to preserve solvency accounting around ETH obligations backed by REP. The ORACLE-A1 section owns the required economic assumption. Locally, operations that can change REP backing or security-bond exposure must use a fresh, economically contestable REP/ETH price and pass local coordinator checks before they can affect the pool.

• PRICE_VALID_FOR_SECONDS limits accepted prices to a five-minute cache window.
• The initial report targets a configured correction profit after modeled gas and fees.
• Pool execution functions reject direct user calls: withdrawals, liquidations, and allowance changes can be performed only by the configured coordinator while its price is still valid.
• Liquidations use a queue-time snapshot and fail if target allowance changes or ownership decreases before execution.
• Liquidations must remain at least minLiquidationPriceDistanceBps beyond the computed liquidation threshold.
• The callback rejects zero reports, computed zero prices, unexpected report ids, and settlements during excessive base fee.

The minimum side is WETH, so the coordinator can calculate it directly from the current block's base fee. In the conservative correction direction, the true REP/ETH price is (1 + targetError) times the reported price. Correcting that report releases the fraction (targetError - fees) / (1 + targetError) of the WETH position before gas. The report multiplies one modeled dispute's base-fee gas cost by the required profit buffer and divides by that correction-profit fraction.

No REP price, assumed gas price, expected REP price movement, pool open interest, or individual protected-operation notional enters the minimum initial WETH calculation. Pool open interest instead raises escalationHalt through ceil(completeSetCollateralAmount / OPEN_INTEREST_DIVIDER), with OPEN_INTEREST_DIVIDER = 100. The sponsor may pass zero to use that minimum or request a larger initial WETH amount. The coordinator sets initialWethReport = max(minimumToken1Report(), requestedInitialWeth), sets OpenOracle currentAmount1 to that selected amount, and derives amount2 = ceil(initialWethReport * proposedRepPerEthPrice / 1e18) inside the same transaction. If that price is wrong by at least the configured target error (initially five percent), the resulting correction opportunity is designed to pay the modeled base-fee gas cost with the configured Open Oracle Security multiplier after the configured OpenOracle fees.

Coordinator construction requires positive dispute gas units, a target error no greater than 100%, an Open Oracle Security multiplier of at least 1x, and combined OpenOracle fees below the target error. The factory stores its deployment configuration, so an invalid domain causes coordinator deployment to revert. Moving the target closer to the fee floor increases required WETH sharply; increasing the Open Oracle Security multiplier increases it linearly. A larger target reduces required WETH but tolerates a wider error before the modeled correction incentive applies.

At 30 gwei, the modeled gas cost is 0.009 ETH. After the 10x Open Oracle Security multiplier and the worst-direction five-percent correction fraction after fees, the minimum gas-based report is 2.423076923076923077 WETH, producing an initial-report-derived halt of 24.230769230769230770 WETH at the configured 10x halt multiplier. One percent of pool open interest replaces that halt only when it is larger.

Once a REP/ETH price is fresh, the coordinator relies on local operation guards: withdrawals must have an effect, liquidations must pass their queue-time snapshot checks and liquidation-distance check, and allowance updates execute against the current vault state.

Callback Rejection and Recovery

OpenOracle settles with a low-level callback whose success is intentionally not stored or emitted. It does not automatically undo settlement when the callback fails. 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 OpenOracle report can still be settled while the coordinator remains pending. If the settlement transaction cannot leave enough gas headroom after attempting the callback, OpenOracle reverts settlement with InvalidGasLimit instead; in that case the report is not settled yet and coordinator recovery is not available.

Coordinator-level price rejections are separate from low-level callback failures. After a callback successfully enters the coordinator, a settlement with base fee above the request-time cap, zero amounts, or a computed zero price clears the pending id, emits PriceReportRejected, and does not update the price cache or replay pending operations. Those pending settlement operations remain queued for a later valid price report. If the pending settlement list is empty, another staged request can fund a replacement report. If pending settlement operation IDs still remain, an operator or user must call direct requestPrice(proposedRepPerEthPrice, requestedInitialWeth) with the ETH bounty and initial-report funding, then let that replacement report settle. When OpenOracle has already settled but the coordinator is still pending because the low-level callback did not complete, anyone can call recoverSettledPendingReport. Recovery clears the pending report, resets the settlement base-fee cap, and consumes only pendingOperationSlotId without treating it as a successful price update. Queue bookkeeping can still leave other staged operations active; those operations need a later valid price path, for example a direct requestPrice(proposedRepPerEthPrice, requestedInitialWeth) call that opens a new report and atomically submits its initial WETH/REP position before successful settlement.

Intentional Economic Tradeoffs

The ORACLE-A1 section owns the normative notional boundary and loss allocation. Operationally, the coordinator maintains no notional exposure budget: one fresh price may authorize multiple otherwise-valid operations.

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, so repeated disputes can delay settlement. Each extension incurs transaction execution and must fund the contract-specified replacement position. Under ordinary non-dust parameters, protocol fees and the required position also accumulate; integer flooring can leave dust-sized rounds unchanged before the escalation halt. There is intentionally no absolute coordinator deadline: the protocol does not claim liveness against a participant with unbounded capital who is willing to keep submitting and funding disputes. That availability model is separate from the dynamic initial WETH sizing rule and is not a bounded-liveness invariant.

Assumption Boundary and Attack Model

The equations below stress-test failure of ORACLE-A1: an attacker excludes correcting transactions until a bad REP/ETH report can settle and enable an outside payoff. They are not a contract-enforced exposure cap.

OpenOracle's inclusion analysis models an attacker who posts a wrong price and pays for censorship until the report can settle. For linear payoffs the settle payoff scales with price error, but Statoblast's most relevant liquidation payoff is binary: the attacker wins a fixed payoff only if the manipulated REP/ETH price is strictly above the liquidation threshold and satisfies the configured liquidation distance check. OpenOracle's inclusion analysis notes that binary payoffs therefore replace the linear settle payoff with externalPayoff, while keeping the same censorship-spend term.

The minimal attack story is: an attacker posts a manipulated REP/ETH report, an honest reporter would normally dispute it, and the attacker must keep that honest dispute or settlement correction out until the bad report can settle. The payoff is binary because the liquidation either becomes executable or it does not. The cost side scales with oracleReportLiquidity, the report's WETH-denominated liquidity; censorshipRate, the modeled per-step pressure needed to keep honest activity out; and censorshipDuration, how long the attacker must maintain that pressure.

In the equations below, price errors are fractions of the honest price, externalPayoff is the attacker's outside ETH-denominated payoff, and oracleLiquidityRatio compares report liquidity with that payoff. The bound is useful when the denominator is large enough that delaying honest correction costs more than the liquidation can pay.

The first boundary is how far the manipulated price must move before the liquidation can execute. The distance guard discounts the honest price, then the execution threshold and reported price error are measured against that honest baseline. The formulas in this attack model are continuous approximations for reasoning about payoff and censorship cost; the contract guard below them shows the integer check that actually gates staged liquidation execution.

The attack model separates attacker payoff from delay cost. The payoff is binary: only a price strictly above the liquidation threshold and far enough past the guarded distance unlocks externalPayoff; everything else unlocks nothing. The censorship cost grows with duration, the dispute barrier, and the report liquidity honest reporters can use.

The final bound is how long censorship would need to remain cheap for the attack to be attractive. The safety duration shrinks as the censorship rate and liquidity ratio grow.

The controls below parameterize this stress test; they do not replace ORACLE-A1.

• Censorship and delay: settlementTime sets the correction window; the sizing section owns initial-position profitability.
• Binary threshold attacks: staged liquidations must satisfy minLiquidationPriceDistanceBps = 1000, so $\frac{\mathrm{currentPrice}-\mathrm{thresholdPrice}}{\mathrm{currentPrice}}$ must be at least 10% rather than barely crossing the threshold.
• Settlement base-fee boundary: the coordinator records a request-time max settlement base fee and rejects the callback only when settlement base fee is greater than that cap. Equality is accepted. With the default 10x Open Oracle Security multiplier and 3x maxSettlementBaseFeeMultiplierBps, correction profit at the configured target error remains 10 / 3 times the one-dispute gas cost at the largest admitted settlement base fee. That relationship is a deployment assumption, not a constructor invariant: the constructor checks each multiplier's lower bound but does not require the settlement cap to remain below the Open Oracle Security multiplier.
• Settlement validation scope: the callback does not recompute minimumToken1Report() from settlement base fee and does not compare the final price with an external truth source. It checks the request-time base-fee cap, requires nonzero final WETH and REP amounts and a nonzero integer REP/ETH ratio, then records that ratio. The cap is a rejection boundary, not proof that an accepted price is externally correct; ORACLE-A1 owns the remaining assumption.
• Callback scope: only up to four operations are auto-executed from one settlement callback. Additional staged operations require a later manual execution while the price remains fresh.
• Freshness: prices expire after PRICE_VALID_FOR_SECONDS = 5 minutes, so delayed operations cannot reuse old reports indefinitely.

The dynamic-programming section of OpenOracle's inclusion analysis remains a useful template for modeling censorship and delay, but it is not a proof that outside operation exposure is bonded. In this integration the escalation variable is WETH. Before escalationHalt, OpenOracle requires min(floor(oldAmount1 × multiplier / 100), escalationHalt). With the configured multiplier of 115, prior token-one amounts from one through six wei therefore remain unchanged rather than growing; seven wei is the first amount that increases. At or above the halt, each dispute instead requires oldAmount1 + 1, adding one atomic WETH unit. The selected initial amount is max(minimumToken1Report(), requestedInitialWeth), and the selected initial amount determines one halt candidate. The other is ceil(completeSetCollateralAmount / OPEN_INTEREST_DIVIDER), and escalationHalt takes their maximum. See Dynamic Report and Escalation Threshold.

OpenOracle Parameters Used

The integration depends on the OpenOracle fields below. This is the canonical current-value table for coordinator and OpenOracle parameters; the Statoblast whitepaper routes readers here instead of maintaining a second copy.