Holder Rewards

Holder rewards are paid in the Pair Asset. When a settlement acquires the Pair Asset for a Pair Market, part of the market’s unallocated Pair Asset balance is released into a Reward EpochReward EpochA window over which acquired Pair Asset is allocated to eligible holders by their holder weight. Produces exact integer allocations and a Merkle root.. The epoch measures who held the token, for how long and in what size, then turns that measurement into an allocation per wallet.

The epoch covers the window since the market’s previous settlement (or since the market was created, for its first epoch) up to the moment the current settlement completes. With the default hourly cadence, that is one hour of holding. The release size is a configured share of the unallocated balance:

Each epoch is written to the ledger table reward_epochs. These are its real fields:

id

Primary key of the epoch.

pairMarketId

The Pair Market whose holders the epoch rewards.

epochNumber

Sequence number per Pair Market, starting at 1.

startAt / endAt

The holding window measured by the epoch.

methodology

time_weighted_balance, average_balance or snapshot_min_hold.

rewardInstrumentId

The Pair Instrument whose Pair Asset the epoch distributes.

totalPoolRaw

The pool in the Pair Asset’s raw base units. Allocations sum to exactly this value.

totalPoolUsd

The pool valued at the settlement’s execution price.

eligibleHolderCount

Holders with a positive weight after exclusions and thresholds.

totalWeight

Σ holder weight. Stored as an integer (numeric 60,0).

allocationRoot

Hex Merkle root over every (wallet, amountRaw) allocation.

status

open, calculating, allocated, finalized.

ledgerMode

live or dev_simulated, inherited from the settlement plan.

Per-wallet results land in reward_allocations (epochId, wallet, weight, amountRaw, usdValue, status). An allocation starts as claimable and becomes claimed when a claim settles it. Claims themselves are rows in reward_claims.

A naive snapshot reads every balance at one instant and divides the pool by those balances. It rewards whoever holds at that instant, regardless of what happened before. A wallet can buy a large position seconds before the snapshot, collect most of the pool, and sell immediately after.

Time weighting closes that gap. A holder’s Holder WeightHolder WeightA holder's share basis inside a reward epoch. Under the time-weighted method: the integral of balance over time held inside the epoch (token-seconds). is the area under its balance curve inside the epoch: balance multiplied by time held. A large balance held for two seconds produces a small area. A modest balance held for the whole epoch produces a large one.

The arithmetic behind the time-weighted view:

The snapshot gives Wallet B 10,000 / 10,400 of the pool, which is 961.54 units. Time weighting gives it 1.00. Wallet A, the holder who was present for the entire epoch, moves from 9.62 units to 399.60.

Each Pair Market declares one methodology in its configuration (rewardMethodology). All three are implemented as pure functions in src/server/pair/rewards.ts and covered by tests. Each one receives the holder balance timeline as segments (wallet, balanceRaw, from, to), clips every segment to the epoch window, and returns an integer weight per wallet.

Wallet B in the figure above earns nothing under snapshot_min_hold: it held for 2.16 seconds of an 86,400-second epoch, far short of the 21,600 seconds that 25% requires. Wallets A and C qualify and are weighted by their closing balances, 100 and 300.

Exclusions

Before any weight is computed, the engine removes wallets that hold tokens for structural reasons rather than as holders. Each exclusion carries a reason, and the epoch result lists every excluded wallet with that reason.

• ·creator: the creator wallet, when the market’s excludeCreator setting is on (the default).
• ·vault: the Pair Vault address. Always excluded.
• ·liquidity: holder rows tagged as liquidity accounts, such as the bonding curve’s token account, when excludeLiquidityAccounts is on (the default).
• ·configured: any address in the market’s excludedWallets list.

The Pair Asset is a token with fixed decimals, so allocations are integers in raw base units. Proportional shares are almost never whole numbers. Rounding every share down leaves units unallocated; rounding to nearest can allocate more than the pool. The engine uses the largest-remainder method, which allocates the pool exactly.

/**
 * Largest-remainder allocation: floor every share, then hand the leftover units to the
 * largest fractional remainders (ties broken by wallet for determinism). Σ amount === pool.
 */
export function allocatePool(pool: bigint, weights: Map<string, bigint>): Allocation[];

1. 01Multiply the pool by each weight and divide by the total weight. Keep the integer quotient (the floor) and the remainder.
2. 02Subtract the sum of floors from the pool. The difference is the number of leftover units, always fewer than the number of holders.
3. 03Sort holders by remainder, largest first. Equal remainders are ordered by wallet address so the result is deterministic.
4. 04Give one leftover unit to each holder in that order until none remain.

The tests assert Σ allocations == pool for every case, that an empty pool or zero total weight yields no allocations, and that the output is identical regardless of the order in which holders are supplied. Wallets whose final amount is zero are dropped from the allocation list.

Every finalized epoch carries an allocationRoot: the root of a Merkle tree whose leaves are the epoch’s allocations. The root commits to the full allocation table in 32 bytes. Anyone holding the table can recompute it, and any single allocation can be proven against it with a short proof.

• ·Leaf: SHA-256 of the UTF-8 string wallet:amountRaw, for example <wallet>:400.
• ·Tree: leaves are sorted; each parent is SHA-256 of its two children concatenated smaller-first (a sorted-pair tree, so proofs need no left or right flags). An odd node at the end of a level is carried up unchanged.
• ·Proof: the list of sibling hashes from leaf to root. verifyProof folds them with the same sorted-pair rule and compares the result to the root.

// src/server/pair/rewards.ts
export function leafHash(wallet: string, amountRaw: bigint): Buffer {
  return sha256(Buffer.from(`${wallet}:${amountRaw.toString()}`, "utf8"));
}

/** Sorted-pair Merkle tree (order-independent siblings), hex root. */
export function merkleRoot(leaves: Buffer[]): string;
export function merkleProof(leaves: Buffer[], target: Buffer): string[];
export function verifyProof(leaf: Buffer, proof: string[], root: string): boolean;

The tests build an epoch, compute its root and verify a proof for every allocation. The root is what an onchain Merkle distributor checks a claim against, which is how live claims pay out of the Pair Vault without trusting PairStreet’s database. See Accounting for how allocations reconcile against the vault.

A claim moves a holder’s allocated Pair Asset from the Pair Vault to the holder’s wallet. The flow checks eligibility before anything is written, and pays each allocation once.

The allocation update is conditional on status = claimable and runs in the same database transaction as the claim row. If the number of rows updated differs from the number expected, the whole transaction rolls back and the holder retries. A second claim for the same allocations finds nothing claimable. The tests cover all three: a restricted region is rejected, a valid claim pays the exact claimable amount, and a repeat claim pays nothing.

Eligibility is enforced at claim time as well as at launch. A holder in a region the Pair Instrument restricts keeps the token and can trade it; rewards from that Pair are claimable from an eligible region. The rules are described in Eligibility.

Holder rewards are built in three layers, and each one has its own activation path.