IntervalVirtualLockMultiplierFacet

Enables the application of lock multipliers (used for scaling rewards when positions are locked) within staking campaigns according to an interval-based schema.

_Example of an interval-based schema configuration:

If timeLockPeriods = [100, 300] and timeLockMultipliers = [2, 4]:

• A position with lock duration less than 100 seconds will receive a lock multiplier of 1 (no multiplier).
• A position with lock duration between 100 and 299 seconds will receive a lock multiplier of 2.
• A position with lock duration 300 seconds or more will receive a lock multiplier of 4.

In addition to lock scaling, staking campaigns may also scale rewards based on the allocated staked amounts (i.e., amount multipliers). This implementation focuses solely on lock periods scaling, ensuring that locked positions receive rewards according to the interval-based lock multiplier schema defined by the associated campaign.

IMPORTANT:

• Multipliers should be scaled by 1e18, allowing for calculations with up to 18 decimal precision. -timeLockPeriods and timeLockMultipliers must be in strictly increasing order._

CampaignVirtualLockMultipliersConfigured

event CampaignVirtualLockMultipliersConfigured(uint256 campaignId, uint256[] timeLockPeriods, uint256[] timeLockMultipliers)

Emitted at setCampaignVirtualLockMultipliers().

VirtualLockMultiplierApplied

event VirtualLockMultiplierApplied(uint256 nftId, uint256 virtualLockMultiplier)

Emitted at applyVirtualLockMultiplier() and combineVirtualLockMultipliers().

setCampaignVirtualLockMultipliers

function setCampaignVirtualLockMultipliers(uint256 campaignId, bytes campaignVirtualLockMultipliersData) external

Setter function for configuring lock multipliers for the specified staking campaign.

_Setter functions are executed during the creation process of campaigns (see CampaignCreationSkeleton.sol). This function allows for the configuration of thresholds and their respective multipliers for lock periods.

The lengths of the timeLockPeriods and timeLockMultipliers arrays must be equal. Each threshold defined in timeLockPeriods should correspond to a multiplier in timeLockMultipliers.

Emits a {CampaignVirtualLockMultipliersConfigured} event.

IMPORTANT:

• Values in timeLockMultipliers should be scaled by 1e18 at the API level, allowing for 18 decimal precision. -timeLockPeriods and timeLockMultipliers must be in strictly increasing order._

Parameters

applyVirtualLockMultiplier

function applyVirtualLockMultiplier(uint256 campaignId, uint256 nftId) external returns (uint256)

Applies the respective lock multiplier to the specified position based on the campaign's configuration and the position's lock period.

Lock multipliers are scaled by 1e18, allowing for 18 decimal precision. Emits a {VirtualLockMultiplierApplied} event.

Parameters

Return Values

combineVirtualLockMultipliers

function combineVirtualLockMultipliers(uint256 nftId, uint256 currentLockMultiplier, uint256 newLockMultiplier, uint256 packetsStaked, uint256 packetsRestaked) external returns (uint256)

Applies to the specified position the calculated combined lock multiplier.

_The combined lock multiplier value is calculated as follows:

 combinedLockMultiplier = (((packetsStaked * currentLockMultiplier) + (packetsRestaked * newLockMultiplier)) /
                            (packetsStaked + packetsRestaked))

Emits a {VirtualLockMultiplierApplied} event.

IMPORTANT: This adjustment occurs when a position's lock period hasn't elapsed and the position is increased via a restake operation. The combined lock multiplier for calculating rewards is accounted for the period between the position's current unlock timestamp and the restake's unlocktimestamp._

Parameters

Return Values

getCurrentLockMultiplier

function getCurrentLockMultiplier(uint256 nftId) external view returns (uint256)

Retrieves the lock multiplier currently applied to the specified position.

Lock multipliers are scaled by 1e18, allowing for 18 decimal precision. Lock multipliers are only accounted for rewards during positions lock period.

Parameters

Return Values

getVirtualBalance

function getVirtualBalance(uint256 nftId) external view returns (uint256)

Calculates and retrieves the virtual balance of the specified position. The virtual balance is calculated as the position's actual raw balance (staked input packets) multiplied by the applicable amount and lock multiplier.

Parameters

Return Values

getVirtualBalanceForAmount

function getVirtualBalanceForAmount(uint256 nftId, uint256 amountOfPackets) external view returns (uint256)

Retrieves the virtual amount of packets based on the specified amount of packets and the position's applicable lock multiplier (virtualAmount = amountOfPackets * lockMultiplierApplied).

This function only accounts for any applicable lock multiplier.

Parameters

Return Values