Pawn

Documentation

Epochs & Claiming

Epochs are the fundamental time unit of the ERC-5D reward system. Each epoch defines a window during which rewards accumulate, and the conclusion of an epoch triggers a distribution to all qualifying NFT holders. After distribution, each holder has a fixed window to claim their share.

What is an epoch?

An epoch is a time period of four hours. The epoch clock starts from a fixed anchor timestamp set when the Treasury contract is initialized. Each epoch has a sequential index, starting at 0. The current epoch index is readable on-chain at any time through the currentEpoch() view function on the PawnTreasury contract.

During an epoch, ETH from trading activity accumulates in the Treasury. PAWN from the Phalanx reserve is also allocated at the configured emission rate, to be distributed at epoch close. At the four-hour boundary, the epoch concludes and distribution becomes available.

The epoch duration can be adjusted by the contract owner. Any duration change resets the epoch anchor to the current timestamp, starting a new clean cycle from the point of change.

Epoch distribution

Completed epochs do not distribute automatically on their own. A trigger transaction is required in one of two ways:

  • Manual (owner)

    The owner calls distributeEpoch() on PawnTreasury. This distributes all completed-but-undistributed epochs in one call.

  • Auto-distribute mode (optional)

    If the owner has enabled autoDistribute, the distribution runs automatically inside receiveETH() on each sell-triggered tax swap. This mode is off by default and must be explicitly enabled by the owner.

At distribution, the contract snapshots tier weights and computes per-NFT reward units for both the ETH and PAWN streams. Entitlements are stored in on-chain accumulators and become claimable for 24 hours. Either way, the reward accounting and entitlement computation are identical.

The timestamp of each epoch distribution is recorded on-chain via epochDistributedAt(epochIndex). This timestamp is the reference point for computing the 24-hour claim window.

The 24-hour claim window

After an epoch is distributed, each holder has exactly 24 hours to claim their reward share from that epoch. The window opens at the moment of distribution (epochDistributedAt) and closes 24 hours later.

Rewards from epochs whose 24-hour window has closed are forfeited for that holder. The claim() function advances the holder's cursor past any expired epochs silently; those rewards become permanently uncollectable by that holder. Claiming regularly, at least once per day when you have active Pawns, is important.

Holders can claim across multiple epochs in a single claim() transaction. If you have pending rewards from epochs 10, 11, and 12 (all within their respective windows), one claim() call settles all three.

How to claim

Claiming is done through the app at /app. Connect your wallet. If you hold NFTs and have unclaimed rewards within open windows, the dashboard will display your pending ETH and PAWN amounts alongside which epoch indices are currently claimable. The Claim Rewards button initiates a claim() call to the PawnTreasury contract.

Advanced users can also call claim() directly on the PawnTreasury contract using any Base interface: BaseScan, a custom script, or any wallet with contract interaction capability. The function takes no arguments and is not payable. It settles all in-window unclaimed epochs for the calling address in a single transaction.

The pendingRewards(address) view function on PawnTreasury returns the current pending ETH and PAWN amounts for any address at any time. This is the authoritative real-time figure for pending claims.

Epoch state on-chain

All epoch state is readable on-chain through view functions on the PawnTreasury contract:

  • currentEpoch()

    Returns the current epoch index as a uint256.

  • epochDuration()

    Returns the duration of each epoch in seconds.

  • epochAnchor()

    Returns the unix timestamp of epoch 0 start, used to compute epoch boundaries.

  • epochDistributedAt(epochIndex)

    Returns the unix timestamp at which a given epoch was distributed.

  • lastDistributedEpoch()

    Returns the index of the most recently distributed epoch.

  • pendingRewards(address)

    Returns the pending ETH and PAWN reward amounts for a given address.