API Reference

Complete reference for the POPRegistry contract - all public functions, structs, enums, and events.

Enums Structs Lifecycle Disputes View Functions Events

Enums

POPState

States a POP transitions through during its lifecycle:

enum POPState {
    NONE,              // Default/uninitialized
    PENDING,           // Created, awaiting resolver approval
    REJECTED,          // Resolver rejected during creation
    ACTIVE,            // Approved, ready for resolution
    RESOLVING,         // Outcome proposed, dispute window open
    DISPUTED_ROUND_1,  // TruthKeeper reviewing
    DISPUTED_ROUND_2,  // Admin/Community reviewing
    RESOLVED,          // Final outcome set, immutable
    CANCELLED          // Admin cancelled
}

AnswerType

Types of answers a POP can produce:

enum AnswerType {
    NONE,      // Default/uninitialized
    BOOLEAN,   // True/False - abi.encode(bool)
    NUMERIC,   // int256 - abi.encode(int256)
    GENERIC    // Arbitrary bytes data
}

AccountabilityTier

Trust level snapshot at POP creation:

enum AccountabilityTier {
    NONE,            // Default
    PERMISSIONLESS,  // No guarantees
    TK_GUARANTEED,   // TruthKeeper guarantees response
    SYSTEM           // Full system accountability
}

DisputeResolution

Options for resolving disputes:

enum DisputeResolution {
    UPHOLD_DISPUTE,  // Disputer wins, override outcome
    REJECT_DISPUTE,  // Original outcome stands
    CANCEL_POP,      // POP is invalid, refund bonds
    TOO_EARLY        // Event hasn't occurred, return to ACTIVE
}

ResolverTrust

Trust levels for resolvers:

enum ResolverTrust {
    NONE,           // Not registered
    PERMISSIONLESS, // Registered, no system guarantees
    VERIFIED,       // Admin reviewed
    SYSTEM          // Full system backing
}

Structs

ExtensiveResult

Result with full resolution context - the primary struct for consumers:

struct ExtensiveResult {
    AnswerType answerType;       // Type of answer
    bytes result;                // ABI-encoded result
    bool isFinalized;            // State == RESOLVED
    bool wasDisputed;            // Had a dispute filed
    bool wasCorrected;           // Dispute upheld, result changed
    uint256 resolvedAt;          // Resolution timestamp
    AccountabilityTier tier;     // Accountability tier
    ResolverTrust resolverTrust; // Resolver trust level
}

POP

Core POP data stored in the registry:

struct POP {
    address resolver;
    POPState state;
    AnswerType answerType;
    uint256 resolutionTime;

    // Time windows (user-specified)
    uint256 disputeWindow;
    uint256 truthKeeperWindow;
    uint256 escalationWindow;
    uint256 postResolutionWindow;

    // Computed deadlines
    uint256 disputeDeadline;
    uint256 truthKeeperDeadline;
    uint256 escalationDeadline;
    uint256 postDisputeDeadline;

    address truthKeeper;
    AccountabilityTier tierAtCreation;
}

DisputeInfo

Information about a dispute:

struct DisputeInfo {
    DisputePhase phase;           // PRE_RESOLUTION or POST_RESOLUTION
    address disputer;
    address bondToken;
    uint256 bondAmount;
    string reason;
    string evidenceURI;           // IPFS/Arweave link
    uint256 filedAt;
    uint256 resolvedAt;
    bool resultCorrected;
    bytes proposedResult;
    DisputeResolution tkDecision;
    uint256 tkDecidedAt;
}

POP Lifecycle Functions

createPOP

Creates a new Prediction Option Protocol:

function createPOP(
    address resolver,
    uint32 templateId,
    bytes calldata payload,
    uint256 disputeWindow,
    uint256 truthKeeperWindow,
    uint256 escalationWindow,
    uint256 postResolutionWindow,
    address truthKeeper
) external returns (uint256 popId)

Parameter	Type	Description
`resolver`	address	Resolver contract address
`templateId`	uint32	Template ID within the resolver
`payload`	bytes	ABI-encoded creation parameters
`disputeWindow`	uint256	Pre-resolution dispute window (seconds)
`truthKeeperWindow`	uint256	Time for TK to decide Round 1
`escalationWindow`	uint256	Time to challenge TK decision
`postResolutionWindow`	uint256	Post-resolution dispute window
`truthKeeper`	address	TruthKeeper for this POP

resolvePOP

Proposes a resolution for a POP:

function resolvePOP(
    uint256 popId,
    address bondToken,
    uint256 bondAmount,
    bytes calldata payload
) external payable

Note: Requires bond if dispute window > 0. Use address(0) for native ETH.

finalizePOP

Finalizes a POP after dispute window expires:

function finalizePOP(uint256 popId) external

Dispute Functions

dispute

Disputes a proposed or finalized resolution:

function dispute(
    uint256 popId,
    address bondToken,
    uint256 bondAmount,
    string calldata reason,
    string calldata evidenceURI,
    bytes calldata proposedResult
) external payable

resolveTruthKeeperDispute

TruthKeeper resolves a Round 1 dispute:

function resolveTruthKeeperDispute(
    uint256 popId,
    DisputeResolution resolution,
    bytes calldata correctedResult
) external

challengeTruthKeeperDecision

Challenges TK decision, escalates to Round 2:

function challengeTruthKeeperDecision(
    uint256 popId,
    address bondToken,
    uint256 bondAmount,
    string calldata reason,
    string calldata evidenceURI,
    bytes calldata proposedResult
) external payable

resolveEscalation

Admin resolves a Round 2 escalation:

function resolveEscalation(
    uint256 popId,
    DisputeResolution resolution,
    bytes calldata correctedResult
) external onlyOwner

View Functions

getExtensiveResult

Gets result with full resolution context. Recommended for consumers.

function getExtensiveResult(uint256 popId)
    external view returns (ExtensiveResult memory)

getPOP

Gets core POP data:

function getPOP(uint256 popId)
    external view returns (POP memory)

getResult

Gets the ABI-encoded result:

function getResult(uint256 popId)
    external view returns (bytes memory)

isFullyFinalized

Checks if POP is fully finalized (all dispute windows closed):

function isFullyFinalized(uint256 popId)
    external view returns (bool)

hasCorrectedResult

Checks if result was corrected via dispute:

function hasCorrectedResult(uint256 popId)
    external view returns (bool)

calculateAccountabilityTier

Calculates tier for a resolver + TK combination:

function calculateAccountabilityTier(
    address resolver,
    address tk
) external view returns (AccountabilityTier)

getDisputeInfo

Gets dispute information for a POP:

function getDisputeInfo(uint256 popId)
    external view returns (DisputeInfo memory)

getResolverTrust

Gets resolver's trust level:

function getResolverTrust(address resolver)
    external view returns (ResolverTrust)

Events

POP Lifecycle

event POPCreated(
    uint256 indexed popId,
    address indexed resolver,
    ResolverTrust trust,
    uint32 templateId,
    AnswerType answerType,
    POPState initialState,
    address indexed truthKeeper,
    AccountabilityTier tier
);

event POPResolutionProposed(
    uint256 indexed popId,
    address indexed proposer,
    AnswerType answerType,
    uint256 disputeDeadline
);

event POPFinalized(uint256 indexed popId, AnswerType answerType);

event POPCancelled(uint256 indexed popId, string reason);

Disputes

event POPDisputed(
    uint256 indexed popId,
    address indexed disputer,
    string reason
);

event TruthKeeperDisputeResolved(
    uint256 indexed popId,
    address indexed tk,
    DisputeResolution resolution
);

event TruthKeeperDecisionChallenged(
    uint256 indexed popId,
    address indexed challenger,
    string reason
);

event EscalationResolved(
    uint256 indexed popId,
    DisputeResolution resolution,
    address indexed admin
);

Bonds

event ResolutionBondDeposited(
    uint256 indexed popId,
    address indexed proposer,
    address token,
    uint256 amount
);

event BondSlashed(
    uint256 indexed popId,
    address indexed from,
    address token,
    uint256 amount
);