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:

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.

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:

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 timing and chunk limits:

• 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