The battlepass and the item mall

Status#

These are the platform’s two THD sinks: the only contracts where a user spends THD and the supply falls. Everything else in the reward layer pays THD out. The battlepass is also the largest destination of the Spoils user pool — 5,000 bps of it at construction. See Spoils.

A season is a calendar quarter#

A season is a fixed calendar quarter beginning 1 January, 1 April, 1 July and 1 October, UTC. There is no season-duration constant and nothing an owner can move: the index is year × 4 + (quarter − 1), derived from block.timestamp by the same civil-date routine ProtocolFeeSplitter uses.

The two points boards: Spending and Earnings#

// lib/points/formula.ts — dayPoints, once per board
a board's day points = the board's measure       // Spending, or Earnings
                       × (checked in that day ? 1 : 0)
                       × streak multiplier       // 1 + 0.5 × min(1, (days ÷ 20)^0.7)
                       × premium multiplier      // 1.25 while a pass is held, else 1

// lib/points/net-buying.ts
net   = Σ ETH paid on buys − Σ ETH received on sells and redeems   // per wallet, per launch
close = net at the end of the UTC day
spending = max(0, close − highest earlier close)                   // the high never falls

Premium, and why the payment is burned#

The price is pro-rated by the days left in the month and rounds down, in the buyer’s favour:

// Battlepass.quotePremium
price = premiumMonthlyPriceThd * daysRemaining * (10_000 - discountBps)
      / (daysInMonth * 10_000);

Waiting therefore does not save money, it buys less. The one approved milestone discount is 5,000 bps — 50% off one month’s pass, at day 30, proved against a second Merkle root published per season, spent once a season, and reserving nothing.

Because the payment is destroyed, premium is deflation, not revenue. It never reaches totalProtocolFeesReceived and it unlocks no THD. Trading contributes fees, which the meter counts; buying premium contributes burn, which the meter never sees. The two are not interchangeable and must never be added together. See THD and the fee meter.

Claiming, and the 25% late penalty#

Rewards are committed as one cumulative Merkle root per season, republishable as often as daily. Per-account progress is a running total in claimedOf[seasonIndex][account], and a claim pays the delta — which is what makes the root republishable without a per-claim bitmap. The leaf is keccak256(abi.encode(seasonIndex, account, cumulative)).

totalThdBurned() is the three burn counters combined — totalPremiumBurned, totalLateClaimBurned and totalExpiredBurned. A root may never allocate more than the contract holds: publishRewards checks the new outstanding against available() plus the season’s existing outstanding, so an over-allocation reverts at publication rather than at the last claimant.

The owner Safe publishes both roots itself. There is no keeper role on the battlepass.

The item mall#

The mall sells typed items whose effect must be one of six — Cosmetic, Access, Qualifier, Credit, Consumable, Boost. There is no seventh, and adding one is the change the contract exists to refuse. Delivery is a row in a balance mapping plus an event: no hook, no callback, no delegatecall.

The three milestone legs each round down and the remainder is carried into the next sale in the same currency rather than swept or re-attributed; sweepStrandedEth subtracts the carried dust so a sweep can never take it.

How a mall price is computed#

ItemPricing is not a bonding curve, not a decay and not an oracle. It is a fixed unit price with exactly one discount, and it is stateless — the mall calls it as a staticcall, and a module is swapped rather than edited.

// ItemPricing.quote — multiply first, divide once
total = unitPrice * quantity * (10_000 - discount) / (scale * 10_000);

One truncation, at the end, in the buyer’s favour; the remainder is never charged. scale is 1 for a countable item and 10 ** decimals for a token package.

Taking the larger of two discounts was considered and rejected: adding a discount that stacks is not a pricing change, it is a policy change.

The mall’s discount bounds#

If premiumRegistry is unset, nobody is premium and everybody pays list price — an unset pointer degrades to the undiscounted price rather than to a free one.

Three things that must never be added#

Both contracts carry the same three prohibitions in their own source, and they are design rules rather than implementation notes:

The 1.25× multiplier is the single permitted exception to activity-weighted rewards, and it is permitted because the payment is burned and it is capped: its value to the buyer decays to zero as adoption rises, at which point the whole cohort has burned THD for nothing but the burn. It is not a precedent for a second lever.