Dispute System

TOC implements a two-round dispute mechanism that ensures incorrect resolutions can always be challenged. Round 1 goes to a TruthKeeper (domain expert). If needed, Round 2 escalates to admin arbitration.

Two-Round Architecture

Round 1: TruthKeeper Adjudication

When someone disputes a resolution, the assigned TruthKeeper reviews and decides:

Filing a Dispute

• Anyone can dispute during the dispute window
• Must post a dispute bond (must exceed resolution bond)
• Provide a reason and evidence URI (IPFS/Arweave link)
• Optionally propose a corrected answer (required for NUMERIC/GENERIC types)

// Filing a dispute
registry.disputePOP{value: disputeBondAmount}(
    popId,
    "Price data was incorrect",  // reason
    "ipfs://Qm...",               // evidence URI
    correctedResult                // optional: proposed correction
);

TruthKeeper Decision

The TruthKeeper has truthKeeperWindow time to decide. Four possible outcomes:

Round 2: Admin Escalation

Either party can challenge the TruthKeeper's Round 1 decision:

Filing an Escalation

• Must post an escalation bond (higher than Round 1 bonds)
• Must be filed within escalationWindow after TK decision
• Provide additional evidence if available

// Challenging TruthKeeper's decision
registry.challengeTruthKeeperDecision{value: escalationBond}(
    popId,
    "TK decision was incorrect",  // reason
    "ipfs://Qm...",                // additional evidence
    correctedResult                 // optional correction
);

Admin Resolution

Protocol admin makes the final decision. Same four outcomes as Round 1, but this decision is final.

Bond Economics

Bonds create financial incentives for honest participation. See Bond Economics for full details.

Slash Distribution (50/50)

• 50% to winner - Incentivizes accurate dispute filing
• 50% to protocol - Funds ongoing operations

Evidence System

Disputes include an evidenceURI field for linking to supporting evidence:

• IPFS - Decentralized, permanent storage
• Arweave - Permanent blockchain storage
• HTTPS - Traditional web links (less reliable)

Evidence should include:

• Screenshots or data proving incorrect resolution
• Links to authoritative sources
• Timestamps and context

Post-Resolution Disputes

If a POP has a postResolutionWindow > 0, disputes can be filed even after initial finalization:

• Allows catching errors missed during the main dispute window
• Same two-round process applies
• If upheld, result is corrected (not replaced)
• Original result remains accessible alongside correction

// Check for corrections
if (registry.hasCorrectedResult(popId)) {
    bytes memory corrected = registry.getCorrectedResult(popId);
    // Use corrected result
} else {
    bytes memory original = registry.getResult(popId);
    // Use original result
}

Dispute States

POPs track dispute status through dedicated states:

• DISPUTED_ROUND_1 - TruthKeeper is reviewing
• DISPUTED_ROUND_2 - Admin is reviewing (escalated)

Use isContested(popId) to check if a POP has an active dispute.

TruthKeeper Requirements

To be a TruthKeeper:

• Whitelisted - Added by protocol admin for highest tier POPs
• Domain expertise - Understands the question types they adjudicate
• Responsive - Must decide within the window or face auto-escalation

TruthKeepers can also guarantee resolvers - declare that they stand behind a specific resolver's accuracy. This enables TK_GUARANTEED tier for POPs using that resolver.