Skip to content

Phase 3: Multi-Stage Oracle Resolution Integration Tests

Overview

This document describes the comprehensive integration testing implementation for the Multi-Stage Oracle Resolution system. These tests validate the complete oracle resolution workflow, including initial report submission, challenge periods, dispute resolution, and final settlement.

Implementation Summary

Test Suite Location

  • Main Test File: test/integration/oracle/multi-stage-resolution.test.js
  • Helper Functions: test/integration/helpers/index.js
  • Deployment Fixture: test/integration/fixtures/deploySystem.js

Test Coverage (14 Tests)

1. Happy Path: Unchallenged Resolution

Tests the standard workflow when no challenges are submitted: - Designated reporter submits initial report with bond - Challenge period expires without challenges - Owner finalizes resolution with reporter's values - Reporter bond is returned

2. Challenge Workflow: Successful Challenge

Tests the challenge mechanism and bond redistribution: - Reporter submits initial report - Challenger contests the report within challenge period - Owner accepts challenge and finalizes with challenger's values - Both bonds (reporter + challenger) are awarded to challenger

3. Challenge Rejection: Late Challenge

Tests challenge period enforcement: - Reporter submits initial report - Challenge period expires - Late challenge attempt is rejected

4. Dispute Escalation Workflow

Tests the UMA dispute escalation mechanism: - Reporter submits initial report - Challenger contests the report - Owner escalates to UMA dispute - Dispute is resolved and finalized

5. Bond Management and Access Control

Tests bond validation and access restrictions: - Incorrect bond amounts are rejected - Only designated reporters can submit reports - Only owner can finalize resolutions - Only owner can escalate to UMA

6. Multiple Resolutions in Parallel

Tests handling of multiple concurrent proposals: - Multiple proposals at different stages (reported, challenged, disputed) - Independent state management for each proposal - Correct finalization of each proposal

7. Edge Cases and Error Conditions

Tests error handling and validation: - Double reporting prevention - Double finalization prevention - Empty evidence handling (validation is off-chain)

8. Query Functions and State Verification

Tests the query interface and state transitions: - Resolution details at each stage (Unreported, DesignatedReporting, OpenChallenge, Dispute, Finalized) - Report and challenge information retrieval - State transition validation

Resolution Stages

The OracleResolver implements a multi-stage workflow:

  1. Unreported (0): Initial state, no report submitted
  2. DesignatedReporting (1): Report submitted, within challenge period
  3. OpenChallenge (2): Report has been challenged
  4. Dispute (3): Escalated to UMA dispute resolution
  5. Finalized (4): Resolution complete, values finalized

Helper Functions

Oracle-Specific Helpers

// Complete unchallenged resolution workflow
await completeOracleResolution(oracleResolver, accounts, proposalId, passValue, failValue, evidence);

// Submit initial oracle report
await submitOracleReport(oracleResolver, reporter, proposalId, passValue, failValue, evidence);

// Challenge an existing report
await challengeOracleReport(oracleResolver, challenger, proposalId, counterPassValue, counterFailValue, counterEvidence);

// Complete resolution with challenge workflow
const resolution = await completeOracleResolutionWithChallenge(
  oracleResolver,
  accounts,
  proposalId,
  { passValue: 1000, failValue: 500, evidence: "Initial evidence" },
  { passValue: 800, failValue: 600, evidence: "Counter evidence" }
);

Running the Tests

# Run oracle integration tests only
npm run test:integration:oracle

# Run all integration tests
npm run test:integration

# Run with gas reporting
REPORT_GAS=true npm run test:integration:oracle

# Run specific test file
npx hardhat test test/integration/oracle/multi-stage-resolution.test.js

Test Results

All 14 integration tests pass successfully: 

✓ Should complete oracle resolution without challenge
✓ Should handle challenge and award bonds to challenger
✓ Should reject challenge after challenge period expires
✓ Should escalate to UMA dispute resolution
✓ Should reject escalation if not in challenge stage
✓ Should require correct bond amounts
✓ Should enforce designated reporter access
✓ Should enforce owner-only finalization
✓ Should handle multiple proposals at different stages
✓ Should prevent double reporting
✓ Should prevent double finalization
✓ Should accept empty evidence (evidence validation is off-chain)
✓ Should return correct resolution details at each stage
✓ Should return detailed report and challenge information

14 passing (706ms)

Bond Amounts

  • Reporter Bond: 100 ETH (REPORTER_BOND)
  • Challenger Bond: 150 ETH (CHALLENGER_BOND)
  • Challenge Period: 2 days (CHALLENGE_PERIOD)
  • Settlement Window: 3 days (SETTLEMENT_WINDOW)

Integration with System

The OracleResolver integrates with other system components:

  1. ProposalRegistry: Proposals are tracked and linked to oracle resolutions
  2. FutarchyGovernor: Proposal execution depends on oracle resolution outcomes
  3. ConditionalMarketFactory: Market settlement uses oracle resolution values

Security Considerations

✅ CodeQL Scan: No security vulnerabilities found ✅ Access Control: Designated reporter and owner-only functions properly enforced ✅ Reentrancy Protection: ReentrancyGuard modifier applied to sensitive functions ✅ Bond Management: Secure bond handling with validation and proper return mechanisms

Evidence Handling

Evidence is stored as bytes in the contract: - Evidence can be IPFS hashes, URLs, or any encoded data - On-chain validation is minimal (just storage) - Real validation happens off-chain by governance participants - Empty evidence is accepted (edge case test validates this)

Future Enhancements

Potential improvements for future phases:

  1. UMA Integration: Full integration with UMA's Optimistic Oracle V3
  2. Automated Finalization: Trustless finalization after challenge period
  3. Multi-Token Bonds: Support for bonds in different tokens
  4. Slashing Mechanism: More sophisticated slashing for malicious reporters
  5. Appeal Process: Additional dispute rounds beyond UMA

Changes Made

Modified Files

  1. test/integration/oracle/multi-stage-resolution.test.js (NEW)
  2. 14 comprehensive integration tests
  3. Tests all resolution stages and workflows

  4. Edge case coverage

  5. test/integration/helpers/index.js

  6. Updated completeOracleResolution() to match new signature
  7. Added submitOracleReport() helper
  8. Added challengeOracleReport() helper

  9. Added completeOracleResolutionWithChallenge() helper

  10. test/integration/fixtures/deploySystem.js

  11. Added reporter as designated reporter before ownership transfer

  12. Modified ownership transfer to keep OracleResolver under owner control for testing

  13. test/integration/README.md

  14. Documented oracle integration tests
  15. Updated coverage goals

  16. Added oracle-specific helper documentation

  17. package.json

  18. Added test:integration:oracle npm script

Conclusion

The Phase 3 integration tests provide comprehensive coverage of the Multi-Stage Oracle Resolution system, ensuring that:

  • All resolution stages work correctly
  • Bond management is secure and accurate
  • Access control is properly enforced
  • Edge cases are handled appropriately
  • Multiple proposals can be processed in parallel
  • Query functions provide accurate state information

All tests pass successfully, and no security vulnerabilities were found during the CodeQL scan.