Prime leaderboard

PrimeLeaderboard

PrimeLeaderboard manages Prime V2 eligibility with time-weighted scoring. It tracks per-deposit timestamps for LIFO withdrawals and computes each user’s Prime Score. It is called by the XVSVault via the existing xvsUpdated() callback. Governance reads getEffectiveStakeBatch() off-chain, ranks users by Prime Score, and either sets a mint threshold on PrimeV2 (for permissionless minting) or calls PrimeV2.issue() / burn() directly.

Solidity API

constructor

Sets immutable XVS Vault references and disables initialization on the implementation.

constructor(address xvsVault_, address xvsVaultRewardToken_, uint256 xvsVaultPoolId_)

xvsVault

Address of XVSVault contract

address xvsVault

xvsVaultRewardToken

Reward token address in XVSVault

address xvsVaultRewardToken

xvsVaultPoolId

Pool ID in XVSVault

uint256 xvsVaultPoolId

initialize

PrimeLeaderboard initializer. Initializes the default multiplier tiers: 30 days → 1.3x, 60 days → 1.6x, 90 days → 2.0x (cap).

function initialize(address accessControlManager_, uint256 loopsLimit_) external

Parameters

Name	Type	Description
accessControlManager_	address	Address of AccessControlManager
loopsLimit_	uint256	Maximum number of loops allowed in a single transaction

initializeStakers

Batch-seed existing stakers’ deposit data during migration. Idempotent: skips users with totalStaked[user] != 0 (already seeded). Caller must batch appropriately to avoid exceeding block gas limits.

function initializeStakers(address[] users, uint256[] amounts, uint64[] timestamps) external

Parameters

Name	Type	Description
users	address[]	Array of user addresses to initialize
amounts	uint256[]	Array of staked amounts (in XVS wei)
timestamps	uint64[]	Array of deposit timestamps

📅 Events

Emits StakerInitialized for each user successfully seeded

⛔️ Access Requirements

Controlled by ACM

❌ Errors

Throw StakersAlreadyInitialized if finalizeInitialization was already called
Throw LengthMismatch if array lengths don’t match
Throw InvalidTimestamp if a seeded timestamp is zero or in the future

finalizeInitialization

Finalize staker initialization, preventing further seeding. Must be called after all initializeStakers batches are complete.

function finalizeInitialization() external

📅 Events

Emits StakersInitializationFinalized

⛔️ Access Requirements

Controlled by ACM

❌ Errors

Throw StakersAlreadyInitialized if already finalized

xvsUpdated

Called by the XVSVault (via primeToken.xvsUpdated) when a user’s stake changes. Reads the user’s current vault balance, diffs it against totalStaked, and records the appropriate deposit or LIFO withdrawal internally. Then forwards accrueInterestAndUpdateScore(user) to PrimeV2 if set.

function xvsUpdated(address user) external

Parameters

Name	Type	Description
user	address	The user whose stake changed

📅 Events

Emits DepositRecorded event on deposit
Emits WithdrawalRecorded event on withdrawal
Emits DepositsCompacted event if deposits are compacted

⛔️ Access Requirements

Only callable by XVSVault

❌ Errors

Throw OnlyXVSVaultAllowed if caller is not XVSVault
Throw ZeroAddress if user address is zero

getEffectiveStake

Get a user’s current Prime Score (time-weighted score)

function getEffectiveStake(address user) public view returns (uint256 effectiveStake)

Parameters

Name	Type	Description
user	address	The user’s address

Return Values

Name	Type	Description
effectiveStake	uint256	The user’s Prime Score (time-weighted)

getEffectiveStakeBatch

Batch view to get Prime Scores for multiple users

function getEffectiveStakeBatch(address[] users) external view returns (uint256[] scores)

Parameters

Name	Type	Description
users	address[]	Array of user addresses

Return Values

Name	Type	Description
scores	uint256[]	Array of Prime Scores

getTotalStaked

Get a user’s total staked amount

function getTotalStaked(address user) external view returns (uint256)

Parameters

Name	Type	Description
user	address	The user’s address

Return Values

Name	Type	Description
[0]	uint256	The total XVS staked

getDeposits

Get a user’s deposit stack

function getDeposits(address user) external view returns (struct IPrimeLeaderboard.Deposit[] deposits)

Parameters

Name	Type	Description
user	address	The user’s address

Return Values

Name	Type	Description
deposits	struct IPrimeLeaderboard.Deposit[]	Array of deposits (index 0 = oldest)

getDepositCount

Get the number of deposit tranches for a user

function getDepositCount(address user) external view returns (uint256 count)

Parameters

Name	Type	Description
user	address	The user’s address

Return Values

Name	Type	Description
count	uint256	Number of deposit tranches

getMultiplier

Calculate the multiplier for a given holding duration

function getMultiplier(uint256 holdingDuration) external view returns (uint256 multiplier)

Parameters

Name	Type	Description
holdingDuration	uint256	Duration in seconds

Return Values

Name	Type	Description
multiplier	uint256	The multiplier (scaled by 1e18)

getMultiplierTiers

Get the multiplier tier configuration

function getMultiplierTiers() external view returns (uint256[] durations, uint256[] multipliers)

Return Values

Name	Type	Description
durations	uint256[]	Array of duration thresholds
multipliers	uint256[]	Array of multiplier values

setMultiplierTiers

Set the multiplier tiers. Durations and multipliers must be strictly ascending, and each multiplier must be ≥ the base multiplier (1e18).

function setMultiplierTiers(uint256[] durations, uint256[] multipliers) external

Parameters

Name	Type	Description
durations	uint256[]	Array of duration thresholds in seconds
multipliers	uint256[]	Array of multiplier values (scaled by 1e18)

📅 Events

Emits MultiplierTiersUpdated event

⛔️ Access Requirements

Controlled by ACM

❌ Errors

Throw LengthMismatch if durations and multipliers arrays have different lengths
Throw InvalidValue if durations array is empty
Throw InvalidMultiplierTiers if tiers are not in ascending order or multipliers below base

setPrimeV2

Set the PrimeV2 contract address

function setPrimeV2(address primeV2_) external

Parameters

Name	Type	Description
primeV2_	address	Address of PrimeV2 contract

📅 Events

Emits PrimeV2Set event

⛔️ Access Requirements

Controlled by ACM

❌ Errors

Throw ZeroAddress if address is zero

setMaxLoopsLimit

Set the limit for the loops that can iterate to avoid DOS

function setMaxLoopsLimit(uint256 loopsLimit) external

Parameters

Name	Type	Description
loopsLimit	uint256	Limit for the max loops that can execute at a time

📅 Events

Emits MaxLoopsLimitUpdated event

⛔️ Access Requirements

Controlled by ACM