Loyalty

Loyalty tracks what a player has contributed to their faction over a period, and what that has accumulated. Capability-only entry.

import {
  getLoyaltyEpoch,
  getLoyaltyContributionsByProfile,
} from '@aephia/atlas-kit/loyalty';

A loyalty epoch is one reward round

A loyalty epoch is a fixed period in which players earn points for helping their faction. Every UTC day, the game sets aside a small part of the player reward treasury for each faction. How much a faction receives that day depends on how many starbases it controls at the end of the day. Certain activities earn loyalty points for players during the epoch. When the epoch ends, those points automatically determine each player’s share of their faction’s ATLAS reward.

Epochs bound everything

A loyalty epoch is a window. Contributions belong to one, and reading a contribution without knowing its epoch tells you less than it looks like it does.

const epochs = await getLoyaltyEpochsByFaction(ctx, factionId);
const contributions = await getLoyaltyContributionsByProfile(
  ctx,
  profileAddress,
);

Lifecycle is projected

An epoch’s state — upcoming, running, concluded — is derived deterministically from the epoch’s own timing rather than read from a status field. The SDK computes it so that every consumer computes it the same way, rather than each application inventing slightly different boundary handling.

ATLAS banks

Accumulated rewards sit in a bank:

const bank = await maybeGetLoyaltyAtlasBank(ctx, profileAddress, factionId);

maybe because a profile that has never contributed has no bank. Absence is an answer.

Gotchas

Contributions are per epoch. Summing across epochs is your job, and whether that sum is meaningful depends on what you are asking.

Amounts are bigint. ATLAS values in particular are large.

A concluded epoch still reads. Its data does not disappear when it ends. Check the projected lifecycle rather than assuming a readable epoch is the current one.

Reference

• loyalty — every export in this entry
• factions — the faction being contributed to
• rewards — the other ATLAS-denominated capability