# Integrate openOracle — callbacks, gas, parameters > Wire openOracle into your contracts: deployments and token support, v2 gas costs, the openOracleCallback interface, storage flags, parameter sizing, and off-chain requirements. Source: https://www.openoracle.org/build/integrate # INTEGRATE Create a game per use case, size its security against the value at risk, and receive the settled price by callback or on-chain read. 01 Deployments 02 Gas 03 Callbacks 04 Parameters 05 Off-chain 01 Deployments ## Networks and token support Oracle addresses by chain. Standard ERC-20s and native ETH only. [![Base](data:image/svg+xml,%3c?xml%20version='1.0'%20encoding='UTF-8'?%3e%3csvg%20id='Layer_1'%20data-name='Layer%201'%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%201280%201280'%3e%3cdefs%3e%3cstyle%3e%20.cls-1%20{%20fill:%20blue;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='cls-1'%20d='M0,101.12c0-34.64,0-51.95,6.53-65.28,6.25-12.76,16.56-23.07,29.32-29.32C49.17,0,66.48,0,101.12,0h1077.76c34.63,0,51.96,0,65.28,6.53,12.75,6.25,23.06,16.56,29.32,29.32,6.52,13.32,6.52,30.64,6.52,65.28v1077.76c0,34.63,0,51.96-6.52,65.28-6.26,12.75-16.57,23.06-29.32,29.32-13.32,6.52-30.65,6.52-65.28,6.52H101.12c-34.64,0-51.95,0-65.28-6.52-12.76-6.26-23.07-16.57-29.32-29.32-6.53-13.32-6.53-30.65-6.53-65.28V101.12Z'/%3e%3c/svg%3e) Base openOracle v2 0x0cf849531f77E4bfE2d869db5b3F9Bca83d68626 Explorer ↗](https://basescan.org/address/0x0cf849531f77E4bfE2d869db5b3F9Bca83d68626#code) ### SUPPORTED ✓ Native ETH, passed as `address(0)` on either side of the pair ✓ Standard ERC-20 tokens ✓ USDC and USDT-style return behaviour ### NOT SUPPORTED ✕ Fee-on-transfer tokens ✕ Rebasing and elastic-supply tokens ✕ Hook and callback tokens (ERC-777 style) ▸ Reference [Contracts](https://docs.openoracle.org/openoracle/contracts#base) [Smart Contract Reference](https://docs.openoracle.org/openoracle/game-guide#oracle-game) 02 Gas ## Gas costs in the oracle game openOracle stores a single 32-byte hash per game, with the data sourced from the event log or calldata. Games can opt into full state storage with a flag. report() from 0k Opens the game and submits the first live report. dispute() from 0k Replaces the live report with a larger two-sided report. settle() from 0k Finalises after settlementTime passes with no dispute. Why it can be so cheap One contract, one stored hash per game, and tightly packed event logs. In-game transfers are internal balance credits rather than token transfers, and every balance slot is seeded with dust so dispute gas stays predictable. ▸ Reference [What's new in v2](https://docs.openoracle.org/openoracle/whats-new-v2#headline-changes) 03 Callbacks & flags ## How your contract receives the price Receive the price at settlement through a callback, or read it afterwards by passing the game’s preimage, which the contract verifies against its stored hash. Storage flags can keep the full state on-chain instead. If `callbackContract` is set, settlement calls `openOracleCallback` on it. The settled price is the ratio of the surviving amounts — raw token amounts, so you account for decimals. Callback failure does not undo settlement. source Consumer.sol ``` // Settlement calls this on your contract when callbackContract is set. interface IOpenOracleCallback { function openOracleCallback( uint256 reportId, uint256 currentAmount1, uint256 currentAmount2, uint256 currentTime, address token1, address token2 ) external; } contract Consumer is IOpenOracleCallback { address constant ORACLE = 0x0cf849531f77E4bfE2d869db5b3F9Bca83d68626; mapping(uint256 => uint256) public settledPrice; function openOracleCallback( uint256 reportId, uint256 currentAmount1, uint256 currentAmount2, uint256 currentTime, address token1, address token2 ) external { require(msg.sender == ORACLE, "NOT_ORACLE"); // Settled price is the ratio of the surviving amounts. // Raw token amounts — account for decimals yourself. settledPrice[reportId] = (currentAmount1 * 1e30) / currentAmount2; } } ``` EVM ▸ settlement callback Fixed at creation, inherited by everyone `callbackContract` and `callbackGasLimit` are set on the original report and inherited by every disputer. An impossible gas limit makes settlement revert and can lock the current reporter's funds. ### FLAGS BITFIELD Bit Behaviour Effect 1 timeType Use timestamps instead of block numbers for the game clock. Influences settlementTime and disputeDelay. 2 Track dispute history Records report amounts, block base fee and report time per round. 4 Store live game Stores the full OracleGame and helper from creation, updating on dispute and settlement. 8 Store finalPrice Persists the settled ratio on-chain so you can read it without the callback. 16 Store eligibility Stores settlementEligibility and updates it on each dispute. 32 Fees after halt Charge swap and protocol fees only once currentAmount1 is at or above escalationHalt. 64 Free escalation Allow larger-than-minimum escalation up to escalationHalt. ### ON-CHAIN READS Getter Requires Returns `oracleGame(reportId)` Always Current state hash, including after settlement. `storedGame(reportId)` Flag 4 Full current game. `storedHelper(reportId)` Flag 4 Creator, creation timestamp and creation block number. `finalPrice(reportId)` Flag 8 Settled ratio: floor(currentAmount1 \* 1e30 / currentAmount2). `settlementEligibility(reportId)` Flag 16 Latest reportTimestamp + settlementTime. `disputeHistory(reportId, i)` Flag 2 Amounts, base fee and time per round. Index 0 is the initial report. To read a settled price later, set flag `8` at creation — it cannot be added afterwards. ▸ Reference [Settling & callbacks](https://docs.openoracle.org/openoracle/game-guide#settling) 04 Parameters ## SIZING A GAME AGAINST VALUE AT RISK Every game carries its own security budget. The contract performs almost no parameter sanity checking — validation is on you. ![openOracle](data:image/svg+xml,%3c?xml%20version='1.0'%20encoding='UTF-8'?%3e%3csvg%20id='Layer_1'%20data-name='Layer%201'%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%20127.18%2078.46'%3e%3cdefs%3e%3cstyle%3e%20.cls-1%20{%20fill:%20%23ff1d25;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='cls-1'%20d='M107.97,29.82c-1.79-2.65-4.52-4.9-8.09-6.67-4.04-2.08-9.16-3.71-15.23-4.83s-12.75-1.69-19.85-1.69c-.4,0-.81.01-1.21.01s-.81-.01-1.21-.01c-7.1,0-13.78.57-19.85,1.69-6.07,1.12-11.2,2.75-15.23,4.83-3.57,1.76-6.29,4.02-8.09,6.67-1.79,2.68-2.72,5.8-2.72,9.28,0,.04,0,.09.01.13-.01.04-.01.09-.01.12,0,3.48.93,6.61,2.72,9.28,1.79,2.66,4.51,4.9,8.09,6.68,4.04,2.06,9.16,3.69,15.23,4.81s12.75,1.69,19.85,1.69c.4,0,.81,0,1.21-.01.4.01.81.01,1.21.01,7.1,0,13.78-.57,19.85-1.69,6.07-1.12,11.2-2.75,15.23-4.83,3.57-1.76,6.29-4.01,8.09-6.67,1.81-2.68,2.72-5.8,2.72-9.28v-.25c0-3.48-.91-6.61-2.72-9.28ZM100.63,45.26c-1.49,1.72-3.77,3.15-6.77,4.28-3.36,1.15-7.79,2.05-13.11,2.66-5.04.58-10.81.91-17.16.94-6.35-.03-12.12-.36-17.15-.94-5.34-.61-9.76-1.51-13.12-2.66-3-1.12-5.28-2.56-6.77-4.28-1.45-1.63-2.17-3.6-2.21-6.02.04-2.42.76-4.41,2.21-6.04,1.49-1.72,3.77-3.15,6.77-4.28,3.36-1.15,7.79-2.05,13.12-2.66,5.02-.58,10.79-.91,17.15-.94,6.35.03,12.12.36,17.16.94,5.32.61,9.75,1.51,13.11,2.66,3,1.12,5.28,2.56,6.77,4.28,1.45,1.63,2.17,3.62,2.21,6.04-.04,2.42-.76,4.39-2.21,6.02Z'/%3e%3cpath%20class='cls-1'%20d='M127.16,38.74c-.05-4.5-1.27-8.52-3.65-11.97-1.7-2.48-4.05-4.71-6.97-6.62-.87-8.01-1.72-8.97-2-9.28-2.14-2.41-5.37-4.44-9.63-6.01h-.02c-4.65-1.55-10.7-2.77-18.01-3.6-6.8-.78-14.65-1.21-23.3-1.26-8.65.04-16.5.48-23.3,1.26-7.31.84-13.36,2.05-18.01,3.6h-.01c-4.26,1.57-7.49,3.6-9.63,6.01-.28.31-1.14,1.27-2,9.28-2.92,1.91-5.26,4.14-6.97,6.62C1.29,30.22.06,34.25.01,38.74h-.01v.97h.01c.04,4.5,1.27,8.52,3.65,11.97,1.7,2.48,4.05,4.71,6.97,6.62.87,8.01,1.72,8.97,2,9.28,2.14,2.41,5.37,4.44,9.63,6.01h.01c4.65,1.55,10.7,2.77,18.01,3.6,6.8.78,14.65,1.21,23.3,1.26,8.65-.04,16.5-.48,23.3-1.26,7.31-.84,13.36-2.05,18.01-3.6h.02c4.26-1.57,7.49-3.6,9.63-6.01.28-.31,1.14-1.27,2-9.28,2.92-1.91,5.26-4.14,6.97-6.62,2.38-3.45,3.6-7.47,3.65-11.97h.01v-.97h-.01ZM115.62,57.76c-1.06.67-2.21,1.32-3.42,1.91-5.38,2.72-12.23,4.84-20.36,6.32-8.15,1.48-17.12,2.23-26.68,2.23h-3.14c-9.57,0-18.54-.75-26.68-2.23-8.13-1.48-14.98-3.6-20.34-6.32-1.23-.6-2.38-1.24-3.42-1.91V20.7c1.05-.67,2.2-1.32,3.41-1.91,5.38-2.72,12.23-4.84,20.36-6.32,8.15-1.48,17.12-2.23,26.68-2.23h3.14c9.57,0,18.54.75,26.68,2.23,8.13,1.48,14.98,3.6,20.34,6.32,1.23.6,2.38,1.24,3.44,1.91v37.06Z'/%3e%3c/svg%3e) Parameter Meaning `token1 / token2` Token pair for the game. address(0) means native ETH. `settlementTime` Per-round timer. A report can settle only after this much time passes without a dispute. `disputeDelay` Optional delay before a report or dispute can be disputed. `multiplier` Growth rate for currentAmount1 on each dispute. 140 means 1.4x. `escalationHalt` currentAmount1 level where multiplier growth stops. `feePercentage` Swap fee paid to the previous reporter. 1e7 units — 1000 is 0.01%. `protocolFee` Fee routed to protocolFeeRecipient. Same 1e7 units. `settlerReward` Native ETH credited to whoever settles the game. `callbackContract / callbackGasLimit` Optional settlement callback target and gas limit. `flags` Bitfield for optional game behaviour. See the table above. ### The accuracy you are buying Dispute economics set the band the settled price lands in: settled price ∈ true price ± 0.65 · M · σ(T) with fees: D > 0.65 · M · σ(T) + F\_s + F\_p Rough estimate. σ(T) is the standard deviation of returns over the settlement window, so accuracy and cost both scale linearly with background volatility. See [Oracle Accuracy & Cost](https://docs.openoracle.org/openoracle/oracle-accuracy-cost#accuracy) for more. ### The cost of opening one The initial reporter position expects to lose money. If your protocol creates games, you fund it — directly or through a bounty. initial reporter cost ≈ 0.65 · σ(T) · L + worst-case settlement gas cost L = initial liquidity committed to the game A swap fee on the order of σ(T) or larger drives initial reporter risk toward zero, at the cost of a wider no-dispute band and therefore worse accuracy. ▸ Reference [Oracle Accuracy & Cost](https://docs.openoracle.org/openoracle/oracle-accuracy-cost#accuracy) [Economic Bounds](https://docs.openoracle.org/openoracle/economic-bounds#settlement-probability-inequality) [Guardrails](https://docs.openoracle.org/openoracle/guardrails#max-slippage) 05 Off-chain ## What you have to build besides the contract ▢ 01Decode packed events Event payloads are tightly packed bytes, not ABI-encoded fields. You need a small custom decoder — layouts are in the contract reference. ▢ 02Retain the preimage dispute() and settle() take the full preimage as calldata, re-verified against the stored hash. Keep the original event data. ▢ 03Someone has to play A game only works if participants report, dispute and settle it. Run the roles yourself, pay others, or rely on the existing bot network. Internal balances make repeat participation cheap Hold funds inside the oracle contract and play without a transfer per call: deposit once, delegate with `approveInternal`. Native ETH flows through the ledger like an ERC-20, no WETH wrapping. [RUN A BOT ⟶](https://www.openoracle.org/build/operate)[SEE LIVE GAMES ⟶](https://scan.openoracle.org/) ▸ Reference [Events & packed layout](https://docs.openoracle.org/openoracle/game-guide#events-and-packed-layout)