> For the complete documentation index, see [llms.txt](https://tech.usual.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tech.usual.money/smart-contracts/protocol-contracts/usual/usual-vested-allocation-staking.md).

# USUAL\* Vested Allocation Staking

### High-Level Overview

The **UsualSP** contract is a smart contract designed for managing the vesting and staking of **USUALS** token allocations. It allows insiders to vest and claim their **USUALS** allocations over a pre-defined vesting period and provides users (both insiders and outsiders) the ability to stake **USUALS** tokens to receive yield in the form of liquid allocations and rewards in **USUAL** tokens. Insiders can claim their vested **USUALS** allocations after a user-specific cliff period (multiple of the **ONE\_MONTH** constant), and these tokens are distributed in monthly increments.

### Contract Summary

#### Inherited Contracts

* **RewardAccrualBase**: Base contract that handles the reward accrual mechanism for staked tokens.
* **PausableUpgradeable**: Allows contract functionality to be paused by authorized accounts (OZ implementation).
* **ReentrancyGuardUpgradeable**: Prevents reentrant attacks on sensitive functions (OZ implementation).
* **IUsualSP**: Interface defining the required methods for the **UsualSP** contract.

### Functionality Breakdown

#### SC-Flows

<figure><img src="/files/SZS9YZExgTycmIF70hKV" alt=""><figcaption></figcaption></figure>

#### Key Functionalities

* **Vesting**: Insiders receive an initial **USUALS allocation** that is vested over a defined period. This allocation is released gradually, with insiders able to claim it from their start time and after their cliff period has passed.
* **Claiming USUALS Allocations**: Insiders can claim their vested **USUALS** after the cliff period is over. The claimable amount is calculated based on the duration passed since the vesting started.
* **Staking**: Users (including insiders) can stake their **USUALS** tokens to receive liquid allocations and rewards in **USUAL** tokens. These rewards accrue over time and can be claimed.
* **Reward Accrual**: Users who stake **USUALS** tokens are eligible for rewards in **USUAL** tokens based on the staking duration and amount.
* **Pause and Unpause**: Admins with specific role have the ability to pause and unpause the contract to safeguard against attacks or during upgrades.

### Functions Description

#### Public/External Functions

* **initialize**: Initializes the contract by setting the registry contract, vesting start date, and duration.
* **claimOriginalAllocation**: Allows insiders to claim their vested **USUALS** allocations.
* **stake**: Users can stake their **USUALS** tokens to receive liquid allocations.
* **unstake**: Users can withdraw a portion of their staked **USUALS** tokens.
* **claimReward**: Users can claim their accrued rewards in **USUAL** tokens based on their allocation.
* **pause**: Pauses all token transfer operations; callable only by the PAUSING\_CONTRACTS\_ROLE.
* **unpause**: Resumes all token transfer operations; also callable only by the DEFAULT\_ADMIN\_ROLE.
* **allocate**: Function to allocate original **USUALS** allocations and set the vesting start times and cliff durations for insiders. Only callable by the USUALSP\_OPERATOR\_ROLE.
* **stakeUsualS**: Sends the total supply of **USUALS** to the staking contract. Only callable by the USUALS contract.
* **removeOriginalAllocation**: Function to remove the original allocation and claimed amounts for a list of recipients. Only callable by the USUALSP\_OPERATOR\_ROLE.
* **startRewardDistribution**: Initiates the reward distribution process. Only callable by the Distribution Module contract.

### Constants

* **CONTRACT\_REGISTRY\_ACCESS**: Registry access contract address.
* **DEFAULT\_ADMIN\_ROLE**: Default admin role. Can unpause the contract.
* **PAUSING\_CONTRACTS\_ROLE**: Role required to pause the contract.
* **USUALSP\_OPERATOR\_ROLE**: Role required for allocation management and staking operations.
* **CONTRACT\_USUALS**: The address of the **USUALS** token contract.
* **CONTRACT\_USUAL**: The address of the **USUAL** token contract.
* **CONTRACT\_DISTRIBUTION\_MODULE**: The address of the Distribution Module contract.
* **ONE\_MONTH**: Represents the duration of one month in seconds, used to calculate the vesting schedule.
* **NUMBER\_OF\_MONTHS\_IN\_THREE\_YEARS**: Used to calculate the total vesting duration over three years.
* **STARTDATE\_USUAL\_CLAIMING\_USUALSP:**  The start date of the Usual claiming.

### Safeguards Implementation

* **Pausability**: Ensures that token transfers can be halted in case of emergency.
* **Role-Based Access Control**: Restricts sensitive actions to addresses with appropriate roles.
* **ReentrancyGuard**: All external-facing functions that handle transfers or state changes are protected from reentrancy attacks.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://tech.usual.money/smart-contracts/protocol-contracts/usual/usual-vested-allocation-staking.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.