Skip to main content

​
Core events

There are three main event structures defining the limit order game. The first, ReportInstanceCreated, is when a new game is created. The second structure, which is equivalent for ReportDisputed and InitialReportSubmitted, tells you how much money is in the limit orders, which instance (reportId) the limit orders correspond to, and the rules of that specific game. The third structure, ReportInstanceCreated2, ReportDisputed2 and InitialReportSubmitted2, contains extra game variables that couldn’t fit in the larger events. All of this data is available in on-chain storage as well, but it is generally faster to read from the events. 
ReportInstanceCreated:
    uint256 indexed reportId,
    address indexed token1Address,
    address indexed token2Address,
    uint256 feePercentage,
    uint256 multiplier,
    uint256 exactToken1Report,
    uint256 ethFee,
    address creator,
    uint256 settlementTime,
    uint256 escalationHalt,
    uint256 disputeDelay,
    uint256 protocolFee,
    uint256 settlerReward,
    bool timeType,
    address callbackContract,
    bytes4 callbackSelector,
    bool trackDisputes,
    uint256 callbackGasLimit,
    bool keepFee,
    bytes32 stateHash,
    uint256 blockTimestamp

ReportDisputed and InitialReportSubmitted:
    uint256 indexed reportId,
    address reporter,
    uint256 amount1,
    uint256 amount2,
    address indexed token1Address,
    address indexed token2Address,
    uint256 swapFee,
    uint256 protocolFee,
    uint256 settlementTime,
    uint256 disputeDelay,
    uint256 escalationHalt,
    bool timeType,
    address callbackContract,
    bytes4 callbackSelector,
    bool trackDisputes,
    uint256 callbackGasLimit,
    bytes32 stateHash,
    uint256 blockTimestamp

ReportDisputed2 and InitialReportSubmitted2:
    uint256 reportId
    uint256 multiplier
    address protocolFeeRecipient

ReportInstanceCreated2:
    uint256 reportId
    address protocolFeeRecipient
When you see an oracle game created (event ReportInstanceCreated), it’s important to have a few sanity check filters.

​
Critical filters (if these are not followed your funds may be lost forever)

1. callbackGasLimit < 2000000
2. if timeType true, settlementTime < 86400
3. if on Ethereum L1, if timeType false, settlementTime < 7200
4. if on Base, if timeType false, settlementTime < 43200
5. tokens must be standard ERC20, like WETH or USDC, no rebasing tokens or fee-on-transfer
Set callbackGasLimit below the chain’s per-tx gas limit. settle() reverts if the callback cannot be fully attempted, so an oversized value can make settlement impossible and lock funds. settlementTime is more user preference: when you submit a report, your funds are locked in the limit orders for up to this amount of time before the settle() function can free them. timeType true means this time is measured in seconds, timeType false means this time is measured in blocks. Add normal ERC-20 token addresses like WETH and USDC (no rebasing tokens or anything like that) to your whitelist and check the reportId’s token1Address and token2Address against these. If the reportId doesn’t match these filters, ignore it.

​
Overloads in the oracle contract

There are some overload functions in the oracle contract with optional reporter and disputer inputs, mainly for external contracts. 
function submitInitialReport(
    uint256 reportId,
    uint256 amount1,
    uint256 amount2,
    bytes32 stateHash,
    address reporter
)

function disputeAndSwap(
    uint256 reportId,
    address tokenToSwap,
    uint256 newAmount1,
    uint256 newAmount2,
    address disputer,
    uint256 amt2Expected,
    bytes32 stateHash
)
If using these overloads the disputer and reporter input should be an address YOU control, NOT the address of the previous reporter or you will lose your tokens. At the end of the round, tokens are pulled from msg.sender and returned at the end of the round to the specified reporter or disputer address. Both submitInitialReport() and disputeAndSwap() have overloads that let you set the beneficiary (reporter/disputer). The base forms return funds to msg.sender.

​
Playing the game

​
Settler Reward Filter

The settlerReward event item is quoted in wei and should be greater than 120k + callbackGasLimit worth of gas at prevailing gas prices in order for you to participate in a given reportId. If the settlerReward is not high enough, ignore the reportId. This way you don’t have to worry about collecting your report amounts yourself, the network will take care of it for you at settlement.

​
Initial reporting

If you only see ReportInstanceCreated, and don’t see any InitialReportSubmitted event, the reportId is eligible for an initial report. There can only be one successful initial report per reportId. To submit an initial report, you can call submitInitialReport(reportId, amount1, amount2, stateHash). Looking at the ReportInstanceCreated event, you earn ethFee minus settlerReward as an initial reporter reward. If keepFee is true, you keep the initial reporter reward if later disputed. If keepFee is false, you don’t receive the initial reporter reward if later disputed. Filtering keepFee to true is reasonable. amount1 in the function input must equal exactToken1Report. As part of the initial report, you send in exactToken1Report of token1Address. amount2 in the function input is the amount of token2Address that equals exactToken1Report in value. As part of the initial report, you send in amount2 of token2Address. stateHash in the function input should equal stateHash from the ReportInstanceCreated event you saw and validated. If you get disputed, you receive two times the lower valued token amount plus swap fees. For example, if you initially reported $100 of WETH and $100 of USDC, and WETH drops -1%, there is now $99 WETH and $100 USDC in the report. If someone comes and disputes, you will receive 2 * $99 + swap fees in WETH. If swap fees are 1%, you receive 1% * $99 in additional swap fees from the disputer, in WETH. The swap fees you get paid are controlled by the feePercentage event item. Here, 1% = 100000 in contract units. 0.01% = 1000, etc. A higher swap fee protects you from market moves. Funds unlock on settle if undisputed for settlementTime (timeType true: seconds, false: blocks). submitInitialReport() costs around 250k gas per transaction. Initial reporters should be aware they must be able to receive ETH, or the initial reporter reward will be burned. Keep in mind anyone can dispute you before the end of the settlementTime, and you will lose the absolute difference in value between your reported token amounts at that time, less the swap fee.

​
Disputing

If a reportId has either InitialReportSubmitted or ReportDisputed, treat it as active and disputable. For dispute bots, those two events are equivalent signals. A reportId is disputable if settlementTime has not yet passed and disputeDelay has elapsed since the last report. Disputes are allowed in the last eligible block or timestamp. Contract check: 
if (meta.timeType) {
    if (block.timestamp > status.reportTimestamp + meta.settlementTime) {
        revert InvalidTiming("dispute period expired");
    }
} else {
    if (_getBlockNumber() > status.reportTimestamp + meta.settlementTime) {
        revert InvalidTiming("dispute period expired");
    }
}
Note reportTimestamp is stored as blocks if timeType is false. To submit a dispute, you can call disputeAndSwap(reportId, tokenToSwap, newAmount1, newAmount2, amt2Expected, stateHash). Choose tokenToSwap as the side with lower USD value (amount1 vs amount2). That choice captures the current mispricing spread, minus swap/protocol fees. The newAmount1 input depends on amount1 and escalationHalt from the InitialReportSubmitted or ReportDisputed event and multiplier from the ReportInstanceCreated event (or ReportDisputed2 / InitialReportSubmitted2). Multiplier in the contract is coded so 140 = 1.4x (pseudocode): 
if amount1 >= escalationHalt
    newAmount1 = amount1 + 1
else
    newAmount1 = min(escalationHalt, floor(multiplier * amount1 / 100))
All amounts are in lowest level ERC-20 contract units. The newAmount2 input is the amount of token2Address that equals newAmount1 in value. amt2Expected is simply the amount2 in the InitialReportSubmitted or ReportDisputed event you are reacting to. This helps protect disputers against chain reorganization attacks. stateHash in the function input should equal stateHash from the ReportInstanceCreated event you saw and validated. When you dispute, you pay swapFee + protocolFee times the amount of the token corresponding to your choice of tokenToSwap. For example, if there is $99 WETH (token1) and $100 USDC (token2) in a report you are disputing, you would choose tokenToSwap as token1Address, and swap and protocol fees paid would be multiplied by amount1 ($99 weth). For both swap and protocol fees, a 1% fee would be 100000 in contract units. 0.01% = 1000, etc. A higher swap fee protects you from market moves. Protocol fees (protocolFee) can be considered burned, while swap fees (swapFee) are paid to the reporter you are disputing. swapFee in the initial report and dispute events is equivalent to feePercentage in ReportInstanceCreated. Your dispute can itself be disputed by someone else. If your dispute is later disputed, you receive 2 * lower-valued side + swap fee, denominated in tokenToSwap. Example: from $99/$100, payout is 2 * $99 + fee in WETH. The disputeDelay parameter controls how long you must wait from the last initial report or dispute before disputes are allowed. If timeType is true, disputeDelay is in seconds, if false, blocks. Contract check: 
if (meta.timeType) {
    if (block.timestamp < status.reportTimestamp + meta.disputeDelay) {
        revert InvalidTiming("dispute too early");
    }
} else {
    if (_getBlockNumber() < status.reportTimestamp + meta.disputeDelay) {
        revert InvalidTiming("dispute too early");
    }
}
As part of the dispute, the token flows from you as the disputer are as follows: 
If tokenToSwap == token1Address
    You transfer into contract:
        1. currentAmount1 + newAmount1 + swap and protocol fees
        2. max( 0 , newAmount2 - currentAmount2)
    You receive from contract:
        1. max( 0 , currentAmount2 - newAmount2)

If tokenToSwap == token2Address
    You transfer into contract:
        1. currentAmount2 + newAmount2 + swap and protocol fees
        2. newAmount1 - currentAmount1
    You receive nothing from the contract.
disputeAndSwap() costs around 210k gas per transaction. Finally, the new implied price by your dispute (ratio of newAmount1 to newAmount2) must be outside the fee barrier around the previous report’s price, which includes both swap fees (feePercentage) and protocol fees (protocolFee): 
uint256 oldAmount1 = status.currentAmount1;
uint256 oldPrice = (oldAmount1 * PRICE_PRECISION) / status.currentAmount2;
uint256 feeSum = uint256(meta.feePercentage) + uint256(meta.protocolFee);
uint256 feeBoundary = (oldPrice * feeSum) / PERCENTAGE_PRECISION;
uint256 lowerBoundary = (oldPrice * PERCENTAGE_PRECISION) / (PERCENTAGE_PRECISION + feeSum);
uint256 upperBoundary = oldPrice + feeBoundary;
uint256 newPrice = (newAmount1 * PRICE_PRECISION) / newAmount2;

if (newPrice >= lowerBoundary && newPrice <= upperBoundary) {
    revert OutOfBounds("price within boundaries");
}
Keep in mind anyone can dispute you before the end of the settlementTime, and you will lose the absolute difference in value between your reported token amounts at that time, less the swap fee.

​
Settling

Once settlementTime has passed since the last InitialReportSubmitted or ReportDisputed event, a reportId can be settled. The settler earns the settlerReward in wei. To settle a reportId, you can call settle(reportId). Calling settle on an already-settled report returns the stored values rather than reverting. Contract check: 
if (meta.timeType) {
    if (block.timestamp < status.reportTimestamp + meta.settlementTime) {
        revert InvalidTiming("settlement");
    }
} else {
    if (_getBlockNumber() < status.reportTimestamp + meta.settlementTime) {
        revert InvalidTiming("settlement");
    }
}
Note that disputes are allowed in the first settle eligibility block or timestamp, and may kick out your settle depending on the inclusion tip (prio fee). The gas cost to settle is at most ~120k + callbackGasLimit, provided token1 and token2 are normal ERC-20 tokens. More complex ERC-20s may cost more. Settlers should be aware malicious ERC-20 tokens in the reportId can cause their settle to revert and waste gas. Generally, there is no incentive other than griefing to play oracle games with malicious ERC-20 tokens, but it is a good practice to filter oracle game tokens for settles. Settlers should also be aware they must be able to receive ETH when calling settle, or the settlerReward will be burned.

​
Oracle game validation

Some may want to run oracle game bots using RPC and websocket data without running a full node. One issue here is if the data provider lies to you, they can trick you into a very bad trade in the oracle game. We have function entries in the batcher contract where you pass in the following oracleParams: 
struct oracleParams {
    uint256 exactToken1Report;
    uint256 escalationHalt;
    uint256 fee;
    uint256 settlerReward;
    address token1;
    uint48 settlementTime;
    address token2;
    bool timeType;
    uint24 feePercentage;
    uint24 protocolFee;
    uint16 multiplier;
    uint24 disputeDelay;//reportMeta end
    uint256 currentAmount1;
    uint256 currentAmount2;//reportStatus end
    uint32 callbackGasLimit;
    address protocolFeeRecipient;
    bool keepFee; //extraData end
}
to: 
/**
 * @notice Submits one initial report with reportId validation checks.
 * @param reports Initial report data from struct InitialReportData
 * @param p Oracle parameter data from struct oracleParams
 * @param batchAmount1 Amount of oracle game token1 the batcher can draw from to attempt the initial report
 * @param batchAmount2 Amount of oracle game token2 the batcher can draw from to attempt the initial report
 * @param timestamp Current block.timestamp
 * @param blockNumber Current block number
 * @param timestampBound Transaction will revert if it lands +/- this number of seconds outside passed timestamp
 * @param blockNumber Transaction will revert if it lands +/- this number of blocks outside passed blockNumber
 */
function submitInitialReportSafe(
    InitialReportData[] calldata reports,
    oracleParams calldata p,
    uint256 batchAmount1,
    uint256 batchAmount2,
    uint256 timestamp,
    uint256 blockNumber,
    uint256 timestampBound,
    uint256 blockNumberBound
)
or: 
/**
 * @notice Submits one dispute with reportId validation checks.
 * @param disputes Dispute data from struct DisputeData
 * @param p Oracle parameter data from struct oracleParams
 * @param batchAmount1 Amount of oracle game token1 the batcher can draw from to attempt the dispute
 * @param batchAmount2 Amount of oracle game token2 the batcher can draw from to attempt the dispute
 * @param timestamp Current block.timestamp
 * @param blockNumber Current block number
 * @param timestampBound Transaction will revert if it lands +/- this number of seconds outside passed timestamp
 * @param blockNumber Transaction will revert if it lands +/- this number of blocks outside passed blockNumber
 */
function disputeReportSafe(
    DisputeData[] calldata disputes,
    oracleParams calldata p,
    uint256 batchAmount1,
    uint256 batchAmount2,
    uint256 timestamp,
    uint256 blockNumber,
    uint256 timestampBound,
    uint256 blockNumberBound
)
These functions check the passed parameters against what is actually on-chain before the initial report or dispute is allowed to fire. If the parameters don’t match, the transaction reverts. This way, if an RPC lies to you, all you do is revert instead of torch your capital. Everything you need to construct oracleParams is in the events.

​
Expected value

Assuming the settler reward is high enough (discussed above), we can write the approximate mean worst-case expected value for an initial reporter as: EV = initial_reporter_reward_usd - exactToken1ReportToUsd * volatility_loss - gas_fees_usd This ignores swap fees received when disputed, which strictly help you as the initial reporter. For a disputer, assuming tokenToSwap is chosen correctly: EV = abs(currentAmount1ToUsd - currentAmount2ToUsd) - swap_fee_usd - protocol_fee_usd - newAmount1ToUsd * volatility_loss - gas_fees_usd This ignores swap fees received when your dispute is itself disputed, which strictly help you as a disputer. swap_fee_usd and protocol_fee_usd are levied on the amount of tokenToSwap in the current report (before you dispute), which should be the amount with a smaller USD value. When EV > 0, an initial report or dispute is in theory profitable.

​
Volatility loss

An appropriate volatility_loss term appears to be something like 0.65 * (standard deviation of settlementTime returns of the token1/token2 ratio) from Oracle Accuracy & Cost. You can increase the 0.65 coefficient a bit to give yourself more of a buffer if desired but it may reduce competitiveness. This appears surprisingly robust across a number of distributions we tested, but real-world price action may differ. In some distributions, variance and standard deviation are not finite. It may behoove you to use something like the realized median absolute deviation divided by ~0.6745 instead of standard deviation. In general, estimating the scale of the returns has a high skill gap. With volatility estimation (and openOracle broadly), we are playing a dangerous game. If volatility spikes more quickly than your sampling adjusts, you can lose money. The best bots will have the best volatility predictions. If nobody is predicting volatility on that level, then the risk to a more naive bot is much lower.

​
Initial reporter bounty contract

An additional initial reporter reward may be available for a given reportId. You can claim by submitting the initial report through the bounty contract instead of the oracle contract. The bounty contract event is as follows: 
event BountyCreated(
    uint256 indexed reportId,
    uint256 totalAmtDeposited,
    uint256 bountyStartAmt,
    uint256 maxRounds,
    uint256 bountyMultiplier,
    uint256 blockTimestamp,
    bool timeType,
    uint256 startTime,
    uint256 roundLength,
    address bountyToken
);
reportId is the oracle game unique identifier the bounty applies to. totalAmtDeposited is the maximum bounty paid to the initial reporter. bountyStartAmt is the starting bounty amount. After maxRounds, the bounty stops increasing. Each round is roundLength of time, where time is determined by timeType. If timeType is true, time is in seconds, and if false, blocks. Each round, the bounty increases by bountyMultiplier. For example, a bountyMultiplier of 15000 corresponds to an increase of 1.5x each round. startTime is when the bounty starts escalating, starting from bountyStartAmt. Before this time, you cannot claim the bounty. Time here depends on timeType: if true, startTime is a timestamp, if false, a block height. blockTimestamp is simply the block timestamp of the event and doesn’t impact the bounty math. bountyToken is the address of the token the bounty is paid in. If bountyToken is address(0), this means the bounty is paid in ETH. Contract logic: 
function calcBounty(
    uint256 start,
    uint256 bountyStartAmt,
    uint256 maxRounds,
    uint256 bountyMultiplier,
    uint256 totalAmtDeposited,
    bool timeType,
    uint256 roundLength
) internal view returns (uint256) {
    uint256 currentTime = timeType ? block.timestamp : block.number;
    if (currentTime < start) revert InvalidInput("start time");

    uint256 rounds = (currentTime - start) / roundLength;
    if (rounds > maxRounds) {
        rounds = maxRounds;
    }

    uint256 bounty = bountyStartAmt;
    for (uint256 i = 0; i < rounds; i++) {
        bounty = (bounty * bountyMultiplier) / 10000;
    }

    if (bounty > totalAmtDeposited) {
        bounty = totalAmtDeposited;
    }

    return bounty;
}
Per-round multiplication uses integer math, so low-decimal tokens may experience truncation. Let’s walk through a simple example: 
event BountyCreated(
    uint256 indexed reportId,
    uint256 totalAmtDeposited = 10 ETH,
    uint256 bountyStartAmt = 1 ETH,
    uint256 maxRounds = 10,
    uint256 bountyMultiplier = 11000,
    uint256 blockTimestamp = 1000,
    bool timeType = true,
    uint256 startTime = 1002,
    uint256 roundLength = 1,
    address bountyToken = address(0)
);
The bounty was created at timestamp 1000. Assume blocks are 2 seconds each. The claimable bounty for reportId is as follows, for each timestamp: 
1000: not claimable
1002: 1 ETH
1004: 1.21 ETH (1 * 1.1^(1004-1002) = 1.1^2)
1006: 1.4641 ETH (1 * 1.1^4)
1008: 1.771561 ETH (1.1^6)
1010: 2.14358881 ETH (1.1^8)
1012: 2.5937424601 ETH (1.1^10, maxRounds hit)
1014: 2.5937424601 ETH
1016: 2.5937424601 ETH
The bounty stops escalating once maxRounds of time has passed, which is 10 seconds in this case, given timeType true, maxRounds of 10, and roundLength 1. If roundLength were 2 here, the claimable bounty at time 1004 would be 1.1 ETH, at time 1006, 1.21 ETH, and so on. This bounty can be added to the initial reporter reward in the oracle contract to get your initial_reporter_reward_usd in the Expected Value section equation. You can claim the bounty by calling the below function directly in the bounty contract: 
/**
 * @notice Submits the initial price report for a given report ID and claims the bounty. Amounts use smallest unit for a given ERC-20.
           No validation other than stateHash is performed
 * @param reportId The unique identifier for the report
 * @param amount1 Amount of token1 (must equal exactToken1Report)
 * @param amount2 Choose the amount of token2 that equals amount1 in value
 * @param stateHash State hash for a given reportId in the oracle game
 * @dev Tokens are pulled from msg.sender and will be returned to msg.sender when settled or disputed
 */
function submitInitialReport(uint256 reportId, uint256 amount1, uint256 amount2, bytes32 stateHash) external nonReentrant {
    _submitInitialReport(reportId, amount1, amount2, stateHash, msg.sender);
}
This works the same as the initial report function in the oracle contract. There are additional overloads for game validation just like in the “Oracle game validation” section above to protect against adversarial RPCs and delayed transaction inclusion. Sometimes, a bounty for a reportId can be retargeted: 
event BountyRetargeted(
    uint256 indexed newReportId,
    uint256 oldReportId,
    uint256 totalAmtDeposited,
    uint256 bountyStartAmt,
    uint256 maxRounds,
    uint256 bountyMultiplier,
    uint256 blockTimestamp,
    bool timeType,
    uint256 startTime,
    uint256 roundLength,
    address bountyToken
);
This is the same as the BountyCreated event except the parameters now apply to newReportId and the bounty for oldReportId is no longer claimable.