# Rewards

The private messaging system includes a reward mechanism that distributes native COTI based on message activity.

## How rewards work

Rewards are tracked in 14-day epochs. Every encrypted cell generated by private messages contributes usage units to the sender's account for that epoch.

At the end of an epoch, the funded reward pool is distributed proportionally across participants.

```
claimable = rewardPool × myUsageUnits / totalUsageUnits
```

## Core functions

The SDK exposes the following reward helpers:

* `getCurrentEpoch()`
* `getEpochForTimestamp()`
* `getContractConfig()`
* `getEpochUsage()`
* `getEpochSummary()`
* `getPendingRewards()`
* `claimRewards()`
* `fundEpoch()`

## Checking reward status

Use these calls when you want to inspect current or historical rewards:

```typescript
import {
  getCurrentEpoch,
  getEpochUsage,
  getEpochSummary,
  getPendingRewards
} from "@coti-io/coti-sdk-private-messaging";

const currentEpoch = await getCurrentEpoch(client);
const closedEpoch = currentEpoch - 1n;

const usage = await getEpochUsage(client, closedEpoch, wallet.address);
const summary = await getEpochSummary(client, closedEpoch);
const pending = await getPendingRewards(client, closedEpoch, wallet.address);
```

`getEpochUsage()` returns:

* `usageUnits`
* `totalUsageUnits`
* `pendingRewards`
* `hasClaimed`

`getEpochSummary()` returns:

* `totalUsageUnits`
* `rewardPool`
* `claimedAmount`
* `claimedUsageUnits`

## Claiming rewards

Rewards can only be claimed for closed epochs.

```typescript
import { claimRewards } from "@coti-io/coti-sdk-private-messaging";

const result = await claimRewards(client, {
  epoch: closedEpoch
});
```

The SDK performs preflight checks before broadcasting:

* the epoch must be earlier than the current epoch
* the configured wallet must not have already claimed that epoch
* the wallet must have rewards available to claim

The result includes:

* `transactionHash`
* `amount`

## Funding an epoch

Anyone can fund the reward pool for the current epoch or a future epoch:

```typescript
import { fundEpoch } from "@coti-io/coti-sdk-private-messaging";

const txHash = await fundEpoch(client, {
  epoch: currentEpoch,
  amountWei: 1000000000000000000n
});
```

`fundEpoch()` rejects:

* zero-value funding amounts
* past epochs

## Contract configuration

Use `getContractConfig()` when you need the contract-level limits:

* `owner`
* `epochDuration`
* `genesisTimestamp`
* `maxChunkCells`
* `maxChunksPerMessage`

This is useful when you want to inspect the deployed reward and chunking configuration without hardcoding assumptions.

## Important notes

* epochs are 14 days long
* rewards are pull-based, not automatic
* usage is based on encrypted cell count, not just logical message count
* the last claimant can receive the rounding remainder
* the full reward pool is distributed across claimants for the epoch