# Points System

## Overview

The Curvance Points System is a core component of the protocol's voting escrow (veCVE) mechanism, providing the foundation for governance voting power and reward distribution. Rather than using raw locked token amounts, Curvance implements a "points" system to track user influence and manage the distribution of protocol rewards.

## Technical Implementation

### Points System Architecture

The points system consists of several interconnected mechanisms that track both individual and aggregate protocol state:

```solidity
chainPoints: uint256  // Total points on the chain
userPoints: mapping(address => uint256)  // Points per user
chainUnlocksByEpoch: mapping(uint256 => uint256)  // Points unlocking in each epoch
userUnlocksByEpoch: mapping(address => mapping(uint256 => uint256))  // User points unlocking by epoch
```

### **Regular vs. Continuous Locks**

Locks exist in two modes:

* **Regular Locks:** Fixed-duration locks (1 year/26 epochs) with 1:1 point ratio
* **Continuous Locks:** Auto-renewing locks with CONTINUOUS\_LOCK\_VALUE (max uint40) as unlockTime and a 2x point multiplier

### **Points Calculations**

The continuous lock multiplier is defined as:

**`CL_POINT_MULTIPLIER = 2 // 200% of base points`**

Points calculation for continuous locks:

**`_getCLPoints(basePoints) => CL_POINT_MULTIPLIER * basePoints`**

### Points State Machine

The points system's state evolves through these main operations:

* **Creating Locks:** Adds points to user and chain totals
* **Extending Locks:** Updates unlock schedule and potentially modifies points
* **Unlocking:** Removes points when locks expire
* **Early Unlocking:** Removes points with penalty
* **Changing Lock Mode:** Toggles between regular and continuous lock

Internal functions managing this state:

```solidity
_incrementPoints(address user, uint256 points)
_reducePoints(address user, uint256 points)
_incrementTokenUnlocks(address user, uint256 epoch, uint256 points)
_reduceTokenUnlocks(address user, uint256 epoch, uint256 points)
_updateUnlockDataToExtendedLock(address user, uint256 previousEpoch, uint256 epoch, uint256 previousPoints, uint256 points)
_updateDataToContinuousOn(address user, uint256 epoch, uint256 points, uint256 unlocks)
_updateDataFromEarlyUnlock(address user, uint256 points, uint256 unlockTime)
```

## User-Facing Functions

### **createLock()**

Creates a new voting escrow position by locking CVE tokens.

**Function signature:**

```solidity
function createLock(
    uint256 amount,
    bool continuousLock,
    RewardsData calldata rewardsData,
    bytes calldata params,
    uint256 aux
) external nonReentrant
```

<table><thead><tr><th width="157">Parameter</th><th width="135">Type</th><th>Description</th></tr></thead><tbody><tr><td>amount</td><td>uint256</td><td>Amount of CVE tokens to lock</td></tr><tr><td>continuousLock</td><td>bool</td><td>Whether to enable continuous lock mode</td></tr><tr><td>rewardsData</td><td>RewardsData</td><td>Data structure for reward claiming</td></tr><tr><td>params</td><td>bytes</td><td>Additional parameters for rewards processing</td></tr><tr><td>aux</td><td>uint256</td><td>Auxiliary data</td></tr></tbody></table>

### **extendLock()**

Extends an existing lock with additional tokens.

**Function signature:**

```solidity
function extendLock(
    uint256 lockIndex,
    uint256 amount,
    RewardsData calldata rewardsData,
    bytes calldata params,
    uint256 aux
) external nonReentrant
```

<table><thead><tr><th width="139">Parameter</th><th width="154">Type</th><th>Description</th></tr></thead><tbody><tr><td>lockIndex</td><td>uint256</td><td>Index of the lock to extend</td></tr><tr><td>amount</td><td>uint256</td><td>Additional amount to lock</td></tr><tr><td>rewardsData</td><td>RewardsData</td><td>Data structure for reward claiming</td></tr><tr><td>params</td><td>bytes</td><td>Additional parameters for rewards processing</td></tr><tr><td>aux</td><td>uint256</td><td>Auxiliary data</td></tr></tbody></table>

### **updateLockMode()**

Toggles a lock between regular and continuous lock modes.

**Function signature:**

```solidity
function updateLockMode(
    uint256 lockIndex,
    bool continuousLock,
    RewardsData calldata rewardsData,
    bytes calldata params,
    uint256 aux
) external nonReentrant
```

<table><thead><tr><th width="159">Parameter</th><th width="137">Type</th><th>Description</th></tr></thead><tbody><tr><td>lockIndex</td><td>uint256</td><td>Index of the lock to update</td></tr><tr><td>continuousLock</td><td>bool</td><td>Whether to enable or disable continuous lock mode</td></tr><tr><td>rewardsData</td><td>RewardsData</td><td>Data structure for reward claiming</td></tr><tr><td>params</td><td>bytes</td><td>Additional parameters for rewards processing</td></tr><tr><td>aux</td><td>uint256</td><td>Auxiliary data</td></tr></tbody></table>

### **combineLocks()**

Combines multiple locks into a single new lock.

**Function signature:**

```solidity
function combineLocks(
    bool continuousLock,
    RewardsData calldata rewardsData,
    bytes calldata params,
    uint256 aux
) external nonReentrant
```

<table><thead><tr><th width="144">Parameter</th><th width="141">Type</th><th>Description</th></tr></thead><tbody><tr><td>continuousLock</td><td>bool</td><td>Whether the combined lock should be continuous</td></tr><tr><td>rewardsData</td><td>RewardsData</td><td>Data structure for reward claiming</td></tr><tr><td>params</td><td>bytes</td><td>Additional parameters for rewards processing</td></tr><tr><td>aux</td><td>uint256</td><td>Auxiliary data</td></tr></tbody></table>

### **unlock()**

Unlocks tokens from an expired lock.

**Function signature:**

```solidity
function unlock(
    uint256 lockIndex,
    RewardsData calldata rewardsData,
    bytes calldata params,
    uint256 aux
) external nonReentrant
```

<table><thead><tr><th width="123">Parameter</th><th width="139">Type</th><th>Description</th></tr></thead><tbody><tr><td>lockIndex</td><td>uint256</td><td>Index of the lock to unlock</td></tr><tr><td>rewardsData</td><td>RewardsData</td><td>Data structure for reward claiming</td></tr><tr><td>params</td><td>bytes</td><td>Additional parameters for rewards processing</td></tr><tr><td>aux</td><td>uint256</td><td>Auxiliary data</td></tr></tbody></table>

### **earlyUnlock()**

Unlocks tokens before the lock expires, with a penalty.

**Function signature:**

```solidity
function earlyUnlock(
    uint256 lockIndex,
    RewardsData calldata rewardsData,
    bytes calldata params,
    uint256 aux
) external nonReentrant
```

<table><thead><tr><th width="134">Parameter</th><th width="137">Type</th><th width="284">Description</th></tr></thead><tbody><tr><td>lockIndex</td><td>uint256</td><td>Index of the lock to unlock early</td></tr><tr><td>rewardsData</td><td>RewardsData</td><td>Data structure for reward claiming</td></tr><tr><td>params</td><td>bytes</td><td>Additional parameters for rewards processing</td></tr><tr><td>aux</td><td>uint256</td><td>Auxiliary data</td></tr></tbody></table>

## Querying Information

### **queryUserLocks()**

Returns all locks for a specific user.

**Function signature:**

```solidity
function queryUserLocks(address user) external view returns (uint256[] memory, uint256[] memory)
```

<table><thead><tr><th width="105">Parameter</th><th width="102">Type</th><th width="232">Description</th></tr></thead><tbody><tr><td>user</td><td>address</td><td>Address of the user to query</td></tr></tbody></table>

**Return Values:**

<table><thead><tr><th width="160">Type</th><th width="349">Description</th></tr></thead><tbody><tr><td>uint256[] memory</td><td>Lock amounts</td></tr><tr><td>uint256[] memory</td><td>expiry dates or <code>CONTINUOUS_LOCK_VALUE</code></td></tr></tbody></table>

### **getVotes()**

Returns the voting power (points) of a user.

**Function signature:**

```solidity
function getVotes(address user) external view returns (uint256)
```

<table><thead><tr><th width="116">Parameter</th><th width="124">Type</th><th width="264">Description</th></tr></thead><tbody><tr><td>user</td><td>address</td><td>Address of the user to query</td></tr></tbody></table>

**Return values:**

<table><thead><tr><th width="137">Type</th><th width="307">Description</th></tr></thead><tbody><tr><td>uint256</td><td>Total voting power (points) of the user</td></tr></tbody></table>

## Points Lifecycle

1. Lock Creation:

* Regular lock: +1 point per token, scheduled to unlock in 1 year
* Continuous lock: +2 points per token, no scheduled unlock

2. Lock Extension:

* Updates unlock schedule
* For continuous locks, increases points by 2x the additional amount
* For regular locks, increases points by 1x the additional amount

3. Lock Mode Update:

* Regular → Continuous: Increases points by 1x the locked amount, removes scheduled unlock
* Continuous → Regular: Decreases points by 1x the locked amount, adds scheduled unlock

4. Unlock:

* Removes points based on lock mode (1x for regular, 2x for continuous)
* For regular locks, also updates the epoch unlock schedule

5. Early Unlock:

* Same point reduction as normal unlock
* Applies penalty to returned tokens

## Implementation Notes

* The points system is synchronized with epochs to ensure rewards are correctly distributed
* State-changing operations are restricted around epoch transitions (RESTRICTION\_DURATION = 12 hours)
* Multichain support allows locks to be transferred between chains
* Continuous lock mode provides higher rewards but the same amount of locked tokens


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.curvance.com/app/developer-docs/core-token-ecosystem/voting-escrow-cve-vecve/points-system.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.