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.
BNB PrimeV2 only. At block 118,364,540, proxy 0x55e2ccF68B7A276dc28AfA107997b8B1Be932c0b used implementation 0xd80de9ecb6596df95dd67af73b67122054c2d1a1. Resolve the live proxy and Access Control Manager before using an administrative function.
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 xvsVaultxvsVaultRewardToken
Reward token address in XVSVault
address xvsVaultRewardTokenxvsVaultPoolId
Pool ID in XVSVault
initialize
PrimeLeaderboard initializer. Initializes the default multiplier tiers: 30 days → 1.3x, 60 days → 1.6x, 90 days → 2.0x (cap).
Parameters
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.
Parameters
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.
📅 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.
Parameters
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)
Parameters
user
address
The user's address
Return Values
effectiveStake
uint256
The user's Prime Score (time-weighted)
getEffectiveStakeBatch
Batch view to get Prime Scores for multiple users
Parameters
users
address[]
Array of user addresses
Return Values
scores
uint256[]
Array of Prime Scores
getTotalStaked
Get a user's total staked amount
Parameters
user
address
The user's address
Return Values
[0]
uint256
The total XVS staked
getDeposits
Get a user's deposit stack
Parameters
user
address
The user's address
Return Values
deposits
struct IPrimeLeaderboard.Deposit[]
Array of deposits (index 0 = oldest)
getDepositCount
Get the number of deposit tranches for a user
Parameters
user
address
The user's address
Return Values
count
uint256
Number of deposit tranches
getMultiplier
Calculate the multiplier for a given holding duration
Parameters
holdingDuration
uint256
Duration in seconds
Return Values
multiplier
uint256
The multiplier (scaled by 1e18)
getMultiplierTiers
Get the multiplier tier configuration
Return Values
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).
Parameters
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
Parameters
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
Parameters
loopsLimit
uint256
Limit for the max loops that can execute at a time
📅 Events
Emits MaxLoopsLimitUpdated event
⛔️ Access Requirements
Controlled by ACM
Last updated