# Rewards
Documentation: next (source: develop).

Install the preview: `pnpm add @aephia/atlas-kit@next`. These docs follow develop and may include changes not yet published to npm.

> ATLAS reward configuration, treasuries, and commitments.

Markdown source of https://develop.atlas-kit-docs.pages.dev/guides/rewards/ — see https://develop.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

Rewards covers where ATLAS comes from: the configuration that governs emission,
the treasuries that hold it, and the commitments against it. Capability-only
entry.

```ts
import {
  getAtlasRewardConfig,
  getAtlasRewardTreasury,
} from '@aephia/atlas-kit/rewards';
```

:::game[ATLAS rewards come from a funded reward pool]
When the ATLAS token was first created, a fixed amount was earmarked for future
player rewards. Gameplay rewards are paid from this existing pool; the game does
not create new ATLAS each time a player earns a reward. Reward rules decide which
activities can earn from the pool and how much can be paid. Those rules can
change over time, so the game keeps numbered versions of them. The game can also
record a reward for a player before its final payout has happened.
:::

## Configuration is versioned

Reward configuration changes over time, and reading the wrong version gives you
numbers that were true once:

```ts
const registry = await getAtlasRewardRegistry(ctx);
const version = selectAtlasRewardConfigVersion(registry, epoch);
const config = await getAtlasRewardConfig(ctx, version);
```

Selecting a version is explicit rather than implicit. The SDK will not silently
pick one for you, because "the current config" is a question with a
time-dependent answer, and guessing it wrong produces plausible numbers that
are quietly incorrect.

> **Runnable example — Read the ATLAS reward state.** The reward registry current epoch, active config, and treasury. Run it in the browser at https://develop.atlas-kit-docs.pages.dev/guides/rewards/.

## Treasuries and commitments

```ts
const treasury = await getAtlasRewardTreasury(ctx);
const commitment = await maybeGetRewardCommitment(ctx, lootAddress);
```

`maybe` again: a commitment that was never made is absent rather than an error.

## Gotchas

**Do not cache a config across a version change.** It will keep answering, with
the previous rules.

**ATLAS amounts are `bigint`.** These are among the largest numbers in the game;
`number` will lose precision.

**Reward state and loyalty banks are different things.** [Loyalty points](/guides/loyalty/)
tracks contributions and their accumulated bank. This entry covers the reward
system those draw from.

## Reference

- [`rewards`](/reference/rewards/) — every export in this entry
- [`loyalty`](/guides/loyalty/) — contributions and banks
- [`combat`](/guides/combat/) — loot, the other thing combat leaves behind