# 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="https://1503334455-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpUhQzPJGdJzuLTQ5sCym%2Fuploads%2FlqBIwLrZFo6b79zMpBBF%2FSans%20titre.svg?alt=media&#x26;token=4d6eaf94-6a4f-4f6b-8d07-10557c50a6a0" 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.