Solidity Interfaces

Complete, production-ready Solidity interfaces for all FarmTruth contracts deployed on Binance Smart Chain (BSC) Mainnet.

Available Interfaces

IOptimisticOracle

Fast, low-cost oracle with optimistic dispute resolution.

Address: 0xA83689161DFa9d5992fBa658d3148C6f72E1419E

Use Case: Quick oracle queries that resolve in ~1.5 hours if undisputed. Ideal for prediction markets, insurance claims, and real-time data feeds.

Key Features:

• 30k token creation cost
• 1M token collateral for proposals/disputes
• Automatic escalation to main oracle on dispute
• Support for "not clear yet" state

View Full Interface →

IDecentralizedOracle

Main oracle contract with token-weighted voting and tie-breaking mechanisms.

Address: 0xFA4595F636887CA28FCA3260486e44fdcc8c8A71

Use Case: High-stakes queries requiring community consensus. Used as the final arbiter for disputed OptimisticOracle queries.

Key Features:

• Token-weighted voting
• Automatic tie-breaking extensions
• JSON metadata support
• Inactivity slashing

View Full Interface →

IGovernance

On-chain governance for oracle parameter updates.

Address: 0x0ebCFa07497B44e66859F82AC2c8f1187F0154cf

Use Case: Reading governance parameters needed for oracle interactions. Token holders can also propose and vote on parameter changes.

Key Features:

• 4 vote types (FOR, AGAINST, ABSTAIN, VETO)
• 3 proposal types (parameters, tie extensions, indicative)
• Token locking mechanism
• VETO burns proposer's deposit

View Full Interface →

Quick Start

Installation

Copy the interface you need into your project:

# Clone the repository
git clone https://github.com/your-org/farmtruth
cd farmtruth

# Interfaces are in contracts/
cp contracts/IOptimisticOracle.sol your-project/contracts/
cp contracts/IDecentralizedOracle.sol your-project/contracts/
cp contracts/IGovernance.sol your-project/contracts/

Or copy the interface code directly from the documentation pages above.

Basic Usage

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "./IOptimisticOracle.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";

contract MyContract {
    IOptimisticOracle public immutable oracle;
    IERC20 public immutable token;

    constructor(address _oracle, address _token) {
        oracle = IOptimisticOracle(_oracle);
        token = IERC20(_token);

        // Approve unlimited spending for convenience
        token.approve(_oracle, type(uint256).max);
    }

    function askOracle(
        string calldata question,
        string[] calldata options
    ) external returns (uint256 queryId) {
        // Ensure contract has enough tokens
        require(
            token.balanceOf(address(this)) >= oracle.CREATION_COST(),
            "Insufficient balance"
        );

        return oracle.createQuery(question, options);
    }

    function getResult(uint256 queryId) external view returns (uint8[] memory) {
        require(
            oracle.getQueryState(queryId) == IOptimisticOracle.QueryState.Resolved,
            "Not resolved yet"
        );

        return oracle.getAnswer(queryId);
    }
}

Contract Addresses (BSC Mainnet)

Network Details

Binance Smart Chain (BSC) Mainnet

• Chain ID: 56
• RPC: https://bsc-dataseed.bnbchain.org
• Block Time: ~0.75 seconds
• Explorer: https://bscscan.com

Choosing the Right Oracle

Use OptimisticOracle When:

• ✅ You need fast resolution (~1.5 hours)
• ✅ Lower costs are more important than decentralization
• ✅ Queries have clear, objective answers
• ✅ You're okay with dispute escalation possibility
• ✅ Examples: Sports scores, weather data, simple yes/no questions

Use DecentralizedOracle When:

• ✅ You need maximum decentralization
• ✅ Queries are subjective or require debate
• ✅ High-value decisions justify longer resolution time
• ✅ You want community consensus
• ✅ Examples: Governance votes, complex assessments, disputed facts

Integration Guides

For Solidity Developers

• OptimisticOracle Integration
• Main Oracle Integration
• Approvals & Token Handling
• Complete Flow Examples

For JavaScript/TypeScript Developers

• ABI Usage
• Setup & Connection
• Create Queries
• Vote & Resolve

Common Patterns

Approve Once Pattern

constructor(address oracle_, address token_) {
    oracle = IOptimisticOracle(oracle_);
    token = IERC20(token_);

    // Approve maximum amount upfront
    token.approve(oracle_, type(uint256).max);
}

Safe Resolution Pattern

function tryResolve(uint256 queryId) external returns (bool) {
    try this._resolve(queryId) {
        return true;
    } catch {
        return false; // Can retry later
    }
}

function _resolve(uint256 queryId) external {
    oracle.resolveUndisputed(queryId);
}

Cross-Oracle Pattern

// Use OptimisticOracle, fallback to DecentralizedOracle if disputed
IOptimisticOracle optimistic = IOptimisticOracle(optimisticAddr);
IDecentralizedOracle main = IDecentralizedOracle(optimistic.mainOracle());

// OptimisticOracle escalates to main oracle automatically on dispute

Development Resources

Testing

• Testnet: Use BSC Testnet for development
• Local: Deploy to Hardhat network for testing
• Faucet: Get test tokens from BSC faucet

Tools

• Hardhat: Recommended development framework
• Foundry: Alternative with fast testing
• Remix: Quick prototyping in browser
• OpenZeppelin: Security-audited contract libraries

Documentation

• Getting Started
• Main Documentation
• GitHub Repository

Gas Considerations

Typical gas costs on BSC (with ~3 Gwei gas price):

Costs are approximate and vary with gas prices

Security Considerations

1. Token Approvals: Be cautious with unlimited approvals
2. Reentrancy: Interfaces use ReentrancyGuard
3. Front-Running: Consider time-locked commitments for sensitive data
4. Economic Security: Ensure collateral amounts provide adequate security
5. Dispute Resolution: Understand dispute escalation paths

Support & Community

• Documentation: You're reading it!
• GitHub Issues: Report bugs and request features
• Discord: Join the community (link in repo)
• Twitter: Follow for updates

Next Steps

1. Choose Your Oracle: OptimisticOracle or DecentralizedOracle
2. Read Integration Guide: Solidity or JavaScript
3. Copy Interface: From the documentation pages
4. Build & Test: Start integrating with FarmTruth!

Back to Documentation Home