Duration tiers, end to end

A pool can offer many lock terms. Each term carries its own advertised rate and its own payout schedule — "365 days at 10%, paid at the end" alongside "90 days at 8%, paid weekly" — on one pool, sharing one capacity budget.

Creating pools covers the authoring side: the form, the fields, the tier editor. This page is the rest of the contract — what the table holds, what the platform does with it at stake time, what a position freezes, and how to move an existing single-term pool onto tiers without disturbing the book.

The table

staking_durations, one row per term, soft-deleted like every other staking table.

Three constraints are enforced in the admin routes rather than in the schema, and it is worth knowing which:

• One term per lock period, per pool. Two 90-day tiers make "the 90-day rate" ambiguous everywhere downstream. There is a non-unique index on (poolId, lockPeriod) but no unique one, because the table is soft-deleted and MySQL treats NULL deletedAt values as distinct — a unique index would either admit two live rows or permanently block re-creating a retired term.
• At most one featured ACTIVE tier. MySQL has no partial index, so a UNIQUE (poolId, isFeatured) would allow exactly one non-featured tier per pool, which is the opposite of the rule.
• At most 24 tiers per pool. A guard against an unbounded payload.

The foreign key from staking_positions.durationId is RESTRICT: a tier holding user principal cannot be destroyed out from under its positions.

Which term the pool advertises

Resolution runs on read, in this order:

Rule 2 is the whole backward-compatibility story rather than a safety net. Every tier created before the flag existed has isFeatured false, so those pools resolve to their shortest term — which is exactly what they already advertised. Nothing needed backfilling and no pool changed behaviour by being upgraded.

Resolving on read rather than persisting the choice also means that retiring the featured term moves the headline to the next shortest by itself, with no write to go wrong and no window in which the pool advertises a term nobody can buy. The retired row keeps its flag, so reactivating it restores your original choice instead of silently discarding it.

The featured tier's apr, lockPeriod, earningFrequency and — when the tier sets one — autoCompound are mirrored onto the pool's own columns on every save. That is why the Pools table, the per-pool console, the landing page and any report reading pool.apr all show a rate the pool actually offers rather than one frozen at whatever preceded the tiers.

What terms a stake is opened under

resolveStakeTerms(pool, duration) is the single authority, and both the stake endpoint and the rewards calculator go through it.

With no tier (a pool that publishes none) it returns the pool's own lockPeriod, apr, earningFrequency, autoCompound, minStake, maxStake, adminFeePercentage and earlyWithdrawalFee. That is the pre-tier contract, unchanged.

With a tier:

The minimum and maximum a stake is checked against come from the resolved terms, not from the pool. A tier that raises the minimum to 5,000 rejects a 1,000 stake even though the pool's own minimum is 100.

durationId is required once a pool publishes tiers

POST /api/staking/position resolves the requested term before it does anything else, and it refuses to guess. Opening a 365-day lock for someone who meant to pick 30 days is a money decision made on the user's behalf.

The refusal on a multi-term pool, verbatim:

This pool offers 3 durations — select one to stake (durationId is required)

The count is the number of ACTIVE tiers. If an integration of yours posts stakes directly, this is the change that will break it the moment you add a second term to a pool.

There is one further check after resolution: a resolved term with a lock period below 1 day is refused with "This staking option has no valid lock period configured". Both the tier and the pool validate a minimum of 1, so this only fires on data that got in another way.

What a position freezes

On creation the position stores a full snapshot of the resolved terms:

The accrual engine reads position snapshot first, pool second — never through to the tier. That is deliberate: the tier is mutable and shared, so reading through to it would let you re-price a term and retroactively change every in-flight position opened under it, which is exactly the drift the snapshots prevent.

Before tiers existed, earningFrequency and autoCompound were read live from the pool. They are snapshotted now because a single pool can hold positions on different cadences, so "how often does this position pay" is no longer answerable from the pool at all.

A pool with zero tiers is a supported state

It is not a migration gap and there is nothing to fix. The pool's own lockPeriod, apr, earningFrequency and autoCompound are retained precisely so that a pool with no staking_durations rows behaves exactly as it did before the table existed: resolveStakeTerms falls back to them, the stake endpoint asks for no durationId, and every read surface renders one coherent headline.

The tier editor says as much when the list is empty — "This pool offers one term, from Staking Details".

What a staker is shown

Both user-facing pool endpoints attach the ACTIVE tiers and a summary:

• GET /api/staking/pool — every ACTIVE pool, each with durations (ACTIVE only, serialised) and durationSummary.
• GET /api/staking/pool/{id} — the same, plus the caller's own positions.

durationSummary is summarizeDurations over the ACTIVE tiers and carries count, aprMin, aprMax, lockPeriodMin and lockPeriodMax. It is null when the pool publishes no tiers, which is the signal for a client to fall back to the pool's single APR and lock period rather than print an empty range. It is what turns a five-tier pool into one line on a card:

8% – 10% APR over 90 – 365 days

The reward calculator quotes one row per (pool, tier) pair rather than one per pool, so a user typing an amount sees a figure for each term they could actually get it on. Each quote carries durationId — null for a tier-less pool — which is what the client sends straight back as the stake payload. A term longer than the horizon the user asked about is omitted from the quote entirely; a 365-day term cannot pay a 90-day reward.

The staking form opens on the featured term, and a staker picks a term before an amount, because the minimum, the fees and the payout schedule can all change with it.

Retiring a tier versus deleting one

The tier editor's trash icon simply drops the row from the payload you save. The server then decides which of two things that means:

The count is taken with soft-deleted positions included, so a tier that was ever used is never destroyed. Positions snapshot their own terms, but the row still backs their history, and the FK is RESTRICT — deleting it would either fail the whole save or orphan a user's record of what they agreed to. The response reports the retained tiers with their lock period and position count.

Retiring on purpose is the Open to new stakes checkbox under a tier's Advanced panel. Unticking it sets INACTIVE: the term disappears from the staking form, drops out of durationSummary and the pool's advertised range, and stops being stakeable — while every position already opened under it keeps running to maturity untouched.

Tiers are matched by id, never by position in the array or by lock period. Sending an id that belongs to a different pool is refused with durations: tier <id> does not belong to this pool rather than quietly moving that pool's tier under this one.

One more distinction worth knowing if you script against the pool update endpoint: omitting durations entirely leaves the tiers alone; sending an explicit empty array (or null) clears them. Those cannot be collapsed, which is why the payload cannot simply default to [].

Migrating an existing single-term pool

The pool keeps working throughout. Nothing here touches live positions, because every one of them carries its own snapshot.

Where tiers show up in the admin

The tiers are not currently a column on the admin Positions table; they are in the payload. A position's real terms are its own snapshot in any case — the tier row tells you which term it was bought on, not what it pays.