Epoch Rewards

currentEpoch = (block.timestamp - genesisTimestamp) / epochDuration

companyReward = epochRewardPool * (companyScore / totalScoreSum)

// Finalize an epoch with company scores (oracle only, one tx)
function finalizeEpoch(
    uint256 epochNumber,
    address[] calldata companies,
    uint256[] calldata scores,
    address[] calldata claimToAddresses
) external;

// Claim $RUN for a single epoch (permissionless)
function claimReward(uint256 epochNumber, address company) external;
 
// Batch claim across multiple epochs
function batchClaim(uint256[] calldata epochNumbers, address company) external;

// Current epoch number (genesis-relative)
function getCurrentEpoch() external view returns (uint256);
 
// Full epoch metadata
function getEpochInfo(uint256 epochNumber) external view returns (EpochInfo memory);
 
// Individual company allocation for an epoch
function getAllocation(uint256 epochNumber, address company)
    external view returns (EpochAllocation memory);
 
// Claimable $RUN for a company in a specific epoch
function getClaimable(uint256 epochNumber, address company)
    external view returns (uint256 amount);

struct EpochInfo {
    uint256 epochNumber;
    uint256 startTime;
    uint256 endTime;
    uint256 rewardPool;     // $RUN pool for this epoch
    uint256 totalScore;     // Sum of all company scores
    uint256 totalClaimed;   // $RUN claimed so far
    uint256 companyCount;   // Number of participating companies
    bool finalized;         // Whether scores have been submitted
}
 
struct EpochAllocation {
    uint256 score;          // Company's CEOScore snapshot
    uint256 reward;         // Calculated $RUN reward amount
    bool claimed;           // Whether reward has been claimed
    address claimTo;        // Treasury address for $RUN mint
}

1. Read getCurrentEpoch() from contract
2. epochToFinalize = currentEpoch - 1
3. Idempotency check: skip if already finalized on-chain or in DB
4. Query CEOScoreSnapshot records from the last epoch window
5. Filter companies with valid treasury addresses
6. Call finalizeEpoch() with company arrays
7. Create RevenueEpoch DB record (finalized=true)
8. Create pending RevenueClaim records (txHash=null until claimed)

Week 1 (Epoch 0):
  - Companies operate, build CEOScore
  - Epoch 0 ends at genesis + 7 days

Week 2 (Epoch 1 starts):
  - Backend cron detects currentEpoch = 1
  - Finalizes Epoch 0 with CEOScore snapshots
  - Companies can now claim Epoch 0 rewards
  - Companies continue building CEOScore for Epoch 1

Week 3 (Epoch 2 starts):
  - Finalize Epoch 1, companies claim
  - ... and so on

import { useReadContract } from 'wagmi';
 
const EPOCH_DIST = '0x9f96314b2c2b1Cbb7e104D50f7ce5686775D4759';
 
const { data: claimable } = useReadContract({
  address: EPOCH_DIST,
  abi: epochDistributorAbi,
  functionName: 'getClaimable',
  args: [epochNumber, companyAddress],
});

import { useWriteContract } from 'wagmi';
 
const { writeContract } = useWriteContract();
 
await writeContract({
  address: EPOCH_DIST,
  abi: epochDistributorAbi,
  functionName: 'claimReward',
  args: [epochNumber, companyAddress],
  dataSuffix: '0x6263375f376e69346a756a39',
});

await writeContract({
  address: EPOCH_DIST,
  abi: epochDistributorAbi,
  functionName: 'batchClaim',
  args: [[0n, 1n, 2n], companyAddress], // claim epochs 0, 1, 2
  dataSuffix: '0x6263375f376e69346a756a39',
});

const { data: epochInfo } = useReadContract({
  address: EPOCH_DIST,
  abi: epochDistributorAbi,
  functionName: 'getEpochInfo',
  args: [epochNumber],
});
 
// epochInfo.finalized, epochInfo.rewardPool, epochInfo.totalScore, etc.