EpochDistributor

struct EpochAllocation {
    uint256 score;      // CEOScore snapshot
    uint256 reward;     // Calculated $RUN reward (18 decimals)
    bool claimed;       // Whether already claimed
    address claimTo;    // Treasury address receiving $RUN
}
 
struct EpochInfo {
    uint256 epochNumber;
    uint256 startTime;
    uint256 endTime;
    uint256 rewardPool;     // Total $RUN available this epoch
    uint256 totalScore;     // Sum of all company scores
    uint256 totalClaimed;   // $RUN already claimed
    uint256 companyCount;   // Number of companies with allocations
    bool finalized;         // Whether scores have been submitted
}

/// @notice Submit CEOScore snapshots and finalize an epoch's allocations.
/// Only callable by the authorized oracle address.
/// @param epochNumber The epoch to finalize
/// @param companies Array of company addresses
/// @param scores Array of CEOScore values (matching companies array)
/// @param claimToAddresses Array of treasury addresses to receive $RUN
function finalizeEpoch(
    uint256 epochNumber,
    address[] calldata companies,
    uint256[] calldata scores,
    address[] calldata claimToAddresses
) external;

/// @notice Claim $RUN for a company in a finalized epoch.
/// Permissionless -- reward always goes to the registered treasury address.
/// @param epochNumber The epoch to claim from
/// @param company The company address to claim for
function claimReward(uint256 epochNumber, address company) external;
 
/// @notice Batch claim rewards across multiple epochs.
/// Skips non-finalized, already-claimed, and zero-reward epochs silently.
/// @param epochNumbers Array of epoch numbers
/// @param company The company address to claim for
function batchClaim(uint256[] calldata epochNumbers, address company) external;

/// @notice Get the current epoch number (auto-calculated from genesis).
function getCurrentEpoch() external view returns (uint256);
 
/// @notice Get detailed info about a specific epoch.
function getEpochInfo(uint256 epochNumber) external view returns (EpochInfo memory);
 
/// @notice Get a company's allocation in a specific epoch.
function getAllocation(uint256 epochNumber, address company)
    external view returns (EpochAllocation memory);
 
/// @notice Get the claimable $RUN amount (0 if claimed or no allocation).
function getClaimable(uint256 epochNumber, address company)
    external view returns (uint256 amount);

/// @notice Update the $RUN reward pool per epoch.
/// @param newRewardPool New pool amount (18 decimals)
function setRewardPool(uint256 newRewardPool) external;
 
/// @notice Update the epoch duration.
/// @param newDuration New duration in seconds
function setEpochDuration(uint256 newDuration) external;
 
/// @notice Update the oracle address.
/// @param newOracle New oracle address
function setOracle(address newOracle) external;

event EpochStarted(uint256 indexed epochNumber, uint256 startTime, uint256 rewardPool);
event EpochFinalized(uint256 indexed epochNumber, uint256 totalScore, uint256 companyCount);
event RewardClaimed(
    uint256 indexed epochNumber,
    address indexed company,
    address indexed claimTo,
    uint256 amount
);
event RewardPoolUpdated(uint256 oldPool, uint256 newPool);
event EpochDurationUpdated(uint256 oldDuration, uint256 newDuration);
event OracleUpdated(address indexed oldOracle, address indexed newOracle);

error EpochNotFinalized();       // Scores not yet submitted
error EpochAlreadyFinalized();   // Cannot re-finalize
error AlreadyClaimed();          // Double-claim prevention
error NoAllocation();            // Company not in this epoch
error UnauthorizedOracle();      // Caller is not the oracle
error ArrayLengthMismatch();     // companies.length != scores.length
error EmptyArrays();             // Zero-length input
error ZeroAddress();             // Invalid address
error ZeroAmount();              // Invalid amount or config
error EpochNotEnded();           // Cannot finalize mid-epoch

currentEpoch = (block.timestamp - genesisTimestamp) / epochDuration

startTime = genesisTimestamp + (epochNumber * epochDuration)
endTime   = genesisTimestamp + ((epochNumber + 1) * epochDuration)

companyReward = epochRewardPool * (companyScore / totalScoreSum)