Combining Locks

Overview

The Curvance veCVE system allows users to combine multiple veCVE locks into a single lock through the combineAllLocks function. This feature provides several benefits:

• Gas Efficiency: Managing a single lock is more gas-efficient than managing multiple locks

• Simplified Position Management: Consolidates voting power and rewards tracking

• Optimization Opportunity: Users can convert non-continuous locks to a continuous lock, potentially increasing their voting power and rewards

State Machine and Dataflows

State Transitions

When combining locks, the following state transitions occur:

1. Initial State: User has multiple lock positions (userLocks[user][])

2. Intermediate Processing:

   1. System claims any pending rewards

   2. For non-continuous locks, token unlock data is removed

   3. Total locked amount is calculated

3. Terminal State:

   1. All previous locks are deleted

   2. A single new lock is created with:

      1. Combined amount from all previous locks

      2. Either continuous or non-continuous status as specified

Data Flow for Continuous Terminal Lock

Data Flow for Non-Continuous Terminal Lock

Storage Changes

When combining locks, the following storage changes occur:

Storage	Before	After (Continuous)	After (Non-Continuous)
userLocks[user]	Multiple entries	Single continuous entry	Single non-continuous entry
userPoints[user]	Sum of individual lock points	Possibly increased (2x multiplier)	Possibly decreased if had continuous locks
chainPoints	Sum of all points	Updated based on terminal type	Updated based on terminal type
userUnlocksByEpoch	Entries for each non-continuous lock	No entries (continuous)	Single entry for new lock epoch
chainUnlocksByEpoch	Entries for each non-continuous lock	No entries (continuous)	Single entry for new lock epoch

User Functions

combineAllLocks()

Combines all of a user's locks into a single lock with the specified type.

Function signature:

function combineAllLocks(
    bool continuousLock,
    RewardsData calldata rewardsData,
    bytes calldata params,
    uint256 aux
) external nonReentrant

Parameter	Type	Description
continuousLock	bool	Whether the combined lock should be continuous (never expires) or not
rewardsData	RewardsData	Rewards data for desired Reward Manager action during the process
params	bytes	Parameters for rewards claim function, format depends on Reward Manager implementation
aux	uint256	Auxiliary data that may be used by reward functions

Common Scenarios

Combining All Continuous Locks into a Continuous Lock

When combining all continuous locks into a single continuous lock:

• User points remain the same before and after

• veCVE balance stays the same

• No unlock data is created or modified

Combining Non-Continuous Locks into a Continuous Lock

When combining non-continuous locks into a continuous lock:

• User points increase (due to 2x multiplier for continuous locks)

• Previous unlock data is removed

• No new unlock data is created

Combining Locks into a Non-Continuous Lock

When combining locks into a non-continuous lock:

• If some locks were continuous, user points may decrease

• Previous unlock data is removed

• New unlock data is created for the combined lock amount at the fresh lock epoch

Requirements and Restrictions

For combining locks to succeed, the following conditions must be met:

• User must have at least 2 existing locks

• The veCVE contract must not be shut down

• The operation must not occur during epoch transition blackout periods

• All reward epochs must be properly delivered

Best Practices

• Combine locks when gas prices are low to minimize transaction costs

• Consider converting to a continuous lock for maximum voting power and rewards

• Be aware that converting continuous locks to non-continuous will reduce your points